Chapter 1: About This Manual

AKM Encryption Service API

The AKM Encryption Service allows a user to encrypt and decrypt sensitive data remotely on the AKM server so that the encryption keys never leave the server. The AKM Encryption Service API defines a standard interface to the AKM Encryption Service so clients can build custom client implementations.

Encryption and decryption is performed via a secure TLS connection to the AKM server. Both the client and server end-points are authenticated via the TLS protocol.

The AKM Encryption Service supports encryption with symmetric AES keys and asymmetric RSA keys. Symmetric AES encryption is available in two modes: ECB (electronic code book) and CBC (cipher block chaining).

Who is this for?

This guide is designed for developers who will write their own interface to the AKM Encryption Service. You will need to have the programming skills necessary to create TLS connections to exchange requests and responses between your client application and the AKM server. A good knowledge of secure programming techniques is highly recommended.

Other resources

The following documents provide additional information on the installation and use of Alliance Key Manager:

Notices

This product and documentation is covered by U.S. and International copyright law. Please see the AKM Copyright Notice for more information.

This product may incorporate software licensed under one or more open source license agreements. Government users please note that this product is provided under restricted government use license controls. Please refer to the AKM End User License Agreement for more information.

Change log

The following table provides information on the changes to this documentation:

Version Date Description
1.00 10/13/2011 Initial release. Information migrated from the AKM Administrative Interface Reference.
3.0.0.001 5/2/2014 Update and revise for AKM 3.0.0.
3.0.0.002 10/1/2014 Updates. Rename from “AKM Encryption Interface Reference” to “AKM Encryption Service API Reference”.
3.0.3.001 12/30/2014 Update for AKM 3.0.3 and the ready to use version of AKM for VMware.
4.0.0.001 2/15/2016 Update for AKM 4.0. Add info on TLS versions.
4.0.0.002 5/13/2016 Update Preparation chapter for AKM 4.0 HSM release.
4.0.0.003 7/12/2016 Update for AKM 4.0 Azure release.
4.5.0.001 10/14/2016 Add asymmetric RSA key APIs.

Chapter 2: Preparation

Overview

Before setting up remote encryption in your client application, you will need to complete the following steps:

  • Install and set up the primary AKM server and any secondary mirror servers (instructions are located in platform specific deployment guides)

  • Create encryption keys (available as an option during AKM server setup, or, through the AKM Administrative Console application)

  • Download certificates from the AKM server

  • Know the IP address(es) of the AKM server(s) and port number for remote encryption (default is 6003)

See below for more information.

Licensing

A temporary or permanent license is required to use or evaluate AKM. All deployments of AKM create a 30-day license automatically during setup and initialization, except for the Amazon Web Services fee-based deployment, which generates a permanent license.

A temporary license will enable a fully functional AKM server that may be run in your environment for evaluation or testing. If the temporary license expires, a permanent license may be purchased from Townsend Security or your software vendor. See your AKM platform specific deployment guide for information on installing a permanent license.

AKM Encryption Service options

The encryption service on AKM is enabled by default, with both encryption and decryption enabled.

In some environments there may be a compliance advantage in allowing only encryption or decryption. For example, at a point-of-sale checkout location you may want to encrypt a credit card number but not allow decryption in that environment.

To disable either encryption or decryption, modify the AKM configuration file (akm.conf) on the AKM server via the web interface. See the AKM Server Management Guide for more information.

To further restrict operations, a custom license file may be requested with encryption or decryption disabled by default. These settings cannot be later overridden by the configuration file.

Certificates and private keys

The client and AKM server use certificates and private keys to establish a secure TLS connection and perform authentication. You will need to install the following certificates and private keys on the client in order to authenticate your client application with the AKM server:

  • AKM’s certificate authority (CA) certificate

  • Client certificate and private key signed by AKM’s CA certificate

These certificates are generated on initialization and stored on the AKM server in several formats. See your platform specific AKM deployment guide for instructions on downloading key client certificates. The format you require depends on the application development environment.

SECURITY ALERT: Private key files must be protected during creation, distribution, and storage to prevent loss. The loss of these files will compromise the security of the AKM server. Depending on the file format, the private key files may be bundled with a certificate or they may be separate files. Transfer the private key files by sharing them over a secure network, placing them in a password-protected zip file, sending them using SFTP, or another secure method. Use the same level of care you would employ to protect encryption keys, including encryption. In the event the private keys are compromised or lost, you should immediately replace the certificate authority on the AKM server and all client certificates in that chain of trust. See the AKM Certificate Manager Guide for more information.

Server information

The following server information is required for client setup and configuration:

  • The IP address or DNS name of the primary AKM server and any secondary AKM servers

  • The port number for encryption services on AKM (the default is 6003)

Encryption keys

To set up remote encryption in the client application, you must have the name(s) of the encryption key(s) on AKM you would like to use.

AKM setup and initialization includes the option to generate an initial set of encryption keys. See your platform-specific AKM deployment guide for more information on encryption keys available for use, if that option was selected.

If needed, encryption keys can be created using the AKM Administrative Console application. See the AKM Administrative Console Guide for more information.

You will also need the key instance if not using the current instance of the key (to use the current instance, you will enter all blanks for the key instance). Use the AKM Administrative Console to look up this information.

Checklist

Before continuing, you will need the following items:

  • AKM’s CA certificate in a format appropriate for your application environment

  • A client certificate and private key in a format appropriate for your application environment

  • The IP address or DNS name of the primary AKM server (and any secondary AKM servers) and the encryption services port number (the default is 6003)

  • The name of one or more encryption keys on AKM

Chapter 3: Introduction

This chapter covers general information about the AKM Encryption Service API. For information on programming for security, see Appendix B: Programming Best Practices.

Authentication certificates

Certificates are used to verify the identity of their holders and authenticate two or more parties during secure TLS communication.

Certificates contain a public key which is paired with a corresponding private key. These are also known as “asymmetric keys”. However, the asymmetric keys that are used for AKM authentication should not be confused with asymmetric RSA keys that are created and stored on the AKM server and used for encryption/decryption of client data.

The following certificates and private keys are required to be installed on the client to allow communication with the AKM server: AKM’s certificate authority (CA) certificate, a valid client certificate signed by AKM’s CA certificate, and the client private key.

Client/server architecture

The AKM Encryption Service API uses a client/server request/response architecture. This means that every time your application (the client) sends a request to the AKM server, the AKM server returns a response.

Plaintext and ciphertext

Plaintext is the unencrypted data which is sent to the AKM server for encryption. Ciphertext is the encrypted data that is returned to the client. When decrypting this data, the client sends the ciphertext to the AKM server and receives the plaintext data in the response.

Requests and responses

When you send plaintext to the AKM server to be encrypted, this is an encryption request. The AKM server returns the ciphertext in an encryption response. When you send the ciphertext back to the server to be decrypted, this is a decryption request. The server returns the plaintext in a decryption response. Requests and responses contain a header followed by the plaintext or ciphertext data. The header in a request gives instructions to the server about how to encrypt the data. The header in the response gives information about the returned data.

TLS version

AKM supports the use of TLS 1.0, 1.1, and 1.2 for client/server communication. The default minimum TLS setting is 1.0, but for enhanced security you can modify the AKM configuration file (akm.conf) to restrict connections to TLS 1.1 or 1.2. See the AKM Server Management Guide for information on modifying the AKM configuration file.

TLS records

A TLS record is what you send in a TLS send or receive in a TLS receive. AKM’s limit on data which can be sent or received in a single record is 16,384 bytes (16 KB). A single record can be any size up to and including this limit. A record can contain multiple requests or responses. You can send multiple TLS records in a session or in subsequent sessions.

TLS sessions

A TLS session is the period of time during which the TLS connection between the client and the server is open and encryption and decryption requests and responses can be exchanged. Only one type of request (for example, encryption requests in CBC mode) can be performed in any given session. Sessions are persistent in that they are available in full duplex mode as long as the underlying TCP session does not time out or is not closed by the client. The AKM server will time out a TLS session after 30 seconds if no traffic occurs in that time. To prevent denial-of-service attacks, there is no keep alive mechanism for the session.

CBC vs. ECB encryption

The AKM Encryption Service API supports both CBC mode (cipher block chaining) and ECB mode (electronic codebook) for symmetric key encryption. However, CBC mode has several advantages over ECB mode. With ECB mode and given a single key, data always encrypts to the same pattern. Even if you do not know the plaintext, you can clearly see patterns in the ciphertext. Even if you use a new key for every request, if you have any repeating plaintext data there will still be discernable patterns in the ciphertext. In CBC mode, however, a unique input (the initialization vector, or IV) is used to create randomness. The cryptographic algorithm uses the IV in combination with the encryption key to encrypt the first AES block (the first 16 bytes of plaintext), and the resulting ciphertext (along with the key) is used to encrypt the plaintext in the next block, and so on. If you want to use ECB mode, be sure to use a unique key with every encryption request and avoid repeating blocks of plaintext.

Initialization Vector

An initialization vector (IV) is a fixed-size input in cryptographic algorithms used in CBC mode. IV’s do not need to be kept private and can be stored next to the encrypted data and sent in the clear over the network. Be sure to use cryptographically strong random data for the IV. Be aware that typical random calls in various programming languages are not suitable for creating the IV, because these pseudorandom number generators are actually predictable.

Key names and instances

Every symmetric encryption key created by AKM is given a key name and a unique instance (version) name.

When a symmetric key is rolled, a new key is created with the same key name and a new instance name. This maintains the relationship of each instance to the original key, and means that you can roll the key without having to re-encrypt data that was protected with an older instance of the key. A rolled key is technically a new key, but since the key name does not change, it is considered a new instance of the same key. Every time the key is rolled and a new instance is created, this becomes the “current” instance of the key (sometimes known as the “default” instance). All older instances of the key are retained until you explicitly delete them.

An asymmetric RSA key pair has one key name, and the public and private keys also each have a unique instance name. Asymmetric RSA keys cannot be rolled.

When you send an encryption request, you can specify the key name, the key instance, or both. If you specify only the key name and set the key instance to blanks, AKM will use the current instance of the key. The key instance name used for encryption is always returned in the response header and can be stored in a column with the encrypted data. On a decryption request you can then specify the correct instance of the key.

AES blocks and padding

AES encryption supports block sizes of 128 bits (16 bytes). If you have data where the only or final block is not an even 16 bytes, the data must be padded. You can pad the data yourself or you can ask the AKM server to pad the data for you on encryption. You can ask the AKM server to strip the padding for you on decryption, or you can remove the padding yourself in your application after the decrypted data has been returned to you. If the length of your data is a multiple of 16 bytes and you ask for padding, the server will add 16 bytes of padding. The AKM Encryption Service API uses PKCS #7 padding.

Data formats

The AKM Encryption Service API uses US-ASCII format (printable character set, ANSI X3.4-1986) for both numeric and character field values in request and response headers, except for the IV, which will be in binary. Both Base16 and Base64 format use US-ASCII characters.

When encrypting and decrypting with a symmetric key, plaintext data sent in encryption requests must be in binary format, and the ciphertext can be returned in binary, Base16, or Base64 format. When sending the ciphertext to be decrypted, the plaintext data can be returned in binary, Base16, or Base64 format. Binary data can contain a value in the range of 0 to 255 (hex 00 to hex FF) per byte.

When encrypting and decrypting with an asymmetric RSA key, data must be sent and received in binary format.

Data limits

The limit which can be sent and received over the TLS connection in a record is 16 KB (16,384 bytes). This includes headers and associated plaintext or ciphertext data. The limit of plaintext or ciphertext data which can be sent or received is 16,272 bytes.

Be aware that Base16 writes two characters for every one byte. Base64 writes four characters for every three bytes. This means that if you request Base16 or Base64 encoding, the length of the returned plaintext or ciphertext may expand and the combined header(s) and data in the response may exceed the record limit (16,384 bytes). The AKM Encryption Service API can accommodate this through the use of continuation headers. If you do not want to use continuation headers, limit the plaintext or ciphertext data sent so that when it is encrypted or decrypted, the response will not exceed the record limit. For example, if you want to use B16 encoding to encrypt binary plaintext data, limit the plaintext data to 8136 bytes (16,272 divided by 2).

Continuation headers

Continuation headers are used to accommodate Base16 and Base64 encoding used in symmetric key encryption and decryption requests. If the returned response exceeds the record limit of 16,384 bytes, the plaintext or ciphertext will be returned in two responses, the second response beginning with a continuation header. For more information on continuation headers, see Chapter 9: Using Continuation Headers.

Procedures

Use the following process to enable your client applications to encrypt or decrypt data on the AKM server:

  1. Format a request in your application to perform encryption or decryption

  2. Open a TCP connection to the AKM server

  3. Secure the connection with TLS

  4. Send the request to the AKM server

  5. Receive a response from the AKM server

  6. Close the connection to the AKM server

  7. Read the response into your application

Chapter 4: Requests and Responses

Types of requests and responses

When you send plaintext to the AKM server to be encrypted, this is an encryption request. The AKM server returns the ciphertext in an encryption response. When you send the ciphertext back to the server to be decrypted, this is a decryption request. The server returns the decrypted plaintext in a decryption response. For each type of encryption (CBC and ECB), this gives the following types of requests and responses:

CBC:

  • Encrypt CBC request

  • Encrypt CBC response

  • Decrypt CBC request

  • Decrypt CBC response

ECB:

  • Encrypt ECB request

  • Encrypt ECB response

  • Decrypt ECB request

  • Decrypt ECB response

Requests and responses contain a header and the plaintext or ciphertext data.

Example encryption request

The following is an example of an encryption request in CBC mode (Encrypt CBC request), including header and corresponding plaintext:

000982019YNBIN00016YYNYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiipppppppppppppppp

In this example:

  • 00098 is the HeaderLength field (the length of the header excluding the HeaderLength field in bytes).

  • 2019 is the RequestID field.

  • Y is the NewKeyFlag field. A new key is used.

  • N is the PaddingFlag field. Padding is not needed.

  • BIN is the CipherTextFormat field. BIN (binary) is the desired ciphertext format.

  • 00016 is the PlainTextLength field. There are 16 bytes of plaintext to encrypt.

  • Y is the EndOfRequestFlag. No more data will be sent with a continuation header.

  • Y is the PackedFlag. The server will pack the responses.

  • N is the FinalFlag. The server will not close the session.

  • Y is the NewIVFlag. A new IV is used.

  • vvvvvvvvvvvvvvvv This represents the 16-binary bytes of the IV.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk This represents the KeyName field. This is the 40-byte key name (blank-padded on the right if less than 40 bytes).

  • iiiiiiiiiiiiiiiiiiiiiiii This represents the Instance field. This is the 24-byte instance name.

  • pppppppppppppppp This represents the 16-binary bytes in the PlainText field.

Everything up to the PlainText field constitutes the header, and the PlainText field constitutes the data. The total size of this request is 119 bytes. The HeaderLength size is 5 bytes, the header size is 98 bytes, and the PlainText size is 16 bytes.

See the following sections for more information on fields in requests and responses.

Fields in requests and responses

The following sections give information on fields used in requests and responses. Keep the following general considerations in mind:

  • The information given below in the section headings includes the field name, the field length in bytes, and required format or possible values.

  • Header fields have a fixed length. Data fields (PlainText and CipherText) do not.

  • Header fields are in US-ASCII format, except the IV field, which is in binary.

  • Some header fields must be in numeral characters; these are noted below.

  • Header fields that may require padding are left-padded with zeros (0), except the KeyName field, which is padded on the right with blanks.

  • The field names (HeaderLength, etc) are used for explanatory purposes and you will not need to enter these field names when formatting your requests.

HeaderLength - 5 bytes, numeral left-padded

This field indicates the remaining length of the header, not including the HeaderLength field itself. This tells the server how many more bytes to read for the header after this 5-byte field. This field is included in the header of the first request and response exchanged in a session. This field is not included in subsequent request and response headers (even though lengths of subsequent request and response headers can vary).

RequestID - 4 bytes, numeral left-padded

This field indicates the type of request. You must include this field in the header of the first request exchanged in a session. Do not include this field on subsequent requests in a session. Because of this, only one type of request can be sent in a session (for example, Encrypt CBC request).

ResponseID - 4 bytes, numeral left-padded

This field indicates the type of response. It is included in the header of the first response exchanged in a session. This field will not be included on subsequent responses in a session.

NewKeyFlag - 1 byte, Y or N

If NewKeyFlag is set to Y in a request header then the 40-byte KeyName field and the 24-byte Instance fields must be included in the header. If NewKeyFlag is set to N then the KeyName and Instance fields must be left out, and the previously specified KeyName and Instance values will be used to encrypt or decrypt. You must set NewKeyFlag to Y on the first request of a session. If NewKeyFlag is set to Y in CBC mode, NewIVFlag must also be set to Y.

PaddingFlag - 1 byte, 7 or N

This field is used in encryption requests to indicates whether you would like the AKM server to add padding to the plaintext before it is encrypted. It is also used in decryption requests to indicate whether padding should be removed. AES is a block encryption algorithm and requires 16-byte blocks of data for both encryption and decryption. If you have plaintext data where the only or final block is not an even 16 bytes, the data must be padded. If you ask for padding and the only or final block is already 16 bytes, the server will add 16 bytes of padding.

If you do not need padding or if your application will provide padding before the data is sent, set PaddingFlag to N on the encryption request. If you want the AKM server to provide padding, set PaddingFlag to 7. If you want the AKM server to strip padding from the ciphertext on decryption automatically, set PaddingFlag to 7 on the decryption request. If you want to remove padding yourself in your application, set PaddingFlag to N on the decryption request.

AKM uses PKCS #7 padding. With PKCS #7 padding, the value of the added padding bytes will reflect the number of bytes added. For example, if 4 bytes of padding are added to a 12-byte block, each of the added bytes will have the value of 4. This means that by looking at the last byte of decrypted data, you can easily see how many bytes of padding were added to the padded block.

CipherTextFormat - 3 bytes, BIN, B16 or B64

This field indicates the desired ciphertext format in encryption requests and the actual ciphertext format in decryption requests. Ciphertext can be in binary (BIN), Base16 (B16) or Base64 (B64) format. Keep in mind that using Base16 or Base64 encoding will expand the size of the ciphertext relative to the plaintext.

CipherTextLength - 5 bytes, numeral, left-padded

This field indicates the length of the CipherText field returned in encryption responses and sent in decryption requests.

PlainTextFormat - 3 bytes, BIN, B16 or B64

This field indicates the desired format for plaintext returned in a decryption response. Plaintext can be returned in binary (BIN), Base16 (B16) or Base64 (B64) format. Keep in mind that using Base16 or Base64 encoding may change the size of the plaintext relative to the ciphertext.

PlainTextLength - 5 bytes, numeral left-padded

This field indicates the length of the PlainText field sent in encryption requests and returned in decryption responses.

EndOfRequestFlag - 1 byte, Y or N

This field indicates whether the current request is complete, or whether the data has been split in two parts and the second part is being sent in a continuation request. The initial request header will have EndOfRequestFlag set to N and the continuation header will have EndOfRequestFlag set to Y. The server will not encrypt or decrypt until the continuation header is received.

EndOfResponseFlag - 1 byte, Y or N

This field indicates whether the current response is complete, or whether the data has been split in two parts and the second part is being sent in a continuation response. The initial response header will be have EndOfResponseFlag set to N and the continuation header will have EndOfResponseFlag set to Y.

PackedFlag - 1 byte, Y or N

Indicates whether the server should pack the responses. If PackedFlag is set to Y on a request, this means the server will receive this request, formulate a response, and then wait for another request. Then it will try to fit as much data from the second response as it can in the same TLS record as the first response. If all of the data from the second response will not fit in the record, it will send as much as it can in that record and then send the rest of the data in a continuation response. If PackedFlag is set to N on a request, the server will send the response immediately. If PackedFlag is set to Y on a response, it means the response has been packed by the server. If PackedFlag is set to N on a response, it means the response has not been packed by the server.

FinalFlag - 1 byte, Y or N

This field indicates whether the server close the session. To keep the session open, set FinalFlag to N. For the final request, set FinalFlag to Y and the server will close the session.

NewIVFlag - 1 byte, Y or N

This field indicates whether a new IV is being used with CBC Encrypt and CBC Decrypt. You must set NewIVFlag to Y on the first request. If you are splitting a file into multiple segments, you should set NewIVFlag to Y on the first request and NewIVFlag to N on subsequent requests if you want the server to use the last encrypted block value of each request for CBC chaining.

IV - 16 bytes, binary format

If NewIVFlag is set to Y, the IV must be included in the header.

KeyName - 40 bytes, blank right-padded

If NewKeyFlag is set to Y, the KeyName must be included in the header. The KeyName value will be an encryption key already created for use with AKM.

Instance - 24 bytes

If NewKeyFlag is set to Y in a request, the Instance must be included in the request header and the server will return the Instance in the response header. Use blanks to indicate the current instance.

ReturnCode - 4 bytes, numeral left-padded

This field, included in responses, indicates an error state or lack of one. A return code of 0000 means there is no error. Return code values are always positive numbers in the range 0001 - 9999. Non-zero return codes will result in an informational error message with that error number being written to AKM’s log file. If a non-zero return code is returned, the remainder of the response after the PackedFlag is discarded and the session is closed. See the AKM Error Codes Reference for more information.

PlainText - length varies

This field contains the plaintext data sent in an encryption request or returned in a decryption response. In an encryption request, this field must be in binary format.

CipherText - length varies

This field contains the ciphertext data returned in an encryption response or sent in a decryption request.

Chapter 5: TLS Records

This chapter describes the exchange of requests and responses between the client and server and the formatting of TLS records. The following terms, abbreviations and graphical representations are used:

  • {} This represents the TLS session. A session is the period of time during which the connection between the client and the server is open and encryption and decryption requests and responses can be exchanged.

  • [] This represents the TLS record. A TLS record is what you send in a TLS send or receive in a TLS receive. A single record can be any size up to and including the record limit of 16,384 bytes (16 KB), including headers and ciphertext/plaintext. You can send multiple TLS records in a session or in subsequent sessions. A single record can contain multiple requests or responses.

  • HD This represents a header (H) and its corresponding data (D). HD represents a single request or response. Requests and responses begin with a header (H) which gives instructions on what to do with the plaintext or ciphertext data (D). D represents a standalone piece of data.

  • HD1 This represents a header (H) and a corresponding segment of data (D1). When the data in an encryption request cannot be sent within a single TLS record, it must be broken up into smaller segments and sent in separate records ([HD1] [HD2] [HD3]). Dn represents a segment of data that is part of a larger file.

  • HcDc This represents a continuation header (Hc) and a corresponding continuation of data (Dc). When B16 or B64 encoding is used in encryption and decryption requests, the data may expand and the resulting response may exceed the record limit. In this case the data is split into two requests or responses and sent in separate records. The second request or response contains a continuation header.

Sending requests

Keep the following considerations in mind when formulating requests:

  • The HeaderLength and RequestID will only be included in the header of the first request sent in a session. Therefore, you can only send one type of request in a single session (Encrypt CBC request, for example).

  • The actual length of each header will vary depending on whether it is the first request sent in a session (when HeaderLength and RequestID fields are included), whether the NewKeyFlag is set to Y (in which case the 40-byte KeyName field and the 24-byte Instance fields are included), and whether NewIVFlag is set to Y (in which case the 16-byte IV field is included).

  • The combined length of headers and data sent in a record must not exceed the record limit of 16 KB (16,384 bytes)

  • You cannot split either the request header or the request data across TLS record boundaries, unless you are using continuation headers.

There are a number of ways you can formulate requests. You can send multiple smaller requests in a single TLS record [HDHDHD], or send a single larger request per record [HD]. You can send the request header and request data together in one record [HD] or you can send the header and the data in separate records [H] [D]. See below for more information.

Sending one or more requests in a single record

You can send multiple requests in a single record:

{  [HD HD HD ... ] }

Or you can send a single request in a single record:

{  [HD] }

Each HD represents a unique request. The brackets represent the record limit (16,384 bytes). The braces represent the session.

For an example of encrypting a 16-byte piece of data in CBC mode, see Example 1 in Chapter 7: AES CBC Examples. For an example of encrypting small pieces of data of variable length, see Example 3.

Sending a larger file in multiple records

For larger files that exceed the record limit (16,384 bytes), you will need to break the data up into smaller segments and send each segment in multiple requests in separate records:

{ [HD1] [HD2] [HD3] ... }

HD1 represents the first request, which meets the record limit (represented by brackets). D1, D2, D3 etc represent the segments of data that the file has been split into.

Alternatively, you can send each header and segment in separate records:

{ [H] [D1] [H] [D2] [H] [D3] ... }

For an example of encrypting a large file in CBC mode, see Example 2 in Chapter 7: CBC Examples.

Using continuation headers

When B16 or B64 encoding is used in encryption and decryption requests, the data may expand and the resulting response may exceed the record limit. If B16 or B64 encoding is used to encrypt, the response will be returned using a continuation header. When you send the ciphertext back to the server in a decryption request, you will also need to use a continuation header. This can be represented as:

{ [HD] [HcDc] }

Hc represents the continuation header and Dc represents the continuation data. See Chapter 9: Using Continuation Headers for more information.

Receiving responses

For every request sent to the AKM server, the server will return a response. When receiving responses, it is important to note the order received so you can correlate requests and responses.

IMPORTANT: As with request headers, response header lengths will vary. Only the first response in a session will contain the HeaderLength and ResponseID fields in the header.

There are some situations where the server will behave differently when sending responses:

  • If you send a series of requests with PackedFlag set to Y, the server will pack the responses into one TLS record and delay sending responses until the record limit is reached or it receives a request with PackedFlag set to N or FinalFlag set to Y.

  • If the server has EndOfRequestFlag set to N, the server will wait for the continuation request header before sending the response.

  • If the server encounters an error, it will send the response immediately and close the session.

 

Chapter 6: AES CBC Specifications

The following tables show fields used in requests and responses in CBC mode. Each row includes the field name, the length of the field in bytes, possible values, and notes. Variable numbers are represented with the lowercase letter “n”.

For example requests and responses in CBC mode, see Chapter 7: AES CBC Examples.

Encrypt CBC request

Field Length Value Notes
HeaderLength 5 00098 Included in the first request.
RequestID 4 2019 Included in the first request.
NewKeyFlag 1 Y or N  
PaddingFlag 1 7 or N 7 indicates PKCS #7 padding is required, N indicates no padding is required.
CipherTextFormat 3 BIN or B16 or B64  
PlainTextLength 5 nnnnn not 00000  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
NewIVFlag 1 Y or N  
IV 16 Varies Present if NewIVFlag is Y. Must be in binary format.
KeyName 40 Varies Present if NewKeyFlag is Y.
Instance 24 Varies Present if NewKeyFlag is Y.
PlainText Varies* Varies *Up to 16,272 bytes with PaddingFlag set to N. Up to 16,271 bytes with PaddingFlag set to 7. If a continuation is being used and PaddingFlag=7, this PlainText must be of length modulus 16 and continuation PlainTexts may be of any length.

Encrypt CBC request continuation

Field Length Value Notes
EndOfRequestFlag 1 Y or N  
PlainTextLength 5 nnnnn not 00000  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
PlainText Varies * Varies *Up to 16,272 bytes with PaddingFlag set to N. Up to 16,271 bytes with PaddingFlag set to 7.

Encrypt CBC response

Field Length Value Notes
HeaderLength 5 00039 Included in the first response.
ResponseID 4 2020 Included in the first response.
ReturnCode 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N If ReturnCode is non-zero, the response ends here.
CipherTextLength 5 nnnnn not 00000  
Instance 24 Varies Present if NewKeyFlag is Y in corresponding request header.
CipherText Varies * Varies *Up to 16,272 bytes.

Encrypt CBC response continuation

Field Length Value Notes
ReturnCode 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N  
CipherTextLength 5 nnnnn not 00000  
CipherText Varies * Varies *Up to 16,272 bytes.

Decrypt CBC request

Field Length Value Notes
HeaderLength 5 00101 Included in the first request.
RequestID 4 2021 Included in the first request.
NewKeyFlag 1 Y or N  
PaddingFlag 1 7 or N 7 indicates padding should be stripped, N indicates padding should not be stripped.
CipherTextFormat 3 BIN or B16 or B64  
CipherTextLength 5 nnnnn not 00000  
PlainTextFormat 3 BIN or B16 or B64  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
NewIVFlag 1 Y or N  
IV 16 Varies Present if NewIVFlag is Y. Must be in binary format.
KeyName 40 Varies Present if NewKeyFlag is Y.
Instance 24 Varies Present if NewKeyFlag is Y.
CipherText Varies* Varies *Up to 16,272 bytes.

Decrypt CBC request continuation

Field Length Value Notes
CipherTextLength 5 nnnnn not 00000  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
CipherText Varies* Varies *Up to 16,272 bytes.

Decrypt CBC response

Field Length Value Notes
HeaderLength 5 00039 Included in the first response.
ResponseID 4 2022 Included in the first response.
ReturnCode 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N If ReturnCode is non-zero, the response ends here.
PlainTextLength 5 nnnnn not 00000  
Instance 24 Varies Present if NewKeyFlag is Y in corresponding request header.
PlainText Varies* Varies *Up to 16,272 bytes.

Decrypt CBC response continuation

Field Length Value Notes
ReturnCode 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N  
PlainTextLength 5 nnnnn not 00000  
PlainText Varies* Varies *Up to 16,272 bytes.

 

Chapter 7: AES CBC Examples

This chapter contains examples of requests and responses to encrypt and decrypt the following types of data with CBC mode: One 16-byte piece of data, a large file, and several smaller pieces of data of variable length.

In these examples, the following representations are used:

  • The lowercase letter “v” is used to represent values in the IV field.

  • The lowercase letter “k” is used to represent values in the KeyName field.

  • The lowercase letter “i” is used to represent values in the Instance field.

  • The lowercase letter “p” is used to represent values in the PlainText field.

  • The lowercase letter “c” is used to represent values in the CipherText field.

 

Example 1: Encrypt and decrypt one 16-byte piece of data

This example shows how you would encrypt and decrypt a 16-byte piece of data such as a credit card number.

Encrypt CBC request

The following example shows the complete encryption request in CBC mode:

000982019YNBIN00016YNYYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiipppppppppppppppp

In this example:

  • 00098 is the HeaderLength. 98 bytes is the length of the header for this request.

  • 2019 is the RequestID for Encrypt CBC request.

  • Y is the NewKeyFlag. A new key is used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header, and NewIVFlag must be set to Y.

  • N is the PaddingFlag. The data length is a multiple of 16 bytes and therefore no padding is needed.

  • BIN is the CipherTextFormat. BIN (binary) is the desired ciphertext format.

  • 00016 is the PlainTextLength. 16 bytes is the length of the plaintext.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • Y is the FinalFlag. The server will close the session after sending the response.

  • Y is the NewIVFlag. A new IV is used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field. Enter blanks to use the current instance.

  • pppppppppppppppp represents the 16 binary bytes in the PlainText field.

Notes:

  • The size of this request is 119 bytes. The HeaderLength size is 5 bytes, the header size is 98 bytes, and the PlainText size is 16 bytes.

Encrypt CBC response

0003920200000YN00016iiiiiiiiiiiiiiiiiiiiiiiicccccccccccccccc

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2020 is the ResponseID for Encrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 00016 is the CipherTextLength. 16 bytes is the length of the returned ciphertext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • cccccccccccccccc represents the 16 binary bytes in the CipherText field.

Notes:

  • The size of this response is 60 bytes. The HeaderLength size is 5 bytes, the header size is 39 bytes, and the CipherText size is 16 bytes.

Decrypt CBC request

001012021YNBIN00016BINYNYYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiicccccccccccccccc

Where:

  • 00101 is the HeaderLength. 101 bytes is the length of the header for this request.

  • 2021 is the RequestID for Decrypt CBC request.

  • Y is the NewKeyFlag. A new key is used to decrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header.

  • N is the PaddingFlag. The data length was a multiple of 16 bytes and therefore no padding was needed.

  • BIN is the CipherTextFormat. BIN (binary) is the ciphertext format.

  • 00016 is the CipherTextLength. 16 bytes is the length of the ciphertext.

  • BIN is the PlainTextFormat. BIN (binary) is the desired plaintext format.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • Y is the FinalFlag. The server will close the session.

  • Y is the NewIVFlag. A new IV was used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field. Enter blanks to use the current instance.

  • cccccccccccccccc represents the 16 binary bytes in the CipherText field.

Notes:

  • The size of this request is 122 bytes. The HeaderLength size is 5 bytes, the header size is 101 bytes, and the CipherText size is 16 bytes.

Decrypt CBC response

0003920220000YN00016iiiiiiiiiiiiiiiiiiiiiiiipppppppppppppppp

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2022 is the ResponseID for Decrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 00016 is the PlainTextLength. 16 bytes is the length of the returned plaintext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • pppppppppppppppp represents the 16 binary bytes in the PlainText field.

Notes:

  • The size of this response is 60 bytes. The HeaderLength size is 5 bytes, the header size is 39 bytes, and the PlainText size is 16 bytes.

 

Example 2: Encrypt and decrypt a large file

This example shows how you would encrypt and decrypt a file which is too large to send in a single TLS record. The greatest length of plaintext that can be sent in a single request is 16,272 bytes. In this example, a larger file is broken into segments of 16,272 bytes and sent in multiple requests. The example requests and responses below show only the first request and response sent in a session, and do not outline an entire session.

Keep the following considerations in mind:

  • Include the HeaderLength and RequestID fields on the first request in the session, but not on subsequent requests (even if the length of subsequent request headers varies).

  • Set NewKeyFlag to Y on the first request. Set NewKeyFlag to N on subsequent requests.

  • Set NewIVFlag to Y on the first request. Set NewIVFlag to N on subsequent requests.

  • Set PaddingFlag to N on all requests with segments of data of 16,272 bytes. If the last segment of data is not a multiple of 16 bytes, set PaddingFlag to 7 on the final request.

  • Set PlainTextLength to 16272 on all requests except the final request. On the final request, specify the length of the last segment of data in this field.

  • Set FinalFlag to Y on the final request.

Encrypt CBC request

The following example is for the first request in the session (keep the above considerations in mind when formatting subsequent requests):

000982019YNBIN16272YNNYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiippp...

In this example:

  • 00098 is the HeaderLength. 98 bytes is the length of the header for this request.

  • 2019 is the RequestID for Encrypt CBC request.

  • Y is the NewKeyFlag. A new key is used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header.

  • N is the PaddingFlag. The data length is a multiple of 16 bytes and therefore no padding is needed.

  • BIN is the CipherTextFormat. BIN (binary) is the desired ciphertext format.

  • 16272 is the PlainTextLength. 16,272 bytes is the length of the plaintext.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • N is the FinalFlag. The server will keep the session open.

  • Y is the NewIVFlag. A new IV is used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field. Enter blanks to use the current instance.

  • ppp... represents the 16,272 binary bytes in the PlainText field.

Notes:

  • The size of this request is 16,375 bytes. The HeaderLength size is 5 bytes, the header size is 98 bytes, and the PlainText size is 16,272 bytes.

Encrypt CBC response

0003920200000YN16272iiiiiiiiiiiiiiiiiiiiiiiiccc...

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2020 is the ResponseID for Encrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 16272 is the CipherTextLength. 16,272 bytes is the length of the returned ciphertext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • ccc... represents the 16,272 binary bytes in the CipherText field.

Notes:

  • The size of this response is 16,316 bytes. The HeaderLength size is 5 bytes, the header size is 39 bytes, and the CipherText size is 16,272 bytes.

Decrypt CBC request

001012021YNBIN16272BINYNNYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiccc...

Where:

  • 00101 is the HeaderLength. 101 bytes is the length of the header for this request (the length of subsequent headers in the session will vary).

  • 2021 is the RequestID for Decrypt CBC request.

  • Y is the NewKeyFlag. A new key was used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header.

  • N is the PaddingFlag. The data length is a multiple of 16 bytes and therefore no padding is needed.

  • BIN is the CipherTextFormat. BIN (binary) is the ciphertext format.

  • 16272 is the CipherTextLength. 16,272 bytes is the length of the ciphertext.

  • BIN is the PlainTextFormat. BIN (binary) is the desired plaintext format.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • N is the FinalFlag. The server will keep the session open.

  • Y is the NewIVFlag. A new IV was used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field. Enter blanks to use the current instance.

  • ccc... represents the 16,272 binary bytes in the CipherText field.

Notes:

  • The size of this request is 16,378 bytes. The HeaderLength size is 5 bytes, the header size is 101 bytes, and the CipherText size is 16,272 bytes.

Decrypt CBC response

0003920220000YN16272iiiiiiiiiiiiiiiiiiiiiiiippp...

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2022 is the ResponseID for Decrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 16272 is the PlainTextLength. 16,272 bytes is the length of the returned plaintext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • ppp... represents the 16,272 binary bytes in the PlainText field.

Notes:

  • The size of this response is 16,316 bytes. The HeaderLength size is 5 bytes, the header size is 39 bytes, and the PlainText size is 16,272 bytes.

 

Example 3: Encrypt and decrypt pieces of data of variable length

This example shows how you would encrypt and decrypt several pieces of data of variable length, for example, related information on a form (name, address, social security number, etc).

Keep the following considerations in mind:

  • Include the HeaderLength and RequestID fields on the first request, but not on subsequent requests (even if the length of subsequent request headers varies).

  • Set NewKeyFlag to Y on the first request. You can set NewKeyFlag to Y or NewKeyFlag to N on subsequent requests depending on whether or not you want to use the same key.

  • Set NewIVFlag to Y on each request.

  • Set PaddingFlag to Y on all requests. If the data happens to be a multiple of 16 bytes, the server will pad the request with 16 bytes.

  • You will need to specify the PlainTextLength on every request.

  • Set PackedFlag to Y on every request except the final request in the TLS record.

  • Set FinalFlag to Y on the final request.

  • You can send multiple requests in the same TLS record, but the combined length of each piece of data and their corresponding headers cannot exceed 16,384 bytes (the record limit). Be aware that the length of each request and response header will vary depending on whether the request or response is the first sent in a session and whether the NewKeyFlag is set to Y. Depending on the length of each individual requests and whether padding is used, the combined length of the responses may exceed the record limit. If this occurs, the server will send as many responses as possible in the first record, then it will send the rest of the responses in the next record [HD HD] [HD]. At the boundaries of the records, data may be split between a response and a continuation response [HD HD] [HcDc HD], where HcDc represents the continuation header and data).

Encrypt CBC request

The following example is for the first request in the session (keep the above considerations in mind when formatting subsequent requests):

000982019Y7BIN00012YYNYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiipppppppppppp

In this example:

  • 00098 is the HeaderLength. 98 bytes is the length of the header for this request.

  • 2019 is the RequestID for Encrypt CBC request.

  • Y is the NewKeyFlag. A new key is used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header.

  • 7 is the PaddingFlag. The plaintext length is variable and therefore padding is required.

  • BIN is the CipherTextFormat. BIN (binary) is the desired ciphertext format.

  • 00012 is the PlainTextLength. 12 bytes is the length of the plaintext in this request.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • Y is the PackedFlag. The server will pack the responses.

  • N is the FinalFlag. The server will keep the session open.

  • Y is the NewIVFlag. A new IV is used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field. Enter blanks to use the current instance.

  • pppppppppppp represents the 12 binary bytes in the PlainText field.

Notes:

  • The size of this request is 115 bytes. The HeaderLength size is 5 bytes, the header size is 98 bytes, and the PlainText size is 12 bytes.

Encrypt CBC response

0003920200000YY00016iiiiiiiiiiiiiiiiiiiiiiiicccccccccccccccc

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2020 is the ResponseID for Encrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • Y is the PackedFlag. The server has packed the responses.

  • 00016 is the CipherTextLength. 16 bytes is the length of the returned ciphertext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • cccccccccccccccc represents the 16 binary bytes in the CipherText field.

Notes:

  • The size of this response is 60 bytes. The HeaderLength size is 5 bytes, the header size is 39 bytes, and the CipherText size is 16 bytes.

Decrypt CBC request

001012021Y7BIN00016BINYYNYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiicccccccccccccccc

Where:

  • 00101 is the HeaderLength. 101 bytes is the length of the header for this request (the length of subsequent headers in the session will vary).

  • 2021 is the RequestID for Decrypt CBC request.

  • Y is the NewKeyFlag. A new key was used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header.

  • 7 is the PaddingFlag. Padding was required. The server will remove the padding.

  • BIN is the CipherTextFormat. BIN (binary) is the ciphertext format.

  • 00016 is the CipherTextLength. 16 bytes is the length of the ciphertext.

  • BIN is the PlainTextFormat. BIN (binary) is the desired plaintext format.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • Y is the PackedFlag. The server will pack the responses.

  • N is the FinalFlag. The server will keep the session open.

  • Y is the NewIVFlag. A new IV was used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field. Enter blanks to use the current instance.

  • cccccccccccccccc represents the 16 binary bytes in the CipherText field.

Notes:

  • The size of this request is 122 bytes. The HeaderLength size is 5 bytes, the header size is 101 bytes, and the CipherText size is 16 bytes.

Decrypt CBC response

0003920220000YY00012iiiiiiiiiiiiiiiiiiiiiiiipppppppppppp

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2022 is the ResponseID for Decrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • Y is the PackedFlag. The server has packed the responses.

  • 00012 is the PlainTextLength. 12 bytes is the length of the returned plaintext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • pppppppppppp represents the 12 binary bytes in the PlainText field.

Notes:

  • The size of this response is 56 bytes. The HeaderLength size is 5 bytes, the header size is 39 bytes, and the PlainText size is 12 bytes.

 

Chapter 8: AES ECB Specifications

The following tables show fields used in requests and responses in ECB mode. Each row includes the field name, the length of the field in bytes, possible values, and notes. Variable numbers are represented with the lowercase letter “n”.

To formulate requests in ECB mode, use the examples for CBC mode in Chapter 7: AES CBC Examples, omitting the NewIVFlag and IV fields.

Encrypt ECB request

Field Length Value Notes
HeaderLength 5 00081 Included in the first request.
RequestID 4 2015 Included in the first request.
NewKeyFlag 1 Y or N  
PaddingFlag 1 7 or N 7 indicates PKCS #7 padding is required, N indicates no padding is required.
CipherTextFormat 3 BIN, B16, or B64  
PlainTextLength 5 nnnnn  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
KeyName 40 Varies Present if NewKeyFlag is set to Y
Instance 24 Varies Present if NewKeyFlag is set to Y
PlainText Varies* Varies *Up to 16,272 bytes with PaddingFlag set to N. Up to 16,271 bytes with PaddingFlag set to Y.

Encrypt ECB request continuation

Field Length Value Notes
PlainTextLength 5 nnnnn  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y,N  
PlainText Varies* Varies *Up to 16,272 bytes with PaddingFlag set to N. Up to 16,271 bytes with PaddingFlag set to Y.

Encrypt ECB response

The response to the ECB encryption request has the following format:

Field Length Value Notes
HeaderLength 5 00039 Included in the first response.
ResponseID 4 2016 Included in the first response.
Return code 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N If ReturnCode is non-zero, the response ends here.
CipherTextLength 5 nnnnn  
Instance 24 Varies  
CipherText Varies* Varies *Up to 16,272 bytes.

Encrypt ECB response continuation

Field Length Value Notes
Return code 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N  
CipherTextLength 5 nnnnn  
CipherText Varies* Varies *Up to 16,272 bytes.

Decrypt ECB request

Field Length Value Notes
HeaderLength 5 00084 Included in the first request.
RequestID 4 2017 Included in the first request.
NewKeyFlag 1 Y or N  
PaddingFlag 1 7 or x 7 indicates padding should be stripped, N indicates padding should not be stripped.
CipherTextFormat 3 BIN or B16 or B64  
CipherTextLength 5 nnnnn not 00000  
PlainTextFormat 3 BIN or B16 or B64  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
KeyName 40 Varies Present if NewKeyFlag is Y.
Instance 24 Varies Present if NewKeyFlag is Y.
CipherText Varies* Varies *Up to 16,272 bytes.

Decrypt ECB request continuation

Field Length Value Notes
CipherTextLength 5 nnnnn not 00000  
EndOfRequestFlag 1 Y or N  
PackedFlag 1 Y or N  
FinalFlag 1 Y or N  
CipherText Varies* Varies *Up to 16,272 bytes with PaddingFlag set to N. Up to 16,271 bytes with PaddingFlag set to 7.

Decrypt ECB response

Field Length Value Notes
HeaderLength 5 00039 Included in the first response.
ResponseID 4 2018 Included in the first response.
ReturnCode 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N If ReturnCode is non-zero, the response ends here.
PlainTextLength 5 nnnnn not 00000  
Instance 24 Varies Present if NewKeyFlag is Y in corresponding request header.
PlainText Varies* Varies *Up to 16,272 bytes.

Decrypt ECB response continuation

Field Length Value Notes
ReturnCode 4 0000 or nnnn  
EndOfResponseFlag 1 Y or N  
PackedFlag 1 Y or N  
PlainTextLength 5 nnnnn not 00000  
PlainText Varies* Varies *Up to 16,272 bytes.

 

Chapter 9: Using Continuation Headers

Continuation headers are used to accommodate Base16 and Base64 encoding used in encryption and decryption requests. If the returned data exceeds the record limit of 16,384 bytes, the plaintext or ciphertext will be returned in two responses, the second response beginning with a continuation header. Specifications for continuation headers can be found in Chapter 6: AES CBC Specifications and Chapter 8: AES ECB Specifications.

Keep the following considerations in mind when working with continuation headers:

  • On the initial request header, set EndOfRequestFlag to N. On the request continuation header, set EndOfRequestFlag to Y.

  • On the initial response header, EndOfResponseFlag will be set to N. On the response continuation header, EndOfResponseFlag will be set to Y.

  • When using padding, the plaintext or ciphertext associated with the initial header must be a multiple of 16 bytes in length. Set PaddingFlag to 7 on the initial header.

The following example shows the use of continuation headers to accommodate Base16 encoding in an encryption request. In this example, a request is sent to encrypt 16,272 bytes of data with Base16 encoding. The AKM server encrypts the plaintext data and splits the resulting ciphertext into two separate responses sent in separate TLS records, the second response preceded by a continuation header. On the decryption request, two separate requests are sent in separate TLS records, the second request preceded by a continuation header.

Encrypt CBC request

000982019YNB1616272YNYYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiippp...

In this example:

  • 00098 is the HeaderLength. 98 bytes is the length of the header for this request.

  • 2019 is the RequestID for Encrypt CBC request.

  • Y is the NewKeyFlag. A new key is used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header, and NewIVFlag must be set to Y.

  • N is the PaddingFlag. The data length is a multiple of 16 bytes and therefore no padding is needed.

  • B16 is the CipherTextFormat. Base16 is the desired ciphertext format.

  • 16272 is the PlainTextLength. 16,272 bytes is the length of the plaintext.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • Y is the FinalFlag. The server will close the session after sending the response.

  • Y is the NewIVFlag. A new IV is used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • ppp... represents the 16,272 binary bytes in the PlainText field.

Encrypt CBC response

0003920200000NN16272iiiiiiiiiiiiiiiiiiiiiiiiccc...

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2020 is the ResponseID for Encrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • N is the EndOfResponseFlag. A continuation header will follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 16340 is the CipherTextLength. 16,340 bytes is the length of the returned ciphertext in this response.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • ccc... represents the 16,340 Base16 bytes in the CipherText field.

Encrypt CBC response continuation

0000YN16272ccc...

Where:

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 16204 is the CipherTextLength. 16,204 bytes is the length of the returned ciphertext in the continuation response.

  • ccc... represents the 16,204 Base16 bytes in the CipherText field.

Decrypt CBC request

001012021YNB1616272BINNNYYvvvvvvvvvvvvvvvvkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiccc...

Where:

  • 00101 is the HeaderLength. 101 bytes is the length of the header for this request.

  • 2021 is the RequestID for Decrypt CBC request.

  • Y is the NewKeyFlag. A new key was used to encrypt. The 40-byte KeyName field and the 24-byte Instance fields are included in the header.

  • N is the PaddingFlag. The data length was a multiple of 16 bytes and therefore no padding was needed.

  • B16 is the CipherTextFormat. Base16 is the ciphertext format.

  • 16272 is the CipherTextLength. 16,272 bytes is the length of the ciphertext.

  • BIN is the PlainTextFormat. BIN (binary) is the desired plaintext format.

  • N is the EndOfRequestFlag. A continuation header will follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • N is the FinalFlag. The server will not close the session.

  • Y is the NewIVFlag. A new IV was used.

  • vvvvvvvvvvvvvvvv represents the 16-binary bytes of the IV field.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the 40-byte KeyName field

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • ccc... represents the 16,272 B16 bytes in the CipherText field.

Decrypt CBC request continuation

16272YNYccc...
  • 16272 is the CipherTextLength. 16,272 bytes is the length of the ciphertext.

  • Y is the EndOfRequestFlag. A continuation header will not follow this request.

  • N is the PackedFlag. The server will not pack the responses.

  • Y is the FinalFlag. The server will close the session after sending the response.

  • ccc... represents the 16,272 B16 bytes in the CipherText field.

Decrypt CBC response

0003920220000YN16272iiiiiiiiiiiiiiiiiiiiiiiipppppppppppppppp

Where:

  • 00039 is the HeaderLength. 39 bytes is the length of the header for this response.

  • 2022 is the ResponseID for Decrypt CBC response.

  • 0000 is the ReturnCode. There were no errors.

  • Y is the EndOfResponseFlag. A continuation header will not follow this response.

  • N is the PackedFlag. The server has not packed the responses.

  • 16272 is the PlainTextLength. 16,272 bytes is the length of the returned plaintext.

  • iiiiiiiiiiiiiiiiiiiiiiii represents the 24-byte Instance field.

  • ppp... represents the 16,272 binary bytes in the PlainText field.

Chapter 10: Encrypt with RSA Public Key and Decrypt with RSA Private Key Specifications

The following tables show fields used in requests and responses for encrypting with an RSA public key and decrypting with an RSA private key.

Each row includes the field name, the length of the field in bytes, possible values, and notes. Variable numbers are represented with the lowercase letter “n”.

Encrypt with RSA Public Key request

Field Length Value Notes
HeaderLength 5 00074 The length of the remainder of the request in bytes, except the Plaintext field.
RequestID 4 2031 The ID of this request.
KeyName 40 Varies The name of the key to be used to encrypt the data, blank padded on the right. May be be all blanks if Instance is provided.
Instance 24 Varies The instance to be used to encrypt the data. May be all blanks if KeyName is provided.
RSAPaddingMode 1 1 or 2 1 indicates RSA PKCS1 padding. 2 indicates RSA PKCS1 OAEP padding.
PlainTextLength 5 nnnnn not 00000 The length of the PlainText field in bytes.
PlainText Varies* Varies *Up to 16,272 bytes of binary data.

Encrypt with RSA Public Key response

Field Length Value Notes
HeaderLength 5 00037 The length of the remainder of the response in bytes, except the CipherText field.
ResponseID 4 2032 The ID of this response.
ReturnCode 4 0000 or nnnn 0000 indicates success. nnnn indicates an error condition.
Instance 24 Varies The instance of the key that was used to encrypt.
CipherTextLength 5 nnnnn not 00000 The length of the CipherText field in bytes.
CipherText Varies * Varies *Up to 16,272 bytes of binary data.

Decrypt with RSA Private Key request

Field Length Value Notes
HeaderLength 5 00074 The length of the remainder of the request in bytes, except the CipherText field.
RequestID 4 2029 The ID of this request.
KeyName 40 Varies The name of the key to be used to decrypt the data, blank padded on the right. May be be all blanks if Instance is provided.
Instance 24 Varies The instance to be used to decrypt the data. May be all blanks if KeyName is provided.
RSAPaddingMode 1 1 or 2 1 indicates RSA PKCS1 padding. 2 indicates RSA PKCS1 OAEP padding.
CipherTextLen 5 nnnnn not 00000 The length of the CipherText field in bytes.
CipherText Varies* Varies *Up to 16,272 bytes of binary data.

Decrypt with RSA Private Key response

Field Length Value Notes
HeaderLength 5 00037 The length of the remainder of the response in bytes, except the Plaintext field.
ResponseID 4 2030 The ID of this response.
ReturnCode 4 0000 or nnnn 0000 indicates success. nnnn indicates an error condition.
Instance 24 Varies The instance of the key that was used to decrypt.
PlainTextLen 5 nnnnn not 00000 The length of the PlainText field in bytes.
PlainText Varies* Varies *Up to 16,272 bytes of binary data.

Chapter 11: Encrypt with RSA Private Key and Decrypt with RSA Public Key Specifications

The following tables show fields used in requests and responses for encrypting with an RSA private key and decrypting with an RSA public key.

Each row includes the field name, the length of the field in bytes, possible values, and notes. Variable numbers are represented with the lowercase letter “n”.

Encrypt with RSA Private Key request

Field Length Value Notes
HeaderLength 5 00074 The length of the remainder of the request in bytes, except the Plaintext field.
RequestID 4 2027 The ID of this request.
KeyName 40 Varies The name of the key to be used to encrypt the data, blank padded on the right. May be be all blanks if Instance is provided.
Instance 24 Varies The instance to be used to encrypt the data. May be all blanks if KeyName is provided.
RSAPaddingMode 1 1 1 indicates RSA PKCS1 padding. RSA PKCS1 padding is the only padding mode supported for this request.
PlainTextLength 5 nnnnn not 00000 The length of the PlainText field in bytes.
PlainText Varies* Varies *Up to 16,272 bytes of binary data.

Encrypt with RSA Private Key response

Field Length Value Notes
HeaderLength 5 00037 The length of the remainder of the response in bytes, except the CipherText field.
ResponseID 4 2028 The ID of this response.
ReturnCode 4 0000 or nnnn 0000 indicates success. nnnn indicates an error condition.
Instance 24 Varies The instance of the key that was used to encrypt.
CipherTextLength 5 nnnnn not 00000 The length of the CipherText field in bytes.
CipherText Varies * Varies *Up to 16,272 bytes of binary data.

Decrypt with RSA Public Key request

Field Length Value Notes
HeaderLength 5 00074 The length of the remainder of the request in bytes, except the CipherText field.
RequestID 4 2033 The ID of this request.
KeyName 40 Varies The name of the key to be used to decrypt the data, blank padded on the right. May be be all blanks if Instance is provided.
Instance 24 Varies The instance to be used to decrypt the data. May be all blanks if KeyName is provided.
RSAPaddingMode 1 1 1 indicates RSA PKCS1 padding. RSA PKCS1 padding is the only padding mode supported for this request.
CipherTextLen 5 nnnnn not 00000 The length of the CipherText field in bytes.
CipherText Varies* Varies *Up to 16,272 bytes of binary data.

Decrypt with RSA Public Key response

Field Length Value Notes
HeaderLength 5 00037 The length of the remainder of the response in bytes, except the Plaintext field.
ResponseID 4 2034 The ID of this response.
ReturnCode 4 0000 or nnnn 0000 indicates success. nnnn indicates an error condition.
Instance 24 Varies The instance of the key that was used to decrypt.
PlainTextLen 5 nnnnn not 00000 The length of the PlainText field in bytes.
PlainText Varies* Varies *Up to 16,272 bytes of binary data.

Appendix A: Glossary

Base16

Base16 is a method of expressing data in hex format. The hex format uses two ASCII characters in the range of 0 to 9 and A to F to express any single byte of data.

Base64

Base64 encoding is a method of expressing binary data in a character format. It is one of the supported formats for encryption. See RFC 4648 for a definition of Base64 encoding and decoding.

Certificate authority (CA) certificate

A certificate authority is an entity or application responsible for creating client and server keys and certificates. The certificate authority creates a CA certificate for use by the client and server and defines the trust of the certificate chain. You can use AKM Certificate Manager to create all of the required certificates and private keys, or you can use a public entity such as Verisign or commercial key management software or open source software such as OpenSSL. If you are deploying a virtual or cloud AKM server, the required certificates are automatically created on the AKM server. The CA certificate used by AKM must be installed on the client.

Client certificate

A client certificate and private key signed by AKM’s CA certificate identifies the client end point in the TLS communication between the client and the AKM server. The client certificate and private key must be installed on the client in addition to the CA certificate.

Encryption key

The encryption key is the actual binary value used for encryption operations. It can be 128 bits (16 bytes), 192 bits (24 bytes), or 256 bits (32 bytes) in length. The encryption key will be one of the input variables to your encryption or decryption routines.

Key name and instance

Each encryption key is defined by its key name and its instance name. When a key is created the Crypto Officer provides a key name of 1 to 40 characters in length. The instance name is created automatically. Every time the key is rolled, a new instance (version) of the key is created, but the key name remains the same. The key name is used in conjunction with the key instance name to encrypt and decrypt on the AKM server.

Server certificate

A server certificate signed by AKM’s CA certificate identifies the AKM server end point in the TLS communication between the client and the AKM server.

Transport Layer Security (TLS)

TLS is the open standard for secure and authenticated TCP communications between two end points. It is used for the most secure connection requirements in VPN, web browser, and other end-to-end communications where both privacy and authentication are required.

 

Appendix B: Programming Best Practices

When developing applications that perform encryption tasks, you should follow certain generally accepted programming practices to protect against the loss of sensitive information. The following sections provide basic information about best practices for secure programming. There are many other resources available on this subject. You should consult with a security expert if you have any questions about how to implement security in your business application.

Implement error handling

All Alliance key retrieval and encryption routines provide a return code indicating the success or failure of the operation. Your applications should always inspect the return code and take appropriate action if an error occurs. You should never use a value returned in a response that is in an error state.

Clear memory after use

When you finish using an encrypted or plaintext value, be sure to initialize the memory used by the variable. You should overwrite the memory area of the value with random values a minimum of 10 times and free any allocated memory.

Programming for security

Be aware of the general principles of secure programming. The Open Web Application Security Project (OWASP) (www.owasp.org) has published guidelines on secure network programming. See the following website for information on the “Top 10” recommendations for secure programming:

Implement exception handling

Programs that fail when an unexpected error occurs may leave sensitive data in memory or on disk. Be sure that you trap and handle all error conditions that your application may encounter.

Error notification

All Alliance Key Manager operations return a success or failure code. Your applications should always inspect the return code and handle any error you encounter. Never ignore an error code as this may lead to corrupt data and unpredictable results.