Internet DRAFT - draft-abiggs-saag-key-management-service
draft-abiggs-saag-key-management-service
Network Working Group A. Biggs
Internet-Draft S. Cooley
Intended status: Standards Track Cisco Systems
Expires: May 6, 2016 November 03, 2015
Key Management Service Architecture
draft-abiggs-saag-key-management-service-03
Abstract
In the interest of addressing pervasive threats to the
confidentiality and integrity of online communications identified by
the Internet community [I-D.barnes-pervasive-problem] this
specification introduces an open architecture for the establishment,
management, and secure distribution of cryptographic keys for use in
the end-to-end (E2E) encryption of online communications and shared
content. This architecture allows for the independent deployment of
dedicated key management services in a manner that supports the
adoption of third-party communications and data sharing services by
individuals and organizations that require full and exclusive
discretion over the confidentiality of their data.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 6, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
Biggs & Cooley Expires May 6, 2016 [Page 1]
Internet-Draft key-management-service November 2015
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Security Terms . . . . . . . . . . . . . . . . . . . . . 5
1.3. Notational Conventions . . . . . . . . . . . . . . . . . 6
2. Architectural Overview . . . . . . . . . . . . . . . . . . . 6
3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1. Securing an HTTP File Sharing Service . . . . . . . . . . 9
3.2. Securing an XMPP Multi-User Chat . . . . . . . . . . . . 11
3.3. KMS to KMS Key Federation . . . . . . . . . . . . . . . . 13
4. KMS Protocol . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1. Secure Channel . . . . . . . . . . . . . . . . . . . . . 16
4.2. User Identity . . . . . . . . . . . . . . . . . . . . . . 16
4.3. KMS Identity . . . . . . . . . . . . . . . . . . . . . . 17
4.4. Object Types . . . . . . . . . . . . . . . . . . . . . . 18
4.5. Message Structure . . . . . . . . . . . . . . . . . . . . 18
4.5.1. Basic Request Payload . . . . . . . . . . . . . . . . 19
4.5.2. Basic Response Payload . . . . . . . . . . . . . . . 21
4.5.3. Error Response Payload . . . . . . . . . . . . . . . 21
4.6. Requests . . . . . . . . . . . . . . . . . . . . . . . . 22
4.6.1. Create Ephemeral Key . . . . . . . . . . . . . . . . 22
4.6.2. Delete Ephemeral Key . . . . . . . . . . . . . . . . 25
4.6.3. Post GMBC Block (genesis) . . . . . . . . . . . . . . 26
4.6.4. Post GMBC Block (append) . . . . . . . . . . . . . . 28
4.6.5. Get GMBC . . . . . . . . . . . . . . . . . . . . . . 30
4.6.6. Post GK (create) . . . . . . . . . . . . . . . . . . 31
4.6.7. Post GK (update) . . . . . . . . . . . . . . . . . . 33
4.6.8. Get GK . . . . . . . . . . . . . . . . . . . . . . . 35
4.6.9. Ping . . . . . . . . . . . . . . . . . . . . . . . . 37
5. Security Considerations . . . . . . . . . . . . . . . . . . . 38
6. Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . 38
7. Appendix B. Document History . . . . . . . . . . . . . . . . 38
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 39
8.1. Normative References . . . . . . . . . . . . . . . . . . 39
8.2. Informative References . . . . . . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41
Biggs & Cooley Expires May 6, 2016 [Page 2]
Internet-Draft key-management-service November 2015
1. Introduction
Providers of cloud-based services commonly secure user data at the
transport level using established protocols such as TLS [RFC5246] or
IPSec [RFC4301]. These protocols can be effective in protecting
transmitted user data from third party tampering and eavesdropping;
however, by themselves these protocols do not secure user data from
abuses, negligence, or coerced behavior on the part of the cloud
provider. This is a concern for individuals and organizations that
wish to take advantage of cloud-based communications and
collaboration but cannot accept the risk of trusting cloud providers
with unfettered access to the contents of their communications.
E2E encryption describes a category of solutions that can be employed
to address this problem by establishing secure channels among
clients. To the extent that a user can trust their collaboration
client software, E2E encryption mitigates exposure of user data to
untrusted parties by ensuring that intermediaries never possess
unencrypted user data or have access to the keying material necessary
to decrypt it.
Existing E2E strategies such as ECS [RFC5652], PGP [RFC4880], and
Off-the-Record Messaging [OTR] can be effective at securing two-party
communications. However, E2E encryption for the growing domain of
multiparty communications and online content sharing remains a
generally unsolved problem to which these existing approaches do not
readily adapt. In particular, a core challenge exists in providing
for the secure distribution and rotation of E2E encryption keys among
an arbitrary and potentially dynamic set of communicating clients.
In cases where the communications to be secured are persistent or
archived, the additional challenge exists for providing trusted long-
term storage and retrieval of these keys.
Equally problematic is the paucity of E2E encryption options that
satisfy common organizational obligations such as regulatory
compliance and legal discovery. Entities that must operate within
such frameworks require mechanisms by which they (and they alone) may
recover the keys used to secure their communications. Existing E2E
encryption solutions are not, by themselves, well suited for this
purpose.
In the interest of addressing these challenges, this document
presents an architecture for the deployment of E2E encryption key
management services (KMS) based on the curator role described in
[I-D.abiggs-saag-primitives-for-conf-group-comms].
In the interest of addressing these challenges, this document
presents an architecture for the deployment of E2E encryption key
Biggs & Cooley Expires May 6, 2016 [Page 3]
Internet-Draft key-management-service November 2015
management services (KMS). In this architecture a KMS service
provides to its users a means by which their communications clients
may securely create, share, rotate, and store E2E encryption keying
material. It does so in a fashion that permits the decoupling of
such services from the communications media, thereby permitting the
former to reside under the direct control of the communicating
parties or the organizations within which they do business.
1.1. Terminology
This document uses the terminology from
[I-D.ietf-jose-json-web-signature],
[I-D.ietf-jose-json-web-encryption], [I-D.ietf-jose-json-web-key],
and [I-D.ietf-jose-json-web-algorithms] when discussing JOSE
technologies.
This document uses the terminology from
[I-D.abiggs-saag-primitives-for-conf-group-comms] when discussing
authentication, group membership, and secure key exchange.
This document makes use of the following terminology, and
additionally adopts nomenclature defined in
[I-D.barnes-pervasive-problem] for the purpose of describing aspects
of pervasive attacks.
communications resource
A communications resource is any uniquely identifiable continuous
data channel or discrete shared content that represents an
exchange of personal communications between two or more users.
communications resource client
A communications resource client consumes communications resources
on behalf of a user and, when deployed in conformance with the KMS
architecture, consumes the services of KMS server(s) to facilitate
the E2E encryption of those communications resources.
communications resource server
A communications resource server is a provider of services through
which communications resources are made available.
cloud provider
An individual or organization responsible for, and in control of,
one or more communications resource servers.
Biggs & Cooley Expires May 6, 2016 [Page 4]
Internet-Draft key-management-service November 2015
E2E encryption
Shorthand for end-to-end encryption, as defined in [RFC4949],
particularly as it applies to the establishment of confidentiality
and integrity of communications resources.
KMS server
A key management server (KMS) is responsible for creating,
storing, and providing access to E2E encryption keying material by
communications resource clients.
KMS protocol
The protocol through which communications resource clients
interoperate with KMS servers.
KMS provider
An individual or organization responsible for, and in control of,
a KMS server deployment.
KMS transport
Any service or protocol that provides the basic transport over
which KMS protocol messages are exchanged.
resource client
See communications resource client.
resource server
See communications resource server.
trusted party
A trusted party is an individual or organization that is trusted
by one or more communicating users to maintain the confidentiality
and integrity of their communications resources.
1.2. Security Terms
Most security-related terms in this document are to be understood in
the sense defined in [RFC4949]; such terms include, but are not
limited to, "attack", "authentication", "authorization",
"certification authority", "certification path", "certificate",
Biggs & Cooley Expires May 6, 2016 [Page 5]
Internet-Draft key-management-service November 2015
"credential", "identity", "self-signed certificate", "trust", "trust
anchor", "trust chain", "validate", and "verify".
1.3. Notational Conventions
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
[RFC2119].
2. Architectural Overview
The architectural reference model for this specification is
illustrated in Figure 1. Central to this model is the communications
resource server which is presumed to be operated by a cloud provider
for the purpose of offering some form of communications service. The
nature of this service is not prescribed by this specification and
may take the form of any of a variety of communications or
collaboration services including file sharing, messaging, and VoIP.
Consuming the services of the communications resource server are
communications resource clients which may be supplied by the cloud
provider or developed by third parties.
+-----------------+
| Communications |
+-------------------| Resource Server |-------------------+
| | (Cloud Provider)| |
| +-----------------+ |
| |
| |
| +-----------------+ |
| +-----------| KMS Transport |-----------+ |
| | +-----------------+ | |
| | | | |
| | Untrusted | | |
- - -|- - - -|- - - - - - - - - - | - - - - - - - - - -|- - - -|- - -
| | Trusted | | |
| | | | |
+-----------------+ +-----------------+ +-----------------+
| Communications | | KMS Server | | Communications |
| Resource Client | | (KMS Provider) | | Resource Client |
+-----------------+ +-----------------+ +-----------------+
| |
+-----------------+ +-----------------+
| Alice | | Bob |
+-----------------+ +-----------------+
Figure 1: KMS Architecture Reference Model
Biggs & Cooley Expires May 6, 2016 [Page 6]
Internet-Draft key-management-service November 2015
In addition to the familiar elements described above, this model also
includes a key management server, or KMS, operated by a KMS provider.
The KMS server exposes an API through which clients may securely post
and share cryptographic keying material used for the E2E encryption
of content that is transited through the cloud provider's services.
The API exposed by the KMS implements the curator functions described
in the Centralized Groups section of
[I-D.abiggs-saag-primitives-for-conf-group-comms]. It is important
to note that the KMS is a dedicated curator rather than a content
producing curator. This API is secured in such a way as to ensure
these keys are visible to none but the KMS server itself and the
clients authorized to consume the content they protect. This
highlights an important distinction between the KMS provider and the
cloud provider: while the KMS provider is necessarily a trusted
party, the cloud provider need not be.
It is an explicit objective of this specification to promote an
ecosystem of providers of KMS implementations and KMS services that
are distinct and independent of the cloud providers over whose
services users communicate. To that end, this specification seeks to
standardize a KMS service protocol though which clients and KMS
servers interoperate. This protocol provides for the establishment
of a confidential and authenticated channel between each client and
KMS server, and defines an API of request and response messages to be
exchanged over this secure channel for the purpose of creating,
retrieving, and exchanging keys.
While the KMS service protocol constitutes a central focus of this
specification, the means by which this protocol is transported is
expressly out of scope. This role may be readily addressed through
either standards-based or proprietary protocols, and so we refer to
this simply as the KMS transport for the remainder of this document.
Over this transport, the communication paths between clients and KMS
server are encrypted using keys established through an authenticated
ephemeral key agreement. As such, the KMS transport provider need
not be regarded as a trusted party, and in fact may be the cloud
provider itself.
An important non-goal of this specification is the standardization of
any aspect of the cloud provider's services or the means by which
clients utilize shared keys for the E2E encryption of data transiting
those services. By avoiding the application of constraints on the
communications services and protocols we enable the use of this
specification in the context of existing service deployments, both
standards-based and proprietary. It is similarly a non-goal of this
specification to enable federation of secure communications between
vendors of different cloud services, as that is the realm of
standardized application protocols. The scope of this specification
Biggs & Cooley Expires May 6, 2016 [Page 7]
Internet-Draft key-management-service November 2015
is intended to be narrowly focused on the task of separating E2E
encryption key management from the communications services they
secure, thereby facilitating the broadest possible adoption of secure
communications though existing services.
3. Use Cases
The use cases described in this section are non-normative examples
meant to illustrate how the KMS architecture may be deployed to
provide E2E encryption of different types of communications
resources. These use cases differ in detail, but generally follow a
common logical sequence as given below.
Note that all requests to the KMS server are via the KMS transport
which, for clarity, has been omitted from the sequence diagrams
included in this section.
Resource Resource Resource KMS
Client B Client A Server Server
| | | (1) |
| |-----------------|---------------->|
| | | (2) |
| |-----------------|---------------->|
| | | |
| (3) | | |
| | (4) | |
| |---------------->| |
| | | (5) |
| |-----------------|---------------->|
| | | (6) |
| |-----------------|---------------->|
| | (7) | |
|-----------------|---------------->| |
| | | (8) |
|-----------------|-----------------|---------------->|
| | | |
(9) | | | |
| | | |
Figure 2: Nominal Use Case
1. Client A requests a new GMBC from the KMS server, including an
initial operation to add itself as a member. The KMS creates and
returns a new genesis block with the KMS as curator and client A
as a member.
Biggs & Cooley Expires May 6, 2016 [Page 8]
Internet-Draft key-management-service November 2015
2. Client A requests that the KMS generate a new GK. The KMS
generates the GK and returns it to the client with client A as
the only recipient of the embedded JWE used to wrap the included
key material.
3. Client A encrypts a resource using the key material protected by
the GK.
4. Client A posts the encrypted resource to the resource server,
including the URI of the GK as metadata.
5. Client A creates and signs a new GMBC block containing an
operation to add client B and with the hash of the genesis block
from step 1 as the "antecedent". Client A posts this block to
the KMS for appending to the GMBC.
6. Client A posts a request to the KMS to update the GK and bind it
to the GMBC by setting the "block" attribute of the GK to be the
hash of the GMBC block posted in 5 (this has the effect of
linking authorization for retrieval of the GK to the membership
of the GMBC at that particular block).
7. Client B obtains the encrypted resource from the resource server,
including the GK URI as metadata.
8. Client B performs a GK Get to obtain the GK from the KMS server.
The KMS checks the "block" attribute on the requested GK and
examines the GMBC block to which it refers. The membership of
the GMBC at that block includes client B, so the server returns
the GK to the client with client B as the only recipient of the
JWE used to wrap the included key material.
9. Client B decrypts the resource using the key material protected
by the GK.
3.1. Securing an HTTP File Sharing Service
Let A be a user that wishes to share a file with users B and C
through some HTTP based file sharing service. In the context of the
KMS architecture we may regard the file sharing provider's HTTP API
as the resource server and the users' HTTP clients as the resource
clients.
For this scenario we also assume that the file sharing service is
trusted by user A with the role of providing a file sharing mechanism
but is not necessarily trusted to adequately protect the
confidentiality of the file contents. User A's concerns may then be
addressed through the introduction of an HTTP based KMS transport
Biggs & Cooley Expires May 6, 2016 [Page 9]
Internet-Draft key-management-service November 2015
(not shown) and a KMS server deployed by an entity that A regards as
a trusted party.
HTTP HTTP HTTP HTTP File KMS
Client C Client B Client A Share Server Server
| | | | |
| | | | (1) |
| | |--------------|------------>|
| | | | (2) |
| | |--------------|------------>|
| | | | |
| | (3) | | |
| | | (4) | |
| | |------------->| |
| | | | (5) |
| | |--------------|------------>|
| | | | (6) |
| | |--------------|------------>|
| (7) | (7) | | |
|<-------------|<-------------|--------------| |
| | | (8) | |
| |--------------|------------->| |
| | | | (9) |
| |--------------|--------------|------------>|
| | | | |
| (10) | | | |
| | | | |
(11) | | | | |
| | | | |
Figure 3: File Sharing Use Case
This sequence begins with the assumption that each client has, at
some point, already established a secure channel to the KMS via
authenticated key agreement.
1. Client A requests a new GMBC from the KMS server, including an
initial operation to add itself as a member. The KMS creates
and returns a new genesis block with the KMS as curator and
client A as a member.
2. Client A requests that the KMS generate a new GK. The KMS
generates the GK and returns it to the client with client A as
the only recipient of the embedded JWE used to wrap the included
key material.
3. Client A encrypts a file using the key material protected by the
GK.
Biggs & Cooley Expires May 6, 2016 [Page 10]
Internet-Draft key-management-service November 2015
4. Client A posts the encrypted file to the file sharing service,
including the URI of the GK as metadata.
5. Client A creates and signs a new GMBC block containing an
operation to add clients B and C, and with the hash of the
genesis block from step 1 as the "antecedent". Client A posts
this block to the KMS for appending to the GMBC.
6. Client A posts a request to the KMS to bind the GK to the GMBC
by setting the "block" attribute of the GK to be the hash of the
GMBC block posted in 5.
7. Clients B and C learn of the newly shared file from the file
sharing service (the mechanism by which this occurs is out of
scope for this specification).
8. Client B retrieves the encrypted file from the file sharing
service, including the GK URI as metadata.
9. Client B performs a GK Get to obtain the GK from the KMS server.
The KMS checks the "block" attribute on the requested GK and
examines the GMBC block to which it refers. The membership of
the GMBC at that block includes client B, so the server returns
the GK to the client with client B as the only recipient of the
JWE used to wrap the included key material.
10. Client B decrypts the file using the key material protected by
the GK.
11. Client C performs steps 8 through 10 in the same fashion as
client B.
It is worth noting that a race condition does exist where step 9
could occur before steps 5 and 6 complete. This will result in a
client being temporarily denied access to the GK used to encrypt the
shared file.
3.2. Securing an XMPP Multi-User Chat
Let A, B and C be users that wish to engage in secure chat through an
existing XMPP multi-user chat room. In the context of the KMS
architecture we may regard the XMPP MUC service as the resource
server, the users' XMPP clients as the resource clients, and the XMPP
service itself (not shown) as the KMS transport.
Biggs & Cooley Expires May 6, 2016 [Page 11]
Internet-Draft key-management-service November 2015
XMPP XMPP XMPP XMPP MUC KMS
Client C Client B Client A Server Server
| | | | |
| | | | (1) |
| | |--------------|------------>|
| | | | (2) |
| | |--------------|------------>|
| | | (3) | |
| | |------------->| |
| (4) | (4) | | |
|<-------------|<-------------|--------------| |
| | | | (5) |
| |--------------|--------------|------------>|
| | | | |
| (6) | | | |
| | | | |
(7) | | | | |
| | | | |
Figure 4: Multi-User Chat Use Case
This sequence begins with the assumption that a MUC room already
exists on the MUC server and that each client has already established
a secure channel to the KMS via authenticated key agreement. All
messages are transmitted over XMPP, with the presumption that
appropriate XMPP extensions are developed to provide bindings for KMS
operations.
1. Client A requests a new GMBC from the KMS server, providing
initial operations to add clients A, B, and C. The KMS creates
and returns a new genesis block with the KMS as curator and
clients A, B, and C as members.
2. Client A requests that the KMS generate a new GK, and to have it
immediately bound to the genesis block created in step 1. The
KMS generates the GK and returns it to the client with client A
as the only recipient of the embedded JWE used to wrap the
included key material.
3. Client A encrypts the content of an XMPP message using the key
material from the GK created in step 2, and sends the encrypted
message to the MUC room. The GK URI is included within the XMPP
message as metadata.
4. The MUC service delivers client A's encrypted message to clients
B and C.
Biggs & Cooley Expires May 6, 2016 [Page 12]
Internet-Draft key-management-service November 2015
5. Client B performs a GK get operation to retrieve the GK from the
KMS server using the GK URI included in the encrypted message's
metadata.
6. Client B decrypts the messages using the key material protected
by the GK.
7. Client C performs steps 5 and 6 in the same fashion as Client B.
3.3. KMS to KMS Key Federation
This use case illustrates two KMS instances federating keys
associated with a resource. As KMS servers are deployed to serve
groups of users it is inevitable that users will want to share
resources across groups or organizations. This cross-organization
sharing of keys leads to several problems. First, each user is only
known to and only knows of one logical KMS. Second, each
organization might have very different archiving requirements due to
differing legal compliance regulations due to jurisdiction or
industry differences. Lastly, one or both of the users might be
employees of enterprises that need to be able to respond to legal
discovery requests. To address these issues, KMS servers may
federate in such a way as to allow for limited copying of keys from
one KMS to another. This permits each KMS' owning organization the
ability to control the ongoing policy regarding access to keys for
which their respective users are authorized.
Let Alice@DomainA and Bob@DomainB be users of a common file sharing
service and who happen to use different KMS servers to secure their
communications. Assume then that Alice wishes to share a file with
Bob and therefore relies on KMS server federation to facilitate the
key exchange.
Biggs & Cooley Expires May 6, 2016 [Page 13]
Internet-Draft key-management-service November 2015
HTTP Client HTTP Client HTTP File KMS Server KMS Server
Bob@DomainB Alice@DomainA Share Server DomainA DomainB
| | | (1) | |
| |--------------|------------->| |
| | | (2) | |
| |--------------|------------->| |
| | (3) | | |
| |------------->| | |
| (4) | | | |
|<------------|--------------| | |
| | (5) | | |
|-------------|------------->| | |
| | | | (6) |
|-------------|--------------|--------------|------------>|
| | | | (7) |
| | | |<------------|
| | | | (8) |
| | | |------------>|
| (9) | | | |
|<------------|--------------|--------------|-------------|
| | | | |
(10) | | | | |
| | | | |
Figure 5: File Sharing with KMS Federation Use Case
This sequence begins with the assumption that each client has, at
some point, already established a secure channel to their respective
KMS via authenticated key agreement.
1. Alice@DomainA requests a new GMBC from the KMS server, providing
initial operations to add Alice@DomainA and Bob@DomainB as
members. The KMS creates and returns a new genesis block with
the KMS as curator.
2. Alice@DomainA requests that the KMS generate a new GK, and to
have it immediately bound to the genesis block created in step
1. The KMS generates the GK and returns it to the client with
Alice@DomainA as the only recipient of the embedded JWE used to
wrap the included key material.
3. Client A encrypts a file using the key material from the GK
created in step 2, and sends the encrypted message to the file
sharing service. The GK URI is included as metadata.
4. Bob@DomainB learns of the newly shared file from the file
sharing service (the mechanism by which this occurs is out of
scope for this specification).
Biggs & Cooley Expires May 6, 2016 [Page 14]
Internet-Draft key-management-service November 2015
5. Bob@DomainB retrieves the shared file from the file sharing
service along with the GK URI contained in metadata.
6. Using the GK key URI obtained in step 7, Bob@DomainB requests
the GK from his own KMS at DomainB.
7. The DomainB KMS recognizes the GK URI as actually hosted by the
DomainA KMS. The DomainB KMS establishes a secure and mutually
authenticated channel with the DomainA KMS via the KMS transport
(if not previously established) and requests the GK from the
DomainA KMS on behalf of Bob@DomainB.
8. The DomainA KMS first checks to see if Bob@DomainB is entitled
to retrieve the GK. If so, it then consults the WebFinger
resource of Bob@DomainB to determine whether DomainB is entitled
to request GKs on behalf of Bob@DomainB. If so, DomainA KMS
will respond by returning the GK to DomainB in such a way as the
JWE used to wrap the key material is encrypted with the public
key of the DomainB KMS server.
9. DomainB KMS returns the GK to Bob@DomainB in such a way as the
JWE used to wrap the key material is encrypted with
Bob@DomainB's public key, and the GK itself is signed with the
DomainB KMS private key.
10. Bob@DomainB decrypts the shared file using the key obtained in
step (11).
Note that in step 8 the DomainB KMS is being trusted by DomainA KMS
to not share the GK key material with anyone other than those users
on whose behalf it has acted and successfully retrieved the GK. This
is a necessary consequence of KMS federation, where the act of
authorizing access to a GK by a user residing in a federated domain
engenders an implicit trust of the KMS server that controls the
federated domain. For that reason, a KMS provider should restrict
federation of its KMS servers to domains that the KMS provider
regards as trusted.
4. KMS Protocol
The KMS protocol is composed of a message oriented request and
response API and a secure channel over which those messages are
exchanged. The API provides clients with the ability to post and
retrieve GMBC and GK objects. The secure channel provides a mutually
authenticated and E2E encrypted channel over which the clients and
KMS server may exchange API messages securely. The API and secure
channel are described in detail through the remainder of this
section.
Biggs & Cooley Expires May 6, 2016 [Page 15]
Internet-Draft key-management-service November 2015
4.1. Secure Channel
The secure channel is an encrypted and mutually authenticated
communication path between each client and the KMS server. It
transits the KMS transport which, in the context of this document,
represents any service or protocol that may be utilized for the
relaying of KMS API request and response messages. This
specification presumes the KMS transport to be untrusted.
(3) Secure Channel
+===================================================+
V V
+-----------------+ (2) +---------------+ (1) +---------------+
| Resource Client |<------>| KMS Transport |<------>| KMS Server |
+-----------------+ +---------------+ +---------------+
| |
Trusted | Untrusted | Trusted
Figure 6: Establishment of a Secure Channel
At a high level, the communication path between a resource client and
KMS is established as follows.
1. The KMS actively connects to the KMS transport. The protocol
used for this connection is out of scope for this document,
however it MUST support the asynchronous flow of encrypted KMS
request and response messages between the KMS and KMS transport.
2. A resource client connects to the KMS transport. The protocol
used for this connection is out of scope for this document,
however it MUST support the flow of encrypted KMS request and
response messages between the resource client and the KMS
transport.
3. Through an elliptic curve Diffie-Helman key exchange, augmented
by server and client authentication, the resource client and KMS
establish a shared secret and derived ephemeral key. This is
discussed in greater detail in Section 4.6.1.
On successful mutual authentication and ephemeral key agreement, the
resource client and KMS communicate through the exchange of sequenced
request and response messages encrypted using the ephemeral key.
4.2. User Identity
Central to the KMS server's role as a key store is its ability to
both restrict access to stored keying material and to rekey keying
material to only authorized users. This requires robust user
Biggs & Cooley Expires May 6, 2016 [Page 16]
Internet-Draft key-management-service November 2015
authentication and a means for the unambiguous and unique
identification of each user.
Conforming KMS architecture deployments MUST rely on an identity
provider that supports the generation of OAuth 2.0 [RFC6749] access
tokens. The KMS server MUST rely on same identity provider for the
purpose of validating access tokens received from the client. Access
tokens used by clients to demonstrate identity and authorization for
access to KMS resources MUST NOT be used for any other service. Any
exposure of a KMS recognized access token to third parties (such as
providers of other services or a resource server) jeopardizes the
security of all GMBC and GK objectgs for which the user whose
identity is represented by the token is authorized.
The identity provider on which the KMS server relies MAY be the same
identity provider as relied upon by the resource server(s) whose
communications resources are encrypted with GK objects managed by the
KMS server. Note, however, the reliable authentication and
authorization of clients to the KMS server is critical to the
security of the KMS keys it holds. The identity provider on which
the KMS relies must therefore necessarily be regarded as a trusted
party within the context of the KMS architecture.
Access tokens MUST be conveyed to the KMS server as part of the
payload of encrypted KMS API requests as described in Section 4.5.1
and MUST NOT be conveyed in any other manner.
4.3. KMS Identity
Given the untrusted nature of the KMS transport by both the KMS and
clients, it is critical for clients to be able to verify the identity
of their KMS and ensure that no MITM attacks are carried out on
client to KMS or KMS to client communications. Therefore, the KMS
MUST make use of at least one PKIX certificate [RFC5280] and clients
MUST validate the PKIX certificate presented by the KMS through the
comparison of the certificate's common name (CN) or subject
alternative name (SAN) [RFC6125] fields to the Internet domain
portion of the user's Addr-spec [RFC2822] formatted unique identifier
using the procedures defined in section 6 of [RFC6125]. An
acceptable alternative to direct CN or SAN validation is defined in
[I-D.ietf-xmpp-posh].
PKIX certificates presented by the KMS can be issued by either a
public or private certification authority with the stipulation that
clients MUST be able to validate the KMS's entire certificate path
through the pre-established trust of the root certificate used to
anchor the certificate path. The mechanism for establishing trust of
the root certificate is out of scope for this specification, but it
Biggs & Cooley Expires May 6, 2016 [Page 17]
Internet-Draft key-management-service November 2015
is usually carried out through pre-installed trusted root
certificates on various operating systems for public certification
authorities or through enterprise endpoint management solutions or
manual installation tasks for private certification authorities.
4.4. Object Types
The KMS protocol is based on operations on GMBC and GK objects.
Specifically, these include the following JSON object types defined
using using JSON content rules [I-D.newton-json-content-rules] in
[I-D.abiggs-saag-primitives-for-conf-group-comms]:
gmbc-genesis-block
gmbc-appended-block
group-key
It is through the creation and retrieval of instances of these object
types that clients interact with the KMS.
4.5. Message Structure
Every KMS request and response message is composed of a JSON
[RFC7159] formatted payload encapsulated within either a JWE
[I-D.ietf-jose-json-web-encryption] or JWS
[I-D.ietf-jose-json-web-signature] object. These messages may be
divided into three types.
Common Messages
Common messages include all those which do not meet the definition
of either key agreement message or error message. Common messages
are encrypted as JWE objects using the shared ephemeral key
established during initial key agreement between the client and
KMS (see Section 4.6.1). The value of the JWE header "kid"
attribute of a common message MUST match that of the KMS ephemeral
key object URI attribute established during initial key agreement.
Ephemeral Key Agreement Messages
Ephemeral key agreement messages are those exchanged between the
client and KMS for the purpose of establishing a new shared
ephemeral key (see Section 4.6.1). Key agreement request payloads
are encrypted as JWE objects using the authenticated and validated
static public key of the KMS. Key agreement response payloads are
signed as JWS objects using the static private key of the KMS.
The value of the JWE or JWS header "kid" attribute of an ephemeral
Biggs & Cooley Expires May 6, 2016 [Page 18]
Internet-Draft key-management-service November 2015
key agreement message MUST be a well known key identifier for the
KMS static public key.
Error Messages
Error messages are those originated by the KMS to indicate a
failed request. Error messages are composed in the same fashion
as common messages; however, in the event that the KMS does not
recognize the ephemeral key used in the request, or that key is
determined to have expired, the KMS MUST respond with an
unencrypted message composed as a JWS, with a payload as described
in Section 4.5.3, and signed using the KMS server's static public
key.
The basic JSON representations for the request and response payloads
are defined in the following sections.
4.5.1. Basic Request Payload
The basic JSON representation for KMS request message payloads is
defined as follows using JSON content rules
[I-D.newton-json-content-rules] with references to rules defined in
previous sections.
requestId (
"requestId" : integer
)
credential {
"userId": ?string
"bearer": string / "jwk": jwk
}
client {
"clientId": string,
"credential": credential
)
method: string /create|retrieve|update|delete/
request (
"client" : client,
"method" : method,
"uri" : uri,
requestId
)
Biggs & Cooley Expires May 6, 2016 [Page 19]
Internet-Draft key-management-service November 2015
The attributes of a KMS request message payload are defined as
follows.
requestId
A string selected by the client and provided in each request to
uniquely identify the request. The string is treated opaquely by
the server and returned verbatim in the associated response.
userId
The unique identifier of the user making the request. This field
is optional, and MUST be disregarded if the requesting user's
identity can be securely derived from either the bearer token or
jwk.
bearer
An [RFC6749] access token issued by the client's identity provider
and validated by the KMS in cooperation with the identity
provider. See Section 4.2.
jwk
A JWK object, in JSON format as defined in
[I-D.ietf-jose-json-web-key], containing the public key of the
client (presumably a server). This JWK MUST contain an x5c header
with a certificate chain that may be used to positively validate
the public key.
clientId
An opaque unique identifier provided by the client (not used for
authentication, only to assist multiple clients of a single user
in differentiating between their respective unbound keys).
method
Indicates the request type: create, retrieve, update, or delete.
uri
A URI identifying a KMS object or object type (e.g. GMBC or GK)
to which the request applies.
The JSON content rules above are used in conjunction with additional
request type specific rules, defined later in this document, to
produce the full request payload definition for each KMS operation.
Biggs & Cooley Expires May 6, 2016 [Page 20]
Internet-Draft key-management-service November 2015
4.5.2. Basic Response Payload
The basic JSON representation for KMS request message payloads is
defined as follows using JSON content rules with references to rules
defined in previous sections.
response (
"status" : integer,
?"reason" : string,
requestId
)
The attributes of a KMS request message payload are defined as
follows.
status
Indicates the success or failure of the request. The value
returned in a response status attribute SHOULD be that of an
[RFC7231] defined status code with semantics that correspond to
the success or failure condition of the KMS request.
reason
An optional natural language string to describe the response
status in terms that are useful for tracing and troubleshooting
the API.
requestId
An echo of the requestId provided in the request.
The JSON content rules above are used in conjunction with additional
response type specific rules, defined later in this document, to
produce the full response payload definition for each KMS operation.
4.5.3. Error Response Payload
The JSON representation for KMS error response message payloads is
defined as follows using JSON content rules with references to rules
defined in previous sections.
Error response payload definition:
root {
response
}
Biggs & Cooley Expires May 6, 2016 [Page 21]
Internet-Draft key-management-service November 2015
Error response message example:
JWS(K_kms_priv, {
"status": 403,
"reason": "The ephemeral key used in the request has expired.",
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5"
})
4.6. Requests
The following sections provide detailed descriptions for each of the
request and response operations that may occur between a resource
client and the KMS.
4.6.1. Create Ephemeral Key
The first operation between a client and KMS MUST be the
establishment of a shared secret and derived ephemeral key. This is
necessary as all other requests and responses are encrypted with the
ephemeral key.
The client request for creating an ephemeral key conforms to the
basic request message payload, where the method is "create" and the
uri is "/ecdhe". In addition to the basic payload, the client
provides a jwk attribute for which the value is a JWK object
[I-D.ietf-jose-json-web-key] containing the public part of an EC key
pair generated by the client. Unlike a basic request message,
however, the request payload is encrypted as the content of a JWE
[I-D.ietf-jose-json-web-key] secured with the static public key of
the KMS server (K_kms_pub) as obtained from the server's validated
PKIX certificate [RFC5280].
Note, the client MUST generate a new EC key pair for every create
ephemeral key request sent to the KMS server.
Request payload definition:
root {
request,
jwk
}
Request message example:
Biggs & Cooley Expires May 6, 2016 [Page 22]
Internet-Draft key-management-service November 2015
JWE(K_kms_pub, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
},
"method": "create",
"uri": "/ecdhe",
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5",
"jwk" : {
"kty": "EC",
"crv": "P-256",
"x": "VoFkf6Wk5kDQ1ob6csBmiMPHU8jALwdtaap35Fsj20M",
"y": "XymwN6u2PmsKbIPy5iij6qZ-mIyej5dvZWB_75lnRgQ"
}
})
On receiving the ephemeral key creation request, the KMS server MUST
verify the credential provided in the request. If a bearer token is
provided, the KMS MUST validate the token in cooperation with the
identity provider. If a jwk is provided, the KMS MUST validate the
included PKIX certificate chain against the KMS server's trust root.
In either case, the identity of the requesting client MUST be
authenticated and verified to correspond to either an authorized user
of the KMS or an authorized trusted service. If verification fails,
the KMS MUST NOT use the server response to continue with key
agreement.
Upon successful authentication and authorization of the request, the
KMS responds by generating its own EC key pair using the same curve
as indicated in the "crv" attribute of the request message JWK. The
KMS server returns the public part of this key pair to the resource
client in the form of an EK object within the response payload. The
KMS also generates and includes within the response payload a new key
uri to be regarded by both client and KMS as the key identifier of
the agreed upon ephemeral key. The response payload is returned to
the resource client as the content of a JWS
[I-D.ietf-jose-json-web-signature] signed using the static private
key of the KMS server (K_kms_priv).
Response payload definition:
root {
response,
key
}
Biggs & Cooley Expires May 6, 2016 [Page 23]
Internet-Draft key-management-service November 2015
Response message example:
JWS(K_kms_priv, {
"status": 201,
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5",
"ephemeral-key": {
"uri": "/ecdhe/ea9f3858-1240-4328-ae22-a15f6072306f",
"jwk" : {
"kty": "EC",
"crv": "P-256",
"x": "8mdasnEZac2LWxMwKExikKU5LLacLQlcOt7A6n1ZGUC",
"y": "lxs7ln5LtZUE_GE7yzc6BZOwBxtOftdsr8HVh-14ksS"
},
"userId": "842e2d82-7e71-4040-8eb9-d977fe888807",
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"createDate": "2014-10-09T15:54:48Z",
"expirationDate": "2014-10-09T16:54:48Z"
}
})
If successful, the KMS response to a create ephemeral key request
MUST have a status of 201. In the case of a request failure, the KMS
response status SHOULD be that of an [RFC7231] defined status code
with semantics that correspond to the failure condition. In
addition, the ephemeral key SHOULD have the createDate assigned as
the current time and an expirationDate assigned as the latest point
in time before which the key may be used for encrypting messages
(both in [RFC3339] date-time format).
On receiving the ephemeral key creation response, the resource client
MUST verify the received JWS against the KMS server's validated
static public key. If verification fails, the client MUST NOT use
the server response to continue with key agreement.
To generate the shared secret, both resource client and KMS server
use ECDH shared secret derivation with the private part of the local
EC key pair and the public part of the remote EC key pair. The
shared secret is then provided as input to HKDF (with both extract
and expand, and empty salt) [RFC5869] to generate the ephemeral key
(K_ephemeral).
The ephemeral key generated by this operation is used to encrypt all
subsequent KMS requests and responses passed between the resource
client and KMS. When encrypting such a message, the sender MUST
assign a value to the kid attribute of the header of the resulting
JWE object, and this value MUST match the URL of the key as provided
to the client in the KMS response message described above. This
Biggs & Cooley Expires May 6, 2016 [Page 24]
Internet-Draft key-management-service November 2015
provides the recipient with a means for identifying the key necessary
to decrypt the message.
The KMS SHOULD accept messages encrypted with the ephemeral key up to
and until the key expiration date as provided in the response message
described above. On expiration of the ephemeral key, the KMS MUST
reject all further requests submitted using this key, and a client
wishing to submit further requests to the KMS MUST re-establish the
secure channel by requesting the creation of a new ephemeral key.
4.6.2. Delete Ephemeral Key
In the event that a resource client's ephemeral key has become
compromised, a client SHOULD submit a request to the KMS to delete
the ephemeral key.
The request message conforms to the basic request message structure,
where the method is "delete", and the uri is that of the ephemeral
key to be deleted.
Request payload definition:
root {
request
}
Request message example:
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "delete",
"uri": "/ecdhe/ea9f3858-1240-4328-ae22-a15f6072306f",
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5"
})
The response message conforms to the basic response message
structure, and MUST NOT include a representation of the deleted
ephemeral key.
Response payload definition:
Biggs & Cooley Expires May 6, 2016 [Page 25]
Internet-Draft key-management-service November 2015
root {
response
}
Response message example:
JWE(K_ephemeral, {
"status": 204,
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5"
})
If successful, the KMS response to a delete ephemeral key request
MUST have a status of 204. In the case of a request failure, the KMS
response status SHOULD be that of an [RFC7231] defined status code
with semantics that correspond to the failure condition.
On successful deletion of an ephemeral key, the KMS MUST NOT, from
that time forward, accept any requests encrypted with that ephemeral
key.
4.6.3. Post GMBC Block (genesis)
When a client intends to initiate E2E encryption of a communications
resource, it begins by requesting the creation of a GMBC genesis
block. In this request, the client provides basic GMBC block
information which the KMS uses in generating the genesis block. The
KMS will assign a unique GMBC URI to the genesis block and indicate
itself as the GMBC curator.
The request message conforms to the basic request message structure,
where the method is "post", and the path of the URI is "/blocks".
Request payload definition:
root {
request,
"blockPayload": gmbc-block
}
Request message example:
Biggs & Cooley Expires May 6, 2016 [Page 26]
Internet-Draft key-management-service November 2015
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "post",
"uri": "kms://kms.example.com/blocks",
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5",
"blockPayload": {
"creator": "bob@example.com",
"created": "2015-11-02T19:02:15Z",
"operations": [
{
"entity": "bob@example.com",
"optype": "add"
},
{
"entity": "alice@example.com",
"optype": "add"
}
]
}
})
The response message conforms to the basic response message
structure, and includes a representation of the created GMBC genesis
block in the form of a compact-serialized JWS signed with the KMS
server's private static key.
Response payload definition:
signed-gmbc-genesis-block: JWS(K_kms_priv, gmbc-genesis-block)
root {
response,
"block": signed-gmbc-genesis-block
}
Response message example:
JWE(K_ephemeral, {
"status": 201,
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5",
"block": "eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAidXJpIjo..."
}
Biggs & Cooley Expires May 6, 2016 [Page 27]
Internet-Draft key-management-service November 2015
Deserialized payload of the block attribute:
JWS(K_kms_priv, {
"uri": "kms://kms.example.com/blocks/7f35c3eb",
"nonce": "32088b07-1a19-466b-a779-ef8dc8c61be9",
"curator": "kms://kms.example.com",
"creator": "kms://kms.example.com",
"created": "2015-11-02T19:02:15Z",
"operations": [
{
"entity": "bob@example.com",
"optype": "add"
},
{
"entity": "alice@example.com",
"optype": "add"
}
]
})
If successful, the KMS response to a this request MUST have a status
of 201. In the case of a request failure, the KMS response status
SHOULD be that of an [RFC7231] defined status code with semantics
that correspond to the failure condition.
4.6.4. Post GMBC Block (append)
Once a GMBC genesis block has been created, any member may append new
blocks in order to modify the group membership. This is done by
submitting a post GMBC block request to the KMS. In this request,
the client provides a signed gmbc-appended-block and the URI of the
genesis block of the GMBC to which it is to be appended.
The client may submit one or more blocks to be appended, the order of
which they appear in the request representing the order in which they
should be appended. The KMS will validate that the antecedent hash
of the first block matches the hash of the last block of the current
chain, and that the antecedent of each subsequent block matches the
hash of the previous block. The KMS will also validate that each
block is signed by an entity that qualifies as a member of the chain.
If any of these checks fails, the KMS will fail the request in its
entirety.
The request message conforms to the basic request message structure,
where the method is "post", and the uri is that of the genesis block
of the GMBC to which the provided block should be appended.
Request payload definition:
Biggs & Cooley Expires May 6, 2016 [Page 28]
Internet-Draft key-management-service November 2015
signed-gmbc-appended-block: JWS(K_user_priv, gmbc-appended-block)
root {
request,
"blocks" [ *: signed-gmbc-appended-block ]
}
Request message example:
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "post",
"uri": "kms://kms.example.com/blocks/7f35c3eb",
"requestId": "6205452b-c555-484f-8445-bb94c8044882",
"blocks": [
"eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAiYW50ZWNlZGVud..."
]
})
Deserialized payload of the block attribute:
JWS(K_alice_priv, {
"antecedent": "3a2371f8fb6bb0f96e65dc535010b4004afc...",
"creator": "alice@example.com",
"created": "2015-11-02T19:13:15Z",
"operations": [
{
"entity": "charlie@example.com",
"optype": "add"
},
{
"entity": "bob@example.com",
"optype": "remove"
}
]
})
The response message conforms to the basic response message
structure.
Response payload definition:
Biggs & Cooley Expires May 6, 2016 [Page 29]
Internet-Draft key-management-service November 2015
root {
response
}
Response message example:
JWE(K_ephemeral, {
"status": 200,
"requestId": "6205452b-c555-484f-8445-bb94c8044882"
})
If successful, the KMS response to this request MUST have a status of
200. In the case of a request failure, the KMS response status
SHOULD be that of an [RFC7231] defined status code with semantics
that correspond to the failure condition.
4.6.5. Get GMBC
A client may retrieve GMBC blocks from the KMS using the get GMBC
operation. The KMS MAY validate that the requesting client
represents an entity that is a current member of the GMBC.
Alternatively, a KMS MAY validate that the requesting client
represents an entity that has been a member of the GMBC at some point
in time.
The request message conforms to the basic request message structure,
where the method is "get" and the uri is that of the GMBC's genesis
block. The client may also optionally request that only recently
appended blocks be returned, by providing in an "antecedent"
attribute the hash of a GMBC block the client already has. The KMS
will return any and all blocks which were appended after the block
indicated by this hash value.
Request payload definition:
root {
request
?"antecedent": string
}
Request message example:
Biggs & Cooley Expires May 6, 2016 [Page 30]
Internet-Draft key-management-service November 2015
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "get",
"uri": "kms://kms.example.com/blocks/7f35c3eb",
"requestId": "db1e4d2a-d483-4fe7-a802-ec5c0d32295f"
})
The response message conforms to the basic response message
structure, and includes an array containing the JWS compact-
serialization of GMBC blocks in chronological order.
Response payload definition:
signed-gmbc-block:
signed-gmbc-genesis-block / signed-gmbc-appended-block
root {
response,
"blocks" [ *: signed-gmbc-block ]
}
Response message example:
JWE(K_ephemeral, {
"status": 201,
"requestId": "db1e4d2a-d483-4fe7-a802-ec5c0d32295f",
"blocks": [
"eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAidXJpIjogImttczovL...",
"eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAiYW50ZWNlZGVudCI6I..."
]
})
If successful, the KMS response to this request MUST have a status of
200. In the case of a request failure, the KMS response status
SHOULD be that of an [RFC7231] defined status code with semantics
that correspond to the failure condition.
4.6.6. Post GK (create)
When a client intends to initiate E2E encryption of a communications
resource, it obtains the necessary keying material by requesting a
new GK from the KMS. The KMS generates the GK as specified in
[I-D.abiggs-saag-primitives-for-conf-group-comms].
Biggs & Cooley Expires May 6, 2016 [Page 31]
Internet-Draft key-management-service November 2015
In the request, the client has the option to include a block
attribute representing the hash of a GMBC block to which the GK
should be immediately associated, or "bound". This is appropriate in
cases where the block to which the GK is to be bound already exists
and is known by the client. When this is not the case, a client may
omit the block attribute from the request and receive back a GK that
has its block attribute similarly omitted. Such a block-less GK is
referred to as "unbound" because it is not yet associated with any
GMBC block.
The request message conforms to the basic request message structure,
where the method is "post", the path part of the URI is "/gks".
Request payload definition:
root {
request,
"block": string
}
Request message example:
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "post",
"uri": "kms://kms.example.com/gks",
"requestId": "8c198748-36fb-4318-89c9-bfc8bb0a967c"
})
The response message conforms to the basic response message
structure, and includes a representation of the created GK.
Response payload definition:
signed-group-key: JWS(K_kms_priv, group-key)
root {
response,
"gk": signed-group-key
}
Response message example:
Biggs & Cooley Expires May 6, 2016 [Page 32]
Internet-Draft key-management-service November 2015
JWE(K_ephemeral, {
"status": 201,
"requestId": "8c198748-36fb-4318-89c9-bfc8bb0a967c",
"gk": "eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAidXJpIjo..."
}
Deserialized payload of the gk attribute:
JWS(K_kms_priv, {
"uri": "kms://kms.example.com/gks/8ed72cd2",
"creator": "kms://kms.example.com",
"created": "2015-11-02T19:19:15Z",
"key": "eyJraWQiOiJmZjNjNWM5Ni0zOTJlLTQ2ZWYtYTg..."
})
If successful, the KMS response to this request MUST have a status of
201. In the case of a request failure, the KMS response status
SHOULD be that of an [RFC7231] defined status code with semantics
that correspond to the failure condition.
4.6.7. Post GK (update)
A GK is often generated ahead of time, before the requesting client
knows which communications resource the GK will be used to secure.
As such, they are created without being initially associated with any
particular GMBC. These are referred to as "unbound" GKs, as
discussed in the previous section. An unbound GK is not useful for
E2E communications until it is bound to a GMBC block and thereby made
accessible to members of that group.
A client can bind an unbound GK to a GMBC block by sending a post
request to the KMS with the GKs URI and the hash of the block to
which it should be bound. In response to this request the KMS will
update the GK payload to include the block hash provided in the
request, re-sign the GK with its private key, and return the updated
GK to the client.
The request message conforms to the basic request message structure,
where the method is "post", and the uri is that of the GK to be
updated.
Request payload definition:
root {
request,
"block": string
}
Biggs & Cooley Expires May 6, 2016 [Page 33]
Internet-Draft key-management-service November 2015
Request message example:
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "post",
"uri": "kms://kms.example.com/gks/8ed72cd2",
"requestId": "e0f9b55c-d0a5-4f70-aafd-309541fe51ab",
"block": "14b6290c88a9b40ee519832b878ccc1896bef8900d0f9d2..."
})
The response message conforms to the basic response message
structure, and includes a representation of the updated GK.
Response payload definition:
signed-group-key: JWS(K_kms_priv, group-key)
root {
response,
"gk": signed-group-key
}
Response message example:
JWE(K_ephemeral, {
"status": 200,
"requestId": "e0f9b55c-d0a5-4f70-aafd-309541fe51ab",
"gk": "eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAidXJpIjo..."
}
Deserialized payload of the gk attribute:
JWS(K_kms_priv, {
"uri": "kms://kms.example.com/gks/8ed72cd2",
"creator": "kms://kms.example.com",
"created": "2015-11-02T19:19:15Z",
"key": "eyJraWQiOiJmZjNjNWM5Ni0zOTJlLTQ2ZWYtYTg...",
"block": "14b6290c88a9b40ee519832b878ccc1896bef8900d0f9d2..."
})
If successful, the KMS response to a create resource request MUST
have a status of 200. In the case of a request failure, the KMS
Biggs & Cooley Expires May 6, 2016 [Page 34]
Internet-Draft key-management-service November 2015
response status SHOULD be that of an [RFC7231] defined status code
with semantics that correspond to the failure condition.
4.6.8. Get GK
Recipients of a communications resource secured by a GK require some
means by which they can retrieve the GK and subsequently decrypt the
resource. Such a recipient will typically receive the URI of the GK
as metadata of the encrypted resource itself and submit a get request
on that URI to the KMS.
The KMS, as a curator of the GMBC to which the GK is bound, is
responsible for ensuring that the keying material contained within
the GK is not accessible to entities outside of the group. It does
so by testing that the entity whose URI is provided in the request is
a member of the GMBC and, if so, returns the GK with the keying
material wrapped in a JWE encrypted with the public key of that
entity.
The test for membership may be performed based on any one of a
variety of policies, some examples of which are given below. Which
policy is applied is left to the discretion of the KMS
implementation.
Policy 1: An entity is considered a member for purposes of GK
retrieval if and only if the entity was a member of the GMBC at
the time the block to which the GK is bound was appended to the
GMBC.
Policy 2: An entity is considered a member for purposes of GK
retrieval if and only if the entity is a member of the GMBC as of
the most recently appended block.
Policy 3: An entity is considered a member for purposes of GK
retrieval if and only if the entity is a member of the GMBC as of
the most recently appended block, and was a member at the time the
block to which the GK is bound was appended to the GMBC.
Policy 1 represents a persistent right for current and former group
members to retrieve GKs that were available to them at some point in
the past. This policy does not extend the right to retrieve a GK to
members added subsequently.
Policy 2 determines privilege to retrieve GKs based entirely on the
current membership of the GMBC. Former members cannot retrieve and
GKs, and current members can retrieve all GKs for the entire history
of the GMBC.
Biggs & Cooley Expires May 6, 2016 [Page 35]
Internet-Draft key-management-service November 2015
Policy 3 allows only a current member to retrieve GKs and then only
as far back as the block that introduced that member to the group.
The request message conforms to the basic request message structure,
where the method is "get", and the uri is that of the GK to be
retrieved.
Request payload definition:
root {
request,
entity: uri
}
Request message example:
JWE(K_ephemeral, {
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "get",
"uri": "kms://kms.example.com/gks/8ed72cd2",
"requestId": "d83afbf1-523a-453a-8114-48c7df03ac7c",
"entity": "bob@example.com"
})
The response message conforms to the basic response message
structure, and includes a representation of the retrieved GK.
Response payload definition:
signed-group-key: JWS(K_kms_priv, group-key)
root {
response,
"gk": signed-group-key
}
Response message example:
JWE(K_ephemeral, {
"status": 200,
"requestId": "e0f9b55c-d0a5-4f70-aafd-309541fe51ab",
"gk": "eyAiYWxnIjogIlBTMjU2IiB9.ewogICAgICAidXJpIjo..."
}
Biggs & Cooley Expires May 6, 2016 [Page 36]
Internet-Draft key-management-service November 2015
Deserialized payload of the gk attribute:
JWS(K_kms_priv, {
"uri": "kms://kms.example.com/gks/8ed72cd2",
"creator": "kms://kms.example.com",
"created": "2015-11-02T19:19:15Z",
"key": "eyJraWQiOiJmZjNjNWM5Ni0zOTJlLTQ2ZWYtYTg...",
"block": "14b6290c88a9b40ee519832b878ccc1896bef8900d0f9d2..."
})
If successful, the KMS response to a retrieve resource request MUST
have a status of 200. In the case of a request failure, the KMS
response status SHOULD be that of an [RFC7231] defined status code
with semantics that correspond to the failure condition.
4.6.9. Ping
Ping is a simple request intended to provide an efficient means for
verifying the integrity of the secure channel between client and KMS.
Ping MUST be implemented as a safe and idempotent operation that
causes the server to do nothing more than return a basic response
payload in reaction to the client request. The method of a ping
request is "update" and the uri is "/ping".
Request payload definition:
root {
request
}
Request message example:
JWE(K_ephemeral, {
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5",
"client": {
"clientId": "android_a6aa012a-0795-4fb4-bddb-f04abda9e34f",
"credential": {
"bearer": "ZWU5NGE2YWYtMGE2NC0..."
}
}
"method": "update",
"uri": "/ping"
})
The response message conforms to the basic response message structure
with no additional data.
Response payload definition:
Biggs & Cooley Expires May 6, 2016 [Page 37]
Internet-Draft key-management-service November 2015
root {
response
}
Response message example:
JWE(K_ephemeral, {
{
"status": 200,
"requestId": "10992782-e096-4fd3-9458-24dca7a92fa5"
})
If successful, the client may deduce that the KMS was able to
successfully decrypt the received KMS request message, parse the
contents, confirm the identity and authorization of the requesting
client, and return a suitable response.
5. Security Considerations
Security considerations are discussed throughout this document.
Additional considerations may be added here as needed.
6. Appendix A. Acknowledgments
This specification is the work of several contributors. In
particular, the following individuals contributed ideas, feedback,
and wording that influenced this specification:
Cullen Jennings, Matt Miller, Suhas Nandakumar, Jonathan Rosenberg
7. Appendix B. Document History
-00
o Initial draft.
-01
o Editorial revisions and addition of ping operation.
-02
o Addition of new key retrieval options.
-03
o Substantial rewrite based on
[I-D.abiggs-saag-primitives-for-conf-group-comms].
Biggs & Cooley Expires May 6, 2016 [Page 38]
Internet-Draft key-management-service November 2015
8. References
8.1. Normative References
[I-D.abiggs-saag-primitives-for-conf-group-comms]
Biggs, A. and S. Cooley, "Primitives for Confidential
Group Communications", draft-abiggs-saag-primitives-for-
conf-group-comms-00 (work in progress), September 2015.
[I-D.ietf-jose-json-web-algorithms]
Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose-
json-web-algorithms-33 (work in progress), September 2014.
[I-D.ietf-jose-json-web-encryption]
Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption-33 (work in progress),
September 2014.
[I-D.ietf-jose-json-web-key]
Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-
key-33 (work in progress), September 2014.
[I-D.ietf-jose-json-web-signature]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature-33
(work in progress), September 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
2001.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC
4949, August 2007.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869, May 2010.
Biggs & Cooley Expires May 6, 2016 [Page 39]
Internet-Draft key-management-service November 2015
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
8.2. Informative References
[I-D.barnes-pervasive-problem]
Barnes, R., Schneier, B., Jennings, C., and T. Hardie,
"Pervasive Attack: A Threat Model and Problem Statement",
draft-barnes-pervasive-problem-01 (work in progress), July
2014.
[I-D.ietf-xmpp-posh]
Miller, M. and P. Saint-Andre, "PKIX over Secure HTTP
(POSH)", draft-ietf-xmpp-posh-02 (work in progress),
October 2014.
[I-D.newton-json-content-rules]
Newton, A., "A Language for Rules Describing JSON
Content", draft-newton-json-content-rules-02 (work in
progress), August 2014.
[OTR] Borisov, N., Goldberg, I., and E. Brewer, "Off-the-Record
Communication, or, Why Not To Use PGP", 2012,
<https://otr.cypherpunks.ca/otr-wpes.pdf>.
[RFC4301] Kent, S. and K. Seo, "Security Architecture for the
Internet Protocol", RFC 4301, December 2005.
[RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R.
Thayer, "OpenPGP Message Format", RFC 4880, November 2007.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009.
Biggs & Cooley Expires May 6, 2016 [Page 40]
Internet-Draft key-management-service November 2015
Authors' Addresses
Andrew Biggs
Cisco Systems
Email: adb@cisco.com
Shaun Cooley
Cisco Systems
Email: shcooley@cisco.com
Biggs & Cooley Expires May 6, 2016 [Page 41]
