[This local archive copy mirrored from the canonical site: http://www.esrin.esa.it/htdocs/edi/NCG.appendices.doc.html#REF37959; links may not have complete integrity, so use the canonical document at this URL if possible.]

Table of Contents Previous Chapter

Appendix A Agents and Clients

The agent is a composed of a library allowing a client to pack and unpack messages.

Appendix A.1 Structure of the client

Figure 1: Structure of the client.

Appendix A.2 Level-1: the C++ library API of the agent

The public part of the EDB_Agent C++ object includes 5 methods:

These C++ methods are also implemented in C functions, defined with the same names and parameters, in such a way that a pure C-based client application can use the same API.

For more information about the agent C++ library API, please refer to the Detailed Design Document of the agent. (cd. reference [5.])

Appendix A.3 C-shells for the packing and unpacking of messages

Two C-shells have been built on top of the executable and on top of PGP to provide a high-level easy-to-use interface for packing and unpacking messages. These shells are EDB_ClientPack and EDB_ClientUnpack.

These C-shells supposes that you have set the following environment variables:

Appendix A.3.1 EDB_ClientPack for the packing of user messages

   EDB_ClientPack [document] [<destinator>]+


This will create a raw message with the same name as your document plus the ".raw" extension.

Appendix A.3.2 EDB_ClientUnpack for the unpacking of user or system messages

   EDB_ClientUnPack [document] [message type]


This C-shell assumes that the file "document.raw" exists and contains your message.

Appendix A.4 Level-2: the EDB_Client executable

This executable called EDB_Client is built on top of the library described in the previous section. The use of this executable is explained below:

The executable uses the same environment variables that the C-shells. The executable supports five ways of working which are specified by the argument you passes

EDB_Client -pm <source_file> <destination_file> where
EDB_Client -um <source_file> <destination_file> where
EDB_Client -ppum <source_file> <destination_file> [<destinator>]+ where
EDB_Client -upum <source_file> <destination_file> where
EDB_Client -upsm <source_file> <destination_file> where

Appendix A.5 Agent - API of the library

The Agent consists in a library with C++ methods and C functions. The EDB_Agent C++ object class implements the methods for packing/unpacking Messages at different steps of the packing/unpacking, C functions with the same names and parameters as the C++ methods allow user not having a C++ compiler to link their C code to the library.

The detailed specification of the interface can be found in the Software User Manual.

Appendix A.6 DTDs of the Headers

SGML DTDs have been established to structure the headers of the messages exchanged by.

Two headers have been defined:

An additional DTD has been defined for the "Partner definition" configuration request, which is stored in the body of the message when relevant.

Appendix A.6.1 Security Header DTD

     DTD for the security header in order to detect the
     security scheme used at message level
     Copyright (c) Project, ESA/ESRIN-BIM, 1994.
     Authors: phv, epa
     The ESH is used in order to determine if the message is
     signed and/or enciphered. It had to be split from the
     main header because this last one is included in
     the possibly enciphered part of the message.
     This DTD should enable every SGML tool to decipher a ESH.
     Anyway, like for HTML, simple ESH readers are not full-featured
     SGML parsers and will not understand any complex SGML features
     (like entities, comments,...)
     ESH is for description of security scheme at message level.
     If security if achieved at the document level, the headers
     as well as the protocol are not concerned about it.
   !-- main element for the security header -->
   <!ELEMENT esh  O  O  (esh1?)>
   !-- version 1 of the security header -->
   <!ELEMENT  esh1 - -  (secpack!
        - selection security package in the #PCDATA 
      - attributes tell if the message is signed and/or enciphered
   <!ELEMENT  secpack  - -  (#PCDATA)>
   <!ATTLIST  secpack 
     mode  (clear|signed|secret|signsecr)  clear>


Appendix A.6.2 Header DTD

     DTD for the EDIDOC header used at EDIDOC plain message level
     Copyright (c) EDIDOC Project, ESA/ESRIN-BIM, 1994.
     Authors: phv, epa
     The security information is put in a separate
     EDIDOC Security Header (ESH).
     This DTD should enable every SGML tool to decipher a ESH.
     Anyway, SSLP (which is the Simple SGML-like parser user in
     EDIDOC) do not have the capability to handle all SGML features
     (ex. tag omission, entities,...)
   <!-- main element for the EDIDOC header -->
   <!ELEMENT eh    - -     (eh1)>
   <!-- EDIDOC header version 1, either issued from a user or from EDIDOC -->
   <!ELEMENT eh1    - -     (user|edidoc)>
   <!-- messages issued by EDIDOC partners -->
   <!ELEMENT user    - -     (sndreq|gpwreq|cfgreq)>
   <!ATTLIST user -- following comments tell the default behaviour --
     -- sending of a message is usually processed: --
     level   (probe,process)  process
     -- sending of a system notification (just for errors) --
     notif    (error,always)  error
     -- can not forward clear message except if original was clear --
     clearmsg  (safemsg,clrmsg)  safemsg
     -- can not send clear notification for encrypted message --
     clearnot  (safenot,clrnot)  safenot
     -- warning when forwarding of a message failed --
     nondeliv  (negack,none)  negack
     -- packing for every destinator is required --
     destin    (most,every)  most
   <!-- entities for all types of messages generated by users -->

   <!ENTITY % usrgen "from,ref,subject?">
   <!ELEMENT sndreq  - -     (%usrgen;,docinfo,to+)  -- send requests -->
   <!ELEMENT gpwreq  - -     (%usrgen;,app,event)  -- groupware requests -->
   <!ELEMENT cfgreq  - -     (%usrgen;)  -- configuration request (in message body) 
   <!-- elements used in most types of messages -->
   <!ELEMENT from    - -     (#PCDATA)  -- nickname of the message originator 
   <!ELEMENT ref    - -     (#PCDATA)  -- a reference used by the message in
itiator -->
   <!ELEMENT subject  - -     (#PCDATA)  -- a short description of the subject -->
   <!ELEMENT to    - -     (#PCDATA)  -- destinator nickname -->
   <!-- elements defined in provision of groupware requests support -->
   <!ELEMENT app    - -     (class,instance)>
   <!ELEMENT class  - -     (#PCDATA)>
   <!ELEMENT instance  - -     (#PCDATA)>
   <!ELEMENT event    - -     (docinfo,param)>
   <!ATTLIST event    name   NMTOKEN      #REQUIRED>
   <!ELEMENT param    - -     (#PCDATA)>
   <!-- definition of a document types and formats -->
   <!ELEMENT docinfo  - -     (type,format)>
   <!ELEMENT type  - -     (#PCDATA)>
   <!ELEMENT format - -     (#PCDATA)>
   <!-- messages sent by the EDIDOC server -->
   <!ELEMENT edidoc  - -     (sndrep|gpwrep|cfgrep|sysnotif)>
   <!ELEMENT sndrep  - -     (sndreq,check,docinfo)  -- a send reply -->
   <!ELEMENT gpwrep  - -     ((gpwreq|(app,event)),gpwstate,docinfo) --  a group
ware reply -->
   <!ELEMENT cfgrep  - -     (cfgreq)  -- configuration reply -->
   <!ELEMENT sysnotif  - -     (user,check)  -- system notification -->
   <!ELEMENT gpwstate  - -     (#PCDATA)  -- groupware status -->
   <!-- elements for storing the results of checkings -->
   <!ELEMENT check    - -  (chkcom,chksec,chkfmt)>
   <!ENTITY % chks "(chkcom|chksec|chkfmt)">
   <!ELEMENT %chks;  - -  (#PCDATA)>
   <!ATTLIST %chks;
     result  (valid|invalid|na)  na>

Appendix A.6.3 Configuration Request for New Partner Definition: DTD

The following DTD has been updated to include next service request development but currently only the "np" (new partner creation) service request is implemented at the server level.

     DTD for the EDIDOC system requests
     Copyright (c) EDIDOC Project, ESA/ESRIN-BIM, 1994.
     Authors: cl, phv
   <!ELEMENT sr    - -     (np|qp|qm|qs|qsh|qds)>
   <!-- np (New Partner) - Registering a new partner - either issued from a 
user or from EDIDOC -->
   <!ELEMENT np    - -     (partner, supfmt*, inroute*, dstroute*)>
   <!ELEMENT partner  - -     (nickname, name, address, phone?, fax?, secpck)>
   <!ELEMENT inroute  - -     (commean, addrtmpl)>
   <!ELEMENT dstroute  - -     (commean, addrtmpl, retries, timeout, delack)>
   <!ELEMENT nickname  - -     (#PCDATA)>  <!-- Nickname of the registered partner -
   <!ELEMENT name    - -     (#PCDATA)>  <!-- Last and First Name of the reg
istered partner -->
   <!ELEMENT address  - -     (#PCDATA)>  <!-- Address of the registered partner -->
   <!ELEMENT phone    - -     (#PCDATA)>  <!-- Telephone of the registered 
partner -->
   <!ELEMENT fax    - -     (#PCDATA)>  <!-- Fax of the registered partner -
   <!ELEMENT secpck  - -     (#PCDATA)>  <!-- Security package used by the regis
tered partner -->
   <!ELEMENT supfmt  - -     (#PCDATA)>  <!-- Format supported by the registered 
partner -->
   <!ELEMENT commean  - -     (#PCDATA)>  <!-- Name of in/dest-communication mean -->
   <!ELEMENT addrtmpl  - -     (#PCDATA)>  <!-- Address template on the in/dest-com
munication mean -->
   <!ELEMENT retries  - -     (#PCDATA)>  <!-- Maximum number of retries on the dest-
communication mean -->
   <!ELEMENT timeout  - -     (#PCDATA)>  <!-- Timeout on the dest-communication mean 
   <!ELEMENT delack  - -     (#PCDATA)>  <!-- Indicates if an ACK is expected when a 
message is sent using the route -->
   <!-- qp (Query for Partner information)  -  Getting the configuration informa
tion about a partner -->
   <!ELEMENT qp  - -    (nickname)>
   <!-- qm (Query for Message information)  -  Getting the history of a message 
(processing, communications,...) -->
   <!ELEMENT qm  - -    (ref)>
   <!ELEMENT ref  - -    (#PCDATA)>

   <!-- qs (Query for Security public information)  -  Getting a list of security 
packages, key rings,... -->
   <!ELEMENT qs  - -    (#PCDATA)> <!-- information typed in #PCDATA is not 
used -->
   <!-- qds (Query for Document Standards configuration)  -  Getting the list of 
document types and formats -->
   <!ELEMENT qds  - -    (#PCDATA)> <!-- information typed in #PCDATA is not 
used -->