Medical Objects Server Interface Specification 1.0
==================================================

Copyright 1998-2005 Medical Objects Pty Ltd. All rights reserved.

Revision Information
--------------------

  $Id: MO-Connect.txt,v 1.5 2005/06/03 07:17:58 jared Exp $

  $Log: MO-Connect.txt,v $
  Revision 1.5  2005/06/03 07:17:58  jared
  prepare for public release



==================================================

To Connect to a Medical-Object HTTP server:

Supports HTTP 1.1
Uses POST Messages.

The Server accepts encrypted and non-encryted messages but all external access
will be PGP/PKI/GNUPG encrypted and signed. The signing key must be enabled on the Server
or post will Fail. The server Public key can be obtained directly from the Server. PKI
keys are available on LDAP.

The HL7 Messages can be "Classic" HL7 Encoded or XML Encoded (V2.3.1 up). XML in means XML out.

HTTP Request, Method POST

        1. Encrypted Message Headers

        Connection:     keep-alive (this may not be respected :-))
        Accept:         "application/pgp-encrypted" or "application/pki-encrypted or "application/gnupg-encrypted"
        Username:       The full PGP/GNUPG/PKI Keyname of the signing Key. No Password.


        2. Plain Text Headers (Local LAN connections only)

        Connection:     keep-alive
        Accept:         application/hl7
        Set username and password as per basic Authentification

        PKI/PGP Notes:

        The post data is the PGP/PKI/GNUPG encrypted message or plain text message as appropriate
        Will accept Single message or a batch with FHS/BHS/BTS/FTS, no extra characters
        before or after the message allowed. 

        PKI Encrypted messages are to be base64 encoded. Will be base 64 encoded on the way out.
	As PKI API does not support signed/encryted messages in one ASN.1 wrapper the message is 
        first encypted ('Encoding:Enveloped') and then signed ('Encoding:Signed'). The signer must 
        have a valid PKI Certificate and the message should be encrypted with the target servers 
        encryption site certificate.

        For new PKI users the encrytion certificate must be available on HIC LDAP server. Rights are
        granted on the basis of the signer.

        PGP messages to be radix encoded rather than binary. 
        GNUPG messages should be radix encoded (ie --armor).

The Server response.

        Will be PGP/PKI encrypted or plain text depending on the zone. PGP in means PGP out.
        The message will be encrypted with the requesting public key and signed by the server key.

        For Encrypted messages

        ContentEncoding:        "pgp-encrypted" or "base64-pki-encrypted" or "gnupg-encrypted"

        If the message is not parsable then

        ContentEncoding:        application/error

        In case of an error then the response will be a plain text error message.
        This will occur if the message fails parsing or the public key of the signer is not
        registered. If the message is OK but what is requested is not then standard HL7
        error handling (Mainly ERR segments) will be used. ie 'application/error' means
        a connection error. It can be displayed to the user via eg an exception handler
        and has a multiline nature which Name=Value pairs to give more info, assuming that
        its not an unauthorised PGP/GNUPG/PKI Key.

The Server URL.

        Takes the form of

        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/'

        eg http://203.42.156.38:2000/hl7/

        If the message is in PIT format (not desirable) then

        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/pit/'

        eg http://203.42.156.38:2000/hl7/pit/

        In the case of a PIT message a HL7 ACK will be returned.

Utility Methods.

        1. The PGP/GNUPG Key Name for the Server.

        HTTP GET with

        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_KEY_NAME'
        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_GNUPG_KEY_NAME'
        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_PKI_KEY_NAME'


        2. The PGP/GNUPG Public Key of the Server.

        HTTP GET with

        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_PGP_KEY'
        'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_GNUPG_KEY'


        3. To upload a PGP/GNUPG Public Key for a potential user

        HTTP POST with

         'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?' +

                     'METHOD=CLIENT_KEY_UPLOAD' +  ( or 'GNUPG_KEY_UPLOAD')
                     '&KEYNAME=<PGP Key Name>' +
                     '&CLIENTNAME=<Text Name of Potential User>' +
                     '&PHONENUMBER=<Contact Number of Potential User>'
          nb: Don't include <>

          The Client Public Key is Uploaded as the POST Data.
          The key has to be manually validated and a user account created.
          The user must know the Key FingerPrint of the Key they are planning to use.


          The server will return, a error response if not permitted or some
          help text if the key has been accepted. The ability to accept keys in this
          way is an option which can be turned off.


          This text gives helpful info which can be displayed to the user.

Server rights:

        All users will have a userlevel. The most basic one just allows uploading
        HL7 ORU Messages (ORU^R01). This is the base right that a valid PKI key permits. In the STF server
        a valid PKI key permits provider lookup (MFQ^M02). A user can edit their own STF records
        using MFN^M02 messages. 

Correct as of:  20th May 2005