Module: wasi_ephemeral_crypto_signatures

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.

`signature_keypair`

Alias for handle.

$signature_keypair is just an alias for $keypair

However, bindings may want to define a specialized type signature_keypair as a super class of keypair, with additional methods such as sign.

`signature_publickey`

Alias for handle.

$signature_publickey is just an alias for $publickey

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

`signature_secretkey`

Alias for handle.

$signature_secretkey is just an alias for $secretkey

However, bindings may want to define a specialized type signature_secretkey as a super class of secretkey.

Functions

`signature_export()`

Returned error type: crypto_errno

Input:

signature: signature
encoding: signature_encoding

Output:

array_output mutable pointer

Export a signature.

This function exports a signature object using the specified encoding.

May return unsupported_encoding if the signature cannot be encoded into the given format.

`signature_import()`

Returned error type: crypto_errno

Input:

algorithm: string
encoded: u8 pointer
encoded_len: size
encoding: signature_encoding

Output:

signature mutable pointer

Create a signature object.

This object can be used along with a public key to verify an existing signature.

It may return invalid_signature if the signature is invalid or incompatible with the specified algorithm, as well as unsupported_encoding if the encoding is not compatible with the signature type.

The function may also return unsupported_algorithm if the algorithm is not supported by the host.

Example usage:
let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", SignatureEncoding::DER, encoded)?;

`signature_state_open()`

Returned error type: crypto_errno

Input:

kp: signature_keypair

Output:

signature_state mutable pointer

Create a new state to collect data to compute a signature on.

This function allows data to be signed to be supplied in a streaming fashion.

The state is not closed and can be used after a signature has been computed, allowing incremental updates by calling signature_state_update() again afterwards.

Example usage - signature creation
let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "Ed25519ph", keypair, KeypairEncoding::Raw)?;
let state_handle = ctx.signature_state_open(kp_handle)?;
ctx.signature_state_update(state_handle, b"message part 1")?;
ctx.signature_state_update(state_handle, b"message part 2")?;
let sig_handle = ctx.signature_state_sign(state_handle)?;
let raw_sig = ctx.signature_export(sig_handle, SignatureEncoding::Raw)?;

`signature_state_update()`

Returned error type: crypto_errno

Input:

state: signature_state
input: u8 pointer
input_len: size

This function has no output.

Absorb data into the signature state.

This function may return unsupported_feature is the selected algorithm doesn't support incremental updates.

`signature_state_sign()`

Returned error type: crypto_errno

Input:

state: signature_state

Output:

array_output mutable pointer

Compute a signature for all the data collected up to that point.

The function can be called multiple times for incremental signing.

`signature_state_close()`

Returned error type: crypto_errno

Input:

state: signature_state

This function has no output.

Destroy a signature state.

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

Note that closing a signature state doesn't close or invalidate the key pair object, that be reused for further signatures.

`signature_verification_state_open()`

Returned error type: crypto_errno

Input:

kp: signature_publickey

Output:

signature_verification_state mutable pointer

Create a new state to collect data to verify a signature on.

This is the verification counterpart of signature_state.

Data can be injected using signature_verification_state_update(), and the state is not closed after a verification, allowing incremental verification.

Example usage - signature verification:
let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_pk, PublicKeyEncoding::Sec)?;
let signature_handle = ctx.signature_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_sig, SignatureEncoding::Der)?;
let state_handle = ctx.signature_verification_state_open(pk_handle)?;
ctx.signature_verification_state_update(state_handle, "message")?;
ctx.signature_verification_state_verify(signature_handle)?;

`signature_verification_state_update()`

Returned error type: crypto_errno

Input:

state: signature_verification_state
input: u8 pointer
input_len: size

This function has no output.

Absorb data into the signature verification state.

This function may return unsupported_feature is the selected algorithm doesn't support incremental updates.

`signature_verification_state_verify()`

Returned error type: crypto_errno

Input:

state: signature_verification_state
signature: signature

This function has no output.

Check that the given signature is verifies for the data collected up to that point point.

The state is not closed and can absorb more data to allow for incremental verification.

The function returns invalid_signature if the signature doesn't appear to be valid.

`signature_verification_state_close()`

Returned error type: crypto_errno

Input:

state: signature_verification_state

This function has no output.

Destroy a signature verification state.

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

Note that closing a signature state doesn't close or invalidate the public key object, that be reused for further verifications.

`signature_close()`

Returned error type: crypto_errno

Input:

signature: signature

This function has no output.

Destroy a signature.

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

Files

wasi_ephemeral_crypto_signatures.md

Latest commit

History

wasi_ephemeral_crypto_signatures.md

File metadata and controls

Module: wasi_ephemeral_crypto_signatures

Table of contents

Types list:

Functions list:

Types

Functions

Input:

Output:

Input:

Output:

Input:

Output:

Input:

Input:

Output:

Input:

Input:

Output:

Input:

Input:

Input:

Input: