| // Copyright 2022 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.authentication; |
| |
| /// The modes in which an authentication UI protocol may operate. |
| type Mode = strict enum { |
| /// Authenticate a user against existing authentication mechanism |
| /// enrollment(s). For example, prove the user knows a password. |
| AUTHENTICATE = 1; |
| /// Create a new enrollment for an authentication mechanism. For example, |
| /// set a password. |
| ENROLL = 2; |
| }; |
| |
| /// A protocol for interactive enrollment of authentication mechanisms and |
| /// authentication using these mechanisms. The client of this protocol is |
| /// typically a user interface component and the server is the account system. |
| /// The server will close the channel when enrollment or authentication is |
| /// complete or when no further progress is possible. |
| /// |
| /// Authentication and enrollment is performed using a set of more detailed |
| /// protocols specific to a particular authentication mechanism. The client of |
| /// these protocols is typically a user interface component and the server is |
| /// an authenticator component implementing that authentication mechanism. All |
| /// these protocols follow the same pattern where the authenticator follows the |
| /// following state machine: |
| /// |
| /// +---------+ [wait conditions met] +-----------+ |
| /// O-->| WAITING |-------------------------->| VERIFYING | |
| /// +---------+ +-----------+ |
| /// ^ | |
| /// | +-------+ | |
| /// +-------------| ERROR |<---------------+ |
| /// [error reported] +-------+ [verification failed] |
| /// |
| /// On initialization, the authenticator is "WAITING" for some combination of |
| /// inputs from the UI (for example a password) and out of band events (for |
| /// example a touch on the fingerprint sensor). Once these conditions have all |
| /// been met the authenticator enters the "VERIFYING" state where it checks the |
| /// validity of the inputs. If verification succeeds the authenticator closes |
| /// the channel. If verification fails the authenticator enters the "ERROR" |
| /// state until the UI collects the description of the error, whereafter it |
| /// returns to the "WAITING" state. If the client closes the channel the |
| /// authentication or enrollment attempt is abandoned. |
| closed protocol Interaction { |
| /// Begins interactive authentication or enrollment for a password. This |
| /// method should only be called when a `WatchState` response indicated that |
| /// password is available for the requested mode. |
| /// |
| /// The server will close the supplied `PasswordInteraction` channel if the |
| /// requested mode or mechanism was invalid or when the authentication or |
| /// enrollment is complete. Either event will cause a response to |
| /// `WatchState`. |
| strict StartPassword(resource struct { |
| ui server_end:PasswordInteraction; |
| mode Mode; |
| }); |
| |
| /// Begins test authentication or enrollment. This method should only be |
| /// called when a `WatchState` response indicated that test is available |
| /// for the requested mode. |
| /// |
| /// The server will close the supplied `TestInteraction` channel if the |
| /// requested mode or mechanism was invalid or when the authentication or |
| /// enrollment is complete. Either event will cause a response to |
| /// `WatchState`. |
| strict StartTest(resource struct { |
| ui server_end:TestInteraction; |
| mode Mode; |
| }); |
| |
| /// Returns the authentication mechanisms that are available to either |
| /// authenticate or enroll. This method follows the "hanging get" interface |
| /// pattern, returning immediately on the first call and hanging until a |
| /// change in state on subsequent calls. Note that when a `Start*` method |
| /// fails, `WatchState` will return, and may return the same set of |
| /// mechanisms as the previous call. |
| strict WatchState() -> (strict union { |
| /// One or more mechanisms are available for authentication. Not all |
| /// products allow multiple concurrent mechanisms, but when multiple |
| /// mechanisms are allowed these are ordered from most preferred to |
| /// least preferred as determined by the product. |
| 1: authenticate vector<Mechanism>:32; |
| /// One or more mechanisms are available for enrollment. Not all |
| /// products allow multiple concurrent mechanisms, but when multiple |
| /// mechanisms are allowed these are ordered from most preferred to |
| /// least preferred as determined by the product. |
| 2: enrollment vector<Mechanism>:32; |
| }); |
| }; |