Introduction

wAuth is the proprietary communication protocol used by wClient implementations to communicate with the WiKID Authentication Server (WAS). The protocol is based on the exchange of XML fragments over a SSL/TLS socket connection.   Before using the protocol from scratch, make sure that a wClient implementation for your language does not already exist.  We currently have packages for Python, PHP, Ruby and Java (the java jar file is included with the WiKID server).  We are publishing the protocol to encourage developers to add two-factor authentication to their applications, facilitate the submission of wClient packages from the community and to encourage peer review.

The example.jsp page that comes with the server (in /opt/WiKID/tomcat/webapps/WiKIDAdmin/) is an example implementation of the the java wClient.  It is kept up to date. 

Network Communication

The WAS opens a SSL/TLS listener during server startup. The default port is 8388 but can be changed on the server is desired. wClient APIs allow the server port to specified to accommodate non-default installations.

The WAS connection is certificate authenticated. The client must use a non-revoked certificate issued by the WAS that it is connecting to. The server will generate a certificate for each wAuth client that is created. The certificate and private key are stored in a PKCS12 keystore. This keystore must be used to successfully establish a secure connection to the wAuth listener.

Once a successful SSL connection to the WAS has been established the wClient sends a connect transaction with the wClient version information. If the client version is compatible with the server the server will respond with the servers wAuth version information.

Once a successful connection has been acknowledged the client/server relationship is established and ready to process any other transactions. The ping transaction my be used at any point to verify that the underlying connection is still valid. Typically, the wClient issues a ping before each substantive transaction and will automatically reconnect if the connection has been lost.

Transactions

The remainder of this document consists of the XML fragment transactions used to communicate with the WAS. The transaction set prototype provides an XML skeleton to describe each transaction. The client populates the skeletal transactions with the appropriate values and transmits them to the server which returns them to the client with the results of the transaction populated.

Following the prototype section are examples of each wClient transaction (Out) and the server response transaction (In).