Network Working Group S. Baer Internet-Draft B. Haberstumpf Intended status: Informational Elektrobit Expires: November 16, 2015 May 15, 2015 Lightweight Token authentication (LTA) 1.0 draft-baer-lightweight-token-authentication-00 Abstract This document contains a specification for a token authentication mechanism that is sufficiently resource-friendly to use it on small embedded or mobile devices. The three involved parties are a service consumer (CON) a service provider (SP) and an authentication provider (AP). The authentication provider decouples authentication and the actual service that is consumed. It also serves as anonymizer. The consumer authenticates at the authentication provider, requests one or more authorization tokens and redeems those tokens when accessing the service provider's offered services. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on November 16, 2015. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect Baer & Haberstumpf Expires November 16, 2015 [Page 1] Internet-Draft LTA 1.0 May 2015 to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Design Goals . . . . . . . . . . . . . . . . . . . . . . 5 1.3.1. Low Resource Usage and Simple Implementation in the Consumer . . . . . . . . . . . . . . . . . . . . . . 5 1.3.2. Works with Standard HTTP + TLS . . . . . . . . . . . 5 1.3.3. Small Network Overhead . . . . . . . . . . . . . . . 5 1.3.4. Robustness . . . . . . . . . . . . . . . . . . . . . 6 1.3.5. Support a Stateless Service Provider . . . . . . . . 6 1.3.6. Anonymization . . . . . . . . . . . . . . . . . . . . 6 2. Preconditions . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1. Transport security . . . . . . . . . . . . . . . . . . . 6 2.2. Authentication of the communication partners . . . . . . 7 2.3. Syntax Definitions . . . . . . . . . . . . . . . . . . . 7 2.4. Base Elements of the Syntax Definitions . . . . . . . . . 7 3. Authentication Overview . . . . . . . . . . . . . . . . . . . 7 4. Consumer Authentication at the Authentication Provider . . . 8 5. Authentication Offers Discovery . . . . . . . . . . . . . . . 8 5.1. Consumer Request for Authentication Offer List . . . . . 9 5.1.1. Authentication Offer List Response . . . . . . . . . 9 5.1.2. Access to Offer List Granted . . . . . . . . . . . . 9 5.1.3. Offer List Request Denied Because of Missing Credentials . . . . . . . . . . . . . . . . . . . . . 10 5.1.4. Offer List Request Denied Because of Invalid Credentials . . . . . . . . . . . . . . . . . . . . . 10 6. Authentication Step by Step . . . . . . . . . . . . . . . . . 10 6.1. Consumer Requests Token . . . . . . . . . . . . . . . . . 11 6.2. Consumer Sets "Accept" Headers . . . . . . . . . . . . . 11 6.3. Authentication Provider Authenticates the Consumer . . . 12 6.4. Creating a Token . . . . . . . . . . . . . . . . . . . . 12 6.4.1. The Token Format Explained . . . . . . . . . . . . . 13 6.4.2. Token Expiration . . . . . . . . . . . . . . . . . . 14 6.5. Creating the token signature . . . . . . . . . . . . . . 15 7. Authentication Provider Answers Token Request . . . . . . . . 15 7.1. Token Request Granted . . . . . . . . . . . . . . . . . . 15 7.2. Token Request Denied Because of Missing Credentials . . . 16 7.3. Token Request Denied Because of Invalid Credentials . . . 16 8. Consumer Redeems Token . . . . . . . . . . . . . . . . . . . 16 8.1. Consumers Should Not Try to Use Expired Tokens . . . . . 16 8.2. Expiration Time . . . . . . . . . . . . . . . . . . . . . 16 Baer & Haberstumpf Expires November 16, 2015 [Page 2] Internet-Draft LTA 1.0 May 2015 8.3. Time to Use . . . . . . . . . . . . . . . . . . . . . . . 16 9. Service Provider Validates and Authenticates Token . . . . . 17 9.1. Validating a token . . . . . . . . . . . . . . . . . . . 17 9.2. Checking if the Token Is Addressed to the Right Service Provider . . . . . . . . . . . . . . . . . . . . . . . . 17 9.3. Checking the Signature . . . . . . . . . . . . . . . . . 17 9.4. Checking if the Token Expired . . . . . . . . . . . . . . 17 10. Service Provider Answers the Request . . . . . . . . . . . . 18 10.1. Service access granted . . . . . . . . . . . . . . . . . 18 10.2. Access Denied due to Missing Authentication Token . . . 18 10.3. Access Denied Because of Illegal Token Format . . . . . 18 10.4. Access Denied Because of Signature Mismatch . . . . . . 19 10.5. Access Denied Because of Unsupported Signing Mechanism . 19 10.6. Access Denied Because of Expired Token . . . . . . . . . 19 10.7. Access Denied Because of Insufficient Permissions . . . 19 10.8. Supported Signing Mechanisms . . . . . . . . . . . . . . 19 10.9. Using a Signature container . . . . . . . . . . . . . . 20 10.10. Error reporting in the response body . . . . . . . . . . 20 11. Optimizations . . . . . . . . . . . . . . . . . . . . . . . . 21 11.1. Authentication Provider Optimizations . . . . . . . . . 21 11.1.1. Authentication Provider Sets Cache Header of a Token 21 11.1.2. Token Cache on Authentication Provider Side . . . . 21 11.1.3. Issuing a new Token Shortly Before the Existing Token Expires . . . . . . . . . . . . . . . . . . . 22 11.1.4. Token Representation Compatibility with Service Provider . . . . . . . . . . . . . . . . . . . . . . 22 11.2. Service Provider Optimizations . . . . . . . . . . . . . 22 11.2.1. Token Cache on Service Provider Side . . . . . . . . 22 11.3. Consumer Optimizations . . . . . . . . . . . . . . . . . 23 11.3.1. Caching the Token Request URIs . . . . . . . . . . . 23 11.3.2. Using Tokens until They Expire . . . . . . . . . . . 23 12. Permission Handling . . . . . . . . . . . . . . . . . . . . . 23 12.1. Service identification URIs . . . . . . . . . . . . . . 23 12.2. Choosing Service Identification URIs and Permission URIs 23 12.3. Permission URI wildcard . . . . . . . . . . . . . . . . 24 12.4. Parameterized Permissions . . . . . . . . . . . . . . . 24 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 25 13.1. Token Requests . . . . . . . . . . . . . . . . . . . . . 25 13.2. Service Request with LTA Token . . . . . . . . . . . . . 25 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 26 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 16. Security Considerations . . . . . . . . . . . . . . . . . . . 27 16.1. Attack Vectors . . . . . . . . . . . . . . . . . . . . . 27 16.1.1. Flooding of the Service Provider . . . . . . . . . . 27 16.1.2. Time Synchronization Attack . . . . . . . . . . . . 27 16.1.3. Token Hijacking . . . . . . . . . . . . . . . . . . 27 16.1.4. Man-in-the-Middle . . . . . . . . . . . . . . . . . 28 16.1.5. Replay Attacks . . . . . . . . . . . . . . . . . . . 28 Baer & Haberstumpf Expires November 16, 2015 [Page 3] Internet-Draft LTA 1.0 May 2015 16.1.6. Service Permission Information Leaking . . . . . . . 28 16.1.7. Addressing a Token to the Wrong Service . . . . . . 28 16.1.8. Using Token Request URIs That Are Not Valid Anymore 29 16.1.9. Compromized Authentication Provider or Stolen AP Secrets . . . . . . . . . . . . . . . . . . . . . . 29 16.2. Anonymization Limitations . . . . . . . . . . . . . . . 29 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 17.1. Normative References . . . . . . . . . . . . . . . . . . 29 17.2. Informative References . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 1. Introduction The Lightweight Token Authentication is motivated by the need for a simple and resource friendly authentication mechanism mainly targeted (but not limited to) the use in embedded devices. This document specifies the LTA authentication protocol. 1.1. Requirements Language 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 RFC 2119 [RFC2119] . 1.2. Terminology Authentication provider (AP): Network component that accepts authentication requests and issues authentication tokens to a consumer. Consumer (CON): Client application that wants to use a service offered by a service provider. Service provider (SP): Network component that offers a service to the consumer. Service identification URI (SIU): URI of the service used to identify a service in a token. Not necessarily the URI under which the service can be reached. Service permission URI (SPU): URI that represents a permission on the service. Time to use (TTU): Recommended time span for which a token should be used by a consumer before the consumer requests a new token. Baer & Haberstumpf Expires November 16, 2015 [Page 4] Internet-Draft LTA 1.0 May 2015 1.3. Design Goals The design of the Lightweight Token Authentication (LTA) aims to reach the goals described in the following sub-sections. 1.3.1. Low Resource Usage and Simple Implementation in the Consumer It is the most important goal of the LTA to be able to run on small embedded computers (like electronic control units in a car or motorcycle) and mobile devices. Therefore the design keeps the software dependencies and resource requirements low on the consumer side. Calculation and traffic intensive parts of the LTA are shifted to the authentication provider and the service provider. The aim is to keep the following points down in order of importance: 1. Network traffic 2. Memory consumption in the consumer 3. CPU consumption in the consumer 4. Dependencies on 3rd-party software modules in the consumer 1.3.2. Works with Standard HTTP + TLS HTTP software libraries can be considered a commodity - just like the availability of network connections that can transport HTTP. LTA therefore uses HTTP as its transport protocol and TLS as transport security. 1.3.3. Small Network Overhead LTA aims to keep the additional network overhead low. Token requests and the token headers are both designed to stay as small as reasonable while still being in alignment with the philosophy of HTTP. Another goal is to keep the total number of request for authentication down. Typical sizes for LTA tokens including signature are below 500 bytes. The authors are clear on the fact that the biggest part of the network overhead comes from transport security, namely the use of TLS (see Section 2.1 ) but they consider the advantages of using such widely accepted standards to be worth choosing them over proprietary protocol stacks that might reduce network overhead further. Baer & Haberstumpf Expires November 16, 2015 [Page 5] Internet-Draft LTA 1.0 May 2015 1.3.4. Robustness LTA works without a permanent connection between the authentication provider and the service provider in order to remove one possible cause for a service outage. LTA allows consumers to repeat requests. This is important for mobile or embedded devices with an unstable network connection. Service providers that are based on LTA are encouraged to design their services so that they also accept request repetition. 1.3.5. Support a Stateless Service Provider The LTA does not force the service provider to manage state. Many services are intentionally designed stateless, especially to allow for efficient scaling. 1.3.6. Anonymization The separation into authentication provider and service provider aims to anonymize the consumer towards the service provider. This protects the consumer's privacy while still allowing the provider to offer services with access restrictions. While the authentication provider knows the identity of the consumers - or even the users behind the consumer applications - it does not know, what data the consumers send to a service. From the service provider's perspective the consumer is anonymous. The token that the user offers to the service provider does not allow the service provider to identify a consumer. To ensure anonymization, service provider and authentication provider must be separate entities which should also be clearly separated on an organizational level. Especially the authentication provider must not disclose a token-to-consumer mapping to the service provider. See Section 16.2 for limitations on the achieved level of anonymity. 2. Preconditions 2.1. Transport security LTA relies on transport encryption (as opposed to message encryption) between the three involved parties. Baer & Haberstumpf Expires November 16, 2015 [Page 6] Internet-Draft LTA 1.0 May 2015 Consumer, authentication provider and service provider MUST all use Transport Layer Security (TLS) in version 1.2 or newer. See [RFC5246] for details. 2.2. Authentication of the communication partners The consumer MUST verify the authenticity of the communication partners - i.e. authentication provider and service provider. The recommended way is using TLS server certificates. See [RFC5246] section 7.4.2 for details. The service provider indirectly authenticates the authentication provider via the token signature. See Section 9 for more information. 2.3. Syntax Definitions The syntax definitions in this document use the "Augmented Backus Naur Form" (ABNF) as defined in [RFC5234] . 2.4. Base Elements of the Syntax Definitions The following recurring syntax elements are used throughout the document and therefore introduced here. LTA's protocol version (and implicitly the token format): lta-version = 1*DIGIT "." 1*DIGIT In this revision of the LTA specification the LTA version is 1.0. The URI that identifies a service: service-identification-uri 3. Authentication Overview The authentication provider is a service that provides consumer authentication and authorization. It also anonymizes the consumers towards the service provider. Instead of authenticating themselves directly at the service provider the consumers use the authentication provider as authentication authority. In short a successful authentication follows these steps: 1. Consumer uses the authentication offers discovery to find out where to request tokens. Baer & Haberstumpf Expires November 16, 2015 [Page 7] Internet-Draft LTA 1.0 May 2015 2. Consumer requests a token at the authentication provider. 3. Authentication provider authenticates the consumer and issues a token. 4. Consumer redeems the token at the 3rd party service. 5. Service provider verifies the authenticity of the token. 4. Consumer Authentication at the Authentication Provider The consumer MUST provide credentials with all requests to the authentication header. This rule applies to the authentication offer list request and all other (subsequent) requests to the authentication provider. An authentication provider SHOULD at least support the "Basic" authentication scheme as defined in [RFC2617] section 2. Other authentication schemes can be used between the consumer and the authentication provider also but implementers should keep in mind that complicated authentication schemes are in conflict with the design goal to keep the effort low for the consumer. A consumer using basic authentication would set the following header: authorization = "Authorization:" 1*SP "Basic" 1*SP credentials The credentials are encoded with the "Base64 Content-Transfer- Encoding" described in [RFC2045] section 6.8. Example: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Since basic authentication can be considered a commodity of the widely available web servers the implementation is not in the scope of this document. 5. Authentication Offers Discovery The authentication provider has a single entry point. The consumer accesses this entry point and gets a list of URIs that it uses to find out for which services the authentication provider offers tokens. Baer & Haberstumpf Expires November 16, 2015 [Page 8] Internet-Draft LTA 1.0 May 2015 +-----+ +-----+ | CON | | AP | +--+--+ +--+--+ | discoverAuthenticationOffers(credentials) | |---------------------------------------------->| | |--. | checkCredentials() | | | |<-' | : authenticationOfferList | |< - - - - - - - - - - - - - - - - - - - - - - -| | | 5.1. Consumer Request for Authentication Offer List The consumer requests the offer list with the following request: authentication-offer-uri = "GET" SP ap-entry-uri "/" lta-version-number Where "ap-entry-uri" is the entry URI of the authentication provider that the consumer must know. The mandatory protocol version number allows to easily route consumers that use different protocol versions to the right authentication provider. If the authentication provider supports multiple versions it MUST offer one offer discovery URI in the form of "authentication-offer-uri" for each supported protocol version. 5.1.1. Authentication Offer List Response The authentication provider first checks the credentials of the consumer. If the user has a valid account, the authentication provider creates a list of all services the consumer is registered for. 5.1.2. Access to Offer List Granted If the consumer's credentials are valid, the authentication provider MUST answer with 200 (OK). The offer response body MUST contain a map of URIs with the Mime type "text/uri-map". Each line of the map has the following format: offer-list-entry = service-identification-uri ">" token-request-uri CR LF Baer & Haberstumpf Expires November 16, 2015 [Page 9] Internet-Draft LTA 1.0 May 2015 So for each service the map tells the consumer under which URI it must request the authentication token. Example URI map: https://www.example.org/wiki>https://example.com/ ap_node234/1.0/https%3A%2F%2Fexample.org%2Fwiki org.example.blog>https://example.com/ap/1.0/org.example.blog Note that in the example above there is an extra newline an indentation due to line length restrictions. Both are not present in the actual URI map. The authentication provider MUST only list those services for which it actually offers a token to the individual consumer. That means a consumer can expect that it has the necessary rights to request a token under each of the listed URIs. If the authentication provider does not offer authentication for any services to the consumer, the offer list MUST be empty. 5.1.3. Offer List Request Denied Because of Missing Credentials The authentication provider MUST answer 401 (Unauthorized) if the consumer does not provide the required authentication header. 5.1.4. Offer List Request Denied Because of Invalid Credentials The authentication provider MUST answer 401 (Unauthorized) if the credentials the consumer used are not valid. 6. Authentication Step by Step The following diagram depicts the sequence for a successful authentication: Baer & Haberstumpf Expires November 16, 2015 [Page 10] Internet-Draft LTA 1.0 May 2015 +-----+ +-----+ +-----+ | CON | | AP | | SP | +--+--+ +--+--+ +--+--+ | requestToken(credentials) | | |------------------------------>| | | |--. checkCredentials() | | | | calculateExpiration() | | | | createToken() | | | | signPayload() | | : token |<-' | |< - - - - - - - - - - - - - - -| | | | | | requestService(..., token) | |------------------------------------------------------------>| | | |--. | | checkTokenFormat() | | | | checkAddressing() | | | | checkSignature() | | | | checkExpiration() | | | | |<-' | | |--. | | executeRequestedService() | | | | |<-' | : response | |< - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -| | | | 6.1. Consumer Requests Token The consumer MUST initiate the authentication by requesting a token from the authentication provider with the following request: token-request = "GET" SP token-request-uri Where the "token-request-uri" is a URI that the consumer previously discovered via an offer list request to the authentication provider. See Section 5 for details. Example: GET https://example.com/ap/1.0/https%3A%2F%2Fexample.org%2Fwiki 6.2. Consumer Sets "Accept" Headers The consumer MUST NOT set the "Accept" header since the token format is dictated by the common denominator of authentication provider and service provider. Baer & Haberstumpf Expires November 16, 2015 [Page 11] Internet-Draft LTA 1.0 May 2015 The consumer CAN set an "Accept-Charset" header that has one of the following values: o UTF-8 o US-ASCII Tokens only contain only 7bit ASCII characters. See Section 6.4 for details. The consumer CAN set an "Accept-Language"" header. See [RFC2616] section 14.4 for more information. This only has an influence on the language of error messages issued by the authentication provider. Those error messages are used in response to illegal requests or other abnormal situations. Note that authentication providers are allowed to ignore this header and only provide English error messages. See Section 10.10 for details. 6.3. Authentication Provider Authenticates the Consumer The authentication provider checks the credentials provided by the consumer. 6.4. Creating a Token An authentication token is a credential issued by the authentication provider and used by the consumer to gain access to a service provider's services. The authentication token MUST only contain characters from the 7bit ASCII character set. This way maximum compatibility across different character sets is ensured. For example UTF-8 is compatible to 7bit ASCII. An authentication token created by the authentication provider MUST have the following format: token = token-payload " " signature The token payload is defined as follows: token-payload = lta-version " " service-specification " " expiration " " time-to-use The service specification identifies service and permissions: service-specification = service-identification-uri ( *( "|" service-permission-uri ) / "*" ) Baer & Haberstumpf Expires November 16, 2015 [Page 12] Internet-Draft LTA 1.0 May 2015 The signature is defined as follows: signature = signature-info "|" signature-container signature-info = ( hash-algorithm "|" encryption ) / container-format Note that the payload of the token and the signature meta-data are not encrypted since the consumer must be able to read the contents of the token but not to modify them. Refer to Section 6.5 for details. This is important because the consumer has to take the token expiration into account before trying to redeem a token at a service provider. It would cause unnecessary traffic if the consumer tried to redeem an expired token. The list of service permission URIs can be replaced by an asterisk "*" symbol in case no access restrictions below the service level are necessary. Examples for service specifications: https://example.org/blog|* https://example.org/blog|get|head blog.example.org editor|admin 6.4.1. The Token Format Explained There are restrictions that lead to the design of the token format. 1. The consumer MUST be able to copy the received token directly into an HTTP header without modifying it. Therefore only ASCII characters that are allowed as header fields values can be used. 2. The parts the token consists of MUST be separable by the most simple string manipulation. It is designed to be split at separator characters. 1. Since parts of the token are URIs, only characters that are not allowed in a URI are suitable as separators 2. The building blocks are split at the " " character 3. The permissions and signature parts are separated by "|" The reason why there are two kinds of separators is that we want to be able to vary the number of sub-items. Baer & Haberstumpf Expires November 16, 2015 [Page 13] Internet-Draft LTA 1.0 May 2015 6.4.2. Token Expiration The authentication provider MUST calculate an expiration date and time for each token. The expiration delay of a token MUST be configurable in the authentication provider per service provider URI. The expiration time in the token MUST be encoded as date and time according to the following pattern as specified in [RFC3339] section 5.6. expiration = year "-" month "-" day "T" hours ":" minutes ":" seconds "Z" year = 4DIGIT month = ( "0" DIGIT ) / 11 / 12 day = ( "0" / "1" / "2") DIGIT / 30 / 31 hours = ( ( "0" / "1") DIGIT ) / 21 / 22 / 23 minutes = ( "0" / "1" / "2" / "3" / "4" / "5") DIGIT seconds = ( "0" / "1" / "2" / "3" / "4" / "5") DIGIT All expiration timestamps MUST be encoded in Coordinated Universal Time (UTC). If the server is in a different time zone , the authentication provider MUST convert the time accordingly. time-to-use = 1*DIGIT The time to use (TTU) is the number of seconds the token should be used after it was issued. In simple implementations the time to use is equal to the time to live. In this case the TTU is redundant at first glance, but it is a concession to consumers that do not have proper clock synchronization. See Section 8.3 for details. In more sophisticated implementations the authentication provider chooses a TTU that is shorter than the difference between token issuing time and expiration time. See Section 11.1.3 for more information. Baer & Haberstumpf Expires November 16, 2015 [Page 14] Internet-Draft LTA 1.0 May 2015 6.5. Creating the token signature The authentication provider MUST sign the token payload using a hash algorithm and its private key. LTA supports exchanging the signing mechanism. It needs an asymmetric encryption in order to create a token signature. The authentication provider MUST state either the hash algorithm and encryption it uses to create in the token signature or a signature container format. This tells the service provider how to validate the signature. Refer to Section 10.8 for a list of supported algorithms. 7. Authentication Provider Answers Token Request Depending on whether or not the authentication provider was able to identify the consumer, the authentication provider either issues a token or tells the consumer that it could not be authenticated. 7.1. Token Request Granted The authentication provider must answer 200 (OK) if the consumer was authenticated successfully and if the user is authorized to use the requested service or services. In this case the response body contains the token. token-response-body = token The authentication provider MUST mark responses that contain an LTA token with MIME type "application/lta" in the "Content-Type" header. Example: HTTP/1.1 200 OK Date: Mon, 01 Jan 2015 14:21:16 GMT Content-Type: application/lta Content-Length: 451 1.0 org.example.wiki * 2015-01-01T14:21:46Z 25 sha-1|rsa|iQEcBA[...]c+s= The example above is shortened (marked by "[...]") for better readability. Baer & Haberstumpf Expires November 16, 2015 [Page 15] Internet-Draft LTA 1.0 May 2015 7.2. Token Request Denied Because of Missing Credentials The authentication provider MUST answer 401 (Unauthorized) if the consumer does not provide the required authentication header. 7.3. Token Request Denied Because of Invalid Credentials The authentication provider MUST answer 401 (Unauthorized) if the credentials the consumer provided are invalid. 8. Consumer Redeems Token The consumer sends a requests to the service provider and uses the token as credential. For this it MUST set the following HTTP header in the service request: auth-header = "Authorization:" SP "Token" token Note that the consumer does not necessarily need to understand the signature. It can rely on the authenticity of the sender when using HTTPS instead. This allows the consumer to work without needing to decode the signature. 8.1. Consumers Should Not Try to Use Expired Tokens Consumers SHOULD NOT try to use expired tokens. There are two alternative ways for the consumer to determine if a token is expired: 1. via the absolute expiration time - for a consumer with reliable time synchronization 2. via the time to use (TTU) - works without time synchronization 8.2. Expiration Time Properly time synchronized consumers should use the absolute expiration time from the token to determine if the token can still be used or if it already expired. 8.3. Time to Use The time to use (TTU) is a time span between issuing of the token and the time when it is recommended the consumer requests a new token. The TTU may be lower than the difference between issuing and expiration of a token See Section 11.1.3 for more information. Also consumers like mobile devices and embedded computers might not have proper time synchronization or might use the wrong time zone. Baer & Haberstumpf Expires November 16, 2015 [Page 16] Internet-Draft LTA 1.0 May 2015 Therefore using the TTU instead of the absolute expiration time is recommended on the consumer side. The downside of this mechanism is that a part of the TTU given in the token is already used up in the transmission from the authentication provider to the consumer. Since the consumer has no simple means to tell how long this delay is, it will consider the token valid longer than it actually is. The authentication provider CAN mitigate that problem by choosing reasonable safety margin between the expiration of a token and the TTU specified in the token. 9. Service Provider Validates and Authenticates Token Before the service provider offers its services, it validates and authenticates the token sent by the consumer. 9.1. Validating a token The service provider MUST validate the token format. If the token format does not conform to this document, the service provider MUST deny the request. 9.2. Checking if the Token Is Addressed to the Right Service Provider Since consumers might accidently or maliciously try to use an authentication token for the wrong service provider, a service provider MUST always check if a token is really addressed to it. The service provider MUST check if the service identification URI in the token matches the requested service. Note that the service identification URI is not necessarily the URI under which the service can be reached in a network. Authentication provider and service provider just have to agree on a common URI. 9.3. Checking the Signature The service provider checks the signature of the token to verify that it has been issued by the authentication provider and has not been modified. If the signature does not match the token payload, the service provider MUST deny the request. 9.4. Checking if the Token Expired The service provider compares the expiration date and time from the token to the current date and time. If the token's expiration time lies in the past, the service provider MUST deny the request. Baer & Haberstumpf Expires November 16, 2015 [Page 17] Internet-Draft LTA 1.0 May 2015 The service provider MUST always use the absolute expiration time from the token. The time-to-use is reserved for consumer use only and MUST be ignored by the service provider. The service provider MUST use clock synchronization (e.g. the "Network Time Protocol", see [RFC0958] ) that grants a synchronization quality of typically below one second. See Section 16.1.2 for security considerations of time synchronization. The service provider MUST take the time differences into account that result from the timezone the service provider is located in. Token expiration times inside the token are always given in UTC (see [RFC3339] ). Service providers MUST convert their local time to UTC before evaluating token expiry. Service providers MUST NOT accept tokens where the expiration time is more than two hours in the future. This is a safety measure in order to avoid long-term valid tokens issued by accident by the authentication provider. 10. Service Provider Answers the Request 10.1. Service access granted The service provider MUST answer 200 (OK) if the token was successfully validated and authenticated. The response body is the normal service response. 10.2. Access Denied due to Missing Authentication Token The service provider MUST answer 401 (Unauthorized) if the consumer does not provide the token in the authentication header. In addition the service provider must set the "WWW-Authenticate" header (see [RFC2617] section 1.2 ) as follows: challenge = "Token" 1*SP "realm" "=" DQOUTE service-identification-uri DQUOTE Example: WWW-Authenticate: Token realm="https://example.org/blog" 10.3. Access Denied Because of Illegal Token Format The service provider MUST answer 400 (Bad Request) if the token or parts of the token do not conform to this document. Baer & Haberstumpf Expires November 16, 2015 [Page 18] Internet-Draft LTA 1.0 May 2015 10.4. Access Denied Because of Signature Mismatch The service provider MUST answer 401 (Unauthorized) if the token signature and does not match the token payload. 10.5. Access Denied Because of Unsupported Signing Mechanism If the service provider does not understand the encryption algorithm or hash function used for signing the token it MUST answer 400 (Bad Request). The response MUST contain a header field listing the supported hash algorithms: accept-hash-header = "Accept-Token-Hashes:" SP hash *( "," SP hash) The response MUST contain a header field listing the supported ciphers: accept-cipher-header = "Accept-Token-Ciphers:" SP cipher *( "," SP cipher) Example: Accept-Token-Hashes: sha-1, sha-256 Accept-Token-Ciphers: rsa 10.6. Access Denied Because of Expired Token The service provider MUST answer 401 (Unauthorized) if the token expired. 10.7. Access Denied Because of Insufficient Permissions The service provider MUST answer 403 (Forbidden) if the rights specified in the token are not sufficient to execute the service request. 10.8. Supported Signing Mechanisms LTA is designed to support different token representations in order to be able to replace the signing mechanism when a more efficient or more secure algorithm is available. This document therefore contains only a very short list of supported hashes and cyphers. While requiring mandatory implementations is good for interoperability, it would be unwise to use mechanisms that are not cryptographically secure anymore. Baer & Haberstumpf Expires November 16, 2015 [Page 19] Internet-Draft LTA 1.0 May 2015 The hash function textual names are as defined in in the IANA registry. [IANA1] Examples: o sha-1 o sha-256 The textual names for encryptions follow the same style. Examples o rsa o ecc As long as AP and SP agree, they can use implementations not listed here. 10.9. Using a Signature container Signature container formats contain the signature plus the meta information on how to verify it and can be used as an alternative to encoding the hash function an encryption algorithm. While in principle any container format could be used, some technical restrictions apply: 1. The signature containers encoding must only contain characters allowed in an HTTP header field. 2. The container should be small because it otherwise conflicts with the goal of low network overhead. The benefit for using standard containers is that they often come with a full infrastructure for key distribution and revoking (both mechanisms outside of the scope of this document). 10.10. Error reporting in the response body When connecting to web services, it is useful to have clear error messages in case something went wrong. The following recommendations apply to both, the authentication provider and the service provider. The response body of a response with an "4xx" error code should contain a clear text description of the error cause. Baer & Haberstumpf Expires November 16, 2015 [Page 20] Internet-Draft LTA 1.0 May 2015 The error message SHOULD respect the language requested if an Accept- Language header was set in the request. At least English error messages SHOULD be supported. Unless specified explicitly, the error messages do not have to be machine readable. Error messages MUST NOT disclose confidential information to the consumer. Especially error messages MUST NOT contain information that helps an attacker to guess credentials. 11. Optimizations 11.1. Authentication Provider Optimizations 11.1.1. Authentication Provider Sets Cache Header of a Token The authentication provider MAY set the following cache header: cache-control = "cache-control:" SP "private," SP "max-age=" time-to-use The cache directive "private" tells all involved parties that caching is only supposed to happen in the consumer. Where the time to use in seconds is used as maximum cache age of the response. time-to-use = 1*DIGIT Example: cache-control: private, max-age=25 This is useful for consumers that do not implement their own consumer side token cache and rely on the caching their HTTP client library offers. Otherwise it is superfluous. 11.1.2. Token Cache on Authentication Provider Side If the same consumer requests a token with an unconditional "GET" before the old token's time-to-use is reached, the authentication provider SHOULD return the same token instead of creating a new one. For this the authentication provider needs a token cache that holds one not-expired token per consumer. Baer & Haberstumpf Expires November 16, 2015 [Page 21] Internet-Draft LTA 1.0 May 2015 If the same consumer requests a token with a conditional "GET" before the time to use is reached, the authentication provider SHOULD answer with 304 as specified in [RFC2616] section 10.3.5. On the one hand this optimization improves the behaviour of the "GET" requests for tokens. The authentication provider does not create new tokens while the old token is still valid - a desired feature for a get request. On the other hand this introduces a shared state between instances of the authentication provider making scalability more complicated. Implementors should decide on which argument is more important for their use cases. 11.1.3. Issuing a new Token Shortly Before the Existing Token Expires The authentication provider SHOULD introduce a configurable time span (TTU) that is smaller than the difference of token issuing time to expiration time. The TTU is used to determine when a new token must be issued. This helps to avoid situations where the consumer gets a token that is almost expired. 11.1.4. Token Representation Compatibility with Service Provider The applicable token formats are dictated by the common denominator between authentication provider and service provider. For each service the authentication provider SHOULD store and respect the token representations the service provider understands. 11.2. Service Provider Optimizations 11.2.1. Token Cache on Service Provider Side Service providers MAY cache the result of a token evaluation until the token expires, especially for services where a series of request can be expected during the life time of a token. Note that in a clustered service this would have to be centralized potentially introducing a new point of failure and requiring additional network communication. Therefore in clustered environments a node-local token cache is recommended in combination with consumer affinity (e.g. IP affinity). Baer & Haberstumpf Expires November 16, 2015 [Page 22] Internet-Draft LTA 1.0 May 2015 11.3. Consumer Optimizations 11.3.1. Caching the Token Request URIs The Consumer SHOULD cache the token request URIs listed by the authentication provider. This removes unnecessary subsequent discovery traffic. The recommended way is doing this is on application layer. If a token request fails, a consumer MUST invalidate its token request URI cache, because it is likely that either the URI or the consumers permissions changed. For security reasons the consumers MUST NOT cache the token request URIs indefinitely. The recommended caching time is a day. Example: An embedded device requests the token offer list and keeps the result cached in RAM until the next power cycle or day. 11.3.2. Using Tokens until They Expire Although it is possible that consumers request a token before each service request, this introduces unnecessary network traffic if the last token is not yet expired. The Consumer SHOULD reuse the token until the token expired. 12. Permission Handling 12.1. Service identification URIs A service identification URI (short "SIU") uniquely identifies a service. It MUST be agreed upon by both, the service provider and the authentication provider. If permissions on a sub-service level are necessary, then the service provider MUST define a service permission URI for each permission. 12.2. Choosing Service Identification URIs and Permission URIs It is not mandatory that service identification URIs or permission URIs are can be dereferenced. While it is easier to understand if the service identification URI is identical to the URI the service can be reached, it is not required. Baer & Haberstumpf Expires November 16, 2015 [Page 23] Internet-Draft LTA 1.0 May 2015 Note that the token - and therefore the SIUs are transmitted in the HTTP header. Although the HTTP specification does not define a size limit on the HTTP headers, in real-world scenarios the web servers use default limits between four and eight kilobytes. This fact and the goal that LTA should be resource-friendly both suggest that service providers define short URIs to identify services. Permission URIs should be relative to the service identification URI to save more space. Examples: 1. Sub-service level permissions for a restful HTTP service could be the request verbs "get", "put" or "delete". 2. For an accounting system permissions could be on artifact level "invoices", "cancellations" or "customers". 3. A service could also use roles instead of permissions "admin", "user" or "guest". 12.3. Permission URI wildcard If no sub-service level permissions are needed, the authentication provider should use the wildcard "*" instead of listing of all permissions. Example: A service provider defines dot-notation URIs for its services like "org.example.wiki". The service provider does not impose restrictions on the use of the service and marks this with the "*" wildcard. Internally it assembles the permission URI to "org.example.wiki.*"" and uses this for authorization checks. 12.4. Parameterized Permissions Imagine a user payed for a storing ten photos with a total size of not more than 20 MiB on a service. The service provider and the authentication provider agreed on a common scheme for representing this as a permission URI which looks like: store?max-items=10&max-size=20M Baer & Haberstumpf Expires November 16, 2015 [Page 24] Internet-Draft LTA 1.0 May 2015 It is a valid URI and it contains parameters. Given that the authentication provider knows how to build this URI and the service provider knows how to interpret it. 13. Examples 13.1. Token Requests Consumer: GET https://example.com/ap/https%3A%2F%2Fexample.org%2Fblog Authorization: Basic ZXhhbXBsZV91c2VyOmV4YW1wbGVfcGFzc3dvcmQ= [...] Authentication provider: HTTP/1.1 200 OK Date: Mon, 01 Jan 2015 14:21:16 GMT Content-Type: application/lta Content-Length: 451 1.0 https://example.org/blog|get|post|delete 2015-01-01T14:21:46Z 25 sha-1|rsa|iQEcBAABAgAGBQJT/yYfAAoJEBYE2BQYko+r47sH/jZNWgVpzoVXwfdFMVd FkZYG69qDnYNy3rfxw8HtYWa7x1VEngo9x79G+Bk5GhlG62rNpyZAFc63pi9/9eddZEO BBBwqWu7RA/h24DHfp0ngT0MO+H0zLldzTMSLCVkYYp+O3K5HlIqGhA9Rj32XKYBwjiM wPBoIYAcTzbUOb9kih0Ru3jGp/7+K/FbQPZHYK98znvKN/r81PqK0LM3KFpBi1SL+gpv IDm1sz/GjXGlAtBfMViHPcY6Vw6kjhpbuYEqPkOWty5gjhUntrrCyKpA069COR64bLqC eIM7++3E5rZvH1dIYZ86u629xNna5Tj+TJSkev7Jnlfw0YFoc+s= Note that the line breaks in the example HTTP body have been added for readability and are _not_ present in an actual token. 13.2. Service Request with LTA Token Consumer: GET https://example.org/blog/2015/01/01/img42.jpg Authorization: Token 1.0 https://example.org/blog|get|post|delete 2015-01-01T14:21:46Z 25 sha-1|rsa|iQEcBAABAgAGBQJT/yYfAAoJEBYE2BQYko+ r47sH/jZNWgVpzoVXwfdFMVdFkZYG69qDnYNy3rfxw8HtYWa7x1VEngo9x79G+Bk5Ghl G62rNpyZAFc63pi9/9eddZEOBBBwqWu7RA/h24DHfp0ngT0MO+H0zLldzTMSLCVkYYp+ O3K5HlIqGhA9Rj32XKYBwjiMwPBoIYAcTzbUOb9kih0Ru3jGp/7+K/FbQPZHYK98znvK N/r81PqK0LM3KFpBi1SL+gpvIDm1sz/GjXGlAtBfMViHPcY6Vw6kjhpbuYEqPkOWty5g jhUntrrCyKpA069COR64bLqCeIM7++3E5rZvH1dIYZ86u629xNna5Tj+TJSkev7Jnlfw 0YFoc+s= [...] Baer & Haberstumpf Expires November 16, 2015 [Page 25] Internet-Draft LTA 1.0 May 2015 Again the line breaks are for readability an do not exist in a real token. Service provider: HTTP/1.1 200 OK Date: Mon, 01 Jan 2015 14:21:17 GMT Content-Type: image/jpeg Content-Length: 513017 [...] 14. Acknowledgements This document's structure is based on a template by Elwyn Davies (initial version by Pekka Savola). We'd like to thank Peer Sterner for his thorough reviews of the early drafts. Thomas Fleischmann 15. IANA Considerations This document uses the existing IANA registry for "Hash Function Textual Names" in Section 10.8 which was introduced in [RFC4572] (see [IANA1] for a list of values) . This document defines a public key protocol value in Section 10.8 . Figure 1 contains the initial values. Public Key Algorithm Reference -------------------- --------- "rsa" RFC2313 Figure 1: IANA Public Key Algorithm Textual Name Registry The mime type "text/uri-map" was requested at the IANA in parallel to the submission of the LTA to the IETF. The mime type "application/lta" will be requested at the the IANA at the end of the review process for the LTA in order to be able to react on changes proposed by the reviewers. Baer & Haberstumpf Expires November 16, 2015 [Page 26] Internet-Draft LTA 1.0 May 2015 16. Security Considerations The following section lists possible attack vectors and mitigation strategies (if applicable). 16.1. Attack Vectors 16.1.1. Flooding of the Service Provider Since tokens described in this document are intentionally designed to be reused until they expire, they do not grant any protection against flooding of the service provider Tokens with a usage limit would either require the service provider to consult the authentication provider for each service request or require holding a connection state at the service providers. Service providers must implement their own flood protection mechanisms - independently of the LTA. 16.1.2. Time Synchronization Attack Depending on the expiry delay a few seconds difference in the token expiration between what the authentication provider specified and the expiry in the service provider are no problem. Whereas minutes or more would open a potential attack vector where outdated tokens could be used. Therefore proper time synchronization of the AP and SP is crucial. Attackers could try to fake the time source of either the AP or SP. Therefore both must make sure to use a secure and trusted time source. 16.1.3. Token Hijacking One of the goals of the LTA is to provide anonymization of the consumer towards the service provider. Since the service provider does not know the sender, it can not verify if the token belongs to the sender or was copied from another consumer. For this reason it is recommended to use LTA alone only for services that do not disclose personal or confidential data. If service designers plan to use LTA for such a service it is recommended that they use additional user authentication. Baer & Haberstumpf Expires November 16, 2015 [Page 27] Internet-Draft LTA 1.0 May 2015 16.1.4. Man-in-the-Middle If an attacker manages to intercept the communication between the SP and the AP, the attacker could try to impose an authentication provider towards the unknowing consumer. The consumer would then either disclose its credentials to the attacker or the attacker would intercept and abuse the issued token. In a different scenario the attacker could impose a service provider to collect tokens which it could redeem at the real service provider. Consumers need to verify the identity of both, authentication provider and service provider in order to prevent man-in-the-middle attack. 16.1.5. Replay Attacks If attackers are able to record a token during transmission, they can try to run a replay attack. Tokens that are not expired can be used in a replay attack. The first countermeasure is the mandatory use of TLS to prevent eavesdropping. If you are really concerned about replay attacks, the service provider may use the token cache to accept each token only once. The tradeoff is that this contradicts the design goal of keeping the number of requests to the authentication provider down. 16.1.6. Service Permission Information Leaking Since tokens contain service identification URIs, an attacker could try to get tokens to gather information about the services a consumer is using and the associated permissions. Consumers are responsible for protecting their token on the local machine and making sure they are addressing them at the authentic service provider. Losing a token has - at least for the time the token is valid - the same effect as losing other credentials like user name and password. 16.1.7. Addressing a Token to the Wrong Service Token based authentication without callback to the authentication provider from the service provider carries the risk of a malicious consumer trying to feed a token to the service provider that is a valid token addressed at a different service provider. See also Section 9.2 for more information. Baer & Haberstumpf Expires November 16, 2015 [Page 28] Internet-Draft LTA 1.0 May 2015 Therefore service providers must check the service identification URI in the token. 16.1.8. Using Token Request URIs That Are Not Valid Anymore If the consumer cached a token request URI which is not used anymore by an authentication provider and that URI belongs to a different domain there is the chance of an attacker to impose the authentication provider. For this the attacker would need to gain control over the domain, create a matching certificate and deploy what looks like the token granting part of the authentication provider. It is an unlikely scenario but theoretically possible. To mitigate the potential damage consumers SHOULD NOT cache token request URIs indefinitely. 16.1.9. Compromized Authentication Provider or Stolen AP Secrets If attackers successfully take over an authentication provider or copy the authentication providers secret, they can use this to create valid tokens. It is recommended to use a signing mechanism that supports the revocation of encryption keys so that at least after the attack was discovered, the compromised key can be rejected. 16.2. Anonymization Limitations A malicious service provider can collect and compare meta-data of a service request in order to break the anonymization. In the simplest case IP addresses already help narrowing down the consumer. More sophisticated methods include fingerprinting (e.g. by using additional HTTP headers or timing) If anonymity is an important requirement then consumers can only prevent metadata exploitation by adding additional anonymization measures (like using the TOR network). 17. References 17.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Baer & Haberstumpf Expires November 16, 2015 [Page 29] Internet-Draft LTA 1.0 May 2015 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. 17.2. Informative References [IANA1] IANA, "Textual names for hash functions", 2015, . [RFC0958] Mills, D., "Network Time Protocol (NTP)", RFC 958, September 1985. [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. [RFC4572] Lennox, J., "Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP)", RFC 4572, July 2006. [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. Authors' Addresses Sebastian Baer Elektrobit Am Wolfsmantel 46 Erlangen 91058 Germany Email: sebastian.baer@elektrobit.com Baer & Haberstumpf Expires November 16, 2015 [Page 30] Internet-Draft LTA 1.0 May 2015 Bernd Haberstumpf Elektrobit Am Wolfsmantel 46 Erlangen 91058 Germany Email: bernd.haberstumpf@elektrobit.com Baer & Haberstumpf Expires November 16, 2015 [Page 31]