idnits 2.17.1 draft-abiggs-saag-key-management-service-02.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 (July 03, 2015) is 3220 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 792, 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: January 4, 2016 July 03, 2015 7 Key Management Service Architecture 8 draft-abiggs-saag-key-management-service-02 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 January 4, 2016. 41 Copyright Notice 43 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . 6 62 2. Architectural Overview . . . . . . . . . . . . . . . . . . . 6 63 3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . . . . . . 22 76 4.6. Message Structure . . . . . . . . . . . . . . . . . . . . 22 77 4.6.1. Basic Request Payload . . . . . . . . . . . . . . . . 23 78 4.6.2. Basic Response Payload . . . . . . . . . . . . . . . 25 79 4.6.3. Error Response Payload . . . . . . . . . . . . . . . 26 80 4.7. Requests . . . . . . . . . . . . . . . . . . . . . . . . 26 81 4.7.1. Create Ephemeral Key . . . . . . . . . . . . . . . . 26 82 4.7.2. Delete Ephemeral Key . . . . . . . . . . . . . . . . 29 83 4.7.3. Create Resource . . . . . . . . . . . . . . . . . . . 30 84 4.7.4. Retrieve Resource . . . . . . . . . . . . . . . . . . 33 85 4.7.5. Create Keys . . . . . . . . . . . . . . . . . . . . . 34 86 4.7.6. Update Key (Bind) . . . . . . . . . . . . . . . . . . 37 87 4.7.7. Retrieve Keys . . . . . . . . . . . . . . . . . . . . 39 88 4.7.8. Create Authorizations . . . . . . . . . . . . . . . . 43 89 4.7.9. Retrieve Authorizations . . . . . . . . . . . . . . . 45 90 4.7.10. Delete Authorization . . . . . . . . . . . . . . . . 47 91 4.7.11. Ping . . . . . . . . . . . . . . . . . . . . . . . . 48 92 5. Mandatory-to-Implement . . . . . . . . . . . . . . . . . . . 49 93 6. Security Considerations . . . . . . . . . . . . . . . . . . . 50 94 7. Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . 50 95 8. Appendix B. Document History . . . . . . . . . . . . . . . . 50 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 97 9.1. Normative References . . . . . . . . . . . . . . . . . . 50 98 9.2. Informative References . . . . . . . . . . . . . . . . . 52 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52 101 1. Introduction 103 Providers of cloud-based services commonly secure user data at the 104 transport level using established protocols such as TLS [RFC5246] or 105 IPSec [RFC4301]. These protocols can be effective in protecting 106 transmitted user data from third party tampering and eavesdropping; 107 however, by themselves these protocols do not secure user data from 108 abuses, negligence, or coerced behavior on the part of the cloud 109 provider. This is a concern for individuals and organizations that 110 wish to take advantage of cloud-based communications and 111 collaboration but cannot accept the risk of trusting cloud providers 112 with unfettered access to the contents of their communications. 114 E2E encryption describes a category of solutions that can be employed 115 to address this problem by establishing secure channels among 116 clients. To the extent that a user can trust their collaboration 117 client software, E2E encryption mitigates exposure of user data to 118 untrusted parties by ensuring that intermediaries never possess 119 unencrypted user data or have access to the keying material necessary 120 to decrypt it. 122 Existing E2E strategies such as ECS [RFC5652], PGP [RFC4880], and 123 Off-the-Record Messaging [OTR] can be effective at securing two-party 124 communications. However, E2E encryption for the growing domain of 125 multiparty communications and online content sharing remains a 126 generally unsolved problem to which these existing approaches do not 127 readily adapt. In particular, a core challenge exists in providing 128 for the secure distribution and rotation of E2E encryption keys among 129 an arbitrary and potentially dynamic set of communicating clients. 130 In cases where the communications to be secured are persistent or 131 archived, the additional challenge exists for providing trusted long- 132 term storage and retrieval of these keys. 134 Equally problematic is the paucity of E2E encryption options that 135 satisfy common organizational obligations such as regulatory 136 compliance and legal discovery. Entities that must operate within 137 such frameworks require mechanisms by which they (and they alone) may 138 recover the keys used to secure their communications. Existing E2E 139 encryption solutions are not, by themselves, well suited for this 140 purpose. 142 In the interest of addressing these challenges this document presents 143 an architecture for the deployment of E2E encryption key management 144 services (KMS). In this architecture a KMS service provides to its 145 users a means by which their communications clients may securely 146 create, share, rotate, and store E2E encryption keying material. It 147 does so in a fashion that permits the decoupling of such services 148 from the communications media, thereby permitting the former to 149 reside under the direct control of the communicating parties or the 150 organizations within which they do business. 152 1.1. Terminology 154 This document uses the terminology from 155 [I-D.ietf-jose-json-web-signature], 156 [I-D.ietf-jose-json-web-encryption], [I-D.ietf-jose-json-web-key], 157 and [I-D.ietf-jose-json-web-algorithms] when discussing JOSE 158 technologies. 160 This document makes use of the following terminology, and 161 additionally adopts nomenclature defined in 162 [I-D.barnes-pervasive-problem] for the purpose of describing aspects 163 of pervasive attacks. 165 communications resource 167 A communications resource is any uniquely identifiable continuous 168 data channel or discrete shared content that represents an 169 exchange of personal communications between two or more users. 171 communications resource client 173 A communications resource client consumes communications resources 174 on behalf of a user and, when deployed in conformance with the KMS 175 architecture, consumes the services of KMS server(s) to facilitate 176 the E2E encryption of those communications resources. 178 communications resource server 180 A communications resource server is a provider of services through 181 which communications resources are made available. 183 cloud provider 185 An individual or organization responsible for, and in control of, 186 one or more communications resource servers. 188 E2E encryption 190 Shorthand for end-to-end encryption, as defined in [RFC4949], 191 particularly as it applies to the establishment of confidentiality 192 and integrity of communications resources. 194 KMS server 196 A key management server (KMS) is responsible for creating, 197 storing, and providing access to E2E encryption keying material by 198 communications resource clients. 200 KMS protocol 202 The protocol through which communications resource clients 203 interoperate with KMS servers. 205 KMS provider 207 An individual or organization responsible for, and in control of, 208 a KMS server deployment. 210 KMS transport 212 Any service or protocol that provides the basic transport over 213 which KMS protocol messages are exchanged. 215 resource client 217 See communications resource client. 219 resource server 221 See communications resource server. 223 trusted party 225 A trusted party is an individual or organization that is trusted 226 by one or more communicating users to maintain the confidentiality 227 and integrity of their communications resources. 229 1.2. Security Terms 231 Most security-related terms in this document are to be understood in 232 the sense defined in [RFC4949]; such terms include, but are not 233 limited to, "attack", "authentication", "authorization", 234 "certification authority", "certification path", "certificate", 235 "credential", "identity", "self-signed certificate", "trust", "trust 236 anchor", "trust chain", "validate", and "verify". 238 1.3. Notational Conventions 240 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 241 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 242 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 243 [RFC2119]. 245 2. Architectural Overview 247 The architectural reference model for this specification is 248 illustrated in Figure 1. Central to this model is the 249 _communications resource server_ which is presumed to be operated by 250 a _cloud provider_ for the purpose of offering some form of 251 communications service. The nature of this service is not prescribed 252 by this specification and may take the form of any of a variety of 253 communications or collaboration services including file sharing, 254 messaging, and VoIP. Consuming the services of the communications 255 resource server are _communications resource clients_ which may be 256 supplied by the cloud provider or developed by third parties. 258 +-----------------+ 259 | Communications | 260 +-------------------| Resource Server |-------------------+ 261 | | (Cloud Provider)| | 262 | +-----------------+ | 263 | | 264 | | 265 | +-----------------+ | 266 | +-----------| KMS Transport |-----------+ | 267 | | +-----------------+ | | 268 | | | | | 269 | | Untrusted | | | 270 - - -|- - - -|- - - - - - - - - - | - - - - - - - - - -|- - - -|- - - 271 | | Trusted | | | 272 | | | | | 273 +-----------------+ +-----------------+ +-----------------+ 274 | Communications | | KMS Server | | Communications | 275 | Resource Client | | (KMS Provider) | | Resource Client | 276 +-----------------+ +-----------------+ +-----------------+ 277 | | 278 +-----------------+ +-----------------+ 279 | Alice | | Bob | 280 +-----------------+ +-----------------+ 282 Figure 1: KMS Architecture Reference Model 284 In addition to the familiar elements described above, this model also 285 includes a key management server, or _KMS_, operated by a _KMS 286 provider_. The KMS server exposes an API through which clients may 287 securely establish and share cryptographic keying material used for 288 the E2E encryption of content that is transited through the cloud 289 provider's services. This API is secured in such a way as to ensure 290 these keys are visible to none but the KMS server itself and the 291 clients authorized to consume the content they protect. This 292 highlights an important distinction between the KMS provider and the 293 cloud provider: while the KMS provider is necessarily a _trusted 294 party_, the cloud provider need not be. 296 It is an explicit objective of this specification to promote an 297 ecosystem of providers of KMS implementations and KMS services that 298 are distinct and independent of the cloud providers over whose 299 services users communicate. To that end, this specification seeks to 300 standardize a KMS service protocol though which clients and KMS 301 servers interoperate. This protocol provides for the establishment 302 of a confidential and authenticated channel between each client and 303 KMS server, and defines an API of request and response messages to be 304 exchanged over this secure channel for the purpose of creating, 305 retrieving, and exchanging keys. 307 While the KMS service protocol constitutes a central focus of this 308 specification, the means by which this protocol is transported is 309 expressly out of scope. This role may be readily addressed through 310 either standards-based or proprietary protocols, and so we refer to 311 this simply as the _KMS transport_ for the remainder of this 312 document. Over this transport, the communication paths between 313 clients and KMS server are encrypted using keys established through 314 an authenticated ephemeral key agreement. As such, the KMS transport 315 provider need not be regarded as a trusted party, and in fact may be 316 the cloud provider itself. 318 An important non-goal of this specification is the standardization of 319 any aspect of the cloud provider's services or the means by which 320 clients utilize shared keys for the E2E encryption of data transiting 321 those services. By avoiding the application of constraints on the 322 communications services and protocols we enable the use of this 323 specification in the context of existing service deployments, both 324 standards-based and proprietary. It is similarly a non-goal of this 325 specification to enable federation of secure communications between 326 vendors of different cloud services, as that is the realm of 327 standardized application protocols. The scope of this specification 328 is intended to be narrowly focused on the task of separating E2E 329 encryption key management from the communications services they 330 secure, thereby facilitating the broadest possible adoption of secure 331 communications though existing services. 333 3. Use Cases 335 The use cases described in this section are non-normative examples 336 meant to illustrate how the KMS architecture may be deployed to 337 provide E2E encryption of different types of communications 338 resources. These use cases differ in detail, but generally follow a 339 common logical sequence as given below. 341 Note that all requests to the KMS server are via the KMS transport 342 which, for clarity, has been omitted from the sequence diagrams 343 included in this section. 345 Resource Resource Resource KMS 346 Client B Client A Server Server 347 | | | | 348 | | | (1) | 349 | |-----------------|---------------->| 350 | | (2) | | 351 | |---------------->| | 352 | | | (3) | 353 | |-----------------|---------------->| 354 | | (4) | | 355 |-----------------|---------------->| | 356 | | | | 357 (5) | | | | 358 | | | (6) | 359 |-----------------|-----------------|---------------->| 360 | | | | 361 (7) | | | | 362 | | | | 364 Figure 2: Nominal Use Case 366 1. Client A requests the generation of a new unbound key from the 367 KMS. 369 2. Client A encrypts a communications resource using the unbound KMS 370 key and shares it via a resource server. 372 3. Client A requests the creation of a new KMS resource object (KRO) 373 to represent the communications resource. Client A also 374 instructs the KMS to bind the KMS key used in step (2) to the new 375 KRO and to authorize user B to retrieve keys bound to the KRO. 377 4. Client B accesses the communications resource shared by client A 378 and receives the encrypted data. 380 5. Client B obtains, through some means not defined by this 381 specification, the URL of the KMS key used to encrypt the 382 communications resource. 384 6. Client B requests the KMS key from the KMS server. The KMS 385 server, recognizing user B as authorized on the KRO to which the 386 key is bound, returns the KMS key. 388 7. Client B decrypts the communications resource using the KMS key. 390 3.1. Securing an HTTP File Sharing Service 392 Let A be a user that wishes to share a file with users B and C 393 through some HTTP based file sharing service. In the context of the 394 KMS architecture we may regard the file sharing provider's HTTP API 395 as the resource server and the users' HTTP clients as the resource 396 clients. 398 For this scenario we also assume that the file sharing service is 399 trusted by user A with the role of providing a file sharing service 400 but is not necessarily trusted to adequately protect the 401 confidentiality of the file contents. User A's concerns may then be 402 addressed through the introduction of an HTTP based KMS transport 403 (not shown) and KMS server deployed by an entity that A regards as a 404 trusted party. 406 HTTP HTTP HTTP HTTP File KMS 407 Client C Client B Client A Share Server Server 408 | | | | | 409 | | | | (1) | 410 | | |--------------|------------>| 411 | | | (2) | | 412 | | |------------->| | 413 | (3) | (3) | | | 414 |<-------------|<-------------|--------------| | 415 | | | | (4) | 416 | | |--------------|------------>| 417 | | | (5) | | 418 | |--------------|------------->| | 419 | | | | (6) | 420 | |--------------|--------------|------------>| 421 | | | | | 422 | (7) | | | | 423 | | | | | 424 (8) | | | | | 425 | | | | | 427 Figure 3: File Sharing Use Case 429 This sequence begins with the assumption that each client has, at 430 some point, already established a secure channel to the KMS via 431 authenticated key agreement. 433 1. Client A requests from the KMS some number of unbound KMS keys. 435 2. Client A selects an unbound key from the set of keys obtained 436 step (1), encrypts the file to be shared, and posts the encrypted 437 content to the file sharing service. The file sharing service 438 responds with a URL that uniquely identifies the shared file. 440 3. Clients B and C learn of the newly shared file from the file 441 sharing service (the mechanism by which this occurs is out of 442 scope for this specification). 444 4. Client A requests the creation of a KMS resource object (KRO) on 445 the KMS to represent the shared file. In this message the client 446 also requests that the key from step (2) be bound to the newly 447 created KRO and that the users of clients B and C be authorized 448 to retrieve keys bound to the KRO. 450 5. Client B retrieves the shared file from the file sharing service. 452 6. Client B requests from the KMS all keys bound to the KRO 453 associated with the shared file's URL. Recognizing client B as 454 authorized on the KRO, the KMS returns the key bound to the KRO 455 by client A in step (4). 457 7. Client B decrypts the shared file using the key obtained in step 458 (6). 460 8. Client C performs steps (5) through (7) in the same fashion as 461 client B. 463 It is worth noting that a race condition does exist where step (6) 464 could occur before step (4) completes. This will result in a client 465 being temporarily denied access to the key used to encrypt the shared 466 file. 468 3.2. Securing an XMPP Multi-User Chat 470 Let A, B and C be users that wish to engage in secure chat through an 471 existing XMPP multi-user chat room. In the context of the KMS 472 architecture we may regard the XMPP MUC service as the resource 473 server, the users' XMPP clients as the resource clients, and the XMPP 474 service itself (not shown) as the KMS transport. 476 XMPP XMPP XMPP XMPP MUC KMS 477 Client C Client B Client A Server Server 478 | | | | | 479 | | | | (1) | 480 | | |--------------|------------>| 481 | | | | (2) | 482 | | |--------------|------------>| 483 | | | (3) | | 484 | | |------------->| | 485 | (4) | (4) | | | 486 |<-------------|<-------------|--------------| | 487 | | | | (5) | 488 | |--------------|--------------|------------>| 489 | | | | | 490 | (6) | | | | 491 | | | | | 492 (7) | | | | | 494 Figure 4: Multi-User Chat Use Case 496 This sequence begins with the assumption that a MUC room already 497 exists on the MUC server and that each client has already established 498 a secure channel to the KMS via authenticated key agreement. All 499 messages are transmitted over XMPP. 501 1. Client A requests from the KMS some number of unbound KMS keys. 502 Client A selects one of these keys for encrypting MUC room 503 messages. 505 2. Client A requests the creation of a KMS resource object (KRO) on 506 the KMS to represent the MUC room. In this message the client 507 also requests that the key selected in step (1) be bound to the 508 newly created KRO and that the users of clients B and C be 509 authorized to retrieve keys bound to the KRO. 511 3. Client A encrypts a message with the key selected in step (1) and 512 sends it to the MUC room. 514 4. The MUC service delivers client A's encrypted message to clients 515 B and C. 517 5. Client B requests from the KMS all keys bound to the KRO 518 associated with the MUC room's URI. Recognizing client B as 519 authorized on the KRO, the KMS returns the key bound to the KRO 520 by client A in step (2). 522 6. Client B decrypts the shared file using the key selected in step 523 (1). 525 7. Client C performs steps (5) and (6) in the same fashion as client 526 B. 528 3.3. KMS to KMS Key Federation 530 This use case illustrates two KMS instances federating keys 531 associated with a resource. As KMS servers are deployed to serve 532 groups of users it is inevitable that users will want to share 533 resources across groups or organizations. This cross-organization 534 sharing of keys leads to several problems. First, each user is only 535 known to and only knows of one logical KMS. Second, each 536 organization might have very different archiving requirements due to 537 differing legal compliance regulations due to jurisdiction or 538 industry differences. Lastly, one or both of the users might be 539 employees of enterprises that need to be able to respond to legal 540 discovery requests. To address these issues, KMS servers may 541 federate in such a way as to allow for limited copying of keys from 542 one KMS to another. This permits each KMS' owning organization the 543 ability to control the ongoing policy regarding access to keys for 544 which their respective users are authorized. 546 Let Alice@DomainA and Bob@DomainB be users of a common file sharing 547 service and who happen to use different KMS servers to secure their 548 communications. Assume then that Alice wishes to share a file with 549 Bob and therefore relies on KMS server federation to facilitate the 550 key exchange. 552 HTTP Client HTTP Client HTTP File KMS Server KMS Server 553 Bob@DomainB Alice@DomainA Share Server DomainA DomainB 554 | | | (1) | | 555 | |--------------|------------->| | 556 | | (2) | | | 557 | |------------->| | | 558 | (3) | | | | 559 |<-------------|--------------| | | 560 | | | (4) | | 561 | |--------------|------------->| | 562 | | (5) | | | 563 |--------------|------------->| | | 564 | | | | (6) | 565 |--------------|--------------|--------------|------------>| 566 | | | | (7) | 567 | | | |<------------| 568 | | | | (8) | 569 | | | |<------------| 570 | | | | | 571 | | | | | (9) 572 | | | | | 573 (10) | | | | | 574 | | | | | 576 Figure 5: File Sharing with KMS Federation Use Case 578 This sequence begins with the assumption that each client has, at 579 some point, already established a secure channel to their respective 580 KMS via authenticated key agreement. 582 1. Alice@DomainA requests from the DomainA KMS some number of 583 unbound KMS keys. Each KMS key is uniquely identified by a URL. 585 2. Alice@DomainA selects a key from the set of KMS keys obtained in 586 step (1), uses that key to encrypt the file to be shared, and 587 posts the encrypted content to the file sharing service. The 588 file sharing service responds with a URL that uniquely 589 identifies the shared file. 591 3. Bob@DomainB is notified of the newly shared file URL and 592 corresponding KMS key URL through a notification from the file 593 sharing service (or potentially some other means, such an an 594 email from Alice). 596 4. Alice@DomainA requests the creation of a KMS resource object 597 (KRO) on the DomainA KMS to represent the shared file. In this 598 message Alice also requests that the KMS key from step (2) be 599 bound to the newly created KRO and that the user Bob@DomainB be 600 authorized to retrieve KMS keys bound to the KRO. 602 5. Bob@DomainB retrieves the shared file from the file sharing 603 service. 605 6. Using the KMS key URL obtained in step (3), Bob@DomainB requests 606 the KMS key from the DomainB KMS. 608 7. The DomainB KMS recognizes the KMS key URL as actually hosted by 609 the DomainA KMS. The DomainB KMS establishes a secure and 610 mutually authenticated channel with the DomainA KMS via the KMS 611 transport. 613 8. The DomainB KMS requests from the DomainA KMS the KRO object to 614 which the KMS key is bound, along with all DomainB user 615 authorizations and other KMS keys that have been bound to that 616 KRO. The DomainA KMS recognizes that the DomainB KMS is 617 authorized to retrieve all KMS keys for which users in the 618 DomainB domain have been authorized. It then recognizes that at 619 least one DomainB user (Bob) has been authorized on the KRO 620 created in step (4). The DomainA KMS therefore decides the 621 DomainB KMS is authorized to make this request and returns the 622 requested information. 624 9. Using the information received from the DomainA KMS, the DomainB 625 KMS verifies that Bob@DomainB is authorized on the KRO, and 626 satisfies the request from step (6) by returning the KMS key to 627 Bob@DomainB. 629 10. Client Bob@DomainB decrypts the shared file using the key 630 obtained in step (9). 632 Note that in step (9) the DomainB KMS is enforcing authorization 633 policy for the KRO hosted on the DomainA KMS as it pertains to 634 DomainB users. This is a necessary consequence of KMS federation, 635 where the act of authorizing access to a KRO by a user residing in a 636 federated domain engenders an implicit trust of the KMS server that 637 controls the federated domain. For that reason, a KMS provider 638 should restrict federation of its KMS servers to domains that the KMS 639 provider regards as trusted. 641 4. KMS Protocol 643 The KMS protocol is composed of a message oriented request and 644 response API and a secure channel over which those messages are 645 exchanged. The API provides clients with the ability to generate E2E 646 encryption keys, associate those keys with communications resources, 647 and explicitly manage access authorizations on those keys. The 648 secure channel provides a mutually authenticated and E2E encrypted 649 channel over which the clients and KMS server may exchange API 650 messages securely. The API and secure channel are described in 651 detail through the remainder of this section. 653 4.1. Secure Channel 655 The secure channel is an encrypted and mutually authenticated 656 communication path between each client and the KMS server. It 657 transits the KMS transport which, in the context of this document, 658 represents any service or protocol that may be utilized for the 659 relaying of KMS API request and response messages. This 660 specification presumes the KMS transport to be untrusted. 662 (3) Secure Channel 663 +===================================================+ 664 V V 665 +-----------------+ (2) +---------------+ (1) +---------------+ 666 | Resource Client |<------>| KMS Transport |<------>| KMS Server | 667 +-----------------+ +---------------+ +---------------+ 668 | | 669 Trusted | Untrusted | Trusted 671 Figure 6: Establishment of a Secure Channel 673 At a high level, the communication path between a resource client and 674 KMS is established as follows. 676 1. The KMS actively connects to the KMS transport. The protocol 677 used for this connection is out of scope for this document, 678 however it MUST support the asynchronous flow of encrypted KMS 679 request and response messages between the KMS and KMS transport. 681 2. A resource client connects to the KMS transport. The protocol 682 used for this connection is out of scope for this document, 683 however it MUST support the flow of encrypted KMS request and 684 response messages between the resource client and the KMS 685 transport. 687 3. Through an elliptic curve Diffie-Helman key exchange, augmented 688 by server and client authentication, the resource client and KMS 689 establish a shared secret and derived ephemeral key. This is 690 discussed in greater detail in Section 4.7.1. 692 On successful mutual authentication and ephemeral key agreement, the 693 resource client and KMS communicate through the exchange of sequenced 694 request and response messages encrypted using the ephemeral key. 696 4.2. User Identity 698 Central to the KMS server's role as a key store is its ability to 699 restrict access to stored keying material to only authorized users. 700 This requires robust user authentication and a means for the 701 unambiguous and unique identification of each user. 703 Conforming KMS architecture deployments MUST rely on an identity 704 provider that supports the generation of OAuth 2.0 [RFC6749] access 705 tokens. The KMS server MUST rely on same identity provider for the 706 purpose of validating access tokens received from the client. Access 707 tokens used by clients to demonstrate identity and authorization for 708 access to KMS resources MUST NOT be used for any other service. Any 709 exposure of a KMS recognized access token to third parties (such as 710 providers of other services) jeopardizes the security of all KMS keys 711 for which the user whose identity is represented by the token is 712 authorized. 714 The identity provider on which the KMS server relies MAY be the same 715 identity provider as relied upon by the resource server(s) whose 716 communications resources are encrypted with keys managed by the KMS 717 server. Note, however, the reliable authentication and authorization 718 of clients to the KMS server is critical to the security of the KMS 719 keys it holds. The identity provider on which the KMS relies must 720 therefore necessarily be regarded as a trusted party within the 721 context of the KMS architecture. 723 Access tokens MUST be conveyed to the KMS server as part of the 724 payload of encrypted KMS API requests as described in Section 4.6.1 725 and MUST NOT be conveyed in any other manner. 727 4.3. KMS Identity 729 Given the untrusted nature of the KMS transport by both the KMS and 730 clients, it is critical for clients to be able to verify the identity 731 of their KMS and ensure that no MITM attacks are carried out on 732 client to KMS or KMS to client communications. Therefore, the KMS 733 MUST make use of at least one PKIX certificate [RFC5280] and clients 734 MUST validate the PKIX certificate presented by the KMS through the 735 comparison of the certificate's common name (CN) or subject 736 alternative name (SAN) [RFC6125] fields to the Internet domain 737 portion of the user's Addr-spec [RFC2822] formatted unique identifier 738 using the procedures defined in section 6 of [RFC6125]. An 739 acceptable alternative to direct CN or SAN validation is defined in 740 [I-D.ietf-xmpp-posh]. 742 PKIX certificates presented by the KMS can be issued by either a 743 public or private certification authority with the stipulation that 744 clients MUST be able to validate the KMS's entire certificate path 745 through the pre-established trust of the root certificate used to 746 anchor the certificate path. The mechanism for establishing trust of 747 the root certificate is out of scope for this specification, but it 748 is usually carried out through pre-installed trusted root 749 certificates on various operating systems for public certification 750 authorities or through enterprise endpoint management solutions or 751 manual installation tasks for private certification authorities. 753 4.4. Object Types 755 The KMS protocol defines three object types: resources, keys, and 756 authorizations. It is through the creation and manipulation of 757 instances of these object types that clients interact with the KMS. 759 Resource 761 A resource is an object that represents, within the KMS object 762 model, a communications resource as defined in Section 1.1. Keys 763 and user authorizations are associated (bound) to the resource 764 object as a means of representing their logical association with 765 that communications resource. 767 Key 769 A key is an object representing symmetric keying material 770 generated and made available to authorized clients by the KMS. A 771 key may exist in one of two states: "bound", and "unbound". An 772 unbound key is not associated with any resource, whereas a bound 773 key is associated with exactly one resource. 775 Authorization 777 An authorization is the association of a user with a particular 778 resource. When such an association exists between a user and a 779 resource this implies that the user is entitled to retrieve any 780 key that is bound to that resource, and to add or remove 781 authorizations for other users on the same resource. 783 The KMS protocol is composed from representations of these 784 fundamental object types. These representations are defined in the 785 following sections. 787 4.4.1. KMS Key Objects 789 The JSON representations for KMS key objects is defined as follows 790 using JSON content rules [I-D.newton-json-content-rules]. 792 jwk : ; see [JWK] 794 kmsUri ( 795 "uri" : uri relative 796 ) 798 keyRep { 799 kmsUri, 800 "jwk" : jwk, 801 "userId" : string, 802 "clientId" : string, 803 "createDate" : date-time, 804 "expirationDate" : date-time, 805 ?"resourceUri" : kmsUri, 806 ?"bindDate" : date-time 807 } 809 key ( 810 "key" : keyRep 811 ) 813 keys ( 814 "keys" : [ *keyRep ] 815 ) 817 keyUris ( 818 "keyUris" : [ *kmsUri ] 819 ) 821 The attributes of a KMS key object are defined as follows. 823 uri 825 A standard definition for KMS object identifiers. 827 jwk 829 Symmetric keying material represented as a JWK object (see 830 [I-D.ietf-jose-json-web-key]). 832 userId 834 The authenticated unique identifier of the user that created the 835 key. 837 clientId 838 An opaque unique identifier provided by the client that created 839 the key. 841 createDate 843 The point in time when the key was created, in [RFC3339] date-time 844 format. 846 expirationDate 848 The point in time after which the key may no longer be bound (if 849 unbound) or may no longer be used for encrypting data (if bound or 850 an ephemeral key). 852 resourceUri 854 The uri of the KMS resource object to which the key is bound. 856 bindDate 858 The point in time when the key was bound, in [RFC3339] date-time 859 format. 861 4.4.2. KMS Authorization Objects 863 The JSON representations for KMS authorization objects is defined as 864 follows using JSON content rules with references to rules defined in 865 previous sections. 867 authorizationRep { 868 kmsUri, 869 "authId" : string, 870 "createDate" : date-time, 871 "resourceUri" : kmsUri, 872 } 874 authorization ( 875 "authorization" : authorizationRep 876 ) 878 authorizations ( 879 "authorizations" : [ *authorizationRep ] 880 ) 882 authorizationUris ( 883 "authorizationUris" : [ *kmsUri ] 884 ) 885 The attributes of a KMS authorization object are defined as follows. 887 uri 889 A standard definition for KMS object identifiers. 891 authId 893 A unique identifier of the authorized entity. The exact semantics 894 of this attribute are out of scope for this document, however it 895 is RECOMMENDED that an implementation regard the value of this 896 attribute as mapped to either an individual identity or a grouping 897 of identities as recognized by the identity provider employed by 898 the KMS. 900 createDate 902 The point in time when the authorization was created, in [RFC3339] 903 date-time format. 905 resourceUri 907 The object identifier of the resource to which the authorization 908 applies. 910 Note, with respect to this specification user identifiers are opaque, 911 however they MUST map to unique identifiers provided as part of user 912 authentication. 914 4.4.3. KMS Resource Objects (KRO) 916 The JSON representation for KMS resource objects is defined as 917 follows using JSON content rules with references to rules defined in 918 previous sections. 920 resourceRep { 921 kmsUri, 922 keys / keyUris, 923 authorizations / authorizationUris 924 } 926 resource ( 927 "resource" : resourceRep 928 ) 930 resources ( 931 "resources" : [ *resourceRep ] 932 ) 934 resourceUris ( 935 "resourceUris" : [ *kmsUri ] 936 ) 938 The attributes of a KMS resource object are defined as follows. 940 uri 942 A standard definition for KMS object identifiers. 944 keys 946 An array of key object representations, one for each key bound to 947 the resource. 949 keyUris 951 An array of key object identifiers, one for each key bound to the 952 resource. Only one of either keys or keyUris may be present in a 953 resource object representation. 955 authorizations 957 An array of authorization object representations, one for each 958 authorization on the resource. 960 authorizationUris 962 An array of authorization object identifiers, one for each 963 authorization on the resource. Only one of either authorizations 964 or authorizationUris may be present in a resource object 965 representation. 967 4.5. Request Types 969 The KMS protocol defines four types of requests: create, retrieve, 970 update, delete, each of which may be applied to one of the three KMS 971 object types. Note that not all object types support all requests 972 types. A KMS need only support those combinations of request type 973 and object type explicitly defined in this document. 975 Create 977 A create operation acts upon an object type, creating one or more 978 new instances of that object type. 980 Retrieve 982 A retrieve operation acts upon an object or object type, returning 983 in the response a representation of one or more object instances. 985 Update 987 An update operation acts upon an object, altering mutable 988 properties of that object. 990 Delete 992 A delete operation acts upon an object, removing that object from 993 the KMS. 995 4.6. Message Structure 997 Every KMS request and response message is composed of a JSON 998 [RFC7159] formatted payload encapsulated within either a JWE 999 [I-D.ietf-jose-json-web-encryption] or JWS 1000 [I-D.ietf-jose-json-web-signature] object. These messages may be 1001 divided into three types. 1003 Common Messages 1005 Common messages include all those which do not meet the definition 1006 of either key agreement message or error message. Common messages 1007 are encrypted as JWE objects using the shared ephemeral key 1008 established during initial key agreement between the client and 1009 KMS (see Section 4.7.1). The value of the JWE header "kid" 1010 attribute of a common message MUST match that of the KMS ephemeral 1011 key object URI attribute established during initial key agreement. 1013 Ephemeral Key Agreement Messages 1014 Ephemeral key agreement messages are those exchanged between the 1015 client and KMS for the purpose of establishing a new shared 1016 ephemeral key (see Section 4.7.1). Key agreement request payloads 1017 are encrypted as JWE objects using the authenticated and validated 1018 static public key of the KMS. Key agreement response payloads are 1019 signed as JWS objects using the static private key of the KMS. 1020 The value of the JWE or JWS header "kid" attribute of an ephemeral 1021 key agreement message MUST be a well known key identifier for the 1022 KMS static public key. 1024 Error Messages 1026 Error messages are those originated by the KMS to indicate a 1027 failed request. Error messages are composed in the same fashion 1028 as common messages; however, in the event that the KMS does not 1029 recognize the ephemeral key used in the request, or that key is 1030 determined to have expired, the KMS MUST respond with an 1031 unencrypted message composed as a JWS, with a payload as described 1032 in Section 4.6.3, and signed using the KMS server's static public 1033 key. 1035 The basic JSON representations for the request and response payloads 1036 are defined in the following sections. 1038 4.6.1. Basic Request Payload 1040 The basic JSON representation for KMS request message payloads is 1041 defined as follows using JSON content rules with references to rules 1042 defined in previous sections. 1044 requestId ( 1045 "requestId" : integer 1046 ) 1048 credential { 1049 "userId": ?string 1050 "bearer": string / "jwk": jwk 1051 } 1053 client { 1054 "clientId": string, 1055 "credential": credential 1056 ) 1058 method: string /create|retrieve|update|delete/ 1060 request ( 1061 "client" : client, 1062 "method" : method, 1063 kmsUri, 1064 requestId 1065 ) 1067 The attributes of a KMS request message payload are defined as 1068 follows. 1070 requestId 1072 A string selected by the client and provided in each request to 1073 uniquely identify the request. The string is treated opaquely by 1074 the server and returned verbatim in the associated response. 1076 userId 1078 The unique identifier of the user making the request. This field 1079 is optional, and MUST be disregarded if the requesting user's 1080 identity can be securely derived from either the bearer token or 1081 jwk. 1083 bearer 1085 An [RFC6749] access token issued by the client's identity provider 1086 and validated by the KMS in cooperation with the identity 1087 provider. See Section 4.2. 1089 jwk 1090 A JWK object, in JSON format as defined in 1091 [I-D.ietf-jose-json-web-key], containing the public key of the 1092 client (presumably a server). This JWK MUST contain an x5c header 1093 with a certificate chain that may be used to positively validate 1094 the public key. 1096 clientId 1098 An opaque unique identifier provided by the client (not used for 1099 authentication, only to assist multiple clients of a single user 1100 in differentiating between their respective unbound keys). 1102 method 1104 Indicates the request type: create, retrieve, update, or delete. 1106 uri 1108 The KMS object or object type to which the request applies. 1110 The JSON content rules above are used in conjunction with additional 1111 request type specific rules, defined later in this document, to 1112 produce the full request payload definition for each KMS operation. 1114 4.6.2. Basic Response Payload 1116 The basic JSON representation for KMS request message payloads is 1117 defined as follows using JSON content rules with references to rules 1118 defined in previous sections. 1120 response ( 1121 "status" : integer, 1122 ?"reason" : string, 1123 requestId 1124 ) 1126 The attributes of a KMS request message payload are defined as 1127 follows. 1129 status 1131 Indicates the success or failure of the request. The value 1132 returned in a response status attribute SHOULD be that of an 1133 [RFC7231] defined status code with semantics that correspond to 1134 the success or failure condition of the KMS request. 1136 reason 1137 An optional natural language string to describe the response 1138 status in terms that are useful for tracing and troubleshooting 1139 the API. 1141 requestId 1143 An echo of the requestId provided in the request. 1145 The JSON content rules above are used in conjunction with additional 1146 response type specific rules, defined later in this document, to 1147 produce the full response payload definition for each KMS operation. 1149 4.6.3. Error Response Payload 1151 The JSON representation for KMS error response message payloads is 1152 defined as follows using JSON content rules with references to rules 1153 defined in previous sections. 1155 Error response payload definition: 1157 root { 1158 response 1159 } 1161 Error response message example: 1163 JWS(K_kms_priv, { 1164 "status": 403, 1165 "reason": "The ephemeral key used in the request has expired.", 1166 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5" 1167 }) 1169 4.7. Requests 1171 The following sections provide detailed descriptions for each of the 1172 request and response operations that may occur between a resource 1173 client and the KMS. 1175 4.7.1. Create Ephemeral Key 1177 The first operation between a client and KMS MUST be the 1178 establishment of a shared secret and derived ephemeral key. This is 1179 necessary as all other requests and responses are encrypted with the 1180 ephemeral key. 1182 The client request for creating an ephemeral key conforms to the 1183 basic request message payload, where the method is "create" and the 1184 uri is "/ecdhe". In addition to the basic payload, the client 1185 provides a jwk attribute for which the value is a JWK object 1186 [I-D.ietf-jose-json-web-key] containing the public part of an EC key 1187 pair generated by the client. Unlike a basic request message, 1188 however, the request payload is encrypted as the content of a JWE 1189 [I-D.ietf-jose-json-web-key] secured with the static public key of 1190 the KMS server (K_kms_pub) as obtained from the server's validated 1191 PKIX certificate [RFC5280]. 1193 Note, the client MUST generate a new EC key pair for every create 1194 ephemeral key request sent to the KMS server. 1196 Request payload definition: 1198 root { 1199 request, 1200 jwk 1201 } 1203 Request message example: 1205 JWE(K_kms_pub, { 1206 "client": { 1207 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1208 "credential": { 1209 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1210 } 1211 }, 1212 "method": "create", 1213 "uri": "/ecdhe", 1214 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1215 "jwk" : { 1216 "kty": "EC", 1217 "crv": "P-256", 1218 "x": "VoFkf6Wk5kDQ1ob6csBmiMPHU8jALwdtaap35Fsj20M", 1219 "y": "XymwN6u2PmsKbIPy5iij6qZ-mIyej5dvZWB_75lnRgQ" 1220 } 1221 }) 1223 On receiving the ephemeral key creation request, the KMS server MUST 1224 verify the credential provided in the request. If a bearer token is 1225 provided, the KMS MUST validate the token in cooperation with the 1226 identity provider. If a jwk is provided, the KMS MUST validate the 1227 included PKIX certificate chain against the KMS server's trust root. 1228 In either case, the identity of the requesting client MUST be 1229 authenticated and verified to correspond to either an authorized user 1230 of the KMS or an authorized trusted service. If verification fails, 1231 the KMS MUST NOT use the server response to continue with key 1232 agreement. 1234 Upon successful authentication and authorization of the request, the 1235 KMS responds by generating its own EC key pair using the same curve 1236 as indicated in the "crv" attribute of the request message JWK. The 1237 KMS server returns the public part of this key pair to the resource 1238 client in the form of a KMS key object within the response payload. 1239 The KMS also generates and includes within the response payload a new 1240 key uri to be regarded by both client and KMS as the key identifier 1241 of the agreed upon ephemeral key. The response payload is returned 1242 to the resource client as the content of a JWS 1243 [I-D.ietf-jose-json-web-signature] signed using the static private 1244 key of the KMS server (K_kms_priv). 1246 Response payload definition: 1248 root { 1249 response, 1250 key 1251 } 1253 Response message example: 1255 JWS(K_kms_priv, { 1256 "status": 201, 1257 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1258 "key": { 1259 "uri": "/ecdhe/ea9f3858-1240-4328-ae22-a15f6072306f", 1260 "jwk" : { 1261 "kty": "EC", 1262 "crv": "P-256", 1263 "x": "8mdasnEZac2LWxMwKExikKU5LLacLQlcOt7A6n1ZGUC", 1264 "y": "lxs7ln5LtZUE_GE7yzc6BZOwBxtOftdsr8HVh-14ksS" 1265 }, 1266 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1267 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1268 "createDate": "2014-10-09T15:54:48Z", 1269 "expirationDate": "2014-10-09T16:54:48Z" 1270 } 1271 }) 1273 If successful, the KMS response to a create ephemeral key request 1274 MUST have a status of 201. In the case of a request failure, the KMS 1275 response status SHOULD be that of an [RFC7231] defined status code 1276 with semantics that correspond to the failure condition. In 1277 addition, the ephemeral key SHOULD have the createDate assigned as 1278 the current time and an expirationDate assigned as the latest point 1279 in time before which the key may be used for encrypting messages 1280 (both in [RFC3339] date-time format). 1282 On receiving the ephemeral key creation response, the resource client 1283 MUST verify the received JWS against the KMS server's validated 1284 static public key. If verification fails, the client MUST NOT use 1285 the server response to continue with key agreement. 1287 To generate the shared secret, both resource client and KMS server 1288 use ECDH shared secret derivation with the private part of the local 1289 EC key pair and the public part of the remote EC key pair. The 1290 shared secret is then provided as input to HKDF (with both extract 1291 and expand, and empty salt) [RFC5869] to generate the ephemeral key 1292 (K_ephemeral). 1294 The ephemeral key generated by this operation is used to encrypt all 1295 subsequent KMS requests and responses passed between the resource 1296 client and KMS. When encrypting such a message, the sender MUST 1297 assign a value to the kid attribute of the header of the resulting 1298 JWE object, and this value MUST match the URL of the key as provided 1299 to the client in the KMS response message described above. This 1300 provides the recipient with a means for identifying the key necessary 1301 to decrypt the message. 1303 The KMS SHOULD accept messages encrypted with the ephemeral key up to 1304 and until the key expiration date as provided in the response message 1305 described above. On expiration of the ephemeral key, the KMS MUST 1306 reject all further requests submitted using this key, and a client 1307 wishing to submit further requests to the KMS MUST re-establish the 1308 secure channel by requesting the creation of a new ephemeral key. 1310 4.7.2. Delete Ephemeral Key 1312 In the event that a resource client's ephemeral key has become 1313 compromised, a client SHOULD submit a request to the KMS to delete 1314 the ephemeral key. 1316 The request message conforms to the basic request message structure, 1317 where the method is "delete", and the uri is that of the ephemeral 1318 key to be deleted. 1320 Request payload definition: 1322 root { 1323 request 1324 } 1326 Request message example: 1328 JWE(K_ephemeral, { 1329 "client": { 1330 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1331 "credential": { 1332 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1333 } 1334 } 1335 "method": "delete", 1336 "uri": "/ecdhe/ea9f3858-1240-4328-ae22-a15f6072306f", 1337 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5" 1338 }) 1340 The response message conforms to the basic response message 1341 structure, and MUST NOT include a representation of the deleted 1342 ephemeral key. 1344 Response payload definition: 1346 root { 1347 response 1348 } 1350 Response message example: 1352 JWE(K_ephemeral, { 1353 "status": 204, 1354 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5" 1355 }) 1357 If successful, the KMS response to a delete ephemeral key request 1358 MUST have a status of 204. In the case of a request failure, the KMS 1359 response status SHOULD be that of an [RFC7231] defined status code 1360 with semantics that correspond to the failure condition. 1362 On successful deletion of an ephemeral key, the KMS MUST NOT, from 1363 that time forward, accept any requests encrypted with that ephemeral 1364 key. 1366 4.7.3. Create Resource 1368 When a client intends to initiate E2E encryption of a communications 1369 resource, it begins by requesting the creation of a KMS resource 1370 object. This resource object logically represents the communications 1371 resource within the KMS data model. 1373 As part of a create resource request, a KMS server MUST create at 1374 least one authorization object on the newly created resource object 1375 to explicitly authorize the user making the request. A client MAY 1376 request the immediate creation of one or more additional 1377 authorizations such that corresponding users may be immediately 1378 authorized to access and operate on the new resource object. If for 1379 any reason one or more requested authorizations cannot be applied to 1380 the new resource object, the entire create resource request MUST be 1381 failed by the KMS. 1383 As part of a create resource request, a client MAY request the 1384 immediate binding of one or more unbound KMS keys to the new resource 1385 object. If any key indicated in the request is already bound, or is 1386 otherwise invalid (e.g. expired), the entire create resource request 1387 MUST be failed by the KMS. 1389 The request message conforms to the basic request message structure, 1390 where the method is "create", the uri is "/resources", and additional 1391 user identifiers and/or key URIs are provided in a manner consistent 1392 with the following. 1394 Request payload definition: 1396 authIds ( 1397 "authIds" : [ *string ] 1398 ) 1400 root { 1401 request, 1402 ?authIds, 1403 ?keyUris 1404 } 1406 Request message example: 1408 JWE(K_ephemeral, { 1409 "client": { 1410 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1411 "credential": { 1412 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1413 } 1414 } 1415 "method": "create", 1416 "uri": "/resources", 1417 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1418 "authIds": [ 1419 "b46e8124-b6e8-47e0-af0d-e7f1a2072dac", 1420 "39d56a84-c6f9-459e-9fd1-40ab4ad3e89a" 1421 ], 1422 "keyUris": [ 1423 "/keys/b4cba4da-a984-4af2-b54f-3ca04acfe461", 1424 "/keys/2671413c-ab80-4f19-a0a4-ae07e1a94e90" 1425 ] 1426 }) 1428 The response message conforms to the basic response message 1429 structure, and includes a representation of the created KMS resource 1430 object. 1432 Response payload definition: 1434 root { 1435 response, 1436 resource 1437 } 1439 Response message example: 1441 JWE(K_ephemeral, { 1442 "status": 201, 1443 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1444 "resource": { 1445 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094", 1446 "authorizationUris": [ 1447 "/authorizations/50e9056d-0700-4919-b55f-84cd78a2a65e", 1448 "/authorizations/db4c95ab-3fbf-42a8-989f-f53c1f13cc9a" 1449 ], 1450 "keyUris": [ 1451 "/keys/b4cba4da-a984-4af2-b54f-3ca04acfe461", 1452 "/keys/2671413c-ab80-4f19-a0a4-ae07e1a94e90" 1453 ] 1454 } 1455 }) 1456 If successful, the KMS response to a create resource request MUST 1457 have a status of 201. In the case of a request failure, the KMS 1458 response status SHOULD be that of an [RFC7231] defined status code 1459 with semantics that correspond to the failure condition. 1461 4.7.4. Retrieve Resource 1463 A client that is authorized on a given KMS resource object may 1464 retrieve the current state of that object as well as that of current 1465 set of KMS authorization objects and bound KMS keys. 1467 The request message conforms to the basic request message structure, 1468 where the method is "retrieve", and the uri is that of the KMS 1469 resource object as returned by the create operation from which it 1470 originated. 1472 Request payload definition: 1474 root { 1475 request 1476 } 1478 Request message example: 1480 JWE(K_ephemeral, { 1481 "client": { 1482 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1483 "credential": { 1484 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1485 } 1486 } 1487 "method": "retrieve", 1488 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094", 1489 "requestId": "db1e4d2a-d483-4fe7-a802-ec5c0d32295f", 1490 }) 1492 The response message conforms to the basic response message 1493 structure, and includes a representation of the retrieved KMS 1494 resource object. 1496 Response payload definition: 1498 root { 1499 response, 1500 resource 1501 } 1503 Response message example: 1505 JWE(K_ephemeral, { 1506 "status": 200, 1507 "requestId": "db1e4d2a-d483-4fe7-a802-ec5c0d32295f", 1508 "resource": { 1509 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094", 1510 "authorizationUris": [ 1511 "/authorizations/50e9056d-0700-4919-b55f-84cd78a2a65e", 1512 "/authorizations/db4c95ab-3fbf-42a8-989f-f53c1f13cc9a" 1513 ], 1514 "keyUris": [ 1515 "/keys/b4cba4da-a984-4af2-b54f-3ca04acfe461", 1516 "/keys/2671413c-ab80-4f19-a0a4-ae07e1a94e90" 1517 ] 1518 } 1519 }) 1521 If successful, the KMS response to a retrieve resource request MUST 1522 have a status of 200. In the case of a request failure, the KMS 1523 response status SHOULD be that of an [RFC7231] defined status code 1524 with semantics that correspond to the failure condition. 1526 4.7.5. Create Keys 1528 When a client requires a symmetric key for use in the E2E encryption 1529 of a communications resource, it begins by requesting the creation of 1530 one or more keys from the KMS. The initial state of a newly created 1531 key is "unbound" in the sense that it does not yet belong to a 1532 particular resource. A client may submit this request at any time, 1533 even before the communications resource exists. The keys returned by 1534 this request are unbound, which is to say not yet associated with any 1535 KMS resource object. 1537 The request message conforms to the basic request message structure, 1538 where the method is "create", the uri is "/keys", and an additional 1539 count attribute is introduced to indicate the number of keys to be 1540 created. 1542 Request payload definition: 1544 root { 1545 request, 1546 "count": integer 1547 } 1549 Request message example: 1551 JWE(K_ephemeral, { 1552 "client": { 1553 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1554 "credential": { 1555 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1556 } 1557 } 1558 "method": "create", 1559 "uri": "/keys", 1560 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1561 "count": 2 1562 }) 1564 The response message conforms to the basic response message structure 1565 with the addition of an array of key object representations, one for 1566 each unbound key created. 1568 Response payload definition: 1570 root { 1571 response, 1572 keys / keyUris 1573 } 1575 Response message example: 1577 JWE(K_ephemeral, { 1578 "status": 201, 1579 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1580 "keys": [ 1581 { 1582 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1583 "jwk": { 1584 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1585 "kty": "oct", 1586 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1587 } 1588 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1589 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1590 "createDate": "2014-10-09T15:54:48Z", 1591 "expirationDate": "2014-10-09T16:04:48Z" 1592 }, 1593 { 1594 "uri": "/keys/fed33890-f9fa-43ad-a9f8-ab55a983a543", 1595 "jwk": { 1596 "kid": "fed33890-f9fa-43ad-a9f8-ab55a983a543", 1597 "kty": "oct", 1598 "k": "q2znCXQpbBPSZBUddZvchRSH5pSSKPEHlgb3CSGIdpL" 1599 } 1600 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1601 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1602 "createDate": "2014-10-09T15:54:48Z", 1603 "expirationDate": "2014-10-09T16:04:48Z" 1604 } 1605 ] 1606 }) 1608 Each key object in the response to a create unbound keys request 1609 includes a single JWK [I-D.ietf-jose-json-web-key] representing a new 1610 symmetric key of 256 bits generated by a cryptographically secure 1611 PRNG. Note that, as unbound keys, the resourceUri attribute of each 1612 key is either undefined or null. All keys SHOULD have the createDate 1613 assigned as the current time and an expirationDate assigned as the 1614 latest point in time before which the key may be bound to a resource 1615 (both in [RFC3339] date-time format). 1617 The clientId attribute of each created key MUST be the clientId 1618 provided by the client in the client.clientId attribute of the 1619 request. 1621 As shown in the response payload definition, the KMS MUST return 1622 either an array of key object representations or an array of key 1623 object uris. It is at the KMS server's discretion which of these is 1624 returned. 1626 If successful, the KMS response to a create unbound keys request MUST 1627 have a status of 201. In the case of a request failure, the KMS 1628 response status SHOULD be that of an [RFC7231] defined status code 1629 with semantics that correspond to the failure condition. 1631 4.7.6. Update Key (Bind) 1633 To initiate the use of an unbound KMS key in securing a 1634 communications resource, a client will create a corresponding KMS 1635 resource object and subsequently bind the unbound key to that 1636 resource. A client MAY begin using an unbound KMS key to encrypt a 1637 communications resource prior to the binding of that key. 1639 The request message conforms to the basic request message structure, 1640 where the method is "update", the uri is that of the key to be bound, 1641 and an additional resourceUri attribute is introduced to indicate the 1642 KMS resource object to which the key is to be bound. If the user 1643 making a bind unbound key request does not have an authorization on 1644 the resource indicated by the resourceUri, or is not the user for 1645 whom the unbound key was originally created, the KMS MUST fail the 1646 request. The KMS SHOULD fail the request if the clientId of the 1647 request does not match that of the unbound key. 1649 Request payload definition: 1651 root { 1652 request, 1653 "resourceUri" : kmsUri 1654 } 1656 Request message example: 1658 JWE(K_ephemeral, { 1659 "client": { 1660 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1661 "credential": { 1662 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1663 } 1664 } 1665 "method": "update", 1666 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1667 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1668 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1669 }) 1671 The response message conforms to the basic response message 1672 structure, and includes a representation of the full state of the 1673 newly bound key. 1675 Response payload definition: 1677 root { 1678 response, 1679 key 1680 } 1682 Response message example: 1684 JWE(K_ephemeral, { 1685 { 1686 "status": 200, 1687 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1688 "key": { 1689 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1690 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1691 "jwk": { 1692 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1693 "kty": "oct", 1694 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1695 } 1696 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1697 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1698 "createDate": "2014-10-09T15:54:48Z", 1699 "bindDate": "2014-10-09T15:55:34Z", 1700 "expirationDate": "2014-10-10T15:55:34Z", 1701 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1702 } 1703 }) 1705 On successfully binding a formerly unbound KMS key to a resource 1706 object, the state of the KMS key object MUST reflect the updated 1707 resourceUri attribute, MUST reflect a bindDate as the current time, 1708 and MUST reflect an expirationDate as the time after which clients 1709 MUST NOT use this key for encryption as provided by KMS policy. 1710 Subsequently, the KMS MUST regard the key as bound to the KMS 1711 resource object identified by the resourceUri and MUST reject 1712 subsequent requests to bind the same key to any other resource 1713 object. 1715 If successful, the KMS response to a bind unbound key request MUST 1716 have a status of 200. In the case of a request failure, the KMS 1717 response status SHOULD be that of an [RFC7231] defined status code 1718 with semantics that correspond to the failure condition. 1720 4.7.7. Retrieve Keys 1722 Clients engaging in E2E encryption require a means for retrieving 1723 keys from the KMS. A key request may take one of three forms, it may 1724 be a request for 1726 o a specific key, 1728 o all keys bound to a particular resource, 1730 o a subset of keys bound to a particular resource. 1732 In all cases, the request message conforms to the basic request 1733 message structure with "retrieve" as the value for the method 1734 attribute. 1736 To retrieve an individual key, the uri of the request is that of the 1737 key object to be retrieved. If the key is unbound, the KMS MUST 1738 reject the request unless it originates from the user that requested 1739 the key's creation, and SHOULD reject the request unless it 1740 originates from the same client that requested the key's creation (as 1741 determined by clientId). If the key is bound, the KMS MUST reject 1742 the request if the request originates from a user for which there 1743 does not exist a corresponding authorization on the resource to which 1744 the requested key is bound. 1746 To retrieve all keys bound to a resource, the uri of the request is 1747 that of the resource concatenated with "/keys". The KMS MUST reject 1748 the request if the request originates from a user for which there 1749 does not exist a corresponding authorization on the resource. 1751 To retrieve a subset of keys bound to a resource, the client submits 1752 a request in the same fashion as for requesting all keys but also 1753 includes one or more additional attributes indicating selection 1754 criteria. These additional attributes include the following: 1756 o boundAfter 1758 o boundBefore 1760 Each of these parameters is optional and clients MAY employ them in 1761 any combination. 1763 If the request includes a "boundAfter" attribute, the value MUST 1764 conform to the [RFC3339] date-time format and the KMS response MUST 1765 NOT include any key with a "bindDate" that chronologically precedes 1766 it. Similarly, if the request includes a "boundBefore" attribute, 1767 the value MUST conform to the [RFC3339] date-time format and the KMS 1768 response MUST NOT include any key with a "bindDate" that is either 1769 equal to or chronologically subsequent to it. 1771 To limit the number of keys returned in a KMS response, a client MAY 1772 include a "count" attribute. If the request includes a "count" 1773 attribute, it must be of JSON type integer and the cardinality of the 1774 set of keys returned in the KMS response MUST NOT exceed its value. 1775 In the event it becomes necessary for the KMS to truncate the set of 1776 keys included in the KMS response, due to the limitations imposed by 1777 the "count" attribute, the truncated subset MUST be composed of those 1778 keys which satisfy the request's other selection criteria (if any) 1779 and also constitute a subset of that selection for which the elements 1780 possess the chronologically largest "bindDate" values. 1782 Request payload definition: 1784 root { 1785 request, 1786 ?"boundAfter" : date-time, 1787 ?"boundBefore" : date-time, 1788 ?"count" : integer 1789 } 1791 Request message example (individual key): 1793 JWE(K_ephemeral, { 1794 "client": { 1795 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1796 "credential": { 1797 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1798 } 1799 } 1800 "method": "retrieve", 1801 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1802 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5" 1803 }) 1805 Request message example (10 most recently bound keys): 1807 JWE(K_ephemeral, { 1808 "client": { 1809 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1810 "credential": { 1811 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1812 } 1813 } 1814 "method": "retrieve", 1815 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094/keys", 1816 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1817 "count": 10 1818 }) 1820 Request message example (keys bound after a given time, 25 max): 1822 JWE(K_ephemeral, { 1823 "client": { 1824 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1825 "credential": { 1826 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1827 } 1828 } 1829 "method": "retrieve", 1830 "uri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094/keys", 1831 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1832 "boundAfter": "2015-01-11T18:23:21Z", 1833 "count": 25 1834 }) 1836 The response message conforms to the basic response message structure 1837 and includes a representation of the key or keys selected by the 1838 request. When responding to a request for a specific key, the KMS 1839 will return a response that includes a KMS key object representation 1840 as described in Section 4.4.1. When responding to a request for 1841 multiple keys, the KMS will return a response that includes an array 1842 of KMS key object representations. 1844 Response payload definition: 1846 root { 1847 response, 1848 key / keys 1849 } 1851 Response message example (for specific key): 1853 JWE(K_ephemeral, { 1854 { 1855 "status": 200, 1856 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1857 "key": { 1858 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1859 "jwk": { 1860 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1861 "kty": "oct", 1862 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1863 } 1864 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1865 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1866 "createDate": "2014-10-09T15:54:48Z", 1867 "bindDate": "2014-10-09T15:55:34Z", 1868 "expirationDate": "2014-10-10T15:55:34Z", 1869 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1870 } 1871 }) 1873 Response message example (for keys bound to a specific resource): 1875 JWE(K_ephemeral, { 1876 { 1877 "status": 200, 1878 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1879 "keys": [ 1880 { 1881 "uri": "/keys/52100fa4-c222-46d0-994d-1ca885e4a3a2", 1882 "jwk": { 1883 "kid": "52100fa4-c222-46d0-994d-1ca885e4a3a2", 1884 "kty": "oct", 1885 "k": "ZMpktzGq1g6_r4fKVdnx9OaYr4HjxPjIs7l7SwAsgsg" 1886 } 1887 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1888 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1889 "createDate": "2014-10-09T15:54:48Z", 1890 "bindDate": "2014-10-09T15:55:34Z", 1891 "expirationDate": "2014-10-10T15:55:34Z", 1892 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1893 }, 1894 { 1895 "uri": "/keys/fed33890-f9fa-43ad-a9f8-ab55a983a543", 1896 "jwk": { 1897 "kid": "fed33890-f9fa-43ad-a9f8-ab55a983a543", 1898 "kty": "oct", 1899 "k": "q2znCXQpbBPSZBUddZvchRSH5pSSKPEHlgb3CSGIdpL" 1900 } 1901 "userId": "842e2d82-7e71-4040-8eb9-d977fe888807", 1902 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1903 "createDate": "2014-10-09T15:54:48Z", 1904 "bindDate": "2014-10-09T15:56:43Z", 1905 "expirationDate": "2014-10-10T15:56:43Z", 1906 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1907 }] 1908 }) 1910 If successful, the KMS response to a retrieve bound keys request MUST 1911 have a status of 200. In the case of a request failure, the KMS 1912 response status SHOULD be that of an [RFC7231] defined status code 1913 with semantics that correspond to the failure condition. 1915 4.7.8. Create Authorizations 1917 An authorization establishes a relationship between a resource and a 1918 user that entitles the user to retrieve bound keys from, and bind new 1919 keys to, that resource. The KMS resource authorization model is 1920 viral in the sense that, once a user has been authorized on a 1921 resource, that user is also entitled to authorize other users on that 1922 resource. These authorizations are created through create 1923 authorization requests. 1925 The request message conforms to the basic request message structure, 1926 where the method is "create", and the uri is "/authorizations". 1927 Additional attributes are required to indicate the resource on which 1928 authorizations are to be added, as well as the set of users for whom 1929 these new authorizations are to be created. 1931 root { 1932 request, 1933 "resourceUri" : kmsUri, 1934 "authIds" : [ *string ] 1935 } 1937 Request message example: 1939 JWE(K_ephemeral, { 1940 "client": { 1941 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 1942 "credential": { 1943 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 1944 } 1945 } 1946 "method": "create", 1947 "uri": "/authorizations", 1948 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1949 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094", 1950 "authIds": [ 1951 "119a0582-2e2b-4c0c-ba6a-753d05171803", 1952 "557ac05d-5751-43b4-a04b-e7eb1499ee0a" 1953 ] 1954 }) 1956 The response message conforms to the basic response message 1957 structure, and includes a representation of the set of KMS 1958 authorization objects created by the request. 1960 Response payload definition: 1962 root { 1963 response, 1964 authorizations 1965 } 1967 Response message example: 1969 JWE(K_ephemeral, { 1970 { 1971 "status": 201, 1972 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 1973 "authorizations": [ 1974 { 1975 "uri": "/authorizations/79a39ed9-a8e5-4d1f-9ae2-e27857fc5901", 1976 "authId": "119a0582-2e2b-4c0c-ba6a-753d05171803", 1977 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1978 }, 1979 { 1980 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b", 1981 "authId": "557ac05d-5751-43b4-a04b-e7eb1499ee0a", 1982 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 1983 }] 1984 }) 1986 If successful, the KMS response to a create authorizations request 1987 MUST have a status of 201. In the case of a request failure, the KMS 1988 response status SHOULD be that of an [RFC7231] defined status code 1989 with semantics that correspond to the failure condition. If for any 1990 reason one or more requested authorizations cannot be created or 1991 applied to the resource object, the entire create authorizations 1992 request MUST be failed by the KMS. 1994 4.7.9. Retrieve Authorizations 1996 A client may explicitly request the set of all authorizations on a 1997 given KMS resource object. The uri of the request is that of the 1998 resource concatenated with "/authorizations". The KMS MUST reject 1999 the request if the request originates from a user for which there 2000 does not exist a corresponding authorization on the resource. 2002 Request payload definition: 2004 root { 2005 request 2006 } 2008 Request message example: 2010 JWE(K_ephemeral, { 2011 "client": { 2012 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 2013 "credential": { 2014 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 2015 } 2016 } 2017 "method": "retrieve", 2018 "uri": "/resources/7f35c3eb-95d6-4558-1942e5f03094/authorizations", 2019 "requestId": "913d7ae3-8945-46ca-8ed1-2b287c1370ce" 2020 }) 2022 The response message conforms to the basic response message structure 2023 and includes an array of KMS authorization object representations. 2025 Response payload definition: 2027 root { 2028 response, 2029 authorizations 2030 } 2032 Response message example: 2034 JWE(K_ephemeral, { 2035 { 2036 "status": 200, 2037 "requestId": "913d7ae3-8945-46ca-8ed1-2b287c1370ce", 2038 "authorizations": [ 2039 { 2040 "uri": "/authorizations/79a39ed9-a8e5-4d1f-9ae2-e27857fc5901", 2041 "authId": "119a0582-2e2b-4c0c-ba6a-753d05171803", 2042 "resourceUri": "/resources/7f35c3eb-95d6-4558-1942e5f03094" 2043 }, 2044 { 2045 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b", 2046 "authId": "557ac05d-5751-43b4-a04b-e7eb1499ee0a", 2047 "resourceUri": "/resources/7f35c3eb-95d6-4558-1942e5f03094" 2048 }] 2049 }) 2051 If successful, the KMS response to a retrieve bound keys request MUST 2052 have a status of 200. In the case of a request failure, the KMS 2053 response status SHOULD be that of an [RFC7231] defined status code 2054 with semantics that correspond to the failure condition. 2056 4.7.10. Delete Authorization 2058 To remove an authorization from a KMS resource object, any user 2059 currently authorized on the same resource object may issue a delete 2060 authorization request. The request message conforms to the basic 2061 request message structure, where the method is "delete", and the URI 2062 is either that of the authorization object to be deleted, or the URI 2063 of the collection of authorizations within a particular KMS resource 2064 object appended with an authId query parameter whose value matches 2065 that of the authorization object to be deleted. 2067 Request payload definition: 2069 root { 2070 request 2071 } 2073 Request message example, explicitly identifying the URI of the 2074 authorization object to be deleted: 2076 JWE(K_ephemeral, { 2077 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 2078 "client": { 2079 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 2080 "credential": { 2081 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 2082 } 2083 } 2084 "method": "delete", 2085 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b" 2086 }) 2088 Request message example, implicitly identifying the authorization 2089 object to be deleted by the KMS resource object to which it belongs 2090 plus the value of its authId attribute: 2092 JWE(K_ephemeral, { 2093 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 2094 "client": { 2095 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 2096 "credential": { 2097 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 2098 } 2099 } 2100 "method": "delete", 2101 "uri": "/resources/7f35c3eb-95d6-4558-1942e5f03094 2102 /authorizations?authId=557ac05d-5751-43b4-a04b-e7eb1499ee0a", 2103 }) 2104 Note, in the example above, the URI attribute value is a continuous 2105 string of non-whitespace characters. Whitespace has been added here 2106 for readability. 2108 The response message conforms to the basic response message 2109 structure, and includes a representation of the authorization object 2110 that was deleted. 2112 Response payload definition: 2114 root { 2115 response, 2116 ?authorization 2117 } 2119 Response message example: 2121 JWE(K_ephemeral, { 2122 { 2123 "status": 200, 2124 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 2125 "authorization": { 2126 "uri": "/authorizations/5aaca3eb-ca4c-47c9-b8e2-b20f47568b7b", 2127 "authId": "557ac05d-5751-43b4-a04b-e7eb1499ee0a", 2128 "resourceUri": "/resources/7f35c3eb-95d6-4558-a7fc-1942e5f03094" 2129 } 2130 }) 2132 If successful, the KMS response to a delete authorization request 2133 MUST have a status of 200 if the authorization object representation 2134 is included, and 204 if not. In the case of a request failure, the 2135 KMS response status SHOULD be that of an [RFC7231] defined status 2136 code with semantics that correspond to the failure condition. 2138 4.7.11. Ping 2140 Ping is a simple request intended to provide an efficient means for 2141 verifying the integrity of the secure channel between client and KMS. 2142 Ping MUST be implemented as a safe and idempotent operation that 2143 causes the server to do nothing more than return a basic response 2144 payload in reaction to the client request. The method of a ping 2145 request is "update" and the uri is "/ping". 2147 Request payload definition: 2149 root { 2150 request 2151 } 2152 Request message example: 2154 JWE(K_ephemeral, { 2155 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5", 2156 "client": { 2157 "clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f", 2158 "credential": { 2159 "bearer": "ZWU5NGE2YWYtMGE2NC0..." 2160 } 2161 } 2162 "method": "update", 2163 "uri": "/ping" 2164 }) 2166 The response message conforms to the basic response message structure 2167 with no additional data. 2169 Response payload definition: 2171 root { 2172 response 2173 } 2175 Response message example: 2177 JWE(K_ephemeral, { 2178 { 2179 "status": 200, 2180 "requestId": "10992782-e096-4fd3-9458-24dca7a92fa5" 2181 }) 2183 If successful, the client may deduce that the KMS was able to 2184 successfully decrypt the received KMS request message, parse the 2185 contents, confirm the identity and authorization of the requesting 2186 client, and return a suitable response. 2188 5. Mandatory-to-Implement 2190 Implementations MUST support the following JWK key types from 2191 [I-D.ietf-jose-json-web-algorithms]: 2193 o "RSA" for the KMS static public/private key 2195 o "EC" for the Ephemeral Diffie Hellman exchange 2197 o "oct" for all symmetric keys 2198 Implementations MUST support "PS256" (RSASSA-PSS using SHA-256 and 2199 MGF1 with SHA-256) from [I-D.ietf-jose-json-web-algorithms] for 2200 signatures using the KMS static public/private key for Section 4.7.1. 2202 Implementations MUST support JWK Elliptic Curve type "P-256" (NIST 2203 P-256 curve) from [I-D.ietf-jose-json-web-algorithms] for 2204 Section 4.7.1. 2206 Implementations MUST support "RSA-OAEP" (RSAES OAEP using default 2207 parameters) from [I-D.ietf-jose-json-web-algorithms] for key 2208 encryption using the KMS static public/private key for Section 4.7.1. 2210 Implementations MUST support "dir" (Direct Key Agreement Key 2211 Management Mode) from [I-D.ietf-jose-json-web-algorithms] for all 2212 operations other than Section 4.7.1. 2214 Implementations MUST support "A256GCM" (AES GCM using 256 bit key) 2215 from [I-D.ietf-jose-json-web-algorithms] for content encryption for 2216 all operations other than Section 4.7.1. 2218 6. Security Considerations 2220 Security considerations are discussed throughout this document. 2221 Additional considerations may be added here as needed. 2223 7. Appendix A. Acknowledgments 2225 This specification is the work of several contributors. In 2226 particular, the following individuals contributed ideas, feedback, 2227 and wording that influenced this specification: 2229 Cullen Jennings, Matt Miller, Suhas Nandakumar, Jonathan Rosenberg 2231 8. Appendix B. Document History 2233 -00 2235 o Initial draft. 2237 9. References 2239 9.1. Normative References 2241 [I-D.ietf-jose-json-web-algorithms] 2242 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 2243 json-web-algorithms-33 (work in progress), September 2014. 2245 [I-D.ietf-jose-json-web-encryption] 2246 Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2247 draft-ietf-jose-json-web-encryption-33 (work in progress), 2248 September 2014. 2250 [I-D.ietf-jose-json-web-key] 2251 Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 2252 key-33 (work in progress), September 2014. 2254 [I-D.ietf-jose-json-web-signature] 2255 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2256 Signature (JWS)", draft-ietf-jose-json-web-signature-33 2257 (work in progress), September 2014. 2259 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2260 Requirement Levels", BCP 14, RFC 2119, March 1997. 2262 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 2263 2001. 2265 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 2266 Internet: Timestamps", RFC 3339, July 2002. 2268 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 2269 4949, August 2007. 2271 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2272 Housley, R., and W. Polk, "Internet X.509 Public Key 2273 Infrastructure Certificate and Certificate Revocation List 2274 (CRL) Profile", RFC 5280, May 2008. 2276 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2277 Key Derivation Function (HKDF)", RFC 5869, May 2010. 2279 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2280 Verification of Domain-Based Application Service Identity 2281 within Internet Public Key Infrastructure Using X.509 2282 (PKIX) Certificates in the Context of Transport Layer 2283 Security (TLS)", RFC 6125, March 2011. 2285 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 2286 6749, October 2012. 2288 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2289 Interchange Format", RFC 7159, March 2014. 2291 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2292 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2294 9.2. Informative References 2296 [I-D.barnes-pervasive-problem] 2297 Barnes, R., Schneier, B., Jennings, C., and T. Hardie, 2298 "Pervasive Attack: A Threat Model and Problem Statement", 2299 draft-barnes-pervasive-problem-01 (work in progress), July 2300 2014. 2302 [I-D.ietf-xmpp-posh] 2303 Miller, M. and P. Saint-Andre, "PKIX over Secure HTTP 2304 (POSH)", draft-ietf-xmpp-posh-02 (work in progress), 2305 October 2014. 2307 [I-D.newton-json-content-rules] 2308 Newton, A., "A Language for Rules Describing JSON 2309 Content", draft-newton-json-content-rules-02 (work in 2310 progress), August 2014. 2312 [OTR] Borisov, N., Goldberg, I., and E. Brewer, "Off-the-Record 2313 Communication, or, Why Not To Use PGP", 2012, 2314 . 2316 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 2317 Internet Protocol", RFC 4301, December 2005. 2319 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 2320 Thayer, "OpenPGP Message Format", RFC 4880, November 2007. 2322 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2323 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2325 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2326 RFC 5652, September 2009. 2328 Authors' Addresses 2330 Andrew Biggs 2331 Cisco Systems 2333 Email: adb@cisco.com 2335 Shaun Cooley 2336 Cisco Systems 2338 Email: shcooley@cisco.com