1. RESTful Services Administrator's Guide
  2. Cryptographic Commands

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

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

--uuid / uuid

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.

--data / data

Required

File path to the ciphertext data that needs to be decrypted

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

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

--iv / iv

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.

--authenticated-encryption-additional-data / authenticatedEncryptionAdditionalData

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.

--authenticated-encryption-tag / authenticatedEncryptionTag

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.

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

--decrypted-data / decryptedData

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

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

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

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

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

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

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

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

--message-file/messageFile

Required

Denotes the file path to the data that needs to be signed. Specified by the message-file or messageFile argument.

--message-type/messageType

Required

 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 of the algorithm.

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

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

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

Required

The data that is passed to the signing operation (for the algorithms requiring the original data to verify a signature).

--message-file / --messageFile

Required

 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. the value can be either --signature-data or signatureData.

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

Parent topic: Cryptographic Commands