Chapter 1: About This Manual

AKM Admin API

The AKM Admin API defines a standard interface to the AKM Admin functions so clients can build custom administrative implementations. Key management is performed via a secure TLS connection to the AKM server. Both the client and server end-points are authenticated via the TLS protocol.

The AKM Admin API supports managing symmetric AES keys and asymmetric RSA keys throughout their life cycles, managing user and group access to keys, and other administrative functions.

Who is this for?

This guide is designed to help developers who will write their own interface to the AKM Admin API or put administrative functions under program control. You should have the programming skills necessary to create TLS connections to exchange key management requests and responses between your application and the AKM server. A good knowledge of secure programming techniques is highly recommended.

If you want to use the AKM Administrative Console GUI application for key management, see the AKM Administrative Console Guide.

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.03	5/26/2009	Add a note to the Delete Certificate API regarding server restart.
1.04	6/11/2009	Support for RSA_SSLV23_PADDING RSA padding has been removed. Formal release of version 1.03.
1.10	7/3/2009	Added new documentation for mirroring APIs. APIs that have changed are: Get Mirror Address, Get Mirror Status, Get Queue Size, Force Key Sync, and Set Mirror Address. A new API has been added named Get Mirrored Data Hash.
1.11	7/6/2009	Additional small corrections to descriptive text.
1.12	7/18/2009	Add the API definitions for Import Symmetric Key Batch, and Export Symmetric Key Batch
1.13	7/28/2009	The Import Certificate API contained a field definition for the path to the file. This is not a field on the API itself and this has been removed.
1.14	8/16/2009	Corrections to the Set Metadata request and response, Force Key Synch request and response. Correction to the length of the Get Mirror Address response transaction. Correction to Import Symmetric Key and Export Symmetric Key to remove file path information.
1.15	8/26/2009	Update Export Symmetric Key Batch and Import Symmetric Key Batch APIs with the correct transaction IDs.
1.16	9/17/2009	The Get Certificate List API has been updated for new fields.
1.17	10/20/2009	Corrections to several APIs including Export Symmetric Key, Export Symmetric Key Batch, and Import Symmetric Key Batch.
1.18	11/4/2009	The Report FIPS mode API has been updated to return the program version and database version in the response.
1.19	11/11/2009	Move debug APIs to a separate section. Correct API locations in document to make the APIs in alphabetical order. Add the new API Authorize Administrator. Add documentation for the Get Symmetric Key API.
1.20	11/24/2009	The Get Mirror Status API is updated for a new field and better description of the operation.
1.21	12/16/2009	The Get Symmetric Key and Get Next Key APIs have been corrected and updated to be more clear.
1.22	1/2/2010	Add additional type to Set Key Access API. Add the Force Rollover API (it was missed from previous versions). Automatically Generate Keys erroneously indicated that the increment code field must be blank when adding keys. It should actually be the original values used on the first API call.
1.30	2/15/2010	Final version for release 2.0.1 of Alliance Key Manager.
1.31	3/8/2010	Added additional descriptive text to the Get Symmetric Key response. Removed the Direction field from the List Mirror Names API. Removed the Last Rollover Date field from the Rollover Key Command.
1.32	6/20/2010	Add a note to the Change Activation Date API to document a work-around for a reported bug.
1.33	2/22/2010	Errata has been added to the Display Key Instance List API related to a null value returned in the More Flag.
2.1.13.001	8/29/2013	New manual format
3.0.0.001	9/29/2014	Update introductory chapters.
3.0.3.001	1/13/2015	Update for AKM 3.0.3 and the ready to use version of AKM for VMware. Corrections made to several commands.
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.
4.6.0.001	10/23/2016	Added Activate RSA key requests and responses
4.6.0.001	12/04/2020	Updated Display Symmetric Key Policy response, rollover date bytes, and transaction length.
4.6.2.001	13/31/2021	Removed options for 1024 keys following deprecation.
4.6.2.001	13/31/2021	Removed request and response for “Push key to device”

Chapter 2: Preparation

Overview

Before setting up administrative functions in your 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)
Download admin certificates from the AKM server
Know the IP address(es) of the AKM server(s) and port number for admin services (the default is 6001)

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 and private keys

The admin 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
Admin 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 admin 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 admin services on AKM (the default is 6001)

Checklist

Before continuing, you will need the following items:

AKM’s CA certificate in a format appropriate for your application environment
An admin 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 administrative services port number (the default is 6001)

Chapter 3: Introduction

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

Certificates and private keys

Certificates and private keys are used to verify the identity of their holders and authenticate two or more parties during secure TLS communication. AKM’s certificate authority (CA) certificate and a valid admin certificate and the admin private key must be installed on the admin client in order to communicate with the AKM server.

Client/server architecture

The AKM Admin 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.

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

Requests and responses

To perform an admin command, you will send a request to the AKM server and the server will return a response. Requests and response contain fixed-length fields in a specific order which give information about the request or 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.

Data formats

The AKM Admin API uses US-ASCII format (printable character set, ANSI X3.4-1986) for field values in request and response headers. US-ASCII data uses one character per byte. Binary data can contain a value in the range of 0 to 255 (hex 00 to hex FF) per byte.

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.

Bulk key creation

The Automatically Generate Keys command lets you generate any number of encryption keys using a key name template. The key name template provides a high level of flexibility in naming the generated keys. A name template includes a “Constant” name prefix and a sequential name suffix. You can specify the length of the constant portion of the name, and the length of the sequential portion of the name. For example, you can define a 3 character constant and an 8 character sequential suffix:

ABC00000001 through ABC99999999

Or, you could define a one character constant prefix and a 6 character sequential suffix:

C000000 through C999999

In addition to numeric sequences, you can define hex and alpha sequences. When specifying a hex sequence the suffix is incremented through hex values:

C000000 through CFFFFFF

You can also specify the sequential value as an alphabetic string:

C000000 through CZZZZZZ

Bulk key encryption can be useful when you know you will need a large number of keys and you want to provision them in advance. Also, by provisioning a number of keys in advance, you can reduce the frequency of backups of the key store.

To retrieve encryption keys created using a key name template, you will use the Get Next Key command instead of the Get Symmetric Key command.

Procedures

Use the following process to enable your client application to perform an admin command:

Format an admin request in your application
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: Admin APIs

This chapter includes general key management commands for both symmetric and asymmetric keys. For a list of APIs specific to managing asymmetric RSA keys, see Chapter 5: RSA Key Management APIs.

Requests and responses (transactions) contain fixed-length fields in a specific order which give information about the request or response. The following specifications show the fields used for each admin request and response. The field name in bold is followed by the length of the field in bytes, the format, and possible values.

Activate Key request

This transaction activates a symmetric key that was previously revoked. If the request is successful, the key will be activated with the same characteristics as when it was revoked. For example, if the key was originally defined for automatic rollover, it will still be set for automatic rollover.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. This is the length of the remainder of the transaction. The value must be 00052.

Transaction ID

4-byte, ASCII. Value 1019.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Activation Date

8-bytes, ASCII. The format is CCYYMMDD.

Activate Key response

This transaction is the response to the request to activate a symmetric key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00056.

Transaction ID

4-byte, ASCII. Value 1020.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Activation date

8-bytes, ASCII. CCYYMMDD.

Activate Key Instance request

This transaction activates a symmetric key instance that was previously revoked. If the request is successful, the key instance will be activated with the same characteristics as when it was revoked. For example, if the key instance was originally defined for automatic rollover, it will still be set for automatic rollover.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. This is the length of the remainder of the transaction. The value must be 00076.

Transaction ID

4-byte, ASCII.

Value 1033.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key instance

24-byte, ASCII Base64 encoded, left-justified

Activation date

8-bytes, ASCII. CCYYMMDD.

Activate Key Instance response

This transaction is the response to the request to activate a symmetric key instance.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00080.

Transaction ID

4-byte, ASCII. Value 1034.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key instance

24-byte, ASCII Base64 encoded, left-justified. A blank value indicates the current instance.

Activation date

8-bytes, ASCII. CCYYMMDD.

Add User To Group request

This command will add a group-user record to the Group Member table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00516.

Transaction ID

4-byte, ASCII. Value 1085.

Group

256-bytes, ASCII, left-justified, with blank padding on the right.

User

256-bytes, ASCII, left-justified, with blank padding on the right. This is the Common Name (CN) in the public certificate for the client.

Add User To Group response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. This is the length of the remainder of the transaction. Value is 00520.

Transaction ID

4-byte, ASCII. Value 1086.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Group

256-bytes, ASCII, left-justified, with blank padding on the right. Mirrored from request.

User

256-bytes, ASCII, left-justified, with blank padding on the right. Mirrored from request.

Administrative NOOP request

This transaction is used to determine if the administrative service is active. No administrative function is performed.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1043.

Administrative NOOP response

This transaction is the response to the administrative noop request.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00008.

Transaction ID

4-byte, ASCII. Value 1044.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Authorize Administrator request

This transaction authorizes another administrator to use the Alliance Key Manager to work with keys. It can only be used when the master configuration file has been changed to require dual log on control.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00008.

Transaction ID

4-byte, ASCII. Value 1177.

Time

4-byte, ASCII, right-justified with leading zeros. Number of minutes for commands to be issued. The range is 0001-1440. The Value 0000 indicates that the remaining time should be canceled.

Authorize Administrator response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00008.

Transaction ID

4-byte, ASCII. Value 1044.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Automatically Generate Keys Request

This command generates a user-defined number of encryption keys based on a template for the key name. After generating a set of keys you can call this API with the Add option to add additional keys to the set you previously generated.

NOTE: When you automatically generate keys with this API, Alliance Key Manager stores the key template and a pointer to the next key to be retrieved and the last key retrieved. You should use the Get Next Key API to retrieve the next available encryption key. You can use the Get Symmetric Key API to retrieve a key, but the template will not be updated with this retrieval information. Likewise, you should avoid deleting any automatically generated key before it has been retrieved by Get Next Key. This will break the chain of keys retrieved and will cause unexpected errors. Only delete keys after they have been retrieved with the Get Next Key API.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00594.

Transaction ID

4-byte, ASCII. Value 1117.

Constant

39-bytes, ASCII, left-justified.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes.

Increment Code

The type of incrementing to be performed. 1-byte, ASCII. The value must be one of the following:

H - Hex digits (0-9, A-F, upper case only). Initial value is all 0s

N – Numeric (0-9). Initial value is all 0s.

A - Alpha Numeric (0-9, A-Z, a-z). Initial value is 0s. Incrementing from numbers to upper case letters then lower case letters (the same as the appearance of the character in the ASCII table).

Constant Length

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. This value must be in the range of 00 – 39.

Increment Number

5-bytes, ASCII, right-justified with leading zeros. Valid for the range 00001-99999. This number is the number of keys to auto-generate.

Mode

1-byte, ASCII. A – Add. This will add additional keys to an existing template. I – Initialize. Create a new template and keys. If the template exists an error will be returned.

NOTE: If you are calling this API to add keys to an existing template, you must leave the Increment Code field blank. See the definition of the Increment Mode field above.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. This must be 0128, 0192, or 0256.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire

Rollover Code

1-byte, ASCII, case insensitive. The value must be one of the following:

N - never rolled over

M - Manually rolled over

A - Automatic rollover

Rollover Days

4-bytes, ASCII, case insensitive. The number of days in a rollover period. 0000 if Never or Manual.

Deletable

1-byte, ASCII, case insensitive. The value must be Y (Yes) or N (No).

Mirror Key

1-byte, ASCII, case insensitive. The value must be Y or N.

Access Flag

1-byte, ASCII. The value must be one of the following:

1 - No control. Anyone can access key

2 - User control. CN on user cert must match a User-KeyName entry in the UserAccess table.

3 - Group control. OU on user cert must match a Group-KeyName entry in the GroupAccess table.

4 - User + Group control. CN and OU on user cert must match entries in both the UserAccess and GroupAccess tables.

Note that if the access flag is 2, 3, or 4, the user and/or group in the next fields will be added to the access tables.

User

256-bytes, ASCII, left-justified, with blank padding on the right.

Group

256-bytes, ASCII, left-justified, with blank padding on the right.

Automatically Generate Keys response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1118.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

NOTE: Each combination of a constant, increment length and code creates a new set of auto-increment keys. The constant ABC with increment length 3 and code H would create a series of keys with values ABC000-ABCFFF. The constant ABC with increment length 2 and code N would generate keys in the range ABC00-ABC99. Both of these could be used simultaneously.

Change Activation Date request

This transaction changes the activation date of an existing symmetric encryption key. When you create an encryption key you assign the first date that it will be active. This transaction changes that date. Note that an error will be returned if the key is already active.

NOTE: In version 2.1.13 of Alliance Key Manager a bug prevents the changing of the activation date if the expiration date is 0. You can work around this error by changing the expiration date, then changing the activation date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This should be a value of 00076.

Transaction ID

4-byte, ASCII. This should always have the value 1009.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right. You should not null terminate this string.

Key instance

24-byte, ASCII Base64 encoded, left-justified. A blank value indicates the current instance.

Activation Date

8-bytes, ASCII, case insensitive in CCYYMMDD format. 00000000 indicates key is immediately usable

Change Activation Date response

This transaction is the response to the request to change the activation date of an existing symmetric encryption key. The response code will indicate the success or failure of the request.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This should always have the value 00056.

Transaction ID

4-byte, ASCII. Value 1010.

Return Code

4-byte ASCII, right-justified, with leading zeros. Value 0000 indicates success.

Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK.

Case sensitive

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Change Deletable request

Use this command to change whether a symmetric key instance can be deleted or is permanent. If no key instance is specified, the current instance is changed.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This must be the value 00069.

Transaction ID

4-byte, ASCII. Value 1005.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key instance

24-byte, ASCII Base64 encoded, left-justified. A blank value indicates the current instance.

Deletable

1-byte, ASCII, case insensitive. The value of Y indicates Yes and the value of N indicates No.

Change Deletable response

This transaction is the response to the request to change the deletable status of a symmetric encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This field must have the value 00049.

Transaction ID

4-byte, ASCII. Value 1006.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Deletable

1-byte, ASCII, case insensitive. The value of Y indicates Yes, the key is deletable, the value of N indicates the key is now not deletable.

Change Expiration Date request

This transaction changes the expiration date of an existing symmetric encryption key. When you create an encryption key you assign the expiration date after which it cannot be used. This transaction changes that date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00076.

Transaction ID

4-byte, ASCII. Value 1007.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key instance

24-byte, ASCII Base64 encoded, left-justified. A blank value indicates the current instance.

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire

Change Expiration Date response

This transaction is the response to the request to change the expiration date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00056.

Transaction ID

4-byte, ASCII. Value 1008.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK.

Case sensitive

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

Change Mirror Key request

This transaction changes the mirror status of a symmetric key. Keys that are mirrored are automatically sent to a high availability Alliance Key Manager.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00045.

Transaction ID

4-byte, ASCII. Value 1013.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Mirror Key

1-byte, ASCII, case insensitive. The value Y indicates the key should be mirrored. The value N indicates the key will not be mirrored.

Change Mirror key response

This transaction is the response to the request to change the mirroring status of a symmetric encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00048.

Transaction ID

4-byte, ASCII. Value 1014.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

0-byte, ASCII, left-justified, with blank padding on the right.

Mirror Key

1-byte, ASCII, case insensitive. The value Y indicates that you want to mirror this key. The value N indicates that you do not want to mirror keys.

Change Next Increment request

This API changes the pointer to the next automatically generated symmetric key. It is important to provide accurate next key information as you can disrupt the use of the Get Next Key API by setting an invalid value with this API.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00087.

Transaction ID

4-byte, ASCII. Value 1159.

Constant

39-bytes, ASCII, left-justified.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes.

Constant Length

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. The value must be in the range of 00 – 39.

New Next Increment

40-bytes, ASCII

Change Next Increment response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00008.

Transaction ID

4-byte, ASCII. Value 1160.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Change Rollover request

This transaction is used to change the rollover status and interval for a symmetric encryption key. A key that does not automatically rollover can be changed to automatically rollover in a certain number of days. A key that does roll over can be changed to not automatically roll over.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00073.

Transaction ID

4-byte, ASCII. Value 1011.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Key instance

24-byte, ASCII Base64 encoded, left-justified. A blank value indicates the current instance.

Rollover code

1-byte, ASCII, case insensitive. The value of N indicates the key never rolls over. The value of M indicates the key will be manually changed. The value of A indicates the key will automatically roll over. If you specify the value of A you must also specify an interval for the rollover.

Rollover days

4-bytes, ASCII, case insensitive. Days - number of days until rollover. 0000 if never or manual.

Change Rollover response

This transaction is the response to the key rollover request.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00053.

Transaction ID

4-byte, ASCII. Value 1012.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Rollover code

1-byte, ASCII, case insensitive. This value echos the value of the rollover code on the request.

Rollover days

4-bytes, ASCII, case insensitive. Days - number of days until rollover. 0000 if never or manual. This value echos the value of the original request.

Create Symmetric Key request

This transaction creates a new symmetric encryption key. You will give the new key a name that is used for retrieval and other administrative functions, the activation date, expiration date, key size, and other attributes of the encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00584.

Transaction ID

4-byte, ASCII. Value 1001.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. The allowed values are 0128 for a 128-bit key, 0192 for a 192-bit key, and 0256 for a 256-bit encryption key.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

Rollover Code

1-byte, ASCII, case insensitive. The value of N indicates the key is never rolled over (changed). The value of M indicates the key is manually rolled over. The value of A indicates the key is automatically rolled over.

Rollover Days

4-bytes, ASCII, case insensitive. The number of days in a rollover period. 0000 if Never or Manual.

Deletable

1-byte, ASCII, case insensitive. The value of Y indicates the encryption key can be deleted. The value of N indicates the key cannot be deleted.

Mirror Key

1-byte, ASCII, case insensitive. The value of Y indicates the key is mirrored to a high availability Alliance Key Manager. The value of N indicates the key is not mirrored.

Access Flag

1-byte, ASCII. 1 = No control. Anyone can access key. 2 = User control. CN on user cert must match a User-Key Name entry in the User Access table. 3 = Group control. OU on user cert must match a Group-Key Name entry in the Group Access table. 4 = User + Group control. CN and OU on user cert must match entries in both the User Access and Group Access tables.

User Name

256-bytes, ASCII, left-justified, with blank padding on the right.

Group Name

256-bytes, ASCII, left-justified, with blank padding on the right.

Create Symmetric Key response

This transaction is the response to the request to create a new symmetric encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction.. The value must be 00072.

Transaction ID

4-byte, ASCII. Value 1002.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

Echoed from request value. 40-byte, ASCII, left-justified, with blank padding on the right.

Key Instance

24-byte, ASCII.

Crypto Self-Test request

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1045.

Crypto Self-Test response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00009.

Transaction ID

4-byte, ASCII. Value 1046.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mode

1-byte, ASCII. The value P means Passed. The value F means Failed.

Delete Certificate request

This API deletes a certificate file in a known directory on the AKM key server.

SECURITY NOTE: You must restart the Alliance Key Manager application for the certificate deletion to take effect. The certificates are loaded at server start time and remain in effect until the server restarts.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00069.

Transaction ID

4-byte, ASCII. Value 1141.

Certificate type

1-byte, ASCII, A/C. The value A indicates CA certificate, the value C indicates client certificate.

CA certificate name

64-byte, ASCII. Left justified, blank filled. The name of the CA certificate without the path.

Delete Certificate response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00008.

Transaction ID

4-byte, ASCII. Value 1142.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Delete Key request

This transaction is used to delete a symmetric encryption key. The key must have the attribute of being deletable. The delete cannot be reversed. The only way to recover a deleted key is to restore a backup of the key store.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00044.

Transaction ID

4-byte, ASCII. Value 1015.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Delete Key response

This transaction is the response to the request to delete a symmetric encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00048.

Transaction ID

4-byte, ASCII. Value 1016.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Delete Key Instance request

This transaction is used to delete a symmetric encryption key instance. The key instance must have the attribute of being deletable. The delete cannot be reversed. The only way to recover a deleted key instance is to restore a backup of the key store.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00068.

Transaction ID

4-byte, ASCII. Value 1029.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Key instance

24-byte, ASCII, Base64-encoded left-justified.

Delete Key Instance response

This transaction is the response to the request to delete a symmetric encryption key instance.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00072.

Transaction ID

4-byte, ASCII. Value 1030.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Key instance

24-byte, ASCII, Base64 encoded, left justified. A blank value indicates the current instance.

Delete Private Key request

This API deletes a private key file from a known directory on the AKM key server.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This must be the value 00068.

Transaction ID

4-byte, ASCII. Value 1145.

Key name

64-byte, ASCII. Left justified, blank filled. The name of the key without the path.

Delete Private Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This will be the Value 00008.

Transaction ID

4-byte, ASCII. Value 1146.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Display Key Instance List request

This transaction is used to display a list of all instances for a given symmetric key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00044.

Transaction ID

4-byte, ASCII. Value 1035.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Display Key Instance List response

This transaction is the response to the request to list key instances of a symmetric key. This transaction may return more than one buffer of information and you must read each buffer until the last (see the More Flag field description).

ERRATA: In versions prior 2.1.0 of Alliance Key Manager the More Flag can be returned with a null value (hex 00) instead of the correct value of Y or N.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The minimum length of the remainder of the transaction. 000nn - size of this buffer, will vary with number or instances. In no case will more than 16k-bytes be returned in a single buffer.

Transaction ID

4-byte, ASCII. Value 1036.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Values are Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, Transaction ID, Return code, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

ERRATA: In versions prior 2.1.0 of Alliance Key Manager the More Flag can be returned with a null value (hex 00) instead of the correct value of Y or N.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

List Length

5-byte, 0 padded.

Instance-1

24-bytes, Base64 encoding.

Instance-2 through Instance-n

24-bytes, Base64 encoding.

Display Key Name List request

This transaction is used to display a list of all symmetric key names in the key store.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1037.

Display Key Name List response

This transaction is the response to the request to list symmetric keys. This transaction may return more than one buffer of information and you must read each buffer until the last (see the More Flag field description).

Transaction length

Transaction ID

4-byte, ASCII. Value 1038.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

More Flag

ListSegmentLength

The segment contains pairings of KeyName and KeyType; each KeyName is 40 characters, trailing blank padded, followed by the KeyType, 4 characters. KeyType values may be either “Priv” or “Pub”.

KeyName 1-n

40-byte, ASCII, left-justified, with blank padding on the right

Display Symmetric Key policy request

This transaction is used to retrieve the attributes of an existing symmetric encryption key. The actual value of the key is not retrieved.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00068.

Transaction ID

4-byte, ASCII. Value 1003.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Instance

24-byte, ASCII. The instance name of the key. This can be blanks for the default instance.

Display Symmetric Key policy response

This transaction is the response to the request to retrieve the attributes of a symmetric encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 001258.

Transaction ID

4-byte, ASCII. Value 1004.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK

Case sensitive.

Key Instance

24-bytes, Base64 encoding. Case insensitive.

Current

1-byte. Y,N. Indicates if this is the current instance of the key.

Key Size Bits

4-bytes, ASCII. Values can be 0128, 0192, or 0256.

Key Creation Date

8-bytes, ASCII. The format of the date is CCYYMMDD.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

Rollover code

1-byte, ASCII, case insensitive. The values can be N (Never), M (Manual), or A (Automatic).

Rollover days

4-bytes, ASCII, case insensitive. Days - number of days until rollover. 0000 if never or manual.

Last rollover date

4-bytes, ASCII, case insensitive. Days - number of days until rollover. 00000000 if never or manual.

Deletable

1-byte, ASCII, case insensitive. The value Y indicates the key is deletable. The value N indicates the key is not deletable.

Key Revoked Date

8-bytes, ASCII. CCYYMMDD. 00000000 indicates the key has not been revoked

Mirror Key

1-byte, ASCII, case insensitive. Y – yes, N – no.

Time Stamp

14-bytes, ASCII. CCYYMMDDHHMMSS. The timestamp of the last time the key was created or changed.

16 groups (70-byte groupings)

Field name One of MD01, MD02, …, MD16

Field value

Starting single quote (‘) character.

64-byte value

Ending single quote (‘) character

Export certificate request

This API uploads a certificate file to a known directory on the AKM key server.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00069.

Transaction ID

4-byte, ASCII. Value 1153.

Certificate type

1-byte, ASCII, A/C. The value A indicates CA certificate, the value C indicates client certificate.

Certificate name

64-byte, ASCII. Left justified, blank filled. The name of the certificate without the path.

Export Certificate response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00078.

Transaction ID

4-byte, ASCII. Value 1154.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Certificate type

1-byte, ASCII, A/C. The value A indicates CA certificate, the value C indicates client certificate.

Certificate name

64-byte, ASCII. Left justified, blank filled. The name of the certificate without the path.

Certificate length

5-byte, ASCII. Right justified, zero filled. The length of the certificate data in the next field.

Certificate data

16,301-byte maximum. This is the binary contents of a certificate file in pem format.

Export Symmetric Key request

This transaction is used to export an encryption key to a path on the Alliance Key Manager system. If the path is a USB device, the key will be exported to the USB storage device. You can export the key in binary, Base64, or Base16 (hex) format. Only the actual key is exported.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00136.

Transaction ID

4-byte, ASCII. Value 1025.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key Instance

24-bytes, Base64 encoding. Case insensitive. All blanks is current instance.

Key Format

3-byte, ASCII. The value BIN indicates the key will be in binary format. The value B16 indicates the key will be in Base16, or hex, format. The value B64 indicates the key will be Base64 encoded using the RFC 4846 standard. The value RSA indicates a Base64 encoded PEM file.

RSA Certificate Name

64-byte, ASCII. Case Sensitive, left justified, blank padded on the right. Must have .pem extension. This is the name of the file containing the X509 certificate which has the RSA public key used to encrypt the symmetric key binary value. If not exporting using RSA then set this field to blanks.

If using the admin console to request an RSA encrypted key the following fields need to be passed in on the command line. They will enable the admin console to write the encrypted key returned from the key server to a file.

RSA Padding mode

1-byte, ASCII. 1 = RSA_PKCS1_PADDING, 2 = RSA_PKCS1_OAEP_PADDING (recommended). Note: The following padding modes are not supported: RSA_NO_PADDING, RSA_SSLV23_PADDING

Export Symmetric Key response

This transaction is the response to the request to export an encryption key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00339.

Transaction ID

4-byte, ASCII. Value 1026.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success

Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Key Instance

24-bytes, Base64 encoding. Case insensitive.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. The value can be 0128, 0192, or 0256.

The same value as in the request is returned

Key Format

3-byte, ASCII. The value can be BIN (binary), B16 (Base16 encoded, or hex), B64 (Bse64 encoded), or RSA (PEM format). The same value as in the request is returned.

RSA Padding mode

1-byte, ASCII. 1 = RSA_PKCS1_PADDING, 2 = RSA_PKCS1_OAEP_PADDING (recommended).

Value length

4-byte, ASCII, right justified with leading zeros. The number of significant digits in the value.

Value

If the request specified BIN (binary) this field contains the actual key in binary format. For a 256 bit key, the value is left justified in the first 32 bytes of the field. For a 192-bit key, the value is left justified in the first 24 bytes of this field. For a 128 bit key the value is left justified in the first 16 bytes of this field.

If the request specified B16 (Base16, or hex) this field contains the actual key in hex format. For a 256 bit key, the value is left justified in the first 64 bytes of the field. For a 192-bit key, the value is left justified in the first 48 bytes of this field. For a 128 bit key the value is left justified in the first 32 bytes of this field.

If the request specified B64 (Base64) this field contains the actual key in Base64 format. For a 256 bit key, the value is left justified in the first 44 bytes of the field. For a 192-bit key, the value is left justified in the first 32 bytes of this field. For a 128 bit key the value is left justified in the first 24 bytes of this field.

If the request specified RSA (PEM format) this field contains the key with a length of 256 bytes.

Export Symmetric Key Batch Request

This command allows the user to request keys to be exported based upon the contents of the metadata fields. Keys will be sent batched in 16k chunks. Note that the meta data query may or may not return the current instance of a key. In the event the current instance is returned, it will be the first instance returned.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be in the range of 00146 to 01272. The header length is the length of the first five fields: 4 + 1 + 4 + 3 + 64 +1 = 77. The metadata length is between 74 and 1199 (see below). The transaction length is the total of the header length and the metadata length. It is between 151 (77 + 74) and 1276 (77 + 1199).

Transaction ID

4-byte, ASCII. Value 1171.

Current Instance Flag

1-byte, ASCII. Case insensitive. C - Select from current instances only, A - Select from all instances.

Key Size Bits

This is specified to allow all returned keys to have the same length. 4-bytes, ASCII. Values: 0128, 0192, or 0256.

Key Format

3-byte, ASCII. BIN – binary. B16 - Base16 encoded (hex), RFC 4648. B64 - Base64 encoded, RFC 4648. RSA - Base64 encoded PEM file.

RSA Certificate Name

64-byte, ASCII. Case sensitive, left justified, blank padded on the right. Must be a file with a .pem extension but the .pem is not included in the name. This is the name of the file containing the X509 certificate which has the RSA public key used to encrypt the symmetric key binary value. If not exporting using RSA then 64 blanks.

RSA Padding mode

1-byte, ASCII. 1 = RSA_PKCS1_PADDING, 2 = RSA_PKCS1_OAEP_PADDING (recommended). Note: The following padding modes are not supported: RSA_NO_PADDING, RSA_SSLV23_PADDING.

Metadata Request

( (75 bytes/group) * (1 to 16 groups) ) -1. 16 times:

Field name

4 bytes.

Separator space

1 byte.

Selector value

2 bytes.

Separator space

1 byte.

Starting quote

1 byte.

Data

64 bytes.. Ending quote (1) + Separator space (1) -1 as the ending quote for MD16 isn’t followed by a separator character. The minimum metadata length is 74 (75 -1). The maximum medatata length is 1199 ( (75 * 16) - 1 ).

Sample transaction:

00226 - 5 bytes. Transaction ID - 4 bytes, current instance flag – 1 byte, BIN - 3 bytes, RSA Certificate Name - 64 bytes, RSA padding mode – 1 byte, MD01 EQ ‘64-chars’ ‘MD12 NE ‘64-chars’.

This will result in an SQL query against metadata fields of the form:

select * from table where MD01 = ‘64-chars’ MD12 != ‘64-chars’

Export Symmetric Key Batch Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The value will be 00021. The transaction response header length is the length of the first five fields.

Transaction ID

4-byte, ASCII. Value 1172.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition. For a non-zero return code there will be no following data.

Key Size Bits

This is specified to allow all returned keys to have the same length. 4-bytes, ASCII. Values: 0128, 0192, or 0256. The same value as in the request is returned.

Key Format

3-byte, ASCII. BIN – binary, B16 - Base16 encoded (hex), B64 - Base64 encoded, RSA - RSA encoded .pem file. The same value as in the request is returned.

More Flag

1-byte, ASCII. The value must be Y,N. Y indicates that there is another buffer following this. N indicates this is the last buffer in the series.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The total number of bytes remaining to be read in this segment. The minimum List Segment Length is 80. The maximum List Segment Length is 16k.

Key Data (repeated once for each key):

Key name

40 bytes.

Instance

24 bytes. Note that if the current instance of a key was selected by the meta data query, it will be the first instance returned. All other instances will be returned in an undefined order.

Key Value

BIN – Exact length: 16-bytes if 128-bit key, 24-bytes if 192-bit key, 32-bytes if 256-bit key.

B16 – Exact length: 32-bytes if 128-bit key, 48-bytes if 192-bit key, 64-bytes if 256-bit key.

B64 – Exact length: 24-bytes if 128-bit key, 32-bytes if 192-bit key, 44-bytes if 256-bit key.

RSA – Exact length: 256-bytes for all key sizes.

Sample transactions:

00021 - 5 bytes, transaction header length, nnnn- 4 bytes, transaction ID, 0000 - 4 bytes, return code, 0256 - 4 bytes, key size bits, BIN - 3 bytes, Key Format, N - 1 byte, more flag, 00160 - 5 bytes, list segment length (2 keys) * (81 bytes per key below):

Key Name - 40 bytes

Instance - 24 bytes

Key Value - 16 bytes binary

Key Name - 40 bytes

Instance - 24 bytes

Key Value - 16 bytes binary

00008nnnn9999 (error code is returned)

Force Key Sync Request

Causes the server to send either a named key or all keys to all mirror partners. This call blocks until all the transactions have been added to the mirror queue. This command will also send user and group tables when the AllFlag = Y.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00085.

Transaction ID

4-byte, ASCII. Value 1151.

Mirror Name

40-bytes, ASCII. Left-justified, blank filled.

All Flag

1-byte, ASCII. Y - Send all keys (Key name parameter is ignored). N - Mirror the named key only.

Key Name

40-bytes, ASCII. Left-justified, blank filled.

Force Key Sync Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00008.

Transaction ID

4-byte, ASCII. Value 1152.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Force Rollover request

Use this command to force a rollover of all symmetric keys.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1175.

Force Rollover response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00008.

Transaction ID

4-byte, ASCII. Value 1176.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Get Certificate List Request

This command returns a list of certificate names stored on the server. Files in the certificate directory that are not certificates or not in .pem format will not be reported.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00005.

Transaction ID

4-byte, ASCII. Value 1049.

Type

1-byte, ASCII. A - CA Certificate, C - Public Certificate.

Get Certificate List Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00014.

Transaction ID

4-byte, ASCII. Value 1050.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Y for Yes, or N for No. Y indicates that there is another buffer following this. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

Certificate Name 1-n

64-bytes. 16,320 total bytes per segment.

Not Before Date 1-n

6-bytes. YYMMDD format.

Not After Date 1-n

6-bytes. YYMMDD format.

Get Group List For All Keys request

This command returns the value of all the Group Access table values.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1113.

Get Group List For All Keys response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00014.

Transaction ID

4-byte, ASCII. Value 1114.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Value Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, ID, RC, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

Key Name 1-n

40-bytes, mirrored value from request.

Group Name 1-n

256-bytes, ASCII, left-justified, blank padded on the right

Get Group List For Key request

Returns a list of the groups authorized to access this key in the Group Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00044.

Transaction ID

4-byte, ASCII. Value 1071.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Get Group List For Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00054.

Transaction ID

4-byte, ASCII. Value 1072.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

More Flag

1-byte, ASCII. The value will be Y (yes) or N (no). Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, Transaction ID, Reply Code, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. Each Instance is 24-bytes.

Group 1 through Group n

256-bytes, ASCII, left-justified, blank padded on the right.

Get Group List For User request

This command returns a list of the all the groups the user is a member of.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00260.

Transaction ID

4-byte, ASCII. Value 1089.

User

256-bytes, ASCII, left-justified, blank padded on the right.

Get Group List For User response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00270.

Transaction ID

4-byte, ASCII. Value 1090.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

User

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored from request.

More Flag

1-byte, ASCII. The value will be Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, Transaction ID, Reply Code, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. Each Instance is 24-bytes.

Group 1 through Group n

256-bytes, ASCII, left-justified, blank padded on the right.

Get Group Member List request

This command returns the value of all the GroupMember table values.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1115.

Get Group Member List response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00014.

Transaction ID

4-byte, ASCII. Value 1116.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Value Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, ID, RC, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

Group Name 1-n

256-bytes, ASCII, left-justified, blank padded on the right

User Name 1-n

256-bytes, ASCII, left-justified, blank padded on the right

Get Key Access Flag request

This command returns the value of the Access Flag for the named key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00044.

Transaction ID

4-byte, ASCII. Value 1079.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Get Key Access Flag response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00056.

Transaction ID

4-byte, ASCII. Value 1080.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

Access Flag

1-byte, ASCII. The values can be:

1 - No control. Anyone with a valid certificate can access key.

2 - User control. Common Name (CN) on user certificate must match a User-Key Name entry in the User Access table.

3 - Group control. Organization Unit (OU) on user certificate must match a Group-Key Name entry in the Group Access table.

4 - User + Group control. CN and OU on user certificate must match entries in both the User Access and Group Access tables.

Get Key Access List request

This command returns the value of all the KeyAccess table values.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1099.

Get Key Access List response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00014.

Transaction ID

4-byte, ASCII. Value 1100.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, ID, RC, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

Key Name 1-n

40-bytes, mirrored value from request.

Access Flag 1-n

Get Key List For Group request

Returns a list of the Keys authorized to this group in the Group Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00260.

Transaction ID

4-byte, ASCII. Value 1073.

Group

256-bytes, ASCII, left-justified, blank padded on the right.

Get Key List For Group response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00270.

Transaction ID

4-byte, ASCII. Value 1074.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Group

256-bytes, ASCII, left-justified, blank padded on the right.

More Flag

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. Each Instance is 24-bytes.

Key name 1 through Key name n

40-bytes, mirrored value from request.

Get Key List For User request

Return a list of Key Names the user is authorized to retrieve in the User Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00260.

Transaction ID

4-byte, ASCII. Value 1059.

User

256-bytes, ASCII, left-justified, blank padded on the right.

Get Key List For User response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00270.

Transaction ID

4-byte, ASCII. Value 1060.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

User

256-bytes, ASCII, left-justified, blank padded on the right.

More Flag

1-byte, ASCII. The value will be Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, Transaction ID, Reply Code, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. Each Instance is 24-bytes.

Key Name 1 through Key Name n

40-byte, ASCII, left-justified, with blank padding on the right.

Get Mirror Address request

This API retrieves an existing mirror configuration by its unique name.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00044.

Transaction ID

4-byte, ASCII. Value 1127.

Mirror name

40-byte, ASCII, left justified, blank filled. A user-defined, unique name for the mirror.

Get Mirror Address response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00309.

Transaction ID

4-byte, ASCII. Value 1128.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mirror name

40-byte, ASCII, left justified, blank filled. A user-defined, unique name for the mirror.

Host Name

256-bytes, ASCII, left justified, blank-padded on the right. Supports dotted decimal format addresses and Host names. The address of the key store to send to or receive from.

Port

5-bytes, ASCII, right-justified, zero-filled on the left. The port number to send to.

Get Mirror Status Request

Validate that a connection can be made to the mirror partner. Optionally retrieves mirror partner’s mirrored-data hash and compares it to the local mirrored-data hash. Reports and resets the accumulated fault count.

The mirrored-data hash is a SHA-256 hash of all mirrored data in the database, i.e. that data that would be sent, or would have been received, for mirroring.

The fault count keeps track of how many mirror commands the partner reports as having failed at the partner end. It does not count errors sending commands or receiving responses, such as connection failures. It counts non-zero command return codes sent by the partner.

When Compare Hash is N, the AdminNoop command is sent to the mirror partner. When Compare Hash is Y, the GetMirroredDataHash command is sent. In either case, the command is sent from an ad-hoc connection independent of any current mirror connection and is not sent from the mirror thread.

If the mirror thread has terminated due to a fatal error, GetMirrorStatus will return an error indicating this condition.

The fault count is returned and reset each time GetMirrorStatus completes, even if a connection could not be made to the partner.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00045.

Transaction ID

4-byte, ASCII. Value 1135.

Mirror Name

40-bytes, ASCII, left-justified, blank padded on the right. A user-defined unique name.

Compare Hash Flag

1-byte, ASCII. Y - Retrieve and compare hash. N - Do not retrieve or compare hash.

Get Mirror Status Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00104.

Transaction ID

4-byte, ASCII. Value 1136.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mirror Name

40-bytes, ASCII, left-justified, blank padded on the right.

Fault Count

10-bytes, ASCII, right-justified, zero-filled on the left. The number of transactions rejected by the partner. This count is reset on the server each time this command is called. If the fault count does not fit into 10 characters (i.e., larger than 9,999,999,999) then a string of all ‘#’ is returned (‘##########’).

Mirror Status

1-byte, ASCII. Y – Successfully connected to partner, N – Unable to connect.

Data Hash Compare

1-byte, ASCII. Y – Mirrored-data Hashes match, N – Hashes do not match, Blank if failed to connect.

Mirrored Data Hash

44-byte, ASCII Base64 String. The partner’s Mirrored-data Hash value. Blank if failed to connect or Data Hash Compare = N.

Get Mirrored Data Hash Request

Compute and return local mirrored-data hash. The mirrored-data hash is a SHA-256 hash of all mirrored data in the database, i.e. that data that would be sent, or would have been received, for mirroring.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1169.

Get Mirrored Data Hash Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00052.

Transaction ID

4-byte, ASCII. Value 1170.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mirrored Data Hash

44-bytes, ASCII, Base64 string. The SHA-256 hash value encoded in Base64.

Get Private Key List request

This command returns a list of certificate names stored on the server.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1119.

Get Private Key List response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00014.

Transaction ID

4-byte, ASCII. Value 1120.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Y,N. Y indicates that there is another buffer following this. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. 16, 320 total bytes per segment

Private Key Name 1-n

64-bytes.

Get Next Key request

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

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00051.

Transaction ID

4-byte, ASCII. Value 2003.

Constant

39-bytes, ASCII, left-justified.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes.

Increment Code

The type of incrementing to be performed. 1-byte, ASCII. Values: A - Alpha Numeric (0-9, A-Z, a-z). Initial value is 0s. Incrementing from numbers to upper case letters then lower case letters. (The same as the appearance of the character in the ASCII table). H - Hex digits (0-9, A-F upper case only). Initial value is all 0s. N – Numeric (0-9). Initial value is all 0s.

Constant Length

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field Value must be in the range of 00 – 39.

Key Format

3-byte, ASCII. Values: BIN – binary; B16 - Base16 encoded (hex) using RFC 4648; B64 - Base64 encoded.

Get Next Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00263.

Transaction ID

4-byte, ASCII. Value 2004.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right. The same name as in the request.

Instance name

24-byte, ASCII. The same name as in the request or current instance if request was blanks.

Last Rollover Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key does not rollover.

Expiration Date

8-byte, ASCII string. Value in format CCYYMMDD. 00000000 if non-expiring key.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. Value will be one of: 0128, 0192, 0256. The same value as in the request is returned.

Key Format

3-byte, ASCII. The same value as in the request is returned. The value will be one of:

BIN - binary

B16 - Base16 encoded (hex)

B64 - Base64 encoded

Key data

This is the actual data encryption key. The format and length depends on the requested format:

BIN:

128-bytes. Left justified, blank-filled on the right. Significant digits:

16-bytes if 128-bit key

24-bytes if 192-bit key

32-bytes if 256-bit key

64-bytes if 512-bit key

B16:

128-bytes. Left justified, blank-filled on the right. Significant digits:

32-bytes if 128-bit key

48-bytes if 192-bit key

64-bytes if 256-bit key

128-bytes if 512-bit key

B64:

128-bytes. Left justified, blank-filled on the right. Significant digits:

24-bytes if 128-bit key

32-bytes if 192-bit key

44-bytes if 256-bit key

88-bytes if 512-bit key

Last Increment

40-bytes, ASCII, left-justified. The highest increment value of keys remaining in the template.

Get Queue Size request

This API returns the number of transactions in the queue to be sent to a mirroring server.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00044.

Transaction ID

4-byte, ASCII. Value 1147.

Mirror name

40-byte, ASCII. Left justified, blank filled

Get Queue Size response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00018.

Transaction ID

4-byte, ASCII. Value 1148.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Queue Size

10-byte, ASCII, right-justified, 0 filled on the left. The number of transactions queued to this partner. If the value is larger than 9,999,999,999 this field will be filled with ##########.

Get Symmetric Key request

This is a key retrieval request available on the key retrieval port and not the administrative interface. It is documented here for convenience.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00071.

Transaction ID

4-byte, ASCII. Value 2001.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Instance

24-byte, ASCII. An all blank value references the current instance.

Key Format

3-byte, ASCII. BIN – binary; B16 - Base16 encoded (hex) based on RFC 4648; B64 - Base64 encoded based on RFC 4648.

Get Symmetric Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00351.

Transaction ID

4-byte, ASCII. Value 2002.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right. The same name as in the request.

Instance

24-byte, ASCII. The same name as in the request, or current instance if request was blanks.

Last Rollover Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key does not rollover.

Expiration Date

8-byte, ASCII string. Date in CCYYMMDD format. 00000000 if non-expiring key.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. Values will be 0128, 0192, or 0256. The same value as in the request is returned.

Key Format

3-byte, ASCII. BIN – binary; B16 - Base16 encoded (hex); B64 - Base64 encoded. The same value as in the request is returned.

Encryption key data

This is the actual data encryption key you requested. The length and format of the key material varies depending on the request parameters:

BIN

128-bytes. Left justified, blank-filled on the right. Significant digits: 16-bytes if 128-bit key, 24-bytes if 192-bit key, 32-bytes if 256-bit key.

B16

128-bytes. Left justified, blank-filled on the right. Significant digits: 32-bytes if 128-bit key; 48-bytes if 192-bit key; 64-bytes if 256-bit key;

B64

128-bytes. Left justified, blank-filled on the right. Significant digits: 24-bytes if 128-bit key; 32-bytes if 192-bit key; 44-bytes if 256-bit key.

Reserved

128 bytes. Null (hex 00) filled.

Get System Status request

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction.. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1137.

Get System Status response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00056.

Transaction ID

4-byte, ASCII. Value 1138.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, raw sensor output. The last buffer contains N in this position.

Application status

4-byte, ASCII. Value 0000 indicates no errors. Value 0001-9999 represents an error condition.

Disk status array

8-byte, ASCII. Each byte represents one disk. A value of 0 indicates no error, a value of 1 indicates an error. If there is no disk configured for a particular position in the array a value of 9 is returned.

Core status array

8-byte, ASCII. Each byte represents one memory core. A value of 0 indicates no error, a value of 1 indicates an error. If there is no core configured for a particular position in the array a value of 9 is returned.

Voltage status array

8-byte, ASCII. Each byte represents one voltage measurement. A value of 0 indicates no error, a value of 1 indicates an error. If there is no voltage configured for a particular position in the array a value of 9 is returned.

Battery status array

2-byte, ASCII. Each byte represents one battery. A value of 0 indicates no error, a value of 1 indicates an error. If there is no battery configured for a particular position in the array a value of 9 is returned.

Fan status array

4-byte, ASCII. Each byte represents one fan. A value of 0 indicates no error, a value of 1 indicates an error. If there is no fan configured for a particular position in the array a value of 9 is returned.

Temperature

8-byte, ASCII. Each byte represents one temperature measurement. A value of 0 indicates no error, a value of 1 indicates an error. If there is no fan configured for a particular position in the array a value of 9 is returned.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16,323 bytes max value.

Text data

Up to 16,323-bytes, ASCII. Sensor output in text format.

Get Template Depth Request

This command returns the next available key name in the template and the number of auto-generated keys that have not yet been delivered.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00047.

Transaction ID

4-byte, ASCII. Value 1121.

Constant

39-bytes, ASCII, left-justified.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes.

Constant Length

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. The value must be in the range of 00 – 39.

Get Template Depth Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00093.

Transaction ID

4-byte, ASCII. Value 1122.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes.

Next Increment

40-bytes, ASCII, left-justified. The increment value to be used for the next key name.

Last Increment

40-bytes, ASCII, left-justified. The highest increment value of keys remaining in the template.

Key Served

1-byte, Y or N. When N, the next increment is 0s and will be used for the next key name.

Template full

1-byte, Y or N. The next increment value equals the last increment value and the next increment has already been used.

Increment Code

The type of incrementing to be performed. 1-byte, ASCII. The value must be one of the following:

H - Hex digits (0-9, A-F, upper case only). Initial value is all 0s.

N – Numeric (0-9). Initial value is all 0s.

A - Alpha Numeric (0-9, A-Z, a-z). Initial value is 0s. Incrementing from numbers to upper case letters then lower case letters (the same as the appearance of the character in the ASCII table).

Get Template List Request

This command returns the value of all the defined template values.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1123.

Get Template List Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00058.

Transaction ID

4-byte, ASCII. Value 1124.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. The value will be Y (Yes) or N (No). Y indicates that there is another buffer following this. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

Constant 1

39-bytes, ASCII, left-justified.

Increment Length 1

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes

Increment Code 1

The type of incrementing to be performed. 1-byte, ASCII. One of the following values will be returned:

H - Hex digits

N- Numeric

A - Alpha Numeric

Constant Length 1

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. The value will be in the range of 00 – 39.

Each buffer will contain Transaction ID, Return Code, More Flag, List Segment Length,, Constant, Increment Length, Increment Code, Constant Length, More Flag.

Get User List For All Keys request

This command returns the value of all the User Access table values.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1111.

Get User List for All Keys response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00014.

Transaction ID

4-byte, ASCII. Value 1112.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, ID, RC, More Flag, Key Name and at least one instance name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

Key Name 1-n

40-bytes, ASCII, left-justified, blank padded on the right.

User Name 1-n

256-bytes, ASCII, left-justified, blank padded on the right.

Get User List For Group request

This command returns a list of the all the users defined for this group.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00260.

Transaction ID

4-byte, ASCII. Value 1087.

Group

256-bytes, ASCII, left-justified, blank padded on the right.

Get User List For Group response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00270.

Transaction ID

4-byte, ASCII. Value 1088.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Group

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored from request.

More Flag

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. Each Instance is 24-bytes.

User 1 through User n

256-bytes, ASCII, left-justified, blank padded on the right.

Get User List For Key request

Return a list of the users authorized to use the named key in the User Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00044.

Transaction ID

4-byte, ASCII. Value 1057.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Get User List For Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00054.

Transaction ID

4-byte, ASCII. Value 1058.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

More Flag

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value. Each Instance is 24-bytes.

User 1 through User n

256-bytes, ASCII, left-justified, blank padded on the right.

Grant Group Access To Key request

This command will add a group Key Name record to the Group Access table. If the record already exists it will return success. The Key Name must already be defined in the Key Access table. A group may be defined to access multiple keys. A key may have multiple groups defined for it.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00300.

Transaction ID

4-byte, ASCII. Value `1069.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Group

256-bytes, ASCII, left-justified, with blank padding on the right.

Grant Group Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00304.

Transaction ID

4-byte, ASCII. Value 1070.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

Group

256-bytes, ASCII, left-justified, with blank padding on the right. Mirrored from request.

Grant User Access To Key request

This command will add a User-Key Name record to the User Access table. If the record already exists a return code will be set. A user may be defined to access multiple keys. A key may have multiple users defined for it. The Key Name must be defined in the Key Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00300.

Transaction ID

4-byte, ASCII. Value 1055.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

User

256-bytes, ASCII, left-justified, with blank padding on the right.

Grant User Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00304.

Transaction ID

4-byte, ASCII. Value 1056.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

User

256-bytes, ASCII, left-justified, with blank padding on the right. Mirrored from request.

Import Certificate request

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This must be the value 00075.

Transaction ID

4-byte, ASCII. Value 1139.

Certificate type

1-byte, ASCII. A - CA certificate. C - Client certificate.

Certificate Name

64-byte, ASCII. CaseSensitive, left justified, blank padded on the right. Must be a file with a .pem extension but the .pem is not included in the name.

Overwrite Flag

1-byte, ASCII. Y - Overwrite existing certificate. N - Do not overwrite

Certificate Length

5-bytes, ASCII. Right-justified, zero-filled on the left. The length of the certificate data field.

Certificate Data

16,305 byte maximum. The binary contents of the .pem certificate file.

Import Certificate response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This will be the value 00078.

Transaction ID

4-byte, ASCII. Value 1140.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Import Private Key request

Upload a private key file.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This must be the value 00074.

Transaction ID

4-byte, ASCII. Value 1143.

Private Key Name

64-byte, ASCII. CaseSensitive, left justified, blank padded on the right. Must be a file with a .pem extension but the .pem is not included in the name.

Overwrite Flag

1-byte, ASCII. Y - Overwrite existing certificate. N - Do not overwrite.

Private Key Length

5-bytes, ASCII. Right-justified, zero-filled on the left. The length of the private key data field.

Private Key Data

16,305 byte maximum. The binary contents of the .pem certificate file.

Import Private Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This will be the Value 00008.

Transaction ID

4-byte, ASCII. Value 1144.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Import Symmetric Key request

This transaction is used to import a symmetric key into Alliance Key manager.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00908.

Transaction ID

4-byte, ASCII. Value 1023.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. The value must be 0128, 0192, or 0256.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

ExpirationDate

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

Rollover Code

1-byte, ASCII, case insensitive. The value N indicates the key never rolls over. The value M indicates the key is manually rolled over. The value of A indicates the key automatically rolls over at the interval you specify.

Rollover Days

4-bytes, ASCII, case insensitive. The number of days in a rollover period. 0000 indicates not rolled over. This field is only referenced if the Rollover Code is ‘A’.

Deletable

1-byte, ASCII, case insensitive. The value Y indicates the key can be deleted. The value N indicates the key cannot be deleted.

Mirror Key

1-byte, ASCII, case insensitive. The value Y indicates the key is mirrored to a high availability Alliance Key Manager server. The value N indicates the key is not mirrored.

Access Flag

User Name

256-bytes, ASCII, left-justified, with blank padding on the right.

Group Name

256-bytes, ASCII, left-justified, with blank padding on the right.

If using the admin console to import an RSA encrypted key the following fields need to be passed in on the command line. They will enable the admin console to write the encrypted key returned from the key server to a file.

Key Format

3-byte, ASCII. The value can be BIN (binary), B16 (Base16 encoded or hex), B64 (Base64 encoded), or RSA (RSA encrypted key

RSA Private Key Name

64-byte, ASCII. Case sensitive, left justified, blank padded on the right. Must have .pem extension. This is the name of the RSA Private Key used to decrypt. If not exporting using RSA then set this field to 64 blanks.

RSA Padding mode

1-byte, ASCII. 1 = RSA_PKCS1_PADDING. 2 = RSA_PKCS1_OAEP_PADDING (recommended). Note: exporting with RSA_NO_PADDING is considered insecure and is therefore not supported. No support is provided for RSA_SSLV23_PADDING padding.

Value

If the request specified RSA (RSA encrypted key) this field contains the key up to 256 bytes in length.

If using the administrative console to import an RSA encrypted key the following fields need to be passed in on the command line. They will enable the administrative console to write the encrypted key returned from the key server to a file.

NOTE: Password protected RSA private keys are NOT supported. You can remove the password protection using an application like openssl.

Import Symmetric Key response

This transaction is the response to the request to import a symmetric key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00072.

Transaction ID

4-byte, ASCII. Value 1024.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key Instance

24-bytes, Base64 encoding

Import Symmetric Key Batch Request

This transaction is used to import a batch of symmetric keys. These keys will share the same User, Group, Access and format values. The Key Name must not already exist in the database.

Note that if the amount of data does not fit into one buffer, you use the More Flag to indicate that an additional buffer will be sent. In the last buffer the More Flag will indicate that no further buffers will be sent. All of the header fields (transaction ID, key size bits, through list segment length) must be repeated in each buffer transmitted, and must have the same values.

If you send multiple keys in a batch, they will all be added to the key store database only if all of the edits for each key pass. If an error is found in any key, all of the keys will be rejected.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The value must be 00618.

Transaction ID

4-byte, ASCII. The value must be Value 1173.

Key Size Bits

4-byte, ASCII, right-justified, with leading zeros. The value must be one of 0128, 0192, 0256

Key Format

3-byte, ASCII. Value must be one of: BIN – binary, B16 - Base16 encoded (hex), B64 - Base64 encoded, RSA - RSA Encrypted key

RSA Private Key Name

64-byte, ASCII. Case sensitive, left justified, blank padded on the right. Must be a file with a .pem extension but the .pem is not included in the name. This is the name of the RSA Private Key used to decrypt. If not exporting using RSA then 64 blanks.

RSA Padding mode

1-byte, ASCII. Value must be one of: 1 - RSA_PKCS1_PADDING, 2 - RSA_PKCS1_OAEP_PADDING (recommended)

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire

Rollover Code

1-byte, ASCII, case insensitive. N - never rolled over. M - Manually rolled over. A - Automatic rollover.

Rollover Days

4-bytes, ASCII, case insensitive. The number of days in a rollover period. 0000 indicates not rolled over. This field is only referenced if the Rollover Code is ‘A’.

Deletable

1-byte, ASCII, case insensitive. Value Y or N.

Mirror Key

1-byte, ASCII, case insensitive. Value Y, N.

Access Flag

1-byte, ASCII. 1 - No control. Anyone can access key. 2 - User control. CN on user cert must match a User-Key Name entry in the User Access table. 3 - Group control. OU on user cert must match a Group-Key Name entry in the Group Access table. 4 - Permissive User + Group control. CN and OU on user cert must match entries in both the User Access and Group Access tables. 5 - Strict User + Group control. CN and OU on user cert must match entries in both the User Access and Group Access tables. Additionally the user must be defined as a member of the group in the group access table.

User Name

256-bytes, ASCII, left-justified, with blank padding on the right. This value is the subject CN on the user’s certificate.

Group Name

256-bytes, ASCII, left-justified, with blank padding on the right. This value is the subject OU on the user’s certificate.

More Flag

1-byte, ASCII, Value Y or N. Y indicates that there is another buffer following this. N indicates this is the last buffer in the series.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The total number of bytes remaining to be read in this segment. The minimum ListSegmentLength is; 40 + 16 = 56. The maximum ListSegmentLength is: 16k.

Key Data

For each key (56 to 296 bytes depending on key value size):

Key name

40 Ascii.

Key Value

16 - 256 bytes.

BIN = Exact length: 16-bytes if 128-bit key, 24-bytes if 192-bit key, 32-bytes if 256-bit key.

B16: Exact length: 32-bytes if 128-bit key, 48-bytes if 192-bit key, 64-bytes if 256-bit key.

B64 : Exact length: 24-bytes if 128-bit key, 32-bytes if 192-bit key, 44-bytes if 256-bit key.

RSA: Exact length: 256-bytes

Import Symmetric Key Batch Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00008.

Transaction ID

4-byte, ASCII. Value 1174.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

List Mirror Names request

This API requests that a list of mirrors be returned.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00004.

Transaction ID

4-byte, ASCII. Value 1133.

List Mirror Names response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00014.

Transaction ID

4-byte, ASCII. Value 1134.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. Y or N. Y indicates that there is another buffer following this. Each buffer will contain the mirror name. The last buffer contains N in this position.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16,360 bytes max value. The following are repeated for each mirror definition.

Mirror Name-n

40-bytes, ASCII, left-justified, blank padded on the right.

Remove All Users From Group request

This command removes all records for the group from the Group Member table and the Group Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00261.

Transaction ID

4-byte, ASCII. Value 1093.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Group

256-bytes, ASCII, left-justified, blank padded on the right.

Remove All Users From Group response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00264.

Transaction ID

4-byte, ASCII. Value 1094.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Group

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored value from request.

Remove Mirror Address request

This API removes a previously configured mirror and ends mirroring.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00044.

Transaction ID

4-byte, ASCII. Value 1131.

Mirror name

40-byte, ASCII, left justified, blank filled. A user-defined, unique name for the mirror.

Remove Mirror Address response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction.. The value will be 00048.

Transaction ID

4-byte, ASCII. Value 1132.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mirror name

40-byte, ASCII, left justified, blank filled. A user-defined, unique name for the mirror.

Remove Template Record request

Use this command to remove a symmetric key template from the server. This only removes the template and does not remove the keys. You can no longer use the Get Next Key API to retrieve the key, but you can use the Get Symmetric Key API.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00048.

Transaction ID

4-byte, ASCII. Value 1125.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following:

Y - If the group-user record was not in the database return OK.

N - Return error if group-user record was not present.

Constant

39-bytes, ASCII, left-justified. This is the constant portion of the key name.

Constant Length

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. Range 00 – 39.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes

Remove Template Record response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00052.

Transaction ID

4-byte, ASCII. The value will be Value 1126.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. Y - If the group-user record was not in the database return OK.. N - Return error if group-user record was not present.

Constant

39-bytes, ASCII, left-justified. Mirrored value from request.

Constant Length

2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. Range 00 – 39.

Increment Length

2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes. Mirrored value from request.

Remove User From All Groups request

This command removes all records for the specified user from the Group Member table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00261.

Transaction ID

4-byte, ASCII. Value 1095.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

User

256-bytes, ASCII, left-justified, blank padded on the right.

Remove User From All Groups response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00264.

Transaction ID

4-byte, ASCII. Value 1096.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

User

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored value from request.

Remove User From Group request

This command removes the user-group record from the Group Member table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00517.

Transaction ID

4-byte, ASCII. Value 1091.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Group

256-bytes, ASCII, left-justified, blank padded on the right.

User

256-bytes, ASCII, left-justified, blank padded on the right.

Remove User From Group response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00520.

Transaction ID

4-byte, ASCII. Value 1092.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

User

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored value from request.

Group

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored value from request.

Report FIPS-140 mode request

This transaction is used to determine if the key server is operating in FIPS-140 mode.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1047.

Report FIPS-140 mode response

This transaction is the response to FIPS-140 mode request.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00041.

Transaction ID

4-byte, ASCII. Value 1048.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mode

1-byte ASCII. The value F indicates that the server is operating in FIPS-140 mode. The value N indicates that the server is not operating in FIPS-140 mode.

Program Version

32-bytes, ASCII, left-justified, blank padded on the right. Major Version, Minor Version, bug or cosmetic fix level.

Database Version

32-bytes, ASCII, left-justified, blank padded on the right. Major Version, Minor Version, bug or cosmetic fix level.

Retrieve Metadata request

Use this command to retrieve a list of symmetric keys and their meta data values by a search on their metadata values.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. 00078 to 01203. The length is calculated as follows:

Transaction ID (4) +

1 to 16 times (75 byte groupings)

Field name (4) +

Separator space (1) +

Selector (2) +

Separator space (1) +

Starting quote (1) +

Data (64) +

Ending quote (1) +

Separator space (1)

-1 as the ending quote for MD16 isn’t followed by a separator character.

Transaction ID

4-byte, ASCII. Value 1053.

1 to 16 groups

Field name

One of MD01, MD02, … , MD16

Space

Single ASCII space character, 0x20.

Selector

EQ (equals)

NE (does not equal)

LT (less than)

LE (less than or equal to)

GT (greater than)

GE (greater than or equal to)

CT (contains)

Space

Single ASCII space character, 0x20.

Field value

Starting single quote (‘) character

64-byte value

Ending single quote (‘) character

Field separator

A single blank character, 0x20

Fields not to be queried may be left out. Fields must be in name order with no duplicates.

Sample:

MD01 EQ ‘ 64-char value 1 ‘ MD12 NE ‘ 64-char value 12 ‘

This will result in an SQL query against metadata fields of the form:

select * from table where MD01=’ 64-char value 1 ‘ and MD12 !=’ 64-char value 12 ‘

Retrieve Metadata response

For queries that have no records match the search criteria the following response will be returned:

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00014.

Transaction ID

4-byte, ASCII. Value 1054.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. N - No further buffers follow.

List Segment Length

5-bytes, ASCII, right-justified, with leading zeros. The number of bytes remaining to be read in this segment. The segment has a 16k bytes max value.

1 or more records are then returned:

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

Instance

24-bytes, Base64 encoding. Case sensitive.

Current

1-byte, ASCII. Y,N.

Key Size Bits

4-bytes, ASCII. The value will be one of the following: 0128, 0192, 0256.

Key Creation Date

8-bytes, ASCII. Format CCYYMMDD.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Expiration Date

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

Rollover code

1-byte, ASCII, case insensitive. N – Never, M – Manual, A – Automatic.

Rollover days

4-bytes, ASCII, case insensitive. Days - number of days until rollover. 0000 if never or manual.

Last rollover date

8-bytes, ASCII, case insensitive. 00000000 if never.

Deletable

1-byte, ASCII, case insensitive. Y – yes, N – no.

Key Revoked Date

8-bytes, ASCII. Format CCYYMMDD. 00000000 indicates the key has not been revoked.

Mirror Key

1-byte, ASCII, case insensitive. Y – yes, N – no.

16 groups (70-byte groupings) Total of 1120 bytes.

Field name

One of MD01, MD02, …, MD16

Field value

Separator

Starting single quote (‘) character

64-byte value

Separator

Ending single quote (‘) character

Revoke All Group Access To Key request

This command removes all records for a single Key Name from the Group Access table. This will remove access to a key from all Groups.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00045.

Transaction ID

4-byte, ASCII. Value 1081.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Revoke All Group Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00048.

Transaction ID

4-byte, ASCII. Value 1082.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from the request.

Revoke All User Access To Key request

This command removes all records for a single Key Name from the User Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction.. This value must be 00045.

Transaction ID

4-byte, ASCII. Value 1065.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Revoke All User Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00048.

Transaction ID

4-byte, ASCII. Value 1066.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

Revoke All User And Group Access To Key request

This command removes the Key Name record from the Key Access table. The key and its instances remain unchanged. Note that this command will make a key unusable until you set the access flag for the key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00045.

Transaction ID

4-byte, ASCII. Value 1109.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Key Name

40-bytes, mirrored value from request.

Revoke All User And Group Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00048.

Transaction ID

4-byte, ASCII. Value 1110.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Key Name

40-bytes, mirrored value from request. Mirrored value from request.

Revoke Group Access To All Keys request

This command removes all records with the group name from the Group Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00261.

Transaction ID

4-byte, ASCII. Value 1101.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Group

256-bytes, ASCII, left-justified, with blank padding on the right

Revoke Group Access To All Keys response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00048.

Transaction ID

4-byte, ASCII. Value 1102.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Group

256-bytes, ASCII, left-justified, with blank padding on the right.

Revoke Group Access To Key request

This command removes the Key Name-Group record from the Group Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00301.

Transaction ID

4-byte, ASCII. Value 1075.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Key Name

40-bytes, mirrored value from request.

Group

256-bytes, ASCII, left-justified, blank padded on the right

Revoke Group Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00304.

Transaction ID

4-byte, ASCII. Value 1076.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request. Mirrored value from request.

Group

256-bytes, ASCII, left-justified, blank padded on the right. Mirrored value from request.

Revoke Key request

This transaction is used to revoke a symmetric encryption key and all of its instances. The keys are retained in the encryption key database but are not available to use. You can revoke an individual instance of a key with the Revoke Key Instance transaction. You can re-activate a revoked key with the Activate Key transaction.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00044.

Transaction ID

4-byte, ASCII. Value 1017

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Revoke Key response

This transaction is the response to the request to revoke a key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00056.

Transaction ID

4-byte, ASCII. Value 1018.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Key Revoked Date

8-bytes, ASCII. The format of this field is CCYYMMDD.

Revoke Key Instance request

This transaction is used to revoke a symmetric encryption key instance. The key instance is retained in the encryption key database but is not available to use. You can re-activate a revoked key instance with the Activate Key Instance transaction.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00068.

Transaction ID

4-byte, ASCII. Value 1031.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Key instance

24-byte, ASCII, Base64 encoded.

Revoke Key Instance response

This transaction is the response to the request to revoke a key instance.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00080.

Transaction ID

4-byte, ASCII. Value 1032.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Key instance

24-byte, ASCII, Base64 encoded.

Key Revoked Date

8-bytes, ASCII. The format of this field is CCYYMMDD.

Revoke User Access To All Keys request

This command removes all records for a single user from the User Access table for all keys. Use this API to remove user access to all encryption keys where the user access is explicitly defined. This operation does not affect users in the group member table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00261.

Transaction ID

4-byte, ASCII. Value 1063.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

User

256-bytes, ASCII, left-justified, blank padded on the right

Revoke User Access To All Keys response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00264.

Transaction ID

4-byte, ASCII. Value 1064.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

User

256-bytes, ASCII, left-justified, blank padded on the right.

Revoke User Access To Key request

This command removes the Key Name-User record from the User Access table.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00301.

Transaction ID

4-byte, ASCII. Value 1061.

Ignore Missing Record Flag

1-byte, ASCII, case insensitive. The value must be one of the following: Y - If the group-user record was not in the database return OK. N - Return error if group-user record was not present.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

User

256-bytes, ASCII, left-justified, blank padded on the right

Revoke User Access To Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00304.

Transaction ID

4-byte, ASCII. Value 1062.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

User

256-bytes, ASCII, left-justified, blank padded on the right.

Rollover request

This transaction is used to perform a manual key rollover (key change) on a symmetric key. If successful the current key instance is saved, a new key instance is created, and the new key instance becomes the default key instance.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This must be the value 00044.

Transaction ID

4-byte, ASCII. Value 1021.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Rollover response

This transaction is the response to the request to change a symmetric key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00072.

Transaction ID

4-byte, ASCII. Value 1022.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Key Instance

24-bytes, Base64 encoding.

Set Key Access Flag request

This command adds a record in the Key Access table for the specified Key Name with the specified Access Flag. If there is already a Key Name record then the Access Flag value is replaced with the one specified on this command. If the record is an exact match for Key Name and Access Flag we return an error code of 0 (OK).

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00045.

Transaction ID

4-byte, ASCII. Value 1105.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Access Flag

1-byte, ASCII. The value must be one of the following:

1 - No control. Anyone can access key

2 - User control. CN on user cert must match a User-Key Name entry in the User Access table.

3 - Group control. OU on user cert must match a Group-Key Name entry in the Group Access table.

4 - User + Group control. CN and OU on user cert must match entries in both the User Access and Group Access tables.

5 - User + Group control - strict. CN and OU on user cert must match entries in both the User Access and Group Access tables. Additionally the user must be defined as a member of the group in the group member table.

Set Key Access Flag response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00049.

Transaction ID

4-byte, ASCII. Value 1106.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-bytes, mirrored value from request.

Access Flag

1-byte, mirrored value from request.

Notes:

User Name = CN = Common Name on the client certificate.
Group Name = OU = Organizational Unit on the client certificate.
Blank CN not allowed., Blank OU is allowed (?).

Access Levels

No control of key access. Flag = 1;
CN of user matches list of users authorized to key. Flag = 2.
OU group level must match group for key access. Flag = 3.
OU + CN must match. Flag = 4.

Set Log Level request

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00006.

Transaction ID

4-byte, ASCII. Value 1155.

Log Level

2-byte, ASCII, right-justified, 0-filled on the left. The value must be in the range of 00-99. The value 00 will create a minimal log (the default value). The value of 50 will create a verbose log.

Set Log Level response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1020.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Set Metadata request

Use this command to set the meta data fields on a symmetric key instance. Meta data can be used to more fully identify a key instance.

The metadata fields are named MD01, MD02, … MD15, MD16. Each field is 64 bytes long and must be composed of only printable upper and lower case letters, numbers, and spaces. Special characters are not supported. The value must start and end with a single quote, which is not included in the 64 bytes.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 01188. The transaction is composed of the following fields with lengths:

Transaction ID (4) +

KeyName (40) +

Instance (24) +

16 times

Field Name (4)

Starting quote (1)

Data (64)

Ending quote (1)

Transaction ID

4-byte, ASCII. Value 1039.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Instance

24-bytes, Base64 encoding. Case sensitive. All blanks will indicate default instance.

Repeating from 1 to 16:

Field name

One of MD01, MD02, …, MD16

Field value

Starting single quote (‘) character. 64-byte value. Ending single quote (‘) character

Sample:

MD01’1111111111222222222233333333334444444444555555555566666666667777’ MD02’value’MD03’ … ‘, … , MD16’ … ‘

All 16 fields must be present and in numeric order from 01 to 16.

Set Metadata Response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00072.

Transaction ID

4-byte, ASCII. Value 1040.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right

Instance

24-bytes, Base64 encoding. Case sensitive.

Set Mirror Address request

This API creates a new configuration for a mirror and makes it active. A unique name must be assigned to the mirror.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00305.

Transaction ID

4-byte, ASCII. Value 1129.

Mirror name

40-byte, ASCII, left justified, blank filled. A user-defined, unique name for the mirror.

HOST Name

256-bytes, ASCII, left justified, blank-padded on the right. Supports dotted decimal addresses and Host names. The address of the key store to send to or receive from.

Port

5-bytes, ASCII, right-justified, zero-filled on the left. The port number to send to.

Set Mirror Address response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1130.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Stop Key Store request

This transaction is used to stop key management services. The services that are stopped include key retrieval, encryption, administration, and key mirroring. To re-start Alliance Key Manager you must log on to the system using your user ID, pass word, and token and restart the application.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1027.

Stop Key Store response

This transaction is the response to the request to stop the key manager.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1028.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Trigger Put request

This API causes the transactions in the queue to be sent if they are in a error retry wait state. If the queue is already sending this command will have no effect. This is not a blocking call. You may use the Get Queue Size API to determine the number of entries in the queue.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00044.

Transaction ID

4-byte, ASCII. Value 1149.

Mirror name

40-byte, ASCII. Left justified, blank filled.

Trigger Put response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00048.

Transaction ID

4-byte, ASCII. Value 1150.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Mirror name

40-byte, ASCII.

Validate Key Database request

This transaction can be used to validate the status of the database. The HMAC values of each key in the database is re-calculated and compared to the stored value. Errors are reported.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1041.

Validate Key Database response

This transaction is a response to the request to validate the encryption key database. Note that this response may include more than one buffer of data. You must inspect the More Flag and receive the responses until the flag indicates the last response. A list of key and instance names of invalid keys is returned.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The minimum length of the remainder of the transaction. 000nn - size of this buffer, will vary with number or instances.

Transaction ID

4-byte, ASCII. Value 1042.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

More Flag

1-byte, ASCII. The value will be Y or N. Y indicates that there is another buffer following this.

Key instance-1 through Key-instance-n

Key Name: 40-byte, ASCII, left-justified, with blank padding on the right.

Key instance: 24-bytes, Base64 encoding.

Chapter 5: RSA Key Management APIs

This chapter contains commands specific to RSA key management. For general key management commands that apply to both symmetric and asymmetric keys, see Chapter 4: Admin APIs.

Activate RSA Private Key request

Use this command to activate the private key of a RSA key pair that has been revoked. This will activate the key immediately, or on a future date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00052.

Transaction ID

4-byte, ASCII. Value 1255.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Activate RSA Private Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1256.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Activate RSA Public Key request

Use this command to activate the private key of a RSA key pair that has been revoked. This will activate the key immediately, or on a future date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00052.

Transaction ID

4-byte, ASCII. Value 1257.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Activate RSA Public Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1258.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Change Private Key Activation Date request

Use this command to activate the private key of an RSA key pair immediately or on a future date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00052.

Transaction ID

4-byte, ASCII. Value 1231.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right.

Activation Date

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Change Private Key Activation Date response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1232.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Change Private Key Deletable Flag request

Use this command to change the deletable flag for an RSA private key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00045.

Transaction ID

4-byte, ASCII. Value 1239.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Deletable Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Private Key Deletable Flag response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00049.

Transaction ID

4-byte, ASCII. Value 1240.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

Deletable Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Private Key Expiration Date request

Use this command to expire the private key of an RSA key pair on a specified date or never.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00052.

Transaction ID

4-byte, ASCII. Value 1235.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

ExpirationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format.

Change Private Key Expiration Date response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1236.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

ExpirationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format.

Change Private Key Mirror Flag request

Use this command to change the mirroring status of an RSA private key. Keys that are mirrored are automatically copied to a high availability server if one has been configured.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00045.

Transaction ID

4-byte, ASCII. Value 1243.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Mirror Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Private Key Mirror Flag response

Transaction length

5-byte, ASCII, right-justified, with leading zeros.The length of the remainder of the transaction. Value 00049.

Transaction ID

4-byte, ASCII. Value 1244.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

Mirror Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Public Key Activation Date request

Use this command to activate the public key of an RSA key pair immediately or on a future date.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00052.

Transaction ID

4-byte, ASCII. Value 1233.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Change Public Key Activation Date response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1234.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

Change Public Key Deletable Flag request

Use this command to change the deletable flag for an RSA public key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00045.

Transaction ID

4-byte, ASCII. Value 1241.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Deletable Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Public Key Deletable Flag response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00049.

Transaction ID

4-byte, ASCII. Value 1242.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

Deletable Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Public Key Expiration Date request

Use this command to expire the public key of an RSA key pair on a specified date or never.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00052.

Transaction ID

4-byte, ASCII. Value 1237.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

ExpirationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key doesn’t expire.

Change Public Key Expiration Date response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1238.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

ExpirationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format.

Change Public Key Mirror Flag request

Use this command to change the mirroring status of an RSA public key. Keys that are mirrored are automatically copied to a high availability server if one has been configured.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value `00045 .

Transaction ID

4-byte, ASCII. Value 1245.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Mirror Flag

1-byte, ASCII, case insensitive. Value Y or N.

Change Public Key Mirror Flag response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00049.

Transaction ID

4-byte, ASCII. Value 1246.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

Mirror Flag

1-byte, ASCII, case insensitive. Value Y or N.

Create RSA Key Pair request

Use this command to create an RSA key pair on AKM.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00579.

Transaction ID

4-byte, ASCII. Value 1207.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

KeySizeBits

5-byte, ASCII, right-justified, with leading zeros. Value 02048, 03072, or 04096.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

ExpirationDate

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

DeletableFlag

1-byte, ASCII, case insensitive. Value Y or N.

MirrorFlag

1-byte, ASCII, case insensitive. Value Y or N.

AccessFlag

1-byte, ASCII. Value 1, 2, 3, 4, or 5. 1 - No control. Anyone can access key. 2 - User control. CN on user cert must match a User-KeyName entry in the UserAccess table. 3 - Group control. OU on user cert must match a Group-KeyName entry in the GroupAccess table. 4 - User + Group control. CN and OU on user cert must match entries in both the UserAccess and GroupAccess tables. 5 - Strict User + Group control. CN and OU on user cert must match entries in both the UserAccess and GroupAccess tables, AND the user must belong to a group that has access.

UserName

256-bytes, ASCII, left-justified, with blank padding on the right.

GroupName

256-bytes, ASCII, left-justified, with blank padding on the right.

Create RSA Key Pair response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00096.

Transaction ID

4-byte, ASCII. Value 1208.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

Echoed from request value. 40-byte, ASCII, left-justified, with blank padding on the right.

Public Key Instance

24-byte, ASCII.

Private Key Instance

24-byte, ASCII.

Delete RSA Key request

Use this command to delete both public and private key by key name.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00044.

Transaction ID

4-byte, ASCII. Value 1217.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Delete RSA Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1218.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

KeyDeletedDate

8-bytes, ASCII. CCYYMMDD format.

Delete RSA Key Instance request

Use this command to delete an RSA key by instance.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00068.

Transaction ID

4-byte, ASCII. Value 1211.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Instance

24-bytes, Base64 encoding. Case sensitive.

Delete RSA Key Instance response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00072.

Transaction ID

4-byte, ASCII. Value 1212.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Instance

24-bytes, Base64 encoding. Case sensitive.

Delete RSA Private Key request

Use this command to delete an RSA private key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00044.

Transaction ID

4-byte, ASCII. Value 1251.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Delete RSA Private Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1252.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

KeyDeletedDate

8-bytes, ASCII. CCYYMMDD format.

Delete RSA Public Key request

Use this command to delete an RSA public key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00044.

Transaction ID

4-byte, ASCII. Value 1253.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Delete RSA Public Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1254.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

KeyDeletedDate

8-bytes, ASCII. CCYYMMDD format.

Display RSA Key Name List request

Use this command to display a list of RSA keys on AKM.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00008.

Transaction ID

4-byte, ASCII. Value 1219.

RSA Key Type

4-byte, ASCII. Value Pub , Priv, or Both. Case insensitive.

Display RSA Key Name List response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. Value 00008 (the sum of the Transaction ID + Return Code) if ReturnCode is not 0000. If Return Code is 0000, the value is 00014 (TransactionID + ReturnCode + MoreFlag + ListSegmentLength).

Transaction ID

4-byte, ASCII. Value 1220.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

MoreFlag

1-byte, ASCII. Value Y or N. Y indicates that there is another buffer following this. Each buffer will contain Transaction Length, ID, RC, MoreFlag, KeyName. The last buffer contains N in this position.

ListSegmentLength

KeyName 1-n

40-byte, ASCII, left-justified, with blank padding on the right.

RSAKeyType 1-n

4 bytes. Value Pub or Priv.

The response is returned in alphabetic order by KeyName.

Display RSA Key Policy request

Use this command to show the policy attributes applied to a key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00072.

Transaction ID

4-byte, ASCII. Value 1221.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Instance

24-bytes, Base64 encoding. Case sensitive. An all blank value references the current instance.

RSA Key Type

4-byte, ASCII. Value Priv or Pub . Not case sensitive. May be blank if Instance is specified.

Display RSA Key Policy response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00153.

Transaction ID

4-byte, ASCII. Value 1222.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Name

40-byte, ASCII, left-justified, with blank padding on the right. Embedded blanks OK. Case sensitive.

RSA Key Type

4-byte, ASCII. Value Pub or Priv.

Instance

24-bytes, Base64 encoding. Case sensitive.

Paired Instance

24-bytes, Base64 encoding. Case sensitive.

KeySizeBits

5-bytes, ASCII. Value 01024, 02048, 03072, or 04096.

KeyCreationDate

8-bytes, ASCII. CCYYMMDD format.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

ExpirationDate

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

DeletableFlag

1-byte, ASCII, case insensitive. Value Y or N.

KeyRevokedDate

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates the key has not been revoked.

MirrorFlag

1-byte, ASCII, case insensitive. Value Y or N.

TimeStamp

14-bytes, ASCII. CCYYMMDDHHMMSS format. The timestamp of the last time the key was created or changed.

Export RSA Public Key request

Use this command to export an RSA public key from AKM to your filesystem.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00068.

Transaction ID

4-byte, ASCII. Value 1227.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right. May be blank if instance is provided.

Instance

24-bytes, Base64 encoding.

All blanks means use key name only. If key name and instance use key name and edit for instance.

Export RSA Public Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00083.

Transaction ID

4-byte, ASCII. Value 1228.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Key Name

40-byte, ASCII, left-justified, with blank padding on the right. May be blank if instance is provided.

Instance

24-bytes, Base64 encoding.

KeySizeBits

5-bytes, ASCII. Value 01024, 02048, 03072, or 04096.

Key Length

5-byte, ASCII, right justified with leading zeros. The length of the key value in the following field.

Key Value

The binary contents of the key in DER format.

Import RSA Private Key request

Use this command to import an RSA private key from your filesystem into your AKM server.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00589.

Transaction ID

4-byte, ASCII. Value 1223.

KeyName

40-byte, ASCII. Case sensitive, left justified, blank padded on the right.

KeySizeBits

5-bytes, ASCII. Values 02048, 03072, or 04096.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

ExpirationDate

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

DeletableFlag

1-byte, ASCII, case insensitive. Value Y or N.

MirrorFlag

1-byte, ASCII, case insensitive. Value Y or N.

AccessFlag

1-byte, ASCII. Value 1, 2, 3, or 4. 1 - No control. Anyone can access key. 2 - User control. CN on user cert must match a User-KeyName entry in the UserAccess table. 3 - Group control. OU on user cert must match a Group-KeyName entry in the GroupAccess table. 4 - User + Group control. CN and OU on user cert must match entries in both the UserAccess and GroupAccess tables.

UserName

256-bytes, ASCII, left-justified, with blank padding on the right.

GroupName

256-bytes, ASCII, left-justified, with blank padding on the right.

ValueCode

3-bytes, ASCII, not case sensitive. Value DER (DER encoded binary RSA private key).

ValueLength

5-bytes, ASCII. Right-justified, zero-filled on the left. The length of the value field.

Value

This is the binary value of a DER encoded private key.

Import RSA Private Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1224.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Instance

24-bytes, Base64 encoding. Case sensitive.

Paired Instance

24-bytes, Base64 encoding. Case sensitive. If there is no paired public key this field will be blanks.

Import RSA Public Key request

Use this command to import an RSA public key from your filesystem into your AKM server.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00589.

Transaction ID

4-byte, ASCII. Value 1229.

KeyName

40-byte, ASCII. CaseSensitive, left justified, blank padded on the right.

KeySizeBits

5-bytes, ASCII. Value 01024, 02048, 03072, or 04096`.

ActivationDate

8-bytes, ASCII, case insensitive. CCYYMMDD format. 00000000 indicates key is immediately usable.

ExpirationDate

8-bytes, ASCII. CCYYMMDD format. 00000000 indicates key does not expire.

DeletableFlag

1-byte, ASCII, case insensitive. Value Y or N.

MirrorFlag

1-byte, ASCII, case insensitive. Value Y or N.

AccessFlag

1-byte, ASCII. Value 1, 2, 3, or 4. 1 - No control. Anyone can access key 2 - User control. CN on user cert must match a User-KeyName entry in the UserAccess table. 3 - Group control. OU on user cert must match a Group-KeyName entry in the GroupAccess table. 4 - User + Group control. CN and OU on user cert must match entries in both the UserAccess and GroupAccess tables.

UserName

256-bytes, ASCII, left-justified, with blank padding on the right.

GroupName

256-bytes, ASCII, left-justified, with blank padding on the right.

ValueCode

3-bytes, ASCII, not case sensitive. Value DER (DER encoded binary RSA private key).

ValueLength

5-bytes, ASCII. Right-justified, zero-filled on the left. The length of the value field.

Value

This is the binary value of a DER encoded private key.

Import RSA Public Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00096.

Transaction ID

4-byte, ASCII. Value 1230.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Instance

24-bytes, Base64 encoding. Case sensitive.

Paired Instance

24-bytes, Base64 encoding. Case sensitive. If there is no paired public key this field will be blanks.

Revoke RSA Private Key request

Use this command to revoke an RSA private key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00044.

Transaction ID

4-byte, ASCII. Value 1247.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Revoke RSA Private Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1248.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

KeyRevokedDate

8-bytes, ASCII. CCYYMMDD format. This date is applied to instances not previously revoked.

Revoke RSA Public Key request

Use this command to revoke an RSA public key.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00044.

Transaction ID

4-byte, ASCII. Value 1249.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

Revoke RSA Public Key response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. Value 00056.

Transaction ID

4-byte, ASCII. Value 1250.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

KeyName

40-byte, ASCII, left-justified, with blank padding on the right.

KeyRevokedDate

8-bytes, ASCII. CCYYMMDD format. This date is applied to instances not previously revoked.

Chapter 6: Debug Specifications

These transactions are not a part of the Alliance Key Manager implementation and are only available to partners working with debug versions of Alliance Key Manager.

Clear Group Access Table request

The command removes all records from the Group Access table. If the table does not exist a new one is created. This command is only available in DEBUG versions of the key server. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction.. The value will be 00004.

Transaction ID

4-byte, ASCII. Value 1083.

Clear Group Access Table response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1084.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Clear Group Member Table request

Remove all records from the Group Member table. If the table does not exist a new one is created. This command is only available in DEBUG versions of the key server. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00004.

Transaction ID

4-byte, ASCII. Value 1097.

Clear Group Member Table response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1098.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Clear Key Access Table request

Remove all records from the KeyAccess table. If the table does not exist a new one is created. This command is only available in DEBUG versions of the key server. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1103.

Clear Key Access Table response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value will be 00008.

Transaction ID

4-byte, ASCII. Value 1104.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Clear Symmetric Keys request

This command removes all records from the keys table. This transaction is only available in the DEBUG version of the key server. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00016.

Transaction ID

4-byte, ASCII. Value 1077.

Command Name

12-bytes. Not case sensitive. Value is ClearSymKeys This is to prevent a mistake in the transaction Id from clearing the file.

Clear Symmetric Keys response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00020.

Transaction ID

4-byte, ASCII. Value 1078.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Command Name

12-bytes. Value echoed from request.

Clear Template Table request

Remove all records from the Template table. This transaction is only available in the DEBUG version of the key server. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00022.

Transaction ID

4-byte, ASCII. Value 1051.

Command Name

18-bytes. Not case sensitive. Value is ClearTemplateTable. This is to prevent a mistake in the transaction Id from clearing the file.

Clear Template Table response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00026.

Transaction ID

4-byte, ASCII. Value 1052.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Command Name

18-bytes. Value echoed from request.

Clear User Access Table request

The transaction removes all records from the User Access table. If the table does not exist a new one is created. This command is only available in DEBUG versions of the key server. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. The value must be 00004.

Transaction ID

4-byte, ASCII. Value 1067.

Clear User Access Table response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00008.

Transaction ID

4-byte, ASCII. Value 1068.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition

Create Database request

This command creates the key store database file and adds all the tables to it. If the file exists it is cleared and a new instance created. This transaction is only available in the DEBUG version of the key store. If mirroring is active, this command will cause mirrored servers to be out of sync.

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value must be 00012.

Transaction ID

4-byte, ASCII. Value 1107.

Command Name

8-bytes. Not case sensitive. Value is CreateDB. This is to prevent a mistake in the transaction Id from clearing the file.

Create Database response

Transaction length

5-byte, ASCII, right-justified, with leading zeros. The length of the remainder of the transaction. This value will be 00016.

Transaction ID

4-byte, ASCII. Value 1108.

Return Code

4-byte, ASCII, right-justified, with leading zeros. Value 0000 indicates success. Value 0001-9999 represents an error condition.

Command Name

8-bytes. Value echoed from request.

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 xxxx for a definition of Base64 encoding and decodikng.

Certificate authority (CA) certificate

A certificate authority is an entity responsible for creating client and server keys and certificates. It can be a public entity like Verisign, or can be created using commercial key management software or open source software such as OpenSSL. The certificate authority creates a CA certificate for use by the client and server applications and defines the trust of the certificate chain.

Client certificate

A client certificate identifies the client end point in TLS communications and contains the public key of the client. The client certificate is installed on the client and is used when negotiating the TLS connection between the client and key manager server.

Encryption key

The encryption key is the actual binary value used for encryption operations. It can be 128 bits (16 bytes), 192 bits (), 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 instance name

Each encryption key is defined by its key name and its instance name. When a key is created you provide the key name and an instance name is created for you. Over the life of a key there may be many unique instances of the key.

Key name

The name of the encryption key. This is a name the security administrator assigns to the encryption key when it is created. It can be any name from 1 to 40 characters in length. This name, in conjunction with the key instance name, is used to retrieve a key from the key server.

Server certificate

A server certificate identifies the key manager server end point in TLS communications and contains the public key of the server. The server certificate is installed on the AKM server and is used when negotiating the TLS connection between the client and key manager server.

Transport Layer Security (TLS)

TLS is the open standard for secure and authenticated TLS 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 admin 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 AKM admin 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:

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

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.

AKM Admin API Reference

Chapter 1: About This Manual

AKM Admin API

Who is this for?

Other resources

Notices

Change log

Chapter 2: Preparation

Overview

Licensing

Certificates and private keys

Server information

Checklist

Chapter 3: Introduction

Certificates and private keys

Client/server architecture

TLS version

TLS sessions

Requests and responses

Data formats

Return codes

Bulk key creation

Procedures

Chapter 4: Admin APIs

Activate Key request

Activate Key response

Activate Key Instance request

Activate Key Instance response

Add User To Group request

Add User To Group response

Administrative NOOP request

Administrative NOOP response

Authorize Administrator request

Authorize Administrator response

Automatically Generate Keys Request

Automatically Generate Keys response

Change Activation Date request

Change Activation Date response

Change Deletable request

Change Deletable response

Change Expiration Date request

Change Expiration Date response

Change Mirror Key request

Change Mirror key response

Change Next Increment request

Change Next Increment response

Change Rollover request

Change Rollover response

Create Symmetric Key request

Create Symmetric Key response

Crypto Self-Test request

Crypto Self-Test response

Delete Certificate request

Delete Certificate response

Delete Key request

Delete Key response

Delete Key Instance request

Delete Key Instance response

Delete Private Key request

Delete Private Key response

Display Key Instance List request

Display Key Instance List response

Display Key Name List request

Display Key Name List response

Display Symmetric Key policy request

Display Symmetric Key policy response

Export certificate request

Export Certificate response

Export Symmetric Key request

Export Symmetric Key response

Export Symmetric Key Batch Request

Export Symmetric Key Batch Response

Force Key Sync Request

Force Key Sync Response

Force Rollover request

Force Rollover response

Get Certificate List Request

Get Certificate List Response

Get Group List For All Keys request

Get Group List For All Keys response