// Copyright 2025 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=HEAD)
library fuchsia.hardware.inlineencryption;

using zx;

@discoverable
closed protocol Device {
    /// Programs the ephemerally wrapped `wrapped_key` into the inline encryption hardware in the
    /// next available `slot`. All slots programmed via the connection this method is called on
    /// will be evicted once the connection is dropped. It is not possible to evict individual keys
    /// (not for any technical reasons; a need for this has not yet arisen). `wrapped_key` must be
    /// a key wrapped by the inline encryption hardware (in the same session/boot) via a separate
    /// mechanism to this protocol.
    ///
    /// Returns
    /// - ZX_ERR_NO_RESOURCES if there are no available key slots.
    /// - ZX_ERR_INVALID_ARGS if `wrapped_key` is not the expected size or if the `wrapped_key`
    ///   fails authentication (e.g. wrapped_key is from a previous boot).
    /// - ZX_ERR_TIMED_OUT if the operation times out.
    /// - ZX_ERR_INTERNAL if the operation failed for any other reason.
    strict ProgramKey(resource struct {
        wrapped_key vector<uint8>:MAX;
        data_unit_size uint32;
    }) -> (struct {
        slot uint8;
    }) error zx.Status;

    /// Derives a raw software secret from the ephemerally wrapped `wrapped_key`. `wrapped_key`
    /// must be a key wrapped by the inline encryption hardware (in the same session/boot) via a
    /// separate mechanism to this protocol. The returned secret can be used for non-inline
    /// cryptographic operations e.g. it can be used for encrypting filesystem metadata not covered
    /// by inline encryption.
    /// Returns
    /// - ZX_ERR_INVALID_ARGS if `wrapped_key` is not the expected size or if the `wrapped_key`
    ///   fails authentication (e.g. wrapped_key is from a previous boot).
    /// - ZX_ERR_TIMED_OUT if the operation times out.
    /// - ZX_ERR_INTERNAL if the operation failed for any other reason.
    strict DeriveRawSecret(resource struct {
        wrapped_key vector<uint8>:MAX;
    }) -> (resource struct {
        secret vector<uint8>:MAX;
    }) error zx.Status;
};

service Service {
    device client_end:Device;
};