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

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
--uuid / uuid 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 Keys & Wallets, then Keys & Secrets in the left navigation pane. Check the Unique Identifier column.
--data / data Required File path to the plaintext data that needs to be encrypted.
--block-cipher-mode / blockCipherMode Optional Block cipher mode. Supported values are:

- CBC (cipher block chaining)
- CFB (cipher feedback)
- ECB (electronic codebook)
- GCM (Galois/counter)
- OFB (output feedback)

If omitted, Oracle Key Vault uses the cryptographic parameters associated with the key. If GCM is used, specify --authenticated-encryption-tag.
--padding / padding Optional Padding mode. Supported values are:

- NONE
- ZEROS
- PKCS5

If omitted, Oracle Key Vault uses the cryptographic parameters associated with the key.
--random-iv / randomIV Optional Indicates whether Oracle Key Vault should generate a random initialization vector (IV). Supported values are:

- TRUE
- FALSE (default)

randomIV is used only if no IV is provided. If randomIV is TRUE, Oracle Key Vault generates a random IV for the encryption operation.
--iv / iv Optional File path of the IV to use for the encryption operation. If you provide an IV during encryption, use the same IV when running okv crypto data decrypt.
--authenticated-encryption-additional-data / authenticatedEncryptionAdditionalData Optional File path of the authenticated encryption additional data (AEAD) to use for the encryption operation. If provided during encryption, supply the same file when running okv crypto data decrypt.
--data-format / dataFormat Optional Format of the data in the input and output files. If omitted, data is read and written as binary. Supported values are:

- HEX
- BASE64
--encrypted-data / encryptedData Required File path where the encrypted data is written. The output file must already exist. If it exists, it is overwritten with the encrypted data.
--iv-out / ivOut Optional File path where the response IV is written. The output file must already exist. If it exists, it is overwritten. The IV is returned only when iv is not provided and randomIV is TRUE. If iv is provided, Oracle Key Vault ignores ivOut. Use this IV when running okv crypto data decrypt.
--authenticated-encryption-tag / authenticatedEncryptionTag Optional File path where the response authenticated encryption tag is written. The output file must already exist. If it exists, it is overwritten. Use the generated authentication tag when decrypting the ciphertext with okv crypto data decrypt.

JSON Example

  1. Generate JSON input for the okv crypto data decrypt command:

    okv crypto data decrypt --generate-json-input

    The generated JSON input is displayed as shown in the earlier section JSON Input File Template.

  2. 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"
    }
  }
}

  3. 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"
  }
}

okv crypto data encrypt

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
--uuid / uuid 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.

--data / data Required File path to the plaintext data that needs to be encrypted
--block-cipher-mode / blockCipherMode Optional

Block Cipher Mode. Values are as follows:

  • CBC for cipher block chaining
  • CFB for cipher feedback
  • ECB for electronic codebook
  • GCM for Galois/counter
  • OFB for output feedback

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.
--padding / padding Optional

Padding. Values are as follows:

  • NONE
  • ZEROS
  • PKCS5

If you omit this setting, then Oracle Key Vault uses the cryptographic parameters that are associated with the key.
--random-iv / randomIV Optional

Indicates whether the Oracle Key Vault server should use random initialization vector (IV). Values are as follows:

  • TRUE
  • FALSE (default)

Oracle Key Vault uses the randomIV value only when the IV is not provided in the input for this command. If you omit the IV and if randomIV is set to TRUE in the input, then Oracle Key Vault uses a random IV for the encrypt operation.

--iv / iv Optional

File path of the IV to use for the encrypt operation.

If you include the IV file path in the okv crypto data encrypt command, and when you run okv crypto data decrypt, use this IV file path.

--authenticated-encryption-additional-data / authenticatedEncryptionAdditionalData 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 okv crypto data encrypt command, and when you run okv crypto data decrypt, use this authenticated encryption file path.

--data-format / dataFormat 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:

  • HEX
  • BASE64
--encrypted-data / encryptedData 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.
--iv-out / ivOut 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 ivOut only when iv is not provided and randomIV is set to true in the input. If iv is provided in the input, then Oracle Key Vault ignores the ivOut parameter.

If you include the response IV file path in the okv crypto data encrypt command, and when you run okv crypto data decrypt, use this response IV file path.

--authenticated-encryption-tag / authenticatedEncryptionTag 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 okv crypto data encrypt command, and when you run okv crypto data decrypt, use this response authenticated encryption tag file path.

JSON Example

  1. Generate JSON input for the okv crypto data encrypt command:

    okv crypto data encrypt --generate-json-input

    The generated JSON input is displayed as shown in the earlier section JSON Input File Template.

  2. 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"
    }
  }
}

  3. 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.

okv crypto data sign

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
--uuid / uuid 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.
--message / message Optional The data that needs to be signed.

- If message type is DIGEST, it should be HEX.
- If message type is RAW, it can be any type.
- Either --message/message or --message-file/messageFile options are required.
--message-file / messageFile Optional Denotes the file path to the data that needs to be signed. Specified by the message-file or messageFile argument. Either --message/message or --message-file/messageFile options is required
--message-type / messageType Optional Denotes the type of data specified by the message or message-file/messageFile argument - RAW or DIGEST. The Default value is RAW
--digital-signature-algorithm / digitalSignatureAlgorithm Optional Digital Signature Algorithm Supported algorithms are

- RSASSA_PKCS1_v1_5_SHA256
- RSASSA_PKCS1_v1_5_SHA384
- RSASSA_PKCS1_v1_5_SHA512
- RSASSA_PSS_SHA256
- RSASSA_PSS_SHA384
- RSASSA_PSS_SHA512

Default: RSASSA_PKCS1_v1_5_SHA256
--signature-data / signatureData Optional Path to the file where the received signed data should be written to. If this option is provided, the output will be:

{
"result" : "Success"
}

If this option is not provided, the output will be:

{
"result" : "Success",
"value" : {
"signatureData" : "3258D33DFB12F97....86419A35F32BA903ADDEB3"
}
}

JSON Example

  1. Generate JSON input for the okv crypto data sign command:

    okv crypto data sign --generate-json-input

    The generated JSON input is displayed as shown in the earlier section JSON Input File Template.

  2. 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"
    }
  }
}

  3. 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"
  }
}

okv crypto data sign-verify

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
--uuid / uuid 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.

--message / message Optional The data that is passed to the signing operation (for the algorithms requiring the original data to verify a signature). Either --message/message or --message-file/messageFile options is required
--message-file / --messageFile 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.
--message-type / messageType Optional Denotes the type of data specified by the message or message-file/messageFile argument - RAW or DIGEST.
--signature-data / signatureData Required Denotes the file path to the signature that needs to be verified.
--digital-signature-algorithm / digitalSignatureAlgorithm Optional Digital Signature of the algorithm.
--output_format Optional Provides the output format.

JSON Example

  1. Generate JSON input for the okv crypto data sign-verify command:

    okv crypto data sign-verify --generate-json-input

    The generated JSON input is displayed as shown in the earlier section JSON Input File Template.

  2. 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"
    }
  }
}

  3. 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.

  1. 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

  2. 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