blob: 72dfb771d4c56aa0ac80a17f451c3130f95a6d7b [file] [log] [blame]
// 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. 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
protocol AccountManager {
/// Returns a vector of all accounts provisioned on the device.
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()
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()
/// `context_provider` [required] An `AuthenticationContextProvider` capable
/// of supplying UI contexts used for interactive
/// authentication on this account
/// `account` [required] The server end of an `Account` channel
GetAccount(resource table {
1: id AccountId;
2: context_provider client_end:fuchsia.auth.AuthenticationContextProvider;
3: reserved; // 3 is reserved for auto_lock in a near-future CL
4: 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;
/// 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.
RegisterAccountListener(resource table {
1: listener client_end:AccountListener;
2: initial_state bool;
3: add_account bool;
4: remove_account bool;
5: granularity AuthChangeGranularity;
}) -> (struct {}) error Error;
/// Removes an account from the device.
///
/// `id` The account's identifier as returned by GetAccountIds()
RemoveAccount(struct {
id AccountId;
}) -> (struct {}) error Error;
/// Adds a new account to the device. If a storage unlock-capable
/// authentication mechanism is provided, a single enrollment will be
/// created of that mechanism.
///
/// `lifetime` [required] The lifetime of the account
/// `metadata` [required] Metadata for the new 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(table {
1: lifetime Lifetime;
2: metadata AccountMetadata;
3: auth_mechanism_id AuthMechanismId;
}) -> (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
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.
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.
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<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.
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.
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;
}) -> ();
};