6 Cryptographic Commands
You can use the cryptographic commands to encrypt and decrypt the provided data using the Oracle Key Vault managed security objects.
- okv crypto data decrypt Command
Theokv crypto data decrypt
command performs a decrypt operation on the given ciphertext data using the Oracle Key Vault managed security object that is within the Oracle Key Vault server, and returns the decrypted data. - okv crypto data encrypt Command
Theokv crypto data encrypt
command performs an encrypt operation on the given plaintext data using the Oracle Key Vault managed security object that is within the Oracle Key Vault server, and returns the encrypted data. - okv crypto data sign Command
Theokv crypto data sign
command performs a sign operation on the given message file using the Oracle Key Vault managed security object that is within the Oracle Key Vault server, and returns the signature data. - okv crypto data sign-verify Command
Theokv crypto data sign-verify
command performs a signature verification operation on the given signature data and message file using the Oracle Key Vault managed security object that is within the Oracle Key Vault server, and returns whether or not the signature is valid.
6.1 okv crypto data decrypt Command
The okv crypto data decrypt
command performs a decrypt operation on the given ciphertext data using the Oracle Key Vault managed security object that is within the Oracle Key Vault server, and returns the decrypted data.
Required Authorization
The endpoint must have read permission on the key used for the decryption.
Syntax
okv crypto data decrypt --uuid UUID --data file_path --block-cipher-mode block_cipher_mode --padding padding --iv file_path --authenticated-encryption-additional-data file_path --authenticated-encryption-tag file_path --data-format data_format --decrypted-data output_file_path
JSON Input File Template
{ "service": { "category": "crypto", "resource": "data", "action": "decrypt", "options": { "uuid": "#VALUE", "data" : "#VALUE", "blockCipherMode" : "#CBC|ECB|CFB|OFB|GCM", "padding" : "#NONE|ZEROS|PKCS5", "iv" : "#VALUE", "authenticatedEncryptionAdditionalData" : "#VALUE", "authenticatedEncryptionTag" : "#VALUE" "dataFormat": "#HEX|BASE64", "decryptedData": "#VALUE" } } }
Parameters
Parameter/Template Parameter | Required? | Description |
---|---|---|
|
Required |
Universally unique ID (UUID) of the key to use for the decryption. To find the unique identifier for the object, in the Oracle Key Vault management console, click the Keys & Wallets tab, and then click Keys & Secrets in the left navigation window. In the Keys & Secrets table, check the Unique Identifier column. |
|
Required |
File path to the ciphertext data that needs to be decrypted |
|
Optional |
Block Cipher Mode. Values are as follows:
If you omit this setting, then Oracle Key Vault uses the cryptographic parameters that are associated with the key. |
|
Optional |
Padding. Values are as follows:
If you omit this setting, then Oracle Key Vault uses the cryptographic parameters that are associated with the key. |
|
Optional |
File path of the initialization vector (IV) to use for the decrypt operation. You must use the same initialization vector that was used during encryption. |
|
Optional |
File path of authenticated encryption additional data to use for the decrypt operation. You must specify the same authenticated encryption additional data that was used during encryption. |
|
Optional |
File path of the authenticated encryption tag to use for the decrypt operation. You must specify the same authenticated encryption tag that was generated during encryption. |
|
Optional |
Data format. Format of the data in input and output files. If not specified, data is read and written as binary data. Values are as follows:
|
|
Required |
File path where the decrypted data is written. If the provided output file does not exist, then an error results. If the file is present, then it is overwritten with the decrypted data. |
JSON Example
- Generate JSON input for the
okv crypto data decrypt
command.okv crypto data decrypt --generate-json-input
The generated input appears as follows:
{ "service": { "category": "crypto", "resource": "data", "action": "decrypt", "options": { "uuid": "#VALUE", "data" : "#VALUE", "blockCipherMode" : "#CBC|ECB|CFB|OFB|GCM", "padding" : "#NONE|ZEROS|PKCS5", "iv" : "#VALUE", "authenticatedEncryptionAdditionalData" : "#VALUE", "authenticatedEncryptionTag" : "#VALUE" "dataFormat": "#HEX|BASE64", "decryptedData": "#VALUE" } } }
- Save the generated input to a file (for example,
key_decrypt.json
) and then edit it to include the decryption settings that you want. For example:{ "service": { "category": "crypto", "resource": "data", "action": "decrypt", "options": { "uuid": "2359E04F-DA61-4F7C-BF9F-913D3369A93A", "data" : "/okv/opt/data", "blockCipherMode" : "GCM", "padding" : "ZEROS", "iv" : "/okv/opt/iv", "authenticatedEncryptionAdditionalData" : "/okv/opt/keys/authenticatedEncryptionAdditionalData", "authenticatedEncryptionTag" : "/okv/opt/keys/authenticatedEncryptionTag", "dataFormat": "HEX", "decryptedData": "/okv/opt/keys/decrypted_data" } } }
- Run the
okv crypto data decrypt
command using the generated JSON file.okv crypto data decrypt --from-json key_decrypt.json
Output similar to the following appears:
{ "result" : "Success", "value" : { "decryptedData" : "/okv/opt/keys/decrypted_data" } }
Parent topic: Cryptographic Commands
6.2 okv crypto data encrypt Command
The okv crypto data encrypt
command performs an encrypt operation on the given plaintext data using the Oracle Key Vault managed security object that is within the Oracle Key Vault server, and returns the encrypted data.
Required Authorization
The endpoint must have read permission on the key used for the encryption.
Syntax
okv crypto data encrypt --uuid UUID --data file_path --block-cipher-mode block_cipher_mode --padding padding --random-iv random_iv --iv file_path --authenticated-encryption-additional-data file_path --data-format data_format --encrypted-data output_file_path --iv-out output_file_path --authenticated-encryption-tag output_file_path
JSON Input File Template
{ "service": { "category": "crypto", "resource": "data", "action": "encrypt", "options": { "uuid": "#VALUE", "data" : "#VALUE", "blockCipherMode" : "#CBC|ECB|CFB|OFB|GCM", "padding" : "#NONE|ZEROS|PKCS5", "randomIV" : "#TRUE|FALSE", "iv" : "#VALUE", "authenticatedEncryptionAdditionalData" : "#VALUE", "dataFormat": "#HEX|BASE64", "encryptedData": "#VALUE", "ivOut": "#VALUE", "authenticatedEncryptionTag" : "#VALUE" } } }
Parameters
Parameter/Template Parameter | Required? | Description |
---|---|---|
|
Required |
Universally unique ID (UUID) of the key to use for the encryption. To find the unique identifier for the object, in the Oracle Key Vault management console, click the Keys & Wallets tab, and then click Keys & Secrets in the left navigation window. In the Keys & Secrets table, check the Unique Identifier column. |
|
Required |
File path to the plaintext data that needs to be encrypted |
|
Optional |
Block Cipher Mode. Values are as follows:
If you omit this setting, then Oracle Key Vault uses the cryptographic parameters that are associated with the key. Note: If you are using the
block-cipher-mode as GCM , then set the
--authenticated-encryption-tag with the parameter.
|
|
Optional |
Padding. Values are as follows:
If you omit this setting, then Oracle Key Vault uses the cryptographic parameters that are associated with the key. |
|
Optional |
Indicates whether the Oracle Key Vault server should use random initialization vector (IV). Values are as follows:
Oracle Key Vault uses the |
|
Optional |
File path of the IV to use for the encrypt operation. If you include the IV file path in the |
|
Optional |
File path of authenticated encryption additional data to use for the encrypt operation. If you include the authenticated encryption additional data file path in the |
|
Optional |
Data format. Format of the data in input and output files. If not specified, data is read and written as binary data. Values are as follows:
|
|
Required |
File path where the encrypted data is written. If the provided output file does not exist, then an error results. If the file is present, then it is overwritten with the encrypted data. |
|
Optional |
File path where the response IV is written. If the provided output file does not exist, then an error results. If the file is present, then it is overwritten with the response IV. The IV is returned in If you include the response IV file path in the |
|
Optional |
File path where the response authenticated encryption tag is written. If the provided output file does not exist, then an error results. If the file is present, then it is overwritten with the response authenticated encryption tag. The authenticated encryption tag that is returned should be used for decrypting the cipher text. If you include the response authenticated encryption tag file path in the |
JSON Example
- Generate JSON input for the
okv crypto data encrypt
command.okv crypto data encrypt --generate-json-input
The generated input appears as follows:
{ "service": { "category": "crypto", "resource": "data", "action": "encrypt", "options": { "uuid": "#VALUE", "data" : "#VALUE", "blockCipherMode" : "#CBC|ECB|CFB|OFB|GCM", "padding" : "#NONE|ZEROS|PKCS5", "randomIV" : "#TRUE|FALSE", "iv" : "#VALUE", "authenticatedEncryptionAdditionalData" : "#VALUE", "dataFormat": "#HEX|BASE64", "encryptedData": "#VALUE", "ivOut": "#VALUE", "authenticatedEncryptionTag" : "#VALUE" } } }
- Save the generated input to a file (for example,
key_encrypt.json
) and then edit it to include the encryption settings that you want. Keep a record of the values that you use during encryption along with the generated ivOut and authenticatedEncryptionTag, if any. You must provide the same values when decrypting the ciphertext. For example:{ "service": { "category": "crypto", "resource": "data", "action": "encrypt", "options": { "uuid": "2359E04F-DA61-4F7C-BF9F-913D3369A93A", "data" : "/okv/opt/data", "blockCipherMode" : "GCM", "padding" : "ZEROS", "iv" : "/okv/opt/iv", "authenticatedEncryptionAdditionalData" : "/okv/opt/keys/authenticatedEncryptionAdditionalData", "dataFormat": "HEX", "encryptedData": "/okv/opt/keys/encrypted_data", "authenticatedEncryptionTag" : "/okv/opt/keys/authenticatedEncryptionTag" } } }
- Run the
okv crypto data encrypt
command using the generated JSON file.okv crypto data encrypt --from-json key_encrypt.json
Output similar to the following appears:
{ "result" : "Success", "value" : { "encryptedData" : "/okv/opt/keys/encrypted_data" "authenticatedEncryptionTag" : "/okv/opt/keys/authenticatedEncryptionTag" } }
Note:
Oracle Key Vault can encrypt maximum 32KB of data.Parent topic: Cryptographic Commands
6.3 okv crypto data sign Command
The okv crypto data sign
command performs a sign
operation on the given message file using the Oracle Key Vault managed security object that is
within the Oracle Key Vault server, and returns the signature data.
Required Authorization
The endpoint must have read permission on the private key used for signing.
Syntax
okv crypto data sign --uuid <UUID> --message-file <filePath> --message <message> --message-type <messageType> --digital-signature-algorithm <digitalSignatureAlgoritm> --signature-data <output file path> --output_format TEXT
JSON Input File Template
{ "service": { "category": "crypto", "resource": "data", "action": "sign", "options": { "uuid": "#VALUE", "message" : "#VALUE", "messageFile" : "#VALUE", "messageType" : "#RAW|DIGEST", "digitalSignatureAlgorithm" : #RSASSA_PKCS1_v1_5_SHA256|RSASSA_PKCS1_v1_5_SHA384|RSASSA_PKCS1_v1_5_SHA512|RSASSA_PSS_SHA256|RSASSA_PSS_SHA384|RSASSA_PSS_SHA512", "signatureData": "#VALUE" } } }
Parameters
Parameter/Template Parameter | Required? | Description |
---|---|---|
|
Required |
Unique Identifier of the key to be used for the signature operation. To find the unique identifier for the object, in the Oracle Key Vault management console, click the Keys & Wallets tab, and then click Keys & Secrets in the left navigation window. In the Keys & Secrets table, check the Unique Identifier column. |
|
Optional |
The data that needs to be signed.
|
|
Optional |
Denotes the file path to the data that needs to be signed. Specified by the
|
|
Optional |
Denotes the type of data specified by the message or
message-file/messageFile argument - RAW or
DIGEST . The Default value is RAW |
|
Optional |
Digital Signature Algorithm Supported algorithms are
Default: |
|
Optional |
Path to the file where the received signed data should be written to. If this option is provided, the output will
be:
If this option is not provided, the output will
be:
|
JSON Example
- Generate JSON input for the
okv crypto data sign
command.okv crypto data sign --generate-json-input
The generated input appears as follows:
{ "service": { "category": "crypto", "resource": "data", "action": "sign", "options": { "uuid": "#VALUE", "message" : "#VALUE", "messageFile" : "#VALUE", "messageType" : "#RAW|DIGEST", "digitalSignatureAlgorithm" : "#RSASSA_PKCS1_v1_5_SHA256|RSASSA_PKCS1_v1_5_SHA384|RSASSA_PKCS1_v1_5_SHA512", "signatureData": "#VALUE" } } }
- Save the generated input to a file (for example,
key_sign.json
) and then edit it to include the sign settings that you want. For example:{ "service": { "category": "crypto", "resource": "data", "action": "sign", "options": { "uuid": "2359E04F-DA61-4F7C-BF9F-913D3369A93A", "message" : "Example message to sign", "messageType" : "RAW", "digitalSignatureAlgorithm" : "RSASSA_PKCS1_v1_5_SHA256" } } }
- Run the
okv crypto data sign
command using the generated JSON file.okv crypto data sign --from-json key_sign.json
If "--signature-data/signatureData" is provided, the output will be:
{ "result" : "Success", "value" : { "signatureData" : "12634F979551C19ADAEB69733853ADB41405FF108E479393AF8B82140186F7244A41F7E36BA1129E67453B36297BB91115C4B10B02101AA8068E251B74B7374E975E1E9C1EEACDCB73BAACF4E05359563A8806B49AA9263ECF61A0D4A0769F1CA5C3CEC0B0B8B4F4F470C5E78F01549C04A491CE346916ECC55E5AA6E2EEA42A3909A38A8090C341FAFEE7C1547D7BC4509CDC65728729011F4301DFB105CF2A0F6B1799D4B9B29667789E6EA1A4319D14E7B92BBC2E68F3DB20CA8B8270FC20C272F638202F3D68248B7AF12750C2A22DF159886AC2456DBAA4CC94A90A064D771106619C103DCCC66C0815FA9FF3349A03E0E3D9696984E6A826EAA507C32F" } }
Parent topic: Cryptographic Commands
6.4 okv crypto data sign-verify Command
The okv crypto data sign-verify
command performs a
signature verification operation on the given signature data and message file using the Oracle
Key Vault managed security object that is within the Oracle Key Vault server, and returns
whether or not the signature is valid.
Required Authorization
The endpoint must have read permission on the public key used for signature verification.
Syntax
okv crypto data sign-verify --uuid <UUID> --message-file <filePath> --message <message> --signature-data <filePath> --digital-signature-algorithm <digitalSignAlgoritm> --text_output TEXT
JSON Input File Template
{ "service": { "category": "crypto", "resource": "data", "action": "sign-verify", "options": { "uuid": "#VALUE", "message" : "#VALUE", "messageFile" : "#VALUE", "messageType" : "#RAW|DIGEST", "signatureData" : "#VALUE", "digitalSignatureAlgorithm" : "#RSASSA_PKCS1_v1_5_SHA256|RSASSA_PKCS1_v1_5_SHA384|RSASSA_PKCS1_v1_5_SHA512|RSASSA_PSS_SHA256|RSASSA_PSS_SHA384|RSASSA_PSS_SHA512" } } }
Parameters
Parameter/Template Parameter | Required? | Description |
---|---|---|
|
Required |
Universally unique ID (UUID) of the key to use for the signature verify. To find the unique identifier for the object, in the Oracle Key Vault management console, click the Keys & Wallets tab, and then click Keys & Secrets in the left navigation window. In the Keys & Secrets table, check the Unique Identifier column. |
|
Optional |
The data that is passed to the signing operation (for the algorithms requiring the
original data to verify a signature). Either |
|
Optional |
Specifies the file path to the data that is passed to the signing
operation (for the algorithms requiring the original data to verify a signature).
Denotes the file path to the data that needs to be signed. Specified by the
message-file or messageFile argument.
|
|
Optional |
Denotes the type of data specified by the message or
message-file/messageFile argument - RAW or
DIGEST .
|
|
Required |
Denotes the file path to the signature that needs to be verified. |
|
Optional |
Digital Signature of the algorithm. |
--output_format |
Optional |
Provides the output format. |
JSON Example
- Generate JSON input for the
okv crypto data sign-verify
command.okv crypto data sign-verify --generate-json-input
The generated input appears as follows:
{ "service": { "category": "crypto", "resource": "data", "action": "sign-verify", "options": { "uuid": "#VALUE", "message" : "#VALUE", "messageFile" : "#VALUE", "messageType" : "#RAW|DIGEST", "signatureData" : "#VALUE", "digitalSignatureAlgorithm" : "#RSASSA_PKCS1_v1_5_SHA256|RSASSA_PKCS1_v1_5_SHA384|RSASSA_PKCS1_v1_5_SHA512" } } }
- Save the generated input to a file (for example,
key_sign-verify.json
) and then edit it to include the decryption settings that you want. For example:{ { "service": { "category": "crypto", "resource": "data", "action": "sign-verify", "options": { "uuid": "2359E04F-DA61-4F7C-BF9F-913D3369A93A", "message" : "Example message to sign", "messageType" : "RAW", "signatureData": "/tmp/signature_data", "digitalSignatureAlgorithm" : "RSASSA_PKCS1_v1_5_SHA256" } } }
- Run the
okv crypto data sign-verify
command using the generated JSON file.okv crypto data sign-verify --from-json key_sign-verify.json
Output similar to the following appears:
{ "result" : "Success", "value" : { "validityIndicator" : "VALID" } }
Example
The following example shows how to use openssl to verify signature generated by
okvutil sign
command.
- openssl does not support verification of signatures in HEX format. As the signature
generated by okvutil sign command is in HEX format therefore the signature can be
converted into binary format using xxd or some other
utility.
xxd -r -p /tmp/signature_data > /tmp/signature_data.bin
- Verify signature of a message stored in file message.txt, using signature in binary
format stored in /tmp/signature_data.bin and public key stored in file
key.pub.
openssl dgst -sha256 -verify key.pub -signature /tmp/signature_data.bin message.txt Verified OK
Parent topic: Cryptographic Commands