pub const DOC_TEXT: &str = "(;; Error codes.\n ;) (typename $crypto_errno (enum u16 (;; Operation succeeded.\n ;) $success (;; An error occurred when trying to during a conversion from a host type to a guest type.\n\nOnly an internal bug can throw this error.\n ;) $guest_error (;; The requested operation is valid, but not implemented by the host.\n ;) $not_implemented (;; The requested feature is not supported by the chosen algorithm.\n ;) $unsupported_feature (;; The requested operation is valid, but was administratively prohibited.\n ;) $prohibited_operation (;; Unsupported encoding for an import or export operation.\n ;) $unsupported_encoding (;; The requested algorithm is not supported by the host.\n ;) $unsupported_algorithm (;; The requested option is not supported by the currently selected algorithm.\n ;) $unsupported_option (;; An invalid or incompatible key was supplied.\n\nThe key may not be valid, or was generated for a different algorithm or parameters set.\n ;) $invalid_key (;; The currently selected algorithm doesn\'t support the requested output length.\n\nThis error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block.\n ;) $invalid_length (;; A signature or authentication tag verification failed.\n ;) $verification_failed (;; A secure random numbers generator is not available.\n\nThe requested operation requires random numbers, but the host cannot securely generate them at the moment.\n ;) $rng_error (;; An error was returned by the underlying cryptography library.\n\nThe host may be running out of memory, parameters may be incompatible with the chosen implementation of an algorithm or another unexpected error may have happened.\n\nIdeally, the specification should provide enough details and guidance to make this error impossible to ever be thrown.\n\nRealistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific.\nThis error can thus be thrown when other error types are not suitable, and when the original error comes from the cryptographic primitives themselves and not from the WASI module.\n ;) $algorithm_failure (;; The supplied signature is invalid, or incompatible with the chosen algorithm.\n ;) $invalid_signature (;; An attempt was made to close a handle that was already closed.\n ;) $closed (;; A function was called with an unassigned handle, a closed handle, or handle of an unexpected type.\n ;) $invalid_handle (;; The host needs to copy data to a guest-allocated buffer, but that buffer is too small.\n ;) $overflow (;; An internal error occurred.\n\nThis error is reserved to internal consistency checks, and must only be sent if the internal state of the host remains safe after an inconsistency was detected.\n ;) $internal_error (;; Too many handles are currently open, and a new one cannot be created.\n\nImplementations are free to represent handles as they want, and to enforce limits to limit resources usage.\n ;) $too_many_handles (;; A key was provided, but the chosen algorithm doesn\'t support keys.\n\nThis is returned by symmetric operations.\n\nMany hash functions, in particular, do not support keys without being used in particular constructions.\nBlindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities.\n\nThese functions must refuse to create the context and return this error instead.\n ;) $key_not_supported (;; A key is required for the chosen algorithm, but none was given.\n ;) $key_required (;; The provided authentication tag is invalid or incompatible with the current algorithm.\n\nThis error is returned by decryption functions and tag verification functions.\n\nUnlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input.\n ;) $invalid_tag (;; The requested operation is incompatible with the current scheme.\n\nFor example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function.\nThis error code will be returned instead.\n ;) $invalid_operation (;; A nonce is required.\n\nMost encryption schemes require a nonce.\n\nIn the absence of a nonce, the WASI cryptography module can automatically generate one, if that can be done safely. The nonce can be retrieved later with the `symmetric_state_option_get()` function using the `nonce` parameter.\nIf automatically generating a nonce cannot be done safely, the module never falls back to an insecure option and requests an explicit nonce by throwing that error.\n ;) $nonce_required (;; The named option was not set.\n\nThe caller tried to read the value of an option that was not set.\nThis error is used to make the distinction between an empty option, and an option that was not set and left to its default value.\n ;) $option_not_set (;; A key or key pair matching the requested identifier cannot be found using the supplied information.\n\nThis error is returned by a key manager via the `keypair_from_id()` function.\n ;) $key_not_found (;; The algorithm requires parameters that haven\'t been set.\n\nNon-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm.\n ;) $parameters_missing (;; A requested computation is not done yet, and additional calls to the function are required.\n\nSome functions, such as functions generating key pairs and password stretching functions, can take a long time to complete.\n\nIn order to avoid a host call to be blocked for too long, these functions can return prematurely, requiring additional calls with the same parameters until they complete.\n ;) $in_progress (;; Multiple keys have been provided, but they do not share the same type.\n\nThis error is returned when trying to build a key pair from a public key and a secret key that were created for different and incompatible algorithms.\n ;) $incompatible_keys (;; A managed key expired and cannot be used any more.\n ;) $expired_key))\n(;; Encoding to use for importing or exporting a key pair.\n ;) (typename $keypair_encoding (enum u16 (;; Raw bytes.\n ;) $raw (;; PCSK8 encoding.\n ;) $pkcs8 (;; DER encoding.\n ;) $der (;; PEM encoding.\n ;) $pem))\n(;; Encoding to use for importing or exporting a public key.\n ;) (typename $publickey_encoding (enum u16 (;; Raw bytes.\n ;) $raw (;; DER encoding.\n ;) $der (;; PEM encoding.\n ;) $pem (;; SEC encoding.\n ;) $sec (;; Compressed SEC encoding.\n ;) $compressed_sec))\n(;; Encoding to use for importing or exporting a secret key.\n ;) (typename $secretkey_encoding (enum u16 (;; Raw bytes.\n ;) $raw (;; DER encoding.\n ;) $der (;; PEM encoding.\n ;) $pem (;; SEC encoding.\n ;) $sec (;; Compressed SEC encoding.\n ;) $compressed_sec))\n(;; Encoding to use for importing or exporting a signature.\n ;) (typename $signature_encoding (enum u16 (;; Raw bytes.\n ;) $raw (;; DER encoding.\n ;) $der))\n(;; An algorithm category.\n ;) (typename $algorithm_type (enum u16 $signatures $symmetric $key_exchange))\n(;; Version of a managed key.\n\nA version can be an arbitrary `u64` integer, with the expection of some reserved values.\n ;) (typename $version (int u64 (;; Key doesn\'t support versioning.\n ;) (const $unspecified 18374686479671623680) (;; Use the latest version of a key.\n ;) (const $latest 18374686479671623681) (;; Perform an operation over all versions of a key.\n ;) (const $all 18374686479671623682)))\n(;; Size of a value.\n ;) (typename $size (@witx usize))\n(;; Handle for functions returning output whose size may be large or not known in advance.\n\nAn `array_output` object contains a host-allocated byte array.\n\nA guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size.\nIn addition, the content of such an object can be consumed by a guest in a streaming fashion.\n\nAn `array_output` handle is automatically closed after its full content has been consumed.\n ;) (typename $array_output (handle))\n(;; A set of options.\n\nThis type is used to set non-default parameters.\n\nThe exact set of allowed options depends on the algorithm being used.\n ;) (typename $options (handle))\n(;; A handle to the optional key management facilities offered by a host.\n\nThis is used to generate, retrieve and invalidate managed keys.\n ;) (typename $key_manager (handle))\n(;; A key pair.\n ;) (typename $keypair (handle))\n(;; A state to absorb data to be signed.\n\nAfter a signature has been computed or verified, the state remains valid for further operations.\n\nA subsequent signature would sign all the data accumulated since the creation of the state object.\n ;) (typename $signature_state (handle))\n(;; A signature.\n ;) (typename $signature (handle))\n(;; A public key, for key exchange and signature verification.\n ;) (typename $publickey (handle))\n(;; A secret key, for key exchange mechanisms.\n ;) (typename $secretkey (handle))\n(;; A state to absorb signed data to be verified.\n ;) (typename $signature_verification_state (handle))\n(;; A state to perform symmetric operations.\n\nThe state is not reset nor invalidated after an option has been performed.\nIncremental updates and sessions are thus supported.\n ;) (typename $symmetric_state (handle))\n(;; A symmetric key.\n\nThe key can be imported from raw bytes, or can be a reference to a managed key.\n\nIf it was imported, the host will wipe it from memory as soon as the handle is closed.\n ;) (typename $symmetric_key (handle))\n(;; An authentication tag.\n\nThis is an object returned by functions computing authentication tags.\n\nA tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function.\n\nThis object type can\'t be directly created from raw bytes. They are only returned by functions computing MACs.\n\nThe host is reponsible for securely wiping them from memory on close.\n ;) (typename $symmetric_tag (handle))\n(;; Options index, only required by the Interface Types translation layer.\n ;) (typename $opt_options_u (enum u8 $some $none))\n(;; An optional options set.\n\nThis union simulates an `Option<Options>` type to make the `options` parameter of some functions optional.\n ;) (typename $opt_options (union $opt_options_u (field $some $options) (empty $none)))\n(;; Symmetric key index, only required by the Interface Types translation layer.\n ;) (typename $opt_symmetric_key_u (enum u8 $some $none))\n(;; An optional symmetric key.\n\nThis union simulates an `Option<SymmetricKey>` type to make the `symmetric_key` parameter of some functions optional.\n ;) (typename $opt_symmetric_key (union $opt_symmetric_key_u (field $some $symmetric_key) (empty $none)))\n(;; `$signature_keypair` is just an alias for `$keypair`\n\nHowever, bindings may want to define a specialized type `signature_keypair` as a super class of `keypair`, with additional methods such as `sign`.\n ;) (typename $signature_keypair $keypair)\n(;; `$signature_publickey` is just an alias for `$publickey`\n\nHowever, bindings may want to define a specialized type `signature_publickey` as a super class of `publickey`, with additional methods such as `verify`.\n ;) (typename $signature_publickey $publickey)\n(;; `$signature_secretkey` is just an alias for `$secretkey`\n\nHowever, bindings may want to define a specialized type `signature_secretkey` as a super class of `secretkey`.\n ;) (typename $signature_secretkey $secretkey)\n(;; `$kx_keypair` is just an alias for `$keypair`\n\nHowever, bindings may want to define a specialized type `kx_keypair` as a super class of `keypair`.\n ;) (typename $kx_keypair $keypair)\n(;; `$kx_publickey` is just an alias for `$publickey`\n\nHowever, bindings may want to define a specialized type `kx_publickey` as a super class of `publickey`, with additional methods such as `dh`.\n ;) (typename $kx_publickey $publickey)\n(;; `$kx_secretkey` is just an alias for `$secretkey`\n\nHowever, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkeykey`, with additional methods such as `dh`.\n ;) (typename $kx_secretkey $secretkey)\n(module $wasi_ephemeral_crypto_common (import \"memory\" (memory)) (;; Create a new object to set non-default options.\n\nExample usage:\n\n```rust\nlet options_handle = options_open(AlgorithmType::Symmetric)?;\noptions_set(options_handle, \"context\", context)?;\noptions_set_u64(options_handle, \"threads\", 4)?;\nlet state = symmetric_state_open(\"BLAKE3\", None, Some(options_handle))?;\noptions_close(options_handle)?;\n```\n ;) (@interface func (export \"options_open\") (param $algorithm_type $algorithm_type) (result $error $crypto_errno) (result $handle $options)) (;; Destroy an options object.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"options_close\") (param $handle $options) (result $error $crypto_errno)) (;; Set or update an option.\n\nThis is used to set algorithm-specific parameters, but also to provide credentials for the key management facilities, if required.\n\nThis function may return `unsupported_option` if an option that doesn\'t exist for any implemented algorithms is specified.\n ;) (@interface func (export \"options_set\") (param $handle $options) (param $name string) (param $value (@witx const_pointer u8)) (param $value_len $size) (result $error $crypto_errno)) (;; Set or update an integer option.\n\nThis is used to set algorithm-specific parameters.\n\nThis function may return `unsupported_option` if an option that doesn\'t exist for any implemented algorithms is specified.\n ;) (@interface func (export \"options_set_u64\") (param $handle $options) (param $name string) (param $value u64) (result $error $crypto_errno)) (;; Set or update a guest-allocated memory that the host can use or return data into.\n\nThis is for example used to set the scratch buffer required by memory-hard functions.\n\nThis function may return `unsupported_option` if an option that doesn\'t exist for any implemented algorithms is specified.\n ;) (@interface func (export \"options_set_guest_buffer\") (param $handle $options) (param $name string) (param $buffer (@witx pointer u8)) (param $buffer_len $size) (result $error $crypto_errno)) (;; Return the length of an `array_output` object.\n\nThis allows a guest to allocate a buffer of the correct size in order to copy the output of a function returning this object type.\n ;) (@interface func (export \"array_output_len\") (param $array_output $array_output) (result $error $crypto_errno) (result $len $size)) (;; Copy the content of an `array_output` object into an application-allocated buffer.\n\nMultiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary.\n\nThe 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()`.\n\nThe handle is automatically closed after all the data has been consumed.\n\nExample usage:\n\n```rust\nlet len = array_output_len(output_handle)?;\nlet mut out = vec![0u8; len];\narray_output_pull(output_handle, &mut out)?;\n```\n ;) (@interface func (export \"array_output_pull\") (param $array_output $array_output) (param $buf (@witx pointer u8)) (param $buf_len $size) (result $error $crypto_errno) (result $len $size)) (;; __(optional)__\nCreate a context to use a key manager.\n\nThe set of required and supported options is defined by the host.\n\nThe function returns the `unsupported_feature` error code if key management facilities are not supported by the host.\nThis is also an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"key_manager_open\") (param $options $opt_options) (result $error $crypto_errno) (result $handle $key_manager)) (;; __(optional)__\nDestroy a key manager context.\n\nThe function returns the `unsupported_feature` error code if key management facilities are not supported by the host.\nThis is also an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"key_manager_close\") (param $key_manager $key_manager) (result $error $crypto_errno)) (;; __(optional)__\nInvalidate a managed key or key pair given an identifier and a version.\n\nThis asks the key manager to delete or revoke a stored key, a specific version of a key..\n\n`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.\n\nThe function returns `unsupported_feature` if this operation is not supported by the host, and `key_not_found` if the identifier and version don\'t match any existing key.\n\nThis is an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"key_manager_invalidate\") (param $key_manager $key_manager) (param $key_id (@witx const_pointer u8)) (param $key_id_len $size) (param $key_version $version) (result $error $crypto_errno)))\n(module $wasi_ephemeral_crypto_asymmetric_common (import \"memory\" (memory)) (;; Generate a new key pair.\n\nInternally, a key pair stores the supplied algorithm and optional parameters.\n\nTrying to use that key pair with different parameters will throw an `invalid_key` error.\n\nThis function may return `$crypto_errno.unsupported_feature` if key generation is not supported by the host for the chosen algorithm.\n\nThe function may also return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nFinally, if generating that type of key pair is an expensive operation, the function may return `in_progress`.\nIn that case, the guest should retry with the same parameters until the function completes.\n\nExample usage:\n\n```rust\nlet kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, \"RSA_PKCS1_2048_8192_SHA512\", None)?;\n```\n ;) (@interface func (export \"keypair_generate\") (param $algorithm_type $algorithm_type) (param $algorithm string) (param $options $opt_options) (result $error $crypto_errno) (result $handle $keypair)) (;; Import a key pair.\n\nThis function creates a `keypair` object from existing material.\n\nIt may return `unsupported_algorithm` if the encoding scheme is not supported, or `invalid_key` if the key cannot be decoded.\n\nThe function may also return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nExample usage:\n\n```rust\nlet kp_handle = ctx.keypair_import(AlgorithmType::Signatures, \"RSA_PKCS1_2048_8192_SHA512\", KeypairEncoding::PKCS8)?;\n```\n ;) (@interface func (export \"keypair_import\") (param $algorithm_type $algorithm_type) (param $algorithm string) (param $encoded (@witx const_pointer u8)) (param $encoded_len $size) (param $encoding $keypair_encoding) (result $error $crypto_errno) (result $handle $keypair)) (;; __(optional)__\nGenerate a new managed key pair.\n\nThe key pair is generated and stored by the key management facilities.\n\nIt may be used through its identifier, but the host may not allow it to be exported.\n\nThe function returns the `unsupported_feature` error code if key management facilities are not supported by the host,\nor `unsupported_algorithm` if a key cannot be created for the chosen algorithm.\n\nThe function may also return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nThis is also an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"keypair_generate_managed\") (param $key_manager $key_manager) (param $algorithm_type $algorithm_type) (param $algorithm string) (param $options $opt_options) (result $error $crypto_errno) (result $handle $keypair)) (;; __(optional)__\nReplace a managed key pair.\n\nThis function crates a new version of a managed key pair, by replacing `$kp_old` with `$kp_new`.\n\nIt does several things:\n\n- The key identifier for `$kp_new` is set to the one of `$kp_old`.\n- A new, unique version identifier is assigned to `$kp_new`. This version will be equivalent to using `$version_latest` until the key is replaced.\n- The `$kp_old` handle is closed.\n\nBoth keys must share the same algorithm and have compatible parameters. If this is not the case, `incompatible_keys` is returned.\n\nThe function may also return the `unsupported_feature` error code if key management facilities are not supported by the host,\nor if keys cannot be rotated.\n\nFinally, `prohibited_operation` can be returned if `$kp_new` wasn\'t created by the key manager, and the key manager prohibits imported keys.\n\nIf the operation succeeded, the new version is returned.\n\nThis is an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"keypair_replace_managed\") (param $key_manager $key_manager) (param $kp_old $keypair) (param $kp_new $keypair) (result $error $crypto_errno) (result $version $version)) (;; __(optional)__\nReturn the key pair identifier and version of a managed key pair.\n\nIf the key pair is not managed, `unsupported_feature` is returned instead.\n\nThis is an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"keypair_id\") (param $kp $keypair) (param $kp_id (@witx pointer u8)) (param $kp_id_max_len $size) (result $error $crypto_errno) (result $kp_id_len $size) (result $version $version)) (;; __(optional)__\nReturn a managed key pair from a key identifier.\n\n`kp_version` can be set to `version_latest` to retrieve the most recent version of a key pair.\n\nIf no key pair matching the provided information is found, `key_not_found` is returned instead.\n\nThis is an optional import, meaning that the function may not even exist.\n```\n ;) (@interface func (export \"keypair_from_id\") (param $key_manager $key_manager) (param $kp_id (@witx const_pointer u8)) (param $kp_id_len $size) (param $kp_version $version) (result $error $crypto_errno) (result $handle $keypair)) (;; Create a key pair from a public key and a secret key.\n ;) (@interface func (export \"keypair_from_pk_and_sk\") (param $publickey $publickey) (param $secretkey $secretkey) (result $error $crypto_errno) (result $handle $keypair)) (;; Export a key pair as the given encoding format.\n\nMay return `prohibited_operation` if this operation is denied or `unsupported_encoding` if the encoding is not supported.\n ;) (@interface func (export \"keypair_export\") (param $kp $keypair) (param $encoding $keypair_encoding) (result $error $crypto_errno) (result $encoded $array_output)) (;; Get the public key of a key pair.\n ;) (@interface func (export \"keypair_publickey\") (param $kp $keypair) (result $error $crypto_errno) (result $pk $publickey)) (;; Get the secret key of a key pair.\n ;) (@interface func (export \"keypair_secretkey\") (param $kp $keypair) (result $error $crypto_errno) (result $sk $secretkey)) (;; Destroy a key pair.\n\nThe host will automatically wipe traces of the secret key from memory.\n\nIf this is a managed key, the key will not be removed from persistent storage, and can be reconstructed later using the key identifier.\n ;) (@interface func (export \"keypair_close\") (param $kp $keypair) (result $error $crypto_errno)) (;; Import a public key.\n\nThe function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type.\n\nIt may also return `invalid_key` if the key doesn\'t appear to match the supplied algorithm.\n\nFinally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nExample usage:\n\n```rust\nlet pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?;\n```\n ;) (@interface func (export \"publickey_import\") (param $algorithm_type $algorithm_type) (param $algorithm string) (param $encoded (@witx const_pointer u8)) (param $encoded_len $size) (param $encoding $publickey_encoding) (result $error $crypto_errno) (result $pk $publickey)) (;; Export a public key as the given encoding format.\n\nMay return `unsupported_encoding` if the encoding is not supported.\n ;) (@interface func (export \"publickey_export\") (param $pk $publickey) (param $encoding $publickey_encoding) (result $error $crypto_errno) (result $encoded $array_output)) (;; Check that a public key is valid and in canonical form.\n\nThis function may perform stricter checks than those made during importation at the expense of additional CPU cycles.\n\nThe function returns `invalid_key` if the public key didn\'t pass the checks.\n ;) (@interface func (export \"publickey_verify\") (param $pk $publickey) (result $error $crypto_errno)) (;; Compute the public key for a secret key.\n ;) (@interface func (export \"publickey_from_secretkey\") (param $sk $secretkey) (result $error $crypto_errno) (result $pk $publickey)) (;; Destroy a public key.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"publickey_close\") (param $pk $publickey) (result $error $crypto_errno)) (;; Import a secret key.\n\nThe function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type.\n\nIt may also return `invalid_key` if the key doesn\'t appear to match the supplied algorithm.\n\nFinally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nExample usage:\n\n```rust\nlet pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?;\n```\n ;) (@interface func (export \"secretkey_import\") (param $algorithm_type $algorithm_type) (param $algorithm string) (param $encoded (@witx const_pointer u8)) (param $encoded_len $size) (param $encoding $secretkey_encoding) (result $error $crypto_errno) (result $sk $secretkey)) (;; Export a secret key as the given encoding format.\n\nMay return `unsupported_encoding` if the encoding is not supported.\n ;) (@interface func (export \"secretkey_export\") (param $sk $secretkey) (param $encoding $secretkey_encoding) (result $error $crypto_errno) (result $encoded $array_output)) (;; Destroy a secret key.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"secretkey_close\") (param $sk $secretkey) (result $error $crypto_errno)))\n(;; Digital signatures.\n ;) (module $wasi_ephemeral_crypto_signatures (import \"memory\" (memory)) (;; Export a signature.\n\nThis function exports a signature object using the specified encoding.\n\nMay return `unsupported_encoding` if the signature cannot be encoded into the given format.\n ;) (@interface func (export \"signature_export\") (param $signature $signature) (param $encoding $signature_encoding) (result $error $crypto_errno) (result $encoded $array_output)) (;; Create a signature object.\n\nThis object can be used along with a public key to verify an existing signature.\n\nIt 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.\n\nThe function may also return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nExample usage:\n\n```rust\nlet signature_handle = ctx.signature_import(\"ECDSA_P256_SHA256\", SignatureEncoding::DER, encoded)?;\n```\n ;) (@interface func (export \"signature_import\") (param $algorithm string) (param $encoded (@witx const_pointer u8)) (param $encoded_len $size) (param $encoding $signature_encoding) (result $error $crypto_errno) (result $signature $signature)) (;; Create a new state to collect data to compute a signature on.\n\nThis function allows data to be signed to be supplied in a streaming fashion.\n\nThe state is not closed and can be used after a signature has been computed, allowing incremental updates by calling `signature_state_update()` again afterwards.\n\nExample usage - signature creation\n\n```rust\nlet kp_handle = ctx.keypair_import(AlgorithmType::Signatures, \"Ed25519ph\", keypair, KeypairEncoding::Raw)?;\nlet state_handle = ctx.signature_state_open(kp_handle)?;\nctx.signature_state_update(state_handle, b\"message part 1\")?;\nctx.signature_state_update(state_handle, b\"message part 2\")?;\nlet sig_handle = ctx.signature_state_sign(state_handle)?;\nlet raw_sig = ctx.signature_export(sig_handle, SignatureEncoding::Raw)?;\n```\n ;) (@interface func (export \"signature_state_open\") (param $kp $signature_keypair) (result $error $crypto_errno) (result $state $signature_state)) (;; Absorb data into the signature state.\n\nThis function may return `unsupported_feature` is the selected algorithm doesn\'t support incremental updates.\n ;) (@interface func (export \"signature_state_update\") (param $state $signature_state) (param $input (@witx const_pointer u8)) (param $input_len $size) (result $error $crypto_errno)) (;; Compute a signature for all the data collected up to that point.\n\nThe function can be called multiple times for incremental signing.\n ;) (@interface func (export \"signature_state_sign\") (param $state $signature_state) (result $error $crypto_errno) (result $signature $array_output)) (;; Destroy a signature state.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n\nNote that closing a signature state doesn\'t close or invalidate the key pair object, that be reused for further signatures.\n ;) (@interface func (export \"signature_state_close\") (param $state $signature_state) (result $error $crypto_errno)) (;; Create a new state to collect data to verify a signature on.\n\nThis is the verification counterpart of `signature_state`.\n\nData can be injected using `signature_verification_state_update()`, and the state is not closed after a verification, allowing incremental verification.\n\nExample usage - signature verification:\n\n```rust\nlet pk_handle = ctx.publickey_import(AlgorithmType::Signatures, \"ECDSA_P256_SHA256\", encoded_pk, PublicKeyEncoding::CompressedSec)?;\nlet signature_handle = ctx.signature_import(AlgorithmType::Signatures, \"ECDSA_P256_SHA256\", encoded_sig, PublicKeyEncoding::Der)?;\nlet state_handle = ctx.signature_verification_state_open(pk_handle)?;\nctx.signature_verification_state_update(state_handle, \"message\")?;\nctx.signature_verification_state_verify(signature_handle)?;\n```\n ;) (@interface func (export \"signature_verification_state_open\") (param $kp $signature_publickey) (result $error $crypto_errno) (result $state $signature_verification_state)) (;; Absorb data into the signature verification state.\n\nThis function may return `unsupported_feature` is the selected algorithm doesn\'t support incremental updates.\n ;) (@interface func (export \"signature_verification_state_update\") (param $state $signature_verification_state) (param $input (@witx const_pointer u8)) (param $input_len $size) (result $error $crypto_errno)) (;; Check that the given signature is verifies for the data collected up to that point point.\n\nThe state is not closed and can absorb more data to allow for incremental verification.\n\nThe function returns `invalid_signature` if the signature doesn\'t appear to be valid.\n ;) (@interface func (export \"signature_verification_state_verify\") (param $state $signature_verification_state) (param $signature $signature) (result $error $crypto_errno)) (;; Destroy a signature verification state.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n\nNote that closing a signature state doesn\'t close or invalidate the public key object, that be reused for further verifications.\n ;) (@interface func (export \"signature_verification_state_close\") (param $state $signature_verification_state) (result $error $crypto_errno)) (;; Destroy a signature.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"signature_close\") (param $signature $signature) (result $error $crypto_errno)))\n(;; Symmetric operations.\n ;) (module $wasi_ephemeral_crypto_symmetric (import \"memory\" (memory)) (;; Generate a new symmetric key for a given algorithm.\n\n`options` can be `None` to use the default parameters, or an algoritm-specific set of parameters to override.\n\nThis function may return `unsupported_feature` if key generation is not supported by the host for the chosen algorithm, or `unsupported_algorithm` if the algorithm is not supported by the host.\n ;) (@interface func (export \"symmetric_key_generate\") (param $algorithm string) (param $options $opt_options) (result $error $crypto_errno) (result $handle $symmetric_key)) (;; Create a symmetric key from raw material.\n\nThe algorithm is internally stored along with the key, and trying to use the key with an operation expecting a different algorithm will return `invalid_key`.\n\nThe function may also return `unsupported_algorithm` if the algorithm is not supported by the host.\n ;) (@interface func (export \"symmetric_key_import\") (param $algorithm string) (param $raw (@witx const_pointer u8)) (param $raw_len $size) (result $error $crypto_errno) (result $handle $symmetric_key)) (;; Export a symmetric key as raw material.\n\nThis is mainly useful to export a managed key.\n\nMay return `prohibited_operation` if this operation is denied.\n ;) (@interface func (export \"symmetric_key_export\") (param $symmetric_key $symmetric_key) (result $error $crypto_errno) (result $encoded $array_output)) (;; Destroy a symmetric key.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"symmetric_key_close\") (param $symmetric_key $symmetric_key) (result $error $crypto_errno)) (;; __(optional)__\nGenerate a new managed symmetric key.\n\nThe key is generated and stored by the key management facilities.\n\nIt may be used through its identifier, but the host may not allow it to be exported.\n\nThe function returns the `unsupported_feature` error code if key management facilities are not supported by the host,\nor `unsupported_algorithm` if a key cannot be created for the chosen algorithm.\n\nThe function may also return `unsupported_algorithm` if the algorithm is not supported by the host.\n\nThis is also an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"symmetric_key_generate_managed\") (param $key_manager $key_manager) (param $algorithm string) (param $options $opt_options) (result $error $crypto_errno) (result $handle $symmetric_key)) (;; __(optional)__\nReplace a managed symmetric key.\n\nThis function crates a new version of a managed symmetric key, by replacing `$kp_old` with `$kp_new`.\n\nIt does several things:\n\n- The key identifier for `$symmetric_key_new` is set to the one of `$symmetric_key_old`.\n- A new, unique version identifier is assigned to `$kp_new`. This version will be equivalent to using `$version_latest` until the key is replaced.\n- The `$symmetric_key_old` handle is closed.\n\nBoth keys must share the same algorithm and have compatible parameters. If this is not the case, `incompatible_keys` is returned.\n\nThe function may also return the `unsupported_feature` error code if key management facilities are not supported by the host,\nor if keys cannot be rotated.\n\nFinally, `prohibited_operation` can be returned if `$symmetric_key_new` wasn\'t created by the key manager, and the key manager prohibits imported keys.\n\nIf the operation succeeded, the new version is returned.\n\nThis is an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"symmetric_key_replace_managed\") (param $key_manager $key_manager) (param $symmetric_key_old $symmetric_key) (param $symmetric_key_new $symmetric_key) (result $error $crypto_errno) (result $version $version)) (;; __(optional)__\nReturn the key identifier and version of a managed symmetric key.\n\nIf the key is not managed, `unsupported_feature` is returned instead.\n\nThis is an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"symmetric_key_id\") (param $symmetric_key $symmetric_key) (param $symmetric_key_id (@witx pointer u8)) (param $symmetric_key_id_max_len $size) (result $error $crypto_errno) (result $symmetric_key_id_len $size) (result $version $version)) (;; __(optional)__\nReturn a managed symmetric key from a key identifier.\n\n`kp_version` can be set to `version_latest` to retrieve the most recent version of a symmetric key.\n\nIf no key matching the provided information is found, `key_not_found` is returned instead.\n\nThis is an optional import, meaning that the function may not even exist.\n ;) (@interface func (export \"symmetric_key_from_id\") (param $key_manager $key_manager) (param $symmetric_key_id (@witx const_pointer u8)) (param $symmetric_key_id_len $size) (param $symmetric_key_version $version) (result $error $crypto_errno) (result $handle $symmetric_key)) (;; Create a new state to aborb and produce data using symmetric operations.\n\nThe state remains valid after every operation in order to support incremental updates.\n\nThe function has two optional parameters: a key and an options set.\n\nIt will fail with a `key_not_supported` error code if a key was provided but the chosen algorithm doesn\'t natively support keying.\n\nOn the other hand, if a key is required, but was not provided, a `key_required` error will be thrown.\n\nSome algorithms may require additional parameters. They have to be supplied as an options set:\n\n```rust\nlet options_handle = ctx.options_open()?;\nctx.options_set(\"context\", b\"My application\")?;\nctx.options_set_u64(\"fanout\", 16)?;\nlet state_handle = ctx.symmetric_state_open(\"BLAKE2b-512\", None, Some(options_handle))?;\n```\n\nIf some parameters are mandatory but were not set, the `parameters_missing` error code will be returned.\n\nA notable exception is the `nonce` parameter, that is common to most AEAD constructions.\n\nIf a nonce is required but was not supplied:\n\n- If it is safe to do so, the host will automatically generate a nonce. This is true for nonces that are large enough to be randomly generated, or if the host is able to maintain a global counter.\n- If not, the function will fail and return the dedicated `nonce_required` error code.\n\nA nonce that was automatically generated can be retrieved after the function returns with `symmetric_state_get(state_handle, \"nonce\")`.\n\n**Sample usage patterns:**\n\n- **Hashing**\n\n```rust\nlet mut out = [0u8; 64];\nlet state_handle = ctx.symmetric_state_open(\"SHAKE-128\", None, None)?;\nctx.symmetric_state_absorb(state_handle, b\"data\")?;\nctx.symmetric_state_absorb(state_handle, b\"more_data\")?;\nctx.symmetric_state_squeeze(state_handle, &mut out)?;\n```\n\n- **MAC**\n\n```rust\nlet mut raw_tag = [0u8; 64];\nlet key_handle = ctx.symmetric_key_import(\"HMAC/SHA-512\", b\"key\")?;\nlet state_handle = ctx.symmetric_state_open(\"HMAC/SHA-512\", Some(key_handle), None)?;\nctx.symmetric_state_absorb(state_handle, b\"data\")?;\nctx.symmetric_state_absorb(state_handle, b\"more_data\")?;\nlet computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;\nctx.symmetric_tag_pull(computed_tag_handle, &mut raw_tag)?;\n```\n\nVerification:\n\n```rust\nlet state_handle = ctx.symmetric_state_open(\"HMAC/SHA-512\", Some(key_handle), None)?;\nctx.symmetric_state_absorb(state_handle, b\"data\")?;\nctx.symmetric_state_absorb(state_handle, b\"more_data\")?;\nlet computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;\nctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?;\n```\n\n- **Tuple hashing**\n\n```rust\nlet mut out = [0u8; 64];\nlet state_handle = ctx.symmetric_state_open(\"TupleHashXOF256\", None, None)?;\nctx.symmetric_state_absorb(state_handle, b\"value 1\")?;\nctx.symmetric_state_absorb(state_handle, b\"value 2\")?;\nctx.symmetric_state_absorb(state_handle, b\"value 3\")?;\nctx.symmetric_state_squeeze(state_handle, &mut out)?;\n```\nUnlike MACs and regular hash functions, inputs are domain separated instead of being concatenated.\n\n- **Key derivation using extract-and-expand**\n\nExtract:\n\n```rust\nlet mut prk = vec![0u8; 64];\nlet key_handle = ctx.symmetric_key_import(\"HKDF-EXTRACT/SHA-512\", b\"key\")?;\nlet state_handle = ctx.symmetric_state_open(\"HKDF-EXTRACT/SHA-512\", Some(key_handle), None)?;\nctx.symmetric_state_absorb(state_handle, b\"salt\")?;\nlet prk_handle = ctx.symmetric_state_squeeze_key(state_handle, \"HKDF-EXPAND/SHA-512\")?;\n```\n\nExpand:\n\n```rust\nlet mut subkey = vec![0u8; 32];\nlet state_handle = ctx.symmetric_state_open(\"HKDF-EXPAND/SHA-512\", Some(prk_handle), None)?;\nctx.symmetric_state_absorb(state_handle, b\"info\")?;\nctx.symmetric_state_squeeze(state_handle, &mut subkey)?;\n```\n\n- **Key derivation using a XOF**\n\n```rust\nlet mut subkey1 = vec![0u8; 32];\nlet mut subkey2 = vec![0u8; 32];\nlet key_handle = ctx.symmetric_key_import(\"BLAKE3\", b\"key\")?;\nlet state_handle = ctx.symmetric_state_open(\"BLAKE3\", Some(key_handle), None)?;\nctx.symmetric_absorb(state_handle, b\"context\")?;\nctx.squeeze(state_handle, &mut subkey1)?;\nctx.squeeze(state_handle, &mut subkey2)?;\n```\n\n- **Password hashing**\n\n```rust\nlet mut memory = vec![0u8; 1_000_000_000];\nlet options_handle = ctx.symmetric_options_open()?;\nctx.symmetric_options_set_guest_buffer(options_handle, \"memory\", &mut memory)?;\nctx.symmetric_options_set_u64(options_handle, \"opslimit\", 5)?;\nctx.symmetric_options_set_u64(options_handle, \"parallelism\", 8)?;\n\nlet state_handle = ctx.symmetric_state_open(\"ARGON2-ID-13\", None, Some(options))?;\nctx.symmtric_state_absorb(state_handle, b\"password\")?;\n\nlet pw_str_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;\nlet mut pw_str = vec![0u8; ctx.symmetric_tag_len(pw_str_handle)?];\nctx.symmetric_tag_pull(pw_str_handle, &mut pw_str)?;\n```\n\n- **AEAD encryption with an explicit nonce**\n\n```rust\nlet key_handle = ctx.symmetric_key_generate(\"AES-256-GCM\", None)?;\nlet message = b\"test\";\n\nlet options_handle = ctx.symmetric_options_open()?;\nctx.symmetric_options_set(options_handle, \"nonce\", nonce)?;\n\nlet state_handle = ctx.symmetric_state_open(\"AES-256-GCM\", Some(key_handle), Some(options_handle))?;\nlet mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?];\nctx.symmetric_state_absorb(state_handle, \"additional data\")?;\nctx.symmetric_state_encrypt(state_handle, &mut ciphertext, message)?;\n```\n\n- **AEAD encryption with automatic nonce generation**\n\n```rust\nlet key_handle = ctx.symmetric_key_generate(\"AES-256-GCM-SIV\", None)?;\nlet message = b\"test\";\nlet mut nonce = [0u8; 24];\n\nlet state_handle = ctx.symmetric_state_open(\"AES-256-GCM-SIV\", Some(key_handle), None)?;\n\nlet nonce_handle = ctx.symmetric_state_options_get(state_handle, \"nonce\")?;\nctx.array_output_pull(nonce_handle, &mut nonce)?;\n\nlet mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?];\nctx.symmetric_state_absorb(state_handle, \"additional data\")?;\nctx.symmetric_state_encrypt(state_handle, &mut ciphertext, message)?;\n```\n\n- **Session authenticated modes**\n\n```rust\nlet mut out = [0u8; 16];\nlet mut out2 = [0u8; 16];\nlet mut ciphertext = [0u8; 20];\nlet key_handle = ctx.symmetric_key_generate(\"Xoodyak-256\", None)?;\nlet state_handle = ctx.symmetric_state_open(\"Xoodyak-256\", Some(key_handle), None)?;\nctx.symmetric_state_absorb(state_handle, b\"data\")?;\nctx.symmetric_state_encrypt(state_handle, &mut ciphertext, b\"abcd\")?;\nctx.symmetric_state_absorb(state_handle, b\"more data\")?;\nctx.symmetric_state_squeeze(state_handle, &mut out)?;\nctx.symmetric_state_squeeze(state_handle, &mut out2)?;\nctx.symmetric_state_ratchet(state_handle)?;\nctx.symmetric_state_absorb(state_handle, b\"more data\")?;\nlet next_key_handle = ctx.symmetric_state_squeeze_key(state_handle, \"Xoodyak-256\")?;\n// ...\n```\n ;) (@interface func (export \"symmetric_state_open\") (param $algorithm string) (param $key $opt_symmetric_key) (param $options $opt_options) (result $error $crypto_errno) (result $symmetric_state $symmetric_state)) (;; Retrieve a parameter from the current state.\n\nIn particular, `symmetric_state_options_get(\"nonce\")` can be used to get a nonce that as automatically generated.\n\nThe function may return `options_not_set` if an option was not set, which is different from an empty value.\n\nIt may also return `unsupported_option` if the option doesn\'t exist for the chosen algorithm.\n ;) (@interface func (export \"symmetric_state_options_get\") (param $handle $symmetric_state) (param $name string) (param $value (@witx pointer u8)) (param $value_max_len $size) (result $error $crypto_errno) (result $value_len $size)) (;; Retrieve an integer parameter from the current state.\n\nIn particular, `symmetric_state_options_get(\"nonce\")` can be used to get a nonce that as automatically generated.\n\nThe function may return `options_not_set` if an option was not set.\n\nIt may also return `unsupported_option` if the option doesn\'t exist for the chosen algorithm.\n ;) (@interface func (export \"symmetric_state_options_get_u64\") (param $handle $symmetric_state) (param $name string) (result $error $crypto_errno) (result $value u64)) (;; Destroy a symmetric state.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"symmetric_state_close\") (param $handle $symmetric_state) (result $error $crypto_errno)) (;; Absorb data into the state.\n\n- **Hash functions:** adds data to be hashed.\n- **MAC functions:** adds data to be authenticated.\n- **Tuplehash-like constructions:** adds a new tuple to the state.\n- **Key derivation functions:** adds to the IKM or to the subkey information.\n- **AEAD constructions:** adds additional data to be authenticated.\n- **Stateful hash objects, permutation-based constructions:** absorbs.\n\nIf the chosen algorithm doesn\'t accept input data, the `invalid_operation` error code is returned.\n\nIf too much data has been fed for the algorithm, `overflow` may be thrown.\n ;) (@interface func (export \"symmetric_state_absorb\") (param $handle $symmetric_state) (param $data (@witx const_pointer u8)) (param $data_len $size) (result $error $crypto_errno)) (;; Squeeze bytes from the state.\n\n- **Hash functions:** this tries to output an `out_len` bytes digest from the absorbed data. The hash function output will be truncated if necessary. If the requested size is too large, the `invalid_len` error code is returned.\n- **Key derivation functions:** : outputs an arbitrary-long derived key.\n- **RNGs, DRBGs, stream ciphers:**: outputs arbitrary-long data.\n- **Stateful hash objects, permutation-based constructions:** squeeze.\n\nOther kinds of algorithms may return `invalid_operation` instead.\n\nFor password-stretching functions, the function may return `in_progress`.\nIn that case, the guest should retry with the same parameters until the function completes.\n ;) (@interface func (export \"symmetric_state_squeeze\") (param $handle $symmetric_state) (param $out (@witx pointer u8)) (param $out_len $size) (result $error $crypto_errno)) (;; Compute and return a tag for all the data injected into the state so far.\n\n- **MAC functions**: returns a tag authenticating the absorbed data.\n- **Tuplehash-like constructions:** returns a tag authenticating all the absorbed tuples.\n- **Password-hashing functions:** returns a standard string containing all the required parameters for password verification.\n\nOther kinds of algorithms may return `invalid_operation` instead.\n\nFor password-stretching functions, the function may return `in_progress`.\nIn that case, the guest should retry with the same parameters until the function completes.\n ;) (@interface func (export \"symmetric_state_squeeze_tag\") (param $handle $symmetric_state) (result $error $crypto_errno) (result $symmetric_tag $symmetric_tag)) (;; Use the current state to produce a key for a target algorithm.\n\nFor extract-then-expand constructions, this returns the PRK.\nFor session-base authentication encryption, this returns a key that can be used to resume a session without storing a nonce.\n\n`invalid_operation` is returned for algorithms not supporting this operation.\n ;) (@interface func (export \"symmetric_state_squeeze_key\") (param $handle $symmetric_state) (param $alg_str string) (result $error $crypto_errno) (result $symmetric_key $symmetric_key)) (;; Return the maximum length of an authentication tag for the current algorithm.\n\nThis allows guests to compute the size required to store a ciphertext along with its authentication tag.\n\nThe returned length may include the encryption mode\'s padding requirements in addition to the actual tag.\n\nFor an encryption operation, the size of the output buffer should be `input_len + symmetric_state_max_tag_len()`.\n\nFor a decryption operation, the size of the buffer that will store the decrypted data can be reduced to `ciphertext_len - symmetric_state_max_tag_len()` only if the algorithm is known to have a fixed tag length.\n ;) (@interface func (export \"symmetric_state_max_tag_len\") (param $handle $symmetric_state) (result $error $crypto_errno) (result $len $size)) (;; Encrypt data with an attached tag.\n\n- **Stream cipher:** adds the input to the stream cipher output. `out_len` and `data_len` can be equal, as no authentication tags will be added.\n- **AEAD:** encrypts `data` into `out`, including the authentication tag to the output. Additional data must have been previously absorbed using `symmetric_state_absorb()`. The `symmetric_state_max_tag_len()` function can be used to retrieve the overhead of adding the tag, as well as padding if necessary.\n- **SHOE, Xoodyak, Strobe:** encrypts data, squeezes a tag and appends it to the output.\n\nIf `out` and `data` are the same address, encryption may happen in-place.\n\nThe function returns the actual size of the ciphertext along with the tag.\n\n`invalid_operation` is returned for algorithms not supporting encryption.\n ;) (@interface func (export \"symmetric_state_encrypt\") (param $handle $symmetric_state) (param $out (@witx pointer u8)) (param $out_len $size) (param $data (@witx const_pointer u8)) (param $data_len $size) (result $error $crypto_errno) (result $actual_out_len $size)) (;; Encrypt data, with a detached tag.\n\n- **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags.\n- **AEAD:** encrypts `data` into `out` and returns the tag separately. Additional data must have been previously absorbed using `symmetric_state_absorb()`. The output and input buffers must be of the same length.\n- **SHOE, Xoodyak, Strobe:** encrypts data and squeezes a tag.\n\nIf `out` and `data` are the same address, encryption may happen in-place.\n\nThe function returns the tag.\n\n`invalid_operation` is returned for algorithms not supporting encryption.\n ;) (@interface func (export \"symmetric_state_encrypt_detached\") (param $handle $symmetric_state) (param $out (@witx pointer u8)) (param $out_len $size) (param $data (@witx const_pointer u8)) (param $data_len $size) (result $error $crypto_errno) (result $symmetric_tag $symmetric_tag)) (;; - **Stream cipher:** adds the input to the stream cipher output. `out_len` and `data_len` can be equal, as no authentication tags will be added.\n- **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`.\n- **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the one that was appended to the ciphertext.\n\nIf `out` and `data` are the same address, decryption may happen in-place.\n\nThe function returns the actual size of the decrypted message.\n\n`invalid_tag` is returned if the tag didn\'t verify.\n\n`invalid_operation` is returned for algorithms not supporting encryption.\n ;) (@interface func (export \"symmetric_state_decrypt\") (param $handle $symmetric_state) (param $out (@witx pointer u8)) (param $out_len $size) (param $data (@witx const_pointer u8)) (param $data_len $size) (result $error $crypto_errno) (result $actual_out_len $size)) (;; - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags.\n- **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`.\n- **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the expected one.\n\n`raw_tag` is the expected tag, as raw bytes.\n\n`out` and `data` be must have the same length.\nIf they also share the same address, decryption may happen in-place.\n\nThe function returns the actual size of the decrypted message.\n\n`invalid_tag` is returned if the tag verification failed.\n\n`invalid_operation` is returned for algorithms not supporting encryption.\n ;) (@interface func (export \"symmetric_state_decrypt_detached\") (param $handle $symmetric_state) (param $out (@witx pointer u8)) (param $out_len $size) (param $data (@witx const_pointer u8)) (param $data_len $size) (param $raw_tag (@witx const_pointer u8)) (param $raw_tag_len $size) (result $error $crypto_errno) (result $actual_out_len $size)) (;; Make it impossible to recover the previous state.\n\nThis operation is supported by some systems keeping a rolling state over an entire session, for forward security.\n\n`invalid_operation` is returned for algorithms not supporting ratcheting.\n ;) (@interface func (export \"symmetric_state_ratchet\") (param $handle $symmetric_state) (result $error $crypto_errno)) (;; Return the length of an authentication tag.\n\nThis function can be used by a guest to allocate the correct buffer size to copy a computed authentication tag.\n ;) (@interface func (export \"symmetric_tag_len\") (param $symmetric_tag $symmetric_tag) (result $error $crypto_errno) (result $len $size)) (;; Copy an authentication tag into a guest-allocated buffer.\n\nThe handle automatically becomes invalid after this operation. Manually closing it is not required.\n\nExample usage:\n\n```rust\nlet mut raw_tag = [0u8; 16];\nctx.symmetric_tag_pull(raw_tag_handle, &mut raw_tag)?;\n```\n\nThe function returns `overflow` if the supplied buffer is too small to copy the tag.\n\nOtherwise, it returns the number of bytes that have been copied.\n ;) (@interface func (export \"symmetric_tag_pull\") (param $symmetric_tag $symmetric_tag) (param $buf (@witx pointer u8)) (param $buf_len $size) (result $error $crypto_errno) (result $len $size)) (;; Verify that a computed authentication tag matches the expected value, in constant-time.\n\nThe expected tag must be provided as a raw byte string.\n\nThe function returns `invalid_tag` if the tags don\'t match.\n\nExample usage:\n\n```rust\nlet key_handle = ctx.symmetric_key_import(\"HMAC/SHA-256\", b\"key\")?;\nlet state_handle = ctx.symmetric_state_open(\"HMAC/SHA-256\", Some(key_handle), None)?;\nctx.symmetric_state_absorb(state_handle, b\"data\")?;\nlet computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;\nctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?;\n```\n ;) (@interface func (export \"symmetric_tag_verify\") (param $symmetric_tag $symmetric_tag) (param $expected_raw_tag_ptr (@witx const_pointer u8)) (param $expected_raw_tag_len $size) (result $error $crypto_errno)) (;; Explicitly destroy an unused authentication tag.\n\nThis is usually not necessary, as `symmetric_tag_pull()` automatically closes a tag after it has been copied.\n\nObjects are reference counted. It is safe to close an object immediately after the last function needing it is called.\n ;) (@interface func (export \"symmetric_tag_close\") (param $symmetric_tag $symmetric_tag) (result $error $crypto_errno)))\n(;; Key exchange operations.\n ;) (module $wasi_ephemeral_crypto_kx (import \"memory\" (memory)) (;; Perform a simple Diffie-Hellman key exchange.\n\nBoth keys must be of the same type, or else the `$crypto_errno.incompatible_keys` error is returned.\nThe algorithm also has to support this kind of key exchange. If this is not the case, the `$crypto_errno.invalid_operation` error is returned.\n\nOtherwide, a raw shared key is returned, and can be imported as a symmetric key.\n```\n ;) (@interface func (export \"kx_dh\") (param $pk $publickey) (param $sk $secretkey) (result $error $crypto_errno) (result $shared_secret $array_output)) (;; Create a shared secret and encrypt it for the given public key.\n\nThis operation is only compatible with specific algorithms.\nIf a selected algorithm doesn\'t support it, `$crypto_errno.invalid_operation` is returned.\n\nOn success, both the shared secret and its encrypted version are returned.\n ;) (@interface func (export \"kx_encapsulate\") (param $pk $publickey) (result $error $crypto_errno) (result $secret $array_output) (result $encapsulated_secret $array_output)) (;; Decapsulate an encapsulated secret crated with `kx_encapsulate`\n\nReturn the secret, or `$crypto_errno.verification_failed` on error.\n ;) (@interface func (export \"kx_decapsulate\") (param $sk $secretkey) (param $encapsulated_secret (@witx const_pointer u8)) (param $encapsulated_secret_len $size) (result $error $crypto_errno) (result $secret $array_output)))\n";