| // 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; |
| |
| using zx; |
| |
| // This file defines protocols for the interaction between a user interface |
| // and an authenticator for each type of authentication mechanism. See |
| // `interaction.ui` for details of the common pattern these protocols follow. |
| |
| |
| /// The complete set of authentication mechanisms that may be used for Fuchsia |
| /// system authentication. Most products will only support a subset of these |
| /// mechanisms. |
| // Note: this list must be kept in sync with the contents of the |
| // `InteractionProtocolServerEnd` union and with the `Start*` methods in |
| // `Interaction`. |
| type Mechanism = flexible enum { |
| PASSWORD = 1; |
| TEST = 2; |
| }; |
| |
| /// A union of server_end types for each authentication interaction protocol. |
| type InteractionProtocolServerEnd = flexible resource union { |
| 1: password server_end:PasswordInteraction; |
| 2: test server_end:TestInteraction; |
| }; |
| |
| |
| /// A protocol for a password user interface (the client) to interact with a |
| /// password authenticator (the server), both during enrollment and during |
| /// authentication. The server will close the channel when enrollment or |
| /// authentication is complete. |
| closed protocol PasswordInteraction { |
| /// Sets the password. Calling this method is guaranteed to lead to a |
| /// change in state and therefore a response to `WatchState`. During |
| /// password enrollment some server implementations may verify the supplied |
| /// password against rules defined by the product or policy and move to |
| /// an error state if the password does not meet these rules. |
| strict SetPassword(struct { |
| password string:PASSWORD_BYTES_MAX_SIZE; |
| }); |
| |
| /// Wait for a change in the state of the server. This method follows the |
| /// "hanging get" interface pattern, returning immediately on the first call |
| /// and hanging until a change in state on subsequent calls. |
| strict WatchState() -> (strict union { |
| /// The server is waiting for the supplied set of conditions. |
| 1: waiting vector<PasswordCondition>:8; |
| /// The server is verifying the password. Reporting a verification state |
| /// is optional, some implementations may step directly from waiting to |
| /// error or to success. |
| 2: verifying PasswordVerificationStatus; |
| /// Verification failed with the supplied error. |
| 3: error PasswordError; |
| }); |
| }; |
| |
| /// The maximum size of a password in bytes. |
| const PASSWORD_BYTES_MAX_SIZE uint32 = 128; |
| |
| /// The set of conditions that the authenticator may need to wait for during |
| /// enrollment or authentication using password. |
| type PasswordCondition = flexible union { |
| /// (authentication) Too many incorrect password attempts have been made, |
| /// the client must wait until the specified time before another attempt |
| /// will be accepted. |
| 1: wait_until zx.Time; |
| /// (enrollment and authentication) The client should call `SetPassword`. |
| 2: set_password Empty; |
| }; |
| |
| /// The set of verification statuses that may be returned during enrollment or |
| /// authentication using password |
| type PasswordVerificationStatus = flexible union { |
| /// (enrollment and authentication) An optional estimate of the verification |
| /// progress. |
| 1: percent_complete uint8; |
| }; |
| |
| /// The set of errors that may be encountered during enrollment or |
| /// authentication using password. |
| type PasswordError = flexible union { |
| /// (enrollment) The supplied password did not meet the implementation's |
| /// required minimum length. The mimumum length is returned in the response. |
| 1: too_short uint8; |
| /// (enrollment) The supplied password was a known weak password according |
| /// to whichever heuristic the implementation is using. |
| 2: too_weak Empty; |
| /// (authentication) The supplied password did not match the password |
| /// supplied during enrollment. |
| 3: incorrect Empty; |
| /// (authentication) Too many incorrect password attempts have been made, |
| /// the caller must wait for the `wait_until` condition before any other |
| /// response will be returned. |
| 4: must_wait Empty; |
| /// (authentication and enrollment) `SetPassword` was called while state was |
| /// not "waiting" with a condition of "set_password". |
| 5: not_waiting_for_password Empty; |
| }; |
| |
| |
| /// A protocol for a user interface (the client) to interact with a fake |
| /// authenticator (the server) for testing, both during enrollment and during |
| /// authentication. The server will close the channel when enrollment or |
| /// authentication is complete. |
| /// |
| /// Enrollment always completes immediately and successfully without any action |
| /// from the client. Authentication completes successfully when the client calls |
| /// SetSuccess. |
| closed protocol TestInteraction { |
| /// (authentication) Causes this test authenticator to immediately succeed. |
| strict SetSuccess(); |
| |
| /// Wait for a change in the state of the server. This method follows the |
| /// "hanging get" interface pattern, returning immediately on the first call |
| /// and hanging until a change in state on subsequent calls. |
| strict WatchState() -> (strict union { |
| /// The server is waiting for the supplied set of conditions. |
| 1: waiting vector<TestAuthenticatorCondition>:8; |
| }); |
| }; |
| |
| /// The set of conditions that a test authenticator may need to wait for during |
| /// enrollment or authentication. |
| type TestAuthenticatorCondition = flexible union { |
| /// (authentication) The client may call `SetSucceess`. |
| 1: set_success Empty; |
| }; |