KeyRings

Organize, Manage, and Grant Access to Your Encrypted Data

KeyRings are one of the major components in managing your encrypted data. They house the cryptographic keys used for encrypting and decrypting data. Each KeyRing is comprised of:

  • A unique name
  • An Active Key
  • An Active Algorithm
  • A Key Store of all previous Encryption Keys used
  • A Public Key

The unique name allows you to reference the KeyRing throughout the APIs. While the name is stored in lower case, the original casing is preserved, and is available through the displayName property.

At any given time, a KeyRing has a single Active Key. This is the Encryption Key that will be returned when making a call to /encrypt. The KeyRing tracks the usage of this Encryption Key, and will automatically rotate it when necessary. Once the Active Key is rotated, a new Encryption Key is generated, and it becomes the Active Key. The previous Key is then stored for you to retrieve later.

KeyRings are designed to support multiple encryption algorithms, however we currently only support AES-256. The Active Algorithm denotes the type of Encryption Key that is currently Active.

Every Encryption Key generated by a KeyRing is encrypted with a Public Key that was provided at KeyRing creation time. The Encryption Keys are never stored in their original form, and are only stored encrypted with the Public Key. When requesting a Key from a KeyRing, you'll use the Private Key to decrypt the Key Data into the cryptographic data you'll need to perform an encryption or decryption.

Creating a KeyRing

Creating a KeyRing is done using a POST request to https://api.grapheene.com/keyrings. The KeyRing body consists of:

PropertyRequiredDefaultDescription
ringnametrueThe KeyRing name. Casing is preserved for the displayNamebut not used when referencing a KeyRing.
algofalseaes256The Active Algorithm. Currently supported: aes256
publicKeyfalseGeneratedThe Public Key used to encrypt Encryption Keys managed by the KeyRing
propsfalseEmpty ObjectCustom properties or metadata for you to leverage in your workflows
keyPropsfalseEmpty ObjectCustom properties that are added to every Key created in the KeyRing.

The only required field is ringname. Although the platform will generate a Private/Public Key Pair for you, we recommend you generate and manage these yourself.

After the KeyRing has been created, you are now ready to create an API Key that has access to this KeyRing, and begin using it in your workflows.

Properties

Let's take a look at the properties of a KeyRing:

{
  "ring": {
  "id": "ring-000053",
  "name": "comms",
  "displayName": "Comms",
  "publicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUFpejFVWFlBY3NzckZ2aUFBWlVPTApPRE5ONU5jWFE5eXp2RkpISnZNS2c4SFlkV2t1UW1DTmxzNCtOamFtSE1JeUp6QUlMRzBuckQ0VDFzNExPd2o4CmRITDBVVWExRGxGd0hRaTNHb0NaRTNYUXFqY1NBZjJxeHBsWU5uNVZ6UkpmZXFsMnVlNVR0MjhWYnhldHhiU24KSEFwK2l6VEVYYUhTWEVXbmpYQ2JtUERCclJnM2xUQ3NRMWJkRE9GaTdxdzlQYzJuTTM5ZWlHbjdlbDhjTnhzdgppOExHRS80SEFqSU9CTVc5NU5WSStmeitWZ21pU1pTcEY5aUdudXZhSHpIT2phdHJoaGdkSTRXWkdJeDk4RkJpCnYrWUFnRjF0WGVHUW9QS1cxdnJUb0hZWndkTm5sR3VHaHdSbHpMYkxpL2NvR1ZZc0NXM0lHVUVJRGJlbGx2OVUKQ3J4eEFLUmYxNnR1bkwwUjlqZmViN2t4MjF2TjVBNW53VDJOdlhoWU9BSDZhS2N5UmxDN2V2NnBSU3VqY0RkNQpRS1RlWUhENDVCbkVnKzF6eFRkZTMycit5b3dvbWVNNW1FYzV6NnEwL2RjNXZIY3BoNU1mZlJoUzd3OFIvcnBzCmpaMVVLNGpaM2VGbnc2b0NuUTNpNFNHOCtFVVdzWXc5Z29vUlZhVUY2RUdwT25CdFFEcWdtb0lDK3N0U0JLc2oKdDRCUEplWVVZRlI1SlVCL2hkUm1US3Z1SitmWnBUL0ZuSzlqM2lWQ0dLVVNFR1kyWnhXVitnZlA0empMeWxJMQo3NkdKRFdjajROZVhPMUg0VnJSU21CSEovdWpJdzg1cjUyaWNPc3NDaytobEdyUHZucTN4bWtNMDQ1S0FRSmZBClFWZm5BVmhWbVYzNWtCU3k5eVpPRlRFQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ==",
  "activeKey": "key-000053-00000000",
  "activeAlgorithm": "aes256",
  "createdAt": "2023-11-21T23:22:54.729Z",
  "updatedAt": "2023-11-21T23:22:54.729Z"
  }
}

ring

PropertyDescription
idThe KeyRing ID
nameThe KeyRing name
displayNameThe KeyRing name with preserved casing
publicKeyThe Public Key. Base64 encoded
activeKeyThe Active Key ID
activeAlgorithmThe current Active Algorithm
createdAtKeyRing creation time. ISO-8601 format
updatedAtKeyRing last update timestamp. ISO-8601 format