Signing keys

IoT App Store Guide
1

The Serial Vault provides encrypted storage for signing keys for an account. Signing keys can be generated locally and uploaded, or generated within the Serial Vault. The signing key also needs to be registered with the Brand store so it can be used to verify the signature of serial assertions. The Serial Vault holds the private key, whereas the Brand Store holds only the public key as an account-key assertion.

Info:

The private key of any key pair generated within the Serial Vault cannot be downloaded for local use. If you wish to sign both model and serial assertions with the same key, ensure the key is generated locally and then uploaded to the Serial Vault.

The steps needed with local key generation and registration are:

  1. Generating the key(s)
  2. Registering the key with the Brand Store
  3. Exporting the key as ASCII-armored
  4. Uploading the ASCII-armored key file to the Serial Vault

The Serial Vault will need the private keys uploaded to its database for the following keys:

  • Key for signing serial assertions
  • Key for signing system-user assertions
  • (if model pivoting is needed) Key for signing model assertions

Although one key can be used for each of these three purposes, it is recommended to use a separate signing key for each type of assertion.

Signing keys that are to be uploaded to the Serial Vault need to be passwordless (i.e. keeping a blank password when generating the key). Using a key that has a password results in an error when uploading the signing key.

Register a signing key with limited roles

Role-scoped keys are signing keys that are limited to be able to sign only specific assertion types. These limitations can be set when first registering the key with the Brand Store. For example, a key can be registered for only signing serial assertions, and can be further constrained to the serial assertions for only certain models. This improves security as it limits the potential impact of a leaked key.

Customers currently cannot register a role-scoped signing key themselves. They must raise a support request as documented below.

A key can be scoped to a single or a combination of the following assertion types:

  • Serial
  • Model
  • System-user
  • Preseed

For the serial, model, and preseed assertion types, keys can be further be constrained on model names matching a certain regular expression, e.g. foo-.*

Info:

If role-scoped keys are in use, it is recommended to limit the roles of all available keys for increased security.

Procedure for requesting a role-scoped key

To register a role-scoped key, raise a support request with the Brand Store with the following details:

  • Account ID of the brand account to which the key would be registered
  • Name for the key
  • Verbatim base64-encoded output of snap export-key, ran against the locally created signing key they wish to register
  • Model name constraints for the serial, model, and preseed assertion types, if any

Currently, roles can only be defined for new keys. Once registered, the role(s) of a role-scoped signing key cannot be changed.

2

However, signing keys cannot be downloaded from the Serial Vault so the unencrypted signing is never available, so the recommended approach is to generate the key locally.

This statement doesn’t really make sense. If a signing key is generated within the SV, its true the private component of this key can’t be downloaded. The public portion of the key is registered by the SV to the brand account, and thus is accessible via assertion.

Also I’m not sure why the inability to access the signing key when generated by the SV is reason to suggest that customers generate serial vault keys locally? The whole idea behind auto-generation of the serial signing key, is that there’s one less key for the brand to managed.

3

The Serial Vault will need the private keys uploaded to its database for the following keys:

Key for signing serial assertions
Key for signing system-user assertions
(if model pivoting is needed) Key for signing model assertions

Again, see my previous comment about use of SV generated keys for serial assertions.

The ability to sign system-user assertions is also quite limited, so not sure it should be included here?

Also, afaik there is no support in the SV for signing model assertions, so that should be removed.

4

Notably, the export-key subcommand is not documented in neither snap help nor snap help --all…

5

Note, we should add a notes regarding the fact that keys registered with key roles via support ticket replaces the previous process of registering a via with snapcraft. It might also be worth noting that if key roles are used, then all brand keys should be assigned them (i.e. it doesn’t make sense to use roles if a super key w/out role still exists and/or is used).

We also still really need to fix the verbiage that suggests that serial assertion keys should be generated locally and imported to the SV. Please see my previous comment about this.

1 Like