Skip to content

Latest commit

 

History

History
505 lines (312 loc) · 14.4 KB

wasi_ephemeral_crypto_external_secrets.md

File metadata and controls

505 lines (312 loc) · 14.4 KB
Raw

Module: wasi_ephemeral_crypto_external_secrets

Table of contents

Types list:

[All] - [crypto_errno] - [keypair_encoding] - [publickey_encoding] - [secretkey_encoding] - [signature_encoding] - [algorithm_type] - [version] - [size] - [timestamp] - [u64] - [array_output] - [options] - [secrets_manager] - [keypair] - [signature_state] - [signature] - [publickey] - [secretkey] - [signature_verification_state] - [symmetric_state] - [symmetric_key] - [symmetric_tag] - [opt_options_u] - [opt_options] - [opt_symmetric_key_u] - [opt_symmetric_key]

Functions list:

[All] - [external_secret_store()] - [external_secret_replace()] - [external_secret_from_id()] - [external_secret_invalidate()] - [external_secret_encapsulate()] - [external_secret_decapsulate()]

Types

crypto_errno

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

Error codes.

keypair_encoding

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

Encoding to use for importing or exporting a key pair.

publickey_encoding

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

Encoding to use for importing or exporting a public key.

secretkey_encoding

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

Encoding to use for importing or exporting a secret key.

signature_encoding

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

Encoding to use for importing or exporting a signature.

algorithm_type

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

An algorithm category.

version

Alias for u64.

Version of a managed key.

A version can be an arbitrary u64 integer, with the expection of some reserved values.

size

Alias for usize.

Size of a value.

timestamp

Alias for u64.

A UNIX timestamp, in seconds since 01/01/1970.

u64

Alias for u64.

A 64-bit value

array_output

Alias for handle.

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:

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

opt_options

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

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:

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

opt_symmetric_key

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

An optional symmetric key.

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

Functions

external_secret_store()

Returned error type: crypto_errno

Input:

This function has no output.

Store an external secret into the secrets manager.

$expiration is the expiration date of the secret as a UNIX timestamp, in seconds. An expiration date is mandatory.

On success, the secret identifier is put into $secret_id if it fits into $secret_id_max_len bytes. If the supplied ouptut buffer is too small, $overflow is returned.

If this function is not supported by the host the $unsupported_feature error is returned.

external_secret_replace()

Returned error type: crypto_errno

Input:

Output:

Replace a managed external with a new version.

$expiration is the expiration date of the secret as a UNIX timestamp, in seconds. An expiration date is mandatory.

On success, a new version is created and returned.

If this function is not supported by the host the $unsupported_feature error is returned.

external_secret_from_id()

Returned error type: crypto_errno

Input:

Output:

Get a copy of an external secret given an identifier and version.

secret_version can be set to a version number, or to version.latest to retrieve the most recent version of a secret.

On success, a copy of the secret is returned.

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

external_secret_invalidate()

Returned error type: crypto_errno

Input:

This function has no output.

Invalidate an external secret given an identifier and a version.

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

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

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

external_secret_encapsulate()

Returned error type: crypto_errno

Input:

Output:

Encrypt an external secret.

Applications don't have access to the encryption key, and the secrets manager is free to choose any suitable algorithm.

However, the returned ciphertext must include and authenticate both the secret and the expiration date.

On success, the ciphertext is returned.

external_secret_decapsulate()

Returned error type: crypto_errno

Input:

Output:

Decrypt an external secret previously encrypted by the secrets manager.

Returns the original secret if the ciphertext is valid. Returns $expired if the current date is past the stored expiration date. Returns $verification_failed if the ciphertext format is invalid or if its authentication tag couldn't be verified.