Starting an XML Session
Immediately after you establish a connection with the CipherTrust Manager on port 9000, you can negotiate the XML protocol version to be used for the entire session and you can authenticate to the NAE Server. You are not required to do either of these actions to continue with your session, but should you choose to do either, you must do them immediately after connecting. If you decide to do both, you must do them in the correct order: negotiate the protocol version first (VersionRequest), then authenticate (AuthRequest).
If you opt not to authenticate the session or negotiate a protocol version, you must do that in each request.
The XML Interface accepts requests to:
Negotiate the XML protocol version (VersionRequest)
Authenticate the session with a valid username and password (AuthRequest)
Get the server's model number, Box ID, and software version (DeviceInfoRequest)
VersionRequest
Negotiate a protocol version with the CipherTrust Manager.
The KeySecure Classic can communicate with clients using all XML Interface versions ranging from 1.1-2.10 and 3.0-3.1.
The NextGen KeySecure can communicate with clients using XML Interface versions mentioned above, and versions 6.0 or higher.
The CipherTrust Manager 2.14 supports the following XML versions:
Minimum version | Maximum version |
---|---|
2.0 | 2.10 |
3.0 | 3.1 |
6.0 | 6.9 |
7.0 | 7.1 |
We recommend using the most recent version of the interface, because that gives your clients access to the CipherTrust Manager's latest features.
You have two options when setting the protocol version:
Negotiate a version for the session by sending a VersionRequest element. List each desired protocol in its own Version element. Place the Version elements in a VersionList - put them in order of preference. The server selects the first protocol it supports. Then, both client and server use that version for the entire session. For example:
<VersionRequest> <MessageVersion>1.0</MessageVersion> <ID>test1</ID> <VersionList> <Version>2.10</Version> <Version>2.10</Version> </VersionList> </VersionRequest> <VersionResponse> <Version>2.10</Version> <ID>test1</ID> <Success>true</Success> <ServerVersion>2.0.0</ServerVersion> </VersionResponse>
If you choose this option, the VersionRequest element must be the first request sent to the CipherTrust Manager after establishing a connection. Sending the VersionRequest element later on in the session will close the connection.
The CipherTrust Manager chooses the first item it can support and skips those it cannot. If the server does not support any of the versions in the list, it returns a failure message and closes the connection. If this happens, you should either upgrade your CipherTrust Manager, or negotiate an earlier protocol version.
Submit the protocol version in each request. When this is done, the server responses will also contain a Version element. (In this document, most examples do not include a Version element.) For example, when sending a KeyGenRequest, you must include a Version element, in the proper location:
<KeyGenRequest> <Version><XMLProtocolVersion></Version> <ID>3</ID> <KeyName>key_a</KeyName> <KeySize>256</KeySize> <Algorithm>AES</Algorithm> </KeyGenRequest> <KeyGenResponse> <Version><XMLProtocolVersion></Version> <ID>3</ID> <Success>true</Success> <Fingerprint>5AC1CB6A1BC41A76</Fingerprint> <KeyName>key_a</KeyName> </KeyGenResponse
You cannot choose both options. If you use the VersionRequest element and you later include a Version element in a request, that request will fail and the connection will close.
<VersionRequest>
<MessageVersion>1.0</MessageVersion>
<ID>...</ID>
<VersionList>
<Version>2.4</Version>
<Version>2.3</Version>
<Version>2.2</Version>
</VersionList>
</VersionRequest>
Element | Description |
---|---|
MessageVersion | Contains the XML protocol version for this message. This element must contain the value 1.0 - that is the protocol version used for version negotiation. |
ID | Contains the user-specified request ID. |
VersionList | Contains a list of Version elements that are supported by the client application. |
Version | Contains a protocol version string. For KeySecure Classic, the protocol version can be 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10, and 3.0. For Next Generation KeySecure, XML Interface version 6.0 or higher are supported. |
VersionResponse
Server response to a VersionRequest.
If the server supports one of the protocols submitted by the client, the server sends a successful VersionResponse. Otherwise, the server sends an unsuccessful VersionResponse.
<VersionResponse>
<Version>...</Version>
<ID>...</ID>
<Success>true</Success>
<ServerVersion>...</ServerVersion>
</VersionResponse>
Element | Description |
---|---|
Version | Contains the protocol version that will be used for all subsequent communications for the duration of the session. |
ID | Contains the user-specified request ID. |
Success | Indicates whether the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the |
ServerVersion | Indicates the server software version. |
AuthRequest
Authenticate the XML session with a valid username and password.
The communication between the client and the server varies slightly, depending on whether your CipherTrust Manager configuration requires users to authenticate.
You can authenticate your XML session by sending an AuthRequest element with a valid username and password. In an authenticated session, the client operates as the selected user; all keys and key operations available to that user are available, and all keys created during the session are owned by that user.
To use non-global keys, you must authenticate. If you choose not to authenticate, the client operates as a global user; only global keys and key operations are available, and all keys created during the session are global keys.
If you are negotiating a version and you also want to authenticate users, you must send an AuthRequest immediately after you send the VersionRequest. If you are not negotiating a version, and you want to authenticate users, you must send the AuthRequest immediately after establishing an XML connection to the NAE Server. You cannot authenticate later in the session.
After your client authenticates, all other requests sent through the same connection are assumed to belong to the user specified in the authentication request. If your client drops the connection and establishes a new connection, you should authenticate again.
Specifying LDAP and Multi-Domain Client Usernames in NAE AuthRequest
The connection and/or username can be specified in 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>|<ldap-connection>|<username>
An LDAP user in a specific domain. For example, domain|ldap-connection|joe.
<domain>||<username>
A root domain user assigned in a specific domain. For example, domain||joe.
<domain>|<auth_domain>||<username>
A local user created inside a specific domain, named "auth-domain". For example, domain|auth-domain||joe.
Note
You can specify either domain ID or domain name for a specific domain.
Root-domain user:
<AuthRequest>
<ID>...</ID>
<User>...</User>
<Passwd>...</Passwd>
</AuthRequest>
LDAP user:
<AuthRequest>
<ID>...</ID>
<User>ldap-connection|username</User>
<Passwd>...</Passwd>
</AuthRequest>
LDAP user in a domain:
<AuthRequest>
<ID>...</ID>
<User>domain|ldap-connection|username</User>
<Passwd>...</Passwd>
</AuthRequest>
Assigned user in a domain:
<AuthRequest>
<ID>...</ID>
<User>domain||username</User>
<Passwd>...</Passwd>
</AuthRequest>
User created in a specific domain:
<AuthRequest>
<ID>...</ID>
<User>domain|auth-domain||username</User>
<Passwd>...</Passwd>
</AuthRequest>
Element | Description |
---|---|
ID | Contains the user-specified request ID. |
User | Contains a valid username. |
Passwd | Contains the password for the user. |
AuthResponse
Server response to an AuthRequest.
If the server accepts the authorization request submitted by the client, the server sends a successful AuthResponse. Otherwise the server sends an unsuccessful AuthResponse. An AuthResponse contains the following information:
<AuthResponse>
<ID>...</ID>
<Success>true</Success>
</AuthResponse>
Element | Description |
---|---|
ID | Contains the user-specified request ID. |
Success | Indicates whether the operation was successful. true indicates success, false indicates failure. When the operation is successful, the remainder of the session is authenticated.When the operation is unsuccessful, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
DeviceInfoRequest
Get the server's model number, Box ID, and software version
<DeviceInfoRequest>
<ID>...</ID>
</DeviceInfoRequest>
Element | Description |
---|---|
ID | Contains the user-specified request ID. |
DeviceInfoResponse
Server response to a DeviceInfoRequest.
<DeviceInfoResponse>
<ID>...</ID>
<Success>true</Success>
<Model>...</Model>
<BoxID>...</BoxID>
<SoftwareVersion>...</SoftwareVersion>
<DateTime>...<DateTime>
<Vendor>...<Vendor>
</DeviceInfoResponse>
Element | Description |
---|---|
ID | Contains the user-specified request ID. |
Success | Indicates whether the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the elements described below. When the operation is unsuccessful, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
Model | Contains the hardware model number. |
BoxID | Contains the device's serial number. |
SoftwareVersion | Contains the server's software version number. |
DateTime | Contains a UTC timestamp in the format yyyy-mm-dd hh:mm:ss. |
Vendor | Contains the name of the software vendor. |
Examples of Initial Requests and Responses
This section provides examples of XML sessions that illustrate successful and unsuccessful requests.
Connection, Version Negotiation
In the example below, the client successfully negotiates XML protocol version 2.10.
<VersionRequest>
<MessageVersion>1.0</MessageVersion>
<ID>123</ID>
<VersionList>
<Version>2.10</Version>
</VersionList>
</VersionRequest>
<VersionResponse>
<Version>2.10</Version>
<ID>123</ID>
<Success>true</Success>
<ServerVersion>2.0.0</ServerVersion>
</VersionResponse>
Connection, Version Negotiation, Authentication
In the example below, the client first successfully negotiates XML protocol version 2.10, then successfully authenticates as user NAE_User1.
<VersionRequest>
<MessageVersion>1.0</MessageVersion>
<ID>123</ID>
<VersionList>
<Version>2.10</Version>
</VersionList>
</VersionRequest>
<VersionResponse>
<Version>2.10</Version>
<ID>123</ID>
<Success>true</Success>
<ServerVersion>7.1.0-14</ServerVersion>
</VersionResponse>
<AuthRequest>
<ID>456</ID>
<User>NAE_User1</User>
<Passwd>SecretPassword</Passwd>
</AuthRequest>
<AuthResponse>
<ID>456</ID>
<Success>true</Success>
</AuthResponse>
Connection, Version Negotiation, Failed Authentication
In the example below, the client first successfully negotiates XML protocol version 2.10, then fails to authenticate as user NAE_User1.
<VersionRequest>
<MessageVersion>1.0</MessageVersion>
<ID>123</ID>
<VersionList>
<Version>2.10</Version>
</VersionList>
</VersionRequest>
<VersionResponse>
<Version>2.10</Version>
<ID>123</ID>
<Success>true</Success>
<ServerVersion>2.0.0</ServerVersion>
</VersionResponse>
<AuthRequest>
<ID>456</ID>
<User>NAE_User1</User>
<Passwd>SecretPassword</Passwd>
</AuthRequest>
<AuthResponse>
<ID>456</ID>
<Success>false</Success>
<FatalError>202</FatalError>
<ErrorString>Invalid username or password</ErrorString>
</AuthResponse>
Connection, Negotiation, Authentication
In the example below, the client first successfully negotiates XML protocol version 2.10, then successfully authenticates as user NAE_User1.
<VersionRequest>
<MessageVersion>1.0</MessageVersion>
<ID>1</ID>
<VersionList>
<Version>2.10</Version>
</VersionList>
</VersionRequest>
<VersionResponse>
<Version>2.10</Version>
<ID>1</ID>
<Success>true</Success>
<ServerVersion>2.0.0</ServerVersion>
</VersionResponse>
<AuthRequest>
<ID>2</ID>
<User>NAE_User1</User>
<Passwd>SecretPassword</Passwd>
</AuthRequest>
<AuthResponse>
<ID>2</ID>
<Success>true</Success>
</AuthResponse>