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 |
V |
+------------------+ |
| PendingTransfer | |
+------------------+ |
| |
| PerformTransfer | CreateAccount/
V | LoadAccount
+------------------+ |
| Transferred | |
+------------------+ |
| |
| 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.Initialized
- the handler has loaded account information and is ready to serve requests for theAccount
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.
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
|
LoadAccount
Loads information about a Fuchsia account that was previously provisioned on the current device.
Fails with FAILED_PRECONDITION if the AccountHandler is not in the Uninitialized
state.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
result |
AccountHandlerControl_LoadAccount_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).
GetAuthProvider
Connects to the AuthProvider
implementation for a particular service
provider, launching it if necessary. This method will soon be removed
along with the AuthProvider
protocol.
auth_provider_type
An OAuth identity provider matching a configuration
set in an AuthProviderConfig.auth_provider_type
auth_provider
The server end of an AuthProvider
channel
Request
Name | Type |
---|---|
auth_provider_type |
string
|
auth_provider |
request<fuchsia.auth/AuthProvider>
|
Response
Name | Type |
---|---|
result |
AccountHandlerContext_GetAuthProvider_Result
|
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_LoadAccount_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_GetAuthProvider_Response
generated
Name | Type | Description | 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_LoadAccount_Result
generated
Name | Type | Description |
---|---|---|
response |
AccountHandlerControl_LoadAccount_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_GetAuthProvider_Result
generated
Name | Type | Description |
---|---|---|
response |
AccountHandlerContext_GetAuthProvider_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. |