// Copyright 2021 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.credential;

/// Parameters to AddCredential method.
/// TODO(fxbug.dev/88343): Replace with anonymous tables when available as
/// parameter arguments.
type AddCredentialParams = table {
    /// The low entropy credential.
    1: le_secret LeSecret;
    /// The rate at which `CheckCredential()` attempts are allowed as a function
    /// of the number of successive failed attempts.
    2: delay_schedule vector<DelayScheduleEntry>:32;
    /// The high entropy secret locked in the CR50 by the `le_secret`.
    3: he_secret HeSecret;
    /// The reset secret for resetting credentials.  Optional.
    4: reset_secret HeSecret;
};

/// Parameters to CheckCredential method.
/// TODO(fxbug.dev/88343): Replace with anonymous tables when available as
/// parameter arguments.
type CheckCredentialParams = table {
    /// The label of the credential you want to authenticate.
    1: label Label;
    /// The associated user inputed low entropy secret to unlock the credential.
    2: le_secret LeSecret;
};

/// Response to CheckCredential method.
/// TODO(fxbug.dev/88343): Replace with anonymous tables when available as
/// parameter arguments.
type CheckCredentialResponse = table {
    /// The high entropy secret associated with the label.
    1: he_secret HeSecret;
};

/// Manager manages the overall state of low entropy secrets,
/// such as knowleged-based authentication factors, on a Fuchsia device.
/// This includes inserting, deleting and validating credentials. With
/// anti-hammering support built in to prevent pin brute forcing.
///
/// The Manager is the core of the credential management system and
/// is intended only for use by highly trusted components such as the
/// Password Authenticator.
@discoverable
protocol Manager {
    /// Adds a low entropy credential into the system.
    /// `params` see `AddCredentialParams`.
    /// Success returns a label for the newly provisioned credential. This
    /// acts as a identifier which is used to check the credential or remove it
    /// later on. This should be stored by the caller.
    AddCredential(struct {
        params AddCredentialParams;
    }) -> (struct {
        label Label;
    }) error CredentialError;

    /// Removes a credential with the provided label.
    ///
    /// On Failure:
    /// INVALID_LABEL if a label is provided which is not in the tree.
    RemoveCredential(struct {
        label Label;
    }) -> (struct {}) error CredentialError;

    /// Attempts to authenticate a credential. It checks whether the `le_secret`
    /// for a given `label` is correct.
    ///
    /// On Success:
    /// See `CheckCredentialResponse`.
    /// On Failure:
    /// INVALID_LABEL if an invalid label was entered.
    /// TOO_MANY_ATTEMPTS if too many incorrect attempts are made defined by the
    ///                   `delay_schedule` set on AddCredential.
    /// INVALID_SECRET for an incorrect authentication attempt.
    /// CORRUPT_METADATA for invalid credential metadata.
    CheckCredential(struct {
        params CheckCredentialParams;
    }) -> (struct {
        response CheckCredentialResponse;
    }) error CredentialError;
};