

This DEVELOPER document describes the interfaces for the scatterchat module.


The scatterchat module only supports an stdin/stdout interface in this release
(a shared object interface will be released in the future).  Below is a
list of all the commands the scatterchat module understands, along with its
effects.  You may enter these commands at the command line after running
the scatterchat module's executable file (by default it is named
'scatterchatmod' or 'scatterchatmod.exe').

A simple working example on how to use this interface can be found in the
tests/ directory.


        -= SCATTERCHAT MODULE APPLICATION PROGRAMMING INTERFACE V0.0 =-


On Startup:

In:      <Nothing>
Out:     <SC VERSION><CRLF><API VERSION><CRLF>

Description:  On startup, the module will automatically output the version
              of the module itself, followed by a carriage-return and
              line-feed (CRLF), then the API version it understands with
	      another CRLF at the end.



Initialization of load/save directory:

In:      INIT <LOAD/SAVE DIR><CRLF>
Success: OK<CRLF>
	 N<CRLF><ID 1>|<FP 1><CRLF><ID 2>|<FP 2><CRLF>...<ID N>|<FP N><CRLF>
         N<CRLF><ID 1>|<FP 1><CRLF><ID 2>|<FP 2><CRLF>...<ID N>|<FP N><CRLF>
Error:   ERROR [MUST SPECIFY LOAD/SAVE DIR | DIRECTORY NOT FOUND]<CRLF>

Description:  This will initialize the load/save directory.  This directory
	      is what is used to hold the key database along with the
	      encryption keyrings.  The module will respond with a list of
	      encryption IDs followed by a list of key fingerprints that were
	      loaded from the directory (if there were any--a first-time user
	      won't have any of this, so nothing will be loaded).  This
	      information should be displayed to the user to select the
	      ID to connect with and/or edit the key database.

When to use:  As soon as possible.  The module is not initialized until this
              function is called.



Load Keys For A Local User:

In:  SELECT_USER <ID>|<PW><CRLF>
Success:  OK<CRLF>
Error:    ERROR [ID IS UNKNOWN | ARGUMENTS MISSING | MUST SET LOAD/SAVE DIRECTORY FIRST | PASSWORD IS BAD]<CRLF>

Description:  This will load an ID from the list output by the module when
              the load/save directory was initialized.  The password to unlock
              the ID is also needed (the same password that was used to
              generate the key).

When to use:  Before any communication is to occur, an ID must be loaded.




To Send A Message:

In:       SEND <PROTOCOL-NAME>|<SIZE OF DATA><CRLF>
          <DATA><CRLF>
Success:  OK 3 <Number of Results><CRLF>
          <Size of Result1> <Size of Result2> ... <Size of ResultN><CRLF>
	  <Result1><Result2>...<ResultN><CRLF>
Error:    ERROR [ERROR ARGUMENTS MISSING | <ERROR MSG>]<CRLF>

Description:  Sends a message to a specific user.  Although only one message
              is sent per call, this function may return multiple messages.
              All of these messages must be transmitted to the peer in order.
	      PROTOCOL-NAME can be any arbitrary string and is used to
	      distinguish connections internally (the module can handle
	      multiple peers simultaneously).  Once a connection is given
	      a PROTOCOL-NAME, it cannot be changed for the duration of the
	      connection.

When to use:  Use when there exists any message to send to the peer.




To Get A Message:

In:       PROCESS <PROTOCOL-NAME>|<SIZE OF DATA><CRLF>
          <DATA><CRLF>
Success:  OK X Y<Type: 0 = unused | 1 = crypted message | 2 = cleartext message | 3 = actionable handshake messages | 4 = non-actionable handshake messages | 5 = public key for verification> <Number of Results><CRLF>
          <Size of Result1> <Size of Result2> ... <Size of ResultN><CRLF>
	  <Result1><Result2>...<ResultN><CRLF>
Error:    ERROR <ERROR MSG><CRLF>

Description:  Processes a message received from the peer.  The result(s) of
	      this operation all have the same type, designated by the integer
	      X (described below).  The number of results is designated by the
	      integer Y.  The type tells the caller what kind of message has
	      just been processed, and what to do with it.

	      A type of 0 is not used.

	      A type of 1 means that the result is a decrypted message that
	      comes from an encrypted message the peer sent.  In this case,
	      there will always be one result, namely, the plaintext message
	      itself.

	      A type of 2 means that the result is a plaintext message
	      *and that the peer transmitted it in the clear*.  In this case,
	      there will always be one result.  Be careful how you handle
	      type 2 messages, as any unauthenticated peer can cause them!

	      A type 3 signifies that there is a message(s) that must now be
	      transmitted to the peer which is/are a part of the connection
	      handshake (this is an actionable handshake message).

	      A type 4 signifies that the message received is part of the
	      handshake and that no futher action is necessary.  The number
	      of results will be 0 (this is a non-actionable handshake
	      message).

	      A type 5 signifies the result is the public key fingerprint of
	      the peer.  This fingerprint is NOT in the key database, and so
	      the user must be shown this fingerprint for manual verification.
	      The number of results will be 1.

	      PROTOCOL-NAME can be any arbitrary string and is used to
	      distinguish connections internally (the module can handle
	      multiple peers simultaneously).  Once a connection is given
	      a PROTOCOL-NAME, it cannot be changed for the duration of the
	      connection.

When to use:  As soon as a message is received from the peer.  




To Accept A Connection Temporarily:

In:       KEY_ACCEPT_TEMPORARY <PROTOCOL-NAME>|<UMID><CRLF>
Success:  OK 3 <Number of Results><CRLF>
          <Size of Result1> <Size of Result2> ... <Size of ResultN><CRLF>
	  <Result1><Result2>...<ResultN><CRLF>
Error:    ERROR <ERROR MSG><CRLF>

Description:  This notifies the module that the key should be accepted for this
	      session only.  On success, the module will return the necessary
	      messages needed to complete the handshake.  UMID is an arbitrary
	      string created by the caller to be used as an alternative name
	      to PROTOCOL-NAME.  In some circumstances, such as in instant
	      messaging applications that can maintain multiple IM protocols
	      concurrently, the UMID can be used to abstract users across
	      protocols.  If this feature is not needed, the PROTOCOL-NAME
	      should be used in its place.

When to use:  After a PROCESS input returns a type 5 and the user wishes to
	      accept the connection for this session only without adding
	      the key fingerprint to the database.




To Accept A Connection Permanently:

In:       KEY_ACCEPT_PERMANENTLY <PROTOCOL-NAME>|<UMID><CRLF>
Success:  OK 3 <Number of Results><CRLF>
Error:    ERROR <ERROR MSG><CRLF>

Description:  This notifies the module that the key should be added to the
	      database and the session be allowed.  When the key is encountered
	      in the future, the session will automatically be accepted.
	      UMID is an arbitrary string created by the caller to be used as
	      an alternative name to PROTOCOL-NAME.  In some circumstances,
	      such as in instant messaging applications that can maintain
	      multiple IM protocols concurrently, the UMID can be used to
	      abstract users across protocols.  If this feature is not needed,
	      the PROTOCOL-NAME should be used in its place.

When to use:  After a PROCESS input returns a type 5 and the user wishes to
	      accept the current connection and any future connections based on
	      the key fingerprint.




To Reject A Key:

In:	  KEY_REJECT <PROTOCOL-NAME><CRLF>
Success:  OK<CRLF>
Error:	  ERROR <ERROR MSG><CRLF>

Description:  Rejects a key.

When to use:  After a PROCESS input returns a type 5 and the user determined
	      that the key is not good and the connection should not be
	      accepted.




To Lookup A Name:

In:       LOOKUP_NAME <NAME><CRLF>
Success:  <NAME><CRLF>
Error:    ERROR NAME IS UNKNOWN<CRLF>

Description:  Resolves a PROTOCOL-NAME to a UMID, or vice-versa (where
	      PROTOCOL-NAME and UMID are those provided to SEND and PROCESS
	      functions previously).

When to use:  When the caller has one and needs the other.




To Wipe A Buddy:

In:       WIPE <PROTOCOL-NAME><CRLF>
Success:  OK 0 0
ERROR:    ERROR NAME IS UNKNOWN<CRLF>

Description:  Kills the connection associated with PROTOCOL-NAME and frees
	      all resources it was using.

When to use:  When the connection to the peer identified by PROTOCOL-NAME has
	      terminated or should be terminated.




To Get The Buddy Status:

In:       STATUS <PROTOCOL-NAME><CRLF>
Success:  <Status><CRLF>
Error:    ERROR NAME IS UNKNOWN<CRLF>

Description:  Gives a human-readable status of a peer identified by
	      PROTOCOL-NAME.

When to use:  While debugging.




Reset Entire Module:

In:  RESET<CRLF>
Out: OK<CRLF>

Description:  Resets all connections.  Module remains initialized with
	      previously set load/save directory and loaded ID.

When to use:  When necessary.  =]




Shutdown/Quit/Exit:

In:  [ SHUTDOWN | QUIT | EXIT ]<CRLF>
Out: OK<CRLF>

Description:  Causes the module to exit gracefully.




Add a key fingerprint:

In:       ADD_KEY <UMID>|<FINGERPRINT><CRLF>
Success:  OK<CRLF>
Error:    ERROR [ARGUMENTS MISSING | MUST SET LOAD/SAVE DIRECTORY FIRST]<CRLF>

Description:  Adds a key fingerprint and its associated UMID to the database.

When to use:  Anytime after the load/save directory was set and the user
	      desires to manually add a key fingerprint to the database.




Delete a key fingerprint:

In:       DEL_KEY <NAME>|<FINGERPRINT><CRLF>
Success:  OK<CRLF>
Error:    ERROR [ARGUMENTS MISSING | MUST SET LOAD/SAVE DIRECTORY FIRST | FINGERPRINT NOT FOUND]<CRLF>

Description:  Deletes a key fingerprint from the database.

When to use:  Anytime after the load/save directory was set and the user
	      desires to manually delete a key fingerprint from the database.




Generate a key:

In:       GENERATE_KEY <ID>|<PASSWORD><CRLF>
Success:  OK<CRLF>
	  <FINGERPRINT><CRLF>
Error:    ERROR [ARGUMENT MISSING | ARGUMENT CONTAINS ILLEGAL CHARACTERS | <ERROR MSG>]<CRLF>

Description:  Generates an encryption key and signing key identified by <ID>.
	      The resulting file is written in the load/save directory and is
	      given the filename "<ID>.bc".  The password is used to encrypt
	      the key-file and must be presented later when decrypting (during
	      a SELECT_USER operation).

When to use:  After the load/save directory is set and the user wishes to
	      generate a new encryption & signing keypair.




Check if load/save directory was initialized:

In:  IS_LOADSAVE_INITIALIZED<CRLF>
Out: [ YES | NO ]<CRLF>

Description:  Determines whether or not the load/save directory has been
	      initialized yet.




Check if a user was selected:

In:  IS_USER_SELECTED<CRLF>
Out: [ YES | NO ]<CRLF>

Description:  Determines if an ID has been selected yet (via a SELECT_USER
	      operation).




NO-OP

In:  NOOP<CRLF>
Out: OK<CRLF>

Description:  Does nothing.

When to use:  During debugging, to ensure that the calling application is
	      synchronized with the module.




Encrypt a file:

In:      ENCRYPT_FILE <PROTOCOL-NAME>|<IN FILE>|<OUT FILE><CRLF>
Success: OK<CRLF>
Error:   ERROR <Error message><CRLF>

Description:  Encrypts a file using the session key and writes the output
              to a specified file.  The file's HMAC is also created for
              integrity checking purposes.

When to use:  After a session is set up with a peer, and when a file must be
              encrypted.




Decrypt a file:

In:      DECRYPT_FILE <PROTOCOL-NAME>|<IN FILE>|<OUT FILE><CRLF>
Success: OK<CRLF>
Error:   ERROR <Error message><CRLF>

Description:  Decrypts a file using the session key, and writes the output
              to a specified file if the HMAC check succeeds.

When to use:  After a session is set up with a peer, when a file must be
              decrypted.




Query Autoencrypt:

In:      AUTO_QUERY <NAME><CRLF>
Success: [ YES | NO ]<CRLF>
Error:   ERROR<CRLF>

Description:  Queries whether or not a new session with NAME should be
              automatically encrypted.  Does not modify any internal state
              whatsoever.

When to use:  When a new "conversation" or "session" is started in the calling
              program, this function is used so that proper suggestion is
              passed on to the user.





Autoencrypt feedback:

In:      AUTO_FEEDBACK <NAME>|[C | P]<CRLF>
Success: OK<CRLF>
Error:   ERROR<CRLF>

Description:  Notifies the module that an encrypted ("C") session/conversation
              was started with NAME, or a plaintext ("P") one was.  This
              provides feedback to determine if future sessions should
              automatically default to encrypt.

When to use:  Use anytime a conversation's state has begun in the encrypted or
              plaintext states.
