wasi_ephemeral_crypto_asymmetric_common.witx

(module $wasi_ephemeral_crypto_asymmetric_common
    (use * from $wasi_ephemeral_crypto_common)

    ;;; Generate a new key pair.
    ;;;
    ;;; Internally, a key pair stores the supplied algorithm and optional parameters.
    ;;;
    ;;; Trying to use that key pair with different parameters will throw an `invalid_key` error.
    ;;;
    ;;; This function may return `$crypto_errno.unsupported_feature` if key generation is not supported by the host for the chosen algorithm.
    ;;;
    ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host.
    ;;;
    ;;; Finally, if generating that type of key pair is an expensive operation, the function may return `in_progress`.
    ;;; In that case, the guest should retry with the same parameters until the function completes.
    ;;;
    ;;; Example usage:
    ;;;
    ;;; ```rust
    ;;; let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?;
    ;;; ```
    (@interface func (export "keypair_generate")
        (param $algorithm_type $algorithm_type)
        (param $algorithm string)
        (param $options $opt_options)
        (result $error (expected $keypair (error $crypto_errno)))
    )

    ;;; Import a key pair.
    ;;;
    ;;; This function creates a `keypair` object from existing material.
    ;;;
    ;;; It may return `unsupported_algorithm` if the encoding scheme is not supported, or `invalid_key` if the key cannot be decoded.
    ;;;
    ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host.
    ;;;
    ;;; Example usage:
    ;;;
    ;;; ```rust
    ;;; let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?;
    ;;; ```
    (@interface func (export "keypair_import")
        (param $algorithm_type $algorithm_type)
        (param $algorithm string)
        (param $encoded (@witx const_pointer u8))
        (param $encoded_len $size)
        (param $encoding $keypair_encoding)
        (result $error (expected $keypair (error $crypto_errno)))
    )

    ;;; __(optional)__
    ;;; Generate a new managed key pair.
    ;;;
    ;;; The key pair is generated and stored by the secrets management facilities.
    ;;;
    ;;; It may be used through its identifier, but the host may not allow it to be exported.
    ;;;
    ;;; The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host,
    ;;; or `unsupported_algorithm` if a key cannot be created for the chosen algorithm.
    ;;;
    ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host.
    ;;;
    ;;; This is also an optional import, meaning that the function may not even exist.
    (@interface func (export "keypair_generate_managed")
        (param $secrets_manager $secrets_manager)
        (param $algorithm_type $algorithm_type)
        (param $algorithm string)
        (param $options $opt_options)
        (result $error (expected $keypair (error $crypto_errno)))
    )

    ;;; __(optional)__
    ;;; Store a key pair into the secrets manager.
    ;;;
    ;;; On success, the function stores the key pair identifier into `$kp_id`,
    ;;; into which up to `$kp_id_max_len` can be written.
    ;;;
    ;;; The function returns `overflow` if the supplied buffer is too small.
    (@interface func (export "keypair_store_managed")
        (param $secrets_manager $secrets_manager)
        (param $kp $keypair)
        (param $kp_id (@witx pointer u8))
        (param $kp_id_max_len $size)
        (result $error (expected (error $crypto_errno)))
    )

    ;;; __(optional)__
    ;;; Replace a managed key pair.
    ;;;
    ;;; This function crates a new version of a managed key pair, by replacing `$kp_old` with `$kp_new`.
    ;;;
    ;;; It does several things:
    ;;;
    ;;; - The key identifier for `$kp_new` is set to the one of `$kp_old`.
    ;;; - A new, unique version identifier is assigned to `$kp_new`. This version will be equivalent to using `$version_latest` until the key is replaced.
    ;;; - The `$kp_old` handle is closed.
    ;;;
    ;;; Both keys must share the same algorithm and have compatible parameters. If this is not the case, `incompatible_keys` is returned.
    ;;;
    ;;; The function may also return the `unsupported_feature` error code if secrets management facilities are not supported by the host,
    ;;; or if keys cannot be rotated.
    ;;;
    ;;; Finally, `prohibited_operation` can be returned if `$kp_new` wasn't created by the secrets manager, and the secrets manager prohibits imported keys.
    ;;;
    ;;; If the operation succeeded, the new version is returned.
    ;;;
    ;;; This is an optional import, meaning that the function may not even exist.
    (@interface func (export "keypair_replace_managed")
        (param $secrets_manager $secrets_manager)
        (param $kp_old $keypair)
        (param $kp_new $keypair)
        (result $error (expected $version (error $crypto_errno)))
    )

    ;;; __(optional)__
    ;;; Return the key pair identifier and version of a managed key pair.
    ;;;
    ;;; If the key pair is not managed, `unsupported_feature` is returned instead.
    ;;;
    ;;; This is an optional import, meaning that the function may not even exist.
    (@interface func (export "keypair_id")
        (param $kp $keypair)
        (param $kp_id (@witx pointer u8))
        (param $kp_id_max_len $size)
        (result $error (expected (tuple $size $version) (error $crypto_errno)))
    )

    ;;; __(optional)__
    ;;; Return a managed key pair from a key identifier.
    ;;;
    ;;; `kp_version` can be set to `version_latest` to retrieve the most recent version of a key pair.
    ;;;
    ;;; If no key pair matching the provided information is found, `not_found` is returned instead.
    ;;;
    ;;; This is an optional import, meaning that the function may not even exist.
    ;;; ```
    (@interface func (export "keypair_from_id")
        (param $secrets_manager $secrets_manager)
        (param $kp_id (@witx const_pointer u8))
        (param $kp_id_len $size)
        (param $kp_version $version)
        (result $error (expected $keypair (error $crypto_errno)))
    )

    ;;; Create a key pair from a public key and a secret key.
    (@interface func (export "keypair_from_pk_and_sk")
        (param $publickey $publickey)
        (param $secretkey $secretkey)
        (result $error (expected $keypair (error $crypto_errno)))
    )

    ;;; Export a key pair as the given encoding format.
    ;;;
    ;;; May return `prohibited_operation` if this operation is denied or `unsupported_encoding` if the encoding is not supported.
    (@interface func (export "keypair_export")
        (param $kp $keypair)
        (param $encoding $keypair_encoding)
        (result $error (expected $array_output (error $crypto_errno)))
    )

    ;;; Get the public key of a key pair.
    (@interface func (export "keypair_publickey")
        (param $kp $keypair)
        (result $error (expected $publickey (error $crypto_errno)))
    )

    ;;; Get the secret key of a key pair.
    (@interface func (export "keypair_secretkey")
        (param $kp $keypair)
        (result $error (expected $secretkey (error $crypto_errno)))
    )

    ;;; Destroy a key pair.
    ;;;
    ;;; The host will automatically wipe traces of the secret key from memory.
    ;;;
    ;;; If this is a managed key, the key will not be removed from persistent storage, and can be reconstructed later using the key identifier.
    (@interface func (export "keypair_close")
        (param $kp $keypair)
        (result $error (expected (error $crypto_errno)))
    )

    ;;; Import a public key.
    ;;;
    ;;; The function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type.
    ;;;
    ;;; It may also return `invalid_key` if the key doesn't appear to match the supplied algorithm.
    ;;;
    ;;; Finally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host.
    ;;;
    ;;; Example usage:
    ;;;
    ;;; ```rust
    ;;; let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?;
    ;;; ```
    (@interface func (export "publickey_import")
        (param $algorithm_type $algorithm_type)
        (param $algorithm string)
        (param $encoded (@witx const_pointer u8))
        (param $encoded_len $size)
        (param $encoding $publickey_encoding)
        (result $error (expected $publickey (error $crypto_errno)))
    )

    ;;; Export a public key as the given encoding format.
    ;;;
    ;;; May return `unsupported_encoding` if the encoding is not supported.
    (@interface func (export "publickey_export")
        (param $pk $publickey)
        (param $encoding $publickey_encoding)
        (result $error (expected $array_output (error $crypto_errno)))
    )

    ;;; Check that a public key is valid and in canonical form.
    ;;;
    ;;; This function may perform stricter checks than those made during importation at the expense of additional CPU cycles.
    ;;;
    ;;; The function returns `invalid_key` if the public key didn't pass the checks.
    (@interface func (export "publickey_verify")
        (param $pk $publickey)
        (result $error (expected (error $crypto_errno)))
    )

    ;;; Compute the public key for a secret key.
    (@interface func (export "publickey_from_secretkey")
        (param $sk $secretkey)
        (result $error (expected $publickey (error $crypto_errno)))
    )

    ;;; Destroy a public key.
    ;;;
    ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called.
    (@interface func (export "publickey_close")
        (param $pk $publickey)
        (result $error (expected (error $crypto_errno)))
    )

    ;;; Import a secret key.
    ;;;
    ;;; The function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type.
    ;;;
    ;;; It may also return `invalid_key` if the key doesn't appear to match the supplied algorithm.
    ;;;
    ;;; Finally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host.
    ;;;
    ;;; Example usage:
    ;;;
    ;;; ```rust
    ;;; let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?;
    ;;; ```
    (@interface func (export "secretkey_import")
        (param $algorithm_type $algorithm_type)
        (param $algorithm string)
        (param $encoded (@witx const_pointer u8))
        (param $encoded_len $size)
        (param $encoding $secretkey_encoding)
        (result $error (expected $secretkey (error $crypto_errno)))
    )

    ;;; Export a secret key as the given encoding format.
    ;;;
    ;;; May return `unsupported_encoding` if the encoding is not supported.
    (@interface func (export "secretkey_export")
        (param $sk $secretkey)
        (param $encoding $secretkey_encoding)
        (result $error (expected $array_output (error $crypto_errno)))
    )

    ;;; Destroy a secret key.
    ;;;
    ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called.
    (@interface func (export "secretkey_close")
        (param $sk $secretkey)
        (result $error (expected (error $crypto_errno)))
    )
)