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.auth;

 /// 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, installation of the AuthProviders that are used to obtain
 /// authentication tokens for these accounts, and access to TokenManagers for
 /// these accounts.
 ///
 /// The AccountManager is the most powerful protocol in the authentication
 /// system and is intended only for use by the most trusted parts of the system.
 @discoverable
 protocol AccountManager {
     /// Returns a vector of all accounts provisioned on the current device.
     GetAccountIds() -> (struct {
         account_ids vector<AccountId>:MAX_ACCOUNTS_PER_DEVICE;
     });

     /// Returns a vector of all accounts provisioned on the current
     /// device and the current authentication state for each.
     ///
     /// `scenario` The scenario to produce authentication states for.
     ///
     /// Returns: `account_auth_states` The current authentication state for each
     ///                                account given the provided scenario.
     GetAccountAuthStates(struct {
         scenario Scenario;
     }) -> (struct {
         account_auth_states vector<AccountAuthState>:MAX_ACCOUNTS_PER_DEVICE;
     }) error Error;

     /// Returns the metadata for a single account.
     ///
     /// `id` The account's identifier as returned by GetAccountIds()
     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` The account's identifier as returned by GetAccountIds()
     /// `context_provider` An `AuthenticationContextProvider` capable of
     ///                    supplying UI contexts used for interactive
     ///                    authentication on this account
     /// `account` The server end of an `Account` channel
     GetAccount(resource struct {
         id AccountId;
         context_provider client_end:fuchsia.auth.AuthenticationContextProvider;
         account server_end:Account;
     }) -> (struct {}) 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
     DeprecatedGetAccount(resource struct {
         id AccountId;
         password string:MAX_PASSWORD_SIZE;
         account server_end:Account;
     }) -> (struct {}) error Error;

     // TODO(dnordstrom): Add option to retrieve an account non-interactively.

     /// 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` The client end of an `AccountListener` channel
     /// `options` An `AccountListenerOptions` that defines the set of events to
     ///           be sent to the listener.
     RegisterAccountListener(resource struct {
         listener client_end:AccountListener;
         options AccountListenerOptions;
     }) -> (struct {}) error Error;

     // TODO(fxbug.dev/561): Define methods to managed locked accounts, i.e. those
     // where data decryption keys are not currently available.

     /// Removes a provisioned system account from the current device, revoking
     /// any credentials that are held for the account.
     ///
     /// `id` The account's identifier as returned by GetAccountIds()
     /// `force` If true, continues removing the account even if revocation of
     ///         credentials fails. If false, any revocation failure will result
     ///         in an error and the account will remain. In this case, a subset
     ///         of the credentials may have been deleted.
     RemoveAccount(struct {
         id AccountId;
         force bool;
     }) -> (struct {}) error Error;

     /// Adds a new system account to the current device. If a storage
     /// unlock-capable authentication mechanism is provided, a single
     /// enrollment will be created of that mechanism.
     ///
     /// `lifetime` The lifetime of the account
     /// `auth_mechanism_id` An `AuthMechanismId` for a storage
     ///                     unlock-capable authentication mechanism. If
     ///                     provided, a single enrollment of that
     ///                     mechanism will be created for storage
     ///                     unlock.
     ///
     /// Returns: `account_id` The identifier of the newly added account
     ProvisionNewAccount(struct {
         lifetime Lifetime;
         auth_mechanism_id AuthMechanismId:optional;
     }) -> (struct {
         account_id AccountId;
     }) error Error;

     /// Adds a new system account to the current 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
     DeprecatedProvisionNewAccount(resource struct {
         password string:MAX_PASSWORD_SIZE;
         metadata AccountMetadata;
         account server_end:Account;
     }) -> (struct {}) error Error;

     /// Returns all available authentication mechanisms.
     GetAuthenticationMechanisms() -> (struct {
         auth_mechanisms vector<AuthMechanismProperties>:MAX_AUTH_MECHANISMS;
     }) error Error;
 };

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

 /// The initial state of a system account, reported through an `AccountListener`.
 @max_handles("0")
 type InitialAccountState = struct {
     /// A unique identifier for the account on the current device.
     account_id AccountId;
     /// An authentication state for the account. It is only populated if
     /// `AccountListenerOptions.scenario` was specified when the listener was
     /// created.
     auth_state box<AuthState>;
 };

 /// The configuration for an AccountListener, defining the set of events that it
 /// will receive.
 @max_handles("0")
 type AccountListenerOptions = struct {
     /// If true, the listener will receive an event containing the initial state
     /// for all accounts. The initial auth states will be populated in this
     /// event iff the scenario option is set.
     initial_state bool;
     /// If true, the listener will receive events when a new account is added
     /// to the device.
     add_account bool;
     /// If true, the listener will receive events when an account is removed
     /// from the device.
     remove_account bool;
     /// The scenario to use for all AuthState data sent to the listener. If
     /// scenario is not supplied no AuthState data will be populated.
     scenario box<Scenario>;
     /// An `AuthChangeGranularity` expressing the magnitude of change in
     /// authentication state that will lead to AuthStateChange events.
     /// If granularity is not populated AuthStateChange events will not be
     /// sent. May only be populated if a scenario is provided.
     granularity box<AuthChangeGranularity>;
 };

 /// 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.
 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.
     OnInitialize(struct {
         account_states vector<InitialAccountState>: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.
     OnAccountAdded(struct {
         account_state InitialAccountState;
     }) -> ();

     /// 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.
     OnAccountRemoved(struct {
         account_id AccountId;
     }) -> ();

     /// A method that is called when the authentication state of any provisioned
     /// account changes.
     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.auth;

	/// 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, installation of the AuthProviders that are used to obtain
	/// authentication tokens for these accounts, and access to TokenManagers for
	/// these accounts.
	///
	/// The AccountManager is the most powerful protocol in the authentication
	/// system and is intended only for use by the most trusted parts of the system.
	@discoverable
	protocol AccountManager {
	/// Returns a vector of all accounts provisioned on the current device.
	GetAccountIds() -> (struct {
	account_ids vector<AccountId>:MAX_ACCOUNTS_PER_DEVICE;
	});

	/// Returns a vector of all accounts provisioned on the current
	/// device and the current authentication state for each.
	///
	/// `scenario` The scenario to produce authentication states for.
	///
	/// Returns: `account_auth_states` The current authentication state for each
	/// account given the provided scenario.
	GetAccountAuthStates(struct {
	scenario Scenario;
	}) -> (struct {
	account_auth_states vector<AccountAuthState>:MAX_ACCOUNTS_PER_DEVICE;
	}) error Error;

	/// Returns the metadata for a single account.
	///
	/// `id` The account's identifier as returned by GetAccountIds()
	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` The account's identifier as returned by GetAccountIds()
	/// `context_provider` An `AuthenticationContextProvider` capable of
	/// supplying UI contexts used for interactive
	/// authentication on this account
	/// `account` The server end of an `Account` channel
	GetAccount(resource struct {
	id AccountId;
	context_provider client_end:fuchsia.auth.AuthenticationContextProvider;
	account server_end:Account;
	}) -> (struct {}) 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
	DeprecatedGetAccount(resource struct {
	id AccountId;
	password string:MAX_PASSWORD_SIZE;
	account server_end:Account;
	}) -> (struct {}) error Error;

	// TODO(dnordstrom): Add option to retrieve an account non-interactively.

	/// 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` The client end of an `AccountListener` channel
	/// `options` An `AccountListenerOptions` that defines the set of events to
	/// be sent to the listener.
	RegisterAccountListener(resource struct {
	listener client_end:AccountListener;
	options AccountListenerOptions;
	}) -> (struct {}) error Error;

	// TODO(fxbug.dev/561): Define methods to managed locked accounts, i.e. those
	// where data decryption keys are not currently available.

	/// Removes a provisioned system account from the current device, revoking
	/// any credentials that are held for the account.
	///
	/// `id` The account's identifier as returned by GetAccountIds()
	/// `force` If true, continues removing the account even if revocation of
	/// credentials fails. If false, any revocation failure will result
	/// in an error and the account will remain. In this case, a subset
	/// of the credentials may have been deleted.
	RemoveAccount(struct {
	id AccountId;
	force bool;
	}) -> (struct {}) error Error;

	/// Adds a new system account to the current device. If a storage
	/// unlock-capable authentication mechanism is provided, a single
	/// enrollment will be created of that mechanism.
	///
	/// `lifetime` The lifetime of the account
	/// `auth_mechanism_id` An `AuthMechanismId` for a storage
	/// unlock-capable authentication mechanism. If
	/// provided, a single enrollment of that
	/// mechanism will be created for storage
	/// unlock.
	///
	/// Returns: `account_id` The identifier of the newly added account
	ProvisionNewAccount(struct {
	lifetime Lifetime;
	auth_mechanism_id AuthMechanismId:optional;
	}) -> (struct {
	account_id AccountId;
	}) error Error;

	/// Adds a new system account to the current 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
	DeprecatedProvisionNewAccount(resource struct {
	password string:MAX_PASSWORD_SIZE;
	metadata AccountMetadata;
	account server_end:Account;
	}) -> (struct {}) error Error;

	/// Returns all available authentication mechanisms.
	GetAuthenticationMechanisms() -> (struct {
	auth_mechanisms vector<AuthMechanismProperties>:MAX_AUTH_MECHANISMS;
	}) error Error;
	};

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

	/// The initial state of a system account, reported through an `AccountListener`.
	@max_handles("0")
	type InitialAccountState = struct {
	/// A unique identifier for the account on the current device.
	account_id AccountId;
	/// An authentication state for the account. It is only populated if
	/// `AccountListenerOptions.scenario` was specified when the listener was
	/// created.
	auth_state box<AuthState>;
	};

	/// The configuration for an AccountListener, defining the set of events that it
	/// will receive.
	@max_handles("0")
	type AccountListenerOptions = struct {
	/// If true, the listener will receive an event containing the initial state
	/// for all accounts. The initial auth states will be populated in this
	/// event iff the scenario option is set.
	initial_state bool;
	/// If true, the listener will receive events when a new account is added
	/// to the device.
	add_account bool;
	/// If true, the listener will receive events when an account is removed
	/// from the device.
	remove_account bool;
	/// The scenario to use for all AuthState data sent to the listener. If
	/// scenario is not supplied no AuthState data will be populated.
	scenario box<Scenario>;
	/// An `AuthChangeGranularity` expressing the magnitude of change in
	/// authentication state that will lead to AuthStateChange events.
	/// If granularity is not populated AuthStateChange events will not be
	/// sent. May only be populated if a scenario is provided.
	granularity box<AuthChangeGranularity>;
	};

	/// 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.
	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.
	OnInitialize(struct {
	account_states vector<InitialAccountState>: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.
	OnAccountAdded(struct {
	account_state InitialAccountState;
	}) -> ();

	/// 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.
	OnAccountRemoved(struct {
	account_id AccountId;
	}) -> ();

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