sdk/fidl/fuchsia.identity.keys/key_manager.fidl - fuchsia - Git at Google

 // Copyright 2019 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 /// Defines protocols to manage and access key material that is consistent
 /// across all devices provisioned with a particular identity.
 ///
 /// Acheiving consistency implies synchonization between devices and this
 /// synchronization is not instantaneous. For some implementations
 /// synchronization may take many minutes, or even longer when devices are
 /// offline. The library provides information about the progress of the
 /// sychronization.
 library fuchsia.identity.keys;

 alias KeyId = uint32;

 /// The maximum length of a `KeySingleton` or `KeySet` name, in bytes.
 const uint32 MAX_NAME_LEN = 128;
 /// The maximum length of metadata in a `KeySingleton` or `KeySet`, in bytes.
 const uint32 MAX_METADATA_LEN = 128;
 /// The maximum length of an unstructured random `Key`, in bytes.
 const uint32 MAX_KEY_LEN = 64;

 /// The maximum number of `Key` objects in a `KeySet`.
 const uint32 MAX_KEYSET_SIZE = 64;
 /// Two times the maximum number of `Key` objects in a `KeySet`.
 const uint32 TWICE_MAX_KEYSET_SIZE = 128;

 /// Specifies the reason that a `fuchsia.identity.keys` method failed.
 enum Error {
     /// Some other problem occurred that cannot be classified using one of the
     /// more specific statuses. Retry is optional.
     UNKNOWN = 1;

     /// An internal error occurred. This usually indicates a bug within the
     /// account system itself. Retry is optional.
     INTERNAL = 2;

     /// The requested operation is not supported. This generally indicates that
     /// implementation of a new feature is not yet complete. The request should
     /// not be retried.
     UNSUPPORTED_OPERATION = 3;

     /// The request was malformed in some way, such as using an invalid key
     /// size. The request should not be retried.
     INVALID_REQUEST = 4;

     /// A local resource error occurred such as I/O, FIDL, or memory allocation
     /// failure. Retry, after a delay, is recommended.
     RESOURCE = 5;

     /// The requested key or key set is not present.  The request should not be
     /// retried.
     NOT_FOUND = 7;

     /// The request would require an illegal change to an entry that is in a
     /// frozen state.
     FROZEN = 8;
 };

 /// Summarizes the sychronization between the device's local state and the
 /// master definition for some item (such as a `KeySingleton` or `KeySet`) in an
 /// identity. Depending on the identity and implementation this "master
 /// definition" might take one of many forms such as the device itself, a
 /// server, a blockchain, a transparency directory, or a quorum of devices.
 ///
 /// Synchronization follows the state machine illustrated below. Only `KeySet`
 /// supports the `PENDING_FROZEN_ADDITION`, `PENDING_FREEZE`, and `FROZEN`
 /// states:
 /// ```
 ///             +------------------------+                 --\
 ///             |                        |                   |
 ///             |   +----------------+   | [commit           |
 ///             |   | PENDING_FROZEN |   |  success]         |
 ///             |   |   _ADDITION    |---|----------\        \ Present on
 ///             |   +----------------+   |          |        / local device
 ///             |     ^                  | Delete   |        |
 ///             |     | Freeze locally   | locally  |        |
 ///   Add       |     |                  |----------|--\     |
 ///   locally   |  +------------------+  | [commit  |  |     |
 ///   ----------|->| PENDING_ADDITION |  |  fail]   |  |     |
 ///             |  +------------------+  |          |  |     |
 ///             |          |             |          |  |     |
 ///   Add       +----------|-------------+          |  |     |
 ///   remotely             |                        |  |     |
 ///   ----------------+    | [commit success]       |  |     |
 ///                   |    |                        |  |     |  --\
 ///             +-----|----|------------+           |  |     |    |
 ///             |     v    v            |           |  |     |    |
 ///             |  +-----------------+  |           |  |     |    |
 ///   +----------->|     LIVE        |  |           |  |     |    |
 ///   |         |  +-----------------+  |           |  |     |    |
 ///   |         |         | ^           |           |  |     |    |
 ///   |         |  Freeze | | [commit   |           |  |     |    |
 ///   |         | locally | |  fail]    |           |  |     |    |
 ///   |         |         v |           | Delete    |  |     |    |
 ///   |         |  +-----------------+  | Remotely  |  |     |    |
 ///   |         |  | PENDING_FREEZE  |  |-----------|--+     |    |
 ///   |         |  +-----------------+  |           |  |     |    |
 ///   |         |          |            |           |  |     |    |
 ///   |         |          | [commit    |           |  |     |    |
 ///   |         |          |  success]  |           |  |     |    |
 ///   |         |          v            |           |  |     |    |
 ///   |         |  +-----------------+  |           |  |     |    |
 ///   | +--------->|    FROZEN       |<-------------/  |     |    |
 ///   | |       |  +-----------------+  |              |     |    |
 ///   | |       |    ^                  |              |     |    |
 ///   | |       |    | Freeze remotely  |              |     |    |
 ///   | |       |    |                  |              |     |    |
 ///   | |       +----+------------------+              |     |    |
 ///   | |                    |                         |     |    |
 ///   | | [previous state    | Delete                  |   --/    |
 ///   | |  == FROZEN]        | locally                 |          |
 ///   | |                    v            Delete       |          \ Present
 ///   | +----+      +------------------+  remotely     |          / in master
 ///   |      |      | PENDING_DELETION |---------------+          | definition
 ///   |      ^      +------------------+  [commit      |          |
 ///   |     / \              |             success]    |        --/
 ///   +----<   >-------------+                         V
 /// [else]  \ /   [commit fail]                   +---------+
 ///          v                                    | INVALID |
 ///                                               +---------+
 /// ```
 enum SynchronizationState {
     /// The item is present and not frozen on the current device but has not yet
     /// been committed into the master definition. Items in this state might not
     /// reach other devices and might become invalid if committing the addition
     /// fails.
     PENDING_ADDITION = 1;

     /// The item is present and frozen on the current device but has not yet
     /// been committed into the master definition. Items in this state might not
     /// reach other devices and might become invalid if committing the addition
     /// fails. If committing the item succeeds it will enter the `FROZEN` state
     /// directly without passing through `LIVE`.
     PENDING_FROZEN_ADDITION = 2;

     /// The item is present and not frozen both on the current device and in the
     /// master definition of the identity. It should eventually be consistent
     /// across all devices with access to the identity.
     LIVE = 3;

     /// The item has been frozen on the current device but this operation has
     /// not yet been committed. Items in this state might return to the `LIVE`
     /// state if committing the freeze fails.
     PENDING_FREEZE = 4;

     /// The item is present and frozen both on the current device and in the
     /// master definition of the identity. Mutations are no longer possible
     /// but deletions are still allowed.
     FROZEN = 5;

     /// The item is present in the master definition of the identity, but has
     /// been deleted from the current device and this deletion has not yet been
     /// committed. Items in this state might return to the `LIVE` or `FROZEN`
     /// state if committing the deletion fails.
     PENDING_DELETION = 6;
 };

 /// `KeyManager` provides access to key material that is consistent across all
 /// devices provisioned with the identity that the `KeyManager` was acquired
 /// from, such as a Fuchsia Persona.
 ///
 /// Acheiving consistency implies synchonization between devices and this
 /// synchronization is not instantaneous. For some implementations
 /// synchronization may take many minutes or even longer when devices are
 /// offline. The `KeyManager` is able to report information about the progress
 /// of this synchronization via `SynchonizationState`.
 protocol KeyManager {
     /// Returns the `KeySingleton` with the name supplied in `properties` or
     /// creates a new `KeySingleton` if this name does not exist.
     ///
     /// This method follows the hanging get pattern and does not return until
     /// the response would be different than the previous request for the same
     /// name. Errors are always returned as soon as they are detected.
     ///
     /// `properties` The properties of the new `KeySingleton`.
     ///
     /// Returns: `properties` The `KeySingletonProperties` supplied at creation,
     ///                       with uid populated.
     ///          `state` The `SychronizationState` for the `KeySingleton`.
     ///          `key` The `Key` for the `KeySingleton`.
     WatchOrCreateKeySingleton(KeySingletonProperties properties)
         -> (KeySingletonProperties properties,
             SynchronizationState state,
             Key key) error Error;

     /// Returns the `KeySingleton` with the specified name.
     ///
     /// Fails with `NOT_FOUND` if the requested name does not exist. This method
     /// follows the hanging get pattern and does not return until the response
     /// would be different than the previous request for the same name. Errors
     /// are always returned as soon as they are detected.
     ///
     /// `name` The name of the requested `KeySingleton`.
     ///
     /// Returns: `properties` The `KeySingletonProperties` supplied at creation,
     ///                       with uid populated.
     ///          `state` The `SychronizationState` for the `KeySingleton`.
     ///          `key` The `Key` for the `KeySingleton`.
     WatchKeySingleton(string:MAX_NAME_LEN name)
         -> (KeySingletonProperties properties,
             SynchronizationState state,
             Key key) error Error;

     /// Deletes a previously created `KeySingleton`.
     ///
     /// Fails with `NOT_FOUND` if the requested name does not exist. This method
     /// returns once the deletion has been recorded locally and this does not
     /// guarantee that the deletion will be successfully committed.
     ///
     /// `name` The name of the key singleton.
     DeleteKeySingleton(string:MAX_NAME_LEN name) -> () error Error;

     /// Connects a channel to the `KeySet` with the name supplied in
     /// `properties` or creates a new `KeySet` containing a single `Key` if this
     /// name does not exist.
     ///
     /// `properties` The properties of the new `KeySet`.
     /// `key_set_to_freeze` If this string is the name of another `KeySet` that
     ///                     is in the `LIVE` state, and if this method causes a
     ///                     new `KeySet` to be created, the other `KeySet` will
     ///                     be moved to the `FROZEN` state atomically with the
     ///                     new `KeySet` reaching the `LIVE` state.
     /// `key_set` The server end of a `KeySet` channel.
     GetOrCreateKeySet(
         KeySetProperties properties,
         string:MAX_NAME_LEN? key_set_to_freeze,
         request<KeySet> key_set)
         -> () error Error;

     /// Connects a channel to a previously created `KeySet`.
     ///
     /// Fails with `NOT_FOUND` if the requested name does not exist.
     ///
     /// `name` The name of the key set.
     /// `key_set` The server end of a `KeySet` channel.
     GetKeySet(string:MAX_NAME_LEN name, request<KeySet> key_set)
         -> () error Error;

     /// Freezes a previously created `KeySet`.
     ///
     /// Fails with `NOT_FOUND` if the requested name does not exist.  The method
     /// returns once the freeze has been recorded locally and this does not
     /// guarantee that the freeze will be successfully committed. If the
     /// `KeySet` is already in the `PENDING_FROZEN_ADDITION`, `PENDING_FREEZE`,
     /// or `FROZEN` state this operation has no effect.
     ///
     /// `name` The name of the key set.
     FreezeKeySet(string:MAX_NAME_LEN name) -> () error Error;

     /// Deletes a previously created `KeySet`.
     ///
     /// Fails with `NOT_FOUND` if the requested name does not exist. Once the
     /// deletion has been successfully committed any `KeySet` channels referring
     /// to it will be closed. The method returns once the deletion has been
     /// recorded locally and this does not guarantee that the deletion will
     /// be successfully committed.
     ///
     /// `name` The name of the key set.
     DeleteKeySet(string:MAX_NAME_LEN name) -> () error Error;
 };

 /// Defines the key material in a `KeySingleton` or each member of a `KeySet`.
 ///
 /// Note: Currently all keys are defined as fixed length arrays of random data
 ///       but we use an xunion to potentially allow more structured key types
 ///       in a future version of the API.
 flexible union Key {
     /// An unstructured random key of the length specified in
     /// `KeySingletonProperties.key_length` or `KeySetProperties.key_length`.
     1: bytes:MAX_KEY_LEN random_key;
 };

 /// Specifies the properties of a `KeySingleton`. These properties are provided
 /// when the `KeySingleton` is created and do not change during its lifetime.
 table KeySingletonProperties {
     /// A name of the `KeySingleton`. Unique within the `KeyManager` that
     /// supplied it at a single point in time.
     1: string:MAX_NAME_LEN name;

     /// A numeric identifier for the `KeySingleton` that is unique within the
     /// `KeyManager` that created it. The same name might be reused for
     /// different key singletons during the lifetime of a `KeyManager` but these
     /// will have different `uid` values.
     ///
     /// This field is set by the account system and must not be supplied in
     /// `KeyManager.CreateKeySingleton`.
     2: uint64 uid;

     /// Optional metadata associated with the `KeySingleton`. This is supplied
     /// by the client and is opaque to the account system.
     3: bytes:MAX_METADATA_LEN metadata;

     /// The size of the key material in this `KeySingleton` in bytes. The value
     /// must be between one and MAX_KEY_LEN inclusive.
     4: uint32 key_length;
 };

 /// Specifies the properties of a `KeySet`. These properties are provided when
 /// the `KeySet` is created and do not change during its lifetime.
 table KeySetProperties {
     /// A name of the `KeySet`. Unique within the `KeyManager` that supplied it
     /// at a single point in time.
     1: string:MAX_NAME_LEN name;

     /// A numeric identifier for the `KeySet` that is unique within the
     /// `KeyManager` that created it. The same name might be reused for
     /// different key sets during the lifetime of a `KeyManager` but these will
     /// have different `uid` values.
     ///
     /// This field is set by the account system and must not be supplied in
     /// `KeyManager.CreateKeySet`.
     2: uint64 uid;

     /// Optional metadata associated with the `KeySet`. This is supplied by the
     /// client and is opaque to the account system.
     3: bytes:MAX_METADATA_LEN metadata;

     /// The size of the keys in this `KeySet` in bytes. The value must be
     /// between one and MAX_KEY_LEN inclusive.
     4: uint32 key_length;

     /// The maximum number of keys within this `KeySet`. Old keys will be
     /// automatically deleted to prevent this limit being exceeded. The value
     /// must be between one and MAX_KEYSET_SIZE inclusive.
     5: uint32 max_keys;

     /// If true, a new key will be added to this `KeySet` each time a device
     /// with access to the identity is remotely revoked.
     /// `automatic_rotation` and `manual_rotation` cannot both be false.
     6: bool automatic_rotation;

     /// If true, users of this KeySet may cause new keys to be added by calling
     /// `KeySet.AddKey`.
     /// `automatic_rotation` and `manual_rotation` cannot both be false.
     7: bool manual_rotation;
 };

 /// `KeySet` provides access to a set of keys that is consistent across devices
 /// provisioned with the identity that it applies to.
 ///
 /// The keys within a key set are typically all used for the same purpose, such
 /// as encrypting a sensitive dataset. A recent key can be used to encrypt new
 /// data but older keys remain available to decrypt older data.
 ///
 /// All keys in the set are of the same size and each is identified by a
 /// monotonically increasing `KeyId` starting at one. A new key is added into
 /// the set on each rotation event. These rotation events may either occur
 /// "automatically" or "manually":
 /// * An automatic rotation occurs when a device's access to the identity is
 ///   remotely revoked (we trust a device that performs its own recovation to
 ///   also securely delete the key material it is holding). The newly added key
 ///   is not supplied to the device whose access was revoked. The account system
 ///   may combine the revocation of multiple devices into a single rotation
 ///   event.
 /// * A manual rotation occurs when a client calls the `AddKey` method.
 ///
 /// Old keys are deleted from the set automatically to avoid exceeding its
 /// maximum size, clients may also delete keys using the `DeleteKey` method.
 ///
 /// Optionally, a client may "mark" specific keys in the `KeySet` to track
 /// its processing of individual keys. The account system will report the
 /// latest key that has been marked on any device.
 ///
 /// A key set may be frozen, after which no further keys will be added and no
 /// further mark operations may be performed. Keys may still be deleted from a
 /// frozen key set.
 protocol KeySet {
     /// Returns the `SynchronizationState` for the entire `KeySet`. Refer to the
     /// documentation on `SynchronizationState` for the available states and
     /// state transitions.
     ///
     /// This method follows the hanging get pattern and does not return until
     /// the response would be different than the previous request.
     WatchSynchronizationState() -> (SynchronizationState state);

     /// Returns the `KeySetProperties` for this key set.
     ///
     /// These properties are fixed and will not change through the life of the
     /// key set.
     GetProperties() -> (KeySetProperties properties);

     /// Return a vector of the `KeyId` for all keys in the key set with
     /// `SynchronizationState == LIVE`.
     ///
     /// The returned vector is ordered by id. This method follows the hanging
     /// get pattern and does not return until the response would be different
     /// than the previous request.
     WatchSynchronizedIds() -> (vector<KeyId>:MAX_KEYSET_SIZE ids) error Error;

     /// Return a vector of the `KeyId` for all keys in the key set, whatever
     /// their `SynchronizationState`.
     ///
     /// The returned vector is ordered by id. This method follows the hanging
     /// get pattern and does not return until the response would be different
     /// than the previous request.
     ///
     /// Note: Worst case this vector will be twice the maximum size of the key
     ///       set. Consider a full key set that contains N `LIVE` keys.
     ///       N manual rotations are now performed before the first succeeds.
     ///       Each rotation moves a key from the `LIVE` state to the
     ///       `PENDING_DELETION` state and adds a new key in the
     ///       `PENDING_ADDITION` state.
     WatchAllIds() -> (vector<KeyId>:TWICE_MAX_KEYSET_SIZE ids) error Error;

     /// Returns a `Key` from the key set.
     ///
     /// Fails with `NOT_FOUND` if the requested key does not exist. This method
     /// follows the hanging get pattern and does not return until the response
     /// would be different than the previous request for this `id`.
     ///
     /// `id` The `KeyId` of the requested key.
     ///
     /// Returns: `key` The requested `Key`.
     ///          `state` The current `SynchronizationState` of the key. Note
     ///                  that keys in `PENDING_ADDITION` are not final: they
     ///                  might never reach other devices and the same `KeyId`
     ///                  might be reused for a different `Key` in the future.
     WatchKey(KeyId id) -> (Key key, SynchronizationState state) error Error;

     /// Deletes a `Key` from the key set.
     ///
     /// Fails with `NOT_FOUND` if the requested key does not exist. The method
     /// returns once the deletion has been recorded locally and this does not
     /// guarantee that the deletion will be successfully committed.
     ///
     /// `id` The `KeyId` of the requested key.
     DeleteKey(KeyId id) -> () error Error;

     /// Adds a new `Key` to the key set, i.e. performs a manual key rotation.
     ///
     /// The method returns once the addition has been recorded locally and this
     /// does not guarantee that the addition will be successfully committed.
     ///
     /// Fails with `UNSUPPORTED_OPERATION` if `KeySetProperties.manual_rotation`
     /// is false or with `FROZEN` if the key set has been frozen.
     AddKey() -> () error Error;

     /// Performs a "Mark" operation on a key, such that it is eligible to be
     /// returned by `GetMaxMarkedId`.
     ///
     /// The largest `KeyId` on which a mark operation has been performed is
     /// synchronized across devices.
     ///
     /// Fails with `FROZEN` if the key set has been frozen.
     ///
     /// `id` The `KeyId` of the requested key. The method will fail with
     ///      NOT_FOUND if this key does not exist.
     MarkId(KeyId id) -> () error Error;

     /// Returns the maximum `KeyId` on which `MarkId` has been called and
     /// successfully commited.
     ///
     /// This method follows the hanging get pattern and does not return until
     /// the response would be different than the previous request.
     ///
     /// Returns: `id` The largest `KeyId` for which a `MarkId` call has been
     ///               made and successfully committed, or zero if no `MarkId`
     ///               calls have been committed.
     WatchMaxCommittedMarkedId() -> (KeyId id) error Error;

     /// Returns the maximum `KeyId` on which `MarkId` has been called, even if
     /// this has not yet been successfully committed.
     ///
     /// This method follows the hanging get pattern and does not return until
     /// the response would be different than the previous request.
     ///
     /// Returns: `id` The largest `KeyId` for which a `MarkId` call has been
     ///               made, or zero if no `MarkId` calls have been made.
     WatchMaxPendingMarkedId() -> (KeyId id) error Error;
 };
	// Copyright 2019 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	/// Defines protocols to manage and access key material that is consistent
	/// across all devices provisioned with a particular identity.
	///
	/// Acheiving consistency implies synchonization between devices and this
	/// synchronization is not instantaneous. For some implementations
	/// synchronization may take many minutes, or even longer when devices are
	/// offline. The library provides information about the progress of the
	/// sychronization.
	library fuchsia.identity.keys;

	alias KeyId = uint32;

	/// The maximum length of a `KeySingleton` or `KeySet` name, in bytes.
	const uint32 MAX_NAME_LEN = 128;
	/// The maximum length of metadata in a `KeySingleton` or `KeySet`, in bytes.
	const uint32 MAX_METADATA_LEN = 128;
	/// The maximum length of an unstructured random `Key`, in bytes.
	const uint32 MAX_KEY_LEN = 64;

	/// The maximum number of `Key` objects in a `KeySet`.
	const uint32 MAX_KEYSET_SIZE = 64;
	/// Two times the maximum number of `Key` objects in a `KeySet`.
	const uint32 TWICE_MAX_KEYSET_SIZE = 128;

	/// Specifies the reason that a `fuchsia.identity.keys` method failed.
	enum Error {
	/// Some other problem occurred that cannot be classified using one of the
	/// more specific statuses. Retry is optional.
	UNKNOWN = 1;

	/// An internal error occurred. This usually indicates a bug within the
	/// account system itself. Retry is optional.
	INTERNAL = 2;

	/// The requested operation is not supported. This generally indicates that
	/// implementation of a new feature is not yet complete. The request should
	/// not be retried.
	UNSUPPORTED_OPERATION = 3;

	/// The request was malformed in some way, such as using an invalid key
	/// size. The request should not be retried.
	INVALID_REQUEST = 4;

	/// A local resource error occurred such as I/O, FIDL, or memory allocation
	/// failure. Retry, after a delay, is recommended.
	RESOURCE = 5;

	/// The requested key or key set is not present. The request should not be
	/// retried.
	NOT_FOUND = 7;

	/// The request would require an illegal change to an entry that is in a
	/// frozen state.
	FROZEN = 8;
	};

	/// Summarizes the sychronization between the device's local state and the
	/// master definition for some item (such as a `KeySingleton` or `KeySet`) in an
	/// identity. Depending on the identity and implementation this "master
	/// definition" might take one of many forms such as the device itself, a
	/// server, a blockchain, a transparency directory, or a quorum of devices.
	///
	/// Synchronization follows the state machine illustrated below. Only `KeySet`
	/// supports the `PENDING_FROZEN_ADDITION`, `PENDING_FREEZE`, and `FROZEN`
	/// states:
	/// ```
	/// +------------------------+ --\
	/// \| \| \|
	/// \| +----------------+ \| [commit \|
	/// \| \| PENDING_FROZEN \| \| success] \|
	/// \| \| _ADDITION \|---\|----------\ \ Present on
	/// \| +----------------+ \| \| / local device
	/// \| ^ \| Delete \| \|
	/// \| \| Freeze locally \| locally \| \|
	/// Add \| \| \|----------\|--\ \|
	/// locally \| +------------------+ \| [commit \| \| \|
	/// ----------\|->\| PENDING_ADDITION \| \| fail] \| \| \|
	/// \| +------------------+ \| \| \| \|
	/// \| \| \| \| \| \|
	/// Add +----------\|-------------+ \| \| \|
	/// remotely \| \| \| \|
	/// ----------------+ \| [commit success] \| \| \|
	/// \| \| \| \| \| --\
	/// +-----\|----\|------------+ \| \| \| \|
	/// \| v v \| \| \| \| \|
	/// \| +-----------------+ \| \| \| \| \|
	/// +----------->\| LIVE \| \| \| \| \| \|
	/// \| \| +-----------------+ \| \| \| \| \|
	/// \| \| \| ^ \| \| \| \| \|
	/// \| \| Freeze \| \| [commit \| \| \| \| \|
	/// \| \| locally \| \| fail] \| \| \| \| \|
	/// \| \| v \| \| Delete \| \| \| \|
	/// \| \| +-----------------+ \| Remotely \| \| \| \|
	/// \| \| \| PENDING_FREEZE \| \|-----------\|--+ \| \|
	/// \| \| +-----------------+ \| \| \| \| \|
	/// \| \| \| \| \| \| \| \|
	/// \| \| \| [commit \| \| \| \| \|
	/// \| \| \| success] \| \| \| \| \|
	/// \| \| v \| \| \| \| \|
	/// \| \| +-----------------+ \| \| \| \| \|
	/// \| +--------->\| FROZEN \|<-------------/ \| \| \|
	/// \| \| \| +-----------------+ \| \| \| \|
	/// \| \| \| ^ \| \| \| \|
	/// \| \| \| \| Freeze remotely \| \| \| \|
	/// \| \| \| \| \| \| \| \|
	/// \| \| +----+------------------+ \| \| \|
	/// \| \| \| \| \| \|
	/// \| \| [previous state \| Delete \| --/ \|
	/// \| \| == FROZEN] \| locally \| \|
	/// \| \| v Delete \| \ Present
	/// \| +----+ +------------------+ remotely \| / in master
	/// \| \| \| PENDING_DELETION \|---------------+ \| definition
	/// \| ^ +------------------+ [commit \| \|
	/// \| / \ \| success] \| --/
	/// +----< >-------------+ V
	/// [else] \ / [commit fail] +---------+
	/// v \| INVALID \|
	/// +---------+
	/// ```
	enum SynchronizationState {
	/// The item is present and not frozen on the current device but has not yet
	/// been committed into the master definition. Items in this state might not
	/// reach other devices and might become invalid if committing the addition
	/// fails.
	PENDING_ADDITION = 1;

	/// The item is present and frozen on the current device but has not yet
	/// been committed into the master definition. Items in this state might not
	/// reach other devices and might become invalid if committing the addition
	/// fails. If committing the item succeeds it will enter the `FROZEN` state
	/// directly without passing through `LIVE`.
	PENDING_FROZEN_ADDITION = 2;

	/// The item is present and not frozen both on the current device and in the
	/// master definition of the identity. It should eventually be consistent
	/// across all devices with access to the identity.
	LIVE = 3;

	/// The item has been frozen on the current device but this operation has
	/// not yet been committed. Items in this state might return to the `LIVE`
	/// state if committing the freeze fails.
	PENDING_FREEZE = 4;

	/// The item is present and frozen both on the current device and in the
	/// master definition of the identity. Mutations are no longer possible
	/// but deletions are still allowed.
	FROZEN = 5;

	/// The item is present in the master definition of the identity, but has
	/// been deleted from the current device and this deletion has not yet been
	/// committed. Items in this state might return to the `LIVE` or `FROZEN`
	/// state if committing the deletion fails.
	PENDING_DELETION = 6;
	};

	/// `KeyManager` provides access to key material that is consistent across all
	/// devices provisioned with the identity that the `KeyManager` was acquired
	/// from, such as a Fuchsia Persona.
	///
	/// Acheiving consistency implies synchonization between devices and this
	/// synchronization is not instantaneous. For some implementations
	/// synchronization may take many minutes or even longer when devices are
	/// offline. The `KeyManager` is able to report information about the progress
	/// of this synchronization via `SynchonizationState`.
	protocol KeyManager {
	/// Returns the `KeySingleton` with the name supplied in `properties` or
	/// creates a new `KeySingleton` if this name does not exist.
	///
	/// This method follows the hanging get pattern and does not return until
	/// the response would be different than the previous request for the same
	/// name. Errors are always returned as soon as they are detected.
	///
	/// `properties` The properties of the new `KeySingleton`.
	///
	/// Returns: `properties` The `KeySingletonProperties` supplied at creation,
	/// with uid populated.
	/// `state` The `SychronizationState` for the `KeySingleton`.
	/// `key` The `Key` for the `KeySingleton`.
	WatchOrCreateKeySingleton(KeySingletonProperties properties)
	-> (KeySingletonProperties properties,
	SynchronizationState state,
	Key key) error Error;

	/// Returns the `KeySingleton` with the specified name.
	///
	/// Fails with `NOT_FOUND` if the requested name does not exist. This method
	/// follows the hanging get pattern and does not return until the response
	/// would be different than the previous request for the same name. Errors
	/// are always returned as soon as they are detected.
	///
	/// `name` The name of the requested `KeySingleton`.
	///
	/// Returns: `properties` The `KeySingletonProperties` supplied at creation,
	/// with uid populated.
	/// `state` The `SychronizationState` for the `KeySingleton`.
	/// `key` The `Key` for the `KeySingleton`.
	WatchKeySingleton(string:MAX_NAME_LEN name)
	-> (KeySingletonProperties properties,
	SynchronizationState state,
	Key key) error Error;

	/// Deletes a previously created `KeySingleton`.
	///
	/// Fails with `NOT_FOUND` if the requested name does not exist. This method
	/// returns once the deletion has been recorded locally and this does not
	/// guarantee that the deletion will be successfully committed.
	///
	/// `name` The name of the key singleton.
	DeleteKeySingleton(string:MAX_NAME_LEN name) -> () error Error;

	/// Connects a channel to the `KeySet` with the name supplied in
	/// `properties` or creates a new `KeySet` containing a single `Key` if this
	/// name does not exist.
	///
	/// `properties` The properties of the new `KeySet`.
	/// `key_set_to_freeze` If this string is the name of another `KeySet` that
	/// is in the `LIVE` state, and if this method causes a
	/// new `KeySet` to be created, the other `KeySet` will
	/// be moved to the `FROZEN` state atomically with the
	/// new `KeySet` reaching the `LIVE` state.
	/// `key_set` The server end of a `KeySet` channel.
	GetOrCreateKeySet(
	KeySetProperties properties,
	string:MAX_NAME_LEN? key_set_to_freeze,
	request<KeySet> key_set)
	-> () error Error;

	/// Connects a channel to a previously created `KeySet`.
	///
	/// Fails with `NOT_FOUND` if the requested name does not exist.
	///
	/// `name` The name of the key set.
	/// `key_set` The server end of a `KeySet` channel.
	GetKeySet(string:MAX_NAME_LEN name, request<KeySet> key_set)
	-> () error Error;

	/// Freezes a previously created `KeySet`.
	///
	/// Fails with `NOT_FOUND` if the requested name does not exist. The method
	/// returns once the freeze has been recorded locally and this does not
	/// guarantee that the freeze will be successfully committed. If the
	/// `KeySet` is already in the `PENDING_FROZEN_ADDITION`, `PENDING_FREEZE`,
	/// or `FROZEN` state this operation has no effect.
	///
	/// `name` The name of the key set.
	FreezeKeySet(string:MAX_NAME_LEN name) -> () error Error;

	/// Deletes a previously created `KeySet`.
	///
	/// Fails with `NOT_FOUND` if the requested name does not exist. Once the
	/// deletion has been successfully committed any `KeySet` channels referring
	/// to it will be closed. The method returns once the deletion has been
	/// recorded locally and this does not guarantee that the deletion will
	/// be successfully committed.
	///
	/// `name` The name of the key set.
	DeleteKeySet(string:MAX_NAME_LEN name) -> () error Error;
	};

	/// Defines the key material in a `KeySingleton` or each member of a `KeySet`.
	///
	/// Note: Currently all keys are defined as fixed length arrays of random data
	/// but we use an xunion to potentially allow more structured key types
	/// in a future version of the API.
	flexible union Key {
	/// An unstructured random key of the length specified in
	/// `KeySingletonProperties.key_length` or `KeySetProperties.key_length`.
	1: bytes:MAX_KEY_LEN random_key;
	};

	/// Specifies the properties of a `KeySingleton`. These properties are provided
	/// when the `KeySingleton` is created and do not change during its lifetime.
	table KeySingletonProperties {
	/// A name of the `KeySingleton`. Unique within the `KeyManager` that
	/// supplied it at a single point in time.
	1: string:MAX_NAME_LEN name;

	/// A numeric identifier for the `KeySingleton` that is unique within the
	/// `KeyManager` that created it. The same name might be reused for
	/// different key singletons during the lifetime of a `KeyManager` but these
	/// will have different `uid` values.
	///
	/// This field is set by the account system and must not be supplied in
	/// `KeyManager.CreateKeySingleton`.
	2: uint64 uid;

	/// Optional metadata associated with the `KeySingleton`. This is supplied
	/// by the client and is opaque to the account system.
	3: bytes:MAX_METADATA_LEN metadata;

	/// The size of the key material in this `KeySingleton` in bytes. The value
	/// must be between one and MAX_KEY_LEN inclusive.
	4: uint32 key_length;
	};

	/// Specifies the properties of a `KeySet`. These properties are provided when
	/// the `KeySet` is created and do not change during its lifetime.
	table KeySetProperties {
	/// A name of the `KeySet`. Unique within the `KeyManager` that supplied it
	/// at a single point in time.
	1: string:MAX_NAME_LEN name;

	/// A numeric identifier for the `KeySet` that is unique within the
	/// `KeyManager` that created it. The same name might be reused for
	/// different key sets during the lifetime of a `KeyManager` but these will
	/// have different `uid` values.
	///
	/// This field is set by the account system and must not be supplied in
	/// `KeyManager.CreateKeySet`.
	2: uint64 uid;

	/// Optional metadata associated with the `KeySet`. This is supplied by the
	/// client and is opaque to the account system.
	3: bytes:MAX_METADATA_LEN metadata;

	/// The size of the keys in this `KeySet` in bytes. The value must be
	/// between one and MAX_KEY_LEN inclusive.
	4: uint32 key_length;

	/// The maximum number of keys within this `KeySet`. Old keys will be
	/// automatically deleted to prevent this limit being exceeded. The value
	/// must be between one and MAX_KEYSET_SIZE inclusive.
	5: uint32 max_keys;

	/// If true, a new key will be added to this `KeySet` each time a device
	/// with access to the identity is remotely revoked.
	/// `automatic_rotation` and `manual_rotation` cannot both be false.
	6: bool automatic_rotation;

	/// If true, users of this KeySet may cause new keys to be added by calling
	/// `KeySet.AddKey`.
	/// `automatic_rotation` and `manual_rotation` cannot both be false.
	7: bool manual_rotation;
	};

	/// `KeySet` provides access to a set of keys that is consistent across devices
	/// provisioned with the identity that it applies to.
	///
	/// The keys within a key set are typically all used for the same purpose, such
	/// as encrypting a sensitive dataset. A recent key can be used to encrypt new
	/// data but older keys remain available to decrypt older data.
	///
	/// All keys in the set are of the same size and each is identified by a
	/// monotonically increasing `KeyId` starting at one. A new key is added into
	/// the set on each rotation event. These rotation events may either occur
	/// "automatically" or "manually":
	/// * An automatic rotation occurs when a device's access to the identity is
	/// remotely revoked (we trust a device that performs its own recovation to
	/// also securely delete the key material it is holding). The newly added key
	/// is not supplied to the device whose access was revoked. The account system
	/// may combine the revocation of multiple devices into a single rotation
	/// event.
	/// * A manual rotation occurs when a client calls the `AddKey` method.
	///
	/// Old keys are deleted from the set automatically to avoid exceeding its
	/// maximum size, clients may also delete keys using the `DeleteKey` method.
	///
	/// Optionally, a client may "mark" specific keys in the `KeySet` to track
	/// its processing of individual keys. The account system will report the
	/// latest key that has been marked on any device.
	///
	/// A key set may be frozen, after which no further keys will be added and no
	/// further mark operations may be performed. Keys may still be deleted from a
	/// frozen key set.
	protocol KeySet {
	/// Returns the `SynchronizationState` for the entire `KeySet`. Refer to the
	/// documentation on `SynchronizationState` for the available states and
	/// state transitions.
	///
	/// This method follows the hanging get pattern and does not return until
	/// the response would be different than the previous request.
	WatchSynchronizationState() -> (SynchronizationState state);

	/// Returns the `KeySetProperties` for this key set.
	///
	/// These properties are fixed and will not change through the life of the
	/// key set.
	GetProperties() -> (KeySetProperties properties);

	/// Return a vector of the `KeyId` for all keys in the key set with
	/// `SynchronizationState == LIVE`.
	///
	/// The returned vector is ordered by id. This method follows the hanging
	/// get pattern and does not return until the response would be different
	/// than the previous request.
	WatchSynchronizedIds() -> (vector<KeyId>:MAX_KEYSET_SIZE ids) error Error;

	/// Return a vector of the `KeyId` for all keys in the key set, whatever
	/// their `SynchronizationState`.
	///
	/// The returned vector is ordered by id. This method follows the hanging
	/// get pattern and does not return until the response would be different
	/// than the previous request.
	///
	/// Note: Worst case this vector will be twice the maximum size of the key
	/// set. Consider a full key set that contains N `LIVE` keys.
	/// N manual rotations are now performed before the first succeeds.
	/// Each rotation moves a key from the `LIVE` state to the
	/// `PENDING_DELETION` state and adds a new key in the
	/// `PENDING_ADDITION` state.
	WatchAllIds() -> (vector<KeyId>:TWICE_MAX_KEYSET_SIZE ids) error Error;

	/// Returns a `Key` from the key set.
	///
	/// Fails with `NOT_FOUND` if the requested key does not exist. This method
	/// follows the hanging get pattern and does not return until the response
	/// would be different than the previous request for this `id`.
	///
	/// `id` The `KeyId` of the requested key.
	///
	/// Returns: `key` The requested `Key`.
	/// `state` The current `SynchronizationState` of the key. Note
	/// that keys in `PENDING_ADDITION` are not final: they
	/// might never reach other devices and the same `KeyId`
	/// might be reused for a different `Key` in the future.
	WatchKey(KeyId id) -> (Key key, SynchronizationState state) error Error;

	/// Deletes a `Key` from the key set.
	///
	/// Fails with `NOT_FOUND` if the requested key does not exist. The method
	/// returns once the deletion has been recorded locally and this does not
	/// guarantee that the deletion will be successfully committed.
	///
	/// `id` The `KeyId` of the requested key.
	DeleteKey(KeyId id) -> () error Error;

	/// Adds a new `Key` to the key set, i.e. performs a manual key rotation.
	///
	/// The method returns once the addition has been recorded locally and this
	/// does not guarantee that the addition will be successfully committed.
	///
	/// Fails with `UNSUPPORTED_OPERATION` if `KeySetProperties.manual_rotation`
	/// is false or with `FROZEN` if the key set has been frozen.
	AddKey() -> () error Error;

	/// Performs a "Mark" operation on a key, such that it is eligible to be
	/// returned by `GetMaxMarkedId`.
	///
	/// The largest `KeyId` on which a mark operation has been performed is
	/// synchronized across devices.
	///
	/// Fails with `FROZEN` if the key set has been frozen.
	///
	/// `id` The `KeyId` of the requested key. The method will fail with
	/// NOT_FOUND if this key does not exist.
	MarkId(KeyId id) -> () error Error;

	/// Returns the maximum `KeyId` on which `MarkId` has been called and
	/// successfully commited.
	///
	/// This method follows the hanging get pattern and does not return until
	/// the response would be different than the previous request.
	///
	/// Returns: `id` The largest `KeyId` for which a `MarkId` call has been
	/// made and successfully committed, or zero if no `MarkId`
	/// calls have been committed.
	WatchMaxCommittedMarkedId() -> (KeyId id) error Error;

	/// Returns the maximum `KeyId` on which `MarkId` has been called, even if
	/// this has not yet been successfully committed.
	///
	/// This method follows the hanging get pattern and does not return until
	/// the response would be different than the previous request.
	///
	/// Returns: `id` The largest `KeyId` for which a `MarkId` call has been
	/// made, or zero if no `MarkId` calls have been made.
	WatchMaxPendingMarkedId() -> (KeyId id) error Error;
	};