Key Management Service (KMS)

Concept

Keys managed in KMS are not extractable from the platform. Additionally, data is never stored when performing cryptographic operations.

Workflow

Feedback
Creating a KMS key. As part of this step, you specify a name for the key and the encryption algorithm meant to be used for it (e.g. AES-GCM-128, AES-GCM-256).
Feedback
Encryption: To encrypt data, you would make a request to the Hanzo KMS API endpoint, specifying the base64-encoded plaintext and the intended key to use for encryption; the API would return the base64-encoded ciphertext.
Feedback
Decryption: To decrypt data, you would make a request to the Hanzo KMS API endpoint, specifying the base64-encoded ciphertext and the intended key to use for decryption; the API would return the base64-encoded plaintext.

Note that this workflow can be executed via the Hanzo KMS UI or manually such as via API.

Encryption

Guide to Encrypting Data

Navigate to Project > Key Management and tap on the Add Key button.

Specify your key details. Here's some guidance on each field:

• Name: A slug-friendly name for the key.
• Key Usage: The type of key to create (e.g Encrypt/Decrypt for encryption, and Sign/Verify for signing).
• Algorithm: The encryption algorithm associated with the key (e.g. AES-GCM-256).
• Description: An optional description of what the intended usage is for the key.

Once your key is generated, open the options menu for the newly created key and select encrypt data.

Populate the text area with your data and tap on the Encrypt button.

If your data is already Base64 encoded make sure to toggle the respective switch on to avoid redundant encoding.

Copy and store the encrypted data.

To create a cryptographic key, make an API request to the Create KMS Key API endpoint.

Sample request

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys \
--header 'Content-Type: application/json' \
--data '{
    "projectId": "<project-id>",
    "name": "my-secret-key",
    "description": "...",
    "encryptionAlgorithm": "aes-256-gcm"
}'

Sample response

{
    "key": {
        "id": "<key-id>",
        "description": "...",
        "isDisabled": false,
        "isReserved": false,
        "orgId": "<org-id>",
        "name": "my-secret-key",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "projectId": "<project-id>"
    }
}

To encrypt data, make an API request to the Encrypt Data API endpoint, specifying the key to use.

Make sure your data is Base64 encoded

Sample request

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys/<key-id>/encrypt \
--header 'Content-Type: application/json' \
--data '{
    "plaintext": "lUFHM5Ggwo6TOfpuN1S==" // base64 encoded plaintext
}'

Sample response

{
    "ciphertext": "HwFHwSFHwlMF6TOfp==" // base64 encoded ciphertext
}

Guide to Decrypting Data

Navigate to Project > Key Management and open the options menu for the key used to encrypt the data you want to decrypt.

Paste your encrypted data into the text area and tap on the Decrypt button. Optionally, if your data was originally plain text, enable the decode Base64 switch.

Your decrypted data will be displayed and can be copied for use.

To decrypt data, make an API request to the Decrypt Data API endpoint, specifying the key to use.

Sample request

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys/<key-id>/decrypt \
--header 'Content-Type: application/json' \
--data '{
    "ciphertext": "HwFHwSFHwlMF6TOfp==" // base64 encoded ciphertext
}'

Sample response

{
    "plaintext": "lUFHM5Ggwo6TOfpuN1S==" // base64 encoded plaintext
}

Signing

Guide to Signing Data

Navigate to Project > Key Management and tap on the Add Key button.

Specify your key details. Here's some guidance on each field:

• Name: A slug-friendly name for the key.
• Key Usage: The type of key to create (e.g Encrypt/Decrypt for encryption, and Sign/Verify for signing).
• Algorithm: The signing algorithm associated with the key (e.g. RSA_4096).
• Description: An optional description of what the intended usage is for the key.

Once your key is generated, open the options menu for the newly created key and select sign data.

Populate the text area with your data and tap on the Sign button.

Make sure to select the appropriate signing algorithm that will be used to sign the data. Supported signing algorithms are:

For RSA keys:

• RSASSA PSS SHA 512: Not deterministic, and includes random salt.
• RSASSA PSS SHA 384: Not deterministic, and includes random salt.
• RSASSA PSS SHA 256: Not deterministic, and includes random salt.
• RSASSA PKCS1 V1.5 SHA 512: Deterministic, and does not include randomness.
• RSASSA PKCS1 V1.5 SHA 384: Deterministic, and does not include randomness.
• RSASSA PKCS1 V1.5 SHA 256: Deterministic, and does not include randomness.

For ECC keys:

• ECDSA SHA 512: Not deterministic, and includes randomness.
• ECDSA SHA 384: Not deterministic, and includes randomness.
• ECDSA SHA 256: Not deterministic, and includes randomness.

In this example, we'll use the RSASSA PSS SHA 512 signing algorithm.

If your data is already Base64 encoded make sure to toggle the respective switch on to avoid redundant encoding.

Copy and store the signature of your data.

To sign data, make an API request to the Sign Data API endpoint, specifying the key to use.

Sample request

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys/<key-id>/sign \
--header 'Content-Type: application/json' \
--data '{
    "data": "SGVsbG8sIFdvcmxkIQ==", // base64 encoded data
    "signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
}'

Sample response

{
    "signature": "JYuiBt1Ta9pbqFIW9Ou6qzBsFhjYbMJp9k4dP87ILrO+F2MPnp85g3nOlXK1ttZmRoGWsWnLNDRn9W3rf5VtkeaixPqUW/KvY/fM3CxdMyIV3BuxlGgDksjL8X34Eqkrz4CCPo9hjB5uT+rBCOxCgZqRbOdATPipAneUapI9npseNquEeh3jPklwviBix83PJHV9PW2t03AGGUXuMY55ZaFEIMv+IrI1WYdnPVIXDyIitYsS3y+/6KRfhVeTcPNJ5Rw+FE9y1eZzDEZtTNpxOfUT3QIoXmpZlYL4HbhRuJBZ+Yx54C7uPiUIN9U69XbyXt+Kkynykw2HPaagwuCZxiqCU5sFfLnrVbc3dmZxQcX2yRrs2gmFamzBx+uVbi648H4mb7WuE5UPTBjjA11jRsBjCY0YS2T4Vgfe1RlzlPQkZgjP/bnCCGDqXa3/VZAlZX1nTI51X995bPHBQI0rq2sNDlIXenwiAy1wJSITbSI8DbUx09Cr83xCEaYAE6R6PUfog/tbIUXi0VbrYsCVkAGCK446Wb1vW6q7HR8jrjXNwmXlqN9eLbSVWqdWj7N7fieeTYSrECtUaAjxtUYTIVsH2bfT6FOEM9gMWKffOpFowVzzr3B9bNQLIhnEEwebxBw947i4OcxyVIcEUuumWxoKvcbSPxzJ8v1M3SoBBh4=", // base64 encoded signature
    "keyId": "62b2c14e-58af-4199-9842-02995c63edf9",
    "signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
}

To sign predigested data, you can pass "isDigest": true in the request body. This requires the data to be a base64 encoded digest of the data you wish to sign. It's important that the digest is created using the same hashing algorithm as the signing algorithm. As an example, you would create the digest with SHA512 if you are using the RSASSA_PKCS1_V1_5_SHA_512 signing algorithm.

Guide to Verifying Data

Navigate to Project > Key Management and open the options menu for the key used to sign the data you want to verify.

Paste your signature and data into the text areas and tap on the Verify button.

Your verification result will be displayed and can be copied for use.

If the signature is invalid, you'll see an error message indicating that the signature is invalid, and the "Signature Status" field will be Invalid.

To verify data, make an API request to the Verify Data API endpoint, specifying the key to use.

Sample request

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys/<key-id>/verify \
--header 'Content-Type: application/json' \
--data '{
    "data": "SGVsbG8sIFdvcmxkIQ==", // base64 encoded data
    "signature": "JYuiBt1Ta9pbqFIW9Ou6qzBsFhjYbMJp9k4dP87ILrO+F2MPnp85g3nOlXK1ttZmRoGWsWnLNDRn9W3rf5VtkeaixPqUW/KvY/fM3CxdMyIV3BuxlGgDksjL8X34Eqkrz4CCPo9hjB5uT+rBCOxCgZqRbOdATPipAneUapI9npseNquEeh3jPklwviBix83PJHV9PW2t03AGGUXuMY55ZaFEIMv+IrI1WYdnPVIXDyIitYsS3y+/6KRfhVeTcPNJ5Rw+FE9y1eZzDEZtTNpxOfUT3QIoXmpZlYL4HbhRuJBZ+Yx54C7uPiUIN9U69XbyXt+Kkynykw2HPaagwuCZxiqCU5sFfLnrVbc3dmZxQcX2yRrs2gmFamzBx+uVbi648H4mb7WuE5UPTBjjA11jRsBjCY0YS2T4Vgfe1RlzlPQkZgjP/bnCCGDqXa3/VZAlZX1nTI51X995bPHBQI0rq2sNDlIXenwiAy1wJSITbSI8DbUx09Cr83xCEaYAE6R6PUfog/tbIUXi0VbrYsCVkAGCK446Wb1vW6q7HR8jrjXNwmXlqN9eLbSVWqdWj7N7fieeTYSrECtUaAjxtUYTIVsH2bfT6FOEM9gMWKffOpFowVzzr3B9bNQLIhnEEwebxBw947i4OcxyVIcEUuumWxoKvcbSPxzJ8v1M3SoBBh4=", // base64 encoded signature
    "signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}'

Sample response

{
    "signatureValid": true,
    "keyId": "62b2c14e-58af-4199-9842-02995c63edf9",
    "signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}

To verify predigested data, you can pass "isDigest": true in the request body. This requires the data to be a base64 encoded digest of the data you wish to verify. It's important that the digest is created using the same hashing algorithm as the signing algorithm. As an example, you would create the digest with SHA512 if you are using the RSASSA_PKCS1_V1_5_SHA_512 signing algorithm.

FAQ

No. Hanzo KMS's KMS only provides cryptographic services and does not store any encrypted or decrypted data.

No. Hanzo KMS's KMS will never expose your keys, encrypted or decrypted, to external sources.

Currently Hanzo KMS supports 4 different key algorithms with different purposes:

• RSA_4096: For signing and verifying data.

• ECC_NIST_P256: For signing and verifying data.

• AES-256-GCM: For encryption and decryption operations.

• AES-128-GCM: For encryption and decryption operations.

We anticipate to further expand our supported algorithms and support cryptographic operations in the future.

To sign and verify a digest using the Hanzo KMS, you can use the Sign and Verify endpoints respectively. You will need to pass "isDigest": true in the request body to indicate that you are signing or verifying a digest. The data you are signing or verifying will need to be a base64 encoded digest of the data you wish to sign or verify. It's important that the digest is created using the same hashing algorithm as the signing algorithm. As an example, you would create the digest with SHA512 if you are using the RSASSA_PKCS1_V1_5_SHA_512 signing algorithm.

To create a SHA512 digest of your data, you can use the following command with OpenSSL:

echo -n "Hello, World" | openssl dgst -sha512 -binary | openssl base64

Sample request for signing a digest

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys/<key-id>/sign \
--header 'Content-Type: application/json' \
--data '{
"data": <digest-output-of-openssl-command>,
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
"isDigest": true
}'

Sample response for signing a digest

{
    "signature": <base64-encoded-signature>,
    "keyId": <key-id>,
    "signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}

Sample request for verifying a digest

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/kms/keys/<key-id>/verify \
--header 'Content-Type: application/json' \
--data '{
"data": <digest-output-of-openssl-command>,
"signature": <base64-encoded-signature>,
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
"isDigest": true
}'

Sample response for verifying a digest

{
    "signatureValid": true,
    "keyId": <key-id>,
    "signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}

Please note that RSA PSS signing algorithms are not supported for digest signing and verification. Please use RSA PKCS1 V1.5 signing algorithms for digest signing and verification, or ECDSA if you're using an ECC key.