This document describes the external interface to the Zonar Web inspection management system. This interface may be used by other software packages to exchange information with the Zonar Web system.
The OMI is a web based interface to a Zonar Web account using the Common Gateway Interface (CGI) protocol. Clients using the OMI send either HTTP GET or POST requests to the server and receive replies in XML format. It is essentially the standard Zonar Web system with XML replies rather than HTML. Eventually all of the functionality present in Zonar Web will be available through the OMI, currently however only a subset of the most widely used functions is present.
Clients wishing to use the OMI must provide several pieces of information to the server in order to form a valid request. The basic required information is:
The Zonar Web account to access. Without identifying the account nothing else can happen.
This code is usually expressed as a combination of three letters and a 4 digit number, for example: abc1234 .
Account codes are case sensitive and are always lower case.
The account may be specified as the hostname portion of the server name in the request URL like this:
abc1234.zonarsystems.net. This is the preferred method and client developers should use it.
Alternately the account code may be specified with the customer variable like this:
https://foobar.zonarsystems.net/interface.php?customer=abc1234.
Before an action can be performed the user requesting the action must be identified and authenticated. This is accomplished with a username password combination supplied in the request This can be supplied in a number of different ways.
https://foobar.zonarsystems.net/interface.php?username=user&password=mypasswordThere is no real difference between the different methods. Convenience and the particulars of the client application should dictate the exact method used.
If the authentication fails an HTTP 401 Unauthorized error response will be sent.
The server may also issue HTTP 403 Permission denied messages in the case of IP address restriction.
Authentication may also be handled through a session mechanism.
This removes the need to supply username and password information for each request.
To begin a session add a parameter gologin with any value to the request along with
the standard username and password.
The server will set two cookies, session_user_name and session_hash.
The session_user_name cookie contains the username established at the beginning
of the session. The session_hash contains the short term security token for the session.
Subsequent OMI requests now be authenticated by including these values in the request, username and password
are not required. These values may be supplied as either cookies or HTTP POST or GET variables.
The session_hash token will expire after a preset length of time, usually 2 hours, this may vary. Each request will update the value of the session_hash and it's expiration. To maintain the session the client needs to provide the updated session_hash. Sessions may be maintained indefinitely by making periodic requests and supplying the updated session_hash token.
If the format parameter has been specified as 'xml' then the returned content will be an XML OMI
error message with code 109.
Otherwise the content is HTML, similar to a typical HTTP server authentication required message.
Once connected to an account and authenticated the action to perform must be specified. This is done through the action
variable. Some actions may identify a family of related actions specified by the operation variable. An example would be the
showopen action which has the showinsp (retrieve detailed inspection information), showassets (retrieve asset listings)
and showoperators (retrieve operator listings) as some of it's individual operations.
Access to actions for any user is controlled in exactly the same way as for the normal web interface.
Some actions have names beginning with 'ext' such as extgetnewinsp or extgetasset. These actions are in the process of being removed
and should be avoided if another equivalent action exists. Read documentation carefully and heed any deprecation warnings.
Most action require additional information to identify a target object or optionally modify the behavior of the action. This will be spelled out in the documentation for the action.
In applications where security is a concern measures should be taken to safeguard the
authentication credentials.
The simplest and most basic measure is to use encrypted SSL connections
to prevent disclosure of authentication information to attackers who can observe the network traffic.
Failure to take this very simple precaution will largely invalidate any other attempts at maintaining security.
Note: Unlike zonarweb, the OMI does not force SSL connections. It is up to the implementor
to specify a secure connection.
Developers should take care that their client SSL implementation is robust, use the highest grade of
encryption practical and validate the HTTP server's certificate.
Proxies, web caching systems or 'web accelerators' between the client and OMI server may store information including authentication material. This may be more likely in situations where the authentication credentials are included in the request URL such as 1 and 2 above. This can be avoided by using a secure encrypted connection from the client all the way to the server.
The client application itself should be designed and implemented in a secure manner.
Any automated application will need to store it's authentication credentials securely.
If external software components are used in the implementation they need to have their security
examined. Care should be taken that HTTP engines do not cache or log requests.
Finally basic user security measures should be applied.
The user that the OMI client application uses should only have those permissions
it needs assigned to it.
Multiple applications or the same application used from multiple locations should have
different users if practical.
Chose passwords wisely and update them often. Update passwords immediately
if it is suspected that they may have been compromised.
If practical impose address restrictions on the OMI user(s). Logins may be restricted to
one or IP addresses or networks.
All OMI-connecting software must include the HTTP User-Agent header to identify itself in the requests that it sends. To be more specific, interface.php will block requests with blank User-Agent headers. When such a request is received, the client software will be sent error code 113.
The User-Agent header is an RFC2616 Section 14 standard for HTTP requests. Information on the User-Agent header is available in section 14.43 "User-Agent" at http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.
The HTTP User-Agent string included in each OMI request must contain, at a minimum, the vendor name/full
identifying name of the application/application version string. Additional information, such as
included libraries/library version is also helpful, and may be included. The format should resemble the
example below:
<VendorName (NOT initials)> <AppName> <AppVersion {x.x.x[.x]}>