* Encoding to use for importing or exporting a key pair.
**/
enumclassKeypairEncoding : uint16_t {
RAW = 0,
PKCS_8 = 1,
PEM = 2,
LOCAL = 3,
};
/**
* Encoding to use for importing or exporting a public key.
**/
enumclassPublickeyEncoding : uint16_t {
RAW = 0,
PKCS_8 = 1,
PEM = 2,
SEC = 3,
COMPRESSED_SEC = 4,
LOCAL = 5,
};
/**
* Encoding to use for importing or exporting a secret key.
**/
enumclassSecretkeyEncoding : uint16_t {
RAW = 0,
PKCS_8 = 1,
PEM = 2,
SEC = 3,
COMPRESSED_SEC = 4,
LOCAL = 5,
};
/**
* Encoding to use for importing or exporting a signature.
**/
enumclassSignatureEncoding : uint16_t {
RAW = 0,
DER = 1,
};
/**
* An algorithm category.
**/
enumclassAlgorithmType : uint16_t {
SIGNATURES = 0,
SYMMETRIC = 1,
KEY_EXCHANGE = 2,
};
/**
* Version of a managed key.
*
* A version can be an arbitrary `u64` integer, with the expection of some reserved values.
**/
using Version = uint64_t;
/**
* Size of a value.
**/
using Size = size_t;
/**
* A UNIX timestamp, in seconds since 01/01/1970.
**/
using Timestamp = uint64_t;
/**
* A 64-bit value
**/
usingU64 = uint64_t;
/**
* 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.
**/
using ArrayOutput = WasiHandle;
/**
* 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.
**/
using Options = WasiHandle;
/**
* A handle to the optional secrets management facilities offered by a host.
*
* This is used to generate, retrieve and invalidate managed keys.
**/
using SecretsManager = WasiHandle;
/**
* A key pair.
**/
using Keypair = WasiHandle;
/**
* 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.
**/
using SignatureState = WasiHandle;
/**
* A signature.
**/
using Signature = WasiHandle;
/**
* A public key, for key exchange and signature verification.
**/
using Publickey = WasiHandle;
/**
* A secret key, for key exchange mechanisms.
**/
using Secretkey = WasiHandle;
/**
* A state to absorb signed data to be verified.
**/
using SignatureVerificationState = WasiHandle;
/**
* 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.
**/
using SymmetricState = WasiHandle;
/**
* 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.
**/
using SymmetricKey = WasiHandle;
/**
* An authentication tag.
*
* This is an object returned by functions computing authentication tags.
*
* A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function.
*
* This object type can't be directly created from raw bytes. They are only returned by functions computing MACs.
*
* The host is reponsible for securely wiping them from memory on close.
**/
using SymmetricTag = WasiHandle;
/**
* Options index, only required by the Interface Types translation layer.
**/
enumclassOptOptionsU : uint8_t {
SOME = 0,
NONE = 1,
};
/**
* An optional options set.
*
* This union simulates an `Option<Options>` type to make the `options` parameter of some functions optional.
**/
union OptOptionsMember {
Options some; // if tag=0
// none: (no associated content) if tag=1
};
struct__attribute__((packed)) OptOptions {
uint8_t tag;
uint8_t __pad8_0;
uint16_t __pad16_0;
uint32_t __pad32_0;
OptOptionsMember member;
};
/**
* Symmetric key index, only required by the Interface Types translation layer.
**/
enumclassOptSymmetricKeyU : uint8_t {
SOME = 0,
NONE = 1,
};
/**
* An optional symmetric key.
*
* This union simulates an `Option<SymmetricKey>` type to make the `symmetric_key` parameter of some functions optional.
**/
union OptSymmetricKeyMember {
SymmetricKey some; // if tag=0
// none: (no associated content) if tag=1
};
struct__attribute__((packed)) OptSymmetricKey {
uint8_t tag;
uint8_t __pad8_0;
uint16_t __pad16_0;
uint32_t __pad32_0;
OptSymmetricKeyMember member;
};
/**
* Generate a new symmetric key for a given algorithm.
*
* `options` can be `None` to use the default parameters, or an algoritm-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.
* 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.
* This function crates 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.
* Create a new state to aborb 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)?;
* - **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.
* - **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.
* - **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.