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 the following versions of the XML Interface: 2.2,2.3,2.4,2.5,2.6,2.7, 2.8, 2.9, and 2.10.

The NextGen KeySecure can communicate with clients using XML Interface versions as stated above, and with 6.0 and higher version as well.

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>

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>

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 local user in a specific domain. For example, domain||joe.

To limit key operations to a domain, specify the user in the following format:

• <domain>||<username>

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>

Domain user:

<AuthRequest>
<ID>...</ID>
<User>domain||username</User>
<Passwd>...</Passwd>
</AuthRequest>

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>

DeviceInfoRequest

Get the server's model number, Box ID, and software version

<DeviceInfoRequest>
   <ID>...</ID>
</DeviceInfoRequest>

DeviceInfoResponse

Server response to a DeviceInfoRequest.

<DeviceInfoResponse>
   <ID>...</ID>
   <Success>true</Success>
   <Model>...</Model>
   <BoxID>...</BoxID>
   <SoftwareVersion>...</SoftwareVersion>
   <DateTime>...<DateTime>
   <Vendor>...<Vendor>
</DeviceInfoResponse>

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>