fuchsia.identity.authentication

Defines the protocols used to enroll and interact with user authentication mechanisms.

New authentication mechanisms may be added to the system by implementing the server side of one or more of these protocols, the core identity system will act as the client.

PROTOCOLS

StorageUnlockMechanism

Defined in fuchsia.identity.authentication/mechanisms.fidl

A stateless interface serving an authentication mechanism capable of supplying pre-key material for use with storage unlock. Clients are responsible for managing and persisting enrollments. Enrollment data created during registration must be provided back during authentication.

NOTE: This protocol may not be discoverable in the future.

Authenticate

Interactively requests the user to authenticate against any of the provided enrollments.

enrollments A list of enrollments that will be accepted.

Returns: attempt An AttemptedEvent where the enrollment_id refers to one of the provided enrollments, and the optional updated_enrollment_data indicates that the enrollment with said id must also be updated if the attempt is successful.

Request

NameType
enrollments vector<Enrollment>[16]

Response

NameType
result StorageUnlockMechanism_Authenticate_Result

Enroll

Interactively run the enrollment flow for a single enrollment.

Returns: enrollment_data Data associated with this enrollment, to be provided during authentication in the future. prekey_material The the pre-key material that will be produced by successfully authenticating against this enrollment.

Request

NameType

Response

NameType
result StorageUnlockMechanism_Enroll_Result

STRUCTS

Enrollment

Defined in fuchsia.identity.authentication/common.fidl

Enrollments allow some authentication mechanisms to produce authentication events. An enrollment must first be created in order to be authenticated against. Both creation and authentication may involve user interaction. An enrollment is typically tied to a user controlled authentication factor, such as a fingerprint, a password or a security key.

NameTypeDescriptionDefault
id EnrollmentId

A unique identifier associated with the enrollment.

No default
data EnrollmentData

Data associated with the enrollment.

No default

PositiveEvent

Defined in fuchsia.identity.authentication/common.fidl

An authentication event is a statement which an authentication mechanism makes about the presence and/or engagement of an account owner, and thus affecting the entity's authentication state. The effect of an event depends on the properties of the authentication mechanism which created it. A positive authentication event may contribute to an increase in authentication state.

NameTypeDescriptionDefault
timestamp zx/time

The time on ZX_CLOCK_UTC when the event completed.

No default

NegativeEvent

Defined in fuchsia.identity.authentication/common.fidl

A negative authentication event may contribute to a decrease in authentication state.

NameTypeDescriptionDefault
timestamp zx/time

The time on ZX_CLOCK_UTC when the event completed.

No default

AttemptedEvent

Defined in fuchsia.identity.authentication/common.fidl

A attempted authentication event may contribute to an increase in authentication state if and only if the pre-key material is correct. Otherwise, it does not affect the authentication state.

NameTypeDescriptionDefault
timestamp zx/time

The time on ZX_CLOCK_UTC when the event completed.

No default
enrollment_id EnrollmentId

The id of the enrollment used to produce this attempt.

No default
updated_enrollment_data EnrollmentData

Enrollment data which should should replace the old enrollment data upon successful authentication. This field is only populated if a change in enrollment data is required.

No default
prekey_material PrekeyMaterial

Pre-key material produced during the authentication attempt.

No default

StorageUnlockMechanism_Authenticate_Response

Defined in fuchsia.identity.authentication/mechanisms.fidl

NameTypeDescriptionDefault
attempt AttemptedEvent No default

StorageUnlockMechanism_Enroll_Response

Defined in fuchsia.identity.authentication/mechanisms.fidl

NameTypeDescriptionDefault
enrollment_data EnrollmentData No default
prekey_material PrekeyMaterial No default

ENUMS

Error

Type: uint32

Defined in fuchsia.identity.authentication/common.fidl

Specifies the reason that a fuchsia.identity.authentication method failed.

NameValueDescription
UNKNOWN 1

Some other problem occurred that cannot be classified using one of the more specific statuses. Retry is optional.

INTERNAL 2

An internal error occurred. This usually indicates a bug within the component implementing the authentication mechanism. Retry is optional.

UNSUPPORTED_OPERATION 3

The requested operation is not supported. This generally indicates that implementation of a new feature is not yet complete. The request should not be retried.

INVALID_AUTH_CONTEXT 4

An invalid or non-functional AuthenticationContextProvider was provided. Retrying is unlikely to correct this error.

INVALID_REQUEST 5

The request was malformed in some way, such as supplying duplicate enrollment entries. The request should not be retried.

INVALID_DATA_FORMAT 6

Data supplied with the request was malformed in some way, such as supplying corrupted enrollment data. The request should not be retried.

RESOURCE 7

A local resource error occurred such as I/O, FIDL, or memory allocation failure. Retry, after a delay, is recommended.

ABORTED 8

An interactive authentication operation was cancelled by the user.

UNIONS

StorageUnlockMechanism_Authenticate_Result

Defined in fuchsia.identity.authentication/mechanisms.fidl

NameTypeDescription
response StorageUnlockMechanism_Authenticate_Response
err Error

StorageUnlockMechanism_Enroll_Result

Defined in fuchsia.identity.authentication/mechanisms.fidl

NameTypeDescription
response StorageUnlockMechanism_Enroll_Response
err Error

CONSTANTS

NameValueTypeDescription
PREKEY_MATERIAL_MAX_SIZE 32 uint32

The maxium size of the prekey material in bytes.

ENROLLMENT_DATA_MAX_SIZE 256 uint32

The maxium size of enrollment data in bytes.

MAX_ENROLLMENTS 16 uint32

The maximum number of active enrollments per authentication mechanism and account.

TYPE ALIASES

NameValueDescription
EnrollmentId uint64

A unique identifier for an Enrollment within an account and an authentication mechanism.

EnrollmentData vector[ENROLLMENT_DATA_MAX_SIZE]

Arbitrary opaque data associated with an authentication enrollment, created and subsequently read by the authentication mechanism that produced the enrollment. It is meaningful only to the authenticator, and opaque to its clients.

PrekeyMaterial vector[PREKEY_MATERIAL_MAX_SIZE]

Pseudo-random data associated with an enrollment of an authentication mechanism capable of storage unlock. It is reproduced only upon successful authentication against that enrollment.