Skip to main content

Introduction​

Key management refers to creating and managing the Keys that are used across RainMaker services. These APIs provide way to create the key, update the key attributes like description or tags, get all the keys created by a user etc.

As of now, Key Management API allows to create the keys that are needed to Secure Signing.

Create Key ​

TODO: Add swagger link

Create Key API provides support to create Keys needed for Signing service.

The Keys are created in AWS KMS. Refer AWS KMS Pricing to know more about the associated cost.

Keys used in RainMaker Secure Signing are for Asymetric Key Cryptography which has two keys, Private key which should be stored securely and the other one is freely available Public key.

When a key is created through Create Key API, the private key and public key both are stored securely in AWS KMS.

Th public key is cached in RainMaker database as there is no harm or security constraints in storing it in plaintext.

The AWS Keys has Key specification and usage options. The Key specification say whether a key is RSA or ECC. If it is a RSA key then whether it is of 2048/3072/4096 key length and similarly for ECC there are P256/P384 curve options.

As of now this API supports Keys needed for Signing with following constraints.

  • The RSA key can be created with 3072 key length only.
  • The ECC key can be created with NIST P256 only.

The keys created with this APIs can only be used for Sign and Verify.


note

The support for creating keys that supports encryption/decryption, and support other key length and curves is in future scope.

Get Key Details​

TODO: Add swagger

Using Get Key API one can fetch the key details like key description, tags, Key specification, SHA 256 of Public key.

Update Key Details​

TODO: Add swagger

Using Update Key Details API one can update the following attributes

  • description
  • add or remove tags

The Key specification cannot be changed once created.

Revoke Key​

TODO: Add swagger

There can be scenarios like keys are compromised where in you need to revoke the key.

Revoke Key API provides support for revocation. The key is marked as revoked in RainMaker database and it will be Disabled in AWS KMS. Upon revocation, These keys won't be deleted from AWS KMS and they will still incure the cost.

Revocation API provides option to undo the Revocation.

This is helpful,

  • If you suspect the keys are compromised and you want to prevent the usage of keys.
  • If you have created the keys but for now you want to prevent the usage
  • You can create the keys in revoked state so that the usage will not be allowed untill you undo the revocation.
caution

The revoked Key cannot be used for Signing firmwares images or it cannot be used in creating OTA job which specifies the revoked key.

Delete Key​

danger

This operation cannot be undone. This is potentially dangerous operation and should be used with caution.

Delete Key API provites ability to delete the keys that are no longer needed, say you have created a key accidently.

To delete a key, first it has to be revoked so that the usage of that can be prevented.

If there are devices which has a signed firmware and you delete the key which has signed that firmware, then you cannot do the subsequent OTAs such devices. The devices will simply reject the firmware signed by a different key.

So, one need to be very cautious about using this API, the usgae of the key to be checked.