Module: wasiephemeralcrypto_kx

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.

`kx_keypair`

Alias for handle.

$kx_keypair is just an alias for $keypair

However, bindings may want to define a specialized type kx_keypair as a super class of keypair.

`kx_publickey`

Alias for handle.

$kx_publickey is just an alias for $publickey

However, bindings may want to define a specialized type kx_publickey as a super class of publickey, with additional methods such as dh.

`kx_secretkey`

Alias for handle.

$kx_secretkey is just an alias for $secretkey

However, bindings may want to define a specialized type kx_secretkey as a super class of secretkeykey, with additional methods such as dh.

Functions

`kx_dh()`

Returned error type: crypto_errno

Input:

pk: publickey
sk: secretkey

Output:

array_output mutable pointer

Perform a simple Diffie-Hellman key exchange.

Both keys must be of the same type, or else the $crypto_errno.incompatible_keys error is returned. The algorithm also has to support this kind of key exchange. If this is not the case, the $crypto_errno.invalid_operation error is returned.

Otherwide, a raw shared key is returned, and can be imported as a symmetric key.

`kx_encapsulate()`

Returned error type: crypto_errno

Input:

pk: publickey

Output:

array_output mutable pointer
array_output mutable pointer

Create a shared secret and encrypt it for the given public key.

This operation is only compatible with specific algorithms. If a selected algorithm doesn't support it, $crypto_errno.invalid_operation is returned.

On success, both the shared secret and its encrypted version are returned.

`kx_decapsulate()`

Returned error type: crypto_errno

Input:

sk: secretkey
encapsulated_secret: u8 pointer
encapsulated_secret_len: size

Output:

array_output mutable pointer

Decapsulate an encapsulated secret crated with kx_encapsulate

Return the secret, or $crypto_errno.verification_failed on error.