[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03

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]


Html markup produced by rfcmarkup 1.124, available from https://tools.ietf.org/tools/rfcmarkup/