Cryptographic Operations
The XML Interface enables you to:
Generate a random byte sequence (see RandGenRequest).
Request a cryptographic operation (see CryptoRequest). The interface enables you to perform the following operations: encryption, decryption, MAC, MAC verification, SIGN, and SIGN verification. You can send data in multiple or single chunks, and batch requests.
When submitting a CryptoRequest you must send the data in one of four elements:
Data
Base64Data
DataSingle
Base64DataSingle
See The Data Elements to learn how to construct data elements. The results of most operation are returned in binary. The exception is the FPE encryption and FPE decryption operations, whereby results are returned in ASCII characters.
RandGenRequest
Return a random number of a given size.
<RandGenRequest>
<ID>...</ID>
<Size>...</Size>
</RandGenRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Size | Specifies the number of random bytes to generate (in bytes). Must be a positive integer between 1 and 131072 (inclusive). |
RandGenResponse
Server response to RandGenRequest.
When the request was successful, the RandGenResponse is following by a Data element.
<RandGenResponse>
<ID>...</ID>
<Success>true</Success>
</RandGenResponse>
<Data>
<Size>...</Size>BINARY_DATA_OF_SPECIFIED_SIZE
<Size>...</Size>BINARY_DATA_OF_SPECIFIED_SIZE
</Data>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates whether the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the Data element described below. When the operation is unsuccessful, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
| Data | In a successful random number generation response, the Data section contains the random byte chunks, each chunk preceded by the Size element, which specifies the size, in bytes, of the following data chunk. Size is a positive integer with a value less than 8024. The total size of all chunks should match the requested size. |
Generating Random Bytes
Request
<RandGenRequest>
<ID>XMLID671</ID>
<Size>5</Size>
</RandGenRequest>
Response
<RandGenResponse>
<ID>XMLID671</ID>
<Success>true</Success>
</RandGenResponse>
<Data>
<Size>5</Size>
ì5Ã
</Data>
CryptoRequest
Performs a cryptographic operation.
This request performs nearly all cryptographic work for the CipherTrust Manager, and therefore has many possible variations. See Examples of Cryptographic Requests and Responses for demonstrations of CryptoRequest construction for common operations. See Supported Key Algorithms for background on supported cryptographic algorithms.
A cryptographic request must be followed by one of the four data elements, which contain the data to be operated on: Data, Base64Data, DataSingle, and Base64DataSingle.
<CryptoRequest>
<ID>...</ID>
<Operations>
<Operation>...</Operation>
<KeyName>...</KeyName>
<Charset>...</Charset>
<KeyVersion>...</KeyVersion>
<WithAllActiveVersions/>
<Algorithm>...</Algorithm>
<IV>...</IV> #for DESede, AES CBC, or AES GCM operations
<TagLen>...</TagLen> #optional, available for AES/GCM only
<Send/> # optional
<Operation>...</Operation>
<KeyName>...</KeyName>
<Algorithm>...</Algorithm>
<EphemeralPubKey>...</EphemeralPubKey> #optional, available for EC decryption only
<MacData>.....</MacData> #optional, available for EC decryption only
...
<SaltLength>...</SaltLength> #optional, available for RSA Sign/Verify
</Operations>
<Base64/> # optional
</CryptoRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Operations | Specifies the operations to perform on the data in the data section of the request. Every operation is defined by the Operation, KeyName, and Algorithm elements. The IV element is required for DESede, AES CBC, and AES GCM encryptions, either in the request header or the data section, and its usage depends on the operation being performed. When the Operations element contains instructions for multiple procedures, the server performs the initial operation on the data in the data section, and all subsequent operations on the result of the previous operation in the sequence. |
| Operation | Specifies the operation to perform on the data. Possible values are: • ENCRYPT: Encrypt the data. The following algorithms, when used in CBC mode, require a random IV byte array for initialization - DESede and AES. • DECRYPT: Decrypt the data. As noted above, DESede and AES require the IV element when used in CBC mode. To successfully decrypt data encrypted with these algorithms, the client must pass the IV used to encrypt the data. • MAC: Mark the data chunk with a message authentication code (MAC) key. The server supports SHA1 HMAC, which returns a 20-byte array. • MACV: Verify a chunk of data that is signed with a MAC key. This operation returns only one byte: 1 if the MAC is verified; 0 if the MAC is not verified. For this operation, the client must pass the previously calculated, hex-encoded MAC in the IV element and the text to be verified in the Data section. • SIGN: Return a digital signature (no data is returned in a sign operation). The server supports RSA signatures. • SIGNV: Verify a signature. This operation returns only one byte: 1 if the signature is verified; 0 if the signature is not verified. For this operation, the client must pass the previously calculated, hex-encoded signature in the IV element and the text to be verified in the Data section. |
| KeyName | Specifies the name of a cryptographic key on the NAE Server. The KeyName element is a required part of the operation specification for all operations except HASH operations. All algorithms use keys of the same algorithm type (for example, 3DES algorithms use 3DES keys). |
| Charset | Specifies the name or ID of the character set on the NAE server. The Charset is required for FPE/AES/UNICODE. It is required for the FPE algorithm only. Note: It is recommended not to use the predefined "All Printable ASCII" charset as it also contains some non-printable ASCII characters. For printable ASCII charset, create a custom charset in the range "0021-007E". |
| KeyVersion | Specifies the key version to use. |
| WithAllActiveVersions | The data will be encrypted with all of the active versions of the key. Used only for versioned keys. |
| Algorithm | Contains a standard identifier string for a cryptographic algorithm supported by the server. |
| IV | The IV element contains an initialization vector (IV) for DESede, AES CBC, and AES GCM operations. An IV is a sequence of random bytes appended to the front of the plaintext before encryption by a block cipher. Using an IV eliminates the possibility that the initial ciphertext block will be the same for any two encryption operations that use the same key. Optionally, you can include the IV element in the data section, rather than in the header. This may be more useful in the case of request batching, where a single request may be used for multiple data segments. See Batching Requests for more information. The specific requirements and format for this element depend on the algorithm and operation selected. AES and DESede IV is not allowed for ECB mode. IV is required for CBC and GCM modes. The length of the IV is eight bytes for DESede, sixteen bytes for AES/CBC, and between one and sixteen bytes for AES/GCM. In accordance with NIST SP800-38D, a 12 byte IV is recommended for AES/GCM. Because the client must pass the IV element to the server as a HEX-encoded ASCII (base 16 encoded) string, an eight byte binary string would be represented as a sixteen byte HEX-encoded ASCII string. Both capital and lower-case letters are allowed in HEX encoding. SIGNV Operations The IV element contains a hex-encoded signature value to be verified and not an actual IV. MACV Operations The IV element contains a hex-encoded MAC to be verified and not an actual IV. For FPE/AES/UNICODE, refer to the link to know about IV size. |
| TagLen | This element is available for AES/GCM only, and is optional. You can specify a tag length between 4 and 16 bytes. If you do not specify a tag length, the server will return an authentication tag that is 16 bytes long. |
| Send/ | The Send element instructs the server to include the results of the previous operation in its response to the client. For example, if your Operations element contains instructions for multiple operations, inserting Send after an Operation, KeyName, Algorithm, IV set, instructs the server to return the results of this individual operation in addition to the results of the last operation. If the Send element is not used, the server sends only the result of the last operation in the chain. |
| Base64/ | The Base64/ element instructs the server to return Base64 data. If the Base64/ element is not used, the server returns binary data, regardless of whether the client sent Base64 or binary data. |
| EphemeralPubKey | Generated EphemeralPubKey from encryption is used in EC decryption. |
| MacData | Generated MacData from encryption is used in EC decryption. |
| SaltLength | Used to pass the length of the Salt for Sign and Verify operations (with RSA keys only) in the following algorithms:• SHA1withRSA/PSSPadding • SHA256withRSA/PSSPadding • SHA384withRSA/PSSPadding • SHA512withRSA/PSSPadding • RSA/PSSPaddingSHA1 • RSA/PSSPaddingSHA256 • RSA/PSSPaddingSHA384 • RSA/PSSPaddingSHA512 The SaltLength tag is optional. If this tag is not provided, the default length is computed based on the maximum length of the Hash algorithm (in Bytes).Possible Values: • Any positive integer From 1 to maximum length. Note:Maximum supported value of Salt Length = (Key length in bytes - HASH length in byte - 2) • HASH-EQUAL-LENGTH It is equivalent to openssl -1 flag. This means that Salt Length is equal to Hash Algorithm length in bytes. • MAX-LENGTH It is equivalent to openssl -2 flag. This means that maximum salt length depends on the algorithm in use. Note: If the combination of key, operation, and algorithm is not as mentioned above, then the provided SaltLength will be ignored. |
Example of the Send Element
When a request contains a series of Operation, KeyName, Algorithm, and IV elements, the server's response includes only the results of the last operation. For example, for the request below, the server would return only the MAC of the encrypted data, not the encrypted data itself.
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
<Operation>MAC</Operation>
<KeyName>MACKey</KeyName>
<Algorithm>HmacSHA1</Algorithm>
</Operations>
To view the results of both operations, you can include a send element between the Operation, KeyName, Algorithm, IV sets. If you were to add the send element to our example, as shown below, the server would return the encrypted binary data and the MAC.
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
<Send/>
<Operation>MAC</Operation>
<KeyName>MACKey</KeyName>
<Algorithm>HmacSHA1</Algorithm>
</Operations>
Example of the Base64/ Element
The following code shows a CryptoRequest that requests that the resulting data be returned in Base64-encoded format.
<CryptoRequest>
<Version>1.1</Version>
<ID>3JALD8EJIF</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
</Operations>
<Base64/>
</CryptoRequest>
<Base64Data>
<Size>16</Size>BASE64_DATA_OF_SIZE_16
</Base64Data>
See Examples of Cryptographic Requests and Responses for demonstrations of CryptoRequest construction for common operations.
The Data Elements
The data section of the cryptographic request follows the request header, though there can be whitespace between them. You can send the data in binary or Base64-encoded format for all operations. You can send data in multiple, or single chunks.
Breaking data into multiple chunks allows the client to start sending data even if the total input size is not yet known. It also allows the server to start sending the response data back without waiting for all of the input data. If you have small amounts of data to encrypt, if you are receiving your data in small chunks, or if the data you are encrypting is greater than or equal to 3500 bytes, use the Data or the Base64Data element to send your data in multiple chunks.
Sending data in a single chunk, enables the server to operate on the data more efficiently than it could with multiple chunks, resulting in faster performance. The single chunk must be smaller than 3500 bytes. If you have a single chunk of data to encrypt (for example, a buffer), use the DataSingle or the Base64DataSingle element to send your data in a single chunk.
Sending Data in Multiple Chunks
To send your data in multiple chunks, you would use the Data element for binary data (ASCII encoded data for FPE encryption or decryption) , or the Base64Data element for Base64-encoded data.
When binary data is sent in multiple chunks, the server receives the data from the client, assembles the chunks, and treats them as one byte array for the purposes of the requested cryptographic operation. (When Base64-encoded data is sent, the server first converts them to binary and then follows the same procedure.)
The format of the Data element is shown below:
<Data>
<Message>...</Message> # optional
<IV>...</IV>
<AuthTag>...</AuthTag> #for AES/GCM decrypt only
<AADSize>...</AADSize> #for AES/GCM only, optional
<TweakData>...</TweakData> #for FPE only, optional
<TweakAlgorithm>...<TweakAlgorithm> #for FPE only, optional
<Size>...</Size>BINARY_DATA
<MacData>.....</MacData> #optional, available for EC decryption only
...
</Data>
The format of the Base64Data element is shown below:
<Base64Data>
<Message>...</Message> # optional
<IV>...</IV>
<AuthTag>...</AuthTag> #for AES/GCM Decrypt only
<AADSize>...</AADSize> #for AES/GCM only, optional
<TweakData>...</TweakData> #for FPE only, optional
<TweakAlgorithm>...<TweakAlgorithm> #for FPE only, optional
<Size>...</Size>BASE64DATA
<MacData>.....</MacData> #optional, available for EC decryption only
...
</Base64Data>
| Element | Description |
|---|---|
| Message | Includes a message that will be logged in the CipherTrust Manager's Activity log. Messages cannot contain new lines or angle brackets and must be less than 1024 bytes. |
| IV | Specifies the IV that will be applied to the data for this operation. For algorithms that require an IV, the IV element must be included in either the CryptoRequest or the data element. If an IV is included in both elements, the server applies the value given here. For FPE/AES/UNICODE, refer to the link to know about IV size. |
| AuthTag | Available and required for AES/GCM decrypt operations only. This is a HEX encoded authentication tag created when the data is first encrypted with AES/GCM. |
| AADSize | Available for AES/GCM operations only, and optional. Enter the size of the additional authenticated data (AAD) followed by the AAD itself. There is a 10240 byte length limit on AAD. The AAD must be the same format as the payload data associated with the Size tag. Additional authenticated data is not encrypted, but is associated with an authentication tag (AuthTag). Note that the CryptoResponse does not include this element. Therefore, to construct a message with AAD, store the AAD client-side and bind the CryptoResponse Data with the stored AAD. |
| TweakData | Available for FPE algorithm only. Providing tweak data for FPE encryption or decryption is optional but highly recommended. The tweak data is a string which transforms the provided encryption key for an added level of security. If you include tweak data in both the CryptoRequest and the Data element, FPE will use the tweak data in the Data Element. This element accepts a 16 character (64 bit) HEX encoded value if the TweakAlgorithm is absent or set to "None", or an ASCII value of fewer than 257 characters if the TweakAlgorithm is set to "SHA1" or "SHA256". |
| TweakAlgorithm | Available for FPE algorithm only. This element allows you to hash tweak data provided as an ASCII string fewer than 257 characters with one of two algorithms. This element transforms the tweak data to the correct length and format, a 16 character (8 byte) HEX encoded value, which allows you more flexibility in the tweak data you can provide. This element accepts the values "None" "SHA1" or "SHA256". An absent TweakAlgorithm is interpreted as a value of "None". |
| Size | Specifies the size, in bytes, of the data being sent to the server. This is a positive number, represented in decimal notation. The value can be anything up to 263, but for best performance we recommend values of less than 1048576 (2^20). The actual data follows immediately after the Size element, with no whitespace in between. You can send multiple data chunks by including multiple Size elements. Normally, the client is not required to chunk data into multiples of the algorithm's block size, although it is more efficient for the server. However, when using "no padding algorithms", the client must chunk the data to a multiple of the block size, otherwise an error will occur. For AES/GCM encryption or decryption with AAD only, set a size of zero and do not add trailing data. |
| MacData | Generated MacData from encryption is used in EC decryption. |
Example of a Data Element
Here's an example of a valid data section:
<Data>
<Message>Here is a message</Message>
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>117</Size>BINARY_DATA_OF_SIZE_117
</Data>
Example of a Base64Data Element
Another example using the Base64Data tag this time:
<Base64Data>
<Size>1024</Size>BASE64_DATA_OF_SIZE_1024
<Size>112</Size>BASE64_DATA_OF_SIZE_112
</Base64Data>
Sending Data as a Single Chunk
To send your data in a single chunk, you would use the DataSingle element for binary data, or the Base64DataSingle element for Base64-encoded data.
The format of the DataSingle element is shown below:
<DataSingle>
<Message>...</Message> # optional
<IV>...</IV> # optional
<AuthTag>...</AuthTag> #for AES/GCM Decrypt only
<AADSize>...</AADSize> #for AES/GCM only, optional
<TweakData>...</TweakData> #For FPE only, optional
<TweakAlgorithm>...<TweakAlgorithm> #For FPE only, optional
<Size>...</Size>BINARY_DATA
<MacData>.....</MacData> #optional, available for EC decryption only
</DataSingle>
The format of the Base64DataSingle element is shown below:
<Base64DataSingle>
<Message>...</Message> # optional
<IV>...</IV> # optional
<AuthTag>...</AuthTag> #for AES/GCM Decrypt only
<AADSize>...</AADSize> #for AES/GCM only, optional
<TweakData>...</TweakData> #For FPE only, optional
<TweakAlgorithm>...<TweakAlgorithm> #For FPE only, optional
<Size>...</Size>BASE64DATA
<MacData>.....</MacData> #optional, available for EC decryption only
</Base64DataSingle>
| Element | Description |
|---|---|
| Message | Includes a message that will be logged in the CipherTrust Manager's Activity log. Messages cannot contain new lines or angle brackets and must be less than 1024 bytes. |
| IV | Specifies the IV that will be applied to the data for this operation. For algorithms that require an IV, the IV element must be included in either the CryptoRequest or the Data element. If an IV is included in both elements, the server applies the value given here. For FPE/AES/UNICODE, refer to the link to know about IV size. |
| AuthTag | Available and required for AES/GCM decrypt operations only. This is a HEX encoded authentication tag created when the data is first encrypted with AES/GCM. |
| AADSize | Available for AES/GCM operations only, and optional. Enter the size of the additional authenticated data (AAD) followed by the AAD itself. There is a 10240 byte length limit on AAD. The AAD must be the same format as the payload data associated with the Size tag. Additional authenticated data is not encrypted, but is associated with an authentication tag (AuthTag). Note that the CryptoResponse does not include this element. Therefore, to construct a message with AAD, store the AAD client-side and bind the CryptoResponse Data with the stored AAD. |
| TweakData | Available for FPE algorithm only. Providing tweak data for FPE encryption or decryption is optional but highly recommended. The tweak data is a string which transforms the provided encryption key for an added level of security. If you include tweak data in both the CryptoRequest and the Data element, FPE uses the tweak data in the Data element. CryptoRequest and the Data element, FPE will use the tweak data in the Data Element. This element accepts a 16 character (64 bit) HEX encoded value if the TweakAlgorithm is absent or set to "None", or an ASCII value of fewer than 257 characters if the TweakAlgorithm is set to "SHA1" or "SHA256". |
| TweakAlgorithm | Available for FPE algorithm only. This element allows you to hash tweak data provided as an ASCII string fewer than 257 characters with one of two algorithms. This element transforms the tweak data to the correct length and format, a 16 character (8 byte) HEX encoded value, which allows you more flexibility in the tweak data you can provide. This element accepts the values "None" "SHA1" or "SHA256". An absent TweakAlgorithm is interpreted as a value of "None". |
| Size | Specifies the size, in bytes, of the data being sent to the server. This is a positive number, represented in decimal notation. The value must be less than 3500 bytes. The actual data follows immediately after the Size element, with no whitespace in between. You can only include one Size element. For AES/GCM encryption or decryption with AAD only, set a size of zero and do not add trailing data. |
| MacData | Generated MacData from encryption is used in EC decryption. |
Batching Requests
If you are using the same cryptographic request-that is, the same key, algorithm or operations-for multiple sets of data, you can optimize server performance by batching those requests. Batching enables you to use the same cryptographic request header with multiple data sections in a single request.
Note that in request batching each data section is encrypted separately using the information in the CryptoRequest header, in other words, each data section has its own encryption context. This is different from a regular non-batched cryptographic request; in that case even if you have split your data into multiple segments (using the Data or Base64Data tags) each data segment uses the same encryption context. Note also that you cannot batch MAC or Signing operations, or any chained operations.
To batch a data request, use a CryptoRequest header as usual, and then use the Batch element to enclose the data elements. You can batch any of the data types (base 64 or binary data, sent as a single call or in chunks). Each data segment can use its own initialization vector with the IV element. For FPE operations, each data segment can contain optional TweakData and TweakAlgorithm elements. Also, for each EC operations, each data segment can contain MacData (for decrypt only) and IV (for both encrypt and decrypt) elements. For each Data element included in the request, the server will return one Data element in the response. For example, the request below batches three decryption requests, two with binary data and one with base 64 data.
<CryptoRequest>
<ID>A38JDSL932</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
<EphemeralPubKey>...</EphemeralPubKey> #optional, available for EC decryption only
</Operations>
</CryptoRequest>
<Batch>
<Data>
<IV>1234123412341234</IV>
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>560</Size>BINARY_DATA_OF_SIZE_560
<MacData>.....</MacData> #optional, available for EC decryption only
</Data>
<Data>
<IV>1234123412341234</IV>
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>105</Size>BINARY_DATA_OF_SIZE_105
<MacData>.....</MacData> #optional, available for EC decryption only
</Data>
<Base64Data>
<IV>1234123412341234</IV>
<Size>1024</Size>BASE64_DATA_OF_SIZE_1024
<Size>1024</Size>BASE64_DATA_OF_SIZE_1024
<Size>1024</Size>BASE64_DATA_OF_SIZE_1024
<Size>117</Size>BASE64_DATA_OF_SIZE_117
<MacData>.....</MacData> #optional, available for EC decryption only
</Base64Data>
</Batch>
In this case, the server would return three separate Data elements.
Reading the Cryptographic Response
A cryptographic response actually consists of two parts: a CryptoResponse element, which indicates the success or failure of the requested operation, and the actual data (if successful).
If the cryptographic request fails, the server can indicate an error in either the response header or the data section, depending on when the failure occurred. If there was a problem with the request header, a reference to a missing key for example, then the server will include an error message in the response header and no data section will be sent. If there was a problem with the data sent from the client, a corrupt data chunk, then the server will return a successful CryptoResponse, but include an error message in the response data section.
Note
The server can send multiple Data sections successfully, and then send an error.
CryptoResponse
Server response to CryptoRequest.
If the requested cryptographic operation was successful, the response header is a valid XML document with the following form:
<CryptoResponse>
<ID>...</ID>
<Success>true</Success>
</CryptoResponse>
Unsuccessful responses have the following form:
<CryptoResponse>
<ID>...</ID>
<Success>false</Success>
<FatalError>...</FatalError> # Or <NonFatalError>
<ErrorString>...</ErrorString>
<OperationIndex>...</OperationIndex>
<Operations>
...
</Operations>
</CryptoResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates whether the operation was successful. true indicates success. false indicates failure. When the operation is successful, the resulting data is included in the Data element.When the operation is unsuccessful, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. It also contains the OperationIndex and Operations elements defined below. For a list of possible error IDs and strings, see Error Messages. |
| OperationIndex | Contains the index of the operation that caused the error. The first operation in the chain would have an operation index of one; the second operation in the chain would have an index of two, and so on. |
| Operations | Contains the Operation, Algorithm, and KeyName elements from the cryptographic request. |
The Returned Data
In case of a successful operation, a cryptographic response data section has the following form:
<Data>
<AuthTag>...</AuthTag> #Only returned for AES/GCM encrypt
<Size>...</Size>BINARY_DATA
<Send/> # Optional. Used only if the client used <Send/>.
<Size>...</Size>BINARY_DATA
... # More chunks
</Data>
<EphemeralPubKey>....</EphemeralPubKey> #Optional applicable for EC encryption only
<MacData>.....</MacData> #optional, only returned for EC encrypt
Data sections that contain an error have the following form:
<Data>
...
<Size>...</Size>BINARY_DATA_OF_SPECIFIED_SIZE
<FatalError> # Or NonFatalError
<ErrorString>...</ErrorString>
<OperationIndex>...</OperationIndex>
</Data>
| Element | Description |
|---|---|
| AuthTag | Only returned for AES/GCM encryption. This authentication tag is created for the encryption data and additional authenticated data. The authentication tag is necessary to access the data for decryption. |
| Size | Specifies the size, in bytes, of the data being sent from the server. The actual data follows immediately after the Size element, with no whitespace in between. The client is required to reassemble the binary chunks and treat them as one byte array for the purposes of the requested cryptographic operations. The server is not required to preserve chunk structure in the response. For instance, the server is free to include the encryption of many client request data chunks in one server response data chunk. If no data is sent in the CryptoRequest, which occurs when you perform AES/GCM encryption or decryption operations on AAD only, this size element is absent. |
| Send/ | Indicates the end of the intermediate result requested when the client includes the Send/ element in the cryptographic request. The end of the intermediate result always coincides with the end of the chunk. This means that, after sending the intermediate result, the server completes the current chunk, writes a Send/ element, and then starts a new chunk. |
| FatalError | Contains the error ID for any fatal error that occurred when the data was transmitted. A fatal error is one that will close the connection. |
| NonFatalError | Contains the error ID for any non-fatal error that occurred when the data was transmitted. A non-fatal error will not close the connection. |
| ErrorString | Contains the textual description of any error that occurred when the data was transmitted. |
| OperationIndex | Contains the index of the operation that caused the error. The first operation in the chain would have an operation index of one; the second operation in the chain would have an index of two, and so on. |
| EphemeralPubKey | Response in case of EC encryption. |
| MacData | Response in case of EC encryption. |
Tagged Ciphertext
The ciphertext generated when using versioned keys will contain a leading tag that is used during decryption to identify which key version to use. Client code may treat this tag as simply being part of the ciphertext.
The tag has been designed to be able to support some additional features in future software releases. It consists of a one-byte header followed by optional data elements. The header has a tag format version ID to allow for future changes. It also has a bit field to indicate the presence of the optional data elements. The elements are packed into the tag in the order they appear in the header's bit field. The lengths of the elements following the header are predetermined and fixed.
The tag header has the following format:
| Element | Use |
|---|---|
| 0-2 | Tag format version ID. Currently set to "000". |
| 3 | Key Version ID present if set. Always set to "1". |
| 4 | Reserved for future use. Currently set to "0". |
| 5 | Reserved for future use. Currently set to "0". |
| 6 | Reserved for future use. Currently set to "0". |
| 7 | Reserved for future use. Currently set to "0". |
The data element following the header is the key's version ID. In future releases, there may be additional data elements. The key's version ID field length is 12 bits. It is followed by 4 bits of unused padding (set to "0"), in order to end on a byte boundary.
The total size of the ciphertext header is therefore 3 bytes. Here is graphical representation:
| 01234567 | 012345670123 | 4567 | 01234567...
--------------------------------------------------------------
| | | |
| 00010000 | xxxxxxxxxxxx | 0000 | xxxxxxxxxxxx...
| | | |
--------------------------------------------------------------
header key version ID padding ciphertext
(8 bits) (12 bits) (4 bits)
Examples of Cryptographic Requests and Responses
This section provides examples of cryptographic requests and responses.
See Encrypting and Decrypting for CryptoRequest and CryptoResponse structures which apply to most algorithms.
See Encrypting in AES/GCM mode and Decrypting in AES/GCM mode for examples using tags unique to AES/GCM.
See Encrypting with FPE and Decrypting with FPE for examples using tags unique to FPE.
See Encrypting with FPE/FF3-1 and Decrypting with FPE/FF3-1 for examplesusing tags unique to FPE/FF3-1.
See Encrypting and Creating a MAC and Verifying a MAC for examples of creating and verifying Message Authentication Codes (MACs).
See Creating an Authentication Tag with AES/GCM (GMAC) and Verifying an Authentication Tag with AES/GCM (GMAC Verification)) for examples of the GMAC variant of AES/GCM. GMAC only does authenticated work and does not encrypt plaintext data.
See Encrypting and Creating a Digital Signature and Verifying a Digital Signature for examples of digital signature requests and responses.
See Creating Digital Signature for EC Algorithm and Verifying Digital Signature for EC Algorithm for examples of digital signature requests and responses for EC algorithm.
See Response Header Error: "Invalid or Missing Key Name" and Response Header Error: "Invalid Key/Algorithm Pair" for common response errors.
Encrypting
The following example encrypts a small byte array of a known size with a symmetric cipher.
Request
<CryptoRequest>
<ID>3JALD8EJIF</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<IV>1234123412341234</IV>
<Size>16</Size>BINARY_DATA_OF_SIZE_16
</Data>
Response
<CryptoResponse>
<ID>3JALD8EJIF</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>64</Size>BINARY_DATA_OF_SIZE_64
</Data>
Decrypting
The following example illustrates the decryption of a large chunk of data with a symmetric cipher.
Request
<CryptoRequest>
<ID>A38JDSL932</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<IV>1234123412341234</IV>
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>560</Size>BINARY_DATA_OF_SIZE_560
</Data>
Response
<CryptoResponse>
<ID>A38JDSL932</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>1024</Size>BINARY_DATA_OF_SIZE_1024
<Size>77</Size>BINARY_DATA_OF_SIZE_77
</Data>
Encrypting in AES/GCM mode
The following example illustrates typical Base64 data encryption in AES/GCM mode. A tag length of 10 is specified to generate the authentication tag, and some Additional Authenticated Data is sent with the request.
Note
The CryptoResponse does not return the Additional Authenticated Data. Save any Additional Authenticated Data client-side and add it to the relevant CryptoResponse values.
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>AES_key</KeyName>
<Algorithm>AES/GCM</Algorithm>
<TagLen>10</TagLen>
</Operations>
<Base64/>
</CryptoRequest>
<Base64Data>
<IV>123412341234</IV>
<AADSize>8</AADSize>aGVsbG8=<Size>16</Size>
1234567890123456
</Base64Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data>
<Size>16</Size>
1234567890123456
<AuthTag>8F5D4FFBD4E71D6C56C6</AuthTag>
</Base64Data>
Decrypting in AES/GCM mode
The following example illustrates typical Base64 data decryption in AES/GCM mode. The authentication tag is provided along with all encrypted data and additional authentication data.
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>AES_key</KeyName>
<Algorithm>AES/GCM</Algorithm>
</Operations>
<Base64/>
</CryptoRequest>
<Base64Data>
<IV>123412341234</IV>
<AuthTag>8F5D4FFBD4E71D6C56C6</AuthTag>
<AADSize>8</AADSize>aGVsbG8=
<Size>64</Size>
16AkIeeb7Xbeg06uqHWcB3gSqmWBuagKP3dC0AWBs8YTyP/pUNMuhyQJ1E80Wtue
<Size>64</Size>
f2bBu5zFCVARLY19yYgVpHf+z7xM0uRCqJX1YPUK1PGqQhYYPpdSndBufU8B4sAv
</Base64Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data>
<Size>64</Size>
aGVsbG8gd29ybGQsaGVsbG8gd29ybGQhaGVsbG8gd29ybGQsaGVsbG8gd29ybGQh
<Size>64</Size>
aGVsbG8gd29ybGQsaGVsbG8gd29ybGQhaGVsbG8gd29ybGQsaGVsbG8gd29ybGQh
</Base64Data>
Encrypting with FPE
The following example illustrates how to encrypt with Format Preserving Encryption (FPE) using the optional tags, TweakData, TweakAlgorithm, and Charset that are specific to the algorithm.
FPE/AES/CARD10 Mode
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>AES_Key</KeyName>
<Algorithm>FPE/AES/CARD10</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<TweakData>qwerty123</TweakData>
<TweakAlgorithm>SHA256</TweakAlgorithm>
<Size>16</Size>1234567890123456
</Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>16</Size>7899341944703854
</Data>
FPE/AES/UNICODE Mode
The following example illustrates the encryption of the Unicode data. The charset must be present on the NAE server. Here, we have used Greek charset with HEX code points ranging from 03A3-03B6.
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>AES_Key</KeyName>
<Algorithm>FPE/AES/UNICODE</Algorithm>
<Charset>Greek</Charset>
<Algorithm>FPE/AES/UNICODE</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<Size>10</Size>ΨΥΦΥΣ
</Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>10</Size>γέΤήή
</Data>
Decrypting with FPE
The following example illustrates how to decrypt with Format Preserving Encryption (FPE) using the optional tags, TweakData and TweakAlgorithm, that are specific to that algorithm.
FPE/AES/CARD10 Mode
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>AES_Key</KeyName>
<Algorithm>FPE/AES/CARD10</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<TweakData>qwerty123</TweakData>
<TweakAlgorithm>SHA256</TweakAlgorithm>
<Size>16</Size>7899341944703854
</Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>16</Size>1234567890123456
</Data>
FPE/AES/UNICODE Mode
The following example illustrates the decryption of the Unicode data. The charset must be present on the NAE server. Here, we have used Greek charset with HEX code points ranging from 03A3-03B6.
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>AES_Key</KeyName>
<Algorithm>FPE/AES/UNICODE</Algorithm>
<Charset>Greek</Charset>
<Algorithm>FPE/AES/UNICODE</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<Size>10</Size>γέΤήή
</Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>10</Size>ΨΥΦΥΣ
</Data>
Encrypting with FPE/FF3-1
The following example illustrates how to encrypt with Format Preserving Encryption (FPE) using FF3-1. The TweakData is manadatory for FPE/FF3-1. This element accepts a 14 character(7 byte) HEX encoded value.
Request
<CryptoRequest>
<ID>100004</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>AES_KEY</KeyName>
<Algorithm>FPE/FF3-1/CARD10</Algorithm>
<TweakData>012345678901ab</TweakData>
</Operations>
</CryptoRequest>
<Data>
<Size>8</Size>12345678
</Data>
Response
<CryptoResponse>
<ID>100004</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>8</Size>82288542
</Data>
Decrypting with FPE/FF3-1
The following example illustrates how to decrypt with Format Preserving Encryption (FPE) using FF3-1. The TweakData is manadatory for FPE/FF3-1. This element accepts a 14 character(7 byte) HEX encoded value.
Request
<CryptoRequest>
<ID>100004</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>AES_KEY</KeyName>
<Algorithm>FPE/FF3-1/CARD10</Algorithm>
<TweakData>012345678901ab</TweakData>
</Operations>
</CryptoRequest>
<Data>
<Size>8</Size>82288542
</Data>
Response
<CryptoResponse>
<ID>100004</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>8</Size>12345678
</Data>
Encrypting and Creating a MAC
The following example shows a client's request to encrypt and add an integrity check to the "Hello World!" string. Since there is no Send element, the server will return only the results of the MAC operation.
Request
<CryptoRequest>
<ID>7</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/PKCS5Padding</Algorithm>
<IV>0102030405060708</IV>
<Operation>MAC</Operation>
<KeyName>MACKey</KeyName>
<Algorithm>HmacSHA1</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!
</Data>
Response
<CryptoResponse>
<ID>7</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>20</Size>:´Qõ_ªåíðµÐØ’‰ÉŠ
</Data>
To get the server to send back the original ciphertext, in addition to the MAC operation results, you need to add the Send element after the ENCRYPT operation, as illustrated by this example:
Request
<CryptoRequest>
<ID>8</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
<IV>0102030405060708</IV>
<Send/>
<Operation>MAC</Operation>
<KeyName>MACKey</KeyName>
<Algorithm>HmacSHA1</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!</Data>
Response
<CryptoResponse>
<ID>8</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>16</Size>Z!&ÀM(&àl&{…h]
<Send/>
<Size>20</Size>:´Qõ_ªåíðµÐØ’‰ÉŠ
</Data>
Verifying a MAC
In the example below, the client requests that the server verify a MAC. Notice that the hex-encoded MAC value is contained in the IV element.
Request
<CryptoRequest>
<ID>4</ID>
<Operations>
<Operation>MACV</Operation>
<KeyName>DGMacKey</KeyName>
<Algorithm>HmacSHA1</Algorithm>
<IV>3ab451f55f1501aa06e5edf0b5d0d8921f89c98a</IV>
</Operations>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!</Data>
Response
<CryptoResponse>
<ID>4</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>1</Size>0
</Data>
Creating an Authentication Tag with AES/GCM (GMAC)
There is a variant of GCM, called GMAC, whereby no plaintext data is encrypted into ciphertext, only an authentication tag is generated over Additional Authenticated Data. The following example demonstrates how to use GMAC by sending an AES/GCM encryption request with only Additional Authenticated Data.
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>key_gcm</KeyName>
<Algorithm>AES/GCM</Algorithm>
<TagLen>10</TagLen>
</Operations>
<Base64/>
</CryptoRequest>
<Base64DataSingle>
<IV>123412341234</IV>
<AADSize>8</AADSize>aGVsbG8=
<Size>0</Size>
</Base64DataSingle>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data>
<AuthTag>8F5D4FFBD4E71D6C56C6</AuthTag>
</Base64Data>
Verifying an Authentication Tag with AES/GCM (GMAC Verification)
If there is no ciphertext data in an AES/GCM encrypted message, you can construct a CryptoRequest to only verify the authentication tag. This is essentially a GMAC verification. The following example demonstrates how to use GMAC by sending an AES/GCM decryption request with only Additional Authenticated Data.
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>key_gcm</KeyName>
<Algorithm>AES/GCM</Algorithm>
</Operations>
<Base64/>
</CryptoRequest>
<Base64Data>
<IV>123412341234</IV>
<AuthTag>8F5D4FFBD4E71D6C56C6</AuthTag>
<AADSize>8</AADSize>aGVsbG8=
<Size>0</Size>
</Base64Data>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data></Base64Data>
Encrypting and Creating a Digital Signature
In the example below, the client submits an encryption request and then requests that a digital signature be created.
Request
<CryptoRequest>
<ID>5</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/PKCS5Padding</Algorithm>
<IV>0102030405060708</IV>
<Operation>SIGN</Operation>
<KeyName>RSA1</KeyName>
<Algorithm>SHA1withRSA</Algorithm>
</Operations>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!
</Data>
Response
<CryptoResponse>
<ID>5</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>16</Size>Z!&ÀM(&àl&{…h]
<Send/>
<Size>256</Size>HŠZh?Ó†(øºîsRÅ믆0¾";@û_l’¦êž7Ò“’ö1Ñr)xßKוnÿ ا?÷A±zu¶àó[œÄŽGzȇû÷5'‹1R°AµunEŠí(Ñ¢qu¡W±©€dƃ3fúÛVB“½‹¥Ôãúqö˝Ë€ìú^óè„·a³B çÞÞe/'¾àöGßmhyÜBBòŒ‘1I¤us)ýTù8V²½P&5g5Cjäf–'*< \1«gŠLL:Û‰RV¿…ó $¹ò‰ÀB¬8ˆGåô†ÚãŒ;eužÙvu,ð>'¸k…aùj
</Data>
For PSS Padding with Precomputed Hash:
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>SIGN</Operation>
<KeyName>testkey1</KeyName>
<Algorithm>RSA/PSSPaddingSHA256</Algorithm>
<SaltLength>32</SaltLength>
</Operations>
<Base64/>
</CryptoRequest>
<Base64DataSingle>
<Size>44</Size>GJtW9jdyfbO32P7HQTk/EzL3kAAWXnZ2YI2LjVk+/ko=
</Base64DataSingle>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data>
<Size>344</Size>btI26SfB04MJSEzvSItl9Y/IzwcGPs5K3B62BADBoEny4v7wS/7ckHwRTV7Y1AIC5UiXu6NsxMXzt4co2dyNn55GGJUjM5UonF8iZB5sqJwmCGUI2EHH4VyblsbQWG8JABKZFScoLeNkYxsC6or3Q/Cxhm8xHf8V42ttsMo31sKxGsUzHauKblVG3nBfuC6tC30ABcV9eaiayI6kbYlg5RxETcLXDZ4Hrglvcy/gfwwWLeAnZ92mnTpl9kHCE7xisb+qrfzhIrsD6QcMNyaxrK2af5awtia1IUfEjc/G5DPbTnXl76vU+PRDNWcGshoqIzEZjV5SQXvwQffPZ/hdsQ==
</Base64Data>
Verifying a Digital Signature
In the example below, the client requests that the server verify a digital signature. Note that the hex-encoded signature is in the IV element.
Request
<CryptoRequest>
<ID>1</ID>
<Operations>
<Operation>SIGNV</Operation>
<KeyName>RSA2048</KeyName>
<Algorithm>SHA256wihRSA</Algorithm>
<IV>488a5a683fd38628f8baee7352c5ebaf8630be223b40fb5f6c0192a
6adea9e37d211939214f631d1722978df4d7956efd8a73ff74101c2b17a75b6e0f35b9cc48
e477ac887fbf73527c28b3152b041b5756e451d0d0a8a04ed28d1a271200d0a75a157b1a90d0a80644c3adb110626233134333b89520b5619bf85f32426233132393b26233134333b07b9f28915c042ac1
5388847e5f486dae38c3b65759ed9760e752cf0023e27b86b0f8561f6a</IV>
</Operations>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!
</Data>
Response
<CryptoResponse>
<ID>1</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>1</Size>
</Data>
For PSS Padding with Precomputed Hash:
Request
<CryptoRequest>
<ID>cqY3szwe</ID>
<Operations>
<Operation>SIGNV</Operation>
<KeyName>testkey1</KeyName>
<Algorithm>RSA/PSSPaddingSHA256</Algorithm>
<SaltLength>32</SaltLength>
<IV>6ed236e927c1d38309484cef488b65f58fc8cf07063ece4adc1eb60400c1a049f2e2fef04bfedc907c114d5ed8d40202e54897bba36cc4c5f3b78728d9dc8d9f9e461895233395289c5f22641e6ca89c26086508d841c7e15c9b96c6d0586f090012991527282de364631b02ea8af743f0b1866f311dff15e36b6db0ca37d6c2b11ac5331dab8a6e5546de705fb82ead0b7d0005c57d79a89ac88ea46d8960e51c444dc2d70d9e07ae096f732fe07f0c162de02767dda69d3a65f641c213bc62b1bfaaadfce122bb03e9070c3726b1acad9a7f96b0b626b52147c48dcfc6e433db4e75e5efabd4f8f443356706b21a2a2331198d5e52417bf041f7cf67f85db1</IV>
</Operations>
</CryptoRequest>
<Base64DataSingle>
<Size>44</Size>GJtW9jdyfbO32P7HQTk/EzL3kAAWXnZ2YI2LjVk+/ko=
</Base64DataSingle>
Response
<CryptoResponse>
<ID>cqY3szwe</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>1</Size>
</Data>
Encryption Using EC Algorithms
In the example below, the client requests the server to encrypt data using EC algorithm.
With Batching Request
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>ecc</KeyName>
<Algorithm>ECIESwithSHA512/AES/CBC/PKCS5Padding</Algorithm>
</Operations>
<Base64/>
</CryptoRequest>
<Batch>
<Data>
<IV>01010101010101010101010101010101</IV>
<Size>16</Size>rankumarrankumar
</Data>
<Data>
<IV>02020202020202020202020202020202</IV>
<Size>16</Size>kamkumarkamkumar
</Data>
</Batch>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<EphemeralPubKey>30819B301006072A8648CE3D020106052B81040023038186000400
80FEB1E307E995C5D10499FC25E54C3A8EDFD0D03531E777A82F5D106D34EAC79E8CC24BAC
D09FC883979DA6ECC15A8A81FA01DEC21235D2F357D764DC284B47B7014C86A80EFBF1F501
F90A80B47E2800378AD1C06EE374C35877DE07B36C93C2D10F463D1202D76984B2702B9068
248C6F23B8518E6717EAF02DBFE3A570DFC7D8D5
</EphemeralPubKey>
<Base64Data>
<Size>20</Size>GYDM2Cvn9u096y+7Gxkq<Size>24</Size>L8b9LwYNN5cMbkDqwCX2
znE=
</Base64Data>
<MacData>F2DC5662F8DCDDD1AB2C2A41FD4F930FF9A30CF6D98F1C5
D4AE29BABAB3947BFACB418B3B8164C1F5B37E944BF5FE0614BCCB6F23AF40D0A291DDB68
4BDDC1AF
</MacData>
<EphemeralPubKey>30819B301006072A8648CE3D020106052B8104
002303818600040080FEB1E307E995C5D10499FC25E54C3A8EDFD0D03531E777A82F5D106
D34EAC79E8CC24BACD09FC883979DA6ECC15A8A81FA01DEC21235D2F357D764DC284B47B7
014C86A80EFBF1F501F90A80B47E2800378AD1C06EE374C35877DE07B36C93C2D10F463D1
202D76984B2702B9068248C6F23B8518E6717EAF02DBFE3A570DFC7D8D5
</EphemeralPubKey>
<Base64Data>
<Size>20</Size>D48vQiCAWDjtSx8AW7oA<Size>24</Size>AWLOeHDnNZOAkQgajgq
H7dQ=
</Base64Data>
<MacData>118D0D6068690BD48B01D54CFC2187C11B2C780FFEA5503B8AF0A420CFAEB
9C58574C26AD09604091A135AB9E0D7F39DAA9FABAB41ED14E0B0BEDEBA81F054A3
</MacData>
Without Batching Request
Request
<CryptoRequest>
<ID>Hg92bueK</ID>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>prime256v1</KeyName>
<Algorithm>ECIESwithSHA512/AES/CBC/PKCS5Padding</Algorithm>
<IV>02020202020202020202020202020202</IV>
</Operations>
<Base64/>
</CryptoRequest>
<Data>
<Size>16</Size>1234567890123456
</Data>
Response
<CryptoResponse>
<ID>Hg92bueK</ID>
<Success>true</Success>
</CryptoResponse>
<EphemeralPubKey>3059301306072A8648CE3D020106082A8648CE3D0
3010703420004FAF5273C09AAB88A67DD9F37C2450675BC9250D51D2E
A4377317992A90B749199FDE30C50157118E4A23BC5905243F3C8C9C0
93C8588800E9D489B5A5628F598
</EphemeralPubKey>
<Base64Data>
<Size>20</Size>KKznDKqLi995z7/eP4G7<Size>24
</Size>55LFhVKWur2vPsp31p9PxO0=
</Base64Data>
<MacData>47026676AD1B87FB7DDA1117E5371A08E0E1FACDA31B2E2F
B25FB26B34DFF53159EF20F3D039E2ABE1E9941944955CF25DD719A39
649924FCD0B8039208CE97B
</MacData>
Decryption using EC Algorithms
With Batching Request
Request
<CryptoRequest>
<ID>123</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>ecc</KeyName>
<Algorithm>ECIESwithSHA512/AES/CBC/PKCS5Padding</Algorithm>
<EphemeralPubKey>30819B301006072A8648CE3D020106052B8104002303818600
040080FEB1E307E995C5D10499FC25E54C3A8EDFD0D03531E777A82F5D106D34EAC79E8CC2
4BACD09FC883979DA6ECC15A8A81FA01DEC21235D2F357D764DC284B47B7014C86A80EFBF
1F501F90A80B47E2800378AD1C06EE374C35877DE07B36C93C2D10F463D1202D76984B270
2B9068248C6F23B8518E6717EAF02DBFE3A570DFC7D8D5
</EphemeralPubKey>
</Operations>
<Base64/>
</CryptoRequest>
<Batch>
<Base64Data>
<IV>01010101010101010101010101010101</IV>
<MacData>F2DC5662F8DCDDD1AB2C2A41FD4F930FF9A30CF6D98F1C5D4AE29BABAB394
7BFACB418B3B8164C1F5B37E944BF5FE0614BCCB6F23AF40D0A291DDB684BDDC1AF
</MacData>
<Size>44</Size>GYDM2Cvn9u096y+7GxkqL8b9LwYNN5cMbkDqwCX2znE=</Base64Data>
<Base64Data>
<IV>02020202020202020202020202020202</IV>
<MacData>118D0D6068690BD48B01D54CFC2187C11B2C780FFEA5503B8AF0A420CFAEB
9C58574C26AD09604091A135AB9E0D7F39DAA9FABAB41ED14E0B0BEDEBA81F054A3
</MacData>
<Size>44</Size>D48vQiCAWDjtSx8AW7oAAWLOeHDnNZOAkQgajgqH7dQ=</Base64Data>
</Batch>
Response
<CryptoResponse>
<ID>123</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data><Size>20</Size>cmFua3VtYXJyYW5rdW1h<Size>4</Size>cg==</Base64Data>
<Base64Data><Size>20</Size>a2Fta3VtYXJrYW1rdW1h<Size>4</Size>cg==</Base64Data>
Without Batching Request
Request
<CryptoRequest>
<ID>Z9Wai7TZ</ID>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>prime256v1</KeyName>
<Algorithm>ECIESwithSHA512/AES/CBC/PKCS5Padding</Algorithm>
<IV>02020202020202020202020202020202</IV>
<EphemeralPubKey>3059301306072A8648CE3D020106082A8648CE3D
03010703420004FAF5273C09AAB88A67DD9F37C2450675BC9250D51
D2EA4377317992A90B749199FDE30C50157118E4A23BC5905243F3C
8C9C093C8588800E9D489B5A5628F598</EphemeralPubKey>
<MacData>47026676AD1B87FB7DDA1117E5371A08E0E1FACDA31B2
E2FB25FB26B34DFF53159EF20F3D039E2ABE1E9941944955CF25DD
719A39649924FCD0B8039208CE97B</MacData>
</Operations>
</CryptoRequest>
<Base64Data>
<Size>44</Size>KKznDKqLi995z7/eP4G755LFhVKWur2vPsp31p9PxO0=
</Base64Data>
Response
<CryptoResponse>
<ID>Z9Wai7TZ</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>16</Size>1234567890123456
</Data>
Creating Digital signature for EC algorithm
In the example below, the client requests that the server create a digital signature for EC algorithm.
Request
<CryptoRequest>
<ID>1</ID>
<Operations>
<Operation>SIGN</Operation>
<KeyName>key_ecc</KeyName>
<Algorithm>SHA256withECDSA</Algorithm>
</Operations>
<base64/>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!
</Data>
Response
<CryptoResponse>
<ID>1</ID>
<Success>true</Success>
</CryptoResponse>
<Base64Data>
<Data>
<Size>84</Size>MD0CHQCQ5UuMwnXeJz854nsgo1IveH3koEc6qewJzIWpAhxKNlptfZd6A52HLljbNb47W/2j4wc/MFSCrzIx
</Base64Data>
Verifying digital signature for EC algorithm
In the example below, the client requests that the server verify a digital signature for EC algorithm.
Request
<CryptoRequest>
<ID>1</ID>
<Operations>
<Operation>SIGNV</Operation>
<KeyName>key_ecc</KeyName>
<Algorithm>SHA256withECDSA</Algorithm>
<IV>303c021c1c8cb9cf8d1da5010dffb3cdeb8bb0721c6daa8b45fc790abc683775021c6e9333de91407a9cfe8df6725603dfe7451b7dabfb3d71a98b1a2ad8</IV>
</Operations>
</CryptoRequest>
<Data>
<Size>12</Size>Hello World!
</Data>
Response
<CryptoResponse>
<ID>1</ID>
<Success>true</Success>
</CryptoResponse>
<Data>
<Size>1</Size>
</Data>
| Element | Description |
|---|---|
| Supported Algorithm by EC for SIGN/VERIFY | ECDSA (Data to be signed should be pre calculated hash) • SHA1withECDSA • SHA256withECDSA • SHA384withECDSA • SHA512withECDSA |
Response Header Error: "Invalid or Missing Key Name"
In this example, the client requested encryption on a small byte array of a known size. The key is not found and the server sends back a non-fatal error in the response header. This is an unsuccessful response to the request example shown in Examples of Cryptographic Requests and Responses.
<CryptoResponse>
<ID>3JALD8EJIF</ID>
<Success>false</Success>
<NonFatalError>1401</NonFatalError>
<ErrorString>Unknown key name</ErrorString>
<OperationIndex>1</OperationIndex>
<Operations>
<Operation>ENCRYPT</Operation>
<KeyName>EncryptionKey</Operation>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
</Operations>
</CryptoResponse>
Response Header Error: "Invalid Key/Algorithm Pair"
In this example, the client requested decryption on a large chunk of data. EncryptionKey is not a DES key and the server sends back a non-fatal error in the response header. This is an unsuccessful response to the request example shown in Examples of Cryptographic Requests and Responses.
<CryptoResponse>
<ID>A38JDSL932</ID>
<Success>false</Success>
<NonFatalError>1323</NonFatalError>
<ErrorString>Invalid algorithm/key pair</ErrorString>
<OperationIndex>1</OperationIndex>
<Operations>
<Operation>DECRYPT</Operation>
<KeyName>EncryptionKey</KeyName>
<Algorithm>DESede/CBC/NoPadding</Algorithm>
</Operations>
</CryptoResponse>
