**********************************************************************
FTSC                             FIDONET TECHNICAL STANDARDS COMMITTEE
**********************************************************************

Publication:    FTS-1027
Revision:       1
Title:          Binkp/1.0 optional protocol extension CRAM
Authors:        Michiel Broek
                Dima Maloff
                Stas Degteff
                Pavel Goulchuck
Issue Date:     1 December 2005
Review Date:    1 December 2007
----------------------------------------------------------------------
Contents:
         1. Keyed Hashing Challenge-Response Authentication Mechanism
              1. Overview
              2. Sequence of Steps
              3. Generating and Transmitting Challenge Data
              4. Producing and Transmitting a Digest
              5. Indicating CRAM Capabilities
              6. Example of Frame Exchange During CRAM Authentication
              7. Notes on Hash Function Algorithms
         A. References
         B. History
----------------------------------------------------------------------

Status of this document
-----------------------

   This document is a Fidonet Technical Standard (FTS).

   This document specifies an optional Fidonet standard protocol for
   the Fidonet community.

   This document is released to the public domain, and may be used,
   copied or modified for any purpose whatever.


1. Keyed Hashing Challenge-Response Authentication Mechanism
------------------------------------------------------------

   1.1 Overview
   ------------

   This is the optional binkp protocol extension Challenge-Response
   Authentication Mechanism. This protocol extension is recommended
   for all binkp protocol versions.

   Challenge-Response Authentication Mechanism (CRAM) allows to avoid
   passing cleartext, reusable passwords across the network. Since it
   utilizes Keyed-Hashing digests [Keyed], it does not require
   password to be stored in the clear on the Mailer's media, allowing
   storage of the intermediate results which are known as "contexts".

   Providing binkp-mailer is capable of [Keyed] digest calculation and
   conversion of a byte array to a hexadecimal string and back,
   implementation of CRAM is easily achieved by slightly modifying the
   state machine.

   CRAM-MD5 is a recommended minimal implementation (for compatibility
   purposes).


   1.2 Sequence of Steps
   ---------------------

   CRAM adds an additional synchronization step to binkp protocol. The
   description of this step follows:

    1. Answering side sends a unique set of data (challenge data) to
       the Originating side, encoded to a hexadecimal string.
    2. Originating side uses challenge data, decoded from received
       hexadecimal string, and a password to produce a digest by
       applying the keyed Hashing algorithm from [Keyed] where the key
       is the password and the digested text is the challenge data.
    3. When the answering side receives this response, it verifies the
       digest provided. If the digest is correct, the answering side
       should consider the Originating side authenticated and responds
       appropriately.

   Similar technique is used in [IMAP-AUTH].

   1.3 Generating and Transmitting Challenge Data
   ----------------------------------------------

   Size and contents of challenge data are implementation-dependent,
   but it SHOULD be no smaller than 8 bytes and no bigger than 64
   bytes. Answering side SHOULD never generate the same challenge
   data.

   Instead of generating a long challenge data, answering side MAY use
   a hash function to shorten it. In calculation of a challenge data
   answering side MAY also use connection/line number, caller's IP
   address, current time, etc.

   Answering side transmits challenge data in the very first M_NUL
   message, in the following way:

   M_NUL "OPT [othropt] CRAM-lsthf-cde [othropt]"

   lsthf is a list of aliases of supported hash functions, delimited
   by slash characters. The list begins with alias of the most
   preferred and ends with alias of the least preferred hash function.

   Currently defined aliases are: MD5 for [MD5] and SHA1 for [SHA-1].

   cde is the challenge data encoded to hexadecimal string, Lower-case
   ASCII characters MUST be used for encoding, but Mailer SHOULD also
   accept upper-case characters. The length of the string MUST be
   even, and the leading zeros MUST NOT be trimmed.

   1.4 Producing and Transmitting a Digest
   ---------------------------------------

   Originating side responds with:

   M_PWD "CRAM-chosenhf-khde [othropt]"

   where chosenhf is the alias of the chosen hash function and khde is
   the keyed hashed digest, encoded to a hexadecimal string.

   According to [IMAP-AUTH], keyed hashed digest is produced by
   calculating

   HASH((secret XOR opad), HASH((secret XOR ipad), challengedata))

   where HASH is chosen hash function, ipad and opad are 36 hex and 5C
   hex (as defined in [Keyed]) and secret is a password null-padded to
   a length of 64 bytes. If the password is longer than 64 bytes, the
   hash-function digest of the password is used as an input (16-byte
   for [MD5] and 20-byte for [SHA-1]) to the keyed hashed calculation.

   If originating side doesn't supports requested CRAM digest method
   it MAY use plain text password for backward compatibility:

   M_PWD "plain_text_password"

   Answering side SHOULD accept this method.

   Note: possible uncertainty if password begins from string "CRAM-";
   a workaround does not exist for this, please don't use passwords
   that begin with "CRAM-".


   1.6 Indicating CRAM Capabilities
   --------------------------------

   Answering side MUST send

   M_NUL "OPT [othropt] CRAM-lsthf-cde [othropt]"

   before M_ADR if it supports CRAM. Usually this command is send as
   the first command.

   Originating side MUST be ready to receive any binkp message before
   M_NUL in a CRAM session. Binkp state machine MUST ignore any
   received message of unknown type in order to be compatible with
   future extensions.

   If an originating side receives a first message that is a M_ADR or
   a M_NUL message that is not

   M_NUL "OPT [othropt] CRAM-lsthf-cde [othropt]"

   it MUST decide that the answering side doesn't support CRAM and MAY
   either disconnect or use old password exchange. If the sides do not
   have any compatible hash function, the originating may also either
   disconnect or use the old password exchange. If an originating side
   decides to disconnect, it MUST send M_ERR frame with a proper
   explanation before disconnecting, recommended messages are:
    M_ERR "You must support CRAM authentication"
    M_ERR "CRAM authentication required, no common hash function"

   When parsing M_NUL "OPT ..." string (coming from the answering
   side), originating side first splits it by using space delimiter to
   get a list of options, and then if an option begins with
   "CRAM-lsthf-", takes the remaining substring as a
   hexadecimal-encoded challenge data.

   1.7 Example of Frame Exchange During CRAM Authentication
   --------------------------------------------------------

   (Password here is tanstaaftanstaaf)

   Originating :
     send M_NUL and M_ADR messages
     wait for first M_NUL and/or M_ADR message

   Answering   :
     send M_NUL "OPT xx xx CRAM-MD5-f0315b074d728d483d6887d0182fc328"
     send M_ADR message
     and other messages
     wait for M_PWD
   Note: xx means other optional extensions thay are supported.

   Originating :
     M_PWD "CRAM-MD5-56be002162a4a15ba7a9064f0c93fd00"

   Answering   :
     M_OK "secure"
     continue session

   1.8 Notes on Hash Function Algorithms
   -------------------------------------

   [MD5] and [SHA-1] are the most widely used cryptographic hash
   functions. [MD5] has been shown to be vulnerable to collision
   search attacks [Dobb]. This attack and other currently known
   weaknesses of [MD5] do not compromise the use of [MD5] within CRAM
   as specified in this document (see [Dobb]); however, [SHA-1]
   appears to be a cryptographically stronger function. To this date,
   [MD5] can be considered for use in CRAM for applications where the
   superior performance of [MD5] is critical. In any case,
   implementors and users need to be aware of possible cryptanalytic
   developments regarding any of these cryptographic hash functions,
   and the eventual need to replace the underlying hash function.


A. References
-------------

   [Dobb]
           H. Dobbertin, "The Status of MD5 After a Recent Attack",
           RSA Labs' CryptoBytes, Vol. 2 No. 2, Summer 1996.

   [MD5]
           Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
           April 1992.

   [SHA-1]
           NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995.

   [Keyed]
           Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for
           Message Authentication", RFC 2104, February 1997.

   [IMAP-AUTH]
           Klensin, "IMAP/POP AUTHorize Extension for Simple
           Challenge/Response", RFC 2195, September, 1997

   [FTA-1006]
           Key words to indicate requirement levels, Fidonet Technical
           Standards Committee administrative. FTA-1006.

   [FSP-1018]
           Binkp 1.0 Protocol specification.


B. History
----------

   Rev.1, 20051201: Initial Release.
