Security Working Group B. Burke Internet-Draft Red Hat Intended status: Standards Track February 22, 2011 Expires: August 26, 2011 HTTP Header for digital signatures draft-burke-content-signature-00 Abstract This document describes the Content-Signature HTTP entity header. It is used to transmit one or more digital signatures comprised of metadata and the HTTP message body. 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 August 26, 2011. Copyright Notice Copyright (c) 2011 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 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. Burke Expires August 26, 2011 [Page 1] Internet-Draft Content-Signature February 2011 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 3. The Content-Signature Header Field . . . . . . . . . . . . . . 4 3.1. Attribute Descriptions . . . . . . . . . . . . . . . . . . 5 4. Creating and Verifying Signatures . . . . . . . . . . . . . . 6 5. OAuth Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6.1. Algorithm Registry . . . . . . . . . . . . . . . . . . . . 9 6.1.1. Registering New Algorithms . . . . . . . . . . . . . . 10 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 6.2. Attribute Registry . . . . . . . . . . . . . . . . . . . . 10 6.2.1. Registering New Attributes . . . . . . . . . . . . . . 10 6.3. Registration Approval Process . . . . . . . . . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 9.1. Normative References . . . . . . . . . . . . . . . . . . . 11 9.2. Informative References . . . . . . . . . . . . . . . . . . 12 Appendix A. An Appendix . . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 Burke Expires August 26, 2011 [Page 2] Internet-Draft Content-Signature February 2011 1. Introduction This document describes the Content-Signature HTTP entity header. This header is used to transmit one more more digital signatures which are composed by signing both the HTTP message body and an optional set of transmitted metadata about the signature. While the formats like multipart/signed already allow you to transmit digital signatures, it requires HTTP clients and servers to be able to understand and parse the format to get at the enclosed message body even if they have no interest in the digital signature. The multipart/signed format also does not really specify how the signature is composed and leaves it up to the sender. While this specification does not mandate the digital signature algorithm to use, it does describe what is signed, particularly how metadata and headers are combined with the message body before they are signed. In summary the goals and features of the Content-Signature header are: o Ability to transmit multiple digital signatures via an HTTP request or response entity header o Ability to transmit a set of standard and user-defined metadata about each signature and to include it as part of the signature signing and verification process o The receiver of the HTTP request or response should be able to ignore signature information. o Ability to include zero or more other HTTP headers within the calculation of the signature o Ability to include other attached signatures within the calculation of a particular signature This specification is not meant to replace OAuth or the HTTP Digest protocol. While those protocols are more interested in guaranteeing the integrity of a message between a specific interaction between a client and server, Content-Header is merely a way to attach one or more signatures to a representation. In other words, Content- Signature can be completely orthogonal to the authentication and authorization protocol of the HTTP request. 2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this Burke Expires August 26, 2011 [Page 3] Internet-Draft Content-Signature February 2011 document are to be interpreted as described in RFC 2119 [RFC2119]. This document uses the Augmented Backus-Naur Form (ABNF) notation of RFC2616 [RFC2616], and explicitly includes the following rules from it: quoted-string, token, SP (space), and HEX. 3. The Content-Signature Header Field The Content-Signature entity-header field provides a means for serializing one or more digital signatures and metadata associated with those signatures. The value of this header is a set of attributes which are name-value pairs delimited by the ";" character. Multiple values of Content-Signature are allowed if they are delimited by the "," character. Content-Signature = "Content-Signature" ":" #content-signature-value content-signature-value = signature *( ";" metadata) signature = "signature" "=" 1*HEX metadata = ( ("id" "=" (ptoken | quoted-string)) | ( "algorithm" "=" (ptoken | quoted-string)) | ( "values" "=" name-list) | ( "headers" "=" name-list) | ( "signature-refs" "=" name-list ) | ( "signer" "=" ( ptoken | quoted-string ) ) | ( "timestamp" "=" HTTP-date ) | ( "expiration" "=" HTTP-date ) | ( "nonce" "=" 1*DIGIT ) | ( other-metadata) ) other-metadata = ( paramname "=" ( ptoken | quoted-string ) ) name-list = paramname *( ":" paramname) paramname = 1*paramchar paramchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" | ")" | "*" | "+" | "-" | "." | "/" | DIGIT | "<" | "=" | ">" | "?" | "@" | ALPHA | "[" | "]" | "^" | "_" | "`" | "{" | "|" | "}" | "~" ptoken = 1*ptokenchar ptokenchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" | ")" | "*" | "+" | "-" | "." | "/" | DIGIT | ":" | "<" | "=" | ">" | "?" | "@" | ALPHA | "[" | "]" | "^" | "_" | "`" | "{" | "|" | "}" | "~" Burke Expires August 26, 2011 [Page 4] Internet-Draft Content-Signature February 2011 3.1. Attribute Descriptions Name: signature Required: yes Description: Hex encoded string of the binary value of the signature Name: id Required: no Description: Identifies an included signature. This is useful when there are more than one signature value included within the Content- Signature header. Applications can use this "id" attribute to find the signature they are interested in verifying. Name: algorithm Required: no Description: Specifies the algorithm used to calculate the signature. The algorithm registry (Section 6.1) specifies possible but not exhaustive list of values. Name: values Required: no Description: A ":" delimited list of parameter names. These parameter names correspond to attribute metadata values within the Content- Signature value. The values of these parameters are used when creating and verifying the signature. See Creating and Verifying Signature (Section 4) section for more details.> Name: headers Required: no Description: A ":" delimited list of header names. These names correspond to HTTP header values included in the HTTP request or response. The values of these headers are used when creating and verifying the signature. See Creating and Verifying Signatures (Section 4) section for more details.> Name: signature-refs Required: no Description: Burke Expires August 26, 2011 [Page 5] Internet-Draft Content-Signature February 2011 A ":" delimited list of signature ids. These names correspond to other signatures included in the Content-Signature header. The names reference the "id" attribute of each of these included signatures. The "signature" attribute value of each of these identified signatures are used when creating and verifying the signature. See Creating and Verifying Signatures (Section 4) section for more details.> Name: signer Required: no Description: This is the identity of the signer of the message. It allows the receiver to look up verification keys within an internal registry. It also allows applications to know who sent the message if identity cannot be determined by authentication protocols. Name: timestamp Required: no Description: The time and date the message was signed. This gives the receiver the option to refuse old signed messages. The format of this timestamp is the Date format described in RFC 2616 [RFC2616]. Name: expiration Required: no Description: The time and date the message should be expired. This gives the sender the option to set an expiration date on the message. The format of this timestamp is the Date format described in RFC 2616 [RFC2616]. Name: nonce Required: no Description: Random number to ensure old communications cannot be replayed. 4. Creating and Verifying Signatures Signatures are created by applying a digital signature algorithm to the contatenation a set of metadata with the body of the HTTP message. The order in which data is concatenated is very important Burke Expires August 26, 2011 [Page 6] Internet-Draft Content-Signature February 2011 as verifiers must know this in order to verify the signature when they receive it. This is the order that will be applied: values + headers + signature-refs + message-body The values and headers pertain to the Content-Signature metadata of a specific Content-Signature value.For example, if the signer decides to include the signer and expiration attributes, the Content-Type header, and a text/plain message of "hello world", the base for the signature would look like this: billSunday, 06-Nov-11 08:49:37 GMTtext/plainhello world The Content-Signature header transmitted would look like: Content-Signature: values=signer:expiration; headers=Content-Type; signer=bill; expiration="Sunday, 06-Nov-11 08:49:37 GMT"; signature=0f341265ffa32211333f6ab2d1 To verify a signature, the verifier would recreate the signature by concatenating the attributes specified in the "values" attribute, HTTP headers defined in "headers" attribute, the hex signature values pointed to by "signature-ref" attribute, and finally the message body. The array of bytes produced should by verified with the decoded value of the "signature" attribute. If there is an attribute declared within the "values" attribute that isn't specified in the Content-Signature header, it is assumed it is a secret held between the signer and verifier. If there is a header declared within the "headers" attribute that doesn't exist, the server may choose to abort if it cannot figure out how to reproduce this value. Here's an example of multiple signatures. Let's say the Content- Signature header is initially set up like this with a message body of "hello": Content-Signature: id=husband; signature=0A01, id=wife; signature=0F02 Here, we have two initial signatures signed by two different entities, husband and wife (found by their id attribute). We want to define a third signature, marriage, that includes those signatures. Burke Expires August 26, 2011 [Page 7] Internet-Draft Content-Signature February 2011 Content-Signature: id=husband; signature=0A01, id=wife; signature=0F02, id=marriage; signature-refs=husband:wife signature=0D0330 The marriage signature would be calculated by the signing of this array of bytes: 0A010F02hello Which is the husband's signature + wife's signature + message-body. If there is a signature reference declared within the signature-refs attribute that doesn't exist, the server may choose to abort if it cannot figure out how to reproduce this value. 5. OAuth Considerations While Content-Signature is only a means to attach signatures to a transmitted representation, it is possible to use it as an authentication and authorization mechanism on top of OAuth2 [I-D.ietf-oauth-v2]. An authorization token can be obtained using OAuth mechanisms and attached as metadata to transmitted Content- Signature values. This is different than the MAC [I-D.hammer-oauth-v2-mac-token] protocol in that since Content- Signature is an entity-header, it can travel through and be forwarded by transparent gateways. The representation, along with the Content- Signature can make multiple hops until it reaches the protected resource. The protected resource can trust the forwarded representation because it has the desired auth-token all signed by the original sender. An example of this is an application that listens to Twitter feed of a particular person. The application sends SMS messages on behalf of the individual to the individual's friends. The mobile provider bills the individual rather than the application. The signer is the individual. The transparent gateway is Twitter. The protected resource is the mobile provider. Firstly, the individual obtains an authorization token using OAuth from the mobile provider which gives the individual permission to forward messages. The application obtains an authorization token from the mobile provider which gives it permission to send SMS messages on behalf of authenticated and authorized individuals. The Burke Expires August 26, 2011 [Page 8] Internet-Draft Content-Signature February 2011 individual then posts a message to Twitter signing it including its authorization token. Content-Signature: signature=0A01; values=mobile-auth-code:signer:nonce mobile-auth-code=342a2f11; signer=bill; nonce=1 Twitter receives the messages and sends it to all the interested feeds. The application picks up the message from twitter. It adds an additional signature to the message that is comprised of its auth token, the individual's signature, and the message. Content-Signature: id=invidual; signature=0A01; values=mobile-auth-code:signer:nonce mobile-auth-code=342a2f11; signer=bill; nonce=1, id=forwarder; signature=0B02; values=mobile-forward-auth-code:signer; signature-refs=individual; mobile-forward-auth-code=4020FACE; signer=application The application then sends an SMS to each of the individual's friends attaching the signatures to each SMS message. An interesting thing to note here is that the application added additional metadata to the individual's signature, specifically the "id" attribute. Labeling each signature allows the mobile provider to sort out which signatures are which. Finally, the mobile provider looks at each message to the individual's and application's signatures. If approved it bills the individual, if not it bills the provider. Granted this example is a bit contrived, but hopefully you get the picture. 6. IANA Considerations 6.1. Algorithm Registry This specification establishes the digital signature algorithm registry which is a list of algorithm names that can be used as values for the "algorithm" attribute of Content-Signature. Burke Expires August 26, 2011 [Page 9] Internet-Draft Content-Signature February 2011 6.1.1. Registering New Algorithms (FYI: I copied this section from Link header draft) Algorithms are registered on the advice of (TBD)... Registration requests consist of the completed registration template below, typically published in an RFC or Open Standard (in the sense described by [RFC2026], Section 7). However, to allow for the allocation of values prior to publication, the Designated Expert may approve registration once they are satisfied that a specification will be published. The registration template is: o Algorithm Name: o Description: o Reference: o Notes: [optional] o Application Data: [optional] Registration requests should be sent to the [TBD]@ietf.org mailing list, marked clearly in the subject line (e.g,. "NEW DIGITAL SIGNATURE ALGORITHM REQUEST"). 6.1.2. Initial Registry Contents TBD 6.2. Attribute Registry This specification establishes the Content-Signature attribute registry which is a list of attribute names that can be included as metadata within a Content-Signature. 6.2.1. Registering New Attributes (FYI: I copied this section from Link header draft) Algorithms are registered on the advice of (TBD)... Registration requests consist of the completed registration template below, typically published in an RFC or Open Standard (in the sense described by [RFC2026], Section 7). However, to allow for the allocation of values prior to publication, the Designated Expert may approve registration once they are satisfied that a specification Burke Expires August 26, 2011 [Page 10] Internet-Draft Content-Signature February 2011 will be published. The registration template is: o Attribute Name: o Description: o Reference: o Notes: [optional] o Application Data: [optional] Registration requests should be sent to the [TBD]@ietf.org mailing list, marked clearly in the subject line (e.g,. "NEW DIGITAL SIGNATURE ALGORITHM REQUEST"). 6.3. Registration Approval Process (FYI: Stole this from Link header draft) Within at most 14 days of registration request, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. Decisions (or lack thereof) made by the Designated Expert can be first appealed to Application Area Directors (contactable using app-ads@tools.ietf.org email address or directly by looking up their email addresses on http://www.iesg.org/ website) and, if the appellant is not satisfied with the response, to the full IESG (using the iesg@iesg.org mailing list). 7. Security Considerations TBD 8. Acknowledgements 9. References 9.1. Normative References [I-D.hammer-oauth-v2-mac-token] Hammer-Lahav, E., "HTTP Authentication: MAC Burke Expires August 26, 2011 [Page 11] Internet-Draft Content-Signature February 2011 Authentication", draft-hammer-oauth-v2-mac-token-02 (work in progress), January 2011. [I-D.ietf-oauth-v2] Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2.0 Authorization Protocol", draft-ietf-oauth-v2-12 (work in progress), January 2011. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [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. 9.2. Informative References [InfRef] "", 2004. Appendix A. An Appendix Author's Address Bill Burke Red Hat Email: bburke@redhat.com URI: http://bill.burkecentral.com Burke Expires August 26, 2011 [Page 12]