sdk/fidl/fuchsia.security.keymint/sealing_keys.fidl

// 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.security.keymint;

/// Allows a client to generate sealing keys and then use these keys to seal and unseal secrets.
/// Sealed secrets are safe for offline storage.
///
/// Note that (un)seal is synonymous with (un)wrap, e.g., wrapping an encryption key is the same
/// as sealing an encryption key.
@discoverable
closed protocol SealingKeys {
    /// Generates a new sealing key to seal and unseal secrets.
    ///
    /// |key_info| is information to be cryptographically bound to the returned key.
    ///   * The client will have to supply it in all uses (other than key deletion) of the returned
    ///     key.
    ///   * It serves two purposes: (1) internally by the key manager to identify the key owner and
    ///     (2) as a password to mitigate potential attacks from the key manager and as well as
    ///     other clients.
    ///   * It is recommended to include sufficient entropy in it (using it as a password) to
    ///     mitigage potential attacks from the secure world (the key manager's execution
    ///     environment) or from other clients.
    ///   * It is acceptible to pass a constant if deriving and persisting a password is too
    ///     cumbersome and the client fully trust the secure world and there are not many other
    ///     clients.
    ///
    /// The client is responsible for persisting both |key_info| and the returned |key_blob|.
    /// The key blob is encrypted with a TEE-private key. It is guaranteed to be unique for each
    /// call (even with the same key info). It can be stored in unsecure storage.
    ///
    /// Returns:
    ///   * The sealing key if everything worked.
    ///   * FAILED_CREATE if the key creation failed, e.g., the |key_info| was empty.
    strict CreateSealingKey(struct {
        key_info vector<uint8>:MAX;
    }) -> (struct {
        key_blob vector<uint8>:MAX;
    }) error CreateError;

    /// Seals a secret using a sealing key identified by its info and blob:
    ///   * The key info has to match the one supplied when generating the sealing key.
    ///
    /// Note that the secret may be a key itself. It has no bearing on the seal operation.
    ///
    /// Returns:
    ///   * The sealed secret if everything worked.
    ///   * FAILED_SEAL if the sealing failed, e.g., sealing key info or blob mismatch.
    strict Seal(struct {
        key_info vector<uint8>:MAX;
        key_blob vector<uint8>:MAX;
        secret vector<uint8>:MAX;
    }) -> (struct {
        sealed_secret vector<uint8>:MAX;
    }) error SealError;

    /// Unseals a sealed secret using a sealing key identified by its info and blob:
    ///   * The key info has to match the one supplied when generating the sealing key.
    ///   * The key blob has to match the one used to seal the secret.
    ///
    /// Note that the secret may be a key itself. It has no bearing on the unseal operation.
    ///
    /// Returns:
    ///   * The unsealed secret if everything worked.
    ///   * FAILED_UNSEAL if the unsealing failed, e.g., sealing key info or blob mismatch.
    strict Unseal(struct {
        key_info vector<uint8>:MAX;
        key_blob vector<uint8>:MAX;
        sealed_secret vector<uint8>:MAX;
    }) -> (struct {
        unsealed_secret vector<uint8>:MAX;
    }) error UnsealError;

    // TODO(http://fxbug.dev/423694897): add "delete all keys" method.
};

type CreateError = flexible enum {
    @unknown
    UNKNOWN = 0;
    FAILED_CREATION = 1;
};

type SealError = flexible enum {
    @unknown
    UNKNOWN = 0;
    FAILED_SEAL = 1;
};

type UnsealError = flexible enum {
    @unknown
    UNKNOWN = 0;
    FAILED_UNSEAL = 1;
};