Module: wasi_ephemeral_crypto_asymmetric_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

`keypair_generate()`

Returned error type: crypto_errno

Input:

algorithm_type: algorithm_type
algorithm: string
options: opt_options

Output:

keypair mutable pointer

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:
let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?;

`keypair_import()`

Returned error type: crypto_errno

Input:

algorithm_type: algorithm_type
algorithm: string
encoded: u8 pointer
encoded_len: size
encoding: keypair_encoding

Output:

keypair mutable pointer

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:
let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?;

`keypair_generate_managed()`

Returned error type: crypto_errno

Input:

secrets_manager: secrets_manager
algorithm_type: algorithm_type
algorithm: string
options: opt_options

Output:

keypair mutable pointer

(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.

`keypair_store_managed()`

Returned error type: crypto_errno

Input:

secrets_manager: secrets_manager
kp: keypair
kp_id: u8 mutable pointer
kp_id_max_len: size

This function has no output.

(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.

`keypair_replace_managed()`

Returned error type: crypto_errno

Input:

secrets_manager: secrets_manager
kp_old: keypair
kp_new: keypair

Output:

version mutable pointer

(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.

`keypair_id()`

Returned error type: crypto_errno

Input:

kp: keypair
kp_id: u8 mutable pointer
kp_id_max_len: size

Output:

size mutable pointer
version mutable pointer

(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.

`keypair_from_id()`

Returned error type: crypto_errno

Input:

secrets_manager: secrets_manager
kp_id: u8 pointer
kp_id_len: size
kp_version: version

Output:

keypair mutable pointer

(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.

`keypair_from_pk_and_sk()`

Returned error type: crypto_errno

Input:

publickey: publickey
secretkey: secretkey

Output:

keypair mutable pointer

Create a key pair from a public key and a secret key.

`keypair_export()`

Returned error type: crypto_errno

Input:

kp: keypair
encoding: keypair_encoding

Output:

array_output mutable pointer

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.

`keypair_publickey()`

Returned error type: crypto_errno

Input:

kp: keypair

Output:

publickey mutable pointer

Get the public key of a key pair.

`keypair_secretkey()`

Returned error type: crypto_errno

Input:

kp: keypair

Output:

secretkey mutable pointer

Get the secret key of a key pair.

`keypair_close()`

Returned error type: crypto_errno

Input:

kp: keypair

This function has no output.

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.

`publickey_import()`

Returned error type: crypto_errno

Input:

algorithm_type: algorithm_type
algorithm: string
encoded: u8 pointer
encoded_len: size
encoding: publickey_encoding

Output:

publickey mutable pointer

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:
let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?;

`publickey_export()`

Returned error type: crypto_errno

Input:

pk: publickey
encoding: publickey_encoding

Output:

array_output mutable pointer

Export a public key as the given encoding format.

May return unsupported_encoding if the encoding is not supported.

`publickey_verify()`

Returned error type: crypto_errno

Input:

pk: publickey

This function has no output.

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.

`publickey_from_secretkey()`

Returned error type: crypto_errno

Input:

sk: secretkey

Output:

publickey mutable pointer

Compute the public key for a secret key.

`publickey_close()`

Returned error type: crypto_errno

Input:

pk: publickey

This function has no output.

Destroy a public key.

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

`secretkey_import()`

Returned error type: crypto_errno

Input:

algorithm_type: algorithm_type
algorithm: string
encoded: u8 pointer
encoded_len: size
encoding: secretkey_encoding

Output:

secretkey mutable pointer

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:
let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?;

`secretkey_export()`

Returned error type: crypto_errno

Input:

sk: secretkey
encoding: secretkey_encoding

Output:

array_output mutable pointer

Export a secret key as the given encoding format.

May return unsupported_encoding if the encoding is not supported.

`secretkey_close()`

Returned error type: crypto_errno

Input:

sk: secretkey

This function has no output.

Destroy a secret key.

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

Files

wasi_ephemeral_crypto_asymmetric_common.md

Latest commit

History

wasi_ephemeral_crypto_asymmetric_common.md

File metadata and controls

Module: wasi_ephemeral_crypto_asymmetric_common

Table of contents

Types list:

Functions list:

Types

Functions

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Input:

Output:

Input:

Output:

Input:

Input:

Output:

Input:

Input:

Output:

Input:

Output:

Input: