From 6866946c23e8521e3f728b71335a9f5206cb630d Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Mon, 20 Apr 2026 16:10:43 +0200 Subject: [PATCH 01/15] feat: add transpiled wit --- ...asi_ephemeral_crypto_asymmetric_common.wit | 451 ++++++++++ wit/wasi_ephemeral_crypto_common.wit | 364 ++++++++ ...wasi_ephemeral_crypto_external_secrets.wit | 343 ++++++++ wit/wasi_ephemeral_crypto_kx.wit | 296 +++++++ wit/wasi_ephemeral_crypto_signatures.wit | 370 +++++++++ ...wasi_ephemeral_crypto_signatures_batch.wit | 223 +++++ wit/wasi_ephemeral_crypto_symmetric.wit | 778 ++++++++++++++++++ wit/wasi_ephemeral_crypto_symmetric_batch.wit | 480 +++++++++++ 8 files changed, 3305 insertions(+) create mode 100644 wit/wasi_ephemeral_crypto_asymmetric_common.wit create mode 100644 wit/wasi_ephemeral_crypto_common.wit create mode 100644 wit/wasi_ephemeral_crypto_external_secrets.wit create mode 100644 wit/wasi_ephemeral_crypto_kx.wit create mode 100644 wit/wasi_ephemeral_crypto_signatures.wit create mode 100644 wit/wasi_ephemeral_crypto_signatures_batch.wit create mode 100644 wit/wasi_ephemeral_crypto_symmetric.wit create mode 100644 wit/wasi_ephemeral_crypto_symmetric_batch.wit diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit new file mode 100644 index 0000000..08a80cc --- /dev/null +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -0,0 +1,451 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-asymmetric-common { + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + /// 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: + /// + /// ```rust + /// let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?; + /// ``` + keypair-generate: func(algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; + /// 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: + /// + /// ```rust + /// let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?; + /// ``` + /// + /// + /// TODO: Fix 'encoded'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + keypair-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: keypair-encoding) -> result; + /// __(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-generate-managed: func(secrets-manager: secrets-manager, algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; + /// __(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. + /// + /// + /// TODO: Fix 'kp-id'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> result<_, crypto-errno>; + /// __(optional)__ + /// Replace a managed key pair. + /// + /// This function creates 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-replace-managed: func(secrets-manager: secrets-manager, kp-old: keypair, kp-new: keypair) -> result; + /// __(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. + /// + /// + /// TODO: Fix 'kp-id'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'error'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("version"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U64)), docs: "Version of a managed key.\n\nA version can be an arbitrary `u64` integer, with the exception of some reserved values.\n" }), docs: "" }] })). + /// Reason: Unimplemented logic + keypair-id: func(kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-version--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u64--docs--version-of-a-managed-key-n-na-version-can-be-an-arbitrary-u64-integer-with-the-exception-of-some-reserved-values-n---docs; + /// __(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. + /// + /// + /// TODO: Fix 'kp-id'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + keypair-from-id: func(secrets-manager: secrets-manager, kp-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, kp-id-len: size, kp-version: version) -> result; + /// Create a key pair from a public key and a secret key. + keypair-from-pk-and-sk: func(publickey: publickey, secretkey: secretkey) -> result; + /// 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-export: func(kp: keypair, encoding: keypair-encoding) -> result; + /// Get the public key of a key pair. + keypair-publickey: func(kp: keypair) -> result; + /// Get the secret key of a key pair. + keypair-secretkey: func(kp: keypair) -> result; + /// 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. + keypair-close: func(kp: keypair) -> result<_, crypto-errno>; + /// 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: + /// + /// ```rust + /// let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?; + /// ``` + /// + /// + /// TODO: Fix 'encoded'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + publickey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: publickey-encoding) -> result; + /// Export a public key as the given encoding format. + /// + /// May return `unsupported_encoding` if the encoding is not supported. + publickey-export: func(pk: publickey, encoding: publickey-encoding) -> result; + /// 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-verify: func(pk: publickey) -> result<_, crypto-errno>; + /// Compute the public key for a secret key. + publickey-from-secretkey: func(sk: secretkey) -> result; + /// Destroy a public key. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + publickey-close: func(pk: publickey) -> result<_, crypto-errno>; + /// 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: + /// + /// ```rust + /// let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?; + /// ``` + /// + /// + /// TODO: Fix 'encoded'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + secretkey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: secretkey-encoding) -> result; + /// Export a secret key as the given encoding format. + /// + /// May return `unsupported_encoding` if the encoding is not supported. + secretkey-export: func(sk: secretkey, encoding: secretkey-encoding) -> result; + /// Destroy a secret key. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + secretkey-close: func(sk: secretkey) -> result<_, crypto-errno>; +} diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit new file mode 100644 index 0000000..eea9e71 --- /dev/null +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -0,0 +1,364 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-common { + /// TODO: Constant + resource version { + /// Original Value: 18374686479671623680 + unspecified: func() -> u64; + /// Original Value: 18374686479671623681 + latest: func() -> u64; + /// Original Value: 18374686479671623682 + all: func() -> u64; + } + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + /// Create a new object to set non-default options. + /// + /// Example usage: + /// + /// ```rust + /// let options_handle = options_open(AlgorithmType::Symmetric)?; + /// options_set(options_handle, "context", context)?; + /// options_set_u64(options_handle, "threads", 4)?; + /// let state = symmetric_state_open("BLAKE3", None, Some(options_handle))?; + /// options_close(options_handle)?; + /// ``` + options-open: func(algorithm-type: algorithm-type) -> result; + /// Destroy an options object. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + options-close: func(handle: options) -> result<_, crypto-errno>; + /// Set or update an option. + /// + /// This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. + /// + /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. + /// + /// + /// TODO: Fix 'value'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + options-set: func(handle: options, name: string, value: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, value-len: size) -> result<_, crypto-errno>; + /// Set or update an integer option. + /// + /// This is used to set algorithm-specific parameters. + /// + /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. + options-set-u64: func(handle: options, name: string, value: u64) -> result<_, crypto-errno>; + /// Set or update a guest-allocated memory that the host can use or return data into. + /// + /// This is for example used to set the scratch buffer required by memory-hard functions. + /// + /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. + /// + /// + /// TODO: Fix 'buffer'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + options-set-guest-buffer: func(handle: options, name: string, buffer: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buffer-len: size) -> result<_, crypto-errno>; + /// Return the length of an `array_output` object. + /// + /// This allows a guest to allocate a buffer of the correct size in order to copy the output of a function returning this object type. + array-output-len: func(array-output: array-output) -> result; + /// Copy the content of an `array_output` object into an application-allocated buffer. + /// + /// Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. + /// + /// The 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()`. + /// + /// The handle is automatically closed after all the data has been consumed. + /// + /// Example usage: + /// + /// ```rust + /// let len = array_output_len(output_handle)?; + /// let mut out = vec![0u8; len]; + /// array_output_pull(output_handle, &mut out)?; + /// ``` + /// + /// + /// TODO: Fix 'buf'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + array-output-pull: func(array-output: array-output, buf: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buf-len: size) -> result; + /// __(optional)__ + /// Create a context to use a secrets manager. + /// + /// The set of required and supported options is defined by the host. + /// + /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. + /// This is also an optional import, meaning that the function may not even exist. + secrets-manager-open: func(options: opt-options) -> result; + /// __(optional)__ + /// Destroy a secrets manager context. + /// + /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. + /// This is also an optional import, meaning that the function may not even exist. + secrets-manager-close: func(secrets-manager: secrets-manager) -> result<_, crypto-errno>; + /// __(optional)__ + /// Invalidate a managed key or key pair given an identifier and a version. + /// + /// This asks the secrets manager to delete or revoke a stored key, a specific version of a key. + /// + /// `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. + /// + /// 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 key. + /// + /// This is an optional import, meaning that the function may not even exist. + /// + /// + /// TODO: Fix 'key-id'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + secrets-manager-invalidate: func(secrets-manager: secrets-manager, key-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, key-id-len: size, key-version: version) -> result<_, crypto-errno>; +} diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit new file mode 100644 index 0000000..47a4a8d --- /dev/null +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -0,0 +1,343 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-external-secrets { + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + /// 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 output buffer is too small, `$overflow` is returned. + /// + /// If this function is not supported by the host the `$unsupported_feature` error is returned. + /// + /// + /// TODO: Fix 'secret'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'secret-id'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + external-secret-store: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, secret-id-max-len: size) -> result<_, crypto-errno>; + /// Replace a managed external secret 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. + /// + /// + /// TODO: Fix 'secret'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'secret-id'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + external-secret-replace: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size) -> result; + /// 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. + /// + /// + /// TODO: Fix 'secret-id'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + external-secret-from-id: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size, secret-version: version) -> result; + /// 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. + /// + /// + /// TODO: Fix 'secret-id'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + external-secret-invalidate: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size, secret-version: version) -> result<_, crypto-errno>; + /// 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. + /// + /// + /// TODO: Fix 'secret'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp) -> result; + /// 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. + /// + /// + /// TODO: Fix 'encrypted-secret'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + external-secret-decapsulate: func(secrets-manager: secrets-manager, encrypted-secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encrypted-secret-len: size) -> result; +} diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit new file mode 100644 index 0000000..2837e01 --- /dev/null +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -0,0 +1,296 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-kx { + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + /// `$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`. + type kx-keypair = keypair; + /// `$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`. + type kx-publickey = publickey; + /// `$kx_secretkey` is just an alias for `$secretkey` + /// + /// However, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkey`, with additional methods such as `dh`. + type kx-secretkey = secretkey; + /// 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. + /// + /// Otherwise, a raw shared key is returned, and can be imported as a symmetric key. + kx-dh: func(pk: publickey, sk: secretkey) -> result; + /// 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. + /// + /// + /// TODO: Fix 'error'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("array_output"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("array_output"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }] })). + /// Reason: Unimplemented logic + kx-encapsulate: func(pk: publickey) -> todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-array-output--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-array-output--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs; + /// Decapsulate an encapsulated secret created with `kx_encapsulate` + /// + /// Return the secret, or `$crypto_errno.verification_failed` on error. + /// + /// + /// TODO: Fix 'encapsulated-secret'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + kx-decapsulate: func(sk: secretkey, encapsulated-secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encapsulated-secret-len: size) -> result; +} diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit new file mode 100644 index 0000000..9b676eb --- /dev/null +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -0,0 +1,370 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-signatures { + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + /// `$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`. + type signature-keypair = keypair; + /// `$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`. + type signature-publickey = publickey; + /// `$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`. + type signature-secretkey = secretkey; + /// 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-export: func(signature: signature, encoding: signature-encoding) -> result; + /// 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: + /// + /// ```rust + /// let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", SignatureEncoding::DER, encoded)?; + /// ``` + /// + /// + /// TODO: Fix 'encoded'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + signature-import: func(algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: signature-encoding) -> result; + /// 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 + /// + /// ```rust + /// 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-open: func(kp: signature-keypair) -> result; + /// Absorb data into the signature state. + /// + /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. + /// + /// + /// TODO: Fix 'input'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + signature-state-update: func(state: signature-state, input: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + /// Compute a signature for all the data collected up to that point. + /// + /// The function can be called multiple times for incremental signing. + signature-state-sign: func(state: signature-state) -> result; + /// 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 can be reused for further signatures. + signature-state-close: func(state: signature-state) -> result<_, crypto-errno>; + /// 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: + /// + /// ```rust + /// let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_pk, PublicKeyEncoding::Sec)?; + /// let signature_handle = ctx.signature_import("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(state_handle, signature_handle)?; + /// ``` + signature-verification-state-open: func(kp: signature-publickey) -> result; + /// Absorb data into the signature verification state. + /// + /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. + /// + /// + /// TODO: Fix 'input'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + signature-verification-state-update: func(state: signature-verification-state, input: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + /// Check that the given signature verifies for the data collected up to that 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-verify: func(state: signature-verification-state, signature: signature) -> result<_, crypto-errno>; + /// 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 can be reused for further verifications. + signature-verification-state-close: func(state: signature-verification-state) -> result<_, crypto-errno>; + /// Destroy a signature. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + signature-close: func(signature: signature) -> result<_, crypto-errno>; +} diff --git a/wit/wasi_ephemeral_crypto_signatures_batch.wit b/wit/wasi_ephemeral_crypto_signatures_batch.wit new file mode 100644 index 0000000..752d032 --- /dev/null +++ b/wit/wasi_ephemeral_crypto_signatures_batch.wit @@ -0,0 +1,223 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-signatures-batch { + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// 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. + type array-output = handle; + /// A signature. + type signature = 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. + type signature-state = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = handle; + type temp = todo-from-witx-namedtype--name-id-signature-sign-result--module-moduleid-witx-wasi-ephemeral-crypto-signatures-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-array-output--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--the-result-of-a-signature-sign-operation-a-pair-of-the-signature-and-an-error-code-n; + /// A list of signature_sign results. + type signature-results = list; + type temp = todo-from-witx-namedtype--name-id-signature-verification-input--module-moduleid-witx-wasi-ephemeral-crypto-signatures-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-signature-verification-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--a-state-to-absorb-signed-data-to-be-verified-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-signature--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--a-signature-n---docs-------docs--a-tuple-of-a-signature-verification-state-and-the-signature-to-verify-n-nused-for-grouping-signature-verification-state-to-be-verified-with-the-signature-to-verify-nused-with-batch-signature-state-verify--n; + type signature-verification-results = list; + /// Compute a batch of signatures. + /// + /// This is a batch version of the signature_state_sign operation and is an extension of the wasi_ephemeral_crypto_signatures module. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result of each operation in the batch + /// is a pair of a $crypto_errno error code and a signature. The error code + /// indicates if that operation succeeded or failed. The signature is only + /// valid if the error code indicates success. + /// + /// Example usage: + /// + /// ```rust + /// let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; + /// + /// let mut state_handles = Vec::new(); + /// + /// let state_handle = signature_state_open(kp_handle)?; + /// signature_state_update(state_handle, b"message part 1")?; + /// signature_state_update(state_handle, b"message part 2")?; + /// state_handles.push(state_handle); + /// + /// let state_handle = signature_state_open(kp_handle)?; + /// signature_state_update(state_handle, b"message part 1")?; + /// signature_state_update(state_handle, b"message part 2")?; + /// state_handles.push(state_handle); + /// + /// let sig_handles = batch_signature_state_sign(state_handles)?; + /// + /// let raw_sig1 = signature_export(sig_handle[0], SignatureEncoding::Raw)?; + /// let raw_sig2 = signature_export(sig_handle[1], SignatureEncoding::Raw)?; + /// ``` + batch-signature-state-sign: func(states: list) -> result; + /// Verify a batch of signatures. + /// + /// This is a batch version of the signature_state_verify operation and is + /// an extension of the wasi_ephemeral_crypto_signatures module. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed (`success`) or if the batch could + /// not be processed. + /// + /// Batch processing failure cases are: + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, a list of verification results is produced. + /// Each entry in the input list has a corresponding error state returned + /// in the verification results list to indicate if the verification + /// succeeded or encountered an error. + /// + /// Example usage: + /// + /// ```rust + /// let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; + /// + /// let mut batch = Vec::new(); + /// + /// let state_handle = signature_verification_state_open(kp_handle)?; + /// signature_verification_state_update(state_handle, b"message part 1")?; + /// signature_verification_state_update(state_handle, b"message part 2")?; + /// state_handles.push((state_handle, signature1)); + /// + /// let state_handle = signature_verification_state_open(kp_handle)?; + /// signature_verification_state_update(state_handle, b"message part 1")?; + /// signature_verification_state_update(state_handle, b"message part 2")?; + /// state_handles.push((state_handle, signature2)); + /// + /// let results = batch_signature_state_verify(state_handles)?; + /// ``` + batch-signature-state-verify: func(states: list) -> result; +} diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit new file mode 100644 index 0000000..4aa870f --- /dev/null +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -0,0 +1,778 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-symmetric { + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + /// Generate a new symmetric key for a given algorithm. + /// + /// `options` can be `None` to use the default parameters, or an algorithm-specific set of parameters to override. + /// + /// This 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. + symmetric-key-generate: func(algorithm: string, options: opt-options) -> result; + /// Create a symmetric key from raw material. + /// + /// The 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`. + /// + /// The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. + /// + /// + /// TODO: Fix 'raw'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-key-import: func(algorithm: string, raw: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, raw-len: size) -> result; + /// Export a symmetric key as raw material. + /// + /// This is mainly useful to export a managed key. + /// + /// May return `prohibited_operation` if this operation is denied. + symmetric-key-export: func(symmetric-key: symmetric-key) -> result; + /// Destroy a symmetric key. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + symmetric-key-close: func(symmetric-key: symmetric-key) -> result<_, crypto-errno>; + /// __(optional)__ + /// Generate a new managed symmetric key. + /// + /// The key 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. + symmetric-key-generate-managed: func(secrets-manager: secrets-manager, algorithm: string, options: opt-options) -> result; + /// __(optional)__ + /// Store a symmetric key into the secrets manager. + /// + /// On success, the function stores the key identifier into `$symmetric_key_id`, + /// into which up to `$symmetric_key_id_max_len` can be written. + /// + /// The function returns `overflow` if the supplied buffer is too small. + /// + /// + /// TODO: Fix 'symmetric-key-id'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> result<_, crypto-errno>; + /// __(optional)__ + /// Replace a managed symmetric key. + /// + /// This function creates a new version of a managed symmetric key, by replacing `$kp_old` with `$kp_new`. + /// + /// It does several things: + /// + /// - The key identifier for `$symmetric_key_new` is set to the one of `$symmetric_key_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 `$symmetric_key_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 `$symmetric_key_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. + symmetric-key-replace-managed: func(secrets-manager: secrets-manager, symmetric-key-old: symmetric-key, symmetric-key-new: symmetric-key) -> result; + /// __(optional)__ + /// Return the key identifier and version of a managed symmetric key. + /// + /// If the key is not managed, `unsupported_feature` is returned instead. + /// + /// This is an optional import, meaning that the function may not even exist. + /// + /// + /// TODO: Fix 'symmetric-key-id'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'error'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("version"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U64)), docs: "Version of a managed key.\n\nA version can be an arbitrary `u64` integer, with the exception of some reserved values.\n" }), docs: "" }] })). + /// Reason: Unimplemented logic + symmetric-key-id: func(symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-version--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u64--docs--version-of-a-managed-key-n-na-version-can-be-an-arbitrary-u64-integer-with-the-exception-of-some-reserved-values-n---docs; + /// __(optional)__ + /// Return a managed symmetric key from a key identifier. + /// + /// `kp_version` can be set to `version_latest` to retrieve the most recent version of a symmetric key. + /// + /// If no key matching the provided information is found, `not_found` is returned instead. + /// + /// This is an optional import, meaning that the function may not even exist. + /// + /// + /// TODO: Fix 'symmetric-key-id'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-len: size, symmetric-key-version: version) -> result; + /// Create a new state to absorb and produce data using symmetric operations. + /// + /// The state remains valid after every operation in order to support incremental updates. + /// + /// The function has two optional parameters: a key and an options set. + /// + /// It will fail with a `key_not_supported` error code if a key was provided but the chosen algorithm doesn't natively support keying. + /// + /// On the other hand, if a key is required, but was not provided, a `key_required` error will be thrown. + /// + /// Some algorithms may require additional parameters. They have to be supplied as an options set: + /// + /// ```rust + /// let options_handle = ctx.options_open()?; + /// ctx.options_set("context", b"My application")?; + /// ctx.options_set_u64("fanout", 16)?; + /// let state_handle = ctx.symmetric_state_open("BLAKE2b-512", None, Some(options_handle))?; + /// ``` + /// + /// If some parameters are mandatory but were not set, the `parameters_missing` error code will be returned. + /// + /// A notable exception is the `nonce` parameter, that is common to most AEAD constructions. + /// + /// If a nonce is required but was not supplied: + /// + /// - 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. + /// - If not, the function will fail and return the dedicated `nonce_required` error code. + /// + /// A nonce that was automatically generated can be retrieved after the function returns with `symmetric_state_get(state_handle, "nonce")`. + /// + /// **Sample usage patterns:** + /// + /// - **Hashing** + /// + /// ```rust + /// let mut out = [0u8; 64]; + /// let state_handle = ctx.symmetric_state_open("SHAKE-128", None, None)?; + /// ctx.symmetric_state_absorb(state_handle, b"data")?; + /// ctx.symmetric_state_absorb(state_handle, b"more_data")?; + /// ctx.symmetric_state_squeeze(state_handle, &mut out)?; + /// ``` + /// + /// - **MAC** + /// + /// ```rust + /// let mut raw_tag = [0u8; 64]; + /// let key_handle = ctx.symmetric_key_import("HMAC/SHA-512", b"key")?; + /// let state_handle = ctx.symmetric_state_open("HMAC/SHA-512", Some(key_handle), None)?; + /// ctx.symmetric_state_absorb(state_handle, b"data")?; + /// ctx.symmetric_state_absorb(state_handle, b"more_data")?; + /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; + /// ctx.symmetric_tag_pull(computed_tag_handle, &mut raw_tag)?; + /// ``` + /// + /// Verification: + /// + /// ```rust + /// let state_handle = ctx.symmetric_state_open("HMAC/SHA-512", Some(key_handle), None)?; + /// ctx.symmetric_state_absorb(state_handle, b"data")?; + /// ctx.symmetric_state_absorb(state_handle, b"more_data")?; + /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; + /// ctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?; + /// ``` + /// + /// - **Tuple hashing** + /// + /// ```rust + /// let mut out = [0u8; 64]; + /// let state_handle = ctx.symmetric_state_open("TupleHashXOF256", None, None)?; + /// ctx.symmetric_state_absorb(state_handle, b"value 1")?; + /// ctx.symmetric_state_absorb(state_handle, b"value 2")?; + /// ctx.symmetric_state_absorb(state_handle, b"value 3")?; + /// ctx.symmetric_state_squeeze(state_handle, &mut out)?; + /// ``` + /// Unlike MACs and regular hash functions, inputs are domain separated instead of being concatenated. + /// + /// - **Key derivation using extract-and-expand** + /// + /// Extract: + /// + /// ```rust + /// let mut prk = vec![0u8; 64]; + /// let key_handle = ctx.symmetric_key_import("HKDF-EXTRACT/SHA-512", b"key")?; + /// let state_handle = ctx.symmetric_state_open("HKDF-EXTRACT/SHA-512", Some(key_handle), None)?; + /// ctx.symmetric_state_absorb(state_handle, b"salt")?; + /// let prk_handle = ctx.symmetric_state_squeeze_key(state_handle, "HKDF-EXPAND/SHA-512")?; + /// ``` + /// + /// Expand: + /// + /// ```rust + /// let mut subkey = vec![0u8; 32]; + /// let state_handle = ctx.symmetric_state_open("HKDF-EXPAND/SHA-512", Some(prk_handle), None)?; + /// ctx.symmetric_state_absorb(state_handle, b"info")?; + /// ctx.symmetric_state_squeeze(state_handle, &mut subkey)?; + /// ``` + /// + /// - **Key derivation using a XOF** + /// + /// ```rust + /// let mut subkey1 = vec![0u8; 32]; + /// let mut subkey2 = vec![0u8; 32]; + /// let key_handle = ctx.symmetric_key_import("BLAKE3", b"key")?; + /// let state_handle = ctx.symmetric_state_open("BLAKE3", Some(key_handle), None)?; + /// ctx.symmetric_absorb(state_handle, b"context")?; + /// ctx.squeeze(state_handle, &mut subkey1)?; + /// ctx.squeeze(state_handle, &mut subkey2)?; + /// ``` + /// + /// - **Password hashing** + /// + /// ```rust + /// let mut memory = vec![0u8; 1_000_000_000]; + /// let options_handle = ctx.symmetric_options_open()?; + /// ctx.symmetric_options_set_guest_buffer(options_handle, "memory", &mut memory)?; + /// ctx.symmetric_options_set_u64(options_handle, "opslimit", 5)?; + /// ctx.symmetric_options_set_u64(options_handle, "parallelism", 8)?; + /// + /// let state_handle = ctx.symmetric_state_open("ARGON2-ID-13", None, Some(options))?; + /// ctx.symmetric_state_absorb(state_handle, b"password")?; + /// + /// let pw_str_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; + /// let mut pw_str = vec![0u8; ctx.symmetric_tag_len(pw_str_handle)?]; + /// ctx.symmetric_tag_pull(pw_str_handle, &mut pw_str)?; + /// ``` + /// + /// - **AEAD encryption with an explicit nonce** + /// + /// ```rust + /// let key_handle = ctx.symmetric_key_generate("AES-256-GCM", None)?; + /// let message = b"test"; + /// + /// let options_handle = ctx.symmetric_options_open()?; + /// ctx.symmetric_options_set(options_handle, "nonce", nonce)?; + /// + /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle), Some(options_handle))?; + /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; + /// ctx.symmetric_state_absorb(state_handle, "additional data")?; + /// ctx.symmetric_state_encrypt(state_handle, &mut ciphertext, message)?; + /// ``` + /// + /// - **AEAD encryption with automatic nonce generation** + /// + /// ```rust + /// let key_handle = ctx.symmetric_key_generate("AES-256-GCM-SIV", None)?; + /// let message = b"test"; + /// let mut nonce = [0u8; 24]; + /// + /// let state_handle = ctx.symmetric_state_open("AES-256-GCM-SIV", Some(key_handle), None)?; + /// + /// let nonce = ctx.symmetric_state_options_get(state_handle, "nonce")?; + /// + /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; + /// ctx.symmetric_state_absorb(state_handle, "additional data")?; + /// ctx.symmetric_state_encrypt(state_handle, &mut ciphertext, message)?; + /// ``` + /// + /// - **Session authenticated modes** + /// + /// ```rust + /// let mut out = [0u8; 16]; + /// let mut out2 = [0u8; 16]; + /// let mut ciphertext = [0u8; 20]; + /// let key_handle = ctx.symmetric_key_generate("Xoodyak-128", None)?; + /// let state_handle = ctx.symmetric_state_open("Xoodyak-128", Some(key_handle), None)?; + /// ctx.symmetric_state_absorb(state_handle, b"data")?; + /// ctx.symmetric_state_encrypt(state_handle, &mut ciphertext, b"abcd")?; + /// ctx.symmetric_state_absorb(state_handle, b"more data")?; + /// ctx.symmetric_state_squeeze(state_handle, &mut out)?; + /// ctx.symmetric_state_squeeze(state_handle, &mut out2)?; + /// ctx.symmetric_state_ratchet(state_handle)?; + /// ctx.symmetric_state_absorb(state_handle, b"more data")?; + /// let next_key_handle = ctx.symmetric_state_squeeze_key(state_handle, "Xoodyak-128")?; + /// // ... + /// ``` + symmetric-state-open: func(algorithm: string, key: opt-symmetric-key, options: opt-options) -> result; + /// Retrieve a parameter from the current state. + /// + /// In particular, `symmetric_state_options_get("nonce")` can be used to get a nonce that as automatically generated. + /// + /// The function may return `options_not_set` if an option was not set, which is different from an empty value. + /// + /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. + /// + /// + /// TODO: Fix 'value'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-options-get: func(handle: symmetric-state, name: string, value: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, value-max-len: size) -> result; + /// Retrieve an integer parameter from the current state. + /// + /// The function may return `options_not_set` if an option was not set. + /// + /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. + symmetric-state-options-get-u64: func(handle: symmetric-state, name: string) -> result<%u64, crypto-errno>; + /// Clone a symmetric state. + /// + /// The function clones the internal state, assigns a new handle to it and returns the new handle. + symmetric-state-clone: func(handle: symmetric-state) -> result; + /// Destroy a symmetric state. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + symmetric-state-close: func(handle: symmetric-state) -> result<_, crypto-errno>; + /// Absorb data into the state. + /// + /// - **Hash functions:** adds data to be hashed. + /// - **MAC functions:** adds data to be authenticated. + /// - **Tuplehash-like constructions:** adds a new tuple to the state. + /// - **Key derivation functions:** adds to the IKM or to the subkey information. + /// - **AEAD constructions:** adds additional data to be authenticated. + /// - **Stateful hash objects, permutation-based constructions:** absorbs. + /// + /// If the chosen algorithm doesn't accept input data, the `invalid_operation` error code is returned. + /// + /// If too much data has been fed for the algorithm, `overflow` may be thrown. + /// + /// + /// TODO: Fix 'data'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-absorb: func(handle: symmetric-state, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result<_, crypto-errno>; + /// Squeeze bytes from the state. + /// + /// - **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. + /// - **Key derivation functions:** : outputs an arbitrary-long derived key. + /// - **RNGs, DRBGs, stream ciphers:**: outputs arbitrary-long data. + /// - **Stateful hash objects, permutation-based constructions:** squeeze. + /// + /// Other kinds of algorithms may return `invalid_operation` instead. + /// + /// For password-stretching functions, the function may return `in_progress`. + /// In that case, the guest should retry with the same parameters until the function completes. + /// + /// + /// TODO: Fix 'out'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-squeeze: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size) -> result<_, crypto-errno>; + /// Compute and return a tag for all the data injected into the state so far. + /// + /// - **MAC functions**: returns a tag authenticating the absorbed data. + /// - **Tuplehash-like constructions:** returns a tag authenticating all the absorbed tuples. + /// - **Password-hashing functions:** returns a standard string containing all the required parameters for password verification. + /// + /// Other kinds of algorithms may return `invalid_operation` instead. + /// + /// For password-stretching functions, the function may return `in_progress`. + /// In that case, the guest should retry with the same parameters until the function completes. + symmetric-state-squeeze-tag: func(handle: symmetric-state) -> result; + /// Use the current state to produce a key for a target algorithm. + /// + /// For extract-then-expand constructions, this returns the PRK. + /// For session-based authentication encryption, this returns a key that can be used to resume a session without storing a nonce. + /// + /// `invalid_operation` is returned for algorithms not supporting this operation. + symmetric-state-squeeze-key: func(handle: symmetric-state, alg-str: string) -> result; + /// Return the maximum length of an authentication tag for the current algorithm. + /// + /// This allows guests to compute the size required to store a ciphertext along with its authentication tag. + /// + /// The returned length may include the encryption mode's padding requirements in addition to the actual tag. + /// + /// For an encryption operation, the size of the output buffer should be `input_len + symmetric_state_max_tag_len()`. + /// + /// For a decryption operation, the size of the buffer that will store the decrypted data must be `ciphertext_len - symmetric_state_max_tag_len()`. + symmetric-state-max-tag-len: func(handle: symmetric-state) -> result; + /// Encrypt data with an attached 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. + /// - **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. + /// - **SHOE, Xoodyak, Strobe:** encrypts data, squeezes a tag and appends it to the output. + /// + /// If `out` and `data` are the same address, encryption may happen in-place. + /// + /// The function returns the actual size of the ciphertext along with the tag. + /// + /// `invalid_operation` is returned for algorithms not supporting encryption. + /// + /// + /// TODO: Fix 'out'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'data'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-encrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + /// Encrypt data, with a detached tag. + /// + /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. + /// - **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. + /// - **SHOE, Xoodyak, Strobe:** encrypts data and squeezes a tag. + /// + /// If `out` and `data` are the same address, encryption may happen in-place. + /// + /// The function returns the tag. + /// + /// `invalid_operation` is returned for algorithms not supporting encryption. + /// + /// + /// TODO: Fix 'out'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'data'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-encrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + /// - **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. + /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. + /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the one that was appended to the ciphertext. + /// + /// If `out` and `data` are the same address, decryption may happen in-place. + /// + /// `out_len` must be exactly `data_len` + `max_tag_len` bytes. + /// + /// The function returns the actual size of the decrypted message, which can be smaller than `out_len` for modes that requires padding. + /// + /// `invalid_tag` is returned if the tag didn't verify. + /// + /// `invalid_operation` is returned for algorithms not supporting encryption. + /// + /// + /// TODO: Fix 'out'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'data'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-decrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. + /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. + /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the expected one. + /// + /// `raw_tag` is the expected tag, as raw bytes. + /// + /// `out` and `data` be must have the same length. + /// If they also share the same address, decryption may happen in-place. + /// + /// The function returns the actual size of the decrypted message. + /// + /// `invalid_tag` is returned if the tag verification failed. + /// + /// `invalid_operation` is returned for algorithms not supporting encryption. + /// + /// + /// TODO: Fix 'out'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'data'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + /// + /// TODO: Fix 'raw-tag'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-state-decrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size, raw-tag: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, raw-tag-len: size) -> result; + /// Make it impossible to recover the previous state. + /// + /// This operation is supported by some systems keeping a rolling state over an entire session, for forward security. + /// + /// `invalid_operation` is returned for algorithms not supporting ratcheting. + symmetric-state-ratchet: func(handle: symmetric-state) -> result<_, crypto-errno>; + /// Return the length of an authentication tag. + /// + /// This function can be used by a guest to allocate the correct buffer size to copy a computed authentication tag. + symmetric-tag-len: func(symmetric-tag: symmetric-tag) -> result; + /// Copy an authentication tag into a guest-allocated buffer. + /// + /// The handle automatically becomes invalid after this operation. Manually closing it is not required. + /// + /// Example usage: + /// + /// ```rust + /// let mut raw_tag = [0u8; 16]; + /// ctx.symmetric_tag_pull(raw_tag_handle, &mut raw_tag)?; + /// ``` + /// + /// The function returns `overflow` if the supplied buffer is too small to copy the tag. + /// + /// Otherwise, it returns the number of bytes that have been copied. + /// + /// + /// TODO: Fix 'buf'. + /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-tag-pull: func(symmetric-tag: symmetric-tag, buf: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buf-len: size) -> result; + /// Verify that a computed authentication tag matches the expected value, in constant-time. + /// + /// The expected tag must be provided as a raw byte string. + /// + /// The function returns `invalid_tag` if the tags don't match. + /// + /// Example usage: + /// + /// ```rust + /// let key_handle = ctx.symmetric_key_import("HMAC/SHA-256", b"key")?; + /// let state_handle = ctx.symmetric_state_open("HMAC/SHA-256", Some(key_handle), None)?; + /// ctx.symmetric_state_absorb(state_handle, b"data")?; + /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; + /// ctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?; + /// ``` + /// + /// + /// TODO: Fix 'expected-raw-tag-ptr'. + /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). + /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. + symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag-ptr: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, expected-raw-tag-len: size) -> result<_, crypto-errno>; + /// Explicitly destroy an unused authentication tag. + /// + /// This is usually not necessary, as `symmetric_tag_pull()` automatically closes a tag after it has been copied. + /// + /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. + symmetric-tag-close: func(symmetric-tag: symmetric-tag) -> result<_, crypto-errno>; +} diff --git a/wit/wasi_ephemeral_crypto_symmetric_batch.wit b/wit/wasi_ephemeral_crypto_symmetric_batch.wit new file mode 100644 index 0000000..9bbb1de --- /dev/null +++ b/wit/wasi_ephemeral_crypto_symmetric_batch.wit @@ -0,0 +1,480 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-symmetric-batch { + resource handle { + } + /// Error codes. + variant crypto-errno { + /// Operation succeeded. + success, + /// An error occurred during a conversion from a host type to a guest type. + /// + /// Only an internal bug can throw this error. + guest-error, + /// The requested operation is valid, but not implemented by the host. + not-implemented, + /// The requested feature is not supported by the chosen algorithm. + unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. + prohibited-operation, + /// Unsupported encoding for an import or export operation. + unsupported-encoding, + /// The requested algorithm is not supported by the host. + unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. + unsupported-option, + /// An invalid or incompatible key was supplied. + /// + /// The key may not be valid, or was generated for a different algorithm or parameters set. + invalid-key, + /// The currently selected algorithm doesn't support the requested output length. + /// + /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. + invalid-length, + /// A signature or authentication tag verification failed. + verification-failed, + /// A secure random numbers generator is not available. + /// + /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. + rng-error, + /// An error was returned by the underlying cryptography library. + /// + /// The 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. + /// + /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. + /// + /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. + /// This 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. + algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. + invalid-signature, + /// An attempt was made to close a handle that was already closed. + closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. + invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. + overflow, + /// An internal error occurred. + /// + /// This 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. + internal-error, + /// Too many handles are currently open, and a new one cannot be created. + /// + /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. + too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. + /// + /// This is returned by symmetric operations. + /// + /// Many hash functions, in particular, do not support keys without being used in particular constructions. + /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. + /// + /// These functions must refuse to create the context and return this error instead. + key-not-supported, + /// A key is required for the chosen algorithm, but none was given. + key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. + /// + /// This error is returned by decryption functions and tag verification functions. + /// + /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. + invalid-tag, + /// The requested operation is incompatible with the current scheme. + /// + /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. + /// This error code will be returned instead. + invalid-operation, + /// A nonce is required. + /// + /// Most encryption schemes require a nonce. + /// + /// In 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. + /// If 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. + nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. + invalid-nonce, + /// The named option was not set. + /// + /// The caller tried to read the value of an option that was not set. + /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. + option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. + /// + /// This error is returned by a secrets manager via the `keypair_from_id()` function. + not-found, + /// The algorithm requires parameters that haven't been set. + /// + /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. + parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. + /// + /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. + /// + /// In 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. + in-progress, + /// Multiple keys have been provided, but they do not share the same type. + /// + /// This 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. + incompatible-keys, + /// A managed key or secret expired and cannot be used any more. + expired, + } + /// Encoding to use for importing or exporting a key pair. + variant keypair-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a public key. + variant publickey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC-1 encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a secret key. + variant secretkey-encoding { + /// Raw bytes. + raw, + /// PKCS8/DER encoding. + pkcs8, + /// PEM encoding. + pem, + /// SEC encoding. + sec, + /// Implementation-defined encoding. + local, + } + /// Encoding to use for importing or exporting a signature. + variant signature-encoding { + /// Raw bytes. + raw, + /// DER encoding. + der, + } + /// An algorithm category. + variant algorithm-type { + signatures, + symmetric, + key-exchange, + } + /// Version of a managed key. + /// + /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. + type version = u64; + /// Size of a value. + type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. + type timestamp = u64; + /// A 64-bit value + type %u64 = u64; + /// 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. + type array-output = 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. + type options = handle; + /// A handle to the optional secrets management facilities offered by a host. + /// + /// This is used to generate, retrieve and invalidate managed keys. + type secrets-manager = handle; + /// A key pair. + type keypair = 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. + type signature-state = handle; + /// A signature. + type signature = handle; + /// A public key, for key exchange and signature verification. + type publickey = handle; + /// A secret key, for key exchange mechanisms. + type secretkey = handle; + /// A state to absorb signed data to be verified. + type signature-verification-state = 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. + type symmetric-state = 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. + type symmetric-key = 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 responsible for securely wiping them from memory on close. + type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. + variant opt-options-u { + some, + none, + } + /// An optional options set. + /// + /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. + variant opt-symmetric-key-u { + some, + none, + } + /// An optional symmetric key. + /// + /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + type opt-symmetric-key = option; + type temp = todo-from-witx-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n; + type output-len = size; + type temp = todo-from-witx-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n; + type data-len = size; + type temp = todo-from-witx-namedtype--name-id-raw-tag--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--an-raw-tag-buffer-n; + type raw-tag-len = size; + type temp = todo-from-witx-namedtype--name-id-crypt-result--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--tuple-representing-results-and-size-produced-by-an-encrypt-decrypt-operation-n; + /// A list of results from the individual encrypt/decrypt operations within a batch operation. + type batch-crypt-results = list; + type temp = todo-from-witx-namedtype--name-id-encrypt-detached-result--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-tag--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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-responsible-for-securely-wiping-them-from-memory-on-close-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--tuple-representing-results-and-size-produced-by-a-detached-encrypt-operation-n; + /// A list of results from the individual encrypt/decrypt operations within a batch operation. + type batch-encrypt-detached-results = list; + /// A list of results from squeeze operation within a batch operation. + type batch-squeeze-results = list; + type temp = todo-from-witx-namedtype--name-id-squeeze-detached-result--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-tag--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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-responsible-for-securely-wiping-them-from-memory-on-close-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--tuple-representing-results-and-tag-and-error-produced-by-a-detached-squeeze-operation-n; + /// A list of results from the individual detached squeeze operations within a batch operation. + type batch-squeeze-detached-results = list; + /// Batch of operations to squeeze bytes from a batch of states. + /// + /// This is a batch version of the $symmetric_state_squeeze operation. + /// + /// Each entry in the batch corresponds to an individual squeeze operation. + /// The parameters associated with each operation are grouped into a tuple. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result is a list of $crypto_errno error + /// codes that represent the status of the operation in the input list at + /// the same list offset. + /// + /// + /// + /// TODO: Fix 'batch'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). + /// Reason: Unimplemented logic + batch-symmetric-state-squeeze: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + /// Batch of operations to compute and return a tag for all the data + /// injected into the state so far. + /// + /// This is a batch version of the $symmetric_state_squeeze_tag operation. + /// + /// Each entry in the batch corresponds to an individual squeeze_tag + /// operation. The parameters associated with each operation are grouped + /// into a tuple. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result is a list of tuples, with each + /// list entry corresponding to the operation in the input list at the same + /// list offset. Each tuple contains a $crypto_errno error code and a tag. + /// The error code represents the status of the operation and the tag is the + /// tag generated from the squeeze operation. The tag is only valid if the + /// tuple's error code is `success`. + /// + batch-symmetric-state-squeeze-tag: func(states: list) -> result; + /// Perform a batch of symmetric encrypt operations. + /// + /// This is a batch version of the symmetric_state_encrypt operation. + /// + /// Each entry in the batch corresponds to an individual encrypt operation. + /// The parameters associated with each encrypt operation are grouped into a + /// tuple. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result is a list of tuples, with each + /// list entry corresponding to the operation in the input list at the same + /// list offset. + /// Each tuple contains a size and a $crypto_errno error code. + /// The error code represents the status of the operation and the size is + /// the actual size of the ciphertext and the tag in the output buffer. The + /// size value is only valid if the tuple's error code is `success`. + /// + /// Example usage: + /// + /// ```rust + /// let mut batch = Vec::new(); + /// + /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; + /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; + /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); + /// + /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; + /// let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; + /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); + /// + /// let results = ctx.batch_symmetric_state_encrypt(batch)?; + /// ``` + /// + /// + /// TODO: Fix 'batch'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). + /// Reason: Unimplemented logic + batch-symmetric-state-encrypt: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + /// Perform a batch of symmetric encrypt operations with detached tags. + /// + /// This is a batch version of the symmetric_state_encrypt_detached + /// operation. + /// + /// Each entry in the batch corresponds to an individual encrypt operation. + /// The parameters associated with each encrypt operation are grouped into a + /// tuple. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result is a list of tuples, with each + /// list entry corresponding to the operation in the input list at the same + /// list offset. + /// Each tuple contains a tag and a $crypto_errno error code. + /// The error code represents the status of the operation and the tag is + /// the tag generated by the operation. The tag is only valid if the tuple's + /// error code is `success`. + /// + /// Example usage: + /// + /// ```rust + /// let mut batch = Vec::new(); + /// + /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; + /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; + /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); + /// + /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; + /// let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; + /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); + /// + /// let results = ctx.batch_symmetric_state_encrypt_detached(batch)?; + /// ``` + /// + /// + /// TODO: Fix 'batch'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). + /// Reason: Unimplemented logic + batch-symmetric-state-encrypt-detached: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + /// Perform a batch of symmetric decrypt operations. + /// + /// This is a batch version of the symmetric_state_decrypt operation. + /// + /// Each entry in the batch corresponds to an individual decrypt operation. + /// The parameters associated with each decrypt operation are grouped into a + /// tuple. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result is a list of tuples, with each + /// list entry corresponding to the operation in the input list at the same + /// list offset. + /// Each tuple contains a size and a $crypto_errno error code. + /// The error code represents the status of the operation and the size is + /// the actual size of the decrypted data in the output buffer. The size + /// value is only valid if the tuple's error code is `success`. + /// + /// + /// + /// TODO: Fix 'batch'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). + /// Reason: Unimplemented logic + batch-symmetric-state-decrypt: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + /// Perform a batch of symmetric decrypt operations with detached tags. + /// + /// This is a batch version of the symmetric_state_decrypt_detached operation. + /// + /// Each entry in the batch corresponds to an individual decrypt operation. + /// The parameters associated with each decrypt operation are grouped into a + /// tuple. + /// + /// The batch operation returns an error code of type $crypto_errno that + /// indicates if the batch was processed or if the batch could not be + /// processed. + /// + /// Batch processing error codes: + /// - `success`: Batch was processed. The status of each operation is indicated in the results list. + /// - `not_implemented`: Batch functionality is not supported. + /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. + /// + /// If the batch was processed, the result is a list of tuples, with each + /// list entry corresponding to the operation in the input list at the same + /// list offset. + /// Each tuple contains a size and a $crypto_errno error code. + /// The error code represents the status of the operation and the size is + /// the actual size of the decrypted data in the output buffer. The size + /// value is only valid if the tuple's error code is `success`. + /// + /// + /// + /// TODO: Fix 'batch'. + /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("5"), tref: Name(NamedType { name: Id("raw_tag"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An raw tag buffer\n" }), docs: "" }, RecordMember { name: Id("6"), tref: Name(NamedType { name: Id("raw_tag_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). + /// Reason: Unimplemented logic + batch-symmetric-state-decrypt-detached: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-5--tref-name-namedtype--name-id-raw-tag--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--an-raw-tag-buffer-n---docs----recordmember--name-id-6--tref-name-namedtype--name-id-raw-tag-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; +} From dbc7f6ab4dd1c31d45fde9b952f48044fecd79d0 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 02:24:43 +0200 Subject: [PATCH 02/15] feat: clean up wit files and use new transpiler version --- ...asi_ephemeral_crypto_asymmetric_common.wit | 277 ++------------- wit/wasi_ephemeral_crypto_common.wit | 91 ++++- ...wasi_ephemeral_crypto_external_secrets.wit | 267 +-------------- wit/wasi_ephemeral_crypto_kx.wit | 264 +-------------- wit/wasi_ephemeral_crypto_signatures.wit | 265 +-------------- ...wasi_ephemeral_crypto_signatures_batch.wit | 149 +------- wit/wasi_ephemeral_crypto_symmetric.wit | 285 ++-------------- wit/wasi_ephemeral_crypto_symmetric_batch.wit | 320 ++---------------- 8 files changed, 206 insertions(+), 1712 deletions(-) diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit index 08a80cc..fed9dee 100644 --- a/wit/wasi_ephemeral_crypto_asymmetric_common.wit +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -1,258 +1,6 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-asymmetric-common { - resource handle { - } - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC-1 encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a signature. - variant signature-encoding { - /// Raw bytes. - raw, - /// DER encoding. - der, - } - /// An algorithm category. - variant algorithm-type { - signatures, - symmetric, - key-exchange, - } - /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - /// Size of a value. - type size = u32; - /// A UNIX timestamp, in seconds since 01/01/1970. - type timestamp = u64; - /// A 64-bit value - type %u64 = u64; - /// 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. - type array-output = 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. - type options = handle; - /// A handle to the optional secrets management facilities offered by a host. - /// - /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; - /// A key pair. - type keypair = 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. - type signature-state = handle; - /// A signature. - type signature = handle; - /// A public key, for key exchange and signature verification. - type publickey = handle; - /// A secret key, for key exchange mechanisms. - type secretkey = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = 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. - type symmetric-state = 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. - type symmetric-key = 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 responsible for securely wiping them from memory on close. - type symmetric-tag = handle; - /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { - some, - none, - } - /// An optional options set. - /// - /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - type opt-options = option; - /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { - some, - none, - } - /// An optional symmetric key. - /// - /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - type opt-symmetric-key = option; /// Generate a new key pair. /// /// Internally, a key pair stores the supplied algorithm and optional parameters. @@ -272,6 +20,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?; /// ``` keypair-generate: func(algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; + /// Import a key pair. /// /// This function creates a `keypair` object from existing material. @@ -291,6 +40,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. keypair-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: keypair-encoding) -> result; + /// __(optional)__ /// Generate a new managed key pair. /// @@ -305,6 +55,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// /// This is also an optional import, meaning that the function may not even exist. keypair-generate-managed: func(secrets-manager: secrets-manager, algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; + /// __(optional)__ /// Store a key pair into the secrets manager. /// @@ -318,6 +69,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> result<_, crypto-errno>; + /// __(optional)__ /// Replace a managed key pair. /// @@ -340,6 +92,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// /// This is an optional import, meaning that the function may not even exist. keypair-replace-managed: func(secrets-manager: secrets-manager, kp-old: keypair, kp-new: keypair) -> result; + /// __(optional)__ /// Return the key pair identifier and version of a managed key pair. /// @@ -351,11 +104,8 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// TODO: Fix 'kp-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'error'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("version"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U64)), docs: "Version of a managed key.\n\nA version can be an arbitrary `u64` integer, with the exception of some reserved values.\n" }), docs: "" }] })). - /// Reason: Unimplemented logic - keypair-id: func(kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-version--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u64--docs--version-of-a-managed-key-n-na-version-can-be-an-arbitrary-u64-integer-with-the-exception-of-some-reserved-values-n---docs; + keypair-id: func(kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> result, crypto-errno>; + /// __(optional)__ /// Return a managed key pair from a key identifier. /// @@ -370,22 +120,28 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. keypair-from-id: func(secrets-manager: secrets-manager, kp-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, kp-id-len: size, kp-version: version) -> result; + /// Create a key pair from a public key and a secret key. keypair-from-pk-and-sk: func(publickey: publickey, secretkey: secretkey) -> result; + /// 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-export: func(kp: keypair, encoding: keypair-encoding) -> result; + /// Get the public key of a key pair. keypair-publickey: func(kp: keypair) -> result; + /// Get the secret key of a key pair. keypair-secretkey: func(kp: keypair) -> result; + /// 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. keypair-close: func(kp: keypair) -> result<_, crypto-errno>; + /// 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. @@ -405,22 +161,27 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. publickey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: publickey-encoding) -> result; + /// Export a public key as the given encoding format. /// /// May return `unsupported_encoding` if the encoding is not supported. publickey-export: func(pk: publickey, encoding: publickey-encoding) -> result; + /// 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-verify: func(pk: publickey) -> result<_, crypto-errno>; + /// Compute the public key for a secret key. publickey-from-secretkey: func(sk: secretkey) -> result; + /// Destroy a public key. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. publickey-close: func(pk: publickey) -> result<_, crypto-errno>; + /// 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. @@ -440,10 +201,12 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. secretkey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: secretkey-encoding) -> result; + /// Export a secret key as the given encoding format. /// /// May return `unsupported_encoding` if the encoding is not supported. secretkey-export: func(sk: secretkey, encoding: secretkey-encoding) -> result; + /// Destroy a secret key. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index eea9e71..36d76e6 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -1,51 +1,52 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-common { - /// TODO: Constant - resource version { - /// Original Value: 18374686479671623680 - unspecified: func() -> u64; - /// Original Value: 18374686479671623681 - latest: func() -> u64; - /// Original Value: 18374686479671623682 - all: func() -> u64; - } - resource handle { - } /// Error codes. variant crypto-errno { /// Operation succeeded. success, + /// An error occurred during a conversion from a host type to a guest type. /// /// Only an internal bug can throw this error. guest-error, + /// The requested operation is valid, but not implemented by the host. not-implemented, + /// The requested feature is not supported by the chosen algorithm. unsupported-feature, + /// The requested operation is valid, but was administratively prohibited. prohibited-operation, + /// Unsupported encoding for an import or export operation. unsupported-encoding, + /// The requested algorithm is not supported by the host. unsupported-algorithm, + /// The requested option is not supported by the currently selected algorithm. unsupported-option, + /// An invalid or incompatible key was supplied. /// /// The key may not be valid, or was generated for a different algorithm or parameters set. invalid-key, + /// The currently selected algorithm doesn't support the requested output length. /// /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. invalid-length, + /// A signature or authentication tag verification failed. verification-failed, + /// A secure random numbers generator is not available. /// /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. rng-error, + /// An error was returned by the underlying cryptography library. /// /// The 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. @@ -55,22 +56,29 @@ interface wasi-ephemeral-crypto-common { /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. /// This 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. algorithm-failure, + /// The supplied signature is invalid, or incompatible with the chosen algorithm. invalid-signature, + /// An attempt was made to close a handle that was already closed. closed, + /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. invalid-handle, + /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. overflow, + /// An internal error occurred. /// /// This 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. internal-error, + /// Too many handles are currently open, and a new one cannot be created. /// /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. too-many-handles, + /// A key was provided, but the chosen algorithm doesn't support keys. /// /// This is returned by symmetric operations. @@ -80,19 +88,23 @@ interface wasi-ephemeral-crypto-common { /// /// These functions must refuse to create the context and return this error instead. key-not-supported, + /// A key is required for the chosen algorithm, but none was given. key-required, + /// The provided authentication tag is invalid or incompatible with the current algorithm. /// /// This error is returned by decryption functions and tag verification functions. /// /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. invalid-tag, + /// The requested operation is incompatible with the current scheme. /// /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. /// This error code will be returned instead. invalid-operation, + /// A nonce is required. /// /// Most encryption schemes require a nonce. @@ -100,31 +112,38 @@ interface wasi-ephemeral-crypto-common { /// In 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. /// If 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. nonce-required, + /// The provided nonce doesn't have a correct size for the given cipher. invalid-nonce, + /// The named option was not set. /// /// The caller tried to read the value of an option that was not set. /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. option-not-set, + /// A key or key pair matching the requested identifier cannot be found using the supplied information. /// /// This error is returned by a secrets manager via the `keypair_from_id()` function. not-found, + /// The algorithm requires parameters that haven't been set. /// /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. parameters-missing, + /// A requested computation is not done yet, and additional calls to the function are required. /// /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. /// /// In 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. in-progress, + /// Multiple keys have been provided, but they do not share the same type. /// /// This 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. incompatible-keys, + /// A managed key or secret expired and cannot be used any more. expired, } @@ -139,6 +158,7 @@ interface wasi-ephemeral-crypto-common { /// Implementation-defined encoding. local, } + /// Encoding to use for importing or exporting a public key. variant publickey-encoding { /// Raw bytes. @@ -152,6 +172,7 @@ interface wasi-ephemeral-crypto-common { /// Implementation-defined encoding. local, } + /// Encoding to use for importing or exporting a secret key. variant secretkey-encoding { /// Raw bytes. @@ -165,6 +186,7 @@ interface wasi-ephemeral-crypto-common { /// Implementation-defined encoding. local, } + /// Encoding to use for importing or exporting a signature. variant signature-encoding { /// Raw bytes. @@ -172,22 +194,44 @@ interface wasi-ephemeral-crypto-common { /// DER encoding. der, } + /// An algorithm category. variant algorithm-type { signatures, symmetric, key-exchange, } + /// Version of a managed key. /// /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. type version = u64; + + /// TODO: Constant + resource version { + /// Original Value: 18374686479671623680 + /// Key doesn't support versioning. + unspecified: func() -> u64; + /// Original Value: 18374686479671623681 + /// Use the latest version of a key. + latest: func() -> u64; + /// Original Value: 18374686479671623682 + /// Perform an operation over all versions of a key. + all: func() -> u64; + } + /// Size of a value. type size = u32; + /// A UNIX timestamp, in seconds since 01/01/1970. type timestamp = u64; + /// A 64-bit value type %u64 = u64; + + resource 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. @@ -197,43 +241,54 @@ interface wasi-ephemeral-crypto-common { /// /// An `array_output` handle is automatically closed after its full content has been consumed. type array-output = 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. type options = handle; + /// A handle to the optional secrets management facilities offered by a host. /// /// This is used to generate, retrieve and invalidate managed keys. type secrets-manager = handle; + /// A key pair. type keypair = 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. type signature-state = handle; + /// A signature. type signature = handle; + /// A public key, for key exchange and signature verification. type publickey = handle; + /// A secret key, for key exchange mechanisms. type secretkey = handle; + /// A state to absorb signed data to be verified. type signature-verification-state = 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. type symmetric-state = 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. type symmetric-key = handle; + /// An authentication tag. /// /// This is an object returned by functions computing authentication tags. @@ -244,24 +299,29 @@ interface wasi-ephemeral-crypto-common { /// /// The host is responsible for securely wiping them from memory on close. type symmetric-tag = handle; + /// Options index, only required by the Interface Types translation layer. variant opt-options-u { some, none, } + /// An optional options set. /// /// This union simulates an `Option` type to make the `options` parameter of some functions optional. type opt-options = option; + /// Symmetric key index, only required by the Interface Types translation layer. variant opt-symmetric-key-u { some, none, } + /// An optional symmetric key. /// /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. type opt-symmetric-key = option; + /// Create a new object to set non-default options. /// /// Example usage: @@ -274,10 +334,12 @@ interface wasi-ephemeral-crypto-common { /// options_close(options_handle)?; /// ``` options-open: func(algorithm-type: algorithm-type) -> result; + /// Destroy an options object. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. options-close: func(handle: options) -> result<_, crypto-errno>; + /// Set or update an option. /// /// This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. @@ -289,12 +351,14 @@ interface wasi-ephemeral-crypto-common { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. options-set: func(handle: options, name: string, value: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, value-len: size) -> result<_, crypto-errno>; + /// Set or update an integer option. /// /// This is used to set algorithm-specific parameters. /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. options-set-u64: func(handle: options, name: string, value: u64) -> result<_, crypto-errno>; + /// Set or update a guest-allocated memory that the host can use or return data into. /// /// This is for example used to set the scratch buffer required by memory-hard functions. @@ -306,10 +370,12 @@ interface wasi-ephemeral-crypto-common { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. options-set-guest-buffer: func(handle: options, name: string, buffer: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buffer-len: size) -> result<_, crypto-errno>; + /// Return the length of an `array_output` object. /// /// This allows a guest to allocate a buffer of the correct size in order to copy the output of a function returning this object type. array-output-len: func(array-output: array-output) -> result; + /// Copy the content of an `array_output` object into an application-allocated buffer. /// /// Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. @@ -331,6 +397,7 @@ interface wasi-ephemeral-crypto-common { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. array-output-pull: func(array-output: array-output, buf: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buf-len: size) -> result; + /// __(optional)__ /// Create a context to use a secrets manager. /// @@ -339,12 +406,14 @@ interface wasi-ephemeral-crypto-common { /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. /// This is also an optional import, meaning that the function may not even exist. secrets-manager-open: func(options: opt-options) -> result; + /// __(optional)__ /// Destroy a secrets manager context. /// /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. /// This is also an optional import, meaning that the function may not even exist. secrets-manager-close: func(secrets-manager: secrets-manager) -> result<_, crypto-errno>; + /// __(optional)__ /// Invalidate a managed key or key pair given an identifier and a version. /// diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index 47a4a8d..8424f81 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -1,258 +1,16 @@ package wasi:crypto@0.0.1; +/// External secrets storage. +/// +/// External secrets are binary blobs, that can represent external API tokens or anything that is not meant to be consumed by the wasi-crypto APIs. +/// These secrets can be securely stored, and then retrieved using an identifier. +/// +/// Alternatively, the secrets manager can encrypt them, and applications will supply the ciphertext get the original secret back. +/// +/// The whole module is optional. +/// +/// __(optional)__ interface wasi-ephemeral-crypto-external-secrets { - resource handle { - } - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC-1 encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a signature. - variant signature-encoding { - /// Raw bytes. - raw, - /// DER encoding. - der, - } - /// An algorithm category. - variant algorithm-type { - signatures, - symmetric, - key-exchange, - } - /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - /// Size of a value. - type size = u32; - /// A UNIX timestamp, in seconds since 01/01/1970. - type timestamp = u64; - /// A 64-bit value - type %u64 = u64; - /// 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. - type array-output = 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. - type options = handle; - /// A handle to the optional secrets management facilities offered by a host. - /// - /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; - /// A key pair. - type keypair = 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. - type signature-state = handle; - /// A signature. - type signature = handle; - /// A public key, for key exchange and signature verification. - type publickey = handle; - /// A secret key, for key exchange mechanisms. - type secretkey = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = 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. - type symmetric-state = 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. - type symmetric-key = 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 responsible for securely wiping them from memory on close. - type symmetric-tag = handle; - /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { - some, - none, - } - /// An optional options set. - /// - /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - type opt-options = option; - /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { - some, - none, - } - /// An optional symmetric key. - /// - /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - type opt-symmetric-key = option; /// Store an external secret into the secrets manager. /// /// `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. @@ -272,6 +30,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. external-secret-store: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, secret-id-max-len: size) -> result<_, crypto-errno>; + /// Replace a managed external secret with a new version. /// /// `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. @@ -290,6 +49,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. external-secret-replace: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size) -> result; + /// 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. @@ -303,6 +63,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. external-secret-from-id: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size, secret-version: version) -> result; + /// 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. @@ -316,6 +77,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. external-secret-invalidate: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size, secret-version: version) -> result<_, crypto-errno>; + /// Encrypt an external secret. /// /// Applications don't have access to the encryption key, and the secrets manager is free to choose any suitable algorithm. @@ -329,6 +91,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp) -> result; + /// Decrypt an external secret previously encrypted by the secrets manager. /// /// Returns the original secret if the ciphertext is valid. diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index 2837e01..a73262d 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -1,270 +1,21 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-kx { - resource handle { - } - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC-1 encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a signature. - variant signature-encoding { - /// Raw bytes. - raw, - /// DER encoding. - der, - } - /// An algorithm category. - variant algorithm-type { - signatures, - symmetric, - key-exchange, - } - /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - /// Size of a value. - type size = u32; - /// A UNIX timestamp, in seconds since 01/01/1970. - type timestamp = u64; - /// A 64-bit value - type %u64 = u64; - /// 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. - type array-output = 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. - type options = handle; - /// A handle to the optional secrets management facilities offered by a host. - /// - /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; - /// A key pair. - type keypair = 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. - type signature-state = handle; - /// A signature. - type signature = handle; - /// A public key, for key exchange and signature verification. - type publickey = handle; - /// A secret key, for key exchange mechanisms. - type secretkey = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = 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. - type symmetric-state = 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. - type symmetric-key = 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 responsible for securely wiping them from memory on close. - type symmetric-tag = handle; - /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { - some, - none, - } - /// An optional options set. - /// - /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - type opt-options = option; - /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { - some, - none, - } - /// An optional symmetric key. - /// - /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - type opt-symmetric-key = option; /// `$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`. type kx-keypair = keypair; + /// `$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`. type kx-publickey = publickey; + /// `$kx_secretkey` is just an alias for `$secretkey` /// /// However, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkey`, with additional methods such as `dh`. type kx-secretkey = secretkey; + /// 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. @@ -272,18 +23,15 @@ interface wasi-ephemeral-crypto-kx { /// /// Otherwise, a raw shared key is returned, and can be imported as a symmetric key. kx-dh: func(pk: publickey, sk: secretkey) -> result; + /// 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. - /// - /// - /// TODO: Fix 'error'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("array_output"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("array_output"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }] })). - /// Reason: Unimplemented logic - kx-encapsulate: func(pk: publickey) -> todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-array-output--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-array-output--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs; + kx-encapsulate: func(pk: publickey) -> result, crypto-errno>; + /// Decapsulate an encapsulated secret created with `kx_encapsulate` /// /// Return the secret, or `$crypto_errno.verification_failed` on error. diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 9b676eb..7e8ce24 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -1,276 +1,28 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures { - resource handle { - } - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC-1 encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a signature. - variant signature-encoding { - /// Raw bytes. - raw, - /// DER encoding. - der, - } - /// An algorithm category. - variant algorithm-type { - signatures, - symmetric, - key-exchange, - } - /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - /// Size of a value. - type size = u32; - /// A UNIX timestamp, in seconds since 01/01/1970. - type timestamp = u64; - /// A 64-bit value - type %u64 = u64; - /// 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. - type array-output = 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. - type options = handle; - /// A handle to the optional secrets management facilities offered by a host. - /// - /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; - /// A key pair. - type keypair = 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. - type signature-state = handle; - /// A signature. - type signature = handle; - /// A public key, for key exchange and signature verification. - type publickey = handle; - /// A secret key, for key exchange mechanisms. - type secretkey = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = 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. - type symmetric-state = 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. - type symmetric-key = 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 responsible for securely wiping them from memory on close. - type symmetric-tag = handle; - /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { - some, - none, - } - /// An optional options set. - /// - /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - type opt-options = option; - /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { - some, - none, - } - /// An optional symmetric key. - /// - /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - type opt-symmetric-key = option; /// `$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`. type signature-keypair = keypair; + /// `$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`. type signature-publickey = publickey; + /// `$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`. type signature-secretkey = secretkey; + /// 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-export: func(signature: signature, encoding: signature-encoding) -> result; + /// Create a signature object. /// /// This object can be used along with a public key to verify an existing signature. @@ -290,6 +42,7 @@ interface wasi-ephemeral-crypto-signatures { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. signature-import: func(algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: signature-encoding) -> result; + /// 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. @@ -307,6 +60,7 @@ interface wasi-ephemeral-crypto-signatures { /// let raw_sig = ctx.signature_export(sig_handle, SignatureEncoding::Raw)?; /// ``` signature-state-open: func(kp: signature-keypair) -> result; + /// Absorb data into the signature state. /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. @@ -316,16 +70,19 @@ interface wasi-ephemeral-crypto-signatures { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. signature-state-update: func(state: signature-state, input: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + /// Compute a signature for all the data collected up to that point. /// /// The function can be called multiple times for incremental signing. signature-state-sign: func(state: signature-state) -> result; + /// 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 can be reused for further signatures. signature-state-close: func(state: signature-state) -> result<_, crypto-errno>; + /// Create a new state to collect data to verify a signature on. /// /// This is the verification counterpart of `signature_state`. @@ -342,6 +99,7 @@ interface wasi-ephemeral-crypto-signatures { /// ctx.signature_verification_state_verify(state_handle, signature_handle)?; /// ``` signature-verification-state-open: func(kp: signature-publickey) -> result; + /// Absorb data into the signature verification state. /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. @@ -351,18 +109,21 @@ interface wasi-ephemeral-crypto-signatures { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. signature-verification-state-update: func(state: signature-verification-state, input: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + /// Check that the given signature verifies for the data collected up to that 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-verify: func(state: signature-verification-state, signature: signature) -> result<_, crypto-errno>; + /// 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 can be reused for further verifications. signature-verification-state-close: func(state: signature-verification-state) -> result<_, crypto-errno>; + /// Destroy a signature. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. diff --git a/wit/wasi_ephemeral_crypto_signatures_batch.wit b/wit/wasi_ephemeral_crypto_signatures_batch.wit index 752d032..6251e37 100644 --- a/wit/wasi_ephemeral_crypto_signatures_batch.wit +++ b/wit/wasi_ephemeral_crypto_signatures_batch.wit @@ -1,146 +1,20 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures-batch { - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// 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. - type array-output = handle; - /// A signature. - type signature = 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. - type signature-state = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = handle; - type temp = todo-from-witx-namedtype--name-id-signature-sign-result--module-moduleid-witx-wasi-ephemeral-crypto-signatures-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-array-output--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--the-result-of-a-signature-sign-operation-a-pair-of-the-signature-and-an-error-code-n; + /// The result of a signature sign operation. A pair of the signature and an error code. + type signature-sign-result = tuple; + /// A list of signature_sign results. type signature-results = list; - type temp = todo-from-witx-namedtype--name-id-signature-verification-input--module-moduleid-witx-wasi-ephemeral-crypto-signatures-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-signature-verification-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--a-state-to-absorb-signed-data-to-be-verified-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-signature--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--a-signature-n---docs-------docs--a-tuple-of-a-signature-verification-state-and-the-signature-to-verify-n-nused-for-grouping-signature-verification-state-to-be-verified-with-the-signature-to-verify-nused-with-batch-signature-state-verify--n; + + /// A tuple of a signature verification state and the signature to verify. + /// + /// Used for grouping signature verification state to be verified with the signature to verify. + /// Used with batch_signature_state_verify(). + type signature-verification-input = tuple; + type signature-verification-results = list; + /// Compute a batch of signatures. /// /// This is a batch version of the signature_state_sign operation and is an extension of the wasi_ephemeral_crypto_signatures module. @@ -182,6 +56,7 @@ interface wasi-ephemeral-crypto-signatures-batch { /// let raw_sig2 = signature_export(sig_handle[1], SignatureEncoding::Raw)?; /// ``` batch-signature-state-sign: func(states: list) -> result; + /// Verify a batch of signatures. /// /// This is a batch version of the signature_state_verify operation and is diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index 4aa870f..a6043d5 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -1,264 +1,13 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-symmetric { - resource handle { - } - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC-1 encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a signature. - variant signature-encoding { - /// Raw bytes. - raw, - /// DER encoding. - der, - } - /// An algorithm category. - variant algorithm-type { - signatures, - symmetric, - key-exchange, - } - /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - /// Size of a value. - type size = u32; - /// A UNIX timestamp, in seconds since 01/01/1970. - type timestamp = u64; - /// A 64-bit value - type %u64 = u64; - /// 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. - type array-output = 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. - type options = handle; - /// A handle to the optional secrets management facilities offered by a host. - /// - /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; - /// A key pair. - type keypair = 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. - type signature-state = handle; - /// A signature. - type signature = handle; - /// A public key, for key exchange and signature verification. - type publickey = handle; - /// A secret key, for key exchange mechanisms. - type secretkey = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = 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. - type symmetric-state = 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. - type symmetric-key = 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 responsible for securely wiping them from memory on close. - type symmetric-tag = handle; - /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { - some, - none, - } - /// An optional options set. - /// - /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - type opt-options = option; - /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { - some, - none, - } - /// An optional symmetric key. - /// - /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - type opt-symmetric-key = option; /// Generate a new symmetric key for a given algorithm. /// /// `options` can be `None` to use the default parameters, or an algorithm-specific set of parameters to override. /// /// This 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. symmetric-key-generate: func(algorithm: string, options: opt-options) -> result; + /// Create a symmetric key from raw material. /// /// The 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`. @@ -270,16 +19,19 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-key-import: func(algorithm: string, raw: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, raw-len: size) -> result; + /// Export a symmetric key as raw material. /// /// This is mainly useful to export a managed key. /// /// May return `prohibited_operation` if this operation is denied. symmetric-key-export: func(symmetric-key: symmetric-key) -> result; + /// Destroy a symmetric key. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. symmetric-key-close: func(symmetric-key: symmetric-key) -> result<_, crypto-errno>; + /// __(optional)__ /// Generate a new managed symmetric key. /// @@ -294,6 +46,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// This is also an optional import, meaning that the function may not even exist. symmetric-key-generate-managed: func(secrets-manager: secrets-manager, algorithm: string, options: opt-options) -> result; + /// __(optional)__ /// Store a symmetric key into the secrets manager. /// @@ -307,6 +60,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> result<_, crypto-errno>; + /// __(optional)__ /// Replace a managed symmetric key. /// @@ -329,6 +83,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// This is an optional import, meaning that the function may not even exist. symmetric-key-replace-managed: func(secrets-manager: secrets-manager, symmetric-key-old: symmetric-key, symmetric-key-new: symmetric-key) -> result; + /// __(optional)__ /// Return the key identifier and version of a managed symmetric key. /// @@ -340,11 +95,8 @@ interface wasi-ephemeral-crypto-symmetric { /// TODO: Fix 'symmetric-key-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'error'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("version"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U64)), docs: "Version of a managed key.\n\nA version can be an arbitrary `u64` integer, with the exception of some reserved values.\n" }), docs: "" }] })). - /// Reason: Unimplemented logic - symmetric-key-id: func(symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-version--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u64--docs--version-of-a-managed-key-n-na-version-can-be-an-arbitrary-u64-integer-with-the-exception-of-some-reserved-values-n---docs; + symmetric-key-id: func(symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> result, crypto-errno>; + /// __(optional)__ /// Return a managed symmetric key from a key identifier. /// @@ -359,6 +111,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-len: size, symmetric-key-version: version) -> result; + /// Create a new state to absorb and produce data using symmetric operations. /// /// The state remains valid after every operation in order to support incremental updates. @@ -535,6 +288,7 @@ interface wasi-ephemeral-crypto-symmetric { /// // ... /// ``` symmetric-state-open: func(algorithm: string, key: opt-symmetric-key, options: opt-options) -> result; + /// Retrieve a parameter from the current state. /// /// In particular, `symmetric_state_options_get("nonce")` can be used to get a nonce that as automatically generated. @@ -548,20 +302,24 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-options-get: func(handle: symmetric-state, name: string, value: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, value-max-len: size) -> result; + /// Retrieve an integer parameter from the current state. /// /// The function may return `options_not_set` if an option was not set. /// /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. symmetric-state-options-get-u64: func(handle: symmetric-state, name: string) -> result<%u64, crypto-errno>; + /// Clone a symmetric state. /// /// The function clones the internal state, assigns a new handle to it and returns the new handle. symmetric-state-clone: func(handle: symmetric-state) -> result; + /// Destroy a symmetric state. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. symmetric-state-close: func(handle: symmetric-state) -> result<_, crypto-errno>; + /// Absorb data into the state. /// /// - **Hash functions:** adds data to be hashed. @@ -580,6 +338,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-absorb: func(handle: symmetric-state, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result<_, crypto-errno>; + /// Squeeze bytes from the state. /// /// - **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. @@ -597,6 +356,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-squeeze: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size) -> result<_, crypto-errno>; + /// Compute and return a tag for all the data injected into the state so far. /// /// - **MAC functions**: returns a tag authenticating the absorbed data. @@ -608,6 +368,7 @@ interface wasi-ephemeral-crypto-symmetric { /// For password-stretching functions, the function may return `in_progress`. /// In that case, the guest should retry with the same parameters until the function completes. symmetric-state-squeeze-tag: func(handle: symmetric-state) -> result; + /// Use the current state to produce a key for a target algorithm. /// /// For extract-then-expand constructions, this returns the PRK. @@ -615,6 +376,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// `invalid_operation` is returned for algorithms not supporting this operation. symmetric-state-squeeze-key: func(handle: symmetric-state, alg-str: string) -> result; + /// Return the maximum length of an authentication tag for the current algorithm. /// /// This allows guests to compute the size required to store a ciphertext along with its authentication tag. @@ -625,6 +387,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// For a decryption operation, the size of the buffer that will store the decrypted data must be `ciphertext_len - symmetric_state_max_tag_len()`. symmetric-state-max-tag-len: func(handle: symmetric-state) -> result; + /// Encrypt data with an attached 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. @@ -646,6 +409,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-encrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + /// Encrypt data, with a detached tag. /// /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. @@ -667,6 +431,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-encrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + /// - **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. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the one that was appended to the ciphertext. @@ -690,6 +455,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-decrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the expected one. @@ -718,16 +484,19 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-state-decrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size, raw-tag: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, raw-tag-len: size) -> result; + /// Make it impossible to recover the previous state. /// /// This operation is supported by some systems keeping a rolling state over an entire session, for forward security. /// /// `invalid_operation` is returned for algorithms not supporting ratcheting. symmetric-state-ratchet: func(handle: symmetric-state) -> result<_, crypto-errno>; + /// Return the length of an authentication tag. /// /// This function can be used by a guest to allocate the correct buffer size to copy a computed authentication tag. symmetric-tag-len: func(symmetric-tag: symmetric-tag) -> result; + /// Copy an authentication tag into a guest-allocated buffer. /// /// The handle automatically becomes invalid after this operation. Manually closing it is not required. @@ -748,6 +517,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-tag-pull: func(symmetric-tag: symmetric-tag, buf: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buf-len: size) -> result; + /// Verify that a computed authentication tag matches the expected value, in constant-time. /// /// The expected tag must be provided as a raw byte string. @@ -769,6 +539,7 @@ interface wasi-ephemeral-crypto-symmetric { /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag-ptr: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, expected-raw-tag-len: size) -> result<_, crypto-errno>; + /// Explicitly destroy an unused authentication tag. /// /// This is usually not necessary, as `symmetric_tag_pull()` automatically closes a tag after it has been copied. diff --git a/wit/wasi_ephemeral_crypto_symmetric_batch.wit b/wit/wasi_ephemeral_crypto_symmetric_batch.wit index 9bbb1de..d0e2005 100644 --- a/wit/wasi_ephemeral_crypto_symmetric_batch.wit +++ b/wit/wasi_ephemeral_crypto_symmetric_batch.wit @@ -1,275 +1,40 @@ package wasi:crypto@0.0.1; +/// Symmetric Batch Operations interface wasi-ephemeral-crypto-symmetric-batch { - resource handle { - } - /// Error codes. - variant crypto-errno { - /// Operation succeeded. - success, - /// An error occurred during a conversion from a host type to a guest type. - /// - /// Only an internal bug can throw this error. - guest-error, - /// The requested operation is valid, but not implemented by the host. - not-implemented, - /// The requested feature is not supported by the chosen algorithm. - unsupported-feature, - /// The requested operation is valid, but was administratively prohibited. - prohibited-operation, - /// Unsupported encoding for an import or export operation. - unsupported-encoding, - /// The requested algorithm is not supported by the host. - unsupported-algorithm, - /// The requested option is not supported by the currently selected algorithm. - unsupported-option, - /// An invalid or incompatible key was supplied. - /// - /// The key may not be valid, or was generated for a different algorithm or parameters set. - invalid-key, - /// The currently selected algorithm doesn't support the requested output length. - /// - /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. - invalid-length, - /// A signature or authentication tag verification failed. - verification-failed, - /// A secure random numbers generator is not available. - /// - /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. - rng-error, - /// An error was returned by the underlying cryptography library. - /// - /// The 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. - /// - /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// - /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. - /// This 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. - algorithm-failure, - /// The supplied signature is invalid, or incompatible with the chosen algorithm. - invalid-signature, - /// An attempt was made to close a handle that was already closed. - closed, - /// A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. - invalid-handle, - /// The host needs to copy data to a guest-allocated buffer, but that buffer is too small. - overflow, - /// An internal error occurred. - /// - /// This 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. - internal-error, - /// Too many handles are currently open, and a new one cannot be created. - /// - /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. - too-many-handles, - /// A key was provided, but the chosen algorithm doesn't support keys. - /// - /// This is returned by symmetric operations. - /// - /// Many hash functions, in particular, do not support keys without being used in particular constructions. - /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// - /// These functions must refuse to create the context and return this error instead. - key-not-supported, - /// A key is required for the chosen algorithm, but none was given. - key-required, - /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// - /// This error is returned by decryption functions and tag verification functions. - /// - /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. - invalid-tag, - /// The requested operation is incompatible with the current scheme. - /// - /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. - /// This error code will be returned instead. - invalid-operation, - /// A nonce is required. - /// - /// Most encryption schemes require a nonce. - /// - /// In 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. - /// If 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. - nonce-required, - /// The provided nonce doesn't have a correct size for the given cipher. - invalid-nonce, - /// The named option was not set. - /// - /// The caller tried to read the value of an option that was not set. - /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. - option-not-set, - /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// - /// This error is returned by a secrets manager via the `keypair_from_id()` function. - not-found, - /// The algorithm requires parameters that haven't been set. - /// - /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. - parameters-missing, - /// A requested computation is not done yet, and additional calls to the function are required. - /// - /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// - /// In 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. - in-progress, - /// Multiple keys have been provided, but they do not share the same type. - /// - /// This 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. - incompatible-keys, - /// A managed key or secret expired and cannot be used any more. - expired, - } - /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC-1 encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { - /// Raw bytes. - raw, - /// PKCS8/DER encoding. - pkcs8, - /// PEM encoding. - pem, - /// SEC encoding. - sec, - /// Implementation-defined encoding. - local, - } - /// Encoding to use for importing or exporting a signature. - variant signature-encoding { - /// Raw bytes. - raw, - /// DER encoding. - der, - } - /// An algorithm category. - variant algorithm-type { - signatures, - symmetric, - key-exchange, - } - /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - /// Size of a value. - type size = u32; - /// A UNIX timestamp, in seconds since 01/01/1970. - type timestamp = u64; - /// A 64-bit value - type %u64 = u64; - /// 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. - type array-output = 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. - type options = handle; - /// A handle to the optional secrets management facilities offered by a host. - /// - /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; - /// A key pair. - type keypair = 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. - type signature-state = handle; - /// A signature. - type signature = handle; - /// A public key, for key exchange and signature verification. - type publickey = handle; - /// A secret key, for key exchange mechanisms. - type secretkey = handle; - /// A state to absorb signed data to be verified. - type signature-verification-state = 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. - type symmetric-state = 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. - type symmetric-key = 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 responsible for securely wiping them from memory on close. - type symmetric-tag = handle; - /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { - some, - none, - } - /// An optional options set. - /// - /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - type opt-options = option; - /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { - some, - none, - } - /// An optional symmetric key. - /// - /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - type opt-symmetric-key = option; - type temp = todo-from-witx-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n; + /// An output buffer + type output = out-buffer; type output-len = size; - type temp = todo-from-witx-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n; + + /// A non-mutable data buffer + type data = in-buffer; type data-len = size; - type temp = todo-from-witx-namedtype--name-id-raw-tag--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--an-raw-tag-buffer-n; + + /// A raw tag buffer + type raw-tag = in-buffer; type raw-tag-len = size; - type temp = todo-from-witx-namedtype--name-id-crypt-result--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--tuple-representing-results-and-size-produced-by-an-encrypt-decrypt-operation-n; + + /// Tuple representing results and size produced by an encrypt/decrypt operation. + type crypt-result = tuple; + /// A list of results from the individual encrypt/decrypt operations within a batch operation. type batch-crypt-results = list; - type temp = todo-from-witx-namedtype--name-id-encrypt-detached-result--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-tag--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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-responsible-for-securely-wiping-them-from-memory-on-close-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--tuple-representing-results-and-size-produced-by-a-detached-encrypt-operation-n; + + /// Tuple representing results and size produced by a detached encrypt operation. + type encrypt-detached-result = tuple; + /// A list of results from the individual encrypt/decrypt operations within a batch operation. type batch-encrypt-detached-results = list; + /// A list of results from squeeze operation within a batch operation. type batch-squeeze-results = list; - type temp = todo-from-witx-namedtype--name-id-squeeze-detached-result--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-tag--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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-responsible-for-securely-wiping-them-from-memory-on-close-n---docs----recordmember--name-id-1--tref-name-namedtype--name-id-crypto-errno--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-variant-variant--tag-repr-u16-cases--case--name-id-success--tref-none-docs--operation-succeeded-n---case--name-id-guest-error--tref-none-docs--an-error-occurred-during-a-conversion-from-a-host-type-to-a-guest-type-n-nonly-an-internal-bug-can-throw-this-error-n---case--name-id-not-implemented--tref-none-docs--the-requested-operation-is-valid-but-not-implemented-by-the-host-n---case--name-id-unsupported-feature--tref-none-docs--the-requested-feature-is-not-supported-by-the-chosen-algorithm-n---case--name-id-prohibited-operation--tref-none-docs--the-requested-operation-is-valid-but-was-administratively-prohibited-n---case--name-id-unsupported-encoding--tref-none-docs--unsupported-encoding-for-an-import-or-export-operation-n---case--name-id-unsupported-algorithm--tref-none-docs--the-requested-algorithm-is-not-supported-by-the-host-n---case--name-id-unsupported-option--tref-none-docs--the-requested-option-is-not-supported-by-the-currently-selected-algorithm-n---case--name-id-invalid-key--tref-none-docs--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---case--name-id-invalid-length--tref-none-docs--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---case--name-id-verification-failed--tref-none-docs--a-signature-or-authentication-tag-verification-failed-n---case--name-id-rng-error--tref-none-docs--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---case--name-id-algorithm-failure--tref-none-docs--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---case--name-id-invalid-signature--tref-none-docs--the-supplied-signature-is-invalid-or-incompatible-with-the-chosen-algorithm-n---case--name-id-closed--tref-none-docs--an-attempt-was-made-to-close-a-handle-that-was-already-closed-n---case--name-id-invalid-handle--tref-none-docs--a-function-was-called-with-an-unassigned-handle-a-closed-handle-or-handle-of-an-unexpected-type-n---case--name-id-overflow--tref-none-docs--the-host-needs-to-copy-data-to-a-guest-allocated-buffer-but-that-buffer-is-too-small-n---case--name-id-internal-error--tref-none-docs--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---case--name-id-too-many-handles--tref-none-docs--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---case--name-id-key-not-supported--tref-none-docs--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---case--name-id-key-required--tref-none-docs--a-key-is-required-for-the-chosen-algorithm-but-none-was-given-n---case--name-id-invalid-tag--tref-none-docs--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---case--name-id-invalid-operation--tref-none-docs--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---case--name-id-nonce-required--tref-none-docs--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---case--name-id-invalid-nonce--tref-none-docs--the-provided-nonce-doesn-t-have-a-correct-size-for-the-given-cipher-n---case--name-id-option-not-set--tref-none-docs--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---case--name-id-not-found--tref-none-docs--a-key-or-key-pair-matching-the-requested-identifier-cannot-be-found-using-the-supplied-information-n-nthis-error-is-returned-by-a-secrets-manager-via-the-keypair-from-id--function-n---case--name-id-parameters-missing--tref-none-docs--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---case--name-id-in-progress--tref-none-docs--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---case--name-id-incompatible-keys--tref-none-docs--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---case--name-id-expired--tref-none-docs--a-managed-key-or-secret-expired-and-cannot-be-used-any-more-n-----docs--error-codes-n---docs-------docs--tuple-representing-results-and-tag-and-error-produced-by-a-detached-squeeze-operation-n; + + /// Tuple representing results and tag and error produced by a detached squeeze operation. + type squeeze-detached-result = tuple; + /// A list of results from the individual detached squeeze operations within a batch operation. type batch-squeeze-detached-results = list; + /// Batch of operations to squeeze bytes from a batch of states. /// /// This is a batch version of the $symmetric_state_squeeze operation. @@ -290,12 +55,8 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// codes that represent the status of the operation in the input list at /// the same list offset. /// - /// - /// - /// TODO: Fix 'batch'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). - /// Reason: Unimplemented logic - batch-symmetric-state-squeeze: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + batch-symmetric-state-squeeze: func(batch: list>) -> result; + /// Batch of operations to compute and return a tag for all the data /// injected into the state so far. /// @@ -322,6 +83,7 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// tuple's error code is `success`. /// batch-symmetric-state-squeeze-tag: func(states: list) -> result; + /// Perform a batch of symmetric encrypt operations. /// /// This is a batch version of the symmetric_state_encrypt operation. @@ -362,12 +124,8 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// /// let results = ctx.batch_symmetric_state_encrypt(batch)?; /// ``` - /// - /// - /// TODO: Fix 'batch'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). - /// Reason: Unimplemented logic - batch-symmetric-state-encrypt: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + batch-symmetric-state-encrypt: func(batch: list>) -> result; + /// Perform a batch of symmetric encrypt operations with detached tags. /// /// This is a batch version of the symmetric_state_encrypt_detached @@ -409,12 +167,8 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// /// let results = ctx.batch_symmetric_state_encrypt_detached(batch)?; /// ``` - /// - /// - /// TODO: Fix 'batch'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). - /// Reason: Unimplemented logic - batch-symmetric-state-encrypt-detached: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + batch-symmetric-state-encrypt-detached: func(batch: list>) -> result; + /// Perform a batch of symmetric decrypt operations. /// /// This is a batch version of the symmetric_state_decrypt operation. @@ -440,12 +194,7 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// the actual size of the decrypted data in the output buffer. The size /// value is only valid if the tuple's error code is `success`. /// - /// - /// - /// TODO: Fix 'batch'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). - /// Reason: Unimplemented logic - batch-symmetric-state-decrypt: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + batch-symmetric-state-decrypt: func(batch: list>) -> result; /// Perform a batch of symmetric decrypt operations with detached tags. /// /// This is a batch version of the symmetric_state_decrypt_detached operation. @@ -471,10 +220,5 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// the actual size of the decrypted data in the output buffer. The size /// value is only valid if the tuple's error code is `success`. /// - /// - /// - /// TODO: Fix 'batch'. - /// Original WITX: Value(Record(RecordDatatype { kind: Tuple, members: [RecordMember { name: Id("0"), tref: Name(NamedType { name: Id("symmetric_state"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Handle(HandleDatatype { resource_id: ResourceId { name: Id("handle"), module_id: ModuleId("witx/wasi_ephemeral_crypto_common.witx") } })), docs: "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" }), docs: "" }, RecordMember { name: Id("1"), tref: Name(NamedType { name: Id("output"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: true, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An output buffer\n" }), docs: "" }, RecordMember { name: Id("2"), tref: Name(NamedType { name: Id("output_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("3"), tref: Name(NamedType { name: Id("data"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "A non-mutable data buffer\n" }), docs: "" }, RecordMember { name: Id("4"), tref: Name(NamedType { name: Id("data_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }, RecordMember { name: Id("5"), tref: Name(NamedType { name: Id("raw_tag"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Value(Buffer(Buffer { out: false, tref: Value(Builtin(U8 { lang_c_char: false })) })), docs: "An raw tag buffer\n" }), docs: "" }, RecordMember { name: Id("6"), tref: Name(NamedType { name: Id("raw_tag_len"), module: ModuleId("witx/wasi_ephemeral_crypto_symmetric_batch.witx"), tref: Name(NamedType { name: Id("size"), module: ModuleId("witx/wasi_ephemeral_crypto_common.witx"), tref: Value(Builtin(U32 { lang_ptr_size: true })), docs: "Size of a value.\n" }), docs: "" }), docs: "" }] })). - /// Reason: Unimplemented logic - batch-symmetric-state-decrypt-detached: func(batch: todo-from-witx-value-record-recorddatatype--kind-tuple-members--recordmember--name-id-0--tref-name-namedtype--name-id-symmetric-state--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-handle-handledatatype--resource-id-resourceid--name-id-handle--module-id-moduleid-witx-wasi-ephemeral-crypto-common-witx-----docs--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---docs----recordmember--name-id-1--tref-name-namedtype--name-id-output--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-true-tref-value-builtin-u8--lang-c-char-false-----docs--an-output-buffer-n---docs----recordmember--name-id-2--tref-name-namedtype--name-id-output-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-3--tref-name-namedtype--name-id-data--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--a-non-mutable-data-buffer-n---docs----recordmember--name-id-4--tref-name-namedtype--name-id-data-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs----recordmember--name-id-5--tref-name-namedtype--name-id-raw-tag--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-value-buffer-buffer--out-false-tref-value-builtin-u8--lang-c-char-false-----docs--an-raw-tag-buffer-n---docs----recordmember--name-id-6--tref-name-namedtype--name-id-raw-tag-len--module-moduleid-witx-wasi-ephemeral-crypto-symmetric-batch-witx--tref-name-namedtype--name-id-size--module-moduleid-witx-wasi-ephemeral-crypto-common-witx--tref-value-builtin-u32--lang-ptr-size-true---docs--size-of-a-value-n---docs-----docs) -> result; + batch-symmetric-state-decrypt-detached: func(batch: list>) -> result; } From 27487f97c70a47877b76e912273e77bf160e9111 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 02:31:11 +0200 Subject: [PATCH 03/15] fix: remove double hyphens --- ...asi_ephemeral_crypto_asymmetric_common.wit | 140 ++++---- wit/wasi_ephemeral_crypto_common.wit | 152 ++++---- ...wasi_ephemeral_crypto_external_secrets.wit | 72 ++-- wit/wasi_ephemeral_crypto_kx.wit | 22 +- wit/wasi_ephemeral_crypto_signatures.wit | 74 ++-- wit/wasi_ephemeral_crypto_symmetric.wit | 334 +++++++++--------- 6 files changed, 397 insertions(+), 397 deletions(-) diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit index fed9dee..8143afc 100644 --- a/wit/wasi_ephemeral_crypto_asymmetric_common.wit +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -2,130 +2,130 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-asymmetric-common { /// 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: - /// + /// /// ```rust /// let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?; /// ``` keypair-generate: func(algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; /// 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: - /// + /// /// ```rust /// let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?; /// ``` - /// - /// + /// + /// /// TODO: Fix 'encoded'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: keypair-encoding) -> result; + keypair-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: keypair-encoding) -> result; /// __(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-generate-managed: func(secrets-manager: secrets-manager, algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; /// __(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. - /// - /// + /// + /// /// TODO: Fix 'kp-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> result<_, crypto-errno>; + keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, kp-id-max-len: size) -> result<_, crypto-errno>; /// __(optional)__ /// Replace a managed key pair. - /// + /// /// This function creates 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-replace-managed: func(secrets-manager: secrets-manager, kp-old: keypair, kp-new: keypair) -> result; /// __(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. - /// - /// + /// + /// /// TODO: Fix 'kp-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-id: func(kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, kp-id-max-len: size) -> result, crypto-errno>; + keypair-id: func(kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, kp-id-max-len: size) -> result, crypto-errno>; /// __(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. - /// - /// + /// + /// /// TODO: Fix 'kp-id'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-from-id: func(secrets-manager: secrets-manager, kp-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, kp-id-len: size, kp-version: version) -> result; + keypair-from-id: func(secrets-manager: secrets-manager, kp-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, kp-id-len: size, kp-version: version) -> result; /// Create a key pair from a public key and a secret key. keypair-from-pk-and-sk: func(publickey: publickey, secretkey: secretkey) -> result; /// 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-export: func(kp: keypair, encoding: keypair-encoding) -> result; @@ -136,41 +136,41 @@ interface wasi-ephemeral-crypto-asymmetric-common { keypair-secretkey: func(kp: keypair) -> result; /// 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. keypair-close: func(kp: keypair) -> result<_, crypto-errno>; /// 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: - /// + /// /// ```rust /// let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?; /// ``` - /// - /// + /// + /// /// TODO: Fix 'encoded'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - publickey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: publickey-encoding) -> result; + publickey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: publickey-encoding) -> result; /// Export a public key as the given encoding format. - /// + /// /// May return `unsupported_encoding` if the encoding is not supported. publickey-export: func(pk: publickey, encoding: publickey-encoding) -> result; /// 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-verify: func(pk: publickey) -> result<_, crypto-errno>; @@ -178,37 +178,37 @@ interface wasi-ephemeral-crypto-asymmetric-common { publickey-from-secretkey: func(sk: secretkey) -> result; /// Destroy a public key. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. publickey-close: func(pk: publickey) -> result<_, crypto-errno>; /// 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: - /// + /// /// ```rust /// let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?; /// ``` - /// - /// + /// + /// /// TODO: Fix 'encoded'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - secretkey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: secretkey-encoding) -> result; - + secretkey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: secretkey-encoding) -> result; + /// Export a secret key as the given encoding format. - /// + /// /// May return `unsupported_encoding` if the encoding is not supported. secretkey-export: func(sk: secretkey, encoding: secretkey-encoding) -> result; /// Destroy a secret key. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. secretkey-close: func(sk: secretkey) -> result<_, crypto-errno>; } diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index 36d76e6..7693831 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -7,7 +7,7 @@ interface wasi-ephemeral-crypto-common { success, /// An error occurred during a conversion from a host type to a guest type. - /// + /// /// Only an internal bug can throw this error. guest-error, @@ -19,7 +19,7 @@ interface wasi-ephemeral-crypto-common { /// The requested operation is valid, but was administratively prohibited. prohibited-operation, - + /// Unsupported encoding for an import or export operation. unsupported-encoding, @@ -30,12 +30,12 @@ interface wasi-ephemeral-crypto-common { unsupported-option, /// An invalid or incompatible key was supplied. - /// + /// /// The key may not be valid, or was generated for a different algorithm or parameters set. invalid-key, /// The currently selected algorithm doesn't support the requested output length. - /// + /// /// This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. invalid-length, @@ -43,16 +43,16 @@ interface wasi-ephemeral-crypto-common { verification-failed, /// A secure random numbers generator is not available. - /// + /// /// The requested operation requires random numbers, but the host cannot securely generate them at the moment. rng-error, /// An error was returned by the underlying cryptography library. - /// + /// /// The 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. - /// + /// /// Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. - /// + /// /// Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. /// This 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. algorithm-failure, @@ -70,22 +70,22 @@ interface wasi-ephemeral-crypto-common { overflow, /// An internal error occurred. - /// + /// /// This 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. internal-error, /// Too many handles are currently open, and a new one cannot be created. - /// + /// /// Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. too-many-handles, /// A key was provided, but the chosen algorithm doesn't support keys. - /// + /// /// This is returned by symmetric operations. - /// + /// /// Many hash functions, in particular, do not support keys without being used in particular constructions. /// Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. - /// + /// /// These functions must refuse to create the context and return this error instead. key-not-supported, @@ -93,22 +93,22 @@ interface wasi-ephemeral-crypto-common { key-required, /// The provided authentication tag is invalid or incompatible with the current algorithm. - /// + /// /// This error is returned by decryption functions and tag verification functions. - /// + /// /// Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. invalid-tag, /// The requested operation is incompatible with the current scheme. - /// + /// /// For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. /// This error code will be returned instead. invalid-operation, /// A nonce is required. - /// + /// /// Most encryption schemes require a nonce. - /// + /// /// In 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. /// If 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. nonce-required, @@ -117,30 +117,30 @@ interface wasi-ephemeral-crypto-common { invalid-nonce, /// The named option was not set. - /// + /// /// The caller tried to read the value of an option that was not set. /// This error is used to make the distinction between an empty option, and an option that was not set and left to its default value. option-not-set, /// A key or key pair matching the requested identifier cannot be found using the supplied information. - /// + /// /// This error is returned by a secrets manager via the `keypair_from_id()` function. not-found, /// The algorithm requires parameters that haven't been set. - /// + /// /// Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. parameters-missing, /// A requested computation is not done yet, and additional calls to the function are required. - /// + /// /// Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. - /// + /// /// In 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. in-progress, /// Multiple keys have been provided, but they do not share the same type. - /// + /// /// This 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. incompatible-keys, @@ -203,7 +203,7 @@ interface wasi-ephemeral-crypto-common { } /// Version of a managed key. - /// + /// /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. type version = u64; @@ -233,24 +233,24 @@ interface wasi-ephemeral-crypto-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. type array-output = 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. type options = handle; /// A handle to the optional secrets management facilities offered by a host. - /// + /// /// This is used to generate, retrieve and invalidate managed keys. type secrets-manager = handle; @@ -258,9 +258,9 @@ interface wasi-ephemeral-crypto-common { type keypair = 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. type signature-state = handle; @@ -277,26 +277,26 @@ interface wasi-ephemeral-crypto-common { type signature-verification-state = 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. type symmetric-state = 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. type symmetric-key = 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 responsible for securely wiping them from memory on close. type symmetric-tag = handle; @@ -307,7 +307,7 @@ interface wasi-ephemeral-crypto-common { } /// An optional options set. - /// + /// /// This union simulates an `Option` type to make the `options` parameter of some functions optional. type opt-options = option; @@ -318,14 +318,14 @@ interface wasi-ephemeral-crypto-common { } /// An optional symmetric key. - /// + /// /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. type opt-symmetric-key = option; /// Create a new object to set non-default options. - /// + /// /// Example usage: - /// + /// /// ```rust /// let options_handle = options_open(AlgorithmType::Symmetric)?; /// options_set(options_handle, "context", context)?; @@ -336,98 +336,98 @@ interface wasi-ephemeral-crypto-common { options-open: func(algorithm-type: algorithm-type) -> result; /// Destroy an options object. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. options-close: func(handle: options) -> result<_, crypto-errno>; /// Set or update an option. - /// + /// /// This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. - /// + /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - /// - /// + /// + /// /// TODO: Fix 'value'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - options-set: func(handle: options, name: string, value: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, value-len: size) -> result<_, crypto-errno>; + options-set: func(handle: options, name: string, value: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, value-len: size) -> result<_, crypto-errno>; /// Set or update an integer option. - /// + /// /// This is used to set algorithm-specific parameters. - /// + /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. options-set-u64: func(handle: options, name: string, value: u64) -> result<_, crypto-errno>; /// Set or update a guest-allocated memory that the host can use or return data into. - /// + /// /// This is for example used to set the scratch buffer required by memory-hard functions. - /// + /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - /// - /// + /// + /// /// TODO: Fix 'buffer'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - options-set-guest-buffer: func(handle: options, name: string, buffer: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buffer-len: size) -> result<_, crypto-errno>; + options-set-guest-buffer: func(handle: options, name: string, buffer: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, buffer-len: size) -> result<_, crypto-errno>; /// Return the length of an `array_output` object. - /// + /// /// This allows a guest to allocate a buffer of the correct size in order to copy the output of a function returning this object type. array-output-len: func(array-output: array-output) -> result; /// Copy the content of an `array_output` object into an application-allocated buffer. - /// + /// /// Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. - /// + /// /// The 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()`. - /// + /// /// The handle is automatically closed after all the data has been consumed. - /// + /// /// Example usage: - /// + /// /// ```rust /// let len = array_output_len(output_handle)?; /// let mut out = vec![0u8; len]; /// array_output_pull(output_handle, &mut out)?; /// ``` - /// - /// + /// + /// /// TODO: Fix 'buf'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - array-output-pull: func(array-output: array-output, buf: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buf-len: size) -> result; + array-output-pull: func(array-output: array-output, buf: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, buf-len: size) -> result; /// __(optional)__ /// Create a context to use a secrets manager. - /// + /// /// The set of required and supported options is defined by the host. - /// + /// /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. /// This is also an optional import, meaning that the function may not even exist. secrets-manager-open: func(options: opt-options) -> result; /// __(optional)__ /// Destroy a secrets manager context. - /// + /// /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. /// This is also an optional import, meaning that the function may not even exist. secrets-manager-close: func(secrets-manager: secrets-manager) -> result<_, crypto-errno>; /// __(optional)__ /// Invalidate a managed key or key pair given an identifier and a version. - /// + /// /// This asks the secrets manager to delete or revoke a stored key, a specific version of a key. - /// + /// /// `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. - /// + /// /// 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 key. - /// + /// /// This is an optional import, meaning that the function may not even exist. - /// - /// + /// + /// /// TODO: Fix 'key-id'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - secrets-manager-invalidate: func(secrets-manager: secrets-manager, key-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, key-id-len: size, key-version: version) -> result<_, crypto-errno>; + secrets-manager-invalidate: func(secrets-manager: secrets-manager, key-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, key-id-len: size, key-version: version) -> result<_, crypto-errno>; } diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index 8424f81..c532394 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -12,95 +12,95 @@ package wasi:crypto@0.0.1; /// __(optional)__ interface wasi-ephemeral-crypto-external-secrets { /// 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 output buffer is too small, `$overflow` is returned. - /// + /// /// If this function is not supported by the host the `$unsupported_feature` error is returned. - /// - /// + /// + /// /// TODO: Fix 'secret'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'secret-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-store: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, secret-id-max-len: size) -> result<_, crypto-errno>; + external-secret-store: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, secret-id-max-len: size) -> result<_, crypto-errno>; /// Replace a managed external secret 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. - /// - /// + /// + /// /// TODO: Fix 'secret'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'secret-id'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-replace: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size) -> result; + external-secret-replace: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-id-len: size) -> result; /// 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. - /// - /// + /// + /// /// TODO: Fix 'secret-id'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-from-id: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size, secret-version: version) -> result; + external-secret-from-id: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-id-len: size, secret-version: version) -> result; /// 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. - /// - /// + /// + /// /// TODO: Fix 'secret-id'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-invalidate: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-id-len: size, secret-version: version) -> result<_, crypto-errno>; + external-secret-invalidate: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-id-len: size, secret-version: version) -> result<_, crypto-errno>; /// 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. - /// - /// + /// + /// /// TODO: Fix 'secret'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, secret-len: size, expiration: timestamp) -> result; + external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-len: size, expiration: timestamp) -> result; /// 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. - /// - /// + /// + /// /// TODO: Fix 'encrypted-secret'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-decapsulate: func(secrets-manager: secrets-manager, encrypted-secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encrypted-secret-len: size) -> result; + external-secret-decapsulate: func(secrets-manager: secrets-manager, encrypted-secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encrypted-secret-len: size) -> result; } diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index a73262d..50be389 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -2,43 +2,43 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-kx { /// `$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`. type kx-keypair = keypair; /// `$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`. type kx-publickey = publickey; /// `$kx_secretkey` is just an alias for `$secretkey` - /// + /// /// However, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkey`, with additional methods such as `dh`. type kx-secretkey = secretkey; /// 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. - /// + /// /// Otherwise, a raw shared key is returned, and can be imported as a symmetric key. kx-dh: func(pk: publickey, sk: secretkey) -> result; /// 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-encapsulate: func(pk: publickey) -> result, crypto-errno>; /// Decapsulate an encapsulated secret created with `kx_encapsulate` - /// + /// /// Return the secret, or `$crypto_errno.verification_failed` on error. - /// - /// + /// + /// /// TODO: Fix 'encapsulated-secret'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - kx-decapsulate: func(sk: secretkey, encapsulated-secret: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encapsulated-secret-len: size) -> result; + kx-decapsulate: func(sk: secretkey, encapsulated-secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encapsulated-secret-len: size) -> result; } diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 7e8ce24..842d5d4 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -2,55 +2,55 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures { /// `$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`. type signature-keypair = keypair; /// `$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`. type signature-publickey = publickey; /// `$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`. type signature-secretkey = secretkey; /// 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-export: func(signature: signature, encoding: signature-encoding) -> result; /// 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: - /// + /// /// ```rust /// let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", SignatureEncoding::DER, encoded)?; /// ``` - /// - /// + /// + /// /// TODO: Fix 'encoded'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - signature-import: func(algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, encoded-len: size, encoding: signature-encoding) -> result; + signature-import: func(algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: signature-encoding) -> result; /// 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 - /// + /// /// ```rust /// let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "Ed25519ph", keypair, KeypairEncoding::Raw)?; /// let state_handle = ctx.signature_state_open(kp_handle)?; @@ -62,35 +62,35 @@ interface wasi-ephemeral-crypto-signatures { signature-state-open: func(kp: signature-keypair) -> result; /// Absorb data into the signature state. - /// + /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. - /// - /// + /// + /// /// TODO: Fix 'input'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - signature-state-update: func(state: signature-state, input: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + signature-state-update: func(state: signature-state, input: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, input-len: size) -> result<_, crypto-errno>; /// Compute a signature for all the data collected up to that point. - /// + /// /// The function can be called multiple times for incremental signing. signature-state-sign: func(state: signature-state) -> result; /// 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 can be reused for further signatures. signature-state-close: func(state: signature-state) -> result<_, crypto-errno>; /// 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: - /// + /// /// ```rust /// let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_pk, PublicKeyEncoding::Sec)?; /// let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", encoded_sig, SignatureEncoding::Der)?; @@ -101,31 +101,31 @@ interface wasi-ephemeral-crypto-signatures { signature-verification-state-open: func(kp: signature-publickey) -> result; /// Absorb data into the signature verification state. - /// + /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. - /// - /// + /// + /// /// TODO: Fix 'input'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - signature-verification-state-update: func(state: signature-verification-state, input: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + signature-verification-state-update: func(state: signature-verification-state, input: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, input-len: size) -> result<_, crypto-errno>; /// Check that the given signature verifies for the data collected up to that 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-verify: func(state: signature-verification-state, signature: signature) -> result<_, crypto-errno>; /// 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 can be reused for further verifications. signature-verification-state-close: func(state: signature-verification-state) -> result<_, crypto-errno>; /// Destroy a signature. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. signature-close: func(signature: signature) -> result<_, crypto-errno>; } diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index a6043d5..cdd9ca1 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -2,150 +2,150 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-symmetric { /// Generate a new symmetric key for a given algorithm. - /// + /// /// `options` can be `None` to use the default parameters, or an algorithm-specific set of parameters to override. - /// + /// /// This 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. symmetric-key-generate: func(algorithm: string, options: opt-options) -> result; /// Create a symmetric key from raw material. - /// + /// /// The 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`. - /// + /// /// The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. - /// - /// + /// + /// /// TODO: Fix 'raw'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-import: func(algorithm: string, raw: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, raw-len: size) -> result; + symmetric-key-import: func(algorithm: string, raw: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, raw-len: size) -> result; /// Export a symmetric key as raw material. - /// + /// /// This is mainly useful to export a managed key. - /// + /// /// May return `prohibited_operation` if this operation is denied. symmetric-key-export: func(symmetric-key: symmetric-key) -> result; /// Destroy a symmetric key. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. symmetric-key-close: func(symmetric-key: symmetric-key) -> result<_, crypto-errno>; /// __(optional)__ /// Generate a new managed symmetric key. - /// + /// /// The key 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. symmetric-key-generate-managed: func(secrets-manager: secrets-manager, algorithm: string, options: opt-options) -> result; /// __(optional)__ /// Store a symmetric key into the secrets manager. - /// + /// /// On success, the function stores the key identifier into `$symmetric_key_id`, /// into which up to `$symmetric_key_id_max_len` can be written. - /// + /// /// The function returns `overflow` if the supplied buffer is too small. - /// - /// + /// + /// /// TODO: Fix 'symmetric-key-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> result<_, crypto-errno>; + symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, symmetric-key-id-max-len: size) -> result<_, crypto-errno>; /// __(optional)__ /// Replace a managed symmetric key. - /// + /// /// This function creates a new version of a managed symmetric key, by replacing `$kp_old` with `$kp_new`. - /// + /// /// It does several things: - /// + /// /// - The key identifier for `$symmetric_key_new` is set to the one of `$symmetric_key_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 `$symmetric_key_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 `$symmetric_key_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. symmetric-key-replace-managed: func(secrets-manager: secrets-manager, symmetric-key-old: symmetric-key, symmetric-key-new: symmetric-key) -> result; /// __(optional)__ /// Return the key identifier and version of a managed symmetric key. - /// + /// /// If the key is not managed, `unsupported_feature` is returned instead. - /// + /// /// This is an optional import, meaning that the function may not even exist. - /// - /// + /// + /// /// TODO: Fix 'symmetric-key-id'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-id: func(symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-max-len: size) -> result, crypto-errno>; + symmetric-key-id: func(symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, symmetric-key-id-max-len: size) -> result, crypto-errno>; /// __(optional)__ /// Return a managed symmetric key from a key identifier. - /// + /// /// `kp_version` can be set to `version_latest` to retrieve the most recent version of a symmetric key. - /// + /// /// If no key matching the provided information is found, `not_found` is returned instead. - /// + /// /// This is an optional import, meaning that the function may not even exist. - /// - /// + /// + /// /// TODO: Fix 'symmetric-key-id'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, symmetric-key-id-len: size, symmetric-key-version: version) -> result; + symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, symmetric-key-id-len: size, symmetric-key-version: version) -> result; /// Create a new state to absorb and produce data using symmetric operations. - /// + /// /// The state remains valid after every operation in order to support incremental updates. - /// + /// /// The function has two optional parameters: a key and an options set. - /// + /// /// It will fail with a `key_not_supported` error code if a key was provided but the chosen algorithm doesn't natively support keying. - /// + /// /// On the other hand, if a key is required, but was not provided, a `key_required` error will be thrown. - /// + /// /// Some algorithms may require additional parameters. They have to be supplied as an options set: - /// + /// /// ```rust /// let options_handle = ctx.options_open()?; /// ctx.options_set("context", b"My application")?; /// ctx.options_set_u64("fanout", 16)?; /// let state_handle = ctx.symmetric_state_open("BLAKE2b-512", None, Some(options_handle))?; /// ``` - /// + /// /// If some parameters are mandatory but were not set, the `parameters_missing` error code will be returned. - /// + /// /// A notable exception is the `nonce` parameter, that is common to most AEAD constructions. - /// + /// /// If a nonce is required but was not supplied: - /// + /// /// - 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. /// - If not, the function will fail and return the dedicated `nonce_required` error code. - /// + /// /// A nonce that was automatically generated can be retrieved after the function returns with `symmetric_state_get(state_handle, "nonce")`. - /// + /// /// **Sample usage patterns:** - /// + /// /// - **Hashing** - /// + /// /// ```rust /// let mut out = [0u8; 64]; /// let state_handle = ctx.symmetric_state_open("SHAKE-128", None, None)?; @@ -153,9 +153,9 @@ interface wasi-ephemeral-crypto-symmetric { /// ctx.symmetric_state_absorb(state_handle, b"more_data")?; /// ctx.symmetric_state_squeeze(state_handle, &mut out)?; /// ``` - /// + /// /// - **MAC** - /// + /// /// ```rust /// let mut raw_tag = [0u8; 64]; /// let key_handle = ctx.symmetric_key_import("HMAC/SHA-512", b"key")?; @@ -165,9 +165,9 @@ interface wasi-ephemeral-crypto-symmetric { /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; /// ctx.symmetric_tag_pull(computed_tag_handle, &mut raw_tag)?; /// ``` - /// + /// /// Verification: - /// + /// /// ```rust /// let state_handle = ctx.symmetric_state_open("HMAC/SHA-512", Some(key_handle), None)?; /// ctx.symmetric_state_absorb(state_handle, b"data")?; @@ -175,9 +175,9 @@ interface wasi-ephemeral-crypto-symmetric { /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; /// ctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?; /// ``` - /// + /// /// - **Tuple hashing** - /// + /// /// ```rust /// let mut out = [0u8; 64]; /// let state_handle = ctx.symmetric_state_open("TupleHashXOF256", None, None)?; @@ -187,11 +187,11 @@ interface wasi-ephemeral-crypto-symmetric { /// ctx.symmetric_state_squeeze(state_handle, &mut out)?; /// ``` /// Unlike MACs and regular hash functions, inputs are domain separated instead of being concatenated. - /// + /// /// - **Key derivation using extract-and-expand** - /// + /// /// Extract: - /// + /// /// ```rust /// let mut prk = vec![0u8; 64]; /// let key_handle = ctx.symmetric_key_import("HKDF-EXTRACT/SHA-512", b"key")?; @@ -199,18 +199,18 @@ interface wasi-ephemeral-crypto-symmetric { /// ctx.symmetric_state_absorb(state_handle, b"salt")?; /// let prk_handle = ctx.symmetric_state_squeeze_key(state_handle, "HKDF-EXPAND/SHA-512")?; /// ``` - /// + /// /// Expand: - /// + /// /// ```rust /// let mut subkey = vec![0u8; 32]; /// let state_handle = ctx.symmetric_state_open("HKDF-EXPAND/SHA-512", Some(prk_handle), None)?; /// ctx.symmetric_state_absorb(state_handle, b"info")?; /// ctx.symmetric_state_squeeze(state_handle, &mut subkey)?; /// ``` - /// + /// /// - **Key derivation using a XOF** - /// + /// /// ```rust /// let mut subkey1 = vec![0u8; 32]; /// let mut subkey2 = vec![0u8; 32]; @@ -220,57 +220,57 @@ interface wasi-ephemeral-crypto-symmetric { /// ctx.squeeze(state_handle, &mut subkey1)?; /// ctx.squeeze(state_handle, &mut subkey2)?; /// ``` - /// + /// /// - **Password hashing** - /// + /// /// ```rust /// let mut memory = vec![0u8; 1_000_000_000]; /// let options_handle = ctx.symmetric_options_open()?; /// ctx.symmetric_options_set_guest_buffer(options_handle, "memory", &mut memory)?; /// ctx.symmetric_options_set_u64(options_handle, "opslimit", 5)?; /// ctx.symmetric_options_set_u64(options_handle, "parallelism", 8)?; - /// + /// /// let state_handle = ctx.symmetric_state_open("ARGON2-ID-13", None, Some(options))?; /// ctx.symmetric_state_absorb(state_handle, b"password")?; - /// + /// /// let pw_str_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; /// let mut pw_str = vec![0u8; ctx.symmetric_tag_len(pw_str_handle)?]; /// ctx.symmetric_tag_pull(pw_str_handle, &mut pw_str)?; /// ``` - /// + /// /// - **AEAD encryption with an explicit nonce** - /// + /// /// ```rust /// let key_handle = ctx.symmetric_key_generate("AES-256-GCM", None)?; /// let message = b"test"; - /// + /// /// let options_handle = ctx.symmetric_options_open()?; /// ctx.symmetric_options_set(options_handle, "nonce", nonce)?; - /// + /// /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle), Some(options_handle))?; /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; /// ctx.symmetric_state_absorb(state_handle, "additional data")?; /// ctx.symmetric_state_encrypt(state_handle, &mut ciphertext, message)?; /// ``` - /// + /// /// - **AEAD encryption with automatic nonce generation** - /// + /// /// ```rust /// let key_handle = ctx.symmetric_key_generate("AES-256-GCM-SIV", None)?; /// let message = b"test"; /// let mut nonce = [0u8; 24]; - /// + /// /// let state_handle = ctx.symmetric_state_open("AES-256-GCM-SIV", Some(key_handle), None)?; - /// + /// /// let nonce = ctx.symmetric_state_options_get(state_handle, "nonce")?; - /// + /// /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; /// ctx.symmetric_state_absorb(state_handle, "additional data")?; /// ctx.symmetric_state_encrypt(state_handle, &mut ciphertext, message)?; /// ``` - /// + /// /// - **Session authenticated modes** - /// + /// /// ```rust /// let mut out = [0u8; 16]; /// let mut out2 = [0u8; 16]; @@ -290,242 +290,242 @@ interface wasi-ephemeral-crypto-symmetric { symmetric-state-open: func(algorithm: string, key: opt-symmetric-key, options: opt-options) -> result; /// Retrieve a parameter from the current state. - /// + /// /// In particular, `symmetric_state_options_get("nonce")` can be used to get a nonce that as automatically generated. - /// + /// /// The function may return `options_not_set` if an option was not set, which is different from an empty value. - /// + /// /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. - /// - /// + /// + /// /// TODO: Fix 'value'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-options-get: func(handle: symmetric-state, name: string, value: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, value-max-len: size) -> result; + symmetric-state-options-get: func(handle: symmetric-state, name: string, value: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, value-max-len: size) -> result; /// Retrieve an integer parameter from the current state. - /// + /// /// The function may return `options_not_set` if an option was not set. - /// + /// /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. symmetric-state-options-get-u64: func(handle: symmetric-state, name: string) -> result<%u64, crypto-errno>; /// Clone a symmetric state. - /// + /// /// The function clones the internal state, assigns a new handle to it and returns the new handle. symmetric-state-clone: func(handle: symmetric-state) -> result; /// Destroy a symmetric state. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. symmetric-state-close: func(handle: symmetric-state) -> result<_, crypto-errno>; /// Absorb data into the state. - /// + /// /// - **Hash functions:** adds data to be hashed. /// - **MAC functions:** adds data to be authenticated. /// - **Tuplehash-like constructions:** adds a new tuple to the state. /// - **Key derivation functions:** adds to the IKM or to the subkey information. /// - **AEAD constructions:** adds additional data to be authenticated. /// - **Stateful hash objects, permutation-based constructions:** absorbs. - /// + /// /// If the chosen algorithm doesn't accept input data, the `invalid_operation` error code is returned. - /// + /// /// If too much data has been fed for the algorithm, `overflow` may be thrown. - /// - /// + /// + /// /// TODO: Fix 'data'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-absorb: func(handle: symmetric-state, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result<_, crypto-errno>; + symmetric-state-absorb: func(handle: symmetric-state, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result<_, crypto-errno>; /// Squeeze bytes from the state. - /// + /// /// - **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. /// - **Key derivation functions:** : outputs an arbitrary-long derived key. /// - **RNGs, DRBGs, stream ciphers:**: outputs arbitrary-long data. /// - **Stateful hash objects, permutation-based constructions:** squeeze. - /// + /// /// Other kinds of algorithms may return `invalid_operation` instead. - /// + /// /// For password-stretching functions, the function may return `in_progress`. /// In that case, the guest should retry with the same parameters until the function completes. - /// - /// + /// + /// /// TODO: Fix 'out'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-squeeze: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size) -> result<_, crypto-errno>; + symmetric-state-squeeze: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size) -> result<_, crypto-errno>; /// Compute and return a tag for all the data injected into the state so far. - /// + /// /// - **MAC functions**: returns a tag authenticating the absorbed data. /// - **Tuplehash-like constructions:** returns a tag authenticating all the absorbed tuples. /// - **Password-hashing functions:** returns a standard string containing all the required parameters for password verification. - /// + /// /// Other kinds of algorithms may return `invalid_operation` instead. - /// + /// /// For password-stretching functions, the function may return `in_progress`. /// In that case, the guest should retry with the same parameters until the function completes. symmetric-state-squeeze-tag: func(handle: symmetric-state) -> result; /// Use the current state to produce a key for a target algorithm. - /// + /// /// For extract-then-expand constructions, this returns the PRK. /// For session-based authentication encryption, this returns a key that can be used to resume a session without storing a nonce. - /// + /// /// `invalid_operation` is returned for algorithms not supporting this operation. symmetric-state-squeeze-key: func(handle: symmetric-state, alg-str: string) -> result; /// Return the maximum length of an authentication tag for the current algorithm. - /// + /// /// This allows guests to compute the size required to store a ciphertext along with its authentication tag. - /// + /// /// The returned length may include the encryption mode's padding requirements in addition to the actual tag. - /// + /// /// For an encryption operation, the size of the output buffer should be `input_len + symmetric_state_max_tag_len()`. - /// + /// /// For a decryption operation, the size of the buffer that will store the decrypted data must be `ciphertext_len - symmetric_state_max_tag_len()`. symmetric-state-max-tag-len: func(handle: symmetric-state) -> result; /// Encrypt data with an attached 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. /// - **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. /// - **SHOE, Xoodyak, Strobe:** encrypts data, squeezes a tag and appends it to the output. - /// + /// /// If `out` and `data` are the same address, encryption may happen in-place. - /// + /// /// The function returns the actual size of the ciphertext along with the tag. - /// + /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// + /// + /// /// TODO: Fix 'out'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'data'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-encrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + symmetric-state-encrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result; /// Encrypt data, with a detached tag. - /// + /// /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. /// - **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. /// - **SHOE, Xoodyak, Strobe:** encrypts data and squeezes a tag. - /// + /// /// If `out` and `data` are the same address, encryption may happen in-place. - /// + /// /// The function returns the tag. - /// + /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// + /// + /// /// TODO: Fix 'out'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'data'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-encrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + symmetric-state-encrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result; /// - **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. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the one that was appended to the ciphertext. - /// + /// /// If `out` and `data` are the same address, decryption may happen in-place. - /// + /// /// `out_len` must be exactly `data_len` + `max_tag_len` bytes. - /// + /// /// The function returns the actual size of the decrypted message, which can be smaller than `out_len` for modes that requires padding. - /// + /// /// `invalid_tag` is returned if the tag didn't verify. - /// + /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// + /// + /// /// TODO: Fix 'out'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'data'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-decrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size) -> result; + symmetric-state-decrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result; /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the expected one. - /// + /// /// `raw_tag` is the expected tag, as raw bytes. - /// + /// /// `out` and `data` be must have the same length. /// If they also share the same address, decryption may happen in-place. - /// + /// /// The function returns the actual size of the decrypted message. - /// + /// /// `invalid_tag` is returned if the tag verification failed. - /// + /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// + /// + /// /// TODO: Fix 'out'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'data'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// + /// /// TODO: Fix 'raw-tag'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-decrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, data-len: size, raw-tag: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, raw-tag-len: size) -> result; + symmetric-state-decrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size, raw-tag: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, raw-tag-len: size) -> result; /// Make it impossible to recover the previous state. - /// + /// /// This operation is supported by some systems keeping a rolling state over an entire session, for forward security. - /// + /// /// `invalid_operation` is returned for algorithms not supporting ratcheting. symmetric-state-ratchet: func(handle: symmetric-state) -> result<_, crypto-errno>; /// Return the length of an authentication tag. - /// + /// /// This function can be used by a guest to allocate the correct buffer size to copy a computed authentication tag. symmetric-tag-len: func(symmetric-tag: symmetric-tag) -> result; /// Copy an authentication tag into a guest-allocated buffer. - /// + /// /// The handle automatically becomes invalid after this operation. Manually closing it is not required. - /// + /// /// Example usage: - /// + /// /// ```rust /// let mut raw_tag = [0u8; 16]; /// ctx.symmetric_tag_pull(raw_tag_handle, &mut raw_tag)?; /// ``` - /// + /// /// The function returns `overflow` if the supplied buffer is too small to copy the tag. - /// + /// /// Otherwise, it returns the number of bytes that have been copied. - /// - /// + /// + /// /// TODO: Fix 'buf'. /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-tag-pull: func(symmetric-tag: symmetric-tag, buf: todo-from-witx-value-pointer-value-builtin-u8--lang-c-char-false, buf-len: size) -> result; + symmetric-tag-pull: func(symmetric-tag: symmetric-tag, buf: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, buf-len: size) -> result; /// Verify that a computed authentication tag matches the expected value, in constant-time. - /// + /// /// The expected tag must be provided as a raw byte string. - /// + /// /// The function returns `invalid_tag` if the tags don't match. - /// + /// /// Example usage: - /// + /// /// ```rust /// let key_handle = ctx.symmetric_key_import("HMAC/SHA-256", b"key")?; /// let state_handle = ctx.symmetric_state_open("HMAC/SHA-256", Some(key_handle), None)?; @@ -533,17 +533,17 @@ interface wasi-ephemeral-crypto-symmetric { /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; /// ctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?; /// ``` - /// - /// + /// + /// /// TODO: Fix 'expected-raw-tag-ptr'. /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag-ptr: todo-from-witx-value-constpointer-value-builtin-u8--lang-c-char-false, expected-raw-tag-len: size) -> result<_, crypto-errno>; + symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag-ptr: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, expected-raw-tag-len: size) -> result<_, crypto-errno>; /// Explicitly destroy an unused authentication tag. - /// + /// /// This is usually not necessary, as `symmetric_tag_pull()` automatically closes a tag after it has been copied. - /// + /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. symmetric-tag-close: func(symmetric-tag: symmetric-tag) -> result<_, crypto-errno>; } From d54ddbaf17cc3aef53fabf4164f24240cbc2dddb Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 03:04:08 +0200 Subject: [PATCH 04/15] feat: add imports --- wit/{ => batch}/wasi_ephemeral_crypto_signatures_batch.wit | 2 ++ wit/{ => batch}/wasi_ephemeral_crypto_symmetric_batch.wit | 3 ++- wit/wasi_ephemeral_crypto_asymmetric_common.wit | 2 ++ wit/wasi_ephemeral_crypto_common.wit | 3 ++- wit/wasi_ephemeral_crypto_external_secrets.wit | 2 ++ wit/wasi_ephemeral_crypto_kx.wit | 2 ++ wit/wasi_ephemeral_crypto_signatures.wit | 2 ++ wit/wasi_ephemeral_crypto_symmetric.wit | 2 ++ wit/wasi_ephemeral_crypto_todo_types.wit | 6 ++++++ 9 files changed, 22 insertions(+), 2 deletions(-) rename wit/{ => batch}/wasi_ephemeral_crypto_signatures_batch.wit (93%) rename wit/{ => batch}/wasi_ephemeral_crypto_symmetric_batch.wit (97%) create mode 100644 wit/wasi_ephemeral_crypto_todo_types.wit diff --git a/wit/wasi_ephemeral_crypto_signatures_batch.wit b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit similarity index 93% rename from wit/wasi_ephemeral_crypto_signatures_batch.wit rename to wit/batch/wasi_ephemeral_crypto_signatures_batch.wit index 6251e37..4b749ee 100644 --- a/wit/wasi_ephemeral_crypto_signatures_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit @@ -1,6 +1,8 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures-batch { + use wasi-ephemeral-crypto-common.{array-output, crypto-errno, signature-verification-state, signature, signature-state}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// The result of a signature sign operation. A pair of the signature and an error code. type signature-sign-result = tuple; diff --git a/wit/wasi_ephemeral_crypto_symmetric_batch.wit b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit similarity index 97% rename from wit/wasi_ephemeral_crypto_symmetric_batch.wit rename to wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit index d0e2005..a3bd98d 100644 --- a/wit/wasi_ephemeral_crypto_symmetric_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit @@ -2,7 +2,8 @@ package wasi:crypto@0.0.1; /// Symmetric Batch Operations interface wasi-ephemeral-crypto-symmetric-batch { - /// An output buffer + use wasi-ephemeral-crypto-common.{out-buffer, size, in-buffer, crypto-errno, symmetric-tag, symmetric-state}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; type output = out-buffer; type output-len = size; diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit index 8143afc..d54d1c8 100644 --- a/wit/wasi_ephemeral_crypto_asymmetric_common.wit +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -1,6 +1,8 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-asymmetric-common { + use wasi-ephemeral-crypto-common.{algorithm-type, opt-options, keypair, crypto-errno, size, keypair-encoding, secrets-manager, version, publickey, secretkey, array-output, publickey-encoding, secretkey-encoding}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// Generate a new key pair. /// /// Internally, a key pair stores the supplied algorithm and optional parameters. diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index 7693831..4383c74 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -1,6 +1,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-common { + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// Error codes. variant crypto-errno { /// Operation succeeded. @@ -208,7 +209,7 @@ interface wasi-ephemeral-crypto-common { type version = u64; /// TODO: Constant - resource version { + resource version-const { /// Original Value: 18374686479671623680 /// Key doesn't support versioning. unspecified: func() -> u64; diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index c532394..8bd8253 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -11,6 +11,8 @@ package wasi:crypto@0.0.1; /// /// __(optional)__ interface wasi-ephemeral-crypto-external-secrets { + use wasi-ephemeral-crypto-common.{secrets-manager, size, timestamp, crypto-errno, version, array-output}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// Store an external secret into the secrets manager. /// /// `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index 50be389..b8cfbd3 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -1,6 +1,8 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-kx { + use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, array-output, crypto-errno, size}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// `$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`. diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 842d5d4..9219b3e 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -1,6 +1,8 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures { + use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, signature, signature-encoding, array-output, crypto-errno, size, signature-state, signature-verification-state}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// `$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`. diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index cdd9ca1..5fb4823 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -1,6 +1,8 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-symmetric { + use wasi-ephemeral-crypto-common.{opt-options, symmetric-key, crypto-errno, size, array-output, secrets-manager, version, opt-symmetric-key, symmetric-state, %u64, symmetric-tag}; + use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; /// Generate a new symmetric key for a given algorithm. /// /// `options` can be `None` to use the default parameters, or an algorithm-specific set of parameters to override. diff --git a/wit/wasi_ephemeral_crypto_todo_types.wit b/wit/wasi_ephemeral_crypto_todo_types.wit new file mode 100644 index 0000000..96f202b --- /dev/null +++ b/wit/wasi_ephemeral_crypto_todo_types.wit @@ -0,0 +1,6 @@ +package wasi:crypto@0.0.1; + +interface wasi-ephemeral-crypto-todo-types { + type todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false = string; + type todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false = string; +} From 78c782500043994149e928d1446b7003fd2a4da3 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 13:37:36 +0200 Subject: [PATCH 05/15] feat: move from handle derivatives to resources --- wit/wasi_ephemeral_crypto_common.wit | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index 4383c74..a5b4db4 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -230,9 +230,6 @@ interface wasi-ephemeral-crypto-common { /// A 64-bit value type %u64 = u64; - resource 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. @@ -241,54 +238,54 @@ interface wasi-ephemeral-crypto-common { /// 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. - type array-output = handle; + resource array-output {} /// 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. - type options = handle; + resource options {} /// A handle to the optional secrets management facilities offered by a host. /// /// This is used to generate, retrieve and invalidate managed keys. - type secrets-manager = handle; + resource secrets-manager {} /// A key pair. - type keypair = handle; + resource keypair {} /// 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. - type signature-state = handle; + resource signature-state {} /// A signature. - type signature = handle; + resource signature {} /// A public key, for key exchange and signature verification. - type publickey = handle; + resource publickey {} /// A secret key, for key exchange mechanisms. - type secretkey = handle; + resource secretkey {} /// A state to absorb signed data to be verified. - type signature-verification-state = handle; + resource signature-verification-state {} /// 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. - type symmetric-state = handle; + resource symmetric-state {} /// 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. - type symmetric-key = handle; + resource symmetric-key {} /// An authentication tag. /// @@ -299,7 +296,7 @@ interface wasi-ephemeral-crypto-common { /// This object type can't be directly created from raw bytes. They are only returned by functions computing MACs. /// /// The host is responsible for securely wiping them from memory on close. - type symmetric-tag = handle; + resource symmetric-tag {} /// Options index, only required by the Interface Types translation layer. variant opt-options-u { From bcce75451ad9ab31709513f167bcdf5c618622bd Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 18:49:53 +0200 Subject: [PATCH 06/15] feat: use list where possible --- wit/README.md | 37 +++++ ...asi_ephemeral_crypto_asymmetric_common.wit | 51 ++---- wit/wasi_ephemeral_crypto_common.wit | 47 ++---- ...wasi_ephemeral_crypto_external_secrets.wit | 61 ++------ wit/wasi_ephemeral_crypto_kx.wit | 9 +- wit/wasi_ephemeral_crypto_signatures.wit | 23 +-- wit/wasi_ephemeral_crypto_symmetric.wit | 147 +++--------------- 7 files changed, 103 insertions(+), 272 deletions(-) create mode 100644 wit/README.md diff --git a/wit/README.md b/wit/README.md new file mode 100644 index 0000000..6d90955 --- /dev/null +++ b/wit/README.md @@ -0,0 +1,37 @@ +## Made changes + +### Automatic + +| WITX Type / Construct | Target WIT Construct | Transpilation Details & Notes | +| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| **`TypeRef::Name`** | `Type::named(...)` | Map using kebab-case identifier. | +| **`BuiltinType::Char`** | `Type::Char` | Translated directly. | +| **`BuiltinType::U8 / U16 / U32 / U64`** | `Type::U8` to `Type::U64` | Translated directly. | +| **`BuiltinType::S8 / S16 / S32 / S64`** | `Type::S8` to `Type::S64` | Translated directly (Signed integer). | +| **`BuiltinType::F32 / F64`** | `Type::F32` / `Type::F64` | Translated directly (Floats). | +| **`Type::List(Type::Char)`** | `Type::String` | Special promotion applied (`list` -> `string`). | +| **`Type::List(T)`** | `Type::list` | Mapped to a WIT list. | +| **`Type::Variant` (Option style)** | `Type::option` | Recognized via `general_as_option`. | +| **`Type::Variant` (Expected style)** | `Type::result` | Recognized via `general_as_expected` (handles ok/err variations). | +| **`Type::Variant` (Enum style)** | `TypeDef::variant(...)` | Custom map to variant cases if items contain data, or simple enums if values are empty. | +| **`Type::Record` (Tuple style)** | `Type::tuple(...)` | Evaluated when `record.is_tuple()` is true. | +| **`Type::Record` (Bitflags)** | `TypeDef::flags(...)` | Evaluated when `record.bitflags_repr().is_some()`. | +| **`Type::Record` (Standard)** | `TypeDef::record(...)` | Maps fields to a named structure. | +| **`Type::Handle`** | `Type::named(...)` | Resolves to the name of the resource handle. | +| **`witx_module.constants()`** | `TypeDef::resource(...)` | **Workaround**: Grouped by type and modeled as a resource containing static-like `ResourceFunc::method` calls tagged with a `TODO` comment. | +| **`witx_module.resources()`** | `TypeDef::resource(...)` | Map to an isolated empty WIT resource type block. | +| **`witx_module.funcs()`** | `StandaloneFunc` | Maps parameters and the single return output. | +| **`Type::Pointer`** | **Not Supported** | ❌ Fails with `TranspileError::UnsupportedType`. Raw memory addresses are disallowed; recommend `list` or `resource`. | +| **`Type::ConstPointer`** | **Not Supported** | ❌ Fails with `TranspileError::UnsupportedType`. Raw memory addresses are disallowed; recommend `list` or `resource`. | + +### Manual + +| WITX Type / Construct | Target WIT Construct | Transpilation Details & Notes | +| --------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`Pointer + len` (Output buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed | +| **`ConstPointer + len` (Input buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed | +| **Version constants** | `variant` | | +| **`Variant`** without data | | | +| `type ... = handle` | `resource` | | +| **Imports** | `use use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | +| `wasm-tools component wit .` | diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit index d54d1c8..359b859 100644 --- a/wit/wasi_ephemeral_crypto_asymmetric_common.wit +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -2,7 +2,9 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-asymmetric-common { use wasi-ephemeral-crypto-common.{algorithm-type, opt-options, keypair, crypto-errno, size, keypair-encoding, secrets-manager, version, publickey, secretkey, array-output, publickey-encoding, secretkey-encoding}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + + type kp-id = list; + /// Generate a new key pair. /// /// Internally, a key pair stores the supplied algorithm and optional parameters. @@ -36,12 +38,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// ```rust /// let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?; /// ``` - /// - /// - /// TODO: Fix 'encoded'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: keypair-encoding) -> result; + keypair-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: list, encoding: keypair-encoding) -> result; /// __(optional)__ /// Generate a new managed key pair. @@ -61,16 +58,8 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// __(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. - /// - /// - /// TODO: Fix 'kp-id'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, kp-id-max-len: size) -> result<_, crypto-errno>; + /// On success, the function returns the key pair identifier + keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair) -> result; /// __(optional)__ /// Replace a managed key pair. @@ -101,12 +90,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// 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. - /// - /// - /// TODO: Fix 'kp-id'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-id: func(kp: keypair, kp-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, kp-id-max-len: size) -> result, crypto-errno>; + keypair-id: func(kp: keypair) -> result, crypto-errno>; /// __(optional)__ /// Return a managed key pair from a key identifier. @@ -116,12 +100,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// 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. - /// - /// - /// TODO: Fix 'kp-id'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - keypair-from-id: func(secrets-manager: secrets-manager, kp-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, kp-id-len: size, kp-version: version) -> result; + keypair-from-id: func(secrets-manager: secrets-manager, kp-id: kp-id, kp-version: version) -> result; /// Create a key pair from a public key and a secret key. keypair-from-pk-and-sk: func(publickey: publickey, secretkey: secretkey) -> result; @@ -157,12 +136,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// ```rust /// let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?; /// ``` - /// - /// - /// TODO: Fix 'encoded'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - publickey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: publickey-encoding) -> result; + publickey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: list, encoding: publickey-encoding) -> result; /// Export a public key as the given encoding format. /// @@ -197,12 +171,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// ```rust /// let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?; /// ``` - /// - /// - /// TODO: Fix 'encoded'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - secretkey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: secretkey-encoding) -> result; + secretkey-import: func(algorithm-type: algorithm-type, algorithm: string, encoded: list, encoding: secretkey-encoding) -> result; /// Export a secret key as the given encoding format. /// diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index a5b4db4..ac1cc1c 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -2,6 +2,9 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-common { use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + + type key-id = list; + /// Error codes. variant crypto-errno { /// Operation succeeded. @@ -204,21 +207,15 @@ interface wasi-ephemeral-crypto-common { } /// Version of a managed key. - /// - /// A version can be an arbitrary `u64` integer, with the exception of some reserved values. - type version = u64; - - /// TODO: Constant - resource version-const { - /// Original Value: 18374686479671623680 + variant version { /// Key doesn't support versioning. - unspecified: func() -> u64; - /// Original Value: 18374686479671623681 + unspecified, /// Use the latest version of a key. - latest: func() -> u64; - /// Original Value: 18374686479671623682 + latest, /// Perform an operation over all versions of a key. - all: func() -> u64; + all, + /// Specific version specifier + specified(u64) } /// Size of a value. @@ -343,12 +340,7 @@ interface wasi-ephemeral-crypto-common { /// This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - /// - /// - /// TODO: Fix 'value'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - options-set: func(handle: options, name: string, value: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, value-len: size) -> result<_, crypto-errno>; + options-set: func(handle: options, name: string, value: list) -> result<_, crypto-errno>; /// Set or update an integer option. /// @@ -378,7 +370,7 @@ interface wasi-ephemeral-crypto-common { /// /// Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. /// - /// The 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()`. + /// The function returns the copied bytes. A length of 0 means that the end of the stream has been reached. /// /// The handle is automatically closed after all the data has been consumed. /// @@ -386,15 +378,9 @@ interface wasi-ephemeral-crypto-common { /// /// ```rust /// let len = array_output_len(output_handle)?; - /// let mut out = vec![0u8; len]; - /// array_output_pull(output_handle, &mut out)?; + /// let out = array_output_pull(output_handle)?; /// ``` - /// - /// - /// TODO: Fix 'buf'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - array-output-pull: func(array-output: array-output, buf: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, buf-len: size) -> result; + array-output-pull: func(array-output: array-output) -> result, crypto-errno>; /// __(optional)__ /// Create a context to use a secrets manager. @@ -422,10 +408,5 @@ interface wasi-ephemeral-crypto-common { /// 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 key. /// /// This is an optional import, meaning that the function may not even exist. - /// - /// - /// TODO: Fix 'key-id'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - secrets-manager-invalidate: func(secrets-manager: secrets-manager, key-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, key-id-len: size, key-version: version) -> result<_, crypto-errno>; + secrets-manager-invalidate: func(secrets-manager: secrets-manager, key-id: key-id, key-version: version) -> result<_, crypto-errno>; } diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index 8bd8253..456fcaa 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -12,45 +12,28 @@ package wasi:crypto@0.0.1; /// __(optional)__ interface wasi-ephemeral-crypto-external-secrets { use wasi-ephemeral-crypto-common.{secrets-manager, size, timestamp, crypto-errno, version, array-output}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + + type secret-id = list; + /// Store an external secret into the secrets manager. /// - /// `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. + /// `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 output buffer is too small, `$overflow` is returned. + /// On success, the secret identifier is returned. /// /// If this function is not supported by the host the `$unsupported_feature` error is returned. - /// - /// - /// TODO: Fix 'secret'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'secret-id'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-store: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, secret-id-max-len: size) -> result<_, crypto-errno>; + external-secret-store: func(secrets-manager: secrets-manager, secret: list, expiration: timestamp) -> result; /// Replace a managed external secret with a new version. /// - /// `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. + /// `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. - /// - /// - /// TODO: Fix 'secret'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'secret-id'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-replace: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-len: size, expiration: timestamp, secret-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-id-len: size) -> result; + external-secret-replace: func(secrets-manager: secrets-manager, secret: list, expiration: timestamp) -> result, crypto-errno>; /// Get a copy of an external secret given an identifier and version. /// @@ -59,12 +42,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// 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. - /// - /// - /// TODO: Fix 'secret-id'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-from-id: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-id-len: size, secret-version: version) -> result; + external-secret-from-id: func(secrets-manager: secrets-manager, secret-id: secret-id, secret-version: version) -> result; /// Invalidate an external secret given an identifier and a version. /// @@ -73,12 +51,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// `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. - /// - /// - /// TODO: Fix 'secret-id'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-invalidate: func(secrets-manager: secrets-manager, secret-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-id-len: size, secret-version: version) -> result<_, crypto-errno>; + external-secret-invalidate: func(secrets-manager: secrets-manager, secret-id: secret-id, secret-version: version) -> result<_, crypto-errno>; /// Encrypt an external secret. /// @@ -87,22 +60,12 @@ interface wasi-ephemeral-crypto-external-secrets { /// However, the returned ciphertext must include and authenticate both the secret and the expiration date. /// /// On success, the ciphertext is returned. - /// - /// - /// TODO: Fix 'secret'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, secret-len: size, expiration: timestamp) -> result; + external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: list, expiration: timestamp) -> result; /// 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. - /// - /// - /// TODO: Fix 'encrypted-secret'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - external-secret-decapsulate: func(secrets-manager: secrets-manager, encrypted-secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encrypted-secret-len: size) -> result; + external-secret-decapsulate: func(secrets-manager: secrets-manager, encrypted-secret: list) -> result; } diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index b8cfbd3..6da8d3f 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -2,7 +2,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-kx { use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, array-output, crypto-errno, size}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + /// `$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`. @@ -37,10 +37,5 @@ interface wasi-ephemeral-crypto-kx { /// Decapsulate an encapsulated secret created with `kx_encapsulate` /// /// Return the secret, or `$crypto_errno.verification_failed` on error. - /// - /// - /// TODO: Fix 'encapsulated-secret'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - kx-decapsulate: func(sk: secretkey, encapsulated-secret: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encapsulated-secret-len: size) -> result; + kx-decapsulate: func(sk: secretkey, encapsulated-secret: list) -> result; } diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 9219b3e..3a9be01 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -2,7 +2,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures { use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, signature, signature-encoding, array-output, crypto-errno, size, signature-state, signature-verification-state}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + /// `$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`. @@ -38,12 +38,7 @@ interface wasi-ephemeral-crypto-signatures { /// ```rust /// let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", SignatureEncoding::DER, encoded)?; /// ``` - /// - /// - /// TODO: Fix 'encoded'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - signature-import: func(algorithm: string, encoded: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, encoded-len: size, encoding: signature-encoding) -> result; + signature-import: func(algorithm: string, encoded: list, encoding: signature-encoding) -> result; /// Create a new state to collect data to compute a signature on. /// @@ -66,12 +61,7 @@ interface wasi-ephemeral-crypto-signatures { /// Absorb data into the signature state. /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. - /// - /// - /// TODO: Fix 'input'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - signature-state-update: func(state: signature-state, input: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + signature-state-update: func(state: signature-state, input: list) -> result<_, crypto-errno>; /// Compute a signature for all the data collected up to that point. /// @@ -105,12 +95,7 @@ interface wasi-ephemeral-crypto-signatures { /// Absorb data into the signature verification state. /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. - /// - /// - /// TODO: Fix 'input'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - signature-verification-state-update: func(state: signature-verification-state, input: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, input-len: size) -> result<_, crypto-errno>; + signature-verification-state-update: func(state: signature-verification-state, input: list) -> result<_, crypto-errno>; /// Check that the given signature verifies for the data collected up to that point. /// diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index 5fb4823..7139cf7 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -2,7 +2,10 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-symmetric { use wasi-ephemeral-crypto-common.{opt-options, symmetric-key, crypto-errno, size, array-output, secrets-manager, version, opt-symmetric-key, symmetric-state, %u64, symmetric-tag}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + + // Would have liked to keep this `symmetric-key-id`, but that overlaps with the function name + type stored-key-id = list; + /// Generate a new symmetric key for a given algorithm. /// /// `options` can be `None` to use the default parameters, or an algorithm-specific set of parameters to override. @@ -15,12 +18,7 @@ interface wasi-ephemeral-crypto-symmetric { /// The 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`. /// /// The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. - /// - /// - /// TODO: Fix 'raw'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-import: func(algorithm: string, raw: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, raw-len: size) -> result; + symmetric-key-import: func(algorithm: string, raw: list) -> result; /// Export a symmetric key as raw material. /// @@ -52,16 +50,10 @@ interface wasi-ephemeral-crypto-symmetric { /// __(optional)__ /// Store a symmetric key into the secrets manager. /// - /// On success, the function stores the key identifier into `$symmetric_key_id`, - /// into which up to `$symmetric_key_id_max_len` can be written. - /// - /// The function returns `overflow` if the supplied buffer is too small. - /// + /// On success, the function returns the key identifier. /// - /// TODO: Fix 'symmetric-key-id'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, symmetric-key-id-max-len: size) -> result<_, crypto-errno>; + /// This is an optional import, meaning that the function may not even exist. + symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key) -> result; /// __(optional)__ /// Replace a managed symmetric key. @@ -92,12 +84,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If the key is not managed, `unsupported_feature` is returned instead. /// /// This is an optional import, meaning that the function may not even exist. - /// - /// - /// TODO: Fix 'symmetric-key-id'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-id: func(symmetric-key: symmetric-key, symmetric-key-id: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, symmetric-key-id-max-len: size) -> result, crypto-errno>; + symmetric-key-id: func(symmetric-key: symmetric-key) -> result, crypto-errno>; /// __(optional)__ /// Return a managed symmetric key from a key identifier. @@ -107,12 +94,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If no key matching the provided information is found, `not_found` is returned instead. /// /// This is an optional import, meaning that the function may not even exist. - /// - /// - /// TODO: Fix 'symmetric-key-id'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, symmetric-key-id-len: size, symmetric-key-version: version) -> result; + symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: stored-key-id, symmetric-key-version: version) -> result; /// Create a new state to absorb and produce data using symmetric operations. /// @@ -298,12 +280,7 @@ interface wasi-ephemeral-crypto-symmetric { /// The function may return `options_not_set` if an option was not set, which is different from an empty value. /// /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. - /// - /// - /// TODO: Fix 'value'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-options-get: func(handle: symmetric-state, name: string, value: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, value-max-len: size) -> result; + symmetric-state-options-get: func(handle: symmetric-state, name: string) -> result, crypto-errno>; /// Retrieve an integer parameter from the current state. /// @@ -334,12 +311,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If the chosen algorithm doesn't accept input data, the `invalid_operation` error code is returned. /// /// If too much data has been fed for the algorithm, `overflow` may be thrown. - /// - /// - /// TODO: Fix 'data'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-absorb: func(handle: symmetric-state, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result<_, crypto-errno>; + symmetric-state-absorb: func(handle: symmetric-state, data: list) -> result<_, crypto-errno>; /// Squeeze bytes from the state. /// @@ -352,12 +324,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// For password-stretching functions, the function may return `in_progress`. /// In that case, the guest should retry with the same parameters until the function completes. - /// - /// - /// TODO: Fix 'out'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-squeeze: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size) -> result<_, crypto-errno>; + symmetric-state-squeeze: func(handle: symmetric-state) -> result, crypto-errno>; /// Compute and return a tag for all the data injected into the state so far. /// @@ -396,21 +363,10 @@ interface wasi-ephemeral-crypto-symmetric { /// - **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. /// - **SHOE, Xoodyak, Strobe:** encrypts data, squeezes a tag and appends it to the output. /// - /// If `out` and `data` are the same address, encryption may happen in-place. - /// - /// The function returns the actual size of the ciphertext along with the tag. + /// The function returns the ciphertext along with the tag. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// - /// TODO: Fix 'out'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'data'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-encrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result; + symmetric-state-encrypt: func(handle: symmetric-state, data: list) -> result, crypto-errno>; /// Encrypt data, with a detached tag. /// @@ -418,45 +374,21 @@ interface wasi-ephemeral-crypto-symmetric { /// - **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. /// - **SHOE, Xoodyak, Strobe:** encrypts data and squeezes a tag. /// - /// If `out` and `data` are the same address, encryption may happen in-place. - /// - /// The function returns the tag. + /// The function returns the ciphertext and tag. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// - /// TODO: Fix 'out'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'data'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-encrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result; + symmetric-state-encrypt-detached: func(handle: symmetric-state, data: list) -> result, symmetric-tag>, crypto-errno>; /// - **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. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the one that was appended to the ciphertext. /// - /// If `out` and `data` are the same address, decryption may happen in-place. - /// - /// `out_len` must be exactly `data_len` + `max_tag_len` bytes. - /// - /// The function returns the actual size of the decrypted message, which can be smaller than `out_len` for modes that requires padding. + /// The function returns the decrypted message. /// /// `invalid_tag` is returned if the tag didn't verify. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// - /// TODO: Fix 'out'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'data'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-decrypt: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size) -> result; + symmetric-state-decrypt: func(handle: symmetric-state, data: list) -> result, crypto-errno>; /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. @@ -464,28 +396,12 @@ interface wasi-ephemeral-crypto-symmetric { /// /// `raw_tag` is the expected tag, as raw bytes. /// - /// `out` and `data` be must have the same length. - /// If they also share the same address, decryption may happen in-place. - /// - /// The function returns the actual size of the decrypted message. + /// The function returns the decrypted message. /// /// `invalid_tag` is returned if the tag verification failed. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - /// - /// - /// TODO: Fix 'out'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'data'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - /// - /// TODO: Fix 'raw-tag'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-state-decrypt-detached: func(handle: symmetric-state, out: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, out-len: size, data: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, data-len: size, raw-tag: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, raw-tag-len: size) -> result; + symmetric-state-decrypt-detached: func(handle: symmetric-state, data: list, raw-tag: list) -> result, crypto-errno>; /// Make it impossible to recover the previous state. /// @@ -506,19 +422,9 @@ interface wasi-ephemeral-crypto-symmetric { /// Example usage: /// /// ```rust - /// let mut raw_tag = [0u8; 16]; - /// ctx.symmetric_tag_pull(raw_tag_handle, &mut raw_tag)?; + /// let raw_tag = ctx.symmetric_tag_pull(raw_tag_handle)?; /// ``` - /// - /// The function returns `overflow` if the supplied buffer is too small to copy the tag. - /// - /// Otherwise, it returns the number of bytes that have been copied. - /// - /// - /// TODO: Fix 'buf'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-tag-pull: func(symmetric-tag: symmetric-tag, buf: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, buf-len: size) -> result; + symmetric-tag-pull: func(symmetric-tag: symmetric-tag) -> result, crypto-errno>; /// Verify that a computed authentication tag matches the expected value, in constant-time. /// @@ -535,12 +441,7 @@ interface wasi-ephemeral-crypto-symmetric { /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; /// ctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?; /// ``` - /// - /// - /// TODO: Fix 'expected-raw-tag-ptr'. - /// Original WITX: Value(ConstPointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag-ptr: todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, expected-raw-tag-len: size) -> result<_, crypto-errno>; + symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag: list) -> result<_, crypto-errno>; /// Explicitly destroy an unused authentication tag. /// From a129d2622259130bdd9d2abd5209effe6b641676 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 23:37:26 +0200 Subject: [PATCH 07/15] feat: add workaround for options-set-guest-buffer --- wit/wasi_ephemeral_crypto_common.wit | 16 +++++++--------- wit/wasi_ephemeral_crypto_todo_types.wit | 6 ------ 2 files changed, 7 insertions(+), 15 deletions(-) delete mode 100644 wit/wasi_ephemeral_crypto_todo_types.wit diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index ac1cc1c..09d5420 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -1,8 +1,6 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-common { - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; - type key-id = list; /// Error codes. @@ -349,17 +347,17 @@ interface wasi-ephemeral-crypto-common { /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. options-set-u64: func(handle: options, name: string, value: u64) -> result<_, crypto-errno>; - /// Set or update a guest-allocated memory that the host can use or return data into. + /// Set or update buffer that the host can use or return data into. /// /// This is for example used to set the scratch buffer required by memory-hard functions. /// - /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - /// + /// NOTE: In WITX, this was a raw pointer into guest linear memory, ensuring the allocation counted against the guest's memory budget. + /// This implementation using `list` does not have this guarantee and serves as a stopgap till [caller-supplied buffers](https://wasi.dev/roadmap) arrive in future WASI 0.3.x release. /// - /// TODO: Fix 'buffer'. - /// Original WITX: Value(Pointer(Value(Builtin(U8 { lang_c_char: false })))). - /// Reason: WIT does not support raw memory addresses. Use 'list' or 'resource'. - options-set-guest-buffer: func(handle: options, name: string, buffer: todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false, buffer-len: size) -> result<_, crypto-errno>; + /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. + @deprecated(version = 0.0.1) + @since(version = 0.0.1) + options-set-guest-buffer: func(handle: options, name: string, buffer: list) -> result<_, crypto-errno>; /// Return the length of an `array_output` object. /// diff --git a/wit/wasi_ephemeral_crypto_todo_types.wit b/wit/wasi_ephemeral_crypto_todo_types.wit deleted file mode 100644 index 96f202b..0000000 --- a/wit/wasi_ephemeral_crypto_todo_types.wit +++ /dev/null @@ -1,6 +0,0 @@ -package wasi:crypto@0.0.1; - -interface wasi-ephemeral-crypto-todo-types { - type todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false = string; - type todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false = string; -} From a792f44ec3c484775816d80a904e30f0e7c8c864 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 2 Jun 2026 23:54:15 +0200 Subject: [PATCH 08/15] feat: change variants without data to enums --- wit/wasi_ephemeral_crypto_common.wit | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index 09d5420..6bf62e9 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -150,7 +150,7 @@ interface wasi-ephemeral-crypto-common { expired, } /// Encoding to use for importing or exporting a key pair. - variant keypair-encoding { + enum keypair-encoding { /// Raw bytes. raw, /// PKCS8/DER encoding. @@ -162,7 +162,7 @@ interface wasi-ephemeral-crypto-common { } /// Encoding to use for importing or exporting a public key. - variant publickey-encoding { + enum publickey-encoding { /// Raw bytes. raw, /// PKCS8/DER encoding. @@ -176,7 +176,7 @@ interface wasi-ephemeral-crypto-common { } /// Encoding to use for importing or exporting a secret key. - variant secretkey-encoding { + enum secretkey-encoding { /// Raw bytes. raw, /// PKCS8/DER encoding. @@ -190,7 +190,7 @@ interface wasi-ephemeral-crypto-common { } /// Encoding to use for importing or exporting a signature. - variant signature-encoding { + enum signature-encoding { /// Raw bytes. raw, /// DER encoding. @@ -198,7 +198,7 @@ interface wasi-ephemeral-crypto-common { } /// An algorithm category. - variant algorithm-type { + enum algorithm-type { signatures, symmetric, key-exchange, @@ -294,7 +294,7 @@ interface wasi-ephemeral-crypto-common { resource symmetric-tag {} /// Options index, only required by the Interface Types translation layer. - variant opt-options-u { + enum opt-options-u { some, none, } @@ -305,7 +305,7 @@ interface wasi-ephemeral-crypto-common { type opt-options = option; /// Symmetric key index, only required by the Interface Types translation layer. - variant opt-symmetric-key-u { + enum opt-symmetric-key-u { some, none, } From fc6932c02ee40d9363e35daaee3da688c25bb34e Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Wed, 3 Jun 2026 00:00:59 +0200 Subject: [PATCH 09/15] chore: run wit idl VS Code formatter --- ...wasi_ephemeral_crypto_signatures_batch.wit | 44 +++++----- .../wasi_ephemeral_crypto_symmetric_batch.wit | 88 +++++++++---------- ...wasi_ephemeral_crypto_external_secrets.wit | 2 +- wit/wasi_ephemeral_crypto_kx.wit | 2 +- 4 files changed, 68 insertions(+), 68 deletions(-) diff --git a/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit index 4b749ee..15ca4cc 100644 --- a/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit @@ -10,7 +10,7 @@ interface wasi-ephemeral-crypto-signatures-batch { type signature-results = list; /// A tuple of a signature verification state and the signature to verify. - /// + /// /// Used for grouping signature verification state to be verified with the signature to verify. /// Used with batch_signature_state_verify(). type signature-verification-input = tuple; @@ -18,82 +18,82 @@ interface wasi-ephemeral-crypto-signatures-batch { type signature-verification-results = list; /// Compute a batch of signatures. - /// + /// /// This is a batch version of the signature_state_sign operation and is an extension of the wasi_ephemeral_crypto_signatures module. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result of each operation in the batch /// is a pair of a $crypto_errno error code and a signature. The error code /// indicates if that operation succeeded or failed. The signature is only /// valid if the error code indicates success. - /// + /// /// Example usage: - /// + /// /// ```rust /// let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; - /// + /// /// let mut state_handles = Vec::new(); - /// + /// /// let state_handle = signature_state_open(kp_handle)?; /// signature_state_update(state_handle, b"message part 1")?; /// signature_state_update(state_handle, b"message part 2")?; /// state_handles.push(state_handle); - /// + /// /// let state_handle = signature_state_open(kp_handle)?; /// signature_state_update(state_handle, b"message part 1")?; /// signature_state_update(state_handle, b"message part 2")?; /// state_handles.push(state_handle); - /// + /// /// let sig_handles = batch_signature_state_sign(state_handles)?; - /// + /// /// let raw_sig1 = signature_export(sig_handle[0], SignatureEncoding::Raw)?; /// let raw_sig2 = signature_export(sig_handle[1], SignatureEncoding::Raw)?; /// ``` batch-signature-state-sign: func(states: list) -> result; /// Verify a batch of signatures. - /// + /// /// This is a batch version of the signature_state_verify operation and is /// an extension of the wasi_ephemeral_crypto_signatures module. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed (`success`) or if the batch could /// not be processed. - /// + /// /// Batch processing failure cases are: /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, a list of verification results is produced. /// Each entry in the input list has a corresponding error state returned /// in the verification results list to indicate if the verification /// succeeded or encountered an error. - /// + /// /// Example usage: - /// + /// /// ```rust /// let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; - /// + /// /// let mut batch = Vec::new(); - /// + /// /// let state_handle = signature_verification_state_open(kp_handle)?; /// signature_verification_state_update(state_handle, b"message part 1")?; /// signature_verification_state_update(state_handle, b"message part 2")?; /// state_handles.push((state_handle, signature1)); - /// + /// /// let state_handle = signature_verification_state_open(kp_handle)?; /// signature_verification_state_update(state_handle, b"message part 1")?; /// signature_verification_state_update(state_handle, b"message part 2")?; /// state_handles.push((state_handle, signature2)); - /// + /// /// let results = batch_signature_state_verify(state_handles)?; /// ``` batch-signature-state-verify: func(states: list) -> result; diff --git a/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit index a3bd98d..b7a9639 100644 --- a/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit @@ -37,71 +37,71 @@ interface wasi-ephemeral-crypto-symmetric-batch { type batch-squeeze-detached-results = list; /// Batch of operations to squeeze bytes from a batch of states. - /// + /// /// This is a batch version of the $symmetric_state_squeeze operation. - /// + /// /// Each entry in the batch corresponds to an individual squeeze operation. /// The parameters associated with each operation are grouped into a tuple. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result is a list of $crypto_errno error /// codes that represent the status of the operation in the input list at /// the same list offset. - /// + /// batch-symmetric-state-squeeze: func(batch: list>) -> result; /// Batch of operations to compute and return a tag for all the data /// injected into the state so far. - /// + /// /// This is a batch version of the $symmetric_state_squeeze_tag operation. - /// + /// /// Each entry in the batch corresponds to an individual squeeze_tag /// operation. The parameters associated with each operation are grouped /// into a tuple. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result is a list of tuples, with each /// list entry corresponding to the operation in the input list at the same /// list offset. Each tuple contains a $crypto_errno error code and a tag. /// The error code represents the status of the operation and the tag is the /// tag generated from the squeeze operation. The tag is only valid if the /// tuple's error code is `success`. - /// + /// batch-symmetric-state-squeeze-tag: func(states: list) -> result; /// Perform a batch of symmetric encrypt operations. - /// + /// /// This is a batch version of the symmetric_state_encrypt operation. - /// + /// /// Each entry in the batch corresponds to an individual encrypt operation. /// The parameters associated with each encrypt operation are grouped into a /// tuple. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result is a list of tuples, with each /// list entry corresponding to the operation in the input list at the same /// list offset. @@ -109,42 +109,42 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// The error code represents the status of the operation and the size is /// the actual size of the ciphertext and the tag in the output buffer. The /// size value is only valid if the tuple's error code is `success`. - /// + /// /// Example usage: - /// + /// /// ```rust /// let mut batch = Vec::new(); - /// + /// /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); - /// + /// /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; /// let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); - /// + /// /// let results = ctx.batch_symmetric_state_encrypt(batch)?; /// ``` batch-symmetric-state-encrypt: func(batch: list>) -> result; /// Perform a batch of symmetric encrypt operations with detached tags. - /// + /// /// This is a batch version of the symmetric_state_encrypt_detached /// operation. - /// + /// /// Each entry in the batch corresponds to an individual encrypt operation. /// The parameters associated with each encrypt operation are grouped into a /// tuple. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result is a list of tuples, with each /// list entry corresponding to the operation in the input list at the same /// list offset. @@ -152,41 +152,41 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// The error code represents the status of the operation and the tag is /// the tag generated by the operation. The tag is only valid if the tuple's /// error code is `success`. - /// + /// /// Example usage: - /// + /// /// ```rust /// let mut batch = Vec::new(); - /// + /// /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; /// let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); - /// + /// /// let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; /// let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; /// batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); - /// + /// /// let results = ctx.batch_symmetric_state_encrypt_detached(batch)?; /// ``` batch-symmetric-state-encrypt-detached: func(batch: list>) -> result; /// Perform a batch of symmetric decrypt operations. - /// + /// /// This is a batch version of the symmetric_state_decrypt operation. - /// + /// /// Each entry in the batch corresponds to an individual decrypt operation. /// The parameters associated with each decrypt operation are grouped into a /// tuple. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result is a list of tuples, with each /// list entry corresponding to the operation in the input list at the same /// list offset. @@ -194,25 +194,25 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// The error code represents the status of the operation and the size is /// the actual size of the decrypted data in the output buffer. The size /// value is only valid if the tuple's error code is `success`. - /// + /// batch-symmetric-state-decrypt: func(batch: list>) -> result; /// Perform a batch of symmetric decrypt operations with detached tags. - /// + /// /// This is a batch version of the symmetric_state_decrypt_detached operation. - /// + /// /// Each entry in the batch corresponds to an individual decrypt operation. /// The parameters associated with each decrypt operation are grouped into a /// tuple. - /// + /// /// The batch operation returns an error code of type $crypto_errno that /// indicates if the batch was processed or if the batch could not be /// processed. - /// + /// /// Batch processing error codes: /// - `success`: Batch was processed. The status of each operation is indicated in the results list. /// - `not_implemented`: Batch functionality is not supported. /// - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. - /// + /// /// If the batch was processed, the result is a list of tuples, with each /// list entry corresponding to the operation in the input list at the same /// list offset. @@ -220,6 +220,6 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// The error code represents the status of the operation and the size is /// the actual size of the decrypted data in the output buffer. The size /// value is only valid if the tuple's error code is `success`. - /// + /// batch-symmetric-state-decrypt-detached: func(batch: list>) -> result; } diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index 456fcaa..6048ec8 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -14,7 +14,7 @@ interface wasi-ephemeral-crypto-external-secrets { use wasi-ephemeral-crypto-common.{secrets-manager, size, timestamp, crypto-errno, version, array-output}; type secret-id = list; - + /// Store an external secret into the secrets manager. /// /// `expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index 6da8d3f..2957562 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -2,7 +2,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-kx { use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, array-output, crypto-errno, size}; - + /// `$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`. From 85184efd5ab7c078e82f3f93cf546895d20f9564 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Wed, 3 Jun 2026 01:41:23 +0200 Subject: [PATCH 10/15] feat: add borrowing where required These are made to mimick the current conventions from witx. In WIT we would normally use destructors instead of close methods, but I'll keep that change for a follow-up PR. This also required removal of the opt-options and opt-symmetric key because they cant be borrowed. --- ...asi_ephemeral_crypto_asymmetric_common.wit | 30 +++++------ wit/wasi_ephemeral_crypto_common.wit | 22 ++++---- ...wasi_ephemeral_crypto_external_secrets.wit | 14 ++--- wit/wasi_ephemeral_crypto_kx.wit | 6 +-- wit/wasi_ephemeral_crypto_signatures.wit | 16 +++--- wit/wasi_ephemeral_crypto_symmetric.wit | 52 +++++++++---------- 6 files changed, 70 insertions(+), 70 deletions(-) diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit index 359b859..072e16a 100644 --- a/wit/wasi_ephemeral_crypto_asymmetric_common.wit +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -1,7 +1,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-asymmetric-common { - use wasi-ephemeral-crypto-common.{algorithm-type, opt-options, keypair, crypto-errno, size, keypair-encoding, secrets-manager, version, publickey, secretkey, array-output, publickey-encoding, secretkey-encoding}; + use wasi-ephemeral-crypto-common.{algorithm-type, options, keypair, crypto-errno, size, keypair-encoding, secrets-manager, version, publickey, secretkey, array-output, publickey-encoding, secretkey-encoding}; type kp-id = list; @@ -23,7 +23,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// ```rust /// let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?; /// ``` - keypair-generate: func(algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; + keypair-generate: func(algorithm-type: algorithm-type, algorithm: string, options: option>) -> result; /// Import a key pair. /// @@ -53,13 +53,13 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// 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-generate-managed: func(secrets-manager: secrets-manager, algorithm-type: algorithm-type, algorithm: string, options: opt-options) -> result; + keypair-generate-managed: func(secrets-manager: borrow, algorithm-type: algorithm-type, algorithm: string, options: option>) -> result; /// __(optional)__ /// Store a key pair into the secrets manager. /// /// On success, the function returns the key pair identifier - keypair-store-managed: func(secrets-manager: secrets-manager, kp: keypair) -> result; + keypair-store-managed: func(secrets-manager: borrow, kp: borrow) -> result; /// __(optional)__ /// Replace a managed key pair. @@ -82,7 +82,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// If the operation succeeded, the new version is returned. /// /// This is an optional import, meaning that the function may not even exist. - keypair-replace-managed: func(secrets-manager: secrets-manager, kp-old: keypair, kp-new: keypair) -> result; + keypair-replace-managed: func(secrets-manager: borrow, kp-old: keypair, kp-new: borrow) -> result; /// __(optional)__ /// Return the key pair identifier and version of a managed key pair. @@ -90,7 +90,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// 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-id: func(kp: keypair) -> result, crypto-errno>; + keypair-id: func(kp: borrow) -> result, crypto-errno>; /// __(optional)__ /// Return a managed key pair from a key identifier. @@ -100,21 +100,21 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// 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-id: func(secrets-manager: secrets-manager, kp-id: kp-id, kp-version: version) -> result; + keypair-from-id: func(secrets-manager: borrow, kp-id: kp-id, kp-version: version) -> result; /// Create a key pair from a public key and a secret key. - keypair-from-pk-and-sk: func(publickey: publickey, secretkey: secretkey) -> result; + keypair-from-pk-and-sk: func(publickey: borrow, secretkey: borrow) -> result; /// 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-export: func(kp: keypair, encoding: keypair-encoding) -> result; + keypair-export: func(kp: borrow, encoding: keypair-encoding) -> result; /// Get the public key of a key pair. - keypair-publickey: func(kp: keypair) -> result; + keypair-publickey: func(kp: borrow) -> result; /// Get the secret key of a key pair. - keypair-secretkey: func(kp: keypair) -> result; + keypair-secretkey: func(kp: borrow) -> result; /// Destroy a key pair. /// @@ -141,17 +141,17 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Export a public key as the given encoding format. /// /// May return `unsupported_encoding` if the encoding is not supported. - publickey-export: func(pk: publickey, encoding: publickey-encoding) -> result; + publickey-export: func(pk: borrow, encoding: publickey-encoding) -> result; /// 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-verify: func(pk: publickey) -> result<_, crypto-errno>; + publickey-verify: func(pk: borrow) -> result<_, crypto-errno>; /// Compute the public key for a secret key. - publickey-from-secretkey: func(sk: secretkey) -> result; + publickey-from-secretkey: func(sk: borrow) -> result; /// Destroy a public key. /// @@ -176,7 +176,7 @@ interface wasi-ephemeral-crypto-asymmetric-common { /// Export a secret key as the given encoding format. /// /// May return `unsupported_encoding` if the encoding is not supported. - secretkey-export: func(sk: secretkey, encoding: secretkey-encoding) -> result; + secretkey-export: func(sk: borrow, encoding: secretkey-encoding) -> result; /// Destroy a secret key. /// diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index 6bf62e9..a7dd707 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -302,6 +302,8 @@ interface wasi-ephemeral-crypto-common { /// An optional options set. /// /// This union simulates an `Option` type to make the `options` parameter of some functions optional. + @deprecated(version = 0.0.1) + @since(version = 0.0.1) type opt-options = option; /// Symmetric key index, only required by the Interface Types translation layer. @@ -313,6 +315,8 @@ interface wasi-ephemeral-crypto-common { /// An optional symmetric key. /// /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. + @deprecated(version = 0.0.1) + @since(version = 0.0.1) type opt-symmetric-key = option; /// Create a new object to set non-default options. @@ -329,23 +333,21 @@ interface wasi-ephemeral-crypto-common { options-open: func(algorithm-type: algorithm-type) -> result; /// Destroy an options object. - /// - /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. - options-close: func(handle: options) -> result<_, crypto-errno>; + options-close: func(options: options) -> result<_, crypto-errno>; /// Set or update an option. /// /// This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - options-set: func(handle: options, name: string, value: list) -> result<_, crypto-errno>; + options-set: func(options: borrow, name: string, value: list) -> result<_, crypto-errno>; /// Set or update an integer option. /// /// This is used to set algorithm-specific parameters. /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - options-set-u64: func(handle: options, name: string, value: u64) -> result<_, crypto-errno>; + options-set-u64: func(options: borrow, name: string, value: u64) -> result<_, crypto-errno>; /// Set or update buffer that the host can use or return data into. /// @@ -357,12 +359,12 @@ interface wasi-ephemeral-crypto-common { /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. @deprecated(version = 0.0.1) @since(version = 0.0.1) - options-set-guest-buffer: func(handle: options, name: string, buffer: list) -> result<_, crypto-errno>; + options-set-guest-buffer: func(options: borrow, name: string, buffer: list) -> result<_, crypto-errno>; /// Return the length of an `array_output` object. /// /// This allows a guest to allocate a buffer of the correct size in order to copy the output of a function returning this object type. - array-output-len: func(array-output: array-output) -> result; + array-output-len: func(array-output: borrow) -> result; /// Copy the content of an `array_output` object into an application-allocated buffer. /// @@ -378,7 +380,7 @@ interface wasi-ephemeral-crypto-common { /// let len = array_output_len(output_handle)?; /// let out = array_output_pull(output_handle)?; /// ``` - array-output-pull: func(array-output: array-output) -> result, crypto-errno>; + array-output-pull: func(array-output: borrow) -> result, crypto-errno>; /// __(optional)__ /// Create a context to use a secrets manager. @@ -387,7 +389,7 @@ interface wasi-ephemeral-crypto-common { /// /// The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. /// This is also an optional import, meaning that the function may not even exist. - secrets-manager-open: func(options: opt-options) -> result; + secrets-manager-open: func(options: option>) -> result; /// __(optional)__ /// Destroy a secrets manager context. @@ -406,5 +408,5 @@ interface wasi-ephemeral-crypto-common { /// 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 key. /// /// This is an optional import, meaning that the function may not even exist. - secrets-manager-invalidate: func(secrets-manager: secrets-manager, key-id: key-id, key-version: version) -> result<_, crypto-errno>; + secrets-manager-invalidate: func(secrets-manager: borrow, key-id: key-id, key-version: version) -> result<_, crypto-errno>; } diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index 6048ec8..d1384ee 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -7,7 +7,7 @@ package wasi:crypto@0.0.1; /// /// Alternatively, the secrets manager can encrypt them, and applications will supply the ciphertext get the original secret back. /// -/// The whole module is optional. +/// The whole interface is optional. /// /// __(optional)__ interface wasi-ephemeral-crypto-external-secrets { @@ -23,7 +23,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// On success, the secret identifier is returned. /// /// If this function is not supported by the host the `$unsupported_feature` error is returned. - external-secret-store: func(secrets-manager: secrets-manager, secret: list, expiration: timestamp) -> result; + external-secret-store: func(secrets-manager: borrow, secret: list, expiration: timestamp) -> result; /// Replace a managed external secret with a new version. /// @@ -33,7 +33,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// 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-replace: func(secrets-manager: secrets-manager, secret: list, expiration: timestamp) -> result, crypto-errno>; + external-secret-replace: func(secrets-manager: borrow, secret: list, expiration: timestamp) -> result, crypto-errno>; /// Get a copy of an external secret given an identifier and version. /// @@ -42,7 +42,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// 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-from-id: func(secrets-manager: secrets-manager, secret-id: secret-id, secret-version: version) -> result; + external-secret-from-id: func(secrets-manager: borrow, secret-id: secret-id, secret-version: version) -> result; /// Invalidate an external secret given an identifier and a version. /// @@ -51,7 +51,7 @@ interface wasi-ephemeral-crypto-external-secrets { /// `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-invalidate: func(secrets-manager: secrets-manager, secret-id: secret-id, secret-version: version) -> result<_, crypto-errno>; + external-secret-invalidate: func(secrets-manager: borrow, secret-id: secret-id, secret-version: version) -> result<_, crypto-errno>; /// Encrypt an external secret. /// @@ -60,12 +60,12 @@ interface wasi-ephemeral-crypto-external-secrets { /// However, the returned ciphertext must include and authenticate both the secret and the expiration date. /// /// On success, the ciphertext is returned. - external-secret-encapsulate: func(secrets-manager: secrets-manager, secret: list, expiration: timestamp) -> result; + external-secret-encapsulate: func(secrets-manager: borrow, secret: list, expiration: timestamp) -> result; /// 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. - external-secret-decapsulate: func(secrets-manager: secrets-manager, encrypted-secret: list) -> result; + external-secret-decapsulate: func(secrets-manager: borrow, encrypted-secret: list) -> result; } diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index 2957562..88a1dcf 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -24,7 +24,7 @@ interface wasi-ephemeral-crypto-kx { /// 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. /// /// Otherwise, a raw shared key is returned, and can be imported as a symmetric key. - kx-dh: func(pk: publickey, sk: secretkey) -> result; + kx-dh: func(pk: borrow, sk: borrow) -> result; /// Create a shared secret and encrypt it for the given public key. /// @@ -32,10 +32,10 @@ interface wasi-ephemeral-crypto-kx { /// 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-encapsulate: func(pk: publickey) -> result, crypto-errno>; + kx-encapsulate: func(pk: borrow) -> result, crypto-errno>; /// Decapsulate an encapsulated secret created with `kx_encapsulate` /// /// Return the secret, or `$crypto_errno.verification_failed` on error. - kx-decapsulate: func(sk: secretkey, encapsulated-secret: list) -> result; + kx-decapsulate: func(sk: borrow, encapsulated-secret: list) -> result; } diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 3a9be01..21eb292 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -23,7 +23,7 @@ interface wasi-ephemeral-crypto-signatures { /// 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-export: func(signature: signature, encoding: signature-encoding) -> result; + signature-export: func(signature: borrow, encoding: signature-encoding) -> result; /// Create a signature object. /// @@ -56,17 +56,17 @@ interface wasi-ephemeral-crypto-signatures { /// let sig_handle = ctx.signature_state_sign(state_handle)?; /// let raw_sig = ctx.signature_export(sig_handle, SignatureEncoding::Raw)?; /// ``` - signature-state-open: func(kp: signature-keypair) -> result; + signature-state-open: func(kp: borrow) -> result; /// Absorb data into the signature state. /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. - signature-state-update: func(state: signature-state, input: list) -> result<_, crypto-errno>; + signature-state-update: func(state: borrow, input: list) -> result<_, crypto-errno>; /// Compute a signature for all the data collected up to that point. /// /// The function can be called multiple times for incremental signing. - signature-state-sign: func(state: signature-state) -> result; + signature-state-sign: func(state: borrow) -> result; /// Destroy a signature state. /// @@ -90,19 +90,19 @@ interface wasi-ephemeral-crypto-signatures { /// ctx.signature_verification_state_update(state_handle, "message")?; /// ctx.signature_verification_state_verify(state_handle, signature_handle)?; /// ``` - signature-verification-state-open: func(kp: signature-publickey) -> result; + signature-verification-state-open: func(kp: borrow) -> result; /// Absorb data into the signature verification state. /// /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. - signature-verification-state-update: func(state: signature-verification-state, input: list) -> result<_, crypto-errno>; + signature-verification-state-update: func(state: borrow, input: list) -> result<_, crypto-errno>; /// Check that the given signature verifies for the data collected up to that 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-verify: func(state: signature-verification-state, signature: signature) -> result<_, crypto-errno>; + signature-verification-state-verify: func(state: borrow, signature: signature) -> result<_, crypto-errno>; /// Destroy a signature verification state. /// @@ -112,7 +112,5 @@ interface wasi-ephemeral-crypto-signatures { signature-verification-state-close: func(state: signature-verification-state) -> result<_, crypto-errno>; /// Destroy a signature. - /// - /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. signature-close: func(signature: signature) -> result<_, crypto-errno>; } diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index 7139cf7..c17fd9a 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -1,7 +1,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-symmetric { - use wasi-ephemeral-crypto-common.{opt-options, symmetric-key, crypto-errno, size, array-output, secrets-manager, version, opt-symmetric-key, symmetric-state, %u64, symmetric-tag}; + use wasi-ephemeral-crypto-common.{options, symmetric-key, crypto-errno, size, array-output, secrets-manager, version, symmetric-state, %u64, symmetric-tag}; // Would have liked to keep this `symmetric-key-id`, but that overlaps with the function name type stored-key-id = list; @@ -11,7 +11,7 @@ interface wasi-ephemeral-crypto-symmetric { /// `options` can be `None` to use the default parameters, or an algorithm-specific set of parameters to override. /// /// This 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. - symmetric-key-generate: func(algorithm: string, options: opt-options) -> result; + symmetric-key-generate: func(algorithm: string, options: option>) -> result; /// Create a symmetric key from raw material. /// @@ -25,7 +25,7 @@ interface wasi-ephemeral-crypto-symmetric { /// This is mainly useful to export a managed key. /// /// May return `prohibited_operation` if this operation is denied. - symmetric-key-export: func(symmetric-key: symmetric-key) -> result; + symmetric-key-export: func(symmetric-key: borrow) -> result; /// Destroy a symmetric key. /// @@ -45,7 +45,7 @@ interface wasi-ephemeral-crypto-symmetric { /// 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. - symmetric-key-generate-managed: func(secrets-manager: secrets-manager, algorithm: string, options: opt-options) -> result; + symmetric-key-generate-managed: func(secrets-manager: borrow, algorithm: string, options: option>) -> result; /// __(optional)__ /// Store a symmetric key into the secrets manager. @@ -53,7 +53,7 @@ interface wasi-ephemeral-crypto-symmetric { /// On success, the function returns the key identifier. /// /// This is an optional import, meaning that the function may not even exist. - symmetric-key-store-managed: func(secrets-manager: secrets-manager, symmetric-key: symmetric-key) -> result; + symmetric-key-store-managed: func(secrets-manager: borrow, symmetric-key: borrow) -> result; /// __(optional)__ /// Replace a managed symmetric key. @@ -76,7 +76,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If the operation succeeded, the new version is returned. /// /// This is an optional import, meaning that the function may not even exist. - symmetric-key-replace-managed: func(secrets-manager: secrets-manager, symmetric-key-old: symmetric-key, symmetric-key-new: symmetric-key) -> result; + symmetric-key-replace-managed: func(secrets-manager: borrow, symmetric-key-old: symmetric-key, symmetric-key-new: borrow) -> result; /// __(optional)__ /// Return the key identifier and version of a managed symmetric key. @@ -84,7 +84,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If the key is not managed, `unsupported_feature` is returned instead. /// /// This is an optional import, meaning that the function may not even exist. - symmetric-key-id: func(symmetric-key: symmetric-key) -> result, crypto-errno>; + symmetric-key-id: func(symmetric-key: borrow) -> result, crypto-errno>; /// __(optional)__ /// Return a managed symmetric key from a key identifier. @@ -94,7 +94,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If no key matching the provided information is found, `not_found` is returned instead. /// /// This is an optional import, meaning that the function may not even exist. - symmetric-key-from-id: func(secrets-manager: secrets-manager, symmetric-key-id: stored-key-id, symmetric-key-version: version) -> result; + symmetric-key-from-id: func(secrets-manager: borrow, symmetric-key-id: stored-key-id, symmetric-key-version: version) -> result; /// Create a new state to absorb and produce data using symmetric operations. /// @@ -271,7 +271,7 @@ interface wasi-ephemeral-crypto-symmetric { /// let next_key_handle = ctx.symmetric_state_squeeze_key(state_handle, "Xoodyak-128")?; /// // ... /// ``` - symmetric-state-open: func(algorithm: string, key: opt-symmetric-key, options: opt-options) -> result; + symmetric-state-open: func(algorithm: string, key: option>, options: option>) -> result; /// Retrieve a parameter from the current state. /// @@ -280,24 +280,24 @@ interface wasi-ephemeral-crypto-symmetric { /// The function may return `options_not_set` if an option was not set, which is different from an empty value. /// /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. - symmetric-state-options-get: func(handle: symmetric-state, name: string) -> result, crypto-errno>; + symmetric-state-options-get: func(state: borrow, name: string) -> result, crypto-errno>; /// Retrieve an integer parameter from the current state. /// /// The function may return `options_not_set` if an option was not set. /// /// It may also return `unsupported_option` if the option doesn't exist for the chosen algorithm. - symmetric-state-options-get-u64: func(handle: symmetric-state, name: string) -> result<%u64, crypto-errno>; + symmetric-state-options-get-u64: func(state: borrow, name: string) -> result<%u64, crypto-errno>; /// Clone a symmetric state. /// /// The function clones the internal state, assigns a new handle to it and returns the new handle. - symmetric-state-clone: func(handle: symmetric-state) -> result; + symmetric-state-clone: func(state: borrow) -> result; /// Destroy a symmetric state. /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. - symmetric-state-close: func(handle: symmetric-state) -> result<_, crypto-errno>; + symmetric-state-close: func(state: symmetric-state) -> result<_, crypto-errno>; /// Absorb data into the state. /// @@ -311,7 +311,7 @@ interface wasi-ephemeral-crypto-symmetric { /// If the chosen algorithm doesn't accept input data, the `invalid_operation` error code is returned. /// /// If too much data has been fed for the algorithm, `overflow` may be thrown. - symmetric-state-absorb: func(handle: symmetric-state, data: list) -> result<_, crypto-errno>; + symmetric-state-absorb: func(state: borrow, data: list) -> result<_, crypto-errno>; /// Squeeze bytes from the state. /// @@ -324,7 +324,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// For password-stretching functions, the function may return `in_progress`. /// In that case, the guest should retry with the same parameters until the function completes. - symmetric-state-squeeze: func(handle: symmetric-state) -> result, crypto-errno>; + symmetric-state-squeeze: func(state: borrow) -> result, crypto-errno>; /// Compute and return a tag for all the data injected into the state so far. /// @@ -336,7 +336,7 @@ interface wasi-ephemeral-crypto-symmetric { /// /// For password-stretching functions, the function may return `in_progress`. /// In that case, the guest should retry with the same parameters until the function completes. - symmetric-state-squeeze-tag: func(handle: symmetric-state) -> result; + symmetric-state-squeeze-tag: func(state: borrow) -> result; /// Use the current state to produce a key for a target algorithm. /// @@ -344,7 +344,7 @@ interface wasi-ephemeral-crypto-symmetric { /// For session-based authentication encryption, this returns a key that can be used to resume a session without storing a nonce. /// /// `invalid_operation` is returned for algorithms not supporting this operation. - symmetric-state-squeeze-key: func(handle: symmetric-state, alg-str: string) -> result; + symmetric-state-squeeze-key: func(state: borrow, alg-str: string) -> result; /// Return the maximum length of an authentication tag for the current algorithm. /// @@ -355,7 +355,7 @@ interface wasi-ephemeral-crypto-symmetric { /// For an encryption operation, the size of the output buffer should be `input_len + symmetric_state_max_tag_len()`. /// /// For a decryption operation, the size of the buffer that will store the decrypted data must be `ciphertext_len - symmetric_state_max_tag_len()`. - symmetric-state-max-tag-len: func(handle: symmetric-state) -> result; + symmetric-state-max-tag-len: func(state: borrow) -> result; /// Encrypt data with an attached tag. /// @@ -366,7 +366,7 @@ interface wasi-ephemeral-crypto-symmetric { /// The function returns the ciphertext along with the tag. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - symmetric-state-encrypt: func(handle: symmetric-state, data: list) -> result, crypto-errno>; + symmetric-state-encrypt: func(state: borrow, data: list) -> result, crypto-errno>; /// Encrypt data, with a detached tag. /// @@ -377,7 +377,7 @@ interface wasi-ephemeral-crypto-symmetric { /// The function returns the ciphertext and tag. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - symmetric-state-encrypt-detached: func(handle: symmetric-state, data: list) -> result, symmetric-tag>, crypto-errno>; + symmetric-state-encrypt-detached: func(state: borrow, data: list) -> result, symmetric-tag>, crypto-errno>; /// - **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. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. @@ -388,7 +388,7 @@ interface wasi-ephemeral-crypto-symmetric { /// `invalid_tag` is returned if the tag didn't verify. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - symmetric-state-decrypt: func(handle: symmetric-state, data: list) -> result, crypto-errno>; + symmetric-state-decrypt: func(state: borrow, data: list) -> result, crypto-errno>; /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. @@ -401,19 +401,19 @@ interface wasi-ephemeral-crypto-symmetric { /// `invalid_tag` is returned if the tag verification failed. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - symmetric-state-decrypt-detached: func(handle: symmetric-state, data: list, raw-tag: list) -> result, crypto-errno>; + symmetric-state-decrypt-detached: func(state: borrow, data: list, raw-tag: list) -> result, crypto-errno>; /// Make it impossible to recover the previous state. /// /// This operation is supported by some systems keeping a rolling state over an entire session, for forward security. /// /// `invalid_operation` is returned for algorithms not supporting ratcheting. - symmetric-state-ratchet: func(handle: symmetric-state) -> result<_, crypto-errno>; + symmetric-state-ratchet: func(state: borrow) -> result<_, crypto-errno>; /// Return the length of an authentication tag. /// /// This function can be used by a guest to allocate the correct buffer size to copy a computed authentication tag. - symmetric-tag-len: func(symmetric-tag: symmetric-tag) -> result; + symmetric-tag-len: func(symmetric-tag: borrow) -> result; /// Copy an authentication tag into a guest-allocated buffer. /// @@ -424,7 +424,7 @@ interface wasi-ephemeral-crypto-symmetric { /// ```rust /// let raw_tag = ctx.symmetric_tag_pull(raw_tag_handle)?; /// ``` - symmetric-tag-pull: func(symmetric-tag: symmetric-tag) -> result, crypto-errno>; + symmetric-tag-pull: func(symmetric-tag: borrow) -> result, crypto-errno>; /// Verify that a computed authentication tag matches the expected value, in constant-time. /// @@ -441,7 +441,7 @@ interface wasi-ephemeral-crypto-symmetric { /// let computed_tag_handle = ctx.symmetric_state_squeeze_tag(state_handle)?; /// ctx.symmetric_tag_verify(computed_tag_handle, expected_raw_tag)?; /// ``` - symmetric-tag-verify: func(symmetric-tag: symmetric-tag, expected-raw-tag: list) -> result<_, crypto-errno>; + symmetric-tag-verify: func(symmetric-tag: borrow, expected-raw-tag: list) -> result<_, crypto-errno>; /// Explicitly destroy an unused authentication tag. /// From 99f8a65a18c999d4640536e80c9542716d655f7a Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Wed, 3 Jun 2026 17:05:43 +0200 Subject: [PATCH 11/15] fix(batch): add same fixes to the batch variants --- wit/README.md | 2 +- ...wasi_ephemeral_crypto_signatures_batch.wit | 6 +-- .../wasi_ephemeral_crypto_symmetric_batch.wit | 37 ++++++++++--------- 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/wit/README.md b/wit/README.md index 6d90955..df63065 100644 --- a/wit/README.md +++ b/wit/README.md @@ -32,6 +32,6 @@ | **`ConstPointer + len` (Input buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed | | **Version constants** | `variant` | | | **`Variant`** without data | | | -| `type ... = handle` | `resource` | | +| `type ... = handle` | `resource` | This required manually adding borrowing where required | | **Imports** | `use use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | | `wasm-tools component wit .` | diff --git a/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit index 15ca4cc..21eaabc 100644 --- a/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit @@ -2,7 +2,7 @@ package wasi:crypto@0.0.1; interface wasi-ephemeral-crypto-signatures-batch { use wasi-ephemeral-crypto-common.{array-output, crypto-errno, signature-verification-state, signature, signature-state}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; + /// The result of a signature sign operation. A pair of the signature and an error code. type signature-sign-result = tuple; @@ -13,7 +13,7 @@ interface wasi-ephemeral-crypto-signatures-batch { /// /// Used for grouping signature verification state to be verified with the signature to verify. /// Used with batch_signature_state_verify(). - type signature-verification-input = tuple; + type signature-verification-input = tuple, borrow>; type signature-verification-results = list; @@ -57,7 +57,7 @@ interface wasi-ephemeral-crypto-signatures-batch { /// let raw_sig1 = signature_export(sig_handle[0], SignatureEncoding::Raw)?; /// let raw_sig2 = signature_export(sig_handle[1], SignatureEncoding::Raw)?; /// ``` - batch-signature-state-sign: func(states: list) -> result; + batch-signature-state-sign: func(states: list>) -> result; /// Verify a batch of signatures. /// diff --git a/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit index b7a9639..0092717 100644 --- a/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit @@ -2,33 +2,33 @@ package wasi:crypto@0.0.1; /// Symmetric Batch Operations interface wasi-ephemeral-crypto-symmetric-batch { - use wasi-ephemeral-crypto-common.{out-buffer, size, in-buffer, crypto-errno, symmetric-tag, symmetric-state}; - use wasi-ephemeral-crypto-todo-types.{todo-from-witx-value-constpointer-value-builtin-u8-lang-c-char-false, todo-from-witx-value-pointer-value-builtin-u8-lang-c-char-false}; - type output = out-buffer; - type output-len = size; + use wasi-ephemeral-crypto-common.{size, crypto-errno, symmetric-tag, symmetric-state}; + + type output = list; /// A non-mutable data buffer - type data = in-buffer; - type data-len = size; + type data = list; /// A raw tag buffer - type raw-tag = in-buffer; - type raw-tag-len = size; + type raw-tag = list; - /// Tuple representing results and size produced by an encrypt/decrypt operation. - type crypt-result = tuple; + /// Tuple representing results and output buffers produced by an encrypt/decrypt operation. + type crypt-result = tuple; /// A list of results from the individual encrypt/decrypt operations within a batch operation. type batch-crypt-results = list; /// Tuple representing results and size produced by a detached encrypt operation. - type encrypt-detached-result = tuple; + type encrypt-detached-result = tuple; /// A list of results from the individual encrypt/decrypt operations within a batch operation. type batch-encrypt-detached-results = list; + /// Tuple representing results and size produced by a squeeze operation. + type squeeze-result = tuple; + /// A list of results from squeeze operation within a batch operation. - type batch-squeeze-results = list; + type batch-squeeze-results = list; /// Tuple representing results and tag and error produced by a detached squeeze operation. type squeeze-detached-result = tuple; @@ -56,7 +56,7 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// codes that represent the status of the operation in the input list at /// the same list offset. /// - batch-symmetric-state-squeeze: func(batch: list>) -> result; + batch-symmetric-state-squeeze: func(batch: list>) -> result; /// Batch of operations to compute and return a tag for all the data /// injected into the state so far. @@ -83,7 +83,7 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// tag generated from the squeeze operation. The tag is only valid if the /// tuple's error code is `success`. /// - batch-symmetric-state-squeeze-tag: func(states: list) -> result; + batch-symmetric-state-squeeze-tag: func(states: list>) -> result; /// Perform a batch of symmetric encrypt operations. /// @@ -125,7 +125,7 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// /// let results = ctx.batch_symmetric_state_encrypt(batch)?; /// ``` - batch-symmetric-state-encrypt: func(batch: list>) -> result; + batch-symmetric-state-encrypt: func(batch: list, data>>) -> result; /// Perform a batch of symmetric encrypt operations with detached tags. /// @@ -168,7 +168,7 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// /// let results = ctx.batch_symmetric_state_encrypt_detached(batch)?; /// ``` - batch-symmetric-state-encrypt-detached: func(batch: list>) -> result; + batch-symmetric-state-encrypt-detached: func(batch: list, data>>) -> result; /// Perform a batch of symmetric decrypt operations. /// @@ -195,7 +195,8 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// the actual size of the decrypted data in the output buffer. The size /// value is only valid if the tuple's error code is `success`. /// - batch-symmetric-state-decrypt: func(batch: list>) -> result; + batch-symmetric-state-decrypt: func(batch: list, data>>) -> result; + /// Perform a batch of symmetric decrypt operations with detached tags. /// /// This is a batch version of the symmetric_state_decrypt_detached operation. @@ -221,5 +222,5 @@ interface wasi-ephemeral-crypto-symmetric-batch { /// the actual size of the decrypted data in the output buffer. The size /// value is only valid if the tuple's error code is `success`. /// - batch-symmetric-state-decrypt-detached: func(batch: list>) -> result; + batch-symmetric-state-decrypt-detached: func(batch: list, data, raw-tag>>) -> result; } From ff41c1c973a28c96fb52171eb79269fcc0bd692f Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Wed, 3 Jun 2026 17:26:06 +0200 Subject: [PATCH 12/15] docs(README): fix remaining mistakes --- wit/README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/wit/README.md b/wit/README.md index df63065..13942ea 100644 --- a/wit/README.md +++ b/wit/README.md @@ -13,7 +13,7 @@ | **`Type::List(T)`** | `Type::list` | Mapped to a WIT list. | | **`Type::Variant` (Option style)** | `Type::option` | Recognized via `general_as_option`. | | **`Type::Variant` (Expected style)** | `Type::result` | Recognized via `general_as_expected` (handles ok/err variations). | -| **`Type::Variant` (Enum style)** | `TypeDef::variant(...)` | Custom map to variant cases if items contain data, or simple enums if values are empty. | +| **`Type::Variant` (Enum style)** | `TypeDef::variant(...)` | Custom map to variant cases. | | **`Type::Record` (Tuple style)** | `Type::tuple(...)` | Evaluated when `record.is_tuple()` is true. | | **`Type::Record` (Bitflags)** | `TypeDef::flags(...)` | Evaluated when `record.bitflags_repr().is_some()`. | | **`Type::Record` (Standard)** | `TypeDef::record(...)` | Maps fields to a named structure. | @@ -26,12 +26,12 @@ ### Manual -| WITX Type / Construct | Target WIT Construct | Transpilation Details & Notes | -| --------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`Pointer + len` (Output buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed | -| **`ConstPointer + len` (Input buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed | -| **Version constants** | `variant` | | -| **`Variant`** without data | | | -| `type ... = handle` | `resource` | This required manually adding borrowing where required | -| **Imports** | `use use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | -| `wasm-tools component wit .` | +| WITX Type / Construct | Target WIT Construct | Transpilation Details & Notes | +| --------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`Pointer + len` (Output buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed. | +| **`ConstPointer + len` (Input buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed. | +| **Version constants** | `variant` | Mostly due to the lack of constants, with a variant being more suitable to display the same information than implicit values. | +| **`Variant`** without data | `enum` | There is nothing stopping the transpiler from handling this case as well. I just didn't notice and fixing it by hand was easier. | +| `type ... = handle` | `resource` | This required manually adding `borrow<>` where required. | +| **Imports** | `use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | +| `wasm-tools component wit .`. | From 1bc18af999c9e5120e6d66beda52787481b9f69d Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Thu, 4 Jun 2026 09:52:37 +0200 Subject: [PATCH 13/15] docs: fix typo based on feedback --- wit/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wit/README.md b/wit/README.md index 13942ea..88c262f 100644 --- a/wit/README.md +++ b/wit/README.md @@ -34,4 +34,4 @@ | **`Variant`** without data | `enum` | There is nothing stopping the transpiler from handling this case as well. I just didn't notice and fixing it by hand was easier. | | `type ... = handle` | `resource` | This required manually adding `borrow<>` where required. | | **Imports** | `use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | -| `wasm-tools component wit .`. | +| `wasm-tools component wit .` | From a45cc896229234ac6895f5d0f68b65a2a755f85b Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Thu, 4 Jun 2026 10:01:50 +0200 Subject: [PATCH 14/15] fix: use version 0.11 to continue numbering WITX --- .../wasi_ephemeral_crypto_signatures_batch.wit | 2 +- .../wasi_ephemeral_crypto_symmetric_batch.wit | 2 +- wit/wasi_ephemeral_crypto_asymmetric_common.wit | 2 +- wit/wasi_ephemeral_crypto_common.wit | 14 +++++++------- wit/wasi_ephemeral_crypto_external_secrets.wit | 2 +- wit/wasi_ephemeral_crypto_kx.wit | 2 +- wit/wasi_ephemeral_crypto_signatures.wit | 2 +- wit/wasi_ephemeral_crypto_symmetric.wit | 2 +- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit index 21eaabc..5bfc81a 100644 --- a/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_signatures_batch.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; interface wasi-ephemeral-crypto-signatures-batch { use wasi-ephemeral-crypto-common.{array-output, crypto-errno, signature-verification-state, signature, signature-state}; diff --git a/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit index 0092717..ea02186 100644 --- a/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit +++ b/wit/batch/wasi_ephemeral_crypto_symmetric_batch.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; /// Symmetric Batch Operations interface wasi-ephemeral-crypto-symmetric-batch { diff --git a/wit/wasi_ephemeral_crypto_asymmetric_common.wit b/wit/wasi_ephemeral_crypto_asymmetric_common.wit index 072e16a..1e6c855 100644 --- a/wit/wasi_ephemeral_crypto_asymmetric_common.wit +++ b/wit/wasi_ephemeral_crypto_asymmetric_common.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; interface wasi-ephemeral-crypto-asymmetric-common { use wasi-ephemeral-crypto-common.{algorithm-type, options, keypair, crypto-errno, size, keypair-encoding, secrets-manager, version, publickey, secretkey, array-output, publickey-encoding, secretkey-encoding}; diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index a7dd707..2bf3da6 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; interface wasi-ephemeral-crypto-common { type key-id = list; @@ -302,8 +302,8 @@ interface wasi-ephemeral-crypto-common { /// An optional options set. /// /// This union simulates an `Option` type to make the `options` parameter of some functions optional. - @deprecated(version = 0.0.1) - @since(version = 0.0.1) + @deprecated(version = 0.11.0) + @since(version = 0.11.0) type opt-options = option; /// Symmetric key index, only required by the Interface Types translation layer. @@ -315,8 +315,8 @@ interface wasi-ephemeral-crypto-common { /// An optional symmetric key. /// /// This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. - @deprecated(version = 0.0.1) - @since(version = 0.0.1) + @deprecated(version = 0.11.0) + @since(version = 0.11.0) type opt-symmetric-key = option; /// Create a new object to set non-default options. @@ -357,8 +357,8 @@ interface wasi-ephemeral-crypto-common { /// This implementation using `list` does not have this guarantee and serves as a stopgap till [caller-supplied buffers](https://wasi.dev/roadmap) arrive in future WASI 0.3.x release. /// /// This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. - @deprecated(version = 0.0.1) - @since(version = 0.0.1) + @deprecated(version = 0.11.0) + @since(version = 0.11.0) options-set-guest-buffer: func(options: borrow, name: string, buffer: list) -> result<_, crypto-errno>; /// Return the length of an `array_output` object. diff --git a/wit/wasi_ephemeral_crypto_external_secrets.wit b/wit/wasi_ephemeral_crypto_external_secrets.wit index d1384ee..11c8b0e 100644 --- a/wit/wasi_ephemeral_crypto_external_secrets.wit +++ b/wit/wasi_ephemeral_crypto_external_secrets.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; /// External secrets storage. /// diff --git a/wit/wasi_ephemeral_crypto_kx.wit b/wit/wasi_ephemeral_crypto_kx.wit index 88a1dcf..cf08ab9 100644 --- a/wit/wasi_ephemeral_crypto_kx.wit +++ b/wit/wasi_ephemeral_crypto_kx.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; interface wasi-ephemeral-crypto-kx { use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, array-output, crypto-errno, size}; diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 21eb292..07fb6a5 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; interface wasi-ephemeral-crypto-signatures { use wasi-ephemeral-crypto-common.{keypair, publickey, secretkey, signature, signature-encoding, array-output, crypto-errno, size, signature-state, signature-verification-state}; diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index c17fd9a..e905908 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -1,4 +1,4 @@ -package wasi:crypto@0.0.1; +package wasi:crypto@0.11.0; interface wasi-ephemeral-crypto-symmetric { use wasi-ephemeral-crypto-common.{options, symmetric-key, crypto-errno, size, array-output, secrets-manager, version, symmetric-state, %u64, symmetric-tag}; From b64e60cef8fe95013588be64a93142ff912927e3 Mon Sep 17 00:00:00 2001 From: Robbe Haegeman Date: Tue, 16 Jun 2026 20:55:01 +0200 Subject: [PATCH 15/15] feat: changes based on learning implementation --- wit/README.md | 18 +++++++++--------- wit/wasi_ephemeral_crypto_common.wit | 10 +++------- wit/wasi_ephemeral_crypto_signatures.wit | 6 ++++-- wit/wasi_ephemeral_crypto_symmetric.wit | 14 +++++++++----- wit/world.wit | 13 +++++++++++++ 5 files changed, 38 insertions(+), 23 deletions(-) create mode 100644 wit/world.wit diff --git a/wit/README.md b/wit/README.md index 88c262f..02a5ede 100644 --- a/wit/README.md +++ b/wit/README.md @@ -26,12 +26,12 @@ ### Manual -| WITX Type / Construct | Target WIT Construct | Transpilation Details & Notes | -| --------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`Pointer + len` (Output buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed. | -| **`ConstPointer + len` (Input buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed. | -| **Version constants** | `variant` | Mostly due to the lack of constants, with a variant being more suitable to display the same information than implicit values. | -| **`Variant`** without data | `enum` | There is nothing stopping the transpiler from handling this case as well. I just didn't notice and fixing it by hand was easier. | -| `type ... = handle` | `resource` | This required manually adding `borrow<>` where required. | -| **Imports** | `use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | -| `wasm-tools component wit .` | +| WITX Type / Construct | Target WIT Construct | Transpilation Details & Notes | +| ------------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`Pointer + len` (Output buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed. | +| **`ConstPointer + len` (Input buffer)** | `list` | For `symmetric-state-encrypt`, `symmetric-state-encrypt-detached`, `symmetric-state-decrypt`, and `symmetric-state-decrypt-detached`; the ability to encrypt in-place had to be removed. | +| **Version constants** | `variant` | Mostly due to the lack of constants, with a variant being more suitable to display the same information than implicit values. | +| **`Variant`** without data | `enum` | There is nothing stopping the transpiler from handling this case as well. I just didn't notice and fixing it by hand was easier. | +| `type ... = handle` | `resource` | This required manually adding `borrow<>` where required. | +| **Imports** | `use wasi-ephemeral-crypto-common.{}` | This was done manually and verified using: | +| **`array-output-pull` / `symmetric-tag-pull` parameter ownership** | `borrow` (WITX host closes as side-effect) | `T` (owned; Component Model destroys on function return) | In WITX the host explicitly closes the handle inside `pull`, enforcing single-use. WIT `borrow` prevents the host from doing so. Taking ownership restores the invariant. The regression is minimal: WITX allowed retrying `pull` with a larger buffer on `Overflow`, but the WIT version already returns `list` (host-allocated), making `Overflow` impossible and retries unnecessary. | diff --git a/wit/wasi_ephemeral_crypto_common.wit b/wit/wasi_ephemeral_crypto_common.wit index 2bf3da6..f3dcb44 100644 --- a/wit/wasi_ephemeral_crypto_common.wit +++ b/wit/wasi_ephemeral_crypto_common.wit @@ -368,19 +368,15 @@ interface wasi-ephemeral-crypto-common { /// Copy the content of an `array_output` object into an application-allocated buffer. /// - /// Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. - /// - /// The function returns the copied bytes. A length of 0 means that the end of the stream has been reached. - /// - /// The handle is automatically closed after all the data has been consumed. + /// The function returns the copied bytes. The handle is consumed and becomes invalid after this call. /// /// Example usage: /// /// ```rust /// let len = array_output_len(output_handle)?; - /// let out = array_output_pull(output_handle)?; + /// let out = array_output_pull(output_handle)?; /// ``` - array-output-pull: func(array-output: borrow) -> result, crypto-errno>; + array-output-pull: func(array-output: array-output) -> result, crypto-errno>; /// __(optional)__ /// Create a context to use a secrets manager. diff --git a/wit/wasi_ephemeral_crypto_signatures.wit b/wit/wasi_ephemeral_crypto_signatures.wit index 07fb6a5..2914c27 100644 --- a/wit/wasi_ephemeral_crypto_signatures.wit +++ b/wit/wasi_ephemeral_crypto_signatures.wit @@ -60,13 +60,15 @@ interface wasi-ephemeral-crypto-signatures { /// Absorb data into the signature state. /// - /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates. + /// This function may return `unsupported_feature` if the selected algorithm doesn't support incremental updates, + /// or if `signature-state-sign` has already been called on this state (e.g. pure Ed25519, which does not support + /// re-feeding data after a signature has been produced). signature-state-update: func(state: borrow, input: list) -> result<_, crypto-errno>; /// Compute a signature for all the data collected up to that point. /// /// The function can be called multiple times for incremental signing. - signature-state-sign: func(state: borrow) -> result; + signature-state-sign: func(state: borrow) -> result; /// Destroy a signature state. /// diff --git a/wit/wasi_ephemeral_crypto_symmetric.wit b/wit/wasi_ephemeral_crypto_symmetric.wit index e905908..dda6ff3 100644 --- a/wit/wasi_ephemeral_crypto_symmetric.wit +++ b/wit/wasi_ephemeral_crypto_symmetric.wit @@ -383,12 +383,18 @@ interface wasi-ephemeral-crypto-symmetric { /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. /// - **SHOE, Xoodyak, Strobe:** decrypts data, squeezes a tag and verify that it matches the one that was appended to the ciphertext. /// + /// `out-len` is the expected length of the plaintext. It must equal `data.len() - tag_len`, where + /// `tag_len` is the length of the authentication tag appended to the ciphertext. This parameter is + /// required because the tag length is algorithm-specific and may vary within the same algorithm + /// (e.g. AES-GCM supports tag lengths of 4–16 bytes), so the host cannot determine the split point + /// without explicit guidance from the caller. + /// /// The function returns the decrypted message. /// /// `invalid_tag` is returned if the tag didn't verify. /// /// `invalid_operation` is returned for algorithms not supporting encryption. - symmetric-state-decrypt: func(state: borrow, data: list) -> result, crypto-errno>; + symmetric-state-decrypt: func(state: borrow, data: list, out-len: size) -> result, crypto-errno>; /// - **Stream cipher:** returns `invalid_operation` since stream ciphers do not include authentication tags. /// - **AEAD:** decrypts `data` into `out`. Additional data must have been previously absorbed using `symmetric_state_absorb()`. @@ -417,14 +423,14 @@ interface wasi-ephemeral-crypto-symmetric { /// Copy an authentication tag into a guest-allocated buffer. /// - /// The handle automatically becomes invalid after this operation. Manually closing it is not required. + /// The handle is consumed and becomes invalid after this call. /// /// Example usage: /// /// ```rust /// let raw_tag = ctx.symmetric_tag_pull(raw_tag_handle)?; /// ``` - symmetric-tag-pull: func(symmetric-tag: borrow) -> result, crypto-errno>; + symmetric-tag-pull: func(symmetric-tag: symmetric-tag) -> result, crypto-errno>; /// Verify that a computed authentication tag matches the expected value, in constant-time. /// @@ -445,8 +451,6 @@ interface wasi-ephemeral-crypto-symmetric { /// Explicitly destroy an unused authentication tag. /// - /// This is usually not necessary, as `symmetric_tag_pull()` automatically closes a tag after it has been copied. - /// /// Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. symmetric-tag-close: func(symmetric-tag: symmetric-tag) -> result<_, crypto-errno>; } diff --git a/wit/world.wit b/wit/world.wit new file mode 100644 index 0000000..d0af565 --- /dev/null +++ b/wit/world.wit @@ -0,0 +1,13 @@ +package wasi:crypto@0.11.0; + +world imports { + import wasi-ephemeral-crypto-asymmetric-common; + import wasi-ephemeral-crypto-common; + import wasi-ephemeral-crypto-external-secrets; + import wasi-ephemeral-crypto-kx; + import wasi-ephemeral-crypto-signatures; + import wasi-ephemeral-crypto-symmetric; + // import wasi-ephemeral-crypto-signatures-batch; + // import wasi-ephemeral-crypto-symmetric-batch; + } +