KMS API spec

  The KMS server exposes an API through which clients may

   securely establish and share cryptographic keying material used for

   the E2E encryption of content that is transited through the cloud

   provider's services.  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.

Below is the sequence 

Client A requests the generation of a new unbound key from the

       KMS.

   2.  Client A encrypts a communications resource using the unbound KMS

       key and shares it via a resource server.

   3.  Client A requests the creation of a new KMS resource object (KRO)

       to represent the communications resource.  Client A also

       instructs the KMS to bind the KMS key used in step (2) to the new

       KRO and to authorize user B to retrieve keys bound to the KRO.

   4.  Client B accesses the communications resource shared by client A

       and receives the encrypted data.

Biggs & Cooley           Expires January 4, 2016                [Page 8]

Internet-Draft           key-management-service                July 2015

   5.  Client B obtains, through some means not defined by this

       specification, the URL of the KMS key used to encrypt the

       communications resource.

   6.  Client B requests the KMS key from the KMS server.  The KMS

       server, recognizing user B as authorized on the KRO to which the

       key is bound, returns the KMS key.

   7.  Client B decrypts the communications resource using the KMS key.

Securing an HTTP File Sharing Service

For this scenario we also assume that the file sharing service is

   trusted by user A with the role of providing a file sharing service

   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

   (not shown) and KMS server deployed by an entity that A regards as a

   trusted party

   1.  Client A requests from the KMS some number of unbound KMS keys.

   2.  Client A selects an unbound key from the set of keys obtained

       step (1), encrypts the file to be shared, and posts the encrypted

       content to the file sharing service.  The file sharing service

       responds with a URL that uniquely identifies the shared file.

   3.  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).

   4.  Client A requests the creation of a KMS resource object (KRO) on

       the KMS to represent the shared file.  In this message the client

       also requests that the key from step (2) be bound to the newly

       created KRO and that the users of clients B and C be authorized

       to retrieve keys bound to the KRO.

   5.  Client B retrieves the shared file from the file sharing service.

   6.  Client B requests from the KMS all keys bound to the KRO

       associated with the shared file's URL.  Recognizing client B as

       authorized on the KRO, the KMS returns the key bound to the KRO

       by client A in step (4).

   7.  Client B decrypts the shared file using the key obtained in step

       (6).

   8.  Client C performs steps (5) through (7) in the same fashion as

       client B.

   It is worth noting that a race condition does exist where step (6)

   could occur before step (4) completes.  This will result in a client

   being temporarily denied access to the key used to encrypt the shared

   file.

references:

https://tools.ietf.org/html/draft-abiggs-saag-key-management-service-02