idnits 2.17.1 draft-abiggs-saag-key-management-service-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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([I-D.barnes-pervasive-problem]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (November 17, 2014) is 3441 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: 'JWK' is mentioned on line 788, but not defined == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-algorithms-33 == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-encryption-33 == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-key-33 == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-signature-33 ** Obsolete normative reference: RFC 2822 (Obsoleted by RFC 5322) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) == Outdated reference: A later version (-06) exists of draft-ietf-xmpp-posh-02 == Outdated reference: A later version (-09) exists of draft-newton-json-content-rules-02 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 8 errors (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Biggs 3 Internet-Draft S. Cooley 4 Intended status: Standards Track Cisco Systems 5 Expires: May 21, 2015 November 17, 2014 7 Key Management Service Architecture 8 draft-abiggs-saag-key-management-service-00 10 Abstract 12 In the interest of addressing pervasive threats to the 13 confidentiality and integrity of online communications identified by 14 the Internet community [I-D.barnes-pervasive-problem] this 15 specification introduces an open architecture for the establishment, 16 management, and secure distribution of cryptographic keys for use in 17 the end-to-end (E2E) encryption of online communications and shared 18 content. This architecture allows for the independent deployment of 19 dedicated key management services in a manner that supports the 20 adoption of third-party communications and data sharing services by 21 individuals and organizations that require full and exclusive 22 discretion over the confidentiality of their data. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on May 21, 2015. 41 Copyright Notice 43 Copyright (c) 2014 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.2. Security Terms . . . . . . . . . . . . . . . . . . . . . 5 61 1.3. Notational Conventions . . . . . . . . . . . . . . . . . 5 62 2. Architectural Overview . . . . . . . . . . . . . . . . . . . 6 63 3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 3.1. Securing an HTTP File Sharing Service . . . . . . . . . . 9 65 3.2. Securing an XMPP Multi-User Chat . . . . . . . . . . . . 10 66 3.3. KMS to KMS Key Federation . . . . . . . . . . . . . . . . 12 67 4. KMS Protocol . . . . . . . . . . . . . . . . . . . . . . . . 14 68 4.1. Secure Channel . . . . . . . . . . . . . . . . . . . . . 15 69 4.2. User Identity . . . . . . . . . . . . . . . . . . . . . . 16 70 4.3. KMS Identity . . . . . . . . . . . . . . . . . . . . . . 16 71 4.4. Object Types . . . . . . . . . . . . . . . . . . . . . . 17 72 4.4.1. KMS Key Objects . . . . . . . . . . . . . . . . . . . 17 73 4.4.2. KMS Authorization Objects . . . . . . . . . . . . . . 19 74 4.4.3. KMS Resource Objects (KRO) . . . . . . . . . . . . . 20 75 4.5. Request Types . . . . . . . . . . . . . . . . . . . . . . 21 76 4.6. Message Structure . . . . . . . . . . . . . . . . . . . . 22 77 4.6.1. Basic Request Payload . . . . . . . . . . . . . . . . 22 78 4.6.2. Basic Response Payload . . . . . . . . . . . . . . . 24 79 4.6.3. Error Response Payload . . . . . . . . . . . . . . . 25 80 4.7. Requests . . . . . . . . . . . . . . . . . . . . . . . . 25 81 4.7.1. Create Ephemeral Key . . . . . . . . . . . . . . . . 25 82 4.7.2. Delete Ephemeral Key . . . . . . . . . . . . . . . . 28 83 4.7.3. Create Resource . . . . . . . . . . . . . . . . . . . 29 84 4.7.4. Create Unbound Keys . . . . . . . . . . . . . . . . . 32 85 4.7.5. Update Unbound Key (Bind) . . . . . . . . . . . . . . 35 86 4.7.6. Retrieve Keys . . . . . . . . . . . . . . . . . . . . 37 87 4.7.7. Create Authorizations . . . . . . . . . . . . . . . . 41 88 4.7.8. Delete Authorization . . . . . . . . . . . . . . . . 43 89 5. Mandatory-to-Implement . . . . . . . . . . . . . . . . . . . 44 90 6. Security Considerations . . . . . . . . . . . . . . . . . . . 45 91 7. Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . 45 92 8. Appendix B. Document History . . . . . . . . . . . . . . . . 45 93 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 94 9.1. Normative References . . . . . . . . . . . . . . . . . . 46 95 9.2. Informative References . . . . . . . . . . . . . . . . . 47 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 98 1. Introduction 100 Providers of cloud-based services commonly secure user data at the 101 transport level using established protocols such as TLS [RFC5246] or 102 IPSec [RFC4301]. These protocols can be effective in protecting 103 transmitted user data from third party tampering and eavesdropping; 104 however, by themselves these protocols do not secure user data from 105 abuses, negligence, or coerced behavior on the part of the cloud 106 provider. This is a concern for individuals and organizations that 107 wish to take advantage of cloud-based communications and 108 collaboration but cannot accept the risk of trusting cloud providers 109 with unfettered access to the contents of their communications. 111 E2E encryption describes a category of solutions that can be employed 112 to address this problem by establishing secure channels among 113 clients. To the extent that a user can trust their collaboration 114 client software, E2E encryption mitigates exposure of user data to 115 untrusted parties by ensuring that intermediaries never possess 116 unencrypted user data or have access to the keying material necessary 117 to decrypt it. 119 Existing E2E strategies such as ECS [RFC5652], PGP [RFC4880], and 120 Off-the-Record Messaging [OTR] can be effective at securing two-party 121 communications. However, E2E encryption for the growing domain of 122 multiparty communications and online content sharing remains a 123 generally unsolved problem to which these existing approaches do not 124 readily adapt. In particular, a core challenge exists in providing 125 for the secure distribution and rotation of E2E encryption keys among 126 an arbitrary and potentially dynamic set of communicating clients. 127 In cases where the communications to be secured are persistent or 128 archived, the additional challenge exists for providing trusted long- 129 term storage and retrieval of these keys. 131 Equally problematic is the paucity of E2E encryption options that 132 satisfy common organizational obligations such as regulatory 133 compliance and legal discovery. Entities that must operate within 134 such frameworks require mechanisms by which they (and they alone) may 135 recover the keys used to secure their communications. Existing E2E 136 encryption solutions are not, by themselves, well suited for this 137 purpose. 139 In the interest of addressing these challenges this document presents 140 an architecture for the deployment of E2E encryption key management 141 services (KMS). In this architecture a KMS service provides to its 142 users a means by which their communications clients may securely 143 create, share, rotate, and store E2E encryption keying material. It 144 does so in a fashion that permits the decoupling of such services 145 from the communications media, thereby permitting the former to 146 reside under the direct control of the communicating parties or the 147 organizations within which they do business. 149 1.1. Terminology 151 This document uses the terminology from 152 [I-D.ietf-jose-json-web-signature], 153 [I-D.ietf-jose-json-web-encryption], [I-D.ietf-jose-json-web-key], 154 and [I-D.ietf-jose-json-web-algorithms] when discussing JOSE 155 technologies. 157 This document makes use of the following terminology, and 158 additionally adopts nomenclature defined in 159 [I-D.barnes-pervasive-problem] for the purpose of describing aspects 160 of pervasive attacks. 162 communications resource 164 A communications resource is any uniquely identifiable continuous 165 data channel or discrete shared content that represents an 166 exchange of personal communications between two or more users. 168 communications resource client 170 A communications resource client consumes communications resources 171 on behalf of a user and, when deployed in conformance with the KMS 172 architecture, consumes the services of KMS server(s) to facilitate 173 the E2E encryption of those communications resources. 175 communications resource server 177 A communications resource server is a provider of services through 178 which communications resources are made available. 180 cloud provider 182 An individual or organization responsible for, and in control of, 183 one or more communications resource servers. 185 E2E encryption 187 Shorthand for end-to-end encryption, as defined in [RFC4949], 188 particularly as it applies to the establishment of confidentiality 189 and integrity of communications resources. 191 KMS server 192 A key management server (KMS) is responsible for creating, 193 storing, and providing access to E2E encryption keying material by 194 communications resource clients. 196 KMS protocol 198 The protocol through which communications resource clients 199 interoperate with KMS servers. 201 KMS provider 203 An individual or organization responsible for, and in control of, 204 a KMS server deployment. 206 KMS transport 208 Any service or protocol that provides the basic transport over 209 which KMS protocol messages are exchanged. 211 resource client 213 See communications resource client. 215 resource server 217 See communications resource server. 219 trusted party 221 A trusted party is an individual or organization that is trusted 222 by one or more communicating users to maintain the confidentiality 223 and integrity of their communications resources. 225 1.2. Security Terms 227 Most security-related terms in this document are to be understood in 228 the sense defined in [RFC4949]; such terms include, but are not 229 limited to, "attack", "authentication", "authorization", 230 "certification authority", "certification path", "certificate", 231 "credential", "identity", "self-signed certificate", "trust", "trust 232 anchor", "trust chain", "validate", and "verify". 234 1.3. Notational Conventions 236 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 237 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 238 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 239 [RFC2119]. 241 2. Architectural Overview 243 The architectural reference model for this specification is 244 illustrated in Figure 1. Central to this model is the 245 _communications resource server_ which is presumed to be operated by 246 a _cloud provider_ for the purpose of offering some form of 247 communications service. The nature of this service is not prescribed 248 by this specification and may take the form of any of a variety of 249 communications or collaboration services including file sharing, 250 messaging, and VoIP. Consuming the services of the communications 251 resource server are _communications resource clients_ which may be 252 supplied by the cloud provider or developed by third parties. 254 +-----------------+ 255 | Communications | 256 +-------------------| Resource Server |-------------------+ 257 | | (Cloud Provider)| | 258 | +-----------------+ | 259 | | 260 | | 261 | +-----------------+ | 262 | +-----------| KMS Transport |-----------+ | 263 | | +-----------------+ | | 264 | | | | | 265 | | Untrusted | | | 266 - - -|- - - -|- - - - - - - - - - | - - - - - - - - - -|- - - -|- - - 267 | | Trusted | | | 268 | | | | | 269 +-----------------+ +-----------------+ +-----------------+ 270 | Communications | | KMS Server | | Communications | 271 | Resource Client | | (KMS Provider) | | Resource Client | 272 +-----------------+ +-----------------+ +-----------------+ 273 | | 274 +-----------------+ +-----------------+ 275 | Alice | | Bob | 276 +-----------------+ +-----------------+ 278 Figure 1: KMS Architecture Reference Model 280 In addition to the familiar elements described above, this model also 281 includes a key management server, or _KMS_, operated by a _KMS 282 provider_. The KMS server exposes an API through which clients may 283 securely establish and share cryptographic keying material used for 284 the E2E encryption of content that is transited through the cloud 285 provider's services. This API is secured in such a way as to ensure 286 these keys are visible to none but the KMS server itself and the 287 clients authorized to consume the content they protect. This 288 highlights an important distinction between the KMS provider and the 289 cloud provider: while the KMS provider is necessarily a _trusted 290 party_, the cloud provider need not be. 292 It is an explicit objective of this specification to promote an 293 ecosystem of providers of KMS implementations and KMS services that 294 are distinct and independent of the cloud providers over whose 295 services users communicate. To that end, this specification seeks to 296 standardize a KMS service protocol though which clients and KMS 297 servers interoperate. This protocol provides for the establishment 298 of a confidential and authenticated channel between each client and 299 KMS server, and defines an API of request and response messages to be 300 exchanged over this secure channel for the purpose of creating, 301 retrieving, and exchanging keys. 303 While the KMS service protocol constitutes a central focus of this 304 specification, the means by which this protocol is transported is 305 expressly out of scope. This role may be readily addressed through 306 either standards-based or proprietary protocols, and so we refer to 307 this simply as the _KMS transport_ for the remainder of this 308 document. Over this transport, the communication paths between 309 clients and KMS server are encrypted using keys established through 310 an authenticated ephemeral key agreement. As such, the KMS transport 311 provider need not be regarded as a trusted party, and in fact may be 312 the cloud provider itself. 314 An important non-goal of this specification is the standardization of 315 any aspect of the cloud provider's services or the means by which 316 clients utilize shared keys for the E2E encryption of data transiting 317 those services. By avoiding the application of constraints on the 318 communications services and protocols we enable the use of this 319 specification in the context of existing service deployments, both 320 standards-based and proprietary. It is similarly a non-goal of this 321 specification to enable federation of secure communications between 322 vendors of different cloud services, as that is the realm of 323 standardized application protocols. The scope of this specification 324 is intended to be narrowly focused on the task of separating E2E 325 encryption key management from the communications services they 326 secure, thereby facilitating the broadest possible adoption of secure 327 communications though existing services. 329 3. Use Cases 331 The use cases described in this section are non-normative examples 332 meant to illustrate how the KMS architecture may be deployed to 333 provide E2E encryption of different types of communications 334 resources. These use cases differ in detail, but generally follow a 335 common logical sequence as given below. 337 Note that all requests to the KMS server are via the KMS transport 338 which, for clarity, has been omitted from the sequence diagrams 339 included in this section. 341 Resource Resource Resource KMS 342 Client B Client A Server Server 343 | | | | 344 | | | (1) | 345 | |-----------------|---------------->| 346 | | (2) | | 347 | |---------------->| | 348 | | | (3) | 349 | |-----------------|---------------->| 350 | | (4) | | 351 |-----------------|---------------->| | 352 | | | | 353 (5) | | | | 354 | | | (6) | 355 |-----------------|-----------------|---------------->| 356 | | | | 357 (7) | | | | 358 | | | | 360 Figure 2: Nominal Use Case 362 1. Client A requests the generation of a new unbound key from the 363 KMS. 365 2. Client A encrypts a communications resource using the unbound KMS 366 key and shares it via a resource server. 368 3. Client A requests the creation of a new KMS resource object (KRO) 369 to represent the communications resource. Client A also 370 instructs the KMS to bind the KMS key used in step (2) to the new 371 KRO and to authorize user B to retrieve keys bound to the KRO. 373 4. Client B accesses the communications resource shared by client A 374 and receives the encrypted data. 376 5. Client B obtains, through some means not defined by this 377 specification, the URL of the KMS key used to encrypt the 378 communications resource. 380 6. Client B requests the KMS key from the KMS server. The KMS 381 server, recognizing user B as authorized on the KRO to which the 382 key is bound, returns the KMS key. 384 7. Client B decrypts the communications resource using the KMS key. 386 3.1. Securing an HTTP File Sharing Service 388 Let A be a user that wishes to share a file with users B and C 389 through some HTTP based file sharing service. In the context of the 390 KMS architecture we may regard the file sharing provider's HTTP API 391 as the resource server and the users' HTTP clients as the resource 392 clients. 394 For this scenario we also assume that the file sharing service is 395 trusted by user A with the role of providing a file sharing service 396 but is not necessarily trusted to adequately protect the 397 confidentiality of the file contents. User A's concerns may then be 398 addressed through the introduction of an HTTP based KMS transport 399 (not shown) and KMS server deployed by an entity that A regards as a 400 trusted party. 402 HTTP HTTP HTTP HTTP File KMS 403 Client C Client B Client A Share Server Server 404 | | | | | 405 | | | | (1) | 406 | | |--------------|------------>| 407 | | | (2) | | 408 | | |------------->| | 409 | (3) | (3) | | | 410 |<-------------|<-------------|--------------| | 411 | | | | (4) | 412 | | |--------------|------------>| 413 | | | (5) | | 414 | |--------------|------------->| | 415 | | | | (6) | 416 | |--------------|--------------|------------>| 417 | | | | | 418 | (7) | | | | 419 | | | | | 420 (8) | | | | | 421 | | | | | 423 Figure 3: File Sharing Use Case 425 This sequence begins with the assumption that each client has, at 426 some point, already established a secure channel to the KMS via 427 authenticated key agreement. 429 1. Client A requests from the KMS some number of unbound KMS keys. 431 2. Client A selects an unbound key from the set of keys obtained 432 step (1), encrypts the file to be shared, and posts the encrypted 433 content to the file sharing service. The file sharing service 434 responds with a URL that uniquely identifies the shared file. 436 3. Clients B and C learn of the newly shared file from the file 437 sharing service (the mechanism by which this occurs is out of 438 scope for this specification). 440 4. Client A requests the creation of a KMS resource object (KRO) on 441 the KMS to represent the shared file. In this message the client 442 also requests that the key from step (2) be bound to the newly 443 created KRO and that the users of clients B and C be authorized 444 to retrieve keys bound to the KRO. 446 5. Client B retrieves the shared file from the file sharing service. 448 6. Client B requests from the KMS all keys bound to the KRO 449 associated with the shared file's URL. Recognizing client B as 450 authorized on the KRO, the KMS returns the key bound to the KRO 451 by client A in step (4). 453 7. Client B decrypts the shared file using the key obtained in step 454 (6). 456 8. Client C performs steps (5) through (7) in the same fashion as 457 client B. 459 It is worth noting that a race condition does exist where step (6) 460 could occur before step (4) completes. This will result in a client 461 being temporarily denied access to the key used to encrypt the shared 462 file. 464 3.2. Securing an XMPP Multi-User Chat 466 Let A, B and C be users that wish to engage in secure chat through an 467 existing XMPP multi-user chat room. In the context of the KMS 468 architecture we may regard the XMPP MUC service as the resource 469 server, the users' XMPP clients as the resource clients, and the XMPP 470 service itself (not shown) as the KMS transport. 472 XMPP XMPP XMPP XMPP MUC KMS 473 Client C Client B Client A Server Server 474 | | | | | 475 | | | | (1) | 476 | | |--------------|------------>| 477 | | | | (2) | 478 | | |--------------|------------>| 479 | | | (3) | | 480 | | |------------->| | 481 | (4) | (4) | | | 482 |<-------------|<-------------|--------------| | 483 | | | | (5) | 484 | |--------------|--------------|------------>| 485 | | | | | 486 | (6) | | | | 487 | | | | | 488 (7) | | | | | 490 Figure 4: Multi-User Chat Use Case 492 This sequence begins with the assumption that a MUC room already 493 exists on the MUC server and that each client has already established 494 a secure channel to the KMS via authenticated key agreement. All 495 messages are transmitted over XMPP. 497 1. Client A requests from the KMS some number of unbound KMS keys. 498 Client A selects one of these keys for encrypting MUC room 499 messages. 501 2. Client A requests the creation of a KMS resource object (KRO) on 502 the KMS to represent the MUC room. In this message the client 503 also requests that the key selected in step (1) be bound to the 504 newly created KRO and that the users of clients B and C be 505 authorized to retrieve keys bound to the KRO. 507 3. Client A encrypts a message with the key selected in step (1) and 508 sends it to the MUC room. 510 4. The MUC service delivers client A's encrypted message to clients 511 B and C. 513 5. Client B requests from the KMS all keys bound to the KRO 514 associated with the MUC room's URI. Recognizing client B as 515 authorized on the KRO, the KMS returns the key bound to the KRO 516 by client A in step (2). 518 6. Client B decrypts the shared file using the key selected in step 519 (1). 521 7. Client C performs steps (5) and (6) in the same fashion as client 522 B. 524 3.3. KMS to KMS Key Federation 526 This use case illustrates two KMS instances federating keys 527 associated with a resource. As KMS servers are deployed to serve 528 groups of users it is inevitable that users will want to share 529 resources across groups or organizations. This cross-organization 530 sharing of keys leads to several problems. First, each user is only 531 known to and only knows of one logical KMS. Second, each 532 organization might have very different archiving requirements due to 533 differing legal compliance regulations due to jurisdiction or 534 industry differences. Lastly, one or both of the users might be 535 employees of enterprises that need to be able to respond to legal 536 discovery requests. To address these issues, KMS servers may 537 federate in such a way as to allow for limited copying of keys from 538 one KMS to another. This permits each KMS' owning organization the 539 ability to control the ongoing policy regarding access to keys for 540 which their respective users are authorized. 542 Let Alice@DomainA and Bob@DomainB be users of a common file sharing 543 service and who happen to use different KMS servers to secure their 544 communications. Assume then that Alice wishes to share a file with 545 Bob and therefore relies on KMS server federation to facilitate the 546 key exchange. 548 HTTP Client HTTP Client HTTP File KMS Server KMS Server 549 Bob@DomainB Alice@DomainA Share Server DomainA DomainB 550 | | | (1) | | 551 | |--------------|------------->| | 552 | | (2) | | | 553 | |------------->| | | 554 | (3) | | | | 555 |<-------------|--------------| | | 556 | | | (4) | | 557 | |--------------|------------->| | 558 | | (5) | | | 559 |--------------|------------->| | | 560 | | | | (6) | 561 |--------------|--------------|--------------|------------>| 562 | | | | (7) | 563 | | | |<------------| 564 | | | | (8) | 565 | | | |<------------| 566 | | | | | 567 | | | | | (9) 568 | | | | | 569 (10) | | | | | 570 | | | | | 572 Figure 5: File Sharing with KMS Federation Use Case 574 This sequence begins with the assumption that each client has, at 575 some point, already established a secure channel to their respective 576 KMS via authenticated key agreement. 578 1. Alice@DomainA requests from the DomainA KMS some number of 579 unbound KMS keys. Each KMS key is uniquely identified by a URL. 581 2. Alice@DomainA selects a key from the set of KMS keys obtained in 582 step (1), uses that key to encrypt the file to be shared, and 583 posts the encrypted content to the file sharing service. The 584 file sharing service responds with a URL that uniquely 585 identifies the shared file. 587 3. Bob@DomainB is notified of the newly shared file URL and 588 corresponding KMS key URL through a notification from the file 589 sharing service (or potentially some other means, such an an 590 email from Alice). 592 4. Alice@DomainA requests the creation of a KMS resource object 593 (KRO) on the DomainA KMS to represent the shared file. In this 594 message Alice also requests that the KMS key from step (2) be 595 bound to the newly created KRO and that the user Bob@DomainB be 596 authorized to retrieve KMS keys bound to the KRO. 598 5. Bob@DomainB retrieves the shared file from the file sharing 599 service. 601 6. Using the KMS key URL obtained in step (3), Bob@DomainB requests 602 the KMS key from the DomainB KMS. 604 7. The DomainB KMS recognizes the KMS key URL as actually hosted by 605 the DomainA KMS. The DomainB KMS establishes a secure and 606 mutually authenticated channel with the DomainA KMS via the KMS 607 transport. 609 8. The DomainB KMS requests from the DomainA KMS the KRO object to 610 which the KMS key is bound, along with all DomainB user 611 authorizations and other KMS keys that have been bound to that 612 KRO. The DomainA KMS recognizes that the DomainB KMS is 613 authorized to retrieve all KMS keys for which users in the 614 DomainB domain have been authorized. It then recognizes that at 615 least one DomainB user (Bob) has been authorized on the KRO 616 created in step (4). The DomainA KMS therefore decides the 617 DomainB KMS is authorized to make this request and returns the 618 requested information. 620 9. Using the information received from the DomainA KMS, the DomainB 621 KMS verifies that Bob@DomainB is authorized on the KRO, and 622 satisfies the request from step (6) by returning the KMS key to 623 Bob@DomainB. 625 10. Client Bob@DomainB decrypts the shared file using the key 626 obtained in step (9). 628 Note that in step (9) the DomainB KMS is enforcing authorization 629 policy for the KRO hosted on the DomainA KMS as it pertains to 630 DomainB users. This is a necessary consequence of KMS federation, 631 where the act of authorizing access to a KRO by a user residing in a 632 federated domain engenders an implicit trust of the KMS server that 633 controls the federated domain. For that reason, a KMS provider 634 should restrict federation of its KMS servers to domains that the KMS 635 provider regards as trusted. 637 4. KMS Protocol 639 The KMS protocol is composed of a message oriented request and 640 response API and a secure channel over which those messages are 641 exchanged. The API provides clients with the ability to generate E2E 642 encryption keys, associate those keys with communications resources, 643 and explicitly manage access authorizations on those keys. The 644 secure channel provides a mutually authenticated and E2E encrypted 645 channel over which the clients and KMS server may exchange API 646 messages securely. The API and secure channel are described in 647 detail through the remainder of this section. 649 4.1. Secure Channel 651 The secure channel is an encrypted and mutually authenticated 652 communication path between each client and the KMS server. It 653 transits the KMS transport which, in the context of this document, 654 represents any service or protocol that may be utilized for the 655 relaying of KMS API request and response messages. This 656 specification presumes the KMS transport to be untrusted. 658 (3) Secure Channel 659 +===================================================+ 660 V V 661 +-----------------+ (2) +---------------+ (1) +---------------+ 662 | Resource Client |<------>| KMS Transport |<------>| KMS Server | 663 +-----------------+ +---------------+ +---------------+ 664 | | 665 Trusted | Untrusted | Trusted 667 Figure 6: Establishment of a Secure Channel 669 At a high level, the communication path between a resource client and 670 KMS is established as follows. 672 1. The KMS actively connects to the KMS transport. The protocol 673 used for this connection is out of scope for this document, 674 however it MUST support the asynchronous flow of encrypted KMS 675 request and response messages between the KMS and KMS transport. 677 2. A resource client connects to the KMS transport. The protocol 678 used for this connection is out of scope for this document, 679 however it MUST support the flow of encrypted KMS request and 680 response messages between the resource client and the KMS 681 transport. 683 3. Through an elliptic curve Diffie-Helman key exchange, augmented 684 by server and client authentication, the resource client and KMS 685 establish a shared secret and derived ephemeral key. This is 686 discussed in greater detail in Section 4.7.1. 688 On successful mutual authentication and ephemeral key agreement, the 689 resource client and KMS communicate through the exchange of sequenced 690 request and response messages encrypted using the ephemeral key. 692 4.2. User Identity 694 Central to the KMS server's role as a key store is its ability to 695 restrict access to stored keying material to only authorized users. 696 This requires robust user authentication and a means for the 697 unambiguous and unique identification of each user. 699 Conforming KMS architecture deployments MUST rely on an identity 700 provider that supports the generation of OAuth 2.0 [RFC6749] access 701 tokens. The KMS server MUST rely on same identity provider for the 702 purpose of validating access tokens received from the client. Access 703 tokens used by clients to demonstrate identity and authorization for 704 access to KMS resources MUST NOT be used for any other service. Any 705 exposure of a KMS recognized access token to third parties (such as 706 providers of other services) jeopardizes the security of all KMS keys 707 for which the user whose identity is represented by the token is 708 authorized. 710 The identity provider on which the KMS server relies MAY be the same 711 identity provider as relied upon by the resource server(s) whose 712 communications resources are encrypted with keys managed by the KMS 713 server. Note, however, the reliable authentication and authorization 714 of clients to the KMS server is critical to the security of the KMS 715 keys it holds. The identity provider on which the KMS relies must 716 therefore necessarily be regarded as a trusted party within the 717 context of the KMS architecture. 719 Access tokens MUST be conveyed to the KMS server as part of the 720 payload of encrypted KMS API requests as described in Section 4.6.1 721 and MUST NOT be conveyed in any other manner. 723 4.3. KMS Identity 725 Given the untrusted nature of the KMS transport by both the KMS and 726 clients, it is critical for clients to be able to verify the identity 727 of their KMS and ensure that no MITM attacks are carried out on 728 client to KMS or KMS to client communications. Therefore, the KMS 729 MUST make use of at least one PKIX certificate [RFC5280] and clients 730 MUST validate the PKIX certificate presented by the KMS through the 731 comparison of the certificate's common name (CN) or subject 732 alternative name (SAN) [RFC6125] fields to the Internet domain 733 portion of the user's Addr-spec [RFC2822] formatted unique identifier 734 using the procedures defined in section 6 of [RFC6125]. An 735 acceptable alternative to direct CN or SAN validation is defined in 736 [I-D.ietf-xmpp-posh]. 738 PKIX certificates presented by the KMS can be issued by either a 739 public or private certification authority with the stipulation that 740 clients MUST be able to validate the KMS's entire certificate path 741 through the pre-established trust of the root certificate used to 742 anchor the certificate path. The mechanism for establishing trust of 743 the root certificate is out of scope for this specification, but it 744 is usually carried out through pre-installed trusted root 745 certificates on various operating systems for public certification 746 authorities or through enterprise endpoint management solutions or 747 manual installation tasks for private certification authorities. 749 4.4. Object Types 751 The KMS protocol defines three object types: resources, keys, and 752 authorizations. It is through the creation and manipulation of 753 instances of these object types that clients interact with the KMS. 755 Resource 757 A resource is an object that represents, within the KMS object 758 model, a communications resource as defined in Section 1.1. Keys 759 and user authorizations are associated (bound) to the resource 760 object as a means of representing their logical association with 761 that communications resource. 763 Key 765 A key is an object representing symmetric keying material 766 generated and made available to authorized clients by the KMS. A 767 key may exist in one of two states: "bound", and "unbound". An 768 unbound key is not associated with any resource, whereas a bound 769 key is associated with exactly one resource. 771 Authorization 773 An authorization is the association of a user with a particular 774 resource. When such an association exists between a user and a 775 resource this implies that the user is entitled to retrieve any 776 key that is bound to that resource, and to add or remove 777 authorizations for other users on the same resource. 779 The KMS protocol is composed from representations of these 780 fundamental object types. These representations are defined in the 781 following sections. 783 4.4.1. KMS Key Objects 785 The JSON representations for KMS key objects is defined as follows 786 using JSON content rules [I-D.newton-json-content-rules]. 788 jwk : ; see [JWK] 790 kmsUri ( 791 "uri" : uri relative 792 ) 794 keyRep { 795 kmsUri, 796 "jwk" : jwk, 797 "userId" : string, 798 "clientId" : string, 799 "createDate" : date-time, 800 "expirationDate" : date-time, 801 ?"resourceUri" : kmsUri, 802 ?"bindDate" : date-time 803 } 805 key ( 806 "key" : keyRep 807 ) 809 keys ( 810 "keys" : [ *keyRep ] 811 ) 813 keyUris ( 814 "keyUris" : [ *kmsUri ] 815 ) 817 The attributes of a KMS key object are defined as follows. 819 uri 821 A standard definition for KMS object identifiers. 823 jwk 825 Symmetric keying material represented as a JWK object (see 826 [I-D.ietf-jose-json-web-key]). 828 userId 830 The authenticated unique identifier of the user that created the 831 key. 833 clientId 834 An opaque unique identifier provided by the client that created 835 the key. 837 createDate 839 The point in time when the key was created, in RFC-3339 date-time 840 format. 842 expirationDate 844 The point in time after which the key may no longer be bound (if 845 unbound) or may no longer be used for encrypting data (if bound or 846 an ephemeral key). 848 resourceUri 850 The uri of the KMS resource object to which the key is bound. 852 bindDate 854 The point in time when the key was bound, in RFC-3339 date-time 855 format. 857 4.4.2. KMS Authorization Objects 859 The JSON representations for KMS authorization objects is defined as 860 follows using JSON content rules with references to rules defined in 861 previous sections. 863 authorizationRep { 864 kmsUri, 865 "userId" : string, 866 "resourceUri" : kmsUri, 867 } 869 authorization ( 870 "authorization" : authorizationRep 871 ) 873 authorizations ( 874 "authorizations" : [ *authorizationRep ] 875 ) 877 authorizationUris ( 878 "authorizationUris" : [ *kmsUri ] 879 ) 881 The attributes of a KMS authorization object are defined as follows. 883 uri 885 A standard definition for KMS object identifiers. 887 userId 889 The unique identifier of the user that is authorized. 891 resourceUri 893 The object identifier of the resource to which the authorization 894 applies. 896 Note, with respect to this specification user identifiers are opaque, 897 however they MUST map to unique identifiers provided as part of user 898 authentication. 900 4.4.3. KMS Resource Objects (KRO) 902 The JSON representation for KMS resource objects is defined as 903 follows using JSON content rules with references to rules defined in 904 previous sections. 906 resourceRep { 907 kmsUri, 908 keys / keyUris, 909 authorizations / authorizationUris 910 } 912 resource ( 913 "resource" : resourceRep 914 ) 916 resources ( 917 "resources" : [ *resourceRep ] 918 ) 920 resourceUris ( 921 "resourceUris" : [ *kmsUri ] 922 ) 924 The attributes of a KMS resource object are defined as follows. 926 uri 928 A standard definition for KMS object identifiers. 930 keys 931 An array of key object representations, one for each key bound to 932 the resource. 934 keyUris 936 An array of key object identifiers, one for each key bound to the 937 resource. Only one of either keys or keyUris may be present in a 938 resource object representation. 940 authorizations 942 An array of authorization object representations, one for each 943 authorization on the resource. 945 authorizationUris 947 An array of authorization object identifiers, one for each 948 authorization on the resource. Only one of either authorizations 949 or authorizationUris may be present in a resource object 950 representation. 952 4.5. Request Types 954 The KMS protocol defines four types of requests: create, retrieve, 955 update, delete, each of which may be applied to one of the three KMS 956 object types. Note that not all object types support all requests 957 types. A KMS need only support those combinations of request type 958 and object type explicitly defined in this document. 960 Create 962 A create operation acts upon an object type, creating one or more 963 new instances of that object type. 965 Retrieve 967 A retrieve operation acts upon an object or object type, returning 968 in the response a representation of one or more object instances. 970 Update 972 An update operation acts upon an object, altering mutable 973 properties of that object. 975 Delete 977 A delete operation acts upon an object, removing that object from 978 the KMS. 980 4.6. Message Structure 982 Every KMS request and response message is composed of a JSON 983 [RFC7159] formatted payload encapsulated within either a JWE 984 [I-D.ietf-jose-json-web-encryption] or JWS 985 [I-D.ietf-jose-json-web-signature] object. These messages may be 986 divided into three types. 988 Common Messages 990 Common messages include all those which do not meet the definition 991 of either key agreement message or error message. Common messages 992 are encrypted as JWE objects using the shared ephemeral key 993 established during initial key agreement between the client and 994 KMS (see Section 4.7.1). The value of the JWE header "kid" 995 attribute of a common message MUST match that of the KMS ephemeral 996 key object URI attribute established during initial key agreement. 998 Ephemeral Key Agreement Messages 1000 Ephemeral key agreement messages are those exchanged between the 1001 client and KMS for the purpose of establishing a new shared 1002 ephemeral key (see Section 4.7.1). Key agreement request payloads 1003 are encrypted as JWE objects using the authenticated and validated 1004 static public key of the KMS. Key agreement response payloads are 1005 signed as JWS objects using the static private key of the KMS. 1007 Error Messages 1009 Error messages are those originated by the KMS to indicate a 1010 failed request. Error messages are composed in the same fashion 1011 as common messages; however, in the event that the KMS does not 1012 recognize the ephemeral key used in the request, or that key is 1013 determined to have expired, the KMS MUST respond with an 1014 unencrypted message composed as a JWS, with a payload as described 1015 in Section 4.6.3, and signed using the KMS server's static public 1016 key. 1018 The basic JSON representations for the request and response payloads 1019 are defined in the following sections. 1021 4.6.1. Basic Request Payload 1023 The basic JSON representation for KMS request message payloads is 1024 defined as follows using JSON content rules with references to rules 1025 defined in previous sections. 1027 sequence ( 1028 "sequence" : integer 1029 ) 1031 credential { 1032 "userId": string 1033 "bearer": string / "jwk": jwk 1034 } 1036 client { 1037 "clientId": string, 1038 "credential": credential 1039 ) 1041 method: string /create|retrieve|update|delete/ 1043 request ( 1044 "client" : client, 1045 "method" : method, 1046 kmsUri, 1047 sequence 1048 ) 1050 The attributes of a KMS request message payload are defined as 1051 follows. 1053 sequence 1055 An integer selected by the client and provided in a monotonically 1056 increasing order with each request, beginning with the initial 1057 create ephemeral key request. 1059 userId 1061 The unique identifier of the user making the request. 1063 bearer 1065 An [RFC6749] access token issued by the client's identity provider 1066 and validated by the KMS in cooperation with the identity 1067 provider. See Section 4.2. 1069 jwk 1071 A JWK object, in JSON format as defined in 1072 [I-D.ietf-jose-json-web-key], containing the public key of the 1073 client (presumably a server). This JWK MUST contain an x5c header 1074 with a certificate chain that may be used to positively validate 1075 the public key. 1077 clientId 1079 An opaque unique identifier provided by the client (not used for 1080 authentication, only to assist multiple clients of a single user 1081 in differentiating between their respective unbound keys). 1083 method 1085 Indicates the request type: create, retrieve, update, or delete. 1087 uri 1089 The KMS object or object type to which the request applies. 1091 The JSON content rules above are used in conjunction with additional 1092 request type specific rules, defined later in this document, to 1093 produce the full request payload definition for each KMS operation. 1095 4.6.2. Basic Response Payload 1097 The basic JSON representation for KMS request message payloads is 1098 defined as follows using JSON content rules with references to rules 1099 defined in previous sections. 1101 response ( 1102 "status" : integer, 1103 ?"reason" : string 1104 sequence 1105 ) 1107 The attributes of a KMS request message payload are defined as 1108 follows. 1110 status 1112 Indicates the success or failure of the request. The value 1113 returned in a response status attribute SHOULD be that of an 1114 [RFC7231] defined status code with semantics that correspond to 1115 the success or failure condition of the KMS request. 1117 reason 1119 An optional natural language string to describe the response 1120 status in terms that are useful for tracing and troubleshooting 1121 the API. 1123 sequence 1125 An echo of the sequence number provided in the request. 1127 The JSON content rules above are used in conjunction with additional 1128 response type specific rules, defined later in this document, to 1129 produce the full response payload definition for each KMS operation. 1131 4.6.3. Error Response Payload 1133 The JSON representation for KMS error response message payloads is 1134 defined as follows using JSON content rules with references to rules 1135 defined in previous sections. 1137 Error response payload definition: 1139 root { 1140 response 1141 } 1143 Error response message example: 1145 JWS(K_kms_priv, { 1146 "status": 403, 1147 "reason": "The ephemeral key used in the request has expired.", 1148 "sequence": 7 1149 }) 1151 4.7. Requests 1153 The following sections provide detailed descriptions for each of the 1154 request and response operations that may occur between a resource 1155 client and the KMS. 1157 4.7.1. Create Ephemeral Key 1159 The first operation between a client and KMS MUST be the 1160 establishment of a shared secret and derived ephemeral key. This is 1161 necessary as all other requests and responses are encrypted with the 1162 ephemeral key. 1164 The client request for creating an ephemeral key conforms to the 1165 basic request message payload, where the method is "create" and the 1166 uri is "/ecdhe". In addition to the basic payload, the client 1167 provides a jwk attribute for which the value is a JWK object 1168 [I-D.ietf-jose-json-web-key] containing the public part of an EC key 1169 pair generated by the client. Unlike a basic request message, 1170 however, the request payload is encrypted as the content of a JWE 1172 [I-D.ietf-jose-json-web-key] secured with the static public key of 1173 the KMS server (K_kms_pub) as obtained from the server's validated 1174 PKIX certificate [RFC5280]. 1176 Note, the client MUST generate a new EC key pair for every create 1177 ephemeral key request sent to the KMS server. 1179 Request payload definition: 1181 root { 1182 request, 1183 jwk 1184 } 1186 Request message example: 1188 JWE(K_kms_pub, { 1189 "client": { 1190 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1191 "credential": { 1192 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1193 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1194 } 1195 }, 1196 "method": "create", 1197 "uri": "/ecdhe", 1198 "sequence": 0, 1199 "jwk" : { 1200 "kty": "EC", 1201 "crv": "P-256", 1202 "x": "VoFkf6Wk5kDQ1ob6csBmiMPHU8jALwdtaap35Fsj20M", 1203 "y": "XymwN6u2PmsKbIPy5iij6qZ-mIyej5dvZWB_75lnRgQ" 1204 } 1205 }) 1207 On receiving the ephemeral key creation request, the KMS server MUST 1208 verify the credential provided in the request. If a bearer token is 1209 provided, the KMS MUST validate the token in cooperation with the 1210 identity provider. If a jwk is provided, the KMS MUST validate the 1211 included PKIX certificate chain against the KMS server's trust root. 1212 In either case, the identity of the requesting client MUST be 1213 authenticated and verified to correspond to either an authorized user 1214 of the KMS or an authorized trusted service. If verification fails, 1215 the KMS MUST NOT use the server response to continue with key 1216 agreement. 1218 Upon successful authentication and authorization of the request, the 1219 KMS responds by generating its own EC key pair using the same curve 1220 as indicated in the "crv" attribute of the request message JWK. The 1221 KMS server returns the public part of this key pair to the resource 1222 client in the form of a KMS key object within the response payload. 1223 The KMS also generates and includes within the response payload a 1224 universally unique identifier to be regarded by both client and KMS 1225 as the key identifier of the agreed upon ephemeral key. The response 1226 payload is returned to the resource client as the content of a JWS 1227 [I-D.ietf-jose-json-web-signature] signed using the static private 1228 key of the KMS server (K_kms_priv). 1230 Response payload definition: 1232 root { 1233 response, 1234 key 1235 } 1237 Response message example: 1239 JWS(K_kms_priv, { 1240 "status": 201, 1241 "sequence": 0, 1242 "key": { 1243 "uri": "/ecdhe/ea9f3858-1240-4328-ae22-a15f6072306f", 1244 "jwk" : { 1245 "kty": "EC", 1246 "crv": "P-256", 1247 "x": "8mdasnEZac2LWxMwKExikKU5LLacLQlcOt7A6n1ZGUC", 1248 "y": "lxs7ln5LtZUE_GE7yzc6BZOwBxtOftdsr8HVh-14ksS" 1249 }, 1250 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1251 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1252 "createDate": "2014-10-09T15:54:48Z", 1253 "expirationDate": "2014-10-09T16:54:48Z" 1254 } 1255 }) 1257 If successful, the KMS response to a create ephemeral key request 1258 MUST have a status of 201. In the case of a request failure, the KMS 1259 response status SHOULD be that of an [RFC7231] defined status code 1260 with semantics that correspond to the failure condition. In 1261 addition, the ephemeral key SHOULD have the createDate assigned as 1262 the current time and an expirationDate assigned as the latest point 1263 in time before which the key may be used for encrypting messages 1264 (both in [RFC3339] date-time format). 1266 On receiving the ephemeral key creation response, the resource client 1267 MUST verify the received JWS against the KMS server's validated 1268 static public key. If verification fails, the client MUST NOT use 1269 the server response to continue with key agreement. 1271 To generate the shared secret, both resource client and KMS server 1272 use ECDH shared secret derivation with the private part of the local 1273 EC key pair and the public part of the remote EC key pair. The 1274 shared secret is then provided as input to HKDF (with both extract 1275 and expand, and empty salt) [RFC5869] to generate the ephemeral key 1276 (K_ephemeral). 1278 The ephemeral key generated by this operation is used to encrypt all 1279 subsequent KMS requests submitted by the requesting resource client. 1280 The encryption of subsequent requests takes the form of a JWE object 1281 for which the kid attribute value MUST be the key object URI provided 1282 by the KMS in the response message described above. 1284 The KMS SHOULD accept messages encrypted with the ephemeral key up to 1285 and until the key expiration date as provided in the response message 1286 described above. On expiration of the ephemeral key, the KMS MUST 1287 reject all further requests submitted using this key, and a client 1288 wishing to submit further requests to the KMS MUST re-establish the 1289 secure channel by requesting the creation of a new ephemeral key. 1291 4.7.2. Delete Ephemeral Key 1293 In the event that a resource client's ephemeral key has become 1294 compromised, a client SHOULD submit a request to the KMS to delete 1295 the ephemeral key. 1297 The request message conforms to the basic request message structure, 1298 where the method is "delete", and the uri is that of the ephemeral 1299 key to be deleted. 1301 Request payload definition: 1303 root { 1304 request 1305 } 1307 Request message example: 1309 JWE(K_ephemeral, { 1310 "client": { 1311 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1312 "credential": { 1313 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1314 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1315 } 1316 } 1317 "method": "delete", 1318 "uri": "/ecdhe/ea9f3858-1240-4328-ae22-a15f6072306f", 1319 "sequence": 7 1320 }) 1322 The response message conforms to the basic response message 1323 structure, and MUST NOT include a representation of the deleted 1324 ephemeral key. 1326 Response payload definition: 1328 root { 1329 response 1330 } 1332 Response message example: 1334 JWE(K_ephemeral, { 1335 "status": 204, 1336 "sequence": 7 1337 }) 1339 If successful, the KMS response to a delete ephemeral key request 1340 MUST have a status of 204. In the case of a request failure, the KMS 1341 response status SHOULD be that of an [RFC7231] defined status code 1342 with semantics that correspond to the failure condition. 1344 On successful deletion of an ephemeral key, the KMS MUST NOT, from 1345 that time forward, accept any requests encrypted with that ephemeral 1346 key. 1348 4.7.3. Create Resource 1350 When a client intends to initiate E2E encryption of a communications 1351 resource, it begins by requesting the creation of a KMS resource 1352 object. This resource object logically represents the communications 1353 resource within the KMS data model. 1355 As part of a create resource request, a KMS server MUST create at 1356 least one authorization object on the newly created resource object 1357 to explicitly authorize the user making the request. A client MAY 1358 request the immediate creation of one or more additional 1359 authorizations such that corresponding users may be immediately 1360 authorized to access and operate on the new resource object. If for 1361 any reason one or more requested authorizations cannot be applied to 1362 the new resource object, the entire create resource request MUST be 1363 failed by the KMS. 1365 As part of a create resource request, a client MAY request the 1366 immediate binding of one or more unbound KMS keys to the new resource 1367 object. If any key indicated in the request is already bound, or is 1368 otherwise invalid (e.g. expired), the entire create resource request 1369 MUST be failed by the KMS. 1371 The request message conforms to the basic request message structure, 1372 where the method is "create", the uri is "/resources", and additional 1373 user identifiers and/or key URIs are provided in a manner consistent 1374 with the following. 1376 Request payload definition: 1378 userIds ( 1379 "userIds" : [ *string ] 1380 ) 1382 root { 1383 request, 1384 ?userIds, 1385 ?keyUris 1386 } 1388 Request message example: 1390 JWE(K_ephemeral, { 1391 "client": { 1392 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1393 "credential": { 1394 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1395 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1396 } 1397 } 1398 "method": "create", 1399 "uri": "/resources", 1400 "sequence": 7, 1401 "userIds": [ 1402 "b46e8124-b6e8-47e0-af0d-e7f1a2072dac", 1403 "39d56a84-c6f9-459e-9fd1-40ab4ad3e89a" 1404 ], 1405 "keyUris": [ 1406 "/keys/b4cba4da-a984-4af2-b54f-3ca04acfe461", 1407 "/keys/2671413c-ab80-4f19-a0a4-ae07e1a94e90" 1408 ] 1409 }) 1411 The response message conforms to the basic response message 1412 structure, and includes a representation of the created KMS resource 1413 object. 1415 Response payload definition: 1417 root { 1418 response, 1419 resource 1420 } 1422 Response message example: 1424 JWE(K_ephemeral, { 1425 "status": 201, 1426 "sequence": 7, 1427 "resource": { 1428 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094", 1429 "authorizationUris": [ 1430 "/authorizations/50e9056d-0700-4919-b55f-84cd78a2a65e", 1431 "/authorizations/db4c95ab-3fbf-42a8-989f-f53c1f13cc9a" 1432 ], 1433 "keyUris": [ 1434 "/keys/b4cba4da-a984-4af2-b54f-3ca04acfe461", 1435 "/keys/2671413c-ab80-4f19-a0a4-ae07e1a94e90" 1436 ] 1437 } 1438 }) 1440 If successful, the KMS response to a create resource request MUST 1441 have a status of 201. In the case of a request failure, the KMS 1442 response status SHOULD be that of an [RFC7231] defined status code 1443 with semantics that correspond to the failure condition. 1445 4.7.4. Create Unbound Keys 1447 When a client requires a symmetric key for use in the E2E encryption 1448 of a communications resource, it begins by requesting the creation of 1449 one or more unbound keys from the KMS. A client may submit this 1450 request at any time, even before the communications resource exists. 1451 The keys returned by this request are unbound, which is to say not 1452 yet associated with any KMS resource object. 1454 The request message conforms to the basic request message structure, 1455 where the method is "create", the uri is "/keys", and an additional 1456 count attribute is introduced to indicate the number of keys to be 1457 created. 1459 Request payload definition: 1461 root { 1462 request, 1463 "count": integer 1464 } 1466 Request message example: 1468 JWE(K_ephemeral, { 1469 "client": { 1470 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1471 "credential": { 1472 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1473 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1474 } 1475 } 1476 "method": "create", 1477 "uri": "/keys", 1478 "sequence": 7, 1479 "count": 2 1480 }) 1482 The response message conforms to the basic response message structure 1483 with the addition of an array of key object representations, one for 1484 each unbound key created. 1486 Response payload definition: 1488 root { 1489 response, 1490 keys / keyUris 1491 } 1493 Response message example: 1495 JWE(K_ephemeral, { 1496 "status": 201, 1497 "sequence": 7, 1498 "keys": [ 1499 { 1500 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1501 "jwk": { 1502 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1503 "kty": "oct", 1504 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1505 } 1506 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1507 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1508 "createDate": "2014-10-09T15:54:48Z", 1509 "expirationDate": "2014-10-09T16:04:48Z" 1510 }, 1511 { 1512 "uri": "/keys/fed33890-f9fa-43ad-a9f8-ab55a983a543", 1513 "jwk": { 1514 "kid": "fed33890-f9fa-43ad-a9f8-ab55a983a543", 1515 "kty": "oct", 1516 "k": "q2znCXQpbBPSZBUddZvchRSH5pSSKPEHlgb3CSGIdpL" 1517 } 1518 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1519 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1520 "createDate": "2014-10-09T15:54:48Z", 1521 "expirationDate": "2014-10-09T16:04:48Z" 1522 } 1523 ] 1524 }) 1526 Each key object in the response to a create unbound keys request 1527 includes a single JWK [I-D.ietf-jose-json-web-key] representing a new 1528 symmetric key of 256 bits generated by a cryptographically secure 1529 PRNG. Note that, as unbound keys, the resourceUri attribute of each 1530 key is either undefined or null. All keys SHOULD have the createDate 1531 assigned as the current time and an expirationDate assigned as the 1532 latest point in time before which the key may be bound to a resource 1533 (both in [RFC3339] date-time format). 1535 The clientId attribute of each created key MUST be the clientId 1536 provided by the client in the client.clientId attribute of the 1537 request. 1539 As shown in the response payload definition, the KMS MUST return 1540 either an array of key object representations or an array of key 1541 object uris. It is at the KMS server's discretion which of these is 1542 returned. 1544 If successful, the KMS response to a create unbound keys request MUST 1545 have a status of 201. In the case of a request failure, the KMS 1546 response status SHOULD be that of an [RFC7231] defined status code 1547 with semantics that correspond to the failure condition. 1549 4.7.5. Update Unbound Key (Bind) 1551 To initiate the use of an unbound KMS key in securing a 1552 communications resource, a client will create a corresponding KMS 1553 resource object and subsequently bind the unbound key to that 1554 resource. A client MAY begin using an unbound KMS key to encrypt a 1555 communications resource prior to the binding of that key. 1557 The request message conforms to the basic request message structure, 1558 where the method is "update", the uri is that of the key to be bound, 1559 and an additional resourceUri attribute is introduced to indicate the 1560 KMS resource object to which the key is to be bound. If the user 1561 making a bind unbound key request does not have an authorization on 1562 the resource indicated by the resourceUri, or is not the user for 1563 whom the unbound key was originally created, the KMS MUST fail the 1564 request. The KMS SHOULD fail the request if the clientId of the 1565 request does not match that of the unbound key. 1567 Request payload definition: 1569 root { 1570 request, 1571 "resourceUri" : kmsUri 1572 } 1574 Request message example: 1576 JWE(K_ephemeral, { 1577 "client": { 1578 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1579 "credential": { 1580 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1581 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1582 } 1583 } 1584 "method": "update", 1585 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1586 "sequence": 7, 1587 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1588 }) 1589 The response message conforms to the basic response message 1590 structure, and includes a representation of the full state of the 1591 newly bound key. 1593 Response payload definition: 1595 root { 1596 response, 1597 key 1598 } 1600 Response message example: 1602 JWE(K_ephemeral, { 1603 { 1604 "status": 200, 1605 "sequence": 7, 1606 "key": { 1607 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1608 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1609 "jwk": { 1610 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1611 "kty": "oct", 1612 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1613 } 1614 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1615 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1616 "createDate": "2014-10-09T15:54:48Z", 1617 "bindDate": "2014-10-09T15:55:34Z", 1618 "expirationDate": "2014-10-10T15:55:34Z", 1619 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1620 } 1621 }) 1623 On successfully binding a formerly unbound KMS key to a resource 1624 object, the state of the KMS key object MUST reflect the updated 1625 resourceUri attribute, MUST reflect a bindDate as the current time, 1626 and MUST reflect an expirationDate as the time after which clients 1627 MUST NOT use this key for encryption as provided by KMS policy. 1628 Subsequently, the KMS MUST regard the key as bound to the KMS 1629 resource object identified by the resourceUri and MUST reject 1630 subsequent requests to bind the same key to any other resource 1631 object. 1633 If successful, the KMS response to a bind unbound key request MUST 1634 have a status of 200. In the case of a request failure, the KMS 1635 response status SHOULD be that of an [RFC7231] defined status code 1636 with semantics that correspond to the failure condition. 1638 4.7.6. Retrieve Keys 1640 Clients engaging in E2E encryption require a means for retrieving 1641 keys from the KMS. A key request may take one of three forms, it may 1642 be 1644 o a request for a specific key, 1646 o a request all keys bound to a particular resource, or 1648 o a request for a subset of keys bound to a particular resource. 1650 In all cases, the request message conforms to the basic request 1651 message structure with "retrieve" as the value for the method 1652 attribute. 1654 To retrieve an individual key, the uri of the request is that of the 1655 key object to be retrieved. If the key is unbound, the KMS MUST 1656 reject the request unless it originates from the user that requested 1657 the key's creation, and SHOULD reject the request unless it 1658 originates from the same clientId that requested the key's creation. 1659 If the key is bound, the KMS MUST reject the request unless the 1660 request originates from a user for which there exists a corresponding 1661 authorization on the resource to which the requested key is bound. 1663 To retrieve all keys bound to a particular resource, the uri of the 1664 request is that of the resource concatenated with "/keys". To 1665 retrieve a select subset of keys bound to a particular resource, the 1666 client constructs a request for all keys and augments this with the 1667 additional attributes "count" and "prefer". The count attribute 1668 specifies the maximum number of keys that the KMS may return in the 1669 response message, and the prefer attribute is a token indicating a 1670 preference criterion. Defined preference criteria are: 1672 o recently-bound 1674 o recently-requested 1676 The recently-bound criterion prefers keys that have been most 1677 recently bound to the resource. The recently-requested criterion 1678 prefers keys that have been most recently requested by their specific 1679 uri (including requests made by other clients). The KMS MUST reject 1680 the request unless the request originates from a user for which there 1681 exists a corresponding authorization on the resource from which bound 1682 keys are being requested. 1684 Request payload definition: 1686 root { 1687 request, 1688 ?( 1689 "prefer": string /recently-bound|recently-requested/, 1690 "count": integer 1691 ) 1692 } 1694 Request message example (individual key): 1696 JWE(K_ephemeral, { 1697 "client": { 1698 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1699 "credential": { 1700 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1701 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1702 } 1703 } 1704 "method": "retrieve", 1705 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1706 "sequence": 7 1707 }) 1709 Request message example (all keys bound to a resource): 1711 JWE(K_ephemeral, { 1712 "client": { 1713 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1714 "credential": { 1715 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1716 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1717 } 1718 } 1719 "method": "retrieve", 1720 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094/keys", 1721 "sequence": 7 1722 }) 1724 Request message example (10 keys most recently bound to a resource): 1726 JWE(K_ephemeral, { 1727 "client": { 1728 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1729 "credential": { 1730 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1731 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1732 } 1733 } 1734 "method": "retrieve", 1735 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094/keys", 1736 "sequence": 7, 1737 "prefer": "recently-bound", 1738 "count": 10 1739 }) 1741 The response message conforms to the basic response message structure 1742 and includes a representation of the key or keys selected by the 1743 request. In the case of a request for a specific individual key, the 1744 response will contain a representation of a single key. In the case 1745 of a request for all keys bound to a resource, the response will 1746 contain an array representing all KMS keys currently bound to the 1747 resource. 1749 In the case of a request for a select subset of keys bound to a 1750 resource, the response will contain an array representing the set of 1751 KMS keys currently bound to the resource and which most closely 1752 satisfy the preference criterion indicated in the request. In this 1753 case, the size of the keys array in the response MUST NOT exceed the 1754 count as given in the request. 1756 Response payload definition: 1758 root { 1759 response, 1760 key / keys 1761 } 1763 Response message example (for specific key): 1765 JWE(K_ephemeral, { 1766 { 1767 "status": 200, 1768 "sequence": 7, 1769 "key": { 1770 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1771 "jwk": { 1772 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1773 "kty": "oct", 1774 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1775 } 1776 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1777 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1778 "createDate": "2014-10-09T15:54:48Z", 1779 "bindDate": "2014-10-09T15:55:34Z", 1780 "expirationDate": "2014-10-10T15:55:34Z", 1781 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1782 } 1783 }) 1785 Response message example (all keys bound to a resource): 1787 JWE(K_ephemeral, { 1788 { 1789 "status": 200, 1790 "sequence": 7, 1791 "keys": [ 1792 { 1793 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1794 "jwk": { 1795 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1796 "kty": "oct", 1797 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1798 } 1799 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1800 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1801 "createDate": "2014-10-09T15:54:48Z", 1802 "bindDate": "2014-10-09T15:55:34Z", 1803 "expirationDate": "2014-10-10T15:55:34Z", 1804 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1805 }, 1806 { 1807 "uri": "/keys/fed33890-f9fa-43ad-a9f8-ab55a983a543", 1808 "jwk": { 1809 "kid": "fed33890-f9fa-43ad-a9f8-ab55a983a543", 1810 "kty": "oct", 1811 "k": "q2znCXQpbBPSZBUddZvchRSH5pSSKPEHlgb3CSGIdpL" 1812 } 1813 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1814 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1815 "createDate": "2014-10-09T15:54:48Z", 1816 "bindDate": "2014-10-09T15:56:43Z", 1817 "expirationDate": "2014-10-10T15:56:43Z", 1818 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1819 }] 1820 }) 1822 If successful, the KMS response to a retrieve bound keys request MUST 1823 have a status of 200. In the case of a request failure, the KMS 1824 response status SHOULD be that of an [RFC7231] defined status code 1825 with semantics that correspond to the failure condition. 1827 4.7.7. Create Authorizations 1829 An authorization establishes a relationship between a resource and a 1830 user that entitles the user to retrieve bound keys from, and bind new 1831 keys to, that resource. The KMS resource authorization model is 1832 viral in the sense that, once a user has been authorized on a 1833 resource, that user is also entitled to authorize other users on that 1834 resource. These authorizations are created through create 1835 authorization requests. 1837 The request message conforms to the basic request message structure, 1838 where the method is "create", and the uri is "/authorizations". 1839 Additional attributes are required to indicate the resource on which 1840 authorizations are to be added, as well as the set of users for whom 1841 these new authorizations are to be created. 1843 root { 1844 request, 1845 "resourceUri" : kmsUri, 1846 "userIds" : [ *string ] 1847 } 1849 Request message example: 1851 JWE(K_ephemeral, { 1852 "client": { 1853 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1854 "credential": { 1855 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1856 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1857 } 1858 } 1859 "method": "create", 1860 "uri": "/authorizations", 1861 "sequence": 7, 1862 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094", 1863 "userIds": [ 1864 "119a0582-2e2b-4c0c-ba6a-753d05171803", 1865 "557ac05d-5751-43b4-a04b-e7eb1499ee0a" 1866 ] 1867 }) 1869 The response message conforms to the basic response message 1870 structure, and includes a representation of the set of KMS 1871 authorization objects created by the request. 1873 Response payload definition: 1875 root { 1876 response, 1877 authorizations 1878 } 1880 Response message example: 1882 JWE(K_ephemeral, { 1883 { 1884 "status": 201, 1885 "sequence": 7, 1886 "collection": [ 1887 { 1888 "uri": "/authorizations/79a39ed9-a8e5-4d1f-9ae2-e27857fc5901", 1889 "userId": "119a0582-2e2b-4c0c-ba6a-753d05171803", 1890 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1891 }, 1892 { 1893 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b", 1894 "userId": "557ac05d-5751-43b4-a04b-e7eb1499ee0a", 1895 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1896 }] 1897 }) 1899 If successful, the KMS response to a create authorizations request 1900 MUST have a status of 201. In the case of a request failure, the KMS 1901 response status SHOULD be that of an [RFC7231] defined status code 1902 with semantics that correspond to the failure condition. If for any 1903 reason one or more requested authorizations cannot be created or 1904 applied to the resource object, the entire create authorizations 1905 request MUST be failed by the KMS. 1907 4.7.8. Delete Authorization 1909 To remove an authorization from a KMS resource object, any user 1910 currently authorized on the same resource object may issue a delete 1911 authorization request. The request message conforms to the basic 1912 request message structure, where the method is "delete", and the uri 1913 is that of the authorization object to be deleted. 1915 Request payload definition: 1917 root { 1918 request 1919 } 1921 Request message example: 1923 JWE(K_ephemeral, { 1924 "requestId": "1234", 1925 "client": { 1926 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1927 "credential": { 1928 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1929 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1930 } 1931 } 1932 "method": "delete", 1933 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b" 1934 }) 1936 The response message conforms to the basic response message 1937 structure, and includes a representation of the authorization object 1938 that was deleted. 1940 Response payload definition: 1942 root { 1943 response, 1944 authorization 1945 } 1947 Response message example: 1949 JWE(K_ephemeral, { 1950 { 1951 "status": 200, 1952 "sequence": 7, 1953 "object": { 1954 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b", 1955 "userId": "557ac05d-5751-43b4-a04b-e7eb1499ee0a", 1956 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1957 } 1958 }) 1960 If successful, the KMS response to a delete authorization request 1961 MUST have a status of 200. In the case of a request failure, the KMS 1962 response status SHOULD be that of an [RFC7231] defined status code 1963 with semantics that correspond to the failure condition. 1965 5. Mandatory-to-Implement 1967 Implementations MUST support the following JWK key types from 1968 [I-D.ietf-jose-json-web-algorithms]: 1970 o "RSA" for the KMS static public/private key 1971 o "EC" for the Ephemeral Diffie Hellman exchange 1973 o "oct" for all symmetric keys 1975 Implementations MUST support "PS256" (RSASSA-PSS using SHA-256 and 1976 MGF1 with SHA-256) from [I-D.ietf-jose-json-web-algorithms] for 1977 signatures using the KMS static public/private key for Section 4.7.1. 1979 Implementations MUST support JWK Elliptic Curve type "P-256" (NIST 1980 P-256 curve) from [I-D.ietf-jose-json-web-algorithms] for 1981 Section 4.7.1. 1983 Implementations MUST support "RSA-OAEP" (RSAES OAEP using default 1984 parameters) from [I-D.ietf-jose-json-web-algorithms] for key 1985 encryption using the KMS static public/private key for Section 4.7.1. 1987 Implementations MUST support "dir" (Direct Key Agreement Key 1988 Management Mode) from [I-D.ietf-jose-json-web-algorithms] for all 1989 operations other than Section 4.7.1. 1991 Implementations MUST support "A256GCM" (AES GCM using 256 bit key) 1992 from [I-D.ietf-jose-json-web-algorithms] for content encryption for 1993 all operations other than Section 4.7.1. 1995 6. Security Considerations 1997 Security considerations are discussed throughout this document. 1998 Additional considerations may be added here as needed. 2000 7. Appendix A. Acknowledgments 2002 This specification is the work of several contributors. In 2003 particular, the following individuals contributed ideas, feedback, 2004 and wording that influenced this specification: 2006 Cullen Jennings, Matt Miller, Suhas Nandakumar, Jonathan Rosenberg 2008 8. Appendix B. Document History 2010 -00 2012 o Initial draft. 2014 9. References 2015 9.1. Normative References 2017 [I-D.ietf-jose-json-web-algorithms] 2018 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 2019 json-web-algorithms-33 (work in progress), September 2014. 2021 [I-D.ietf-jose-json-web-encryption] 2022 Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2023 draft-ietf-jose-json-web-encryption-33 (work in progress), 2024 September 2014. 2026 [I-D.ietf-jose-json-web-key] 2027 Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 2028 key-33 (work in progress), September 2014. 2030 [I-D.ietf-jose-json-web-signature] 2031 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2032 Signature (JWS)", draft-ietf-jose-json-web-signature-33 2033 (work in progress), September 2014. 2035 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2036 Requirement Levels", BCP 14, RFC 2119, March 1997. 2038 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 2039 2001. 2041 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 2042 Internet: Timestamps", RFC 3339, July 2002. 2044 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 2045 4949, August 2007. 2047 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2048 Housley, R., and W. Polk, "Internet X.509 Public Key 2049 Infrastructure Certificate and Certificate Revocation List 2050 (CRL) Profile", RFC 5280, May 2008. 2052 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2053 Key Derivation Function (HKDF)", RFC 5869, May 2010. 2055 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2056 Verification of Domain-Based Application Service Identity 2057 within Internet Public Key Infrastructure Using X.509 2058 (PKIX) Certificates in the Context of Transport Layer 2059 Security (TLS)", RFC 6125, March 2011. 2061 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 2062 6749, October 2012. 2064 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2065 Interchange Format", RFC 7159, March 2014. 2067 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2068 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2070 9.2. Informative References 2072 [I-D.barnes-pervasive-problem] 2073 Barnes, R., Schneier, B., Jennings, C., and T. Hardie, 2074 "Pervasive Attack: A Threat Model and Problem Statement", 2075 draft-barnes-pervasive-problem-01 (work in progress), July 2076 2014. 2078 [I-D.ietf-xmpp-posh] 2079 Miller, M. and P. Saint-Andre, "PKIX over Secure HTTP 2080 (POSH)", draft-ietf-xmpp-posh-02 (work in progress), 2081 October 2014. 2083 [I-D.newton-json-content-rules] 2084 Newton, A., "A Language for Rules Describing JSON 2085 Content", draft-newton-json-content-rules-02 (work in 2086 progress), August 2014. 2088 [OTR] Borisov, N., Goldberg, I., and E. Brewer, "Off-the-Record 2089 Communication, or, Why Not To Use PGP", 2012, 2090 . 2092 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 2093 Internet Protocol", RFC 4301, December 2005. 2095 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 2096 Thayer, "OpenPGP Message Format", RFC 4880, November 2007. 2098 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2099 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2101 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2102 RFC 5652, September 2009. 2104 Authors' Addresses 2106 Andrew Biggs 2107 Cisco Systems 2109 Email: adb@cisco.com 2110 Shaun Cooley 2111 Cisco Systems 2113 Email: shcooley@cisco.com