Chapter 1: About This Manual

AKM Key Service API

Key retrieval allows a user to retrieve encryption keys from the AKM server to encrypt and decrypt sensitive data in client applications. The AKM Key Service API defines a standard interface to the AKM Key Service so clients can build custom implementations.

Key retrieval is performed via a secure TLS connection to the AKM server and both the client and server end-points are authenticated via the TLS protocol.

The AKM Key Service API supports the retrieval of symmetric AES keys and asymmetric RSA keys.

Who is this for?

This guide is designed for developers who will write their own interface to the AKM Key Service API. 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.
2.1.13.001 9/17/2013 New manual format.
3.0.0.001 10/1/2014 Update and revise for AKM 3.0.0. Name change from “AKM Key Retrieval Interface Reference“ to “AKM Key Service API Reference”.
3.0.3.001 12/22/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/18/2016 Add asymmetric RSA key APIs.

Chapter 2: Preparation

Overview

Before setting up key retrieval 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 key retrieval (the default is 6000)

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.

Certificates

The client and AKM server use certificate 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 key retrieval services on AKM (the default is 6000)

Encryption keys

There are four options for retrieving encryption keys: The “Get Symmetric Key” command and the “Get Next Key” commands retrieve symmetric encryption keys. The “Get RSA Private Key” and “Get RSA Public Key” commands retrieve asymmetric RSA keys.

Get Symmetric Key

The Get Symmetric Key command retrieves a specific encryption key. Most applications will use this command to retrieve keys. If using this command, you must know the name of the encryption key(s) you want to retrieve from the AKM server.

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.

Get Next Key

You will use the Get Next Key command if you have created a series of encryption keys based on a template. The command to generate a key template is the “Automatically Generate Keys” admin command; more information can be found in the AKM Administrative Console Guide.

In this case, the Get Next Key command retrieves the next available encryption key in the series. You will need to know the Constant, IncrementLength, IncrementCode, and ConstantLength field values that were used in the Automatically Generate Keys command to create the template. You will enter these values when using the Get Next Key command.

Get RSA Private Key and Get RSA Public Key

These commands retrieve either an RSA private key or an RSA public key from the AKM server. You will need to know the name of the RSA key pair assigned when the key pair was created.

Since RSA keys are created in pairs containing both a public and a private key, the key name for both the private and the public key in the pair is the same. Use the Admin Console or the AKM Admin API to display the list of RSA keys on the server, or to create new RSA keys.

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 key retrieval services port number (the default is 6000)

  • The name of one or more encryption keys on the AKM server (if simply retrieving keys) and/or the key template information (if you have used a key template to generate a series of symmetric keys)

Chapter 3: Introduction

This chapter covers general information about the AKM Key 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 Key Service API uses a client/server request/response architecture. This means that every time the application (the client) sends a request to the AKM server, the AKM server returns a response.

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 sessions

A TLS session is the period of time during which the TLS connection between the client and the server is open and requests and responses can be exchanged. 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.

Key retrieval commands

There are two commands that retrieve symmetric encryption keys and two commands that retrieve asymmetric RSA keys.

Most applications that need to retrieve symmetric keys use the Get Symmetric Key command to retrieve encryption keys. The Get Next Key command is only used in conjunction with the Automatically Generate Keys admin command which creates a number of keys based on a template. If you would like to retrieve these keys, you must use the Get Next Key command to retrieve the next available key in the series created by the template.

For information on the Automatically Generate Keys command, see the AKM Administrative Console Guide if you are using the AKM Administrative Console to generate keys. See the AKM Admin API Reference if you are using the AKM Admin API to generate keys.

Applications that need to retrieve asymmetric RSA keys will use the Get RSA Public Key or Get RSA Private Key commands, depending on whether they need to retrieve the public or the private key in the RSA key pair.

Requests and responses

To retrieve a key, you will send a key retrieval request to the AKM server (Get Symmetric Key or Get Next Key). The AKM server returns a response. Requests contain fixed-length fields in a specific order which give information about the encryption key to be retrieved. Responses contain these fields in addition to the actual key value.

This gives the following types of requests and responses:

  • Get Symmetric Key request

  • Get Symmetric Key response

  • Get Next Key request

  • Get Next Key response

  • Get RSA Public Key request

  • Get RSA Public Key response

  • Get RSA Private Key request

  • Get RSA Private Key response

After the response is sent, the server will close the session. If the server encounters an error, it will send the part of the response containing the error code and close the session. See the following chapters for command specifications and examples.

Data formats

The AKM Key Service API uses US-ASCII format (printable character set, ANSI X3.4-1986) for field values in requests and responses, except for the actual key value. US-ASCII data uses one character per byte.

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

Asymmetric key data (public or private RSA keys) can only be returned in DER format.

Key lengths

When you request a symmetric encryption key, you indicate the desired key format. A symmetric key can be returned in binary, Base16, or Base64 format. Asymmetric keys are returned in DER (binary) format.

The response indicates the key size in bits, the key format, and contains the actual key value. Symmetric key values are padded on the right with blanks to 128 bytes. Asymmetric key values are not padded.

For symmetric keys, the number of significant digits in the key value is determined by the key format:

  • If binary is the requested key format:

    • A 128-bit key will be 16 bytes

    • A 192-bit key will be 24 bytes

    • A 256-bit key will be 32 bytes

  • If Base16 is the requested key format:

    • A 128-bit key will be 32 bytes

    • A 192-bit key will be 48 bytes

    • A 256-bit key will be 64 bytes

  • If Base64 is the requested key format:

    • A 128-bit key will be 24 bytes

    • A 192-bit key will be 32 bytes

    • A 256-bit key will be 44 bytes

Asymmetric RSA public and private keys may only be requested in DER format:

  • A 1024-bit key will be 610 bytes

  • A 2048-bit key will be 1191 bytes

  • A 3072-bit key will be 1769 bytes

  • A 4096-bit key will be 2350 bytes

Key names and key instances

Every symmetric encryption key created by AKM is given a key name and a unique key 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 new 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 friendly 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 revoke or 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 request an encryption key from the AKM server, you must specify the key name and/or key instance. If you specify the key name and set the instance name to blanks (24 space characters), AKM will return the current instance of the key. The returned instance name can then be stored in a column with the encrypted data and used on decryption. If you set the key name to blanks and specify the instance name, AKM will return blanks for the key name. You can do this if you do not want to store the 40-byte KeyName in addition to the 24-byte Instance name.

Return codes

Responses contain a return code which 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 ReturnCode field is discarded and the session is closed. A key is never returned in a response that is in an error state. See the AKM Error Codes Reference for more information.

Encryption

When using encryption keys, be sure to use encryption software that has a known provenance and which has been certified for accuracy. The vendor of the encryption software should be able to provide you with proof of certification by NIST or other independent assessment facility.

Procedures

Use the following process to enable your client applications to retrieve a key from the AKM server:

  1. Format a request to retrieve a key in your application

  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: The Get Symmetric Key Command

The Get Symmetric Key command retrieves an encryption key from the AKM server. Most applications will use this command to retrieve keys. You can retrieve keys in binary, Base64, or Base16 (hex) formats.

See below for Get Symmetric Key specifications. For an example request and response, see Get Symmetric Key example.

Get Symmetric Key specifications

The following tables show the fields used in the Get Symmetric Key request and response.

Keep the following general considerations in mind:

  • Fields are listed in the order they will be formatted in the request and response.

  • Each row includes the field name, the length of the field in bytes, possible values, and informational notes.

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

  • Request and response fields have a fixed length.

  • Request and response fields are in US-ASCII format, except for the KeyValue field.

  • The KeyValue field (the actual key value) can be returned in binary, Base16, or Base64 format

  • Variable numbers are represented with the lowercase letter “n”.

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

Get Symmetric Key request

Field Length Value Notes
HeaderLength 5 00071 The length of the remainder of the request.
RequestID 4 2001 Identifies the type of request.
KeyName 40   Blank right padded. Indicates the name of the desired key. Leave blank and specify the Instance if you do not want to store the 40-byte KeyName field.
Instance 24   Indicates the desired key instance.Use all blanks for the current instance.
KeyFormat 3 BIN, B16 or B64 Indicates the desired key format.

Get Symmetric Key response

Field Length Value Notes
HeaderLength 5 00351 The length of the remainder of the response.
ResponseID 4 2002 Identifies the type of response.
ReturnCode 4 0000 or nnnn Value 0000 indicates success. Values 0001 to 9999 represent error conditions.
KeyName 40   Blank right padded. Indicates the key name.
Instance 24   Indicates the key instance.
LastRolloverDate 8 nnnnnnnn or 00000000 CCYYMMDD format. Indicates the date that the returned key instance was created via rollover of the original key. The date that the new instance is created is the LastRolloverDate. 00000000 is returned if the key has never been rolled (i.e. if it is the original key).
ExpirationDate 8 nnnnnnnn or 00000000 CCYYMMDD format. This field indicates the expiration date of the key. 00000000 will be returned if the key is non-expiring.
KeySizeBits 4 0128, 0192, or 0256 The size of the key in bits.
KeyFormat 3 BIN, B16 or B64 The format of the key.
KeyValue 128   The actual key value, blank right padded.
Reserved 128   A reserved field of null characters.

 

Get Symmetric Key example

The following example shows how to format a Get Symmetric Key request and how to read a Get Symmetric Key response. Characters (k, i, etc) are used to represent actual values.

Get Symmetric Key request

This example shows a Get Symmetric Key request:

000712001kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiBIN

In this example:

  • 00071 is the HeaderLength field (the length of the request excluding the HeaderLength field in bytes).

  • 2001 is the RequestID field. This identifies the type of request.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the KeyName field containing the 40-byte key name, blank-padded on the right if less than 40 bytes (for example, Key1 )

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

  • BIN is the KeyFormat field. Binary is the desired key format.

Get Symmetric Key response

This example shows a Get Symmetric Key response:

0035120020000kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiirrrrrrrreeeeeeeessssBINddd...RRR...

In this example:

  • 00351 is the HeaderLength field (the length of the response excluding the HeaderLength field in bytes).

  • 2002 is the ResponseID field.

  • 0000 is the ReturnCode field. There were no errors.

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

  • rrrrrrrr This represents the LastRolloverDate field.

  • eeeeeeee This represents the ExpirationDate field

  • ssss This represents the KeySizeBits field.

  • BIN is the KeyFormat field. Binary is the key format.

  • ddd... represents the 128-byte KeyValue field. This is the actual value of the key.

  • RRR... represents the 128-byte Reserved field.

Chapter 5: The Get Next Key Command

Most application will use the Get Symmetric Key command documented above. However, if you use the Automatically Generate Keys admin command to generate a number of symmetric keys based on a template, you must use the Get Next Key command to retrieve those keys. The Get Next Key command retrieves the next available key in the series created by the template. You can retrieve keys in binary, Base64, or Base16 (hex) formats.

You can use the Automatically Generate Keys command in the AKM Administrative Console or in your own administrative application built using the AKM Admin API to generate a key template. For more information, see the AKM Administrative Console Guide or the AKM Admin API Reference, respectively.

See below for information on fields and specifications used in the Get Next Key command. For an example of using the Get Next Key command, see Get Next Key Example.

Get Next Key specifications

The following tables show the fields used in the Get Symmetric Key request and response.

Keep the following general considerations in mind:

  • Fields are listed in the order they will be formatted in the request and response.

  • Each row includes the field name, the length of the field in bytes, possible values, and notes.

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

  • Request and response fields have a fixed length.

  • Request and response fields are in US-ASCII format, except for the KeyValue field.

  • The KeyValue field (the actual key value) can be returned in binary, Base16, or Base64 format

  • Variable numbers are represented with the lowercase letter “n”.

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

  • The Constant, IncrementLength, IncrementCode, and ConstantLength field values must match the corresponding field values of the template created using the Automatically Generate Keys admin command. These field values are how AKM determines the template from which to retrieve the next available key.

Get Next Key request

This command requests the next key in an auto-key generation series.

Field Length Value Notes
HeaderLength 5 00051 The length of the remainder of the request.
RequestID 4 2003 Identifies the type of request.
Constant 39   This field indicates the base of the name used in the template for auto-generated keys. For example, if the Constant value is Key (blank padded on the right to 40 bytes), all of the key names will be based on Key and will be followed by an increment value to differentiate each key. Since the increment length has to be at least 1 byte, the Constant can be a maximum of 39 bytes to create a 40-byte key name.
IncrementLength 2 nn This field indicates how many incrementing characters will be added to the Constant field. For example, if the IncrementLength is 02, a two-byte increment will be added to the Constant field to create the key names. The maximum value will be 40 minus the value of ConstantLength.
IncrementCode 1 A, H, or N This field indicates the type of incrementing to be performed. A indicates Alpha Numeric (0-9, A-Z, a-z). Incrementing from numbers to upper case letters then lower case letters. (The same as the appearance of the character in the ASCII table). H indicates Hex digits (0-9, A-F upper case only). N indicates Numeric (0-9). For example, if the Constant value is Key, IncrementLength is 02, and A is selected for IncrementCode, keys will be named Key00, Key01...KeyAA, KeyBB...Keyaa, Keybb, etc. If H is selected, keys will be named Key00, Key01...KeyAA, KeyBB...KeyFF. If N is selected, keys will be named Key00, Key01, etc.
ConstantLength 2 00 to 39 Indicates the length of the Constant field value. For example, if the Constant value is Key (blank padded on the right to 40 bytes), the ConstantLength will be 03. Values in this field must be in the range of 00 – 39.
KeyFormat 3 BIN, B16 or B64 Indicates the key format.

Get Next Key response

Field Length Value Notes
HeaderLength 5 00263 The length of the remainder of the response.
ResponseID 4 2004 Identifies the type of response.
ReturnCode 4 0000 or nnnn Value 0000 indicates success. Values 0001 to 9999 represent error conditions.
KeyName 40   Blank right padded. Indicates the key name.
Instance 24   Indicates the key instance.
LastRolloverDate 8   CCYYMMDD format. Indicates the date that the returned key instance was created via rollover of the original key. The date that the new instance is created is the LastRolloverDate. it is assigned a date of creation. 00000000 is returned if the key has never been rolled (i.e. if it is the original key).
ExpirationDate 8   CCYYMMDD format. This field indicates the expiration date of the key. 00000000 will be returned if the key is non-expiring.
KeySizeBits 4 0128, 0192, or 0256 The size of the key in bits.
KeyFormat 3 BIN, B16 or B64 The format of the key.
KeyValue 128   The actual key value, blank right padded.
LastIncrement 40   This field indicates the last key name created by the template. For example, if the Constant value is Key, IncrementLength is 02, N (numeric) is selected for IncrementCode, and three keys were created, the keys will be named Key00, Key01, and Key02. The last increment value in the template will be Key02 (blank padded on the right to 40 bytes).

 

Get Next Key example

The following example shows how to format a Get Next Key request and how to read a Get Next Key response. Characters (k, i, etc) are used to represent actual values.

Get Next Key request

000512003CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCiiIccBIN

In this example:

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

  • 2003 is the RequestID field.

  • CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC represents the Constant field. This is the 39-byte name used as the base for key names in the template.

  • ii represents the IncrementLength field.

  • I represents the IncrementCode field.

  • cc represents the ConstantLength field.

  • BIN is the KeyFormat field. Binary is the desired key format.

Get Next Key response

0026320040000kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiirrrrrrrreeeeeeeessssBINddd...LLL...

In this example:

  • 00263 is the HeaderLength field (the length of the response excluding the HeaderLength field in bytes).

  • 2004 is the ResponseID field.

  • 0000 is the ReturnCode field. There were no errors.

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

  • rrrrrrrr This represents the LastRolloverDate field.

  • eeeeeeee This represents the ExpirationDate field

  • ssss This represents the KeySizeBits field.

  • BIN is the KeyFormat field. Binary is the key format.

  • ddd... represents the 128-byte KeyValue field. This is the actual value of the key.

  • LLL... represents the 40-byte LastIncrement field.

Chapter 6: Get RSA Private Key

The Get RSA Private Key command retrieves an RSA private key from the AKM server in DER format.

See below for Get RSA Private Key specifications. For an example request and response, see Get RSA Private Key example.

Get RSA Private Key specifications

The following tables show the fields used in the Get RSA Private Key request and response.

Keep the following general considerations in mind:

  • Fields are listed in the order they will be formatted in the request and response.

  • Each row includes the field name, the length of the field in bytes, possible values, and informational notes.

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

  • Request and response fields have a fixed length.

  • Request and response fields are in US-ASCII format, except for the KeyValue field.

  • The KeyValue field (the actual key value) can only be returned in DER encoded format

  • Variable numbers are represented with the lowercase letter “n”.

  • Fields that may require padding are left-padded with zeros (0), except the KeyNamefield, which is padded on the right with blanks.

Get RSA Private Key request

Field Length Value Notes
HeaderLength 5 00071 The length of the remainder of the request.
RequestID 4 2025 Identifies the type of request.
KeyName 40   Blank right padded. Indicates the name of the desired key. Leave blank and specify the Instance if you do not want to store the 40-byte KeyName field.
Instance 24   Indicates the key instance. Either the KeyName or the Instance (or both) may be specified.
KeyFormat 3 DER Indicates the key format.

Get RSA Private Key response

Field Length Value Notes
HeaderLength 5 00093 The length of the remainder of the response, except for the KeyValue.
ResponseID 4 2026 Identifies the type of response.
ReturnCode 4 0000 or nnnn Value 0000 indicates success. Values 0001 to 9999 represent error conditions.
KeyName 40   Blank right padded. Indicates the key name.
Instance 24   Indicates the key instance.
KeyFormat 3 DER The format of the key.
ExpirationDate 8 nnnnnnnn or 00000000 CCYYMMDD format. This field indicates the expiration date of the key. 00000000 will be returned if the key is non-expiring.
KeySizeBits 5 01024, 02048, 03072, or 04096 The size of the key in bits.
KeyLenBytes 5 00610, 01191, 01769, or 02350 The number of bytes in the DER encoded private key. If the key is 1024-bits the field length is 610 bytes, if the key is 2048-bits the length is 1191 bytes, if the key is 3072-bits the length is 1769 bytes, and if the key is 4096-bits the length is 2350 bytes. These values may vary slightly.
KeyValue varies   The actual key value.

<a name=get_rsa_private_example" > </a>

Get RSA Private Key example

The following example shows how to format a Get RSA Private Key request and how to read a Get RSA Private Key response. Characters (k, i, etc) are used to represent actual values.

Get RSA Private Key request

This example shows a Get RSA Private Key request:

000712025kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiDER

In this example:

  • 00071 is the HeaderLength field (the length of the request excluding the HeaderLength field in bytes).

  • 2025 is the RequestID field. This identifies the type of request.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the KeyName field containing the 40-byte key name, blank-padded on the right if less than 40 bytes (for example, Key1 ).

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

  • DER is the KeyFormat field.

Get RSA Private Key response

This example shows a Get RSA Private Key response:

0009320260000kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiDEReeeeeeeessssslllllddd...

In this example:

  • 00093 is the HeaderLength field (the length of the response excluding the HeaderLength field in bytes).

  • 2026 is the ResponseID field.

  • 0000 is the ReturnCode field. There were no errors.

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

  • DER is the KeyFormat field.

  • eeeeeeee This represents the ExpirationDate field

  • sssss This represents the KeySizeBits field.

  • lllll This represents the KeyLenBytes field.

  • ddd... represents the KeyValue field. This is the actual value of the key.

Chapter 7: Get RSA Public Key

The Get RSA Public Key command retrieves an RSA public key from the AKM server in DER format.

See below for Get RSA Public Key specifications. For an example request and response, see Get RSA Public Key example.

Get RSA Public Key specifications

The following tables show the fields used in the Get RSA Public Key request and response.

Keep the following general considerations in mind:

  • Fields are listed in the order they will be formatted in the request and response.

  • Each row includes the field name, the length of the field in bytes, possible values, and informational notes.

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

  • Request and response fields have a fixed length.

  • Request and response fields are in US-ASCII format, except for the KeyValue field.

  • The KeyValue field (the actual key value) can only be returned in DER encoded format

  • Variable numbers are represented with the lowercase letter “n”.

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

Get RSA Public Key request

Field Length Value Notes
HeaderLength 5 00071 The length of the remainder of the request.
RequestID 4 2023 Identifies the type of request.
KeyName 40   Blank right padded. Indicates the name of the desired key. Leave blank and specify the Instance if you do not want to store the 40-byte KeyName field.
Instance 24   Indicates the key instance. Either the KeyName or the Instance (or both) may be specified.
KeyFormat 3 DER Indicates the key format.

Get RSA Public Key response

Field Length Value Notes
HeaderLength 5 00085 The length of the remainder of the response, except for the KeyValue.
ResponseID 4 2024 Identifies the type of response.
ReturnCode 4 0000 or nnnn Value 0000 indicates success. Values 0001 to 9999 represent error conditions.
KeyName 40   Blank right padded. Indicates the key name.
Instance 24   Indicates the key instance.
KeyFormat 3 DER The format of the key.
ExpirationDate 8 nnnnnnnn or 00000000 CCYYMMDD format. This field indicates the expiration date of the key. 00000000 will be returned if the key is non-expiring.
KeySizeBits 5 01024, 02048, 03072, or 04096 The size of the key in bits.
KeyLenBytes 5 00140, 00270, 00398, or 00526 The number of bytes in the DER encoded public key. If the key is 1024-bits the field length is 140 bytes, if the key is 2048-bits the length is 270 bytes, if the key is 3072-bits the length is 398 bytes, and if the key is 4096-bits the length is 526 bytes.
KeyValue varies   The actual key value.

<a name=get_rsa_public_example" > </a>

Get RSA Public Key example

The following example shows how to format a Get RSA Public Key request and how to read a Get RSA Public Key response. Characters (k, i, etc) are used to represent actual values.

Get RSA Public Key request

This example shows a Get RSA Public Key request:

000712023kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiDER

In this example:

  • 00071 is the HeaderLength field (the length of the request excluding the HeaderLength field in bytes).

  • 2023 is the RequestID field. This identifies the type of request.

  • kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk represents the KeyName field containing the 40-byte key name, blank-padded on the right if less than 40 bytes (for example, Key1 ).

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

  • DER is the KeyFormat field.

Get RSA Public Key response

This example shows a Get RSA Public Key response:

0008320240000kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkiiiiiiiiiiiiiiiiiiiiiiiiDEReeeeeeeessssslllllddd...

In this example:

  • 00083 is the HeaderLength field (the length of the response excluding the HeaderLength field in bytes).

  • 2024 is the ResponseID field.

  • 0000 is the ReturnCode field. There were no errors.

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

  • DER is the KeyFormat field.

  • eeeeeeee This represents the ExpirationDate field

  • sssss This represents the KeySizeBits field.

  • lllll This represents the KeyLenBytes field.

  • ddd... represents the KeyValue field. This is the actual value of the key.

Appendix A: Glossary

Activation date

The activation date is the first date on which the encryption key is available for use. The format of the activation date is CCYYMMDD (century, month, year, day).

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 retrieving encryption keys. 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 AKM for VMware, Microsoft Azure, or Amazon Web Services, all of the required certificates are created automatically on the AKM server on initialization and you do not need to follow the steps in this guide for creating a certificate authority (CA) certificate, client certificates, and admin certificates.

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.

Expiration date

The expiration date is the date on which the encryption key is no longer available for retrieval and use for encryption and decryption operations. The format of the activation date is CCYYMMDD (century, month, year, day).

Key format

When you retrieve an encryption key you can specify one of three formats: BIN (binary), B16 (Base16 or hex), and B64 (Base64 encoded).

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 and the old instances are retained on AKM for decryption purposes. The key name is used in conjunction with the key instance name to retrieve a key from 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.

 

Appendix B: Programming Best Practices

When developing applications that retrieve encryption keys, 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.

Do not store encryption keys in non-volatile storage

When retrieving encryption keys, avoid storing an encryption key in non-volatile storage such as a disk file after retrieval.

Protect encryption keys in program memory

If you must store a key for a period of time, consider creating a session encryption key and using encryption to protect it in program memory.

Use certified encryption to avoid key loss

When retrieving encryption keys, be sure to use encryption software that has a known provenance and which has been certified for accuracy. The vendor of the encryption software should be able to provide you with proof of certification by NIST or other independent assessment facility. The Alliance AES encryption solutions meet this recommendation.

Implement error handling

All AKM key retrieval 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. Never ignore an error code as this may lead to corrupt data and unpredictable results.

Implement exception handling in your application

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

Clear memory after use

When you finish using an encryption key, be sure to overwrite the memory used by the variable. Zero the memory in order to erase the key from 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:

https://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project#tab=OWASP_Top_10_for_2013