Powered by Redocly

Transit Keys

Transit keys are used to encode and decode data with a named key. This allows an application to work with encoded data without having to know the encryption key. Keys can be keep more secure and can more easily be managed, ie access controlled, rotated, and revoked. Multiple version of a key can be active at the same time to allow controlled rotation throughout a large distributed system.

Depending on the type of key it can be used for a number of different operations liken encrypt, decrypt, sign, verify, hmac etc.

Create a new transit key

SecurityaccessToken
Request
query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
public-key
string

A initial key can optionally be provided.

allow-plaintext-backup
boolean
Default: false

Allow the transit key to be backed up in plaintext. This allows a key to be backed up, but also restored on another tenant or site.

cipher
string <cipher-type>
Default: "aes256-gcm96"
  • aes128-gcm96: AES 128 GCM, 128 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • aes192-gcm96: AES 192 GCM, 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • aes256-gcm96: AES 256 GCM, 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • chacha20-poly1305: ChaCha20 with Poly1305 (RFC 7539). 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, convergent-encryption.
  • ecdsa-p256: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-256. Supports signing and signature verification.
  • ecdsa-p384: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-384. Supports signing and signature verification.
  • ecdsa-p521: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-521. Supports signing and signature verification.
  • ed25519: Edwards-curve Digital Signature Algorithm. Supports signing and signature verification.
  • rsa-2048: Supports encryption, decryption, signing, signature verification
  • rsa-3072: Supports encryption, decryption, signing, signature verification
  • rsa-4096: Supports encryption, decryption, signing, signature verification
convergent-encryption
boolean
Default: false

If enabled together with derived then the nonce will be calculated instead of randomly generated. The consequence is that the same plaintext will be encrypted to the same ciphertext.

deletion-allowed
boolean
Default: false

Controls if the key can be deleted or not. This is set to false by default since it is a potentially catastrophic operation since no data encrypted with they key will be decryptable once the key has been removed.

derived
boolean
Default: false

The key is derived from the common key and the provided context parameter. Encryption and decryption calls must provide the same context parameter. This allows for a large number of dynamically generated keys.

exportable
boolean
Default: false

If set to true then valid keys can be exported. Cannot be set to false once enabled.

default-encryption-version
integer <uint32>
Default: 0

It is possible to specify a default version for encryption. Once a key has been rotated it might be desirable to delay using the new version until it has been distributed to all parties that need it. Setting the value to 0 indicates that the latest version should be used by default.

min-decryption-version
integer <uint32>
Default: 0

It is possible to specify a minimal version for both encryption and decryption. It might be desirable to phase out an old key by increasing the minimal encryption version, while keeping the minimal decryption version until all data has been migrated to the new version, or become irrelevant.

min-encryption-version
integer <uint32>
Default: 0

It is possible to specify a minimal version for both encryption and decryption. It might be desirable to phase out an old key by increasing the minimal encryption version, while keeping the minimal decryption version until all data has been migrated to the new version, or become irrelevant.

object

It is advisable to periodically rotate encryption keys, regardless of whether a security breach has occurred. According to NIST publication 800-38D, AES-GCM keys should be rotated once they approach approximately 2^32 encryptions. Operators should assess how frequently a key is used for encryption and set a rotation schedule that ensures this threshold is not exceeded. For instance, if a key is used for 40 million operations daily, rotating it every three months would be adequate.

to (object) or sites (object) or deployments (object)
Responses
201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict (instance exists)

503

Service Unavailable (strongbox sealed)

post/v1/config/strongbox/transit-keys
Request samples 
name: import
public-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
  AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
  /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
  -----END EC PRIVATE KEY-----
allow-plaintext-backup: false
cipher: ecdsa-p256
convergent-encryption: false
deletion-allowed: false
derived: false
exportable: false
default-encryption-version: 0
min-decryption-version: 0
min-encryption-version: 0
distribute:
  to: inherit

Retrieve the configuration of all transit keys

SecurityaccessToken
Request
query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/transit-keys
Response samples 
- name: import
  public-key: |
    -----BEGIN EC PRIVATE KEY-----
    MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
    AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
    /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
    -----END EC PRIVATE KEY-----
  allow-plaintext-backup: false
  cipher: ecdsa-p256
  convergent-encryption: false
  deletion-allowed: false
  derived: false
  exportable: false
  default-encryption-version: 0
  min-decryption-version: 0
  min-encryption-version: 0
  distribute:
    to: inherit

Update a transit key

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
public-key
string

A initial key can optionally be provided.

allow-plaintext-backup
boolean
Default: false

Allow the transit key to be backed up in plaintext. This allows a key to be backed up, but also restored on another tenant or site.

cipher
string <cipher-type>
Default: "aes256-gcm96"
  • aes128-gcm96: AES 128 GCM, 128 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • aes192-gcm96: AES 192 GCM, 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • aes256-gcm96: AES 256 GCM, 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • chacha20-poly1305: ChaCha20 with Poly1305 (RFC 7539). 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, convergent-encryption.
  • ecdsa-p256: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-256. Supports signing and signature verification.
  • ecdsa-p384: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-384. Supports signing and signature verification.
  • ecdsa-p521: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-521. Supports signing and signature verification.
  • ed25519: Edwards-curve Digital Signature Algorithm. Supports signing and signature verification.
  • rsa-2048: Supports encryption, decryption, signing, signature verification
  • rsa-3072: Supports encryption, decryption, signing, signature verification
  • rsa-4096: Supports encryption, decryption, signing, signature verification
convergent-encryption
boolean
Default: false

If enabled together with derived then the nonce will be calculated instead of randomly generated. The consequence is that the same plaintext will be encrypted to the same ciphertext.

deletion-allowed
boolean
Default: false

Controls if the key can be deleted or not. This is set to false by default since it is a potentially catastrophic operation since no data encrypted with they key will be decryptable once the key has been removed.

derived
boolean
Default: false

The key is derived from the common key and the provided context parameter. Encryption and decryption calls must provide the same context parameter. This allows for a large number of dynamically generated keys.

exportable
boolean
Default: false

If set to true then valid keys can be exported. Cannot be set to false once enabled.

default-encryption-version
integer <uint32>
Default: 0

It is possible to specify a default version for encryption. Once a key has been rotated it might be desirable to delay using the new version until it has been distributed to all parties that need it. Setting the value to 0 indicates that the latest version should be used by default.

min-decryption-version
integer <uint32>
Default: 0

It is possible to specify a minimal version for both encryption and decryption. It might be desirable to phase out an old key by increasing the minimal encryption version, while keeping the minimal decryption version until all data has been migrated to the new version, or become irrelevant.

min-encryption-version
integer <uint32>
Default: 0

It is possible to specify a minimal version for both encryption and decryption. It might be desirable to phase out an old key by increasing the minimal encryption version, while keeping the minimal decryption version until all data has been migrated to the new version, or become irrelevant.

object

It is advisable to periodically rotate encryption keys, regardless of whether a security breach has occurred. According to NIST publication 800-38D, AES-GCM keys should be rotated once they approach approximately 2^32 encryptions. Operators should assess how frequently a key is used for encryption and set a rotation schedule that ensures this threshold is not exceeded. For instance, if a key is used for 40 million operations daily, rotating it every three months would be adequate.

to (object) or sites (object) or deployments (object)
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

patch/v1/config/strongbox/transit-keys/{transit-key-name}
Request samples 
name: import
public-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
  AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
  /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
  -----END EC PRIVATE KEY-----
allow-plaintext-backup: false
cipher: ecdsa-p256
convergent-encryption: false
deletion-allowed: false
derived: false
exportable: false
default-encryption-version: 0
min-decryption-version: 0
min-encryption-version: 0
distribute:
  to: inherit

Delete a transit key

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

delete/v1/config/strongbox/transit-keys/{transit-key-name}

Replace or create a new transit key

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
public-key
string

A initial key can optionally be provided.

allow-plaintext-backup
boolean
Default: false

Allow the transit key to be backed up in plaintext. This allows a key to be backed up, but also restored on another tenant or site.

cipher
string <cipher-type>
Default: "aes256-gcm96"
  • aes128-gcm96: AES 128 GCM, 128 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • aes192-gcm96: AES 192 GCM, 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • aes256-gcm96: AES 256 GCM, 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, and convergent-encryption.
  • chacha20-poly1305: ChaCha20 with Poly1305 (RFC 7539). 256 bit key, 96 bit IV. Supports encryption, decryption, key-derivation, convergent-encryption.
  • ecdsa-p256: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-256. Supports signing and signature verification.
  • ecdsa-p384: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-384. Supports signing and signature verification.
  • ecdsa-p521: Eliptic Curve Digital Signature Algorithm secp256r1, also known as NIST P-521. Supports signing and signature verification.
  • ed25519: Edwards-curve Digital Signature Algorithm. Supports signing and signature verification.
  • rsa-2048: Supports encryption, decryption, signing, signature verification
  • rsa-3072: Supports encryption, decryption, signing, signature verification
  • rsa-4096: Supports encryption, decryption, signing, signature verification
convergent-encryption
boolean
Default: false

If enabled together with derived then the nonce will be calculated instead of randomly generated. The consequence is that the same plaintext will be encrypted to the same ciphertext.

deletion-allowed
boolean
Default: false

Controls if the key can be deleted or not. This is set to false by default since it is a potentially catastrophic operation since no data encrypted with they key will be decryptable once the key has been removed.

derived
boolean
Default: false

The key is derived from the common key and the provided context parameter. Encryption and decryption calls must provide the same context parameter. This allows for a large number of dynamically generated keys.

exportable
boolean
Default: false

If set to true then valid keys can be exported. Cannot be set to false once enabled.

default-encryption-version
integer <uint32>
Default: 0

It is possible to specify a default version for encryption. Once a key has been rotated it might be desirable to delay using the new version until it has been distributed to all parties that need it. Setting the value to 0 indicates that the latest version should be used by default.

min-decryption-version
integer <uint32>
Default: 0

It is possible to specify a minimal version for both encryption and decryption. It might be desirable to phase out an old key by increasing the minimal encryption version, while keeping the minimal decryption version until all data has been migrated to the new version, or become irrelevant.

min-encryption-version
integer <uint32>
Default: 0

It is possible to specify a minimal version for both encryption and decryption. It might be desirable to phase out an old key by increasing the minimal encryption version, while keeping the minimal decryption version until all data has been migrated to the new version, or become irrelevant.

object

It is advisable to periodically rotate encryption keys, regardless of whether a security breach has occurred. According to NIST publication 800-38D, AES-GCM keys should be rotated once they approach approximately 2^32 encryptions. Operators should assess how frequently a key is used for encryption and set a rotation schedule that ensures this threshold is not exceeded. For instance, if a key is used for 40 million operations daily, rotating it every three months would be adequate.

to (object) or sites (object) or deployments (object)
Responses
201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

put/v1/config/strongbox/transit-keys/{transit-key-name}
Request samples 
name: import
public-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
  AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
  /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
  -----END EC PRIVATE KEY-----
allow-plaintext-backup: false
cipher: ecdsa-p256
convergent-encryption: false
deletion-allowed: false
derived: false
exportable: false
default-encryption-version: 0
min-decryption-version: 0
min-encryption-version: 0
distribute:
  to: inherit

Retrieve the configuration of a transit key

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/transit-keys/{transit-key-name}
Response samples 
name: import
public-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
  AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
  /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
  -----END EC PRIVATE KEY-----
allow-plaintext-backup: false
cipher: ecdsa-p256
convergent-encryption: false
deletion-allowed: false
derived: false
exportable: false
default-encryption-version: 0
min-decryption-version: 0
min-encryption-version: 0
distribute:
  to: inherit

Retrieve the state of all transit keys

SecurityaccessToken
Request
query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/transit-keys
Response samples 
- name: import
  public-key: |
    -----BEGIN EC PRIVATE KEY-----
    MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
    AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
    /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
    -----END EC PRIVATE KEY-----
  allow-plaintext-backup: false
  cipher: ecdsa-p256
  convergent-encryption: false
  deletion-allowed: false
  derived: false
  exportable: false
  default-encryption-version: 0
  min-decryption-version: 0
  min-encryption-version: 0
  latest-version: 1
  creation-time: 2022-01-12T17:42:06.266053Z
  distribute:
    to: inherit
  distribution-status:
    to: none
  supports-encryption: false
  supports-decryption: false
  supports-derivation: false
  supports-signing: false
  keys:
    - version: 1
      data: "1642009326266053"
      creation-time: 2022-01-12T17:42:06.266053Z

Retrieve the state of a transit key

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/transit-keys/{transit-key-name}
Response samples 
name: import
public-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
  AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
  /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
  -----END EC PRIVATE KEY-----
allow-plaintext-backup: false
cipher: ecdsa-p256
convergent-encryption: false
deletion-allowed: false
derived: false
exportable: false
default-encryption-version: 0
min-decryption-version: 0
min-encryption-version: 0
latest-version: 1
creation-time: 2022-01-12T17:42:06.266053Z
distribute:
  to: inherit
distribution-status:
  to: none
supports-encryption: false
supports-decryption: false
supports-derivation: false
supports-signing: false
keys:
  - version: 1
    data: "1642009326266053"
    creation-time: 2022-01-12T17:42:06.266053Z

Invoke the backup operation

Backup encryption key and entire state.

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/backup
Response samples 
key: g3QAAAAOZAAWYWxsb3ctcGxhaW50ZXh0LWJhY2t1cGQABHRydWVkAAZjaXBoZXJkAAxhZXMyNTYtZ2NtOTZkABVjb252ZXJnZW50LWVuY3J5cHRpb25kAAVmYWxzZWQADWNyZWF0aW9uLXRpbWVuBwAdVrusZNUFZAAaZGVmYXVsdC1lbmNyeXB0aW9uLXZlcnNpb25hAGQAEGRlbGV0aW9uLWFsbG93ZWRkAAVmYWxzZWQAB2Rlcml2ZWRkAAVmYWxzZWQACmRpc3RyaWJ1dGVkAAdpbmhlcml0ZAAKZXhwb3J0YWJsZWQABWZhbHNlZAAEa2V5c3QAAAADYQF0AAAAAmQADWNyZWF0aW9uLXRpbWVuBwAdVrusZNUFZAAFdmFsdWVtAAAAIFAAEhKAul6uSOKBhdoA5u9phUqNtYc9lmzdNyxN6+5XYQJ0AAAAAmQADWNyZWF0aW9uLXRpbWVuBwAEIsesZNUFZAAFdmFsdWVtAAAAIKJpio8+HhH9FhLanZLFQ0QlPlzwSnxsca4prbMPI/CYYQN0AAAAAmQADWNyZWF0aW9uLXRpbWVuBwApbtGsZNUFZAAFdmFsdWVtAAAAIHi25mJ8QkIYv0YrDzLBKl7xVuwA50SnBDRg9drqX6jZZAAObGF0ZXN0LXZlcnNpb25hA2QAFm1pbi1kZWNyeXB0aW9uLXZlcnNpb25hAmQAFm1pbi1lbmNyeXB0aW9uLXZlcnNpb25hAGQABG5hbWVtAAAAAngx

Invoke the check-rotate operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
offset
string <duration>
Default: "0s"

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Time offset for testing.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/check-rotate
Request samples 
offset: 0s
Response samples 
rotated: true
min-encryption-version-updated: true
min-decryption-version-updated: true
default-encryption-version-updated: true

Invoke the decrypt operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
ciphertext
required
string <ciphertext>
base64-encoded
boolean
Default: true

Encode the result using base64.

key-version
integer <uint32>
context
string
additional-auth-data
string
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/decrypt
Request samples 
ciphertext: sbox:v1:6Ie5+/43eQE4QrABNIBTkVIMZKknVqq3k2JLOm0IWITji0JI
base64-encoded: true
key-version: 1
context: some context
additional-auth-data: my-db
Response samples 
plaintext: Zm9vIGJhcgo=

Invoke the encrypt operation

Encrypt some data using the named key. Additional auth-data may be supplied and it must match when decrypting.

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
plaintext
required
string <plaintext>
base64-encoded
boolean
Default: true

The input data is base64 encoded.

key-version
integer <uint32>
context
string
additional-auth-data
string
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/encrypt
Request samples 
plaintext: Zm9vIGJhcgo
base64-encoded: true
key-version: 1
context: some context
additional-auth-data: db
Response samples 
ciphertext: sbox:v1:6Ie5+/43eQE4QrABNIBTkVIMZKknVqq3k2JLOm0IWITji0JI

Invoke the export operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
version
integer or string <uint32 | enumeration>
Default: "all"
  • uint32
  • enumeration: - all - latest
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/export
Request samples 
version: all
Response samples 
keys:
  - version: 1
    value: |
      -----BEGIN RSA PRIVATE KEY-----
      MIIEowIBAAKCAQEArQWC8v6/1Y37a6NWGeIQcsZXxvEqDzCJmYI5RfO+qIVpdmAI
      UWMQ1O8Mr/t/2gCxRJ03rBAHl4R2/WyTW1lSnK/OdGgrraF5JaJc9IL5i0E0e59g
      jrY+LpsQ9X91907t9dsw1FUkReQspaKf5dxRwtpy3SQbAM/bmXUJz8wSFPSCVgja
      Pq8no+0vBjBsk/QoH5FHnubkloCff+yVcDeUbal6YoyXRQ+AUGK6TiXsVtzWcFrv
      QRkwIOoWCsJ6Flk7L7g4JhA9HaL8FTJyZdiixTK4IP+yR3v9y8fOplC2uCY9rynf
      abAPpAurP9tNkx9qCPVZNobKYWB+cTjk1MR8gwIDAQABAoIBAF6dSvSSdljToY9E
      7IqO4qvA5rM1oehYhIZbffJQzgvdmMRQ03ueDtBCQM/jWhDenBGHX7BJu70RhPgk
      bZhgihqA0Qc7B9eVG2iHFwnmrYuHBqorh2PDKNHXnjiBkQLCOMJfMJ6MSJ+nnPqe
      qY3LIzLIvlNLsTCKee264LivQZwPCvOCdGOaUb4bzLZWcStJVY4P5zWzBheOuTKo
      WOWwGKzmNk+nLQAL6UZF0bI+63CLIvX9kAfUMAcPb3y+QZtd781fT7rCk76CJ1kO
      JHHzksNHXhWVAmPBBz0MNLM5Zx3Z4DU2I97tQUoGKeR2Kqzb6jvdT5nrLTVUYpCZ
      Yd6S4kECgYEA2u7O6aOTTHrjx5wK1G1VqdFtp5OtQhOfv60w+eqjNTtDhIs4OWU3
      O+3u5tS3FkvqMEHNcKcvaPOsXK2IUj52bMNkzT68qS59QFiEuW0OLtKMKSgosGhq
      L2goPhlRrqGlYQ2F15bFaEHGwBFVbPtuEYt6p1IfkYRgVwUehac/+LMCgYEAylDF
      rU0+BRLpArVB0FAlewm17JuspIkonaNgVYvUeQxgIxZk1ZnVmbPKwny6jo6Qu6HT
      q3NwJMmNvSnBNBqUIu7L7kSAO+Du3CFUqfwP86J1obkzLyAmFgHDwRJjfe2qWXWM
      0lAzhx2kBksGLSWKEHHhwvhXdL+sXUaAVM5dNPECgYBIfo0rVkvfJk4oeaYoYy/b
      dIqv07mqSJ88NBgkmSqD5OTdjdAHSVm50XarHsKlcmvQoOlrJSEQyqdHZPrf6OkD
      6MuHHwAPsWIuHWGNmOv6WyOoOTEIAPswSXgR4AZpIgOGGJk6IyWo+Sbb0KGN3c+7
      pYjuwMXNRJ02E27g6NnI+wKBgFaKAFRl4u6GrTbkU3eIoM+lUrUXzdw/cyki1jUh
      b8wrd//qN02K1Ow/FK7mbWJHJy+rRABli4Wg1Ukh0Cu6Zr0eigqsMHHsgB+W/kEL
      ucMMLeb0cilpRgFJ1fMDK52VCLXla0wW1EOqcRvkAYtUMF9iZyBf3ADrcA4h9wjP
      kNzxAoGBAMYxu7K1WFDj55M2rmrI3lp5yBxryPOP+UXTANsRwpkzMF5X0Y2DHvIq
      B5BSVxeQ7Cq1nIORHbm7IZv/c6ytAWw3Yj9lp1tBsAZlaRFDJ7YDEHQxaXzCHyc3
      L6MXNmys9zpSoaFBeCJ9fCp+Imthz3n+zbUcuf8+AYxE9aMw4Min
      -----END RSA PRIVATE KEY-----

Invoke the generate-data-key operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
bits
integer <uint32>
Default: 256
type
string <enumeration>
  • wrapped: Present the result encrypted with the transit key.
  • plaintext: Present the result in base64 encrypted plaintext, in addition to the encrypted version.
key-version
integer <uint32>

Key version to encrypt the result with

context
string

Context for the encryption of the result, in case the cipher type requires it.

additional-auth-data
string

If needed needed by the cipher.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/generate-data-key
Request samples 
bits: 256
type: plaintext
key-version: 1
context: some context
additional-auth-data: db
Response samples 
ciphertext: sbox:v3:2+LwgU0wTxRDRVD6LkmbKUdU7xmMwuMVmQVhmPZg/sQ22egu67gv+eME9pUBEDQV00iGZHfwaFB8rm4q
plaintext: FijSLX2OZQyzdJt4N/10af4A4MGBYi/Uej8/Tjd5LIQ=

Invoke the hmac operation

Calculate the HMAC with the given key.

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
plaintext
required
string <plaintext>
key-version
integer <uint32>
context
string
algorithm
string <hmac-digest-type>
Default: "sha256"
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
  • sha3-224
  • sha3-256
  • sha3-384
  • sha3-512 Digest types, sha1 should be avoided.
auto-setup
boolean
Default: true
base64-encoded
boolean
Default: true
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/hmac
Request samples 
plaintext: the quick brown fox
key-version: 1
context: some context
algorithm: sha256
auto-setup: true
base64-encoded: false
Response samples 
hmac: sbox:hashed:v1:oSoTBSIbKvBZT6wpRQLqFHXhUYE5Cg2IErx0kOyaIQc=

Invoke the import operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
data
required
string
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/import
Request samples 
data: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOtZk70H7MTVQOPOJFQPVzM0Kjc0B8wXj7OtrjtyBYVLoAoGCCqGSM49
  AwEHoUQDQgAEZWoYC3Xg7WF6W/TZ4CLfnXSUCgw2fJAJiX5+P4AjRqPY6onal8AK
  /7UP/xJLQR4E06m7IrfXAlQEwC99s1WwxQ==
  -----END EC PRIVATE KEY-----

Invoke the restore operation

Restore key from backup.

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
key
required
string
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/restore
Request samples 
key: g3QAAAAOZAAWYWxsb3ctcGxhaW50ZXh0LWJhY2t1cGQABHRydWVkAAZjaXBoZXJkAAxhZXMyNTYtZ2NtOTZkABVjb252ZXJnZW50LWVuY3J5cHRpb25kAAVmYWxzZWQADWNyZWF0aW9uLXRpbWVuBwAdVrusZNUFZAAaZGVmYXVsdC1lbmNyeXB0aW9uLXZlcnNpb25hAGQAEGRlbGV0aW9uLWFsbG93ZWRkAAVmYWxzZWQAB2Rlcml2ZWRkAAVmYWxzZWQACmRpc3RyaWJ1dGVkAAdpbmhlcml0ZAAKZXhwb3J0YWJsZWQABWZhbHNlZAAEa2V5c3QAAAADYQF0AAAAAmQADWNyZWF0aW9uLXRpbWVuBwAdVrusZNUFZAAFdmFsdWVtAAAAIFAAEhKAul6uSOKBhdoA5u9phUqNtYc9lmzdNyxN6+5XYQJ0AAAAAmQADWNyZWF0aW9uLXRpbWVuBwAEIsesZNUFZAAFdmFsdWVtAAAAIKJpio8+HhH9FhLanZLFQ0QlPlzwSnxsca4prbMPI/CYYQN0AAAAAmQADWNyZWF0aW9uLXRpbWVuBwApbtGsZNUFZAAFdmFsdWVtAAAAIHi25mJ8QkIYv0YrDzLBKl7xVuwA50SnBDRg9drqX6jZZAAObGF0ZXN0LXZlcnNpb25hA2QAFm1pbi1kZWNyeXB0aW9uLXZlcnNpb25hAmQAFm1pbi1lbmNyeXB0aW9uLXZlcnNpb25hAGQABG5hbWVtAAAAAngx

Invoke the rewrap operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
ciphertext
required
string <ciphertext>
additional-auth-data
string
key-version
integer <uint32>
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/rewrap
Request samples 
ciphertext: sbox:v2:xAzeNi0PqX1dy1rNVCAPmDdZgbg16PPEkwO/0Qqtce1cjUQB
additional-auth-data: db
key-version: 1
Response samples 
ciphertext: sbox:v3:4XZRmyckd4nG+7+zeOZtG8ThwwM1ieNEUcKaTZsm2QYpNviM

Invoke the rotate operation

Rotate the transit key. A new version will be created. It is still possible to decrypt data encrypted with the old key and new data can be encrypted with an old key, provided a version is specified.

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/rotate

Invoke the sign operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
text
required
string <plaintext>
key-version
integer <uint32>
hash-algorithm
string <digest-type>
Default: "sha256"
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512 Digest types, sha1 should be avoided.
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/sign
Request samples 
text: Zm9vIGJhcgo=
key-version: 1
hash-algorithm: sha256
Response samples 
signature: sbox:v1:d4E3eAPI2T/li655H8n6ESikJlpZVRB370Qst7s1c+rEIH6HqPWwLcoAhWUThMlB9iYDF5hK8Q7r4F8rMy6KIeCXvWodglQ6eh0s8eYrQrFXeA7arZLBQ1dq4mVZJcfMF3UGZttjO8bkMVGriG+Na8at1MKyv3k48gaTHCO0cex+8xk58CN64aaArYpFcLQLSRituGUVyTqWSI2rmpY/pTSWb7VC/S7YQ+JHLnpvgVAL5Mh9o6JSMqvYPIaEKuQh/5MDtz4r8V+lEOuPhEBaYHzc4Opm4ZOYdziUL/5o2Z/vE8XG9DSJIypoR/7iVPJ08VMl5I/4grWkcemyLWtSPQ==

Invoke the trim operation

Remove previous version of the key. Once removed they cannot be recoved.

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
min-available-version
required
integer <uint32>
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/trim
Request samples 
min-available-version: 2

Invoke the verify operation

SecurityaccessToken
Request
path Parameters
transit-key-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of transit-key

Request Body schema:
text
required
string <plaintext>
signature
required
string
key-version
integer <uint32>
hash-algorithm
string <digest-type>
Default: "sha256"
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512 Digest types, sha1 should be avoided.
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/transit-keys/{transit-key-name}/verify
Request samples 
text: Zm9vIGJhcgo=
signature: sbox:v1:d4E3eAPI2T/li655H8n6ESikJlpZVRB370Qst7s1c+rEIH6HqPWwLcoAhWUThMlB9iYDF5hK8Q7r4F8rMy6KIeCXvWodglQ6eh0s8eYrQrFXeA7arZLBQ1dq4mVZJcfMF3UGZttjO8bkMVGriG+Na8at1MKyv3k48gaTHCO0cex+8xk58CN64aaArYpFcLQLSRituGUVyTqWSI2rmpY/pTSWb7VC/S7YQ+JHLnpvgVAL5Mh9o6JSMqvYPIaEKuQh/5MDtz4r8V+lEOuPhEBaYHzc4Opm4ZOYdziUL/5o2Z/vE8XG9DSJIypoR/7iVPJ08VMl5I/4grWkcemyLWtSPQ==
key-version: 1
hash-algorithm: sha256
Response samples 
valid: true
➔ Next to User Passwords