fuchsia.identity.internal

PROTOCOLS

AccountHandlerControl

Defined in fuchsia.identity.internal/account_handler.fidl

The control channel for an AccountHandler component.

This interface is intended only for use by the AccountManager component that starts instances of AccountHandler. We define which account the handler should be handling one time via this channel rather than via startup flags to provide additional flexibility given the range of scenarios:

• The account is completely new
• The account is being added to the current device for the first time
• Account information is already present on the local disk and is readable
• Account information is already present on the local disk but is not yet readable because the disk is not yet decrypted.

A given Account Handler progresses through the following state machine:

                                       |
                                       V
                               +---------------+
                +--------------| Uninitialized |------------+
                |              +---------------+            |
                |                      |                    |
                | PrepareForTransfer   |                    | Preload
                V                      |                    V
      +------------------+             |           +------------------+
      | PendingTransfer  |             |           |      Locked      |
      +------------------+             |           +------------------+
                |                      |                    ^
                | PerformTransfer      |                    |
                V                      |                    |
      +------------------+             |                    | LockAccount /
      |   Transferred    |             | CreateAccount      | UnlockAccount
      +------------------+             |                    |
                |                      |                    |
                | FinalizeTransfer     |                    |
                |                      V                    |
                |              +---------------+            |
                +------------->|  Initialized  |<-----------+
                               +---------------+
                                       |
                                       | Terminate
                                       V
                               +---------------+
                               |   Finished    |
                               +---------------+

• Uninitialized - the handler has just been instantiated and contains no account information.
• PendingTranfer - the handler is awaiting an account transfer. It has created a public key pair that will be associated with the account on this device, but contains no other account information.
• Transferred - the handler has received transferred account information and is holding it in memory. In this state, the account transfer is not yet known to be valid, and is pending further validation from account manager. The account is not available for use, and regardless of the intended lifetime of the account on this device, the account is not saved to disk.
• Locked - the handler has loaded pre-authentication data, which lets it unlock the account subsequently.
• Initialized - the handler has loaded account information and is ready to serve requests for the Account interface. If the account is persistent on this device, then it is saved to disk.
• Finished - the handler is in the process of shutting down and will soon terminate.

CreateAccount

Creates a completely new Fuchsia account, optionally protecting the account with a single enrollment of an authentication mechanism.

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.

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Uninitialized state.

Request

Name	Type
auth_mechanism_id	fuchsia.identity.account/AuthMechanismId

Response

Name	Type
result	AccountHandlerControl_CreateAccount_Result

Preload

Loads pre-auth data, which allows the account to be unlocked later.

This moves the AccountHandler from the Uninitialized state to the Locked state.

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Uninitialized state.

Request

Name	Type

Response

Name	Type
result	AccountHandlerControl_Preload_Result

UnlockAccount

Reach the Initialized state, attempting authentication and unlocking the account where necessary.

Fails with

• FAILED_PRECONDITION if the AccountHandler is not in the Locked or Initialized state.
• FAILED_AUTH_ATTEMPT if the authentication attempt failed.

Request

Name	Type

Response

Name	Type
result	AccountHandlerControl_UnlockAccount_Result

LockAccount

Reach the Locked state, closing any open Account and Persona channels for the account.

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Initialized or Locked state.

Request

Name	Type

Response

Name	Type
result	AccountHandlerControl_LockAccount_Result

PrepareForAccountTransfer

Prepares the AccountHandler to receive an account from another device through direct transfer. This moves the AccountHandler from the Uninitialized state to the PendingTransfer state.

PrepareForAccountTransfer should be used in conjunction with PerformAccountTransfer, FinalizeAccountTransfer, and EncryptAccountData to provision an existing account on another device (source) to this device (target).

The expected sequence of calls to setup an AccountHandler with a transferred account is as follows:

1. PrepareForAccountTransfer is called on the target device.
2. The public key for the target device is retrieved using GetPublicKey and handed to the source device.
3. Account data is encrypted on the source device using the public key with EncryptAccountData.
4. The encrypted account data is passed in to AccountHandler on the target device with PerformAccountTransfer.
5. After any validation, the transfer is finalized on the target device with a call to FinalizeAccountTransfer.

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Uninitialized state.

Request

Name	Type

Response

Name	Type
result	AccountHandlerControl_PrepareForAccountTransfer_Result

PerformAccountTransfer

Loads the encrypted account into memory, but does not make it available for use yet. The account data passed in is expected to be serialized as an AccountTransferContainer and encrypted using the public key retrieved from GetPublicKey. This format of account data is provided by EncryptAccountData on the source device.

Moves the AccountHandler from the PendingTransfer state to the Transferred state.

encrypted_account_data Account data retrieved on the source device using EncryptAccountData.

Fails with FAILED_PRECONDITION if the AccountHandler is not in the PendingTransfer state.

Request

Name	Type
encrypted_account_data	EncryptedAccountData

Response

Name	Type
result	AccountHandlerControl_PerformAccountTransfer_Result

FinalizeAccountTransfer

Completes the account transfer started through PrepareForAccountTransfer and PerformAccountTransfer. This saves the account to disk if the account is persistent and makes it available for use.

Moves the AccountHandler from the Transferred state to the Initialized state.

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Transferred state.

Request

Name	Type

Response

Name	Type
result	AccountHandlerControl_FinalizeAccountTransfer_Result

EncryptAccountData

Serializes and encrypts the account contained in the AccountHandler for transfer. The account will be serialized as AccountData and encrypted using target_public_key. The resulting EncryptedAccountData should be passed to AccountHandler on the target device using PerformAccountTransfer.

target_public_key The public key used to encrypt the account data.

Returns: encrypted_account_data Bytes containing the encrypted account

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Initialized state.

Request

Name	Type
target_public_key	fuchsia.kms/PublicKey

Response

Name	Type
result	AccountHandlerControl_EncryptAccountData_Result

RemoveAccount

Deletes all persistent information about the Fuchsia account handled by this handler, including all credentials and global identifiers. Credential revocation is attempted before deletion. After a successful call to RemoveAccount, all other open interfaces for this account handler will be closed and any subsequent calls on the current interface will fail.

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.

Request

Name	Type
force	bool

Response

Name	Type
result	AccountHandlerControl_RemoveAccount_Result

GetAccount

Connects an interface to read properties of and perform operations on the account handled by this handler. The AccountHandler must be in the Initialized state.

context_provider An AuthenticationContextProvider capable of supplying UI contexts used for interactive authentication on this account account The server end of an Account channel

Fails with FAILED_PRECONDITION if the AccountHandler is not in the Initialized state.

Request

Name	Type
auth_context_provider	fuchsia.auth/AuthenticationContextProvider
account	request<fuchsia.identity.account/Account>

Response

Name	Type
result	AccountHandlerControl_GetAccount_Result

GetPublicKey

Retrieves the public key associated with this account on this device. The public key is exposed so that the target AccountHandler's key can be distributed to the source AccountHandler during an account transfer. This allows the source AccountHandler to encrypt account data such that only the target AccountHandler can decrypt the data.

Returns: public_key Public key in an asymmetric key pair associated with this account on this device.

Fails with FAILED_PRECONDITION is the AccountHandler is not in one of PendingTransfer, Transferred, or Initialized states.

Request

Name	Type

Response

Name	Type
result	AccountHandlerControl_GetPublicKey_Result

GetGlobalIdHash

Generates a hash of the global account ID using the provided salt. Returning a hash of the global ID lets the account system determine whether two locally provisioned accounts represent the same account without storing every account's global ID. A salt is added so that accounts cannot be easily correlated across devices.

The AccountHandler must be in either the Transferred or Initialized states.

salt Bytes used as a salt while hashing global ID.

Returns: id_hash A hash of the global ID of the contained account

Fails with FAILED_PRECONDITION if the AccountHandler is not in one of Transferred or Initialized states.

Request

Name	Type
salt	HashSalt

Response

Name	Type
result	AccountHandlerControl_GetGlobalIdHash_Result

Terminate

Signals that the AccountHandler should tear itself down. After the receiver responds by closing its handle, the caller may terminate the component if it hasn't already exited.

Request

Name	Type

AccountHandlerContext

Defined in fuchsia.identity.internal/account_handler.fidl

An interface that supplies the account and authentication services that an AccountHandler needs to perform its role in the system.

This service is supplied into the namespace of AccountHandler by the component that launches it (i.e. the AccountManager).

GetOauth

Connects to the Oauth implementation for a particular service provider, launching it if necessary.

auth_provider_type An OAuth identity provider matching a configuration set in an AuthProviderConfig.auth_provider_type oauth The server end of an Oauth channel

Request

Name	Type
auth_provider_type	string
oauth	request<fuchsia.identity.external/Oauth>

Response

Name	Type
result	AccountHandlerContext_GetOauth_Result

GetOpenIdConnect

Connects to the OpenIdConnect implementation for a particular service provider, launching it if necessary.

auth_provider_type An OpenID Connect identity provider matching a configuration set in an AuthProviderConfig.auth_provider_type open_id_connect The server end of an OpenIDConnect channel

Request

Name	Type
auth_provider_type	string
open_id_connect	request<fuchsia.identity.external/OpenIdConnect>

Response

Name	Type
result	AccountHandlerContext_GetOpenIdConnect_Result

GetOauthOpenIdConnect

Connects to the OauthOpenIdConnect implementation for a particular service provider, launching it if necessary.

auth_provider_type An OpenID Connect identity provider matching a configuration set in an AuthProviderConfig.auth_provider_type oauth_open_id_connect The server end of an OauthOpenIDConnect channel

Request

Name	Type
auth_provider_type	string
oauth_open_id_connect	request<fuchsia.identity.external/OauthOpenIdConnect>

Response

Name	Type
result	AccountHandlerContext_GetOauthOpenIdConnect_Result

GetStorageUnlockAuthMechanism

Connects to a StorageUnlockMechanism implementation identified by its auth mechanism ID, launching the associated Authenticator if necessary.

auth_mechanism_id An identifier matching an authentication mechanism configured by the account system. storage_unlock_mechanism The server end of an StorageUnlockMechanism channel

Request

Name	Type
auth_mechanism_id	fuchsia.identity.account/AuthMechanismId
storage_unlock_mechanism	request<fuchsia.identity.authentication/StorageUnlockMechanism>

Response

Name	Type
result	AccountHandlerContext_GetStorageUnlockAuthMechanism_Result

STRUCTS

AccountHandlerControl_CreateAccount_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_Preload_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_UnlockAccount_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_LockAccount_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_PrepareForAccountTransfer_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_PerformAccountTransfer_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_FinalizeAccountTransfer_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_EncryptAccountData_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default
encrypted_account_data	EncryptedAccountData		No default

AccountHandlerControl_RemoveAccount_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_GetAccount_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerControl_GetPublicKey_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default
public_key	fuchsia.kms/PublicKey		No default

AccountHandlerControl_GetGlobalIdHash_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default
id_hash	GlobalIdHash		No default

AccountHandlerContext_GetOauth_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerContext_GetOpenIdConnect_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerContext_GetOauthOpenIdConnect_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

AccountHandlerContext_GetStorageUnlockAuthMechanism_Response

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description	Default

TABLES

AccountData

Defined in fuchsia.identity.internal/account_handler.fidl

Contents of an account, used for serialization during account transfer.

Ordinal	Name	Type	Description
1	global_id	fuchsia.identity.account/GlobalAccountId	A globally unique identifier for the account.

UNIONS

AccountHandlerControl_CreateAccount_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_CreateAccount_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_Preload_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_Preload_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_UnlockAccount_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_UnlockAccount_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_LockAccount_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_LockAccount_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_PrepareForAccountTransfer_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_PrepareForAccountTransfer_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_PerformAccountTransfer_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_PerformAccountTransfer_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_FinalizeAccountTransfer_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_FinalizeAccountTransfer_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_EncryptAccountData_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_EncryptAccountData_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_RemoveAccount_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_RemoveAccount_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_GetAccount_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_GetAccount_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_GetPublicKey_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_GetPublicKey_Response
err	fuchsia.identity.account/Error

AccountHandlerControl_GetGlobalIdHash_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerControl_GetGlobalIdHash_Response
err	fuchsia.identity.account/Error

AccountHandlerContext_GetOauth_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerContext_GetOauth_Response
err	fuchsia.identity.account/Error

AccountHandlerContext_GetOpenIdConnect_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerContext_GetOpenIdConnect_Response
err	fuchsia.identity.account/Error

AccountHandlerContext_GetOauthOpenIdConnect_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerContext_GetOauthOpenIdConnect_Response
err	fuchsia.identity.account/Error

AccountHandlerContext_GetStorageUnlockAuthMechanism_Result

Defined in fuchsia.identity.internal/account_handler.fidl

Name	Type	Description
response	AccountHandlerContext_GetStorageUnlockAuthMechanism_Response
err	fuchsia.identity.account/Error

CONSTANTS

Name	Value	Type	Description
HASH_SIZE	32	uint32
HASH_SALT_SIZE	32	uint32

TYPE ALIASES

Name	Value	Description
GlobalIdHash	array[HASH_SIZE]
HashSalt	array[HASH_SALT_SIZE]
EncryptedAccountData	vector	Encrypted form of AccountData.