// Copyright 2020 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.weave;

using fuchsia.mem;

/// The maximum size of a signature supported by Weave.
///
/// Currently, Weave only supports ECDSA signatures using the P224 curve,
/// however, to allow this protocol to support future changes to supported
/// Weave signatures the maximum size of the returned signature is set to
/// 139 bytes which is the largest amount of space needed to return an
/// encoded ECDSA P521 signature.
const MAX_SIGNATURE_SIZE uint32 = 139;

/// The maximum size for a public key produced when generating a key pair.
const MAX_PUBLIC_KEY_SIZE uint32 = 65;

/// Bytes representing a wrapped private key. Since the size of the wrapping is
/// implementation-defined, the bytes are only bounded by MAX. The bytes should
/// be considered opaque, both in structure and in content, as the value is only
/// meaningful to operations such as [`Provisioner.GenerateKeyPair`].
alias PrivateKey = vector<uint8>:MAX;

/// This protocol is used for just-in-time provisioning operations.
@discoverable
closed protocol Provisioner {
    /// Generate key for just-in-time provisioning operations, used when
    /// working with Weave operational certificates. On success, a wrapped
    /// private key and public key pair is returned in `result`. The
    /// `wrapped_private_key` can be passed to [`Signer.SignHashWithPrivateKey`]
    /// to sign Weave messages.
    ///
    /// Currently, Weave only supports ECDSA signatures. This protocol returns
    /// a key-pair compatible with the Signer protocol (e.g. P256).
    strict GenerateKeyPair() -> (struct {
        wrapped_private_key PrivateKey;
        public_key vector<uint8>:MAX_PUBLIC_KEY_SIZE;
    }) error ErrorCode;
};

/// This protocol is used for signing operations with the factory-provisioned
/// Weave key or generated private keys.
@discoverable
closed protocol Signer {
    /// Sign the provided `hash` with the factory provisioned key. On success
    /// the result is returned in `signature`. The signature must be of a type
    /// that is supported by Weave, and must take the standard form of an ASN.1
    /// DER SEQUENCE. This operation must support SHA1 and SHA256 hash values.
    strict SignHash(struct {
        hash vector<uint8>:32;
    }) -> (struct {
        signature vector<uint8>:MAX_SIGNATURE_SIZE;
    }) error ErrorCode;

    /// Sign the provided `hash` with the provided `wrapped_private_key`. On
    /// success, the result is returned in `signature`. The signature must be
    /// of a type that is supported by Weave, and must take the standard form
    /// of an ASN.1 DER SEQUENCE. This operation must support SHA1 and SHA256
    /// hash values.
    strict SignHashWithPrivateKey(struct {
        hash vector<uint8>:32;
        wrapped_private_key PrivateKey;
    }) -> (struct {
        signature vector<uint8>:MAX_SIGNATURE_SIZE;
    }) error ErrorCode;
};

/// This protocol is used to retrieve factory data that may be encrypted at
/// rest.
@discoverable
closed protocol FactoryDataManager {
    /// Return the device `pairing_code` on success.
    strict GetPairingCode() -> (struct {
        pairing_code vector<uint8>:16;
    }) error ErrorCode;

    /// Returns the factory provisioned Weave certificate in PEM format.
    strict GetWeaveCertificate() -> (resource struct {
        certificate fuchsia.mem.Buffer;
    }) error ErrorCode;
};