Module: wasi_ephemeral_crypto_common

Handle for functions returning output whose size may be large or not known in advance.

An array_output object contains a host-allocated byte array.

A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. In addition, the content of such an object can be consumed by a guest in a streaming fashion.

An array_output handle is automatically closed after its full content has been consumed.

`options`

Alias for handle.

A set of options.

This type is used to set non-default parameters.

The exact set of allowed options depends on the algorithm being used.

`secrets_manager`

Alias for handle.

A handle to the optional secrets management facilities offered by a host.

This is used to generate, retrieve and invalidate managed keys.

`keypair`

Alias for handle.

A key pair.

`signature_state`

Alias for handle.

A state to absorb data to be signed.

After a signature has been computed or verified, the state remains valid for further operations.

A subsequent signature would sign all the data accumulated since the creation of the state object.

`signature`

Alias for handle.

A signature.

`publickey`

Alias for handle.

A public key, for key exchange and signature verification.

`secretkey`

Alias for handle.

A secret key, for key exchange mechanisms.

`signature_verification_state`

Alias for handle.

A state to absorb signed data to be verified.

`symmetric_state`

Alias for handle.

A state to perform symmetric operations.

The state is not reset nor invalidated after an option has been performed. Incremental updates and sessions are thus supported.

`symmetric_key`

Alias for handle.

A symmetric key.

The key can be imported from raw bytes, or can be a reference to a managed key.

If it was imported, the host will wipe it from memory as soon as the handle is closed.

`symmetric_tag`

Alias for handle.

An authentication tag.

This is an object returned by functions computing authentication tags.

A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the symmetric_tag_verify() function.

This object type can't be directly created from raw bytes. They are only returned by functions computing MACs.

The host is reponsible for securely wiping them from memory on close.

`opt_options_u`

Enumeration with tag type: u8, and the following members:

some: opt_options_u
none: opt_options_u

Options index, only required by the Interface Types translation layer.

`opt_options`

Tagged union with tag type: u8 and the following possibilities:

some: options
none: (empty)

An optional options set.

This union simulates an Option\<Options\> type to make the options parameter of some functions optional.

`opt_symmetric_key_u`

Enumeration with tag type: u8, and the following members:

some: opt_symmetric_key_u
none: opt_symmetric_key_u

Symmetric key index, only required by the Interface Types translation layer.

`opt_symmetric_key`

Tagged union with tag type: u8 and the following possibilities:

some: symmetric_key
none: (empty)

An optional symmetric key.

This union simulates an Option\<SymmetricKey\> type to make the symmetric_key parameter of some functions optional.

Functions

`options_open()`

Returned error type: crypto_errno

Input:

algorithm_type: algorithm_type

Output:

options mutable pointer

Create a new object to set non-default options.

Example usage:

let options_handle = options_open(AlgorithmType::Symmetric)?;
options_set(options_handle, "context", context)?;
options_set_u64(options_handle, "threads", 4)?;
let state = symmetric_state_open("BLAKE3", None, Some(options_handle))?;
options_close(options_handle)?;

`options_close()`

Returned error type: crypto_errno

Input:

handle: options

This function has no output.

Destroy an options object.

Objects are reference counted. It is safe to close an object immediately after the last function needing it is called.

`options_set()`

Returned error type: crypto_errno

Input:

handle: options
name: string
value: u8 pointer
value_len: size

This function has no output.

Set or update an option.

This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required.

This function may return unsupported_option if an option that doesn't exist for any implemented algorithms is specified.

`options_set_u64()`

Returned error type: crypto_errno

Input:

handle: options
name: string
value: u64

This function has no output.

Set or update an integer option.

This is used to set algorithm-specific parameters.

This function may return unsupported_option if an option that doesn't exist for any implemented algorithms is specified.

`options_set_guest_buffer()`

Returned error type: crypto_errno

Input:

handle: options
name: string
buffer: u8 mutable pointer
buffer_len: size

This function has no output.

Set or update a guest-allocated memory that the host can use or return data into.

This is for example used to set the scratch buffer required by memory-hard functions.

This function may return unsupported_option if an option that doesn't exist for any implemented algorithms is specified.

`array_output_len()`

Returned error type: crypto_errno

Input:

array_output: array_output

Output:

size mutable pointer

Return the length of an array_output object.

This allows a guest to allocate a buffer of the correct size in order to copy the output of a function returning this object type.

`array_output_pull()`

Returned error type: crypto_errno

Input:

array_output: array_output
buf: u8 mutable pointer
buf_len: size

Output:

size mutable pointer

Copy the content of an array_output object into an application-allocated buffer.

Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary.

The function returns the number of bytes that were actually copied. 0 means that the end of the stream has been reached. The total size always matches the output of array_output_len().

The handle is automatically closed after all the data has been consumed.

Example usage:
let len = array_output_len(output_handle)?;
let mut out = vec![0u8; len];
array_output_pull(output_handle, &mut out)?;

`secrets_manager_open()`

Returned error type: crypto_errno

Input:

options: opt_options

Output:

secrets_manager mutable pointer

(optional) Create a context to use a secrets manager.

The set of required and supported options is defined by the host.

The function returns the unsupported_feature error code if secrets management facilities are not supported by the host. This is also an optional import, meaning that the function may not even exist.

`secrets_manager_close()`

Returned error type: crypto_errno

Input:

secrets_manager: secrets_manager

This function has no output.

(optional) Destroy a secrets manager context.

The function returns the unsupported_feature error code if secrets management facilities are not supported by the host. This is also an optional import, meaning that the function may not even exist.

`secrets_manager_invalidate()`

Returned error type: crypto_errno

Input:

secrets_manager: secrets_manager
key_id: u8 pointer
key_id_len: size
key_version: version

This function has no output.

(optional) Invalidate a managed key or key pair given an identifier and a version.

This asks the secrets manager to delete or revoke a stored key, a specific version of a key.

key_version can be set to a version number, to version.latest to invalidate the current version, or to version.all to invalidate all versions of a key.

The function returns unsupported_feature if this operation is not supported by the host, and not_found if the identifier and version don't match any existing key.

This is an optional import, meaning that the function may not even exist.

Files

wasi_ephemeral_crypto_common.md

Latest commit

History

wasi_ephemeral_crypto_common.md

File metadata and controls

Module: wasi_ephemeral_crypto_common

Table of contents

Types list:

Functions list:

Types

Functions

Input:

Output:

Input:

Input:

Input:

Input:

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Input: