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]