One document matched: draft-hammer-http-token-auth-00.xml
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<rfc category="std" ipr="trust200902" docName="draft-hammer-http-token-auth-00">
<?rfc strict="yes" ?>
<?rfc toc="yes" ?>
<?rfc tocdepth="3" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<front>
<title abbrev="Token Authentication">HTTP Authentication: Token Access Authentication</title>
<author initials="E" surname="Hammer-Lahav" fullname="Eran Hammer-Lahav">
<organization>
Yahoo!
</organization>
<address>
<email>eran@hueniverse.com</email>
<uri>http://hueniverse.com</uri>
</address>
</author>
<date year="2009"/>
<abstract>
<t>
This document specifies the HTTP Token Access Authentication scheme.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
[[ This draft is submitted for the consideration of the OAuth Working Group to be adopted as
an official working group item per its current charter. It is presented in its raw form to
assist in facilitating a more effective working group conversation and should not be
considered a complete proposal. Please discuss this draft on the
<eref target="https://www.ietf.org/mailman/listinfo/oauth">oauth@ietf.org</eref> mailing
list. ]]
</t>
<t>
With the growing use of distributed web services and cloud computing, clients need to allow
other parties access to the resources they control. When granting access, clients should
not be required to share their credentials (typically a username and password), and should
have the ability to restrict access to a limited subset of the resources they control or
the access methods supported by these resources. These goals require new classes of
authentication credentials.
</t>
<t>
The HTTP Basic and Digest Access authentication schemes defined by <xref target="RFC2617" />,
enable clients to make authenticated HTTP requests by using a username (or userid) and
a password. In most cases, the client uses a single set of credentials to access all the
resources it controls which are hosted by the server.
</t>
<t>
While the Basic and Digest schemes can be used to send credentials other than a username
and password, their wide deployment and well-established behavior in user-agents preclude
them from being used with other classes of credentials. Extending these schemes to support
new classes would require impractical changes to their existing deployment.
</t>
<t>
The Token Access Authentication scheme provides a method for making authenticated HTTP
requests using a token - an identifier used to denote an access grant with specific scope,
duration, cryptographic properties, and other attributes. Tokens can issued by the server,
self-issued by the client, or issued by a third party.
</t>
<t>
The token scheme support an extensible set of credential classes, by enabling the server to
declare the classes it supports. Token classes determine how tokens are obtained and the
context in which they can be used. It also supports an extensible set of authentication
methods and authentication coverage (the elements of the HTTP request such as the request
URI or entity-body included in the authentication process).
</t>
<t>
This specification defines four token authentication methods to support the most common use
cases and describes their security properties. The methods through which clients obtain
tokens supporting these methods are beyond the scope of this specification. The OAuth
protocol <xref target="I-D.ietf-oauth-web-delegation" /> defines one such set of methods
for obtaining <spanx style="oauth">oauth</spanx>-class token credentials.
</t>
<section title="Terminology">
<t>
<list style="hanging" hangIndent="6">
<t hangText="client">
<vspace />
An HTTP client (per <xref target="RFC2616" />) capable of making
<xref target="requests">Token-authenticated requests</xref>.
</t>
<t hangText="server">
<vspace />
An HTTP server (per <xref target="RFC2616" />) capable of accepting
<xref target="requests">Token-authenticated requests</xref>.
</t>
<t hangText="protected resource">
<vspace />
An access-restricted resource (per <xref target="RFC2616" />) hosted by the server
and accessible by making a <xref target="requests">Token-authenticated request</xref>.
</t>
<t hangText="token credentials">
<vspace />
A set of a unique identifier (token) and an authentication method with an OPTIONAL
shared secret (symmetric or asymmetric), as well as other attributes (e.g. class,
duration, scope), used by the client to make authenticated
requests.
</t>
<t hangText="normalized request string">
<vspace />
A string representing various elements of the HTTP request, normalized and
concatenated together. The elements included in the normalize request string are
determined by the authentication coverage supported by the server.
</t>
</list>
</t>
</section>
<section title="Example">
<figure>
<preamble>
The following HTTP request:
</preamble>
<artwork xml:space="preserve"><![CDATA[
GET /resource/1 HTTP/1.1
Host: example.com
]]>
</artwork>
</figure>
<figure>
<preamble>
returns the following authentication challenge:
</preamble>
<artwork xml:space="preserve"><![CDATA[
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Token class="oauth",
methods="hmac-sha-1 hmac-sha-256",
timestamp="137131190"
]]>
</artwork>
</figure>
<t>
This means the server is expecting an <spanx style="verb">oauth</spanx> class token using
either the <spanx style="verb">hmac-sha-1</spanx> or <spanx style="verb">hmac-sha-256</spanx>
authentication methods. It also provides its current time to assist the client in
synchronizing its clock with the server's clock for the purpose of producing a unique
nonce value.
</t>
<figure>
<preamble>
The client attempts the HTTP request again, this time using a set of token credentials
supporting the <spanx style="verb">hmac-sha-1</spanx> method issued by the server
earlier to authenticate:
</preamble>
<artwork xml:space="preserve"><![CDATA[
GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Token token="h480djs93hd8",
class="oauth",
method="hmac-sha-1",
timestamp="137131200",
nonce="dj83hs9s",
auth="djosJKDKJSD8743243/jdk33klY="
]]>
</artwork>
<postamble>
to which the server respond with the requested resource representation after validating
the request.
</postamble>
</figure>
</section>
<section title="Notational Conventions">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
<xref target="RFC2119" />.
</t>
<t>
This document uses the Augmented Backus-Naur Form (ABNF) notation of
<xref target="I-D.ietf-httpbis-p1-messaging" />. Additionally, the following rules are
included from <xref target="RFC2617" />: realm, auth-param.
</t>
</section>
</section>
<section title="Making Requests" anchor="requests">
<t>
The client makes authenticated requests by calculating the values of a set of attributes
and adding them to the HTTP request using the <xref target="authz_header">Authorization header field</xref>.
Authenticated request can be sent either directly (without first receiving a challenge), or
in response to an authentication challenge.
</t>
<t>
To make an authenticated request, the client obtains information about the attributes
supported by the server. This information is provided by the server via the
<xref target="authn_header">WWW-Authenticate header field</xref>. The client SHOULD only send an
authenticated request to the server (without first receiving a challenge) if it has prior
knowledge of the attributes supported by server.
</t>
<t>
The client chooses an available token with the supported class and authentication method.
It also chooses a supported authentication coverage. The methods through which the client
obtains a valid token, or the criteria used to choose a token if more than one is available
are beyond the scope of this specification.
</t>
<t>
Once the client selects the appropriate token credentials it proceeds to:
<list style="numbers">
<t>
Assign values based on its selection to the following attributes:
<list style="symbols">
<t>
<spanx style="verb">token</spanx>
</t>
<t>
<spanx style="verb">class</spanx>
</t>
<t>
<spanx style="verb">method</spanx>
</t>
<t>
<spanx style="verb">coverage</spanx>
</t>
</list>
</t>
<t>
If the client uses a coverage method other than <spanx style="verb">none</spanx> it
MUST assign values to the following attributes:
<list style="symbols">
<t>
<spanx style="verb">nonce</spanx>
</t>
<t>
<spanx style="verb">timestamp</spanx>
</t>
</list>
</t>
<t>
Assigns value to any additional class-specific, method-specific, or coverage-specific
attributes as defined by protocol extensions.
</t>
<t>
If the client uses a coverage method other than <spanx style="verb">none</spanx> it
constructs the normalized request string based on the selected coverage as described in
<xref target="coverage" />.
</t>
<t>
Calculates the value of the <spanx style="verb">auth</spanx> attribute as defined by
the selected authentication method.
</t>
<t>
Adds the assigned attributes to the request via the
<xref target="authz_header">Authorization header field</xref>.
</t>
<t>
Sends the authenticated HTTP request to the server.
</t>
</list>
</t>
</section>
<section title="Verifying Requests" anchor="verify_request">
<t>
A servers receiving an authenticated request validates it by performing the following
REQUIRED steps:
<list style="numbers">
<t>
Verify that the token used by the client as well as the coverage method matches the
server's requirements.
</t>
<t>
If the client used a coverage method other than <spanx style="verb">none</spanx>,
construct the normalized request string based on the selected coverage as described in
<xref target="coverage" />.
</t>
<t>
If the client used an authentication method other than <spanx style="verb">none</spanx>,
recalculate the value of the <spanx style="verb">auth</spanx> attribute as described in
<xref target="methods" /> and compare it to the value received from the client via
the <spanx style="verb">auth</spanx> attribute.
</t>
<t>
If the client used a coverage method other than <spanx style="verb">none</spanx>,
ensure that the combination of nonce, timestamp, and token received from the client has
not been used before in a previous request (the server MAY reject requests with stale
timestamps; the determination of staleness is left up to the server to define).
</t>
<t>
Verify the scope and status of the client credentials as represented by the token.
</t>
</list>
</t>
<t>
If the request fails verification, the server SHOULD respond with an HTTP 401 (unauthorized)
status code, and SHOULD include a token scheme authentication challenge using the
<xref target="error_header">WWW-Authenticate header field</xref>. The server MAY include
further details about why the request was rejected using the
<xref target="error_header">Authorization-Error header field</xref>.
</t>
</section>
<section title="The WWW-Authenticate Response Header" anchor="authn_header">
<t>
A server receiving a request for a protected resource without a valid
<xref target="authz_header">Authorization header field</xref> MUST respond with a 401
status code (Unauthorized), and includes at least one
<spanx style="verb">WWW-Authenticate</spanx> header field including a token scheme
challenge.
</t>
<t>
The <spanx style="verb">WWW-Authenticate</spanx> header field uses the framework defined by
<xref target="RFC2617" /> as follows:
</t>
<figure>
<artwork xml:space="preserve"><![CDATA[
challenge = "Token" RWS token-challenge
token-challenge = class
CS method-list
[ CS coverage-list ]
[ CS timestamp ]
class = "class" "=" <"> token <">
method-list = "method" "=" <"> 1#method-name <">
method-name = "none" /
"hmac-sha-1" /
"hmac-sha-256" /
"rsassa-pkcs1-v1.5-sha-256" /
token
coverage-list = "coverage" "=" <"> 1#coverage-name <">
coverage-name = "none" /
"base" /
"base+body-sha-256" /
token
timestamp = "timestamp" "=" <"> 1*DIGIT <">
CS = OWF "," OWF
]]>
</artwork>
</figure>
<section title="The 'class' Attribute">
<t>
The name of the token class supported by the server. Servers MAY support multiple classes
per protected resource by providing multiple challenges, each with a different class.
</t>
</section>
<section title="The 'method' Attribute">
<t>
The list of authentication method names supported by the server, provided as a
space-delimited list. Authentication methods are described in <xref target="methods" />.
</t>
</section>
<section title="The 'coverage' Attribute">
<t>
The list of authentication coverage names supported by the server, provided as a
space-delimited list. If omitted, the attribute defaults to <spanx style="verb">base</spanx>.
Authentication coverage is described in <xref target="coverage" />.
</t>
</section>
<section title="The 'timestamp' Attribute">
<t>
Signature-based and hash-based authentication methods use timestamps in combination with
unique nonce values to protect against replay attacks when used over an unsecure channel.
</t>
<t>
The timestamp attribute is used by the server to publish its current time, enabling
clients to synchronize their close with the server. The timestamp value is the current
time expressed in the number of seconds since January 1, 1970 00:00:00 GMT, and MUST be a
positive integer.
</t>
<t>
To avoid the need to retain an infinite number of nonce values for future checks, servers
MAY choose to restrict the time period after which a request with an old timestamp is
rejected. Servers applying such a restriction SHOULD provide their current time to the
client either in every challenge or when a request fails due to a timestamp outside the
allowed window.
</t>
</section>
</section>
<section title="The Authorization Request Header" anchor="authz_header">
<t>
A client making a request for a protected resource either directly, or in retrying a
request after receiving a 401 status code (Unauthorized) with a token challenge, MUST
include at least one <spanx style="verb">Authorization</spanx> header field including
token scheme credentials.
</t>
<t>
The <spanx style="verb">Authorization</spanx> header field uses the framework defined by
<xref target="RFC2617" /> as follows:
</t>
<figure>
<artwork xml:space="preserve"><![CDATA[
credentials = "Token" RWS token-response
token-response = token-id
CS class
CS method
[ CS coverage ]
[ CS nonce ]
[ CS timestamp ]
[ CS auth ]
token-id = "token" "=" <"> token <">
method = "method" "=" <"> method-name <">
coverage = "coverage" "=" <"> coverage-name <">
nonce = "nonce" "=" <"> token <">
auth = "auth" "=" <"> token <">
]]>
</artwork>
</figure>
<section title="The 'token' Attribute">
<t>
The value used to identify the set of token credentials used by the client to
authenticate. The token identifier can be an opaque string or use a well-defined internal
structure, which is determined by the token class.
</t>
</section>
<section title="The 'class' Attribute">
<t>
The name of the token class used by the client to make the request.
</t>
</section>
<section title="The 'method' Attribute">
<t>
The name of the authentication method used by the client to make the request.
</t>
</section>
<section title="The 'coverage' Attribute">
<t>
The name of the authentication coverage method used by the client to make the request.
If the attribute is omitted, its value defaults to <spanx style="verb">base</spanx>.
</t>
</section>
<section title="The 'nonce' Attribute">
<t>
A random string, uniquely generated by the client to allow the server to verify that a
request has never been made before and helps prevent replay attacks when requests are
made over a non-secure channel. The nonce value MUST be unique across all requests with
the same timestamp and token combinations.
</t>
</section>
<section title="The 'timestamp' Attribute">
<t>
The timestamp value is the current time expressed in the number of seconds since
January 1, 1970 00:00:00 GMT, and MUST be a positive integer.
</t>
</section>
<section title="The 'auth' Attribute">
<t>
The output of the authentication method function after applying it to the selected
coverage as described in <xref target="methods" />.
</t>
</section>
</section>
<section title="The Authentication-Error Response Header" anchor="error_header">
<t>
A server receiving a request for a protected resource with an invalid
<xref target="authz_header">Authorization header field</xref> MAY includes the
<spanx style="verb">Authentication-Error</spanx> header field providing the client with
information to help it successfully authenticate with the server.
</t>
<t>
The <spanx style="verb">Authentication-Error</spanx> header field is defined as follows:
</t>
<figure>
<artwork xml:space="preserve"><![CDATA[
Authentication-Error = "Authentication-Error" ":"
OWS #1error-param
error-param = error-code /
error-info /
error-message /
auth-param
error-code = "error-code" "=" <"> token <">
error-info = "error-info" "=" <"> token <">
error-message = "error-message" "=" quoted-string
]]>
</artwork>
</figure>
<section title="The 'error-code' attribute">
<t>
</t>
</section>
<section title="The 'error-info' attribute">
<t>
</t>
</section>
<section title="The 'error-message' attribute">
<t>
</t>
</section>
</section>
<section title="Authentication Methods" anchor="methods">
<t>
In order for the server to verify the authenticity of the request and prevent unauthorized
access, the client must prove it is the rightful owner of the credentials. This is
accomplished using the authentication method associated with the token.
</t>
<t>
This specification provides three methods for the client to prove its rightful ownership of
the credentials: <spanx style="verb">hmac-sha-1</spanx>, <spanx style="verb">hmac-sha-256</spanx>,
and <spanx style="verb">rsassa-pkcs1-v1.5-sha-256</spanx>. In addition, the
<spanx style="verb">none</spanx> method is defined to allow the use of bearer token which
does not utilizes any cryptographic means.
</t>
<t>
The authentication process does not change the request or its parameters, with the exception
of the <spanx style="verb">auth</spanx> attribute.
</t>
<section title="The 'none' Method">
<t>
The <spanx style="verb">none</spanx> method does not employ a cryptographic algorithm
and does not provide any security on its own. Servers utilizing this method use the token
identifier as a bearer token, relying solely on the value of the token identifier to
authenticate the client.
</t>
<t>
The <spanx style="verb">nonce</spanx>, <spanx style="verb">timestamp</spanx>, and
<spanx style="verb">auth</spanx> attributes are not used, and SHOULD NOT be included in
authenticated requests. The <spanx style="verb">coverage</spanx> attribute MUST be set to
<spanx style="verb">none</spanx> but MAY be omitted from the request. Nevertheless, these
attributes MUST be included in the normalized request string together with any other
authentication attributes.
</t>
</section>
<section title="The 'hmac-sha-1' Method">
<t>
The <spanx style="verb">hmac-sha-1</spanx> authentication method uses the HMAC-SHA1
algorithm as defined in <xref target="RFC2104" />:
<figure>
<artwork xml:space="preserve"><![CDATA[
digest = HMAC-SHA1 (key, text)
]]>
</artwork>
</figure>
</t>
<t>
The HMAC-SHA1 function variables are used in following way:
<list style="hanging" hangIndent="6">
<t hangText="text">
<vspace />
is set to the value of the normalize request string as described in
<xref target="coverage" />.
</t>
<t hangText="key">
<vspace />
is set to the shared-secret associated with the token.
</t>
<t hangText="digest">
<vspace />
is used to set the value of the <spanx style="verb">auth</spanx>
attribute, after the result octet string is base64-encoded per
<xref target="RFC2045" /> section 6.8.
</t>
</list>
</t>
</section>
<section title="The 'hmac-sha-256' Method">
<t>
The <spanx style="verb">hmac-sha-256</spanx> authentication method uses the HMAC
algorithm as defined in <xref target="RFC2104" /> together with the SHA-256 hash
function defined in <xref target="NIST FIPS-180-3" />:
<figure>
<artwork xml:space="preserve"><![CDATA[
digest = HMAC-SHA256 (key, text)
]]>
</artwork>
</figure>
</t>
<t>
The HMAC-SHA256 function variables are used in following way:
<list style="hanging" hangIndent="6">
<t hangText="text">
<vspace />
is set to the value of the normalize request string as described in
<xref target="coverage" />.
</t>
<t hangText="key">
<vspace />
is set to the shared-secret associated with the token.
</t>
<t hangText="digest">
<vspace />
is used to set the value of the <spanx style="verb">auth</spanx>
attribute, after the result octet string is base64-encoded per
<xref target="RFC2045" /> section 6.8.
</t>
</list>
</t>
</section>
<section title="The 'rsassa-pkcs1-v1.5-sha-256' Method">
<t>
The <spanx style="verb">rsassa-pkcs1-v1.5-sha-256</spanx> signature method uses the
RSASSA-PKCS1-v1_5 signature algorithm as defined in <xref target="RFC3447" /> section 8.2
(also known as PKCS#1), using SHA-256 as the hash function as defined in
<xref target="NIST FIPS-180-3" /> for EMSA-PKCS1-v1_5.
</t>
<t>
The normalized request string is signed using the RSA private key associated with the
token as defined in <xref target="RFC3447" /> section 8.2.1:
<figure>
<artwork xml:space="preserve"><![CDATA[
S = RSASSA-PKCS1-V1_5-SIGN (K, M)
]]>
</artwork>
</figure>
Where:
<list style="hanging" hangIndent="6">
<t hangText="K">
<vspace />
is set to the RSA private key associated with the token,
</t>
<t hangText="M">
<vspace />
is set to the value of the normalized request string described
in <xref target="coverage" />, and
</t>
<t hangText="S">
<vspace />
is the result signature used to set the value of the <spanx style="verb">auth</spanx>
attribute, after the result octet string is base64-encoded per <xref target="RFC2045" />
section 6.8.
</t>
</list>
</t>
<t>
The server verifies the signature per <xref target="RFC3447" /> section 8.2.2:
<figure>
<artwork xml:space="preserve"><![CDATA[
RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S)
]]>
</artwork>
</figure>
Where:
<list style="hanging" hangIndent="6">
<t hangText="(n, e)">
<vspace />
is set to the RSA public key associated with the token,
</t>
<t hangText="M">
<vspace />
is set to the value of the normalized request string described
in <xref target="coverage" />, and
</t>
<t hangText="S">
<vspace />
is set to the octet string value of the <spanx style="verb">auth</spanx> attribute
received from the client.
</t>
</list>
</t>
</section>
</section>
<section title="Coverage Methods" anchor="coverage">
<t>
The normalized request string is a consistent, reproducible concatenation of several
of the HTTP request elements into a single string. The string is used as an input to
the authentication methods with the exception of <spanx style="verb">none</spanx>.
</t>
<section title="The 'base' Method">
<t>
When using the <spanx style="verb">base</spanx> method, the normalized request string
includes the following components of the HTTP request:
<list style="symbols">
<t>
The HTTP request method (e.g. <spanx style="verb">GET</spanx>,
<spanx style="verb">POST</spanx>, etc.).
</t>
<t>
The authority as declared by the HTTP <spanx style="verb">Host</spanx> request
header.
</t>
<t>
The request resource URI.
</t>
<t>
The <xref target="authz_header">Authorization header field</xref> attributes, with the
exception of the <spanx style="verb">auth</spanx> attribute.
</t>
</list>
</t>
<t>
The <spanx style="verb">base</spanx> normalized request string does not cover the entire
HTTP request. Most notably, it does not include the entity-body or most HTTP
entity-headers. It is important to note that the server cannot verify the authenticity
of the excluded request elements without using additional protections such as SSL/TLS or
other methods.
</t>
<section title="String Construction" anchor="base_string">
<t>
The normalized request string is constructed by concatenating together, in order, the
following HTTP request elements:
<list style="numbers">
<t>
The HTTP request method in uppercase. For example: <spanx style="verb">HEAD</spanx>,
<spanx style="verb">GET</spanx>, <spanx style="verb">POST</spanx>, etc.
</t>
<t>
A <spanx style="verb">,</spanx> character (ASCII code 44).
</t>
<t>
The hostname, colon-separated (ASCII code 58) from the TCP port used to make the
request as included in the HTTP request <spanx style="verb">Host</spanx> header
field. The port MUST be included even if it is not included in the
<spanx style="verb">Host</spanx> header field (i.e. the default port for the
scheme).
</t>
<t>
A <spanx style="verb">,</spanx> character (ASCII code 44).
</t>
<t>
Any authentication attribute, with the exception of the <spanx style="verb">auth</spanx>,
which is assigned a value (including default values), are added to the normalized
request string as follows:
<list style="numbers">
<t>
The name of each parameter is concatenated to its corresponding value using an
<spanx style="verb">=</spanx> character (ASCII code 61) as separator, even if the
value is empty.
</t>
<t>
The name/value pairs are sorted using ascending byte value ordering.
</t>
<t>
The sorted name/value pairs are concatenated together into a single string by
using a <spanx style="verb">,</spanx> character (ASCII code 44) as separator.
</t>
</list>
</t>
<t>
A <spanx style="verb">,</spanx> character (ASCII code 44).
</t>
<t>
The request resource URI.
</t>
</list>
</t>
</section>
</section>
<section title="The 'base+body-hmac-sha-256' Method">
<t>
The <spanx style="verb">base+body-hmac-sha-256</spanx> method added the request entity-body
to the elements included in the normalized request string. It does not include the
entity-body directly in the normalized string. Instead, it calculates the hash value of
the entity-body using the SHA-256 hash function defined in <xref target="NIST FIPS-180-3" />.
</t>
<t>
The normalized request string is constructed following the same process defined in
<xref target="base_string" />, with the following addition:
<list style="symbols">
<t>
Before constructing the string, the entity-body hash is calculated by applying the
SHA-256 hash function on the raw entity-body content.
</t>
<t>
The hash value is added to the list of authentication attributes by assigning its
value to the <spanx style="verb">body-hash</spanx> attribute name. This is done
prior to the attributes being sorted and added to the string.
</t>
<t>
The <spanx style="verb">body-hash</spanx> attribute is only included in the
normalized request string and is not added to the
<xref target="authz_header">Authorization header field</xref>.
</t>
</list>
</t>
</section>
</section>
<section title="Scheme Extensions">
<t>
</t>
</section>
<section title="Security Considerations" anchor="Security">
<t>
As stated in <xref target="RFC2617" />, the greatest sources of risks are usually found not
in the core protocol itself but in policies and procedures surrounding its use. Implementers
are strongly encouraged to assess how this protocol addresses their security requirements.
</t>
<section title="Credentials Transmission">
<t>
This specification does not describe any mechanism for obtaining or transmitting raw
tokens credentials. Methods used to obtain tokens should ensure that these transmissions
are protected using transport-layer mechanisms such as TLS or SSL.
</t>
</section>
<section title="Confidentiality of Requests">
<t>
While this protocol provides a mechanism for verifying the integrity of requests, it
provides no guarantee of request confidentiality. Unless further precautions are taken,
eavesdroppers will have full access to request content. Servers should carefully consider
the kinds of data likely to be sent as part of such requests, and should employ
transport-layer security mechanisms to protect sensitive resources.
</t>
</section>
<section title="Spoofing by Counterfeit Servers">
<t>
This protocol makes no attempt to verify the authenticity of the server. A hostile party
could take advantage of this by intercepting the client's requests and returning
misleading or otherwise incorrect responses. Service providers should consider such
attacks when developing services using this protocol, and should require transport-layer
security for any requests where the authenticity of the server or of request responses is
an issue.
</t>
</section>
<section title="Plaintext Storage of Credentials">
<t>
When used with a symmetric shared-secret authentication method, the token shared-secret
function the same way passwords do in traditional authentication systems. In order to
compute the signatures used in methods, the server must have access to these secrets in
plaintext form. This is in contrast, for example, to modern operating systems, which
store only a one-way hash of user credentials.
</t>
<t>
If an attacker were to gain access to these secrets - or worse, to the server's database
of all such secrets - he or she would be able to perform any action on behalf of any
resource owner. Accordingly, it is critical that servers protect these secrets from
unauthorized access.
</t>
</section>
<section title="Scoping of Access Requests">
<t>
By itself, this protocol does not provide any method for scoping the access rights
granted to a client. However, most applications do require greater granularity of access
rights. For example, servers may wish to make it possible to grant access to some
protected resources but not others, or to grant only limited access (such as read-only
access) to those protected resources.
</t>
<t>
When implementing this protocol, servers should consider the types of access resource
owners may wish to grant clients, and should provide mechanisms to do so. Servers should
also take care to ensure that resource owners understand the access they are granting, as
well as any risks that may be involved.
</t>
</section>
<section title="Entropy of Secrets">
<t>
Unless a transport-layer security protocol is used, eavesdroppers will have full access
to authenticated requests and signatures, and will thus be able to mount offline brute-force
attacks to recover the credentials used. Servers should be careful to assign
shared-secrets which are long enough, and random enough, to resist such attacks for at
least the length of time that the shared-secrets are valid.
</t>
<t>
For example, if shared-secrets are valid for two weeks, servers should ensure that it is
not possible to mount a brute force attack that recovers the shared-secret in less than
two weeks. Of course, servers are urged to err on the side of caution, and use the longest
secrets reasonable.
</t>
<t>
It is equally important that the pseudo-random number generator (PRNG) used to generate
these secrets be of sufficiently high quality. Many PRNG implementations generate number
sequences that may appear to be random, but which nevertheless exhibit patterns or other
weaknesses which make cryptanalysis or brute force attacks easier. Implementers should be
careful to use cryptographically secure PRNGs to avoid these problems.
</t>
</section>
<section title="Denial of Service / Resource Exhaustion Attacks">
<t>
This specification includes a number of features which may make resource exhaustion
attacks against servers possible. For example, this protocol requires servers to track
used nonces. If an attacker is able to use many nonces quickly, the resources required to
track them may exhaust available capacity. And again, this protocol can require servers
to perform potentially expensive computations in order to verify the signature on
incoming requests. An attacker may exploit this to perform a denial of service attack by
sending a large number of invalid requests to the server.
</t>
<t>
Resource Exhaustion attacks are by no means specific to this specification. However,
implementers should be careful to consider the additional avenues of attack that this
protocol exposes, and design their implementations accordingly. For example, entropy
starvation typically results in either a complete denial of service while the system
waits for new entropy or else in weak (easily guessable) secrets. When implementing this
protocol, servers should consider which of these presents a more serious risk for their
application and design accordingly.
</t>
</section>
<section title="Coverage Limitations">
<t>
The normalized request string has been designed to support the authentication methods
defined in this specification. Those designing additional methods, should evaluated the
compatibility of the normalized request string with their security requirements.
Since the normalized request string does not cover the entire HTTP request, servers
should employ additional mechanisms to protect such elements.
</t>
</section>
</section>
<section title="IANA Considerations" anchor="IANA">
<t>
</t>
</section>
<section title="Acknowledgments">
<t>
The author would like to thank Richard Barnes, Breno de Medeiros, Brian Eaton, Ben Laurie,
Mark Nottingham, John Panzer, and Peter Saint-Andre for their suggestions, feedback, and
continued support.
</t>
</section>
<appendix title="Document History" anchor="history">
<t>
[[ To be removed by the RFC editor before publication as an RFC. ]]
</t>
<t>
-00
<list style="symbols">
<t>
Initial (incomplete) draft.
</t>
</list>
</t>
</appendix>
</middle>
<back>
<references title="Normative References">
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.3447.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p1-messaging-08.xml"?>
<reference anchor="NIST FIPS-180-3">
<front>
<title>Secure Hash Standard (SHS). FIPS PUB 180-3, October 2008</title>
<author>
<organization>National Institute of Standards and Technology</organization>
</author>
</front>
<format type="pdf" target="http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf" />
</reference>
</references>
<references title="Informative References">
<?rfc include="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-web-delegation-01.xml"?>
</references>
</back>
</rfc>| PAFTECH AB 2003-2026 | 2026-04-24 13:53:52 |