Key Management¶
Orb uses two crypto keys to do the following operations:
Sign HTTP requests between orb servers.
Sign VC.
Establish orb key¶
There are 2 ways to establish the orb key:
Import a pre-existing private key and ID into KMS at Orb startup via Orb configuration
Prior to orb startup, create a new key within KMS and establish orb configuration
Add pre-existing private key to orb configuration¶
When the Orb server starts, it will import the private key and ID into KMS sever.
Steps to create VC sign key¶
Create ed25519 private key.
Configure ORB_VC_SIGN_PRIVATE_KEYS with value of ed25519 private key as base64.
Example VC sign key¶
ORB_KMS_ENDPOINT=https://orb.kms
ORB_VC_SIGN_PRIVATE_KEYS=orbkey1=9kRTh70Ut0MKPeHY3Gdv/pi8SACx6dFjaEiIHf7JDugPpXBnCHVvRbgdzYbWfCGsXdvh/Zct+AldKG4bExjHXg
ORB_VC_SIGN_ACTIVE_KEY_ID=orbkey1
Steps to create HTTP sign key¶
Create ed25519 private key.
Configure ORB_PRIVATE_KEY with value of ed25519 private key as base64.
Example HTTP sign key¶
ORB_KMS_ENDPOINT=https://orb.kms
ORB_HTTP_SIGN_PRIVATE_KEY=orbkey1=9kRTh70Ut0MKPeHY3Gdv/pi8SACx6dFjaEiIHf7JDugPpXBnCHVvRbgdzYbWfCGsXdvh/Zct+AldKG4bExjHXg
ORB_HTTP_SIGN_ACTIVE_KEY_ID=orbkey1
Create private key in KMS and configure orb to use¶
Key need to be created in KMS before orb server starting.
Steps to create VC sign key¶
Example VC sign key¶
ORB_KMS_STORE_ENDPOINT=https://orb.kms/keystore
ORB_VC_SIGN_KEYS_ID=orbkey1
ORB_VC_SIGN_ACTIVE_KEY_ID=orbkey1
Steps to create HTTP sign key¶
Example HTTP sign key¶
ORB_KMS_STORE_ENDPOINT=https://orb.kms/keystore
ORB_HTTP_SIGN_ACTIVE_KEY_ID=orbkey1
Storing¶
The keys will be managed and stored in KMS please refer to this doc for more details. Orb is using Scenario 1 in kms doc.
Rotation¶
There is two ways to rotate orb key:
Import a pre-existing private key and id into KMS at Orb startup via Orb configuration
Prior to orb startup, create a new key within KMS and establish orb configuration
Add pre-existing private key to orb configuration¶
When you need to rotate the key just add the new private key to orb configuration.
Steps to rotate VC sign key¶
Create new ed25519 private key.
Configure ORB_VC_SIGN_PRIVATE_KEYS with new value of ed25519 private key as base64.
Change the active key id to new key id.
Example VC sign key¶
ORB_KMS_ENDPOINT=https://orb.kms
ORB_VC_SIGN_PRIVATE_KEYS=orbkey1=9kRTh70Ut0MKPeHY3Gdv/pi8SACx6dFjaEiIHf7JDugPpXBnCHVvRbgdzYbWfCGsXdvh/Zct+AldKG4bExjHXg,orbkey2=bwpFhQXFhhPQCkAt3fmj9t05hnuwVqiUkBjaXV9QBeisrjoFhUEcIzVOH6QoIXNptWZtOZNdEvlLAf6bZa8opg
ORB_VC_SIGN_ACTIVE_KEY_ID=orbkey2
Steps to rotate HTTP sign key¶
Create new ed25519 private key.
Replace old key in ORB_HTTP_SIGN_PRIVATE_KEY with new value of ed25519 private key as base64.
Change the active key id to new key id.
Example HTTP sign key¶
ORB_KMS_ENDPOINT=https://orb.kms
ORB_HTTP_SIGN_PRIVATE_KEYS=orbkey2=bwpFhQXFhhPQCkAt3fmj9t05hnuwVqiUkBjaXV9QBeisrjoFhUEcIzVOH6QoIXNptWZtOZNdEvlLAf6bZa8opg
ORB_HTTP_SIGN_ACTIVE_KEY_ID=orbkey2
Create private key in KMS and configure orb to use¶
When you need to rotate the key just create new key in KMS and add key id to orb configuration.
Steps to rotate VC sign key¶
Create new ed25519 key in KMS using KMS cli.
Configure ORB_VC_SIGN_KEYS_ID with key id.
Change the active key id to new key id.
Example VC sign key¶
ORB_KMS_STORE_ENDPOINT=https://orb.kms/keystore
ORB_VC_SIGN_KEYS_ID=orbkey1,orbkey2
ORB_VC_SIGN_ACTIVE_KEY_ID=orbkey2
Steps to rotate HTTP sign key¶
Create new ed25519 key in KMS using KMS cli.
Change the active key id to new key id.
Example HTTP sign key¶
ORB_KMS_STORE_ENDPOINT=https://orb.kms/keystore
ORB_HTTP_SIGN_ACTIVE_KEY_ID=orbkey2
Distribute¶
The key will be managed and stored in KMS please refer to this doc for more details. Orb is using Scenario 1 in kms doc.
Impact of loss¶
Http signatures it’s short-lived no impact of loss.
Can’t verify VC signed before loss.
Impact of compromise¶
TBD