AKM Encryption Service API Reference

Page Information

Last updated: 10.14.2016

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.

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:

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.

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.

Chapter 3: Introduction

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:

Format a request in your application to perform encryption or decryption

Open a TCP connection to the AKM server

Secure the connection with TLS

Send the request to the AKM server

Receive a response from the AKM server

Close the connection to the AKM server

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:

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:

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

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

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

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

Decrypt CBC request

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

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

Decrypt with RSA Public Key response

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.