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:

PrepareForAccountTransfer is called on the target device.
The public key for the target device is retrieved using GetPublicKey and handed to the source device.
Account data is encrypted on the source device using the public key with EncryptAccountData.
The encrypted account data is passed in to AccountHandler on the target device with PerformAccountTransfer.
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`

STRUCTS

AccountHandlerControl_CreateAccount_Response

generated

Name	Type	Description	Default

AccountHandlerControl_Preload_Response

generated

Name	Type	Description	Default

AccountHandlerControl_UnlockAccount_Response

generated

Name	Type	Description	Default

AccountHandlerControl_LockAccount_Response

generated

Name	Type	Description	Default

AccountHandlerControl_PrepareForAccountTransfer_Response

generated

Name	Type	Description	Default

AccountHandlerControl_PerformAccountTransfer_Response

generated

Name	Type	Description	Default

AccountHandlerControl_FinalizeAccountTransfer_Response

generated

Name	Type	Description	Default

AccountHandlerControl_EncryptAccountData_Response

generated

Name	Type	Description	Default
`encrypted_account_data`	`EncryptedAccountData`		No default

AccountHandlerControl_RemoveAccount_Response

generated

Name	Type	Description	Default

AccountHandlerControl_GetAccount_Response

generated

Name	Type	Description	Default

AccountHandlerControl_GetPublicKey_Response

generated

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

AccountHandlerControl_GetGlobalIdHash_Response

generated

Name	Type	Description	Default
`id_hash`	`GlobalIdHash`		No default

AccountHandlerContext_GetOauth_Response

generated

Name	Type	Description	Default

AccountHandlerContext_GetOpenIdConnect_Response

generated

Name	Type	Description	Default

AccountHandlerContext_GetOauthOpenIdConnect_Response

generated

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

generated

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

AccountHandlerControl_Preload_Result

generated

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

AccountHandlerControl_UnlockAccount_Result

generated

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

AccountHandlerControl_LockAccount_Result

generated

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

AccountHandlerControl_PrepareForAccountTransfer_Result

generated

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

AccountHandlerControl_PerformAccountTransfer_Result

generated

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

AccountHandlerControl_FinalizeAccountTransfer_Result

generated

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

AccountHandlerControl_EncryptAccountData_Result

generated

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

AccountHandlerControl_RemoveAccount_Result

generated

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

AccountHandlerControl_GetAccount_Result

generated

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

AccountHandlerControl_GetPublicKey_Result

generated

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

AccountHandlerControl_GetGlobalIdHash_Result

generated

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

AccountHandlerContext_GetOauth_Result

generated

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

AccountHandlerContext_GetOpenIdConnect_Result

generated

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

AccountHandlerContext_GetOauthOpenIdConnect_Result

generated

Name	Type	Description
`response`	`AccountHandlerContext_GetOauthOpenIdConnect_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.