From: http://www.ietf.org/rfc/rfc2831.txt
2 Authentication
The following sections describe how to use Digest as a SASL
authentication mechanism.
2.1 Initial Authentication
If the client has not recently authenticated to the server, then it
must perform "initial authentication", as defined in this section. If
it has recently authenticated, then a more efficient form is
available, defined in the next section.
2.1.1 Step One
The server starts by sending a challenge. The data encoded in the
challenge contains a string formatted according to the rules for a
"digest-challenge" defined as follows:
Leach & Newman Standards Track [Page 3]
RFC 2831 Digest SASL Mechanism May 2000
digest-challenge =
1#( realm | nonce | qop-options | stale | maxbuf | charset
algorithm | cipher-opts | auth-param )
realm = "realm" "=" <"> realm-value <">
realm-value = qdstr-val
nonce = "nonce" "=" <"> nonce-value <">
nonce-value = qdstr-val
qop-options = "qop" "=" <"> qop-list <">
qop-list = 1#qop-value
qop-value = "auth" | "auth-int" | "auth-conf" |
token
stale = "stale" "=" "true"
maxbuf = "maxbuf" "=" maxbuf-value
maxbuf-value = 1*DIGIT
charset = "charset" "=" "utf-8"
algorithm = "algorithm" "=" "md5-sess"
cipher-opts = "cipher" "=" <"> 1#cipher-value <">
cipher-value = "3des" | "des" | "rc4-40" | "rc4" |
"rc4-56" | token
auth-param = token "=" ( token | quoted-string )
The meanings of the values of the directives used above are as
follows:
realm
Mechanistically, a string which can enable users to know which
username and password to use, in case they might have different
ones for different servers. Conceptually, it is the name of a
collection of accounts that might include the user's account. This
string should contain at least the name of the host performing the
authentication and might additionally indicate the collection of
users who might have access. An example might be
"[email protected]". This directive is
optional; if not present, the client SHOULD solicit it from the
user or be able to compute a default; a plausible default might be
the realm supplied by the user when they logged in to the client
system. Multiple realm directives are allowed, in which case the
user or client must choose one as the realm for which to supply to
username and password.
nonce
A server-specified data string which MUST be different each time a
digest-challenge is sent as part of initial authentication. It is
recommended that this string be base64 or hexadecimal data. Note
that since the string is passed as a quoted string, the
double-quote character is not allowed unless escaped (see section
7.2). The contents of the nonce are implementation dependent. The
Leach & Newman Standards Track [Page 4]
RFC 2831 Digest SASL Mechanism May 2000
security of the implementation depends on a good choice. It is
RECOMMENDED that it contain at least 64 bits of entropy. The nonce
is opaque to the client. This directive is required and MUST
appear exactly once; if not present, or if multiple instances are
present, the client should abort the authentication exchange.
qop-options
A quoted string of one or more tokens indicating the "quality of
protection" values supported by the server. The value "auth"
indicates authentication; the value "auth-int" indicates
authentication with integrity protection; the value "auth-conf"
indicates authentication with integrity protection and encryption.
This directive is optional; if not present it defaults to "auth".
The client MUST ignore unrecognized options; if the client
recognizes no option, it should abort the authentication exchange.
stale
The "stale" directive is not used in initial authentication. See
the next section for its use in subsequent authentications. This
directive may appear at most once; if multiple instances are
present, the client should abort the authentication exchange.
maxbuf
A number indicating the size of the largest buffer the server is
able to receive when using "auth-int" or "auth-conf". If this
directive is missing, the default value is 65536. This directive
may appear at most once; if multiple instances are present, the
client should abort the authentication exchange.
charset
This directive, if present, specifies that the server supports
UTF-8 encoding for the username and password. If not present, the
username and password must be encoded in ISO 8859-1 (of which
US-ASCII is a subset). The directive is needed for backwards
compatibility with HTTP Digest, which only supports ISO 8859-1.
This directive may appear at most once; if multiple instances are
present, the client should abort the authentication exchange.
algorithm
This directive is required for backwards compatibility with HTTP
Digest., which supports other algorithms. . This directive is
required and MUST appear exactly once; if not present, or if
multiple instances are present, the client should abort the
authentication exchange.
Leach & Newman Standards Track [Page 5]
RFC 2831 Digest SASL Mechanism May 2000
cipher-opts
A list of ciphers that the server supports. This directive must be
present exactly once if "auth-conf" is offered in the
"qop-options" directive, in which case the "3des" and "des" modes
are mandatory-to-implement. The client MUST ignore unrecognized
options; if the client recognizes no option, it should abort the
authentication exchange.
des
the Data Encryption Standard (DES) cipher [FIPS] in cipher
block chaining (CBC) mode with a 56 bit key.
3des
the "triple DES" cipher in CBC mode with EDE with the same key
for each E stage (aka "two keys mode") for a total key length
of 112 bits.
rc4, rc4-40, rc4-56
the RC4 cipher with a 128 bit, 40 bit, and 56 bit key,
respectively.
auth-param This construct allows for future extensions; it may appear
more than once. The client MUST ignore any unrecognized
directives.
For use as a SASL mechanism, note that the following changes are made
to "digest-challenge" from HTTP: the following Digest options (called
"directives" in HTTP terminology) are unused (i.e., MUST NOT be sent,
and MUST be ignored if received):
opaque
domain
The size of a digest-challenge MUST be less than 2048 bytes.
2.1.2 Step Two
The client makes note of the "digest-challenge" and then responds
with a string formatted and computed according to the rules for a
"digest-response" defined as follows:
Leach & Newman Standards Track [Page 6]
RFC 2831 Digest SASL Mechanism May 2000
digest-response = 1#( username | realm | nonce | cnonce |
nonce-count | qop | digest-uri | response |
maxbuf | charset | cipher | authzid |
auth-param )
username = "username" "=" <"> username-value <">
username-value = qdstr-val
cnonce = "cnonce" "=" <"> cnonce-value <">
cnonce-value = qdstr-val
nonce-count = "nc" "=" nc-value
nc-value = 8LHEX
qop = "qop" "=" qop-value
digest-uri = "digest-uri" "=" <"> digest-uri-value <">
digest-uri-value = serv-type "/" host [ "/" serv-name ]
serv-type = 1*ALPHA
host = 1*( ALPHA | DIGIT | "-" | "." )
serv-name = host
response = "response" "=" response-value
response-value = 32LHEX
LHEX = "0" | "1" | "2" | "3" |
"4" | "5" | "6" | "7" |
"8" | "9" | "a" | "b" |
"c" | "d" | "e" | "f"
cipher = "cipher" "=" cipher-value
authzid = "authzid" "=" <"> authzid-value <">
authzid-value = qdstr-val
username
The user's name in the specified realm, encoded according to the
value of the "charset" directive. This directive is required and
MUST be present exactly once; otherwise, authentication fails.
realm
The realm containing the user's account. This directive is
required if the server provided any realms in the
"digest-challenge", in which case it may appear exactly once and
its value SHOULD be one of those realms. If the directive is
missing, "realm-value" will set to the empty string when computing
A1 (see below for details).
nonce
The server-specified data string received in the preceding
digest-challenge. This directive is required and MUST be present
exactly once; otherwise, authentication fails.
Leach & Newman Standards Track [Page 7]
RFC 2831 Digest SASL Mechanism May 2000
cnonce
A client-specified data string which MUST be different each time a
digest-response is sent as part of initial authentication. The
cnonce-value is an opaque quoted string value provided by the
client and used by both client and server to avoid chosen
plaintext attacks, and to provide mutual authentication. The
security of the implementation depends on a good choice. It is
RECOMMENDED that it contain at least 64 bits of entropy. This
directive is required and MUST be present exactly once; otherwise,
authentication fails.
nonce-count
The nc-value is the hexadecimal count of the number of requests
(including the current request) that the client has sent with the
nonce value in this request. For example, in the first request
sent in response to a given nonce value, the client sends
"nc=00000001". The purpose of this directive is to allow the
server to detect request replays by maintaining its own copy of
this count - if the same nc-value is seen twice, then the request
is a replay. See the description below of the construction of
the response value. This directive may appear at most once; if
multiple instances are present, the client should abort the
authentication exchange.
qop
Indicates what "quality of protection" the client accepted. If
present, it may appear exactly once and its value MUST be one of
the alternatives in qop-options. If not present, it defaults to
"auth". These values affect the computation of the response. Note
that this is a single token, not a quoted list of alternatives.
serv-type
Indicates the type of service, such as "www" for web service,
"ftp" for FTP service, "smtp" for mail delivery service, etc. The
service name as defined in the SASL profile for the protocol see
section 4 of [RFC 2222], registered in the IANA registry of
"service" elements for the GSSAPI host-based service name form
[RFC 2078].
host
The DNS host name or IP address for the service requested. The
DNS host name must be the fully-qualified canonical name of the
host. The DNS host name is the preferred form; see notes on server
processing of the digest-uri.
Leach & Newman Standards Track [Page 8]
RFC 2831 Digest SASL Mechanism May 2000
serv-name
Indicates the name of the service if it is replicated. The service
is considered to be replicated if the client's service-location
process involves resolution using standard DNS lookup operations,
and if these operations involve DNS records (such as SRV, or MX)
which resolve one DNS name into a set of other DNS names. In this
case, the initial name used by the client is the "serv-name", and
the final name is the "host" component. For example, the incoming
mail service for "example.com" may be replicated through the use
of MX records stored in the DNS, one of which points at an SMTP
server called "mail3.example.com"; it's "serv-name" would be
"example.com", it's "host" would be "mail3.example.com". If the
service is not replicated, or the serv-name is identical to the
host, then the serv-name component MUST be omitted.
digest-uri
Indicates the principal name of the service with which the client
wishes to connect, formed from the serv-type, host, and serv-name.
For example, the FTP service on "ftp.example.com" would have a
"digest-uri" value of "ftp/ftp.example.com"; the SMTP server from
the example above would have a "digest-uri" value of
"smtp/mail3.example.com/example.com".
Servers SHOULD check that the supplied value is correct. This will
detect accidental connection to the incorrect server. It is also so
that clients will be trained to provide values that will work with
implementations that use a shared back-end authentication service
that can provide server authentication.
The serv-type component should match the service being offered. The
host component should match one of the host names of the host on
which the service is running, or it's IP address. Servers SHOULD NOT
normally support the IP address form, because server authentication
by IP address is not very useful; they should only do so if the DNS
is unavailable or unreliable. The serv-name component should match
one of the service's configured service names.
This directive may appear at most once; if multiple instances are
present, the client should abort the authentication exchange.
Note: In the HTTP use of Digest authentication, the digest-uri is the
URI (usually a URL) of the resource requested -- hence the name of
the directive.
response
A string of 32 hex digits computed as defined below, which proves
that the user knows a password. This directive is required and
MUST be present exactly once; otherwise, authentication fails.
Leach & Newman Standards Track [Page 9]
RFC 2831 Digest SASL Mechanism May 2000
maxbuf
A number indicating the size of the largest buffer the client is
able to receive. If this directive is missing, the default value
is 65536. This directive may appear at most once; if multiple
instances are present, the server should abort the authentication
exchange.
charset
This directive, if present, specifies that the client has used
UTF-8 encoding for the username and password. If not present, the
username and password must be encoded in ISO 8859-1 (of which
US-ASCII is a subset). The client should send this directive only
if the server has indicated it supports UTF-8. The directive is
needed for backwards compatibility with HTTP Digest, which only
supports ISO 8859-1.
LHEX
32 hex digits, where the alphabetic characters MUST be lower case,
because MD5 is not case insensitive.
cipher
The cipher chosen by the client. This directive MUST appear
exactly once if "auth-conf" is negotiated; if required and not
present, authentication fails.
authzid
The "authorization ID" as per RFC 2222, encoded in UTF-8. This
directive is optional. If present, and the authenticating user has
sufficient privilege, and the server supports it, then after
authentication the server will use this identity for making all
accesses and access checks. If the client specifies it, and the
server does not support it, then the response-value will be
incorrect, and authentication will fail.
The size of a digest-response MUST be less than 4096 bytes.
2.1.2.1 Response-value
The definition of "response-value" above indicates the encoding for
its value -- 32 lower case hex characters. The following definitions
show how the value is computed.
Although qop-value and components of digest-uri-value may be
case-insensitive, the case which the client supplies in step two is
preserved for the purpose of computing and verifying the
response-value.
response-value =
Leach & Newman Standards Track [Page 10]
RFC 2831 Digest SASL Mechanism May 2000
HEX( KD ( HEX(H(A1)),
{ nonce-value, ":" nc-value, ":",
cnonce-value, ":", qop-value, ":", HEX(H(A2)) }))
If authzid is specified, then A1 is
A1 = { H( { username-value, ":", realm-value, ":", passwd } ),
":", nonce-value, ":", cnonce-value, ":", authzid-value }
If authzid is not specified, then A1 is
A1 = { H( { username-value, ":", realm-value, ":", passwd } ),
":", nonce-value, ":", cnonce-value }
where
passwd = *OCTET
The "username-value", "realm-value" and "passwd" are encoded
according to the value of the "charset" directive. If "charset=UTF-8"
is present, and all the characters of either "username-value" or
"passwd" are in the ISO 8859-1 character set, then it must be
converted to ISO 8859-1 before being hashed. This is so that
authentication databases that store the hashed username, realm and
password (which is common) can be shared compatibly with HTTP, which
specifies ISO 8859-1. A sample implementation of this conversion is
in section 8.
If the "qop" directive's value is "auth", then A2 is:
A2 = { "AUTHENTICATE:", digest-uri-value }
If the "qop" value is "auth-int" or "auth-conf" then A2 is:
A2 = { "AUTHENTICATE:", digest-uri-value,
":00000000000000000000000000000000" }
Note that "AUTHENTICATE:" must be in upper case, and the second
string constant is a string with a colon followed by 32 zeros.
These apparently strange values of A2 are for compatibility with
HTTP; they were arrived at by setting "Method" to "AUTHENTICATE" and
the hash of the entity body to zero in the HTTP digest calculation of
A2.
Also, in the HTTP usage of Digest, several directives in the
Leach & Newman Standards Track [Page 11]
RFC 2831 Digest SASL Mechanism May 2000
"digest-challenge" sent by the server have to be returned by the
client in the "digest-response". These are:
opaque
algorithm
These directives are not needed when Digest is used as a SASL
mechanism (i.e., MUST NOT be sent, and MUST be ignored if received).
2.1.3 Step Three
The server receives and validates the "digest-response". The server
checks that the nonce-count is "00000001". If it supports subsequent
authentication (see section 2.2), it saves the value of the nonce and
the nonce-count. It sends a message formatted as follows:
response-auth = "rspauth" "=" response-value
where response-value is calculated as above, using the values sent in
step two, except that if qop is "auth", then A2 is
A2 = { ":", digest-uri-value }
And if qop is "auth-int" or "auth-conf" then A2 is
A2 = { ":", digest-uri-value, ":00000000000000000000000000000000" }
Compared to its use in HTTP, the following Digest directives in the
"digest-response" are unused:
nextnonce
qop
cnonce
nonce-count
