sdk/fidl/fuchsia.castauth/cast_auth.fidl

// 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.
@available(added=7)
library fuchsia.castauth;

/// Input hash to be signed by Cast key.
/// It must be ASN1-encoded SHA1 or SHA256 hash, with sizes 35 or 51 bytes.
type Asn1EncodedHash = strict union {
    1: sha1 array<byte, 35>;
    2: sha256 array<byte, 51>;
};

/// Error codes for CastKeySigner operations.
type ErrorCode = strict enum {
    /// Key/cert not found in storage.
    FILE_NOT_FOUND = 1;
    /// Error occurred during signing operation.
    CRYPTO_ERROR = 2;
};

/// The maximum size a certificate may be returned from `GetCertificateChain`
/// in the protocols of this library, in bytes.
@available(added=18)
const MAX_CERT_SIZE uint64 = 2048;
/// The maximum number of certificates that may be returned from
/// `GetCertificateChain` in the protocols of this library.
@available(added=18)
const MAX_CERT_CHAIN_SIZE uint64 = 16;

/// This FIDL interface is used to sign with hardware Cast key.
/// It is intended for short-term use only and will not be supported on all
/// devices. It will eventually be replaced by an attestation service.
@discoverable
closed protocol CastKeySigner {
    /// Use Cast key to sign a hash value.
    ///
    /// The input is hash value.
    /// The return value is the error code or the signature if the operation
    /// succeeds. The signature algorithm is RSA-2048-PKCS1.
    strict SignHash(struct {
        hash Asn1EncodedHash;
    }) -> (struct {
        signature array<byte, 256>;
    }) error ErrorCode;

    /// Get the Cast certificate chain.
    ///
    /// The return value is the error code or the certificate chain if
    /// the operation succeeds. The chain contains Cast key cert,
    /// one or more intermediate CA certs and root CA cert.
    @available(added=18)
    strict GetCertificateChain() -> (struct {
        cert_chain vector<vector<uint8>:MAX_CERT_SIZE>:MAX_CERT_CHAIN_SIZE;
    }) error ErrorCode;

    @available(replaced=18)
    strict GetCertificateChain() -> (struct {
        cert_chain vector<vector<uint8>:2048>:16;
    }) error ErrorCode;
};

/// This protocol allows accessing the Cast certificate without also granting
/// the capability to sign messages using the Cast key. Otherwise, the
/// functionality of `GetCertificateChain` should be identical to
/// `CastKeySigner`.
@discoverable
@available(added=18)
closed protocol CastCertificateRetriever {
    /// Get the Cast certificate chain.
    ///
    /// The return value is the error code or the certificate chain if
    /// the operation succeeds. The chain contains Cast key cert,
    /// one or more intermediate CA certs and root CA cert.
    strict GetCertificateChain() -> (struct {
        cert_chain vector<vector<uint8>:MAX_CERT_SIZE>:MAX_CERT_CHAIN_SIZE;
    }) error ErrorCode;
};