NAE-XML Interface Development
This document describes how to configure the NAE interface of the CipherTrust Manager using XML.
The XML interface is a protocol for communication between the CipherTrust Manager's Network-Attached Encryption (NAE) Server and a client, for example, CADP. The XML client can be any application that communicates with the server using XML over a configured port, usually 9000.
Note
By default, the CipherTrust Manager runs on TLS, unlike Classic KeySecure, which runs on TCP.
The API supports cryptographic operations such as:
Encryption and decryption
MAC generation and verification
Digital signatures creation and verification
In addition, the XML interface allows you to remotely generate and manage cryptographic keys, to export certificates and certificate authorities, and to sign SSL certificates. The XML interface is compatible with industry standards, such as JCE, PKCS #11, and .NET.
We recommend that clients establish a secure connection with the NAE Server. For added security, we also recommend that you require clients to authenticate themselves to the server.
In a typical situation, the client sends a cryptographic request to the server. The cryptographic request contains an XML header followed by chunked binary data. The server performs the required operation and then sends a response, which consists of an XML header followed by binary data. Typically, a single secure link - a persistent connection - is used for many request/response pairs.
In addition to cryptographic requests, the client might send key administration requests, random number generation requests, or other administrative requests. When an error occurs, the server sends an error response to the client. If the error was fatal, the server closes the connection. If the error was not fatal, the connection stays open.
The XML interface supports the following features:
User Management - Create and delete users, modify user passwords and permissions, query user information. For more information, see User Requests.
Group Management - Create and delete groups, add and remove users from groups, query group information. For more information, see User Group Requests.
Key Management - Generate keys, delete keys, query key information, import keys, export keys, replicate keys, modify custom key attributes, clone keys, modify key metadata, change key version state, export public key. For more information, see Key Management Operations and Importing, Exporting, and Replicating Keys.
Certificates and Certificate Authorities - Export certificates, export key certificates, export certificate authorities, create SSL certificate signing requests, and sign SSL certificates with a local CA. For more information, see Certificate and CA Requests.
Cryptography - Including encryption & decryption, MAC & MAC verification, and signature and signature verification. Send data in single or multiple chunks. Send requests individually or in batch. Generate random numbers between 1 and 128 kb. For more information, see Cryptographic Operations.
Logging - Send messages to the KeySecure Logs. For more information, see Logging.
Common XML elements
The following elements are commonly used in the XML requests and responses:
| Element | Description |
|---|---|
| ID | Contains the request ID, which can be an arbitrary non-empty string of numbers, Latin alphabet characters, and the following punctuation symbols:! # $ % ( ) * + , - . : ; = @ ^ _ | ~ /The length of the ID string should not exceed 32 characters. The ID element is mandatory for all client requests. The server response will contain the same ID. Although the server does not require you to use unique IDs, we recommend it. Using a unique ID for each request will help you associate requests and responses. |
| Success | Indicates whether the cryptographic operation was successful. The valid values are true and false. Note, however, that even if the server reports a successful operation in the response header, it might still report an error when sending the data section. |
| FatalError | Included in the response header when a fatal error occurs during the operation. The FatalError element contains the error ID for the error that occurred. When a fatal error occurs, the server closes the connection. See Error Messages for a complete list of error IDs and strings. |
| NonFatalError | Included in the response header when a non-fatal error occurs during the cryptographic operation. The NonFatalError element contains the error ID for the error that occurred. When a non-fatal error occurs, the connection remains open. This allows the client to continue making requests to the server. See Error Messages for a complete list of error IDs and strings. |
| ErrorString | The ErrorString element contains the relevant error string for the error that occurred. See Error Messages for a complete list of error IDs and strings. |
Specifying LDAP and multi-domain client usernames in NAE certificates
The connection and/or username can be specified in the following formats:
<username>- A local user in the root domain. For example, joe.<ldap-connection>|<username>An LDAP user in the root domain. For example, ldap-connection|joe.
<domain-id>|<ldap-connection>|<username>An LDAP user in a specific domain. For example, domain-id|ldap-connection|joe.
<domain-id>||<username>A local user in a specific domain. For example, domain-id||joe.
<domain-id>|<auth-domain>|<connection>|<username>A local user created inside a specific domain, named "auth-domain". For example, domain-id|auth-domain|local_account|joe.
Note
To authenticate a domain user:
1. Add the trusted CA of the domain to the root domain's external CAs list.
2. Add that external CA of the root domain to the NAE interface's trusted external CAs list.
When browsing the GUI, users can be identified from the source property. The user is displayed in either of the formats listed above. A local user is displayed as local|<username>.
Adding domain CA to the interface as external CA
To add domain CA to the interface as external CA:
Log on to the CipherTrust Manager GUI.
Switch to the desired domain.
Tip
To create a new domain, click here.
Navigate to CA > Local. The list of available CAs is displayed.
Click the ellipsis icon corresponding to the CA.
Click Copy/Download the local CA.
Switch to Root domain.
Navigate to CA > External.
Click Add External CA. The Add External Certificate screen appears.
Provide Display name.
Either upload or paste the Certificate that you copied/downloaded in the step 5.
Click Add External CA. The newly created external CA appears on the External Certificate Authorities page.
Navigate to Admin Settings > Interfaces.
Click nae and select the external CA created in step 11 from the External Trusted CAs drop-down list.
Click Update.
Supported Key Formats
| Object Type | Key Formats |
|---|---|
| Symmetric | • raw |
| Private Key | • pkcs1 • pkcs8 • sec1 • pkcs12 |
| Public Key | • pkcs1 • pkcs6 • sec1 |
| Certificate | • pkcs12 • x.509 |
| Opaque | • raw |
