Cryptographic Operations

Below are the cryptographic operations that can be done using keys on the HSM.

Encrypt

Encrypt a payload

$ vault write securosys-hsm/operation/encrypt/{key-name} 
payload={base64-encoded-string}
password={password-of-the-key}
cipherAlgorithm={cipher-algorithm}
tagLength={tag-length}
additionalAuthenticationData={additional-authentication-data}

curl --location --request PUT '<server_addr>/v1/securosys-hsm/operation/encrypt/{key-name}' \
--header 'X-Vault-Token: <vault_access_token>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payload={base64-encoded-string}' \
--data-urlencode 'password={password-for-a-key}' \
--data-urlencode 'cipherAlgorithm={cipher-algorithm}' \
--data-urlencode 'tagLength={tag-length}' \
--data-urlencode 'additionalAuthenticationData={additional-authentication-data}'

Decrypt

Decrypt an encrypted payload In case the referenced key has a policy attached, then a request-id is returned indicating the required approvals to collect. See section Requests.

Tip

The keyVersion has to be provided in this request, either by adding it in the url (e.g. securosys-hsm/operation/decrypt/{key-name}/{key-version}), or by passing it as parameter (e.g.keyVersion={key-version}). :::

$ vault write securosys-hsm/operation/decrypt/{key-name} 
password={password-for-a-key}
keyVersion={key-version}
encryptedPayload={base64-encoded-string}
cipherAlgorithm={cipher-algorithm}
initializationVector={initialization-vector}
tagLength={tag-length}
additionalAuthenticationData={additional-authentication-data}

curl --location --request PUT '<server_addr>/v1/securosys-hsm/operation/decrypt/{key-name}' \
--header 'X-Vault-Token: <vault_access_token>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'encryptedPayload={base64-encoded-string}' \
--data-urlencode 'keyVersion={key-version}' \
--data-urlencode 'cipherAlgorithm={cipher-algorithm}' \
--data-urlencode 'password={password-for-a-key}' \
--data-urlencode 'tagLength={tag-length}' \
--data-urlencode 'initializationVector={initialization-vector}' \
--data-urlencode 'additionalAuthenticationData={additional-authentication-data}'

Sign

Sign a payload In case the referenced key has a policy attached, then a request-id is returned, indicating the required approvals to be collected. See section Requests

$ vault write securosys-hsm/operation/sign/{key-name}
password={password-for-the-key}
signatureAlgorithm={algorithm}
payload={payload-base64}
payloadType={payload-type}
metaData={meta-data-base64}
metaDataSignature={meta-data-signature}

curl --location --request PUT '<server_addr>/v1/securosys-hsm/operation/sign/{key-name}' \
--header 'X-Vault-Token: <vault_access_token>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'signatureAlgorithm={algorithm}' \
--data-urlencode 'payload={payload-base64}' \
--data-urlencode 'payloadType={payload-type}' \
--data-urlencode 'password={password-for-a-key}' \
--data-urlencode 'metaData={meta-data-base64}' \
--data-urlencode 'metaDataSignature={meta-data-signature}'

Verify

Verify the signature of a signed payload

Tip

The keyVersion has to be provided in this request, either by adding it in the url (e.g. securosys-hsm/operation/verify/{key-name}/{key-version}), or by passing it as parameter (e.g.keyVersion={key-version}).

$ vault write securosys-hsm/operation/verify/{key-name}
password={password-for-the-key}
signatureAlgorithm={algorithm}
payload={payload-base64}
signature={signature}

curl --location --request PUT '<server_addr>/v1/securosys-hsm/operation/verify/{key-name}' \
--header 'X-Vault-Token: <vault_access_token>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'signatureAlgorithm={algorithm}' \
--data-urlencode 'payload={payload-base64}' \
--data-urlencode 'password={password-for-a-key}' \
--data-urlencode 'signature={meta-data-signature}'

Wrap

Wrap a key with another (wrapper) key

$ vault write securosys-hsm/operation/wrap/{key-to-be-wrapped}/{wrap-key-name}
keyToBeWrappedPassword={password-for-first-key}
wrapKeyPassword={password-for-second-key}
wrapMethod={wrap-method}

curl --location --request PUT '<server_addr>/v1/securosys-hsm/operation/wrap/{key-to-be-wrapped}/{wrap-key-name}' \
--header 'X-Vault-Token: <vault_access_token>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'keyToBeWrappedPassword={password-for-first-key}' \
--data-urlencode 'wrapKeyPassword={password-for-second-key}' \
--data-urlencode 'wrapMethod={wrap-method}'

Unwrap

Unwrap a key using a wrapper key In case the referenced key has a policy attached, then a request-id is returned, indicating the required approvals to collect. See section Requests.

Note: The keyVersion has to be provided in this request, either by adding it in the url (e.g. securosys-hsm/operation/unwrap/{new-unwrapped-key-name}/{wrap-key-name}/{key-version}), or by passing it as parameter (e.g.keyVersion={key-version}).

$ vault write securosys-hsm/operation/unwrap/{new-unwrapped-key-name}/{wrap-key-name}
keyLabel={key-label-for-new-key}
keyVersion={key-version}
wrappedKey={wrapped-key-base64-encoded}
password={password-for-wrap-key}
wrapMethod={wrap-method}
simplePolicy={policy} or policy={full-policy} or policy=@policy-file.json
attributes={attributes}

curl --location --request PUT '<server_addr>/v1/securosys-hsm/operation/unwrap/{new-unwrapped-key-name}/{wrap-key-name}' \
--header 'X-Vault-Token: <vault_access_token>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'keyLabel={key-label-for-new-key}' \
--data-urlencode 'keyVersion={key-version}' \
--data-urlencode 'wrappedKey={wrapped-key-base64-encoded}' \
--data-urlencode 'wrapMethod={wrap-method}' \
--data-urlencode 'simplePolicy={policy}' or --data-urlencode 'policy={full-policy}' \
--data-urlencode 'password={password-for-wrap-key}'
--data-urlencode 'attributes={attributes}' \