sdk/fidl/fuchsia.identity.account/account_manager.fidl - fuchsia - Git at Google

 // Copyright 2018 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.
 library fuchsia.identity.account;

 using fuchsia.identity.authentication;

 /// The maximum length of the (UTF-8 encoded) password used in the temporary
 /// methods to support an initial prototype of password-based encryption.
 @deprecated
 const MAX_PASSWORD_SIZE uint32 = 128;

 /// AccountManager manages the overall state of system accounts and personae on
 /// a Fuchsia device. The AccountManager is the most powerful protocol in the
 /// account system and is intended only for use by the most trusted parts of the
 /// system.
 @discoverable
 closed protocol AccountManager {
     /// Returns a vector of all accounts provisioned on the device.
     strict GetAccountIds() -> (struct {
         account_ids vector<AccountId>:MAX_ACCOUNTS_PER_DEVICE;
     });

     /// Returns the metadata for a single account.
     ///
     /// `id` The account's identifier as returned by GetAccountIds()
     strict GetAccountMetadata(struct {
         id AccountId;
     }) -> (struct {
         metadata AccountMetadata;
     }) error Error;

     /// Connects a channel to read properties of and perform operations on
     /// one account. If the account is locked, an interactive authentication
     /// attempt will be invoked as part of this call.
     ///
     /// `id` [required] The account's identifier as returned by GetAccountIds()
     /// `interaction` An `Interaction` channel enabling the user to complete
     ///               authentication challenges if these are necessary.
     /// `account` [required] The server end of an `Account` channel
     ///
     /// Fails with:
     /// - `INVALID_REQUEST` if the `id` does not exist.
     /// - `FAILED_PRECONDITION` if the account is locked but no `interaction`
     ///   channel was supplied to perform authentication.
     /// - `ABORTED` if the client closes the `interaction` channel.
     strict GetAccount(resource table {
         1: id AccountId;
         2: interaction server_end:fuchsia.identity.authentication.Interaction;
         // 3 is reserved for auto_lock in a near-future CL.
         4: account server_end:Account;
     }) -> () error Error;

     /// Connects a channel to read properties of and perform operations on
     /// one account. If the account is locked, the supplied password will be
     /// used to attempt authentication.
     ///
     /// This is a temporary method used for an initial prototype of
     /// password-based encryption. Its usage will be replaced by the
     /// `GetAccount` method where the hardcoded authentication=password
     /// assumption is replaced by a channel that can support different
     /// authentication mechanisms.
     ///
     /// `id` The account's identifier as returned by GetAccountIds()
     /// `password` The account's password
     /// `account` The server end of an `Account` channel
     ///
     /// Fails with `FAILED_AUTHENTICATION` if the password was not correct.
     @deprecated
     strict DeprecatedGetAccount(resource struct {
         id AccountId;
         password string:MAX_PASSWORD_SIZE;
         account server_end:Account;
     }) -> () error Error;

     /// Connects a channel that will receive changes in the provisioned
     /// accounts and their authentication state. Optionally this channel will
     /// also receive the initial set of accounts and authentication states onto
     /// which changes may be applied.
     ///
     /// `listener` [required] The client end of an `AccountListener` channel
     /// `initial_state` If true, the listener will receive an event containing
     ///                 the initial state for all accounts.
     /// `add_account` If true, the listener will receive events when a new
     ///               account is added to the device.
     /// `remove_account` If true, the listener will receive events when an
     ///                  account is removed from the device.
     /// `granularity` An `AuthChangeGranularity` expressing the magnitude of
     ///               change in authentication state that will lead to
     ///               AuthStateChange events. If absent, AuthStateChange events
     ///               will not be sent.
     strict RegisterAccountListener(resource table {
         1: listener client_end:AccountListener;
         2: initial_state bool;
         3: add_account bool;
         4: remove_account bool;
         5: granularity AuthChangeGranularity;
     }) -> () error Error;

     /// Removes an account from the device.
     ///
     /// `id` The account's identifier as returned by GetAccountIds()
     strict RemoveAccount(struct {
         id AccountId;
     }) -> () error Error;

     /// Adds a new account to the device. If this operation if successful the
     /// newly created account will be unlocked and may be accessed using
     /// `GetAccount` without further authentication.
     ///
     /// `lifetime` [required] The lifetime of the account
     /// `metadata` [required] Metadata for the new account
     /// `interaction` An `Interaction` channel enabling the user to select and
     ///               enroll authentication mechanisms for the new account.
     ///
     /// Returns: `account_id` The identifier of the newly added account
     ///
     /// Fails with:
     /// - `INVALID_REQUEST` if policy requires authentication factors for the
     ///    new account but no `interaction` channel was supplied.
     /// - `ABORTED` if the client closes the `interaction` channel.
     strict ProvisionNewAccount(resource table {
         1: lifetime Lifetime;
         2: metadata AccountMetadata;
         3: interaction server_end:fuchsia.identity.authentication.Interaction;
     }) -> (struct {
         account_id AccountId;
     }) error Error;

     /// Adds a new system account to the device using the supplied password
     /// as the only authentication mechanism. The account is automatically
     /// unlocked and the supplied channel is connected to read properties of
     /// and perform operations on the account.
     ///
     /// This is a temporary method used for an initial prototype of
     /// password-based encryption. Its usage will be replaced by the
     /// `ProvisionNewAccount` method where the hardcoded
     /// authentication=password assumption is replaced by a channel
     /// that can support different authentication mechanisms.
     ///
     /// `password` The password to be used for the new account
     /// `metadata` Metadata for the new account
     /// `account` The server end of an `Account` channel
     ///
     /// Fails with `INVALID_REQUEST` if the password does not meet
     /// minimum strength requirements.
     @deprecated
     strict DeprecatedProvisionNewAccount(resource struct {
         password string:MAX_PASSWORD_SIZE;
         metadata AccountMetadata;
         account server_end:Account;
     }) -> () error Error;
 };

 /// An `AuthState` along with the system account that it applies to.
 type AccountAuthState = struct {
     /// A unique identifier for the account.
     account_id AccountId;
     /// An authentication state for the account.
     auth_state AuthState;
 };

 /// A protocol to receive events when the set of accounts on a device or the
 /// authentication states of these accounts change.
 ///
 /// AccountListeners may be registered through the AccountManager protocol
 /// and this registration also defines which types of event should be sent to
 /// the listener. Optionally, the AccountListener will receive an initial state
 /// event onto which the change events may be safely accumulated.
 ///
 /// All methods include an empty response to follow the "Throttle push using
 /// acknowledgements" FIDL design pattern.
 closed protocol AccountListener {
     /// A method that is called to communicate the initial set of accounts and
     /// their authentication states. OnInitialize is called exactly once if and
     /// only if AccountListenerOptions.initial_state was set when creating the
     /// AccountListener. When called, it will always be the first call on the
     /// channel. If no accounts are present on the device the vector will be
     /// empty.
     ///
     /// `account_states` The set of initial states.
     strict OnInitialize(struct {
         account_states vector<AccountAuthState>:MAX_ACCOUNTS_PER_DEVICE;
     }) -> ();

     /// A method that is called when a new account is added to the device.
     /// This method is only called if AccountListenerOptions.add_account was
     /// set when creating the AccountListener.
     ///
     /// `account_state` The initial state for the newly added account.
     strict OnAccountAdded(struct {
         account_state AccountAuthState;
     }) -> ();

     /// A method that is called when a provisioned account is removed.
     /// This method is only called if AccountListenerOptions.remove_account was
     /// set when creating the AccountListener.
     strict OnAccountRemoved(struct {
         account_id AccountId;
     }) -> ();

     /// A method that is called when the authentication state of any provisioned
     /// account changes.
     strict OnAuthStateChanged(struct {
         account_auth_state AccountAuthState;
     }) -> ();
 };
	// Copyright 2018 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.
	library fuchsia.identity.account;

	using fuchsia.identity.authentication;

	/// The maximum length of the (UTF-8 encoded) password used in the temporary
	/// methods to support an initial prototype of password-based encryption.
	@deprecated
	const MAX_PASSWORD_SIZE uint32 = 128;

	/// AccountManager manages the overall state of system accounts and personae on
	/// a Fuchsia device. The AccountManager is the most powerful protocol in the
	/// account system and is intended only for use by the most trusted parts of the
	/// system.
	@discoverable
	closed protocol AccountManager {
	/// Returns a vector of all accounts provisioned on the device.
	strict GetAccountIds() -> (struct {
	account_ids vector<AccountId>:MAX_ACCOUNTS_PER_DEVICE;
	});

	/// Returns the metadata for a single account.
	///
	/// `id` The account's identifier as returned by GetAccountIds()
	strict GetAccountMetadata(struct {
	id AccountId;
	}) -> (struct {
	metadata AccountMetadata;
	}) error Error;

	/// Connects a channel to read properties of and perform operations on
	/// one account. If the account is locked, an interactive authentication
	/// attempt will be invoked as part of this call.
	///
	/// `id` [required] The account's identifier as returned by GetAccountIds()
	/// `interaction` An `Interaction` channel enabling the user to complete
	/// authentication challenges if these are necessary.
	/// `account` [required] The server end of an `Account` channel
	///
	/// Fails with:
	/// - `INVALID_REQUEST` if the `id` does not exist.
	/// - `FAILED_PRECONDITION` if the account is locked but no `interaction`
	/// channel was supplied to perform authentication.
	/// - `ABORTED` if the client closes the `interaction` channel.
	strict GetAccount(resource table {
	1: id AccountId;
	2: interaction server_end:fuchsia.identity.authentication.Interaction;
	// 3 is reserved for auto_lock in a near-future CL.
	4: account server_end:Account;
	}) -> () error Error;

	/// Connects a channel to read properties of and perform operations on
	/// one account. If the account is locked, the supplied password will be
	/// used to attempt authentication.
	///
	/// This is a temporary method used for an initial prototype of
	/// password-based encryption. Its usage will be replaced by the
	/// `GetAccount` method where the hardcoded authentication=password
	/// assumption is replaced by a channel that can support different
	/// authentication mechanisms.
	///
	/// `id` The account's identifier as returned by GetAccountIds()
	/// `password` The account's password
	/// `account` The server end of an `Account` channel
	///
	/// Fails with `FAILED_AUTHENTICATION` if the password was not correct.
	@deprecated
	strict DeprecatedGetAccount(resource struct {
	id AccountId;
	password string:MAX_PASSWORD_SIZE;
	account server_end:Account;
	}) -> () error Error;

	/// Connects a channel that will receive changes in the provisioned
	/// accounts and their authentication state. Optionally this channel will
	/// also receive the initial set of accounts and authentication states onto
	/// which changes may be applied.
	///
	/// `listener` [required] The client end of an `AccountListener` channel
	/// `initial_state` If true, the listener will receive an event containing
	/// the initial state for all accounts.
	/// `add_account` If true, the listener will receive events when a new
	/// account is added to the device.
	/// `remove_account` If true, the listener will receive events when an
	/// account is removed from the device.
	/// `granularity` An `AuthChangeGranularity` expressing the magnitude of
	/// change in authentication state that will lead to
	/// AuthStateChange events. If absent, AuthStateChange events
	/// will not be sent.
	strict RegisterAccountListener(resource table {
	1: listener client_end:AccountListener;
	2: initial_state bool;
	3: add_account bool;
	4: remove_account bool;
	5: granularity AuthChangeGranularity;
	}) -> () error Error;

	/// Removes an account from the device.
	///
	/// `id` The account's identifier as returned by GetAccountIds()
	strict RemoveAccount(struct {
	id AccountId;
	}) -> () error Error;

	/// Adds a new account to the device. If this operation if successful the
	/// newly created account will be unlocked and may be accessed using
	/// `GetAccount` without further authentication.
	///
	/// `lifetime` [required] The lifetime of the account
	/// `metadata` [required] Metadata for the new account
	/// `interaction` An `Interaction` channel enabling the user to select and
	/// enroll authentication mechanisms for the new account.
	///
	/// Returns: `account_id` The identifier of the newly added account
	///
	/// Fails with:
	/// - `INVALID_REQUEST` if policy requires authentication factors for the
	/// new account but no `interaction` channel was supplied.
	/// - `ABORTED` if the client closes the `interaction` channel.
	strict ProvisionNewAccount(resource table {
	1: lifetime Lifetime;
	2: metadata AccountMetadata;
	3: interaction server_end:fuchsia.identity.authentication.Interaction;
	}) -> (struct {
	account_id AccountId;
	}) error Error;

	/// Adds a new system account to the device using the supplied password
	/// as the only authentication mechanism. The account is automatically
	/// unlocked and the supplied channel is connected to read properties of
	/// and perform operations on the account.
	///
	/// This is a temporary method used for an initial prototype of
	/// password-based encryption. Its usage will be replaced by the
	/// `ProvisionNewAccount` method where the hardcoded
	/// authentication=password assumption is replaced by a channel
	/// that can support different authentication mechanisms.
	///
	/// `password` The password to be used for the new account
	/// `metadata` Metadata for the new account
	/// `account` The server end of an `Account` channel
	///
	/// Fails with `INVALID_REQUEST` if the password does not meet
	/// minimum strength requirements.
	@deprecated
	strict DeprecatedProvisionNewAccount(resource struct {
	password string:MAX_PASSWORD_SIZE;
	metadata AccountMetadata;
	account server_end:Account;
	}) -> () error Error;
	};

	/// An `AuthState` along with the system account that it applies to.
	type AccountAuthState = struct {
	/// A unique identifier for the account.
	account_id AccountId;
	/// An authentication state for the account.
	auth_state AuthState;
	};

	/// A protocol to receive events when the set of accounts on a device or the
	/// authentication states of these accounts change.
	///
	/// AccountListeners may be registered through the AccountManager protocol
	/// and this registration also defines which types of event should be sent to
	/// the listener. Optionally, the AccountListener will receive an initial state
	/// event onto which the change events may be safely accumulated.
	///
	/// All methods include an empty response to follow the "Throttle push using
	/// acknowledgements" FIDL design pattern.
	closed protocol AccountListener {
	/// A method that is called to communicate the initial set of accounts and
	/// their authentication states. OnInitialize is called exactly once if and
	/// only if AccountListenerOptions.initial_state was set when creating the
	/// AccountListener. When called, it will always be the first call on the
	/// channel. If no accounts are present on the device the vector will be
	/// empty.
	///
	/// `account_states` The set of initial states.
	strict OnInitialize(struct {
	account_states vector<AccountAuthState>:MAX_ACCOUNTS_PER_DEVICE;
	}) -> ();

	/// A method that is called when a new account is added to the device.
	/// This method is only called if AccountListenerOptions.add_account was
	/// set when creating the AccountListener.
	///
	/// `account_state` The initial state for the newly added account.
	strict OnAccountAdded(struct {
	account_state AccountAuthState;
	}) -> ();

	/// A method that is called when a provisioned account is removed.
	/// This method is only called if AccountListenerOptions.remove_account was
	/// set when creating the AccountListener.
	strict OnAccountRemoved(struct {
	account_id AccountId;
	}) -> ();

	/// A method that is called when the authentication state of any provisioned
	/// account changes.
	strict OnAuthStateChanged(struct {
	account_auth_state AccountAuthState;
	}) -> ();
	};