// Copyright 2019 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;

/// 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.
// TODO(fxbug.dev/42836): Supply UI for system authentication.
[Discoverable]
protocol StorageUnlockMechanism {
    /// 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.
    Authenticate(vector<Enrollment>:MAX_ENROLLMENTS enrollments)
        -> (AttemptedEvent attempt) error Error;

    /// 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.
    Enroll() -> (EnrollmentData enrollment_data, PrekeyMaterial prekey_material) error Error;

    // TODO(dnordstrom): Add method for initilizing authentication event,
    // in order to support user initiated authentication mode.
};

// TODO(dnordstrom): Add a layer of indirection such that multiple
// authentication mechansims can be served by a single discoverable interface.