idnits 2.17.1 draft-burke-content-signature-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (February 22, 2011) is 4805 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC2026' is mentioned on line 443, but not defined == Unused Reference: 'InfRef' is defined on line 508, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-hammer-oauth-v2-mac-token-02 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-12 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Security Working Group B. Burke 3 Internet-Draft Red Hat 4 Intended status: Standards Track February 22, 2011 5 Expires: August 26, 2011 7 HTTP Header for digital signatures 8 draft-burke-content-signature-00 10 Abstract 12 This document describes the Content-Signature HTTP entity header. It 13 is used to transmit one or more digital signatures comprised of 14 metadata and the HTTP message body. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on August 26, 2011. 33 Copyright Notice 35 Copyright (c) 2011 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 52 3. The Content-Signature Header Field . . . . . . . . . . . . . . 4 53 3.1. Attribute Descriptions . . . . . . . . . . . . . . . . . . 5 54 4. Creating and Verifying Signatures . . . . . . . . . . . . . . 6 55 5. OAuth Considerations . . . . . . . . . . . . . . . . . . . . . 8 56 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 57 6.1. Algorithm Registry . . . . . . . . . . . . . . . . . . . . 9 58 6.1.1. Registering New Algorithms . . . . . . . . . . . . . . 10 59 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 60 6.2. Attribute Registry . . . . . . . . . . . . . . . . . . . . 10 61 6.2.1. Registering New Attributes . . . . . . . . . . . . . . 10 62 6.3. Registration Approval Process . . . . . . . . . . . . . . 11 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 64 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 65 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 9.1. Normative References . . . . . . . . . . . . . . . . . . . 11 67 9.2. Informative References . . . . . . . . . . . . . . . . . . 12 68 Appendix A. An Appendix . . . . . . . . . . . . . . . . . . . . . 12 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 71 1. Introduction 73 This document describes the Content-Signature HTTP entity header. 74 This header is used to transmit one more more digital signatures 75 which are composed by signing both the HTTP message body and an 76 optional set of transmitted metadata about the signature. While the 77 formats like multipart/signed already allow you to transmit digital 78 signatures, it requires HTTP clients and servers to be able to 79 understand and parse the format to get at the enclosed message body 80 even if they have no interest in the digital signature. The 81 multipart/signed format also does not really specify how the 82 signature is composed and leaves it up to the sender. While this 83 specification does not mandate the digital signature algorithm to 84 use, it does describe what is signed, particularly how metadata and 85 headers are combined with the message body before they are signed. 87 In summary the goals and features of the Content-Signature header 88 are: 90 o Ability to transmit multiple digital signatures via an HTTP 91 request or response entity header 93 o Ability to transmit a set of standard and user-defined metadata 94 about each signature and to include it as part of the signature 95 signing and verification process 97 o The receiver of the HTTP request or response should be able to 98 ignore signature information. 100 o Ability to include zero or more other HTTP headers within the 101 calculation of the signature 103 o Ability to include other attached signatures within the 104 calculation of a particular signature 106 This specification is not meant to replace OAuth or the HTTP Digest 107 protocol. While those protocols are more interested in guaranteeing 108 the integrity of a message between a specific interaction between a 109 client and server, Content-Header is merely a way to attach one or 110 more signatures to a representation. In other words, Content- 111 Signature can be completely orthogonal to the authentication and 112 authorization protocol of the HTTP request. 114 2. Notational Conventions 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 118 document are to be interpreted as described in RFC 2119 [RFC2119]. 120 This document uses the Augmented Backus-Naur Form (ABNF) notation of 121 RFC2616 [RFC2616], and explicitly includes the following rules from 122 it: quoted-string, token, SP (space), and HEX. 124 3. The Content-Signature Header Field 126 The Content-Signature entity-header field provides a means for 127 serializing one or more digital signatures and metadata associated 128 with those signatures. The value of this header is a set of 129 attributes which are name-value pairs delimited by the ";" character. 130 Multiple values of Content-Signature are allowed if they are 131 delimited by the "," character. 133 Content-Signature = "Content-Signature" ":" #content-signature-value 134 content-signature-value = signature *( ";" metadata) 135 signature = "signature" "=" 1*HEX 136 metadata = ( ("id" "=" (ptoken | quoted-string)) 137 | ( "algorithm" "=" (ptoken | quoted-string)) 138 | ( "values" "=" name-list) 139 | ( "headers" "=" name-list) 140 | ( "signature-refs" "=" name-list ) 141 | ( "signer" "=" ( ptoken | quoted-string ) ) 142 | ( "timestamp" "=" HTTP-date ) 143 | ( "expiration" "=" HTTP-date ) 144 | ( "nonce" "=" 1*DIGIT ) 145 | ( other-metadata) ) 146 other-metadata = ( paramname "=" ( ptoken | quoted-string ) ) 147 name-list = paramname *( ":" paramname) 148 paramname = 1*paramchar 149 paramchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" 150 | ")" | "*" | "+" | "-" | "." | "/" | DIGIT 151 | "<" | "=" | ">" | "?" | "@" | ALPHA 152 | "[" | "]" | "^" | "_" | "`" | "{" | "|" 153 | "}" | "~" 154 ptoken = 1*ptokenchar 155 ptokenchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" 156 | ")" | "*" | "+" | "-" | "." | "/" | DIGIT 157 | ":" | "<" | "=" | ">" | "?" | "@" | ALPHA 158 | "[" | "]" | "^" | "_" | "`" | "{" | "|" 159 | "}" | "~" 161 3.1. Attribute Descriptions 163 Name: signature 164 Required: yes 165 Description: 167 Hex encoded string of the binary value of the signature 169 Name: id 170 Required: no 171 Description: 173 Identifies an included signature. This is useful when there 174 are more than one signature value included within the Content- 175 Signature header. Applications can use this "id" attribute to 176 find the signature they are interested in verifying. 178 Name: algorithm 179 Required: no 180 Description: 182 Specifies the algorithm used to calculate the signature. The 183 algorithm registry (Section 6.1) specifies possible but not 184 exhaustive list of values. 186 Name: values 187 Required: no 188 Description: 190 A ":" delimited list of parameter names. These parameter names 191 correspond to attribute metadata values within the Content- 192 Signature value. The values of these parameters are used when 193 creating and verifying the signature. See Creating and 194 Verifying Signature (Section 4) section for more details.> 196 Name: headers 197 Required: no 198 Description: 200 A ":" delimited list of header names. These names correspond 201 to HTTP header values included in the HTTP request or response. 202 The values of these headers are used when creating and 203 verifying the signature. See Creating and Verifying Signatures 204 (Section 4) section for more details.> 206 Name: signature-refs 207 Required: no 208 Description: 210 A ":" delimited list of signature ids. These names correspond 211 to other signatures included in the Content-Signature header. 212 The names reference the "id" attribute of each of these 213 included signatures. The "signature" attribute value of each 214 of these identified signatures are used when creating and 215 verifying the signature. See Creating and Verifying Signatures 216 (Section 4) section for more details.> 218 Name: signer 219 Required: no 220 Description: 222 This is the identity of the signer of the message. It allows 223 the receiver to look up verification keys within an internal 224 registry. It also allows applications to know who sent the 225 message if identity cannot be determined by authentication 226 protocols. 228 Name: timestamp 229 Required: no 230 Description: 232 The time and date the message was signed. This gives the 233 receiver the option to refuse old signed messages. The format 234 of this timestamp is the Date format described in RFC 2616 235 [RFC2616]. 237 Name: expiration 238 Required: no 239 Description: 241 The time and date the message should be expired. This gives 242 the sender the option to set an expiration date on the message. 243 The format of this timestamp is the Date format described in 244 RFC 2616 [RFC2616]. 246 Name: nonce 247 Required: no 248 Description: 250 Random number to ensure old communications cannot be replayed. 252 4. Creating and Verifying Signatures 254 Signatures are created by applying a digital signature algorithm to 255 the contatenation a set of metadata with the body of the HTTP 256 message. The order in which data is concatenated is very important 257 as verifiers must know this in order to verify the signature when 258 they receive it. This is the order that will be applied: 260 values + headers + signature-refs + message-body 262 The values and headers pertain to the Content-Signature metadata of a 263 specific Content-Signature value.For example, if the signer decides 264 to include the signer and expiration attributes, the Content-Type 265 header, and a text/plain message of "hello world", the base for the 266 signature would look like this: 268 billSunday, 06-Nov-11 08:49:37 GMTtext/plainhello world 270 The Content-Signature header transmitted would look like: 272 Content-Signature: values=signer:expiration; 273 headers=Content-Type; 274 signer=bill; 275 expiration="Sunday, 06-Nov-11 08:49:37 GMT"; 276 signature=0f341265ffa32211333f6ab2d1 278 To verify a signature, the verifier would recreate the signature by 279 concatenating the attributes specified in the "values" attribute, 280 HTTP headers defined in "headers" attribute, the hex signature values 281 pointed to by "signature-ref" attribute, and finally the message 282 body. The array of bytes produced should by verified with the 283 decoded value of the "signature" attribute. 285 If there is an attribute declared within the "values" attribute that 286 isn't specified in the Content-Signature header, it is assumed it is 287 a secret held between the signer and verifier. If there is a header 288 declared within the "headers" attribute that doesn't exist, the 289 server may choose to abort if it cannot figure out how to reproduce 290 this value. 292 Here's an example of multiple signatures. Let's say the Content- 293 Signature header is initially set up like this with a message body of 294 "hello": 296 Content-Signature: id=husband; 297 signature=0A01, 298 id=wife; 299 signature=0F02 301 Here, we have two initial signatures signed by two different 302 entities, husband and wife (found by their id attribute). We want to 303 define a third signature, marriage, that includes those signatures. 305 Content-Signature: id=husband; 306 signature=0A01, 307 id=wife; 308 signature=0F02, 309 id=marriage; 310 signature-refs=husband:wife 311 signature=0D0330 313 The marriage signature would be calculated by the signing of this 314 array of bytes: 316 0A010F02hello 318 Which is the husband's signature + wife's signature + message-body. 320 If there is a signature reference declared within the signature-refs 321 attribute that doesn't exist, the server may choose to abort if it 322 cannot figure out how to reproduce this value. 324 5. OAuth Considerations 326 While Content-Signature is only a means to attach signatures to a 327 transmitted representation, it is possible to use it as an 328 authentication and authorization mechanism on top of OAuth2 329 [I-D.ietf-oauth-v2]. An authorization token can be obtained using 330 OAuth mechanisms and attached as metadata to transmitted Content- 331 Signature values. This is different than the MAC 332 [I-D.hammer-oauth-v2-mac-token] protocol in that since Content- 333 Signature is an entity-header, it can travel through and be forwarded 334 by transparent gateways. The representation, along with the Content- 335 Signature can make multiple hops until it reaches the protected 336 resource. The protected resource can trust the forwarded 337 representation because it has the desired auth-token all signed by 338 the original sender. 340 An example of this is an application that listens to Twitter feed of 341 a particular person. The application sends SMS messages on behalf of 342 the individual to the individual's friends. The mobile provider 343 bills the individual rather than the application. The signer is the 344 individual. The transparent gateway is Twitter. The protected 345 resource is the mobile provider. 347 Firstly, the individual obtains an authorization token using OAuth 348 from the mobile provider which gives the individual permission to 349 forward messages. The application obtains an authorization token 350 from the mobile provider which gives it permission to send SMS 351 messages on behalf of authenticated and authorized individuals. The 352 individual then posts a message to Twitter signing it including its 353 authorization token. 355 Content-Signature: signature=0A01; 356 values=mobile-auth-code:signer:nonce 357 mobile-auth-code=342a2f11; 358 signer=bill; 359 nonce=1 361 Twitter receives the messages and sends it to all the interested 362 feeds. The application picks up the message from twitter. It adds 363 an additional signature to the message that is comprised of its auth 364 token, the individual's signature, and the message. 365 Content-Signature: id=invidual; 366 signature=0A01; 367 values=mobile-auth-code:signer:nonce 368 mobile-auth-code=342a2f11; 369 signer=bill; 370 nonce=1, 371 id=forwarder; 372 signature=0B02; 373 values=mobile-forward-auth-code:signer; 374 signature-refs=individual; 375 mobile-forward-auth-code=4020FACE; 376 signer=application 378 The application then sends an SMS to each of the individual's friends 379 attaching the signatures to each SMS message. An interesting thing 380 to note here is that the application added additional metadata to the 381 individual's signature, specifically the "id" attribute. Labeling 382 each signature allows the mobile provider to sort out which 383 signatures are which. Finally, the mobile provider looks at each 384 message to the individual's and application's signatures. If 385 approved it bills the individual, if not it bills the provider. 387 Granted this example is a bit contrived, but hopefully you get the 388 picture. 390 6. IANA Considerations 392 6.1. Algorithm Registry 394 This specification establishes the digital signature algorithm 395 registry which is a list of algorithm names that can be used as 396 values for the "algorithm" attribute of Content-Signature. 398 6.1.1. Registering New Algorithms 400 (FYI: I copied this section from Link header draft) Algorithms are 401 registered on the advice of (TBD)... 403 Registration requests consist of the completed registration template 404 below, typically published in an RFC or Open Standard (in the sense 405 described by [RFC2026], Section 7). However, to allow for the 406 allocation of values prior to publication, the Designated Expert may 407 approve registration once they are satisfied that a specification 408 will be published. 410 The registration template is: 412 o Algorithm Name: 414 o Description: 416 o Reference: 418 o Notes: [optional] 420 o Application Data: [optional] 422 Registration requests should be sent to the [TBD]@ietf.org mailing 423 list, marked clearly in the subject line (e.g,. "NEW DIGITAL 424 SIGNATURE ALGORITHM REQUEST"). 426 6.1.2. Initial Registry Contents 428 TBD 430 6.2. Attribute Registry 432 This specification establishes the Content-Signature attribute 433 registry which is a list of attribute names that can be included as 434 metadata within a Content-Signature. 436 6.2.1. Registering New Attributes 438 (FYI: I copied this section from Link header draft) Algorithms are 439 registered on the advice of (TBD)... 441 Registration requests consist of the completed registration template 442 below, typically published in an RFC or Open Standard (in the sense 443 described by [RFC2026], Section 7). However, to allow for the 444 allocation of values prior to publication, the Designated Expert may 445 approve registration once they are satisfied that a specification 446 will be published. 448 The registration template is: 450 o Attribute Name: 452 o Description: 454 o Reference: 456 o Notes: [optional] 458 o Application Data: [optional] 460 Registration requests should be sent to the [TBD]@ietf.org mailing 461 list, marked clearly in the subject line (e.g,. "NEW DIGITAL 462 SIGNATURE ALGORITHM REQUEST"). 464 6.3. Registration Approval Process 466 (FYI: Stole this from Link header draft) Within at most 14 days of 467 registration request, the Designated Expert(s) will either approve or 468 deny the registration request, communicating this decision to the 469 review list. Denials should include an explanation and, if 470 applicable, suggestions as to how to make the request successful. 472 Decisions (or lack thereof) made by the Designated Expert can be 473 first appealed to Application Area Directors (contactable using 474 app-ads@tools.ietf.org email address or directly by looking up their 475 email addresses on http://www.iesg.org/ website) and, if the 476 appellant is not satisfied with the response, to the full IESG (using 477 the iesg@iesg.org mailing list). 479 7. Security Considerations 481 TBD 483 8. Acknowledgements 485 9. References 487 9.1. Normative References 489 [I-D.hammer-oauth-v2-mac-token] 490 Hammer-Lahav, E., "HTTP Authentication: MAC 491 Authentication", draft-hammer-oauth-v2-mac-token-02 (work 492 in progress), January 2011. 494 [I-D.ietf-oauth-v2] 495 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 496 2.0 Authorization Protocol", draft-ietf-oauth-v2-12 (work 497 in progress), January 2011. 499 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 500 Requirement Levels", BCP 14, RFC 2119, March 1997. 502 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 503 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 504 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 506 9.2. Informative References 508 [InfRef] "", 2004. 510 Appendix A. An Appendix 512 Author's Address 514 Bill Burke 515 Red Hat 517 Email: bburke@redhat.com 518 URI: http://bill.burkecentral.com