├── .gitignore ├── Contributing.md ├── README.md ├── design └── security.md ├── docs ├── HighLevelGoals.md └── wasi-crypto.md ├── meetings └── minutes │ ├── 2022-09-22.md │ ├── 2022-10-04.md │ └── 2022-11-01.md └── witx ├── witx-0.10 ├── Makefile ├── wasi_ephemeral_crypto.md ├── wasi_ephemeral_crypto.txt ├── wasi_ephemeral_crypto_asymmetric_common.md ├── wasi_ephemeral_crypto_asymmetric_common.witx ├── wasi_ephemeral_crypto_common.md ├── wasi_ephemeral_crypto_common.witx ├── wasi_ephemeral_crypto_external_secrets.md ├── wasi_ephemeral_crypto_external_secrets.witx ├── wasi_ephemeral_crypto_kx.md ├── wasi_ephemeral_crypto_kx.witx ├── wasi_ephemeral_crypto_signatures.md ├── wasi_ephemeral_crypto_signatures.witx ├── wasi_ephemeral_crypto_signatures_batch.md ├── wasi_ephemeral_crypto_signatures_batch.witx ├── wasi_ephemeral_crypto_symmetric.md ├── wasi_ephemeral_crypto_symmetric.witx ├── wasi_ephemeral_crypto_symmetric_batch.md └── wasi_ephemeral_crypto_symmetric_batch.witx └── witx-0.9 ├── proposal_asymmetric_common.witx ├── proposal_common.witx ├── proposal_external_secrets.witx ├── proposal_kx.witx ├── proposal_signatures.witx ├── proposal_symmetric.witx └── wasi_ephemeral_crypto.witx /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | -------------------------------------------------------------------------------- /Contributing.md: -------------------------------------------------------------------------------- 1 | # Contributing to WebAssembly 2 | 3 | Interested in participating? Please follow 4 | [the same contributing guidelines as the design repository]: https://github.com/WebAssembly/design/blob/master/Contributing.md 5 | 6 | Also, please be sure to read [the README.md](README.md) for this repository. 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # WASI Cryptography APIs 2 | 3 | This repository is for development of Cryptography API proposals for the 4 | [WASI Subgroup] of the [WebAssembly Community Group]. 5 | 6 | Please refer to those groups' documentation for more information on their 7 | processes, goals, scope, and deliverables. 8 | 9 | [WASI Subgroup]: https://github.com/WebAssembly/WASI 10 | [WebAssembly Community Group]: https://www.w3.org/community/webassembly/ 11 | 12 | * [High-level goals](docs/HighLevelGoals.md) 13 | * [Security design document](design/security.md) 14 | * [Specification](docs/wasi-crypto.md) 15 | * Interface definitions: 16 | * common types and functions ([witx](witx/witx-0.10/wasi_ephemeral_crypto_common.witx), [doc](witx/witx-0.10/wasi_ephemeral_crypto_common.md)) 17 | * symmetric operations ([witx](witx/witx-0.10/wasi_ephemeral_crypto_symmetric.witx), [doc](witx/witx-0.10/wasi_ephemeral_crypto_symmetric.md)) 18 | * common types and functions for asymmetric operations ([witx](witx/witx-0.10/wasi_ephemeral_crypto_asymmetric_common.witx), [doc](witx/witx-0.10/wasi_ephemeral_crypto_asymmetric_common.md)) 19 | * signatures ([witx](witx/witx-0.10/wasi_ephemeral_crypto_signatures.witx), [doc](witx/witx-0.10/wasi_ephemeral_crypto_signatures.md)) 20 | * key exchange ([witx](witx/witx-0.10/wasi_ephemeral_crypto_kx.witx), [doc](witx/witx-0.10/wasi_ephemeral_crypto_kx.md)) 21 | * external secrets ([witx](witx/witx-0.10/wasi_ephemeral_crypto_external_secrets.witx), [doc](witx/witx-0.10/wasi_ephemeral_crypto_external_secrets.md)) 22 | * [Concise API overview](witx/witx-0.10/wasi_ephemeral_crypto.txt) 23 | * [Implementation for the WasmEdge runtime](https://wasmedge.org/book/en/dev/rust/wasicrypto.html) 24 | * [Wasmtime with support for wasi-crypto](https://github.com/wasm-crypto/wasmtime-crypto) 25 | * [Example implementation](https://github.com/wasm-crypto/wasi-crypto-host-functions) in Rust 26 | * [Example bindings](https://github.com/wasm-crypto/wasi-crypto-bindings) for AssemblyScript and Rust 27 | 28 | Interested parties are welcome to join the working group meeting every 2 weeks on Tuesday 17:00 UTC. 29 | 30 | * [Google Meet link](https://meet.google.com/yeh-kbzo-pfx) 31 | * [Google calendar](https://calendar.google.com/calendar/u/0/embed?src=f67fde02694963243f5dafb70d61c64e715dacbcf1abba17824e672635f90f3e@group.calendar.google.com) 32 | -------------------------------------------------------------------------------- /design/security.md: -------------------------------------------------------------------------------- 1 | # Security considerations for the `wasi-crypto` API design 2 | 3 | ## Misuse resistance 4 | 5 | While the `wasi-crypto` provides low-level operations and may not 6 | prevent primitives from being used incorrectly, we should still try to 7 | avoid insecure constructions to be instantiated, and mitigate the 8 | implications of bugs in applications and implementations. 9 | 10 | ### Strong typing 11 | 12 | Operations requiring any kind of key (including public keys) must only 13 | accept the key as a type specifically defined for the given operation 14 | and key type. 15 | 16 | Even though these keys can be represented as raw bytes, such a 17 | representation should not be directly accepted by any functions besides 18 | the ones constructing a key object. 19 | 20 | For example, a public key used for signature verification must be of 21 | type `signature_publickey`. 22 | 23 | This ensures that a key will not inadvertently be used for a different 24 | operation, and enables type verification to be made during 25 | compilation. 26 | 27 | Internally, a key also stores the algorithm and parameters it is 28 | designed to be used with. Using a key for the correct operation, but 29 | the wrong algorithm or different parameters must result in a runtime 30 | error. 31 | 32 | ### No insecure options 33 | 34 | Applications instantiate a construction using a string representing 35 | an algorithm as well as its main parameters. 36 | 37 | An example is `RSA_PKCS1_2048_8192_SHA384`. 38 | 39 | The set of possible algorithm and parameters must be well-defined, so 40 | that insecure constructions cannot be instantiated. 41 | 42 | ### Bound checking 43 | 44 | The linear memory model of WebAssembly and its current lack of support 45 | for protected pages inside a memory region facilitates heartbleed-like 46 | vulnerabilities. 47 | 48 | As a result, `wasi-crypto` APIs must not trust applications for 49 | providing correctly sized output buffers. 50 | 51 | The following API would assume that `$tag` was properly allocated for 52 | the expected authentication tag: 53 | 54 | ```text 55 | (@interface func (export "crypto_aead_get_tag") 56 | (param $handle crypto_aead) 57 | (param $tag (@witx pointer u8)) 58 | (result $error $crypto_errno) 59 | ) 60 | ``` 61 | 62 | However, such an API would be error prone, so the buffer size, as 63 | actually allocated by the application, should be provided: 64 | 65 | ```text 66 | (@interface func (export "crypto_aead_get_tag") 67 | (param $handle crypto_aead) 68 | (param $tag (@witx pointer u8)) 69 | (param $tag_max_len $size) 70 | (result $error $crypto_errno) 71 | ) 72 | ``` 73 | 74 | If `$tag_max_len` is shorter than the expected length, the function 75 | must return a `$crypto_errno.overflow` error code. `$tag` may be 76 | filled with random bytes in order to mitigate the implications of 77 | applications ignoring the error code. 78 | 79 | ### Side channels 80 | 81 | Mitigations against side channels must be implemented for all 82 | operations involving secrets. 83 | 84 | In order to do so, the API must try to prevent applications from 85 | performing comparisons themselves. 86 | 87 | In particular, a MAC operation should not return raw bytes, but a 88 | MAC object. MAC objects can be compared for equality using a dedicated 89 | function, that will take care of avoiding side channels. 90 | 91 | The API should also not leak internal data structures. For example, 92 | there shouldn't be any ways to get the internal state of a cipher. 93 | 94 | In the context of WebAssembly, it also means nothing directly derived 95 | from pointers to host memory or external linear memories. 96 | 97 | A secret should only be referred to using an opaque handle, and 98 | exporting it should require a dedicated function. 99 | 100 | Error codes may end up being sent to untrusted users, and should not 101 | leak information about secrets either (ex: act as a padding oracle). 102 | 103 | The same guarantees are expected from the underlying algorithm 104 | implementations. Any application using the `wasi-crypto` module can 105 | thus assume that side channels mitigations have been implemented 106 | for every single operation exposed by the API. 107 | 108 | ### Nonces / IVs 109 | 110 | Using a constant IV is one of the most common mistake made by 111 | applications, and has catastrophic implications. In order to prevent 112 | this, APIs should: 113 | 114 | - APIs must not require an IV. Setting the IV should be an optional 115 | operation, distinct from the creation of a cipher object. 116 | 117 | - In absence of an explicit IV, the implementation should either 118 | create a safe IV (e.g. by using a CSPRNG if the size is comfortable 119 | enough to avoid collisions), or return an error when the application 120 | tries to use the object to encrypt data. 121 | 122 | ### Secret zeroing 123 | 124 | Keys are exposed as handles, that applications should close after use. 125 | 126 | `wasi-crypto` implementations should try to wipe secret key material 127 | from memory, as well as any information derived from it (ex: initial 128 | state of block ciphers). 129 | 130 | ### Errors 131 | 132 | Applications may not always correctly check for error codes. If secret 133 | data should have been returned, but the operation failed, the output 134 | buffer should not remain filled, even partially, with secret data. 135 | 136 | For example, if a decryption operation fails, the output buffer 137 | must be zeroed or filled with random data instead of containing 138 | (partially) decrypted data. 139 | 140 | ### Absence of undefined behaviors 141 | 142 | The API specification must explicitly define what happens on edge 143 | cases on a per-algorithm basis. 144 | 145 | For example, what happens when the internal counter of a stream/block 146 | cipher wraps must be defined, and behave consistently across all 147 | implementations. 148 | 149 | This also includes the way public keys are validated. For example, the 150 | specification may require implementations to prevent the creation of a 151 | public key if the source representation of that key is not in canonical 152 | form. 153 | -------------------------------------------------------------------------------- /docs/HighLevelGoals.md: -------------------------------------------------------------------------------- 1 | # WASI-crypto High-Level Goals 2 | 3 | ## Motivations behind WASI-crypto 4 | 5 | While optimizing compilers could allow efficient implementation of 6 | cryptographic features in WebAssembly, there are several occasions as 7 | below where a host implementation is more desirable. WASI-crypto aims 8 | to fill those gaps by defining a standard interface as a set of APIs. 9 | 10 | 1. Hardware acceleration: Modern computing devices are equipped with 11 | dedicated hardware support for major cryptographic primitives, such as 12 | AES and SHA-2. Leveraging those accelerators is important for 13 | performance critical applications. 14 | 2. System level secret isolation: Smartcards and Hardware Security 15 | Modules (HSM) are becoming popular as they can properly isolate users' 16 | private keys from the rest of the system or cloud. To operate on those 17 | private keys, applications need to use the standard interface provided 18 | at the system level. 19 | 3. Software certification: Governments and enterprise often require 20 | certification of crypto implementations. Notable examples are 21 | FIPS-140, Common Criteria, and PCI-DSS. Usually, such certifications 22 | are given to the common system libraries, as it is impractical to 23 | certify every program. 24 | 4. Resilience against side channel attacks: In recent years, several 25 | attacks had been developed by utilizing side channels in the crypto 26 | implementations, such as the use of non constant-time operations and 27 | non-uniform cache access. At WebAssembly level, it is currently not 28 | possible to ensure non-existence of side channels until the final 29 | machine code is generated for the target architecture. 30 | 31 | ## WASI-crypto goals 32 | 33 | 1. Define portable, modular, runtime-independent, and 34 | WebAssembly-native APIs which can be used by WebAssembly code to 35 | perform cryptographic operations while preserving the sandboxed nature 36 | of WebAssembly. 37 | 2. Specify how public and secret keys are generated, verified, 38 | imported, exported, stored, rotated and used. Some of these operations 39 | may not be available. For example, in a HSM-like environment, keys may 40 | not be exportable, or may need further transformations. 41 | 3. Define APIs commonly required for handling sensitive material: 42 | constant-time comparison, secret key destruction, constant-time 43 | encoding, common operations on large numbers. 44 | 4. Define APIs for generating secure random numbers, encryption, hashing, 45 | password stretching, signatures, key derivation and padding. 46 | 5. Define APIs for modular arithmetic and elliptic curve arithmetic. 47 | 48 | All these APIs must be designed for interoperability, with no undefined 49 | behaviors. 50 | 51 | Being core APIs, they should also be designed for stability. Namely, 52 | these APIs should support current and futures primitives and 53 | constructions without requiring breaking changes. 54 | Current and future constructions include XOFs, session-based 55 | encryption, and post-quantum key exchange and signatures. 56 | 57 | ## WASI-crypto non-goals 58 | 59 | - Implementing high-level protocols (ex: Noise, TLS, PAKEs, HPKE). However, 60 | the WASI-crypto module should provide all the required pieces in order to 61 | build these protocols. 62 | - ASN.1 parsing or generation. 63 | - Networking. 64 | 65 | These can be implemented later on, as additional WASI modules. 66 | -------------------------------------------------------------------------------- /meetings/minutes/2022-09-22.md: -------------------------------------------------------------------------------- 1 | # September 22nd, 2022 2 | 3 | * Dan Gohman is going to review the current spec and see what changes might be required in order to make it consistent with other WASI APIs. 4 | * Breaking API change: addition of a context to some functions that can't inherit one (@rjzak for the spec, likely @jedisct1 for the wasmtime/bindings implementations) - Issue #58 5 | * Key attestation: some applications such as ENARX may require an attestation for keys. These are platform-dependent blobs. (@npmccallum). @jedisct1: we can introduce a generic function to get metadata about a key (public, secret, key pair) instead. How to ensure uniqueness of identifiers? Use UUIDs? (@npmccallum) Register to IANA? Or maybe better: maintain the registry within the wasi-crypto specification/repository. 6 | * `symmetric_state_clone()` missing from the rust host implementation, due to issues with Rust. Make it a TODO in the `wasi-crypto` crate, not in the wasmtime glue (@rjzak, @jedisct1) 7 | * Webcrypto algorithms are non normative. But having required algorithms would still be a good thing for wasi-crypto. Yet, FIPS complicance may be an issue. Split them in 4 categories: Required, recommended, optional, reserved. Only FIPS-approved algorithms must go into the "required" category (PR #77, @rjzak, @jedisct1) 8 | -------------------------------------------------------------------------------- /meetings/minutes/2022-10-04.md: -------------------------------------------------------------------------------- 1 | # October 4th, 2022 2 | 3 | * The "hostcalls" implementation is not meant to be a reference implementation, but something that can be actually used in Wasmtime. It is big, not language-agnostic, and it being a reference implementation would incompatible with making it more complicated and adding optimizations. 4 | * Proposal: write a simple reference implememtation in Go or Python, that focuses on readability and is as close to the specification as possible. 5 | * A test suite is much needed. 6 | * At least we should do cross-implementation testing between the rust implementation and the wasmedge implementation. 7 | * Recommended/required algorithms: classify by tiers (Richard, Frank, PR #77) -- Elliptic curves may not be recommended, as some organizations may still not allow them, for compliance with older recommendations. 8 | * The wasi-crypto crate should support both BoringSSL (required for performance and compliance) and Rust implementations (required for Enarx). 9 | -------------------------------------------------------------------------------- /meetings/minutes/2022-11-01.md: -------------------------------------------------------------------------------- 1 | # November 11th, 2022 2 | 3 | * Elliptic curves may still be something we should require for a specification written 2022. 4 | * Update of the wasi-crypto crate in wasmtime: required due to API changes, and deprecated dependencies. 5 | * The PR originally made by Richard was closed due to wasmtime updates and issues with CI. Frank is going to send a new PR. 6 | -------------------------------------------------------------------------------- /witx/witx-0.10/Makefile: -------------------------------------------------------------------------------- 1 | all: wasi_ephemeral_crypto.txt wasi_ephemeral_crypto.md wasi_ephemeral_crypto_common.md wasi_ephemeral_crypto_asymmetric_common.md wasi_ephemeral_crypto_symmetric.md wasi_ephemeral_crypto_signatures.md wasi_ephemeral_crypto_kx.md wasi_ephemeral_crypto_external_secrets.md wasi_ephemeral_crypto_symmetric_batch.md wasi_ephemeral_crypto_signatures_batch.md 2 | 3 | wasi_ephemeral_crypto.txt: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_symmetric.witx wasi_ephemeral_crypto_signatures.witx wasi_ephemeral_crypto_kx.witx wasi_ephemeral_crypto_external_secrets.witx 4 | witx-codegen --output-type overview -o $@ wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_symmetric.witx wasi_ephemeral_crypto_signatures.witx wasi_ephemeral_crypto_kx.witx wasi_ephemeral_crypto_external_secrets.witx 5 | 6 | wasi_ephemeral_crypto.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_symmetric.witx wasi_ephemeral_crypto_signatures.witx wasi_ephemeral_crypto_kx.witx wasi_ephemeral_crypto_external_secrets.witx 7 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_symmetric.witx wasi_ephemeral_crypto_signatures.witx wasi_ephemeral_crypto_kx.witx wasi_ephemeral_crypto_external_secrets.witx 8 | 9 | wasi_ephemeral_crypto_common.md: wasi_ephemeral_crypto_common.witx 10 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_common.witx 11 | 12 | wasi_ephemeral_crypto_asymmetric_common.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx 13 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_asymmetric_common.witx 14 | 15 | wasi_ephemeral_crypto_symmetric.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_symmetric.witx 16 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_symmetric.witx 17 | 18 | wasi_ephemeral_crypto_signatures.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_signatures.witx 19 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_signatures.witx 20 | 21 | wasi_ephemeral_crypto_kx.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_kx.witx 22 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_kx.witx 23 | 24 | wasi_ephemeral_crypto_external_secrets.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_external_secrets.witx 25 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_external_secrets.witx 26 | 27 | wasi_ephemeral_crypto_symmetric_batch.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_symmetric.witx wasi_ephemeral_crypto_symmetric_batch.witx 28 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_symmetric_batch.witx 29 | 30 | wasi_ephemeral_crypto_signatures_batch.md: wasi_ephemeral_crypto_common.witx wasi_ephemeral_crypto_asymmetric_common.witx wasi_ephemeral_crypto_signatures.witx wasi_ephemeral_crypto_signatures_batch.witx 31 | witx-codegen --output-type markdown -o $@ wasi_ephemeral_crypto_signatures_batch.witx 32 | 33 | clean: 34 | -rm -f *.md *.txt 35 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto.txt: -------------------------------------------------------------------------------- 1 | * API overview * 2 | 3 | 4 | ---------------------- Module: [wasi_ephemeral_crypto_common] ---------------------- 5 | 6 | enum crypto_errno: (tag: u16) 7 | - success: 0 8 | - guest_error: 1 9 | - not_implemented: 2 10 | - unsupported_feature: 3 11 | - prohibited_operation: 4 12 | - unsupported_encoding: 5 13 | - unsupported_algorithm: 6 14 | - unsupported_option: 7 15 | - invalid_key: 8 16 | - invalid_length: 9 17 | - verification_failed: 10 18 | - rng_error: 11 19 | - algorithm_failure: 12 20 | - invalid_signature: 13 21 | - closed: 14 22 | - invalid_handle: 15 23 | - overflow: 16 24 | - internal_error: 17 25 | - too_many_handles: 18 26 | - key_not_supported: 19 27 | - key_required: 20 28 | - invalid_tag: 21 29 | - invalid_operation: 22 30 | - nonce_required: 23 31 | - invalid_nonce: 24 32 | - option_not_set: 25 33 | - not_found: 26 34 | - parameters_missing: 27 35 | - in_progress: 28 36 | - incompatible_keys: 29 37 | - expired: 30 38 | 39 | enum keypair_encoding: (tag: u16) 40 | - raw: 0 41 | - pkcs8: 1 42 | - pem: 2 43 | - local: 3 44 | 45 | enum publickey_encoding: (tag: u16) 46 | - raw: 0 47 | - pkcs8: 1 48 | - pem: 2 49 | - sec: 3 50 | - local: 4 51 | 52 | enum secretkey_encoding: (tag: u16) 53 | - raw: 0 54 | - pkcs8: 1 55 | - pem: 2 56 | - sec: 3 57 | - local: 4 58 | 59 | enum signature_encoding: (tag: u16) 60 | - raw: 0 61 | - der: 1 62 | 63 | enum algorithm_type: (tag: u16) 64 | - signatures: 0 65 | - symmetric: 1 66 | - key_exchange: 2 67 | 68 | alias version = u64 69 | predefined constants for version: 70 | - unspecified = 0xff00000000000000 71 | - latest = 0xff00000000000001 72 | - all = 0xff00000000000002 73 | 74 | alias size = usize 75 | 76 | alias timestamp = u64 77 | 78 | alias u64 = u64 79 | 80 | alias array_output = handle 81 | 82 | alias options = handle 83 | 84 | alias secrets_manager = handle 85 | 86 | alias keypair = handle 87 | 88 | alias signature_state = handle 89 | 90 | alias signature = handle 91 | 92 | alias publickey = handle 93 | 94 | alias secretkey = handle 95 | 96 | alias signature_verification_state = handle 97 | 98 | alias symmetric_state = handle 99 | 100 | alias symmetric_key = handle 101 | 102 | alias symmetric_tag = handle 103 | 104 | enum opt_options_u: (tag: u8) 105 | - some: 0 106 | - none: 1 107 | 108 | union opt_options: (tag: u8) 109 | - some: options 110 | - none: (empty) 111 | 112 | enum opt_symmetric_key_u: (tag: u8) 113 | - some: 0 114 | - none: 1 115 | 116 | union opt_symmetric_key: (tag: u8) 117 | - some: symmetric_key 118 | - none: (empty) 119 | 120 | function options_open(): crypto_errno 121 | - Input: 122 | - algorithm_type: algorithm_type 123 | - Output: 124 | - mut_ptr 125 | 126 | function options_close(): crypto_errno 127 | - Input: 128 | - handle: options 129 | - No output 130 | 131 | function options_set(): crypto_errno 132 | - Input: 133 | - handle: options 134 | - name: string 135 | - value: ptr 136 | - value_len: size 137 | - No output 138 | 139 | function options_set_u64(): crypto_errno 140 | - Input: 141 | - handle: options 142 | - name: string 143 | - value: u64 144 | - No output 145 | 146 | function options_set_guest_buffer(): crypto_errno 147 | - Input: 148 | - handle: options 149 | - name: string 150 | - buffer: mut_ptr 151 | - buffer_len: size 152 | - No output 153 | 154 | function array_output_len(): crypto_errno 155 | - Input: 156 | - array_output: array_output 157 | - Output: 158 | - mut_ptr 159 | 160 | function array_output_pull(): crypto_errno 161 | - Input: 162 | - array_output: array_output 163 | - buf: mut_ptr 164 | - buf_len: size 165 | - Output: 166 | - mut_ptr 167 | 168 | function secrets_manager_open(): crypto_errno 169 | - Input: 170 | - options: opt_options 171 | - Output: 172 | - mut_ptr 173 | 174 | function secrets_manager_close(): crypto_errno 175 | - Input: 176 | - secrets_manager: secrets_manager 177 | - No output 178 | 179 | function secrets_manager_invalidate(): crypto_errno 180 | - Input: 181 | - secrets_manager: secrets_manager 182 | - key_id: ptr 183 | - key_id_len: size 184 | - key_version: version 185 | - No output 186 | 187 | 188 | ---------------------- Module: [wasi_ephemeral_crypto_asymmetric_common] ---------------------- 189 | 190 | function keypair_generate(): crypto_errno 191 | - Input: 192 | - algorithm_type: algorithm_type 193 | - algorithm: string 194 | - options: opt_options 195 | - Output: 196 | - mut_ptr 197 | 198 | function keypair_import(): crypto_errno 199 | - Input: 200 | - algorithm_type: algorithm_type 201 | - algorithm: string 202 | - encoded: ptr 203 | - encoded_len: size 204 | - encoding: keypair_encoding 205 | - Output: 206 | - mut_ptr 207 | 208 | function keypair_generate_managed(): crypto_errno 209 | - Input: 210 | - secrets_manager: secrets_manager 211 | - algorithm_type: algorithm_type 212 | - algorithm: string 213 | - options: opt_options 214 | - Output: 215 | - mut_ptr 216 | 217 | function keypair_store_managed(): crypto_errno 218 | - Input: 219 | - secrets_manager: secrets_manager 220 | - kp: keypair 221 | - kp_id: mut_ptr 222 | - kp_id_max_len: size 223 | - No output 224 | 225 | function keypair_replace_managed(): crypto_errno 226 | - Input: 227 | - secrets_manager: secrets_manager 228 | - kp_old: keypair 229 | - kp_new: keypair 230 | - Output: 231 | - mut_ptr 232 | 233 | function keypair_id(): crypto_errno 234 | - Input: 235 | - kp: keypair 236 | - kp_id: mut_ptr 237 | - kp_id_max_len: size 238 | - Output: 239 | - mut_ptr 240 | - mut_ptr 241 | 242 | function keypair_from_id(): crypto_errno 243 | - Input: 244 | - secrets_manager: secrets_manager 245 | - kp_id: ptr 246 | - kp_id_len: size 247 | - kp_version: version 248 | - Output: 249 | - mut_ptr 250 | 251 | function keypair_from_pk_and_sk(): crypto_errno 252 | - Input: 253 | - publickey: publickey 254 | - secretkey: secretkey 255 | - Output: 256 | - mut_ptr 257 | 258 | function keypair_export(): crypto_errno 259 | - Input: 260 | - kp: keypair 261 | - encoding: keypair_encoding 262 | - Output: 263 | - mut_ptr 264 | 265 | function keypair_publickey(): crypto_errno 266 | - Input: 267 | - kp: keypair 268 | - Output: 269 | - mut_ptr 270 | 271 | function keypair_secretkey(): crypto_errno 272 | - Input: 273 | - kp: keypair 274 | - Output: 275 | - mut_ptr 276 | 277 | function keypair_close(): crypto_errno 278 | - Input: 279 | - kp: keypair 280 | - No output 281 | 282 | function publickey_import(): crypto_errno 283 | - Input: 284 | - algorithm_type: algorithm_type 285 | - algorithm: string 286 | - encoded: ptr 287 | - encoded_len: size 288 | - encoding: publickey_encoding 289 | - Output: 290 | - mut_ptr 291 | 292 | function publickey_export(): crypto_errno 293 | - Input: 294 | - pk: publickey 295 | - encoding: publickey_encoding 296 | - Output: 297 | - mut_ptr 298 | 299 | function publickey_verify(): crypto_errno 300 | - Input: 301 | - pk: publickey 302 | - No output 303 | 304 | function publickey_from_secretkey(): crypto_errno 305 | - Input: 306 | - sk: secretkey 307 | - Output: 308 | - mut_ptr 309 | 310 | function publickey_close(): crypto_errno 311 | - Input: 312 | - pk: publickey 313 | - No output 314 | 315 | function secretkey_import(): crypto_errno 316 | - Input: 317 | - algorithm_type: algorithm_type 318 | - algorithm: string 319 | - encoded: ptr 320 | - encoded_len: size 321 | - encoding: secretkey_encoding 322 | - Output: 323 | - mut_ptr 324 | 325 | function secretkey_export(): crypto_errno 326 | - Input: 327 | - sk: secretkey 328 | - encoding: secretkey_encoding 329 | - Output: 330 | - mut_ptr 331 | 332 | function secretkey_close(): crypto_errno 333 | - Input: 334 | - sk: secretkey 335 | - No output 336 | 337 | 338 | ---------------------- Module: [wasi_ephemeral_crypto_symmetric] ---------------------- 339 | 340 | function symmetric_key_generate(): crypto_errno 341 | - Input: 342 | - algorithm: string 343 | - options: opt_options 344 | - Output: 345 | - mut_ptr 346 | 347 | function symmetric_key_import(): crypto_errno 348 | - Input: 349 | - algorithm: string 350 | - raw: ptr 351 | - raw_len: size 352 | - Output: 353 | - mut_ptr 354 | 355 | function symmetric_key_export(): crypto_errno 356 | - Input: 357 | - symmetric_key: symmetric_key 358 | - Output: 359 | - mut_ptr 360 | 361 | function symmetric_key_close(): crypto_errno 362 | - Input: 363 | - symmetric_key: symmetric_key 364 | - No output 365 | 366 | function symmetric_key_generate_managed(): crypto_errno 367 | - Input: 368 | - secrets_manager: secrets_manager 369 | - algorithm: string 370 | - options: opt_options 371 | - Output: 372 | - mut_ptr 373 | 374 | function symmetric_key_store_managed(): crypto_errno 375 | - Input: 376 | - secrets_manager: secrets_manager 377 | - symmetric_key: symmetric_key 378 | - symmetric_key_id: mut_ptr 379 | - symmetric_key_id_max_len: size 380 | - No output 381 | 382 | function symmetric_key_replace_managed(): crypto_errno 383 | - Input: 384 | - secrets_manager: secrets_manager 385 | - symmetric_key_old: symmetric_key 386 | - symmetric_key_new: symmetric_key 387 | - Output: 388 | - mut_ptr 389 | 390 | function symmetric_key_id(): crypto_errno 391 | - Input: 392 | - symmetric_key: symmetric_key 393 | - symmetric_key_id: mut_ptr 394 | - symmetric_key_id_max_len: size 395 | - Output: 396 | - mut_ptr 397 | - mut_ptr 398 | 399 | function symmetric_key_from_id(): crypto_errno 400 | - Input: 401 | - secrets_manager: secrets_manager 402 | - symmetric_key_id: ptr 403 | - symmetric_key_id_len: size 404 | - symmetric_key_version: version 405 | - Output: 406 | - mut_ptr 407 | 408 | function symmetric_state_open(): crypto_errno 409 | - Input: 410 | - algorithm: string 411 | - key: opt_symmetric_key 412 | - options: opt_options 413 | - Output: 414 | - mut_ptr 415 | 416 | function symmetric_state_options_get(): crypto_errno 417 | - Input: 418 | - handle: symmetric_state 419 | - name: string 420 | - value: mut_ptr 421 | - value_max_len: size 422 | - Output: 423 | - mut_ptr 424 | 425 | function symmetric_state_options_get_u64(): crypto_errno 426 | - Input: 427 | - handle: symmetric_state 428 | - name: string 429 | - Output: 430 | - mut_ptr 431 | 432 | function symmetric_state_clone(): crypto_errno 433 | - Input: 434 | - handle: symmetric_state 435 | - Output: 436 | - mut_ptr 437 | 438 | function symmetric_state_close(): crypto_errno 439 | - Input: 440 | - handle: symmetric_state 441 | - No output 442 | 443 | function symmetric_state_absorb(): crypto_errno 444 | - Input: 445 | - handle: symmetric_state 446 | - data: ptr 447 | - data_len: size 448 | - No output 449 | 450 | function symmetric_state_squeeze(): crypto_errno 451 | - Input: 452 | - handle: symmetric_state 453 | - out: mut_ptr 454 | - out_len: size 455 | - No output 456 | 457 | function symmetric_state_squeeze_tag(): crypto_errno 458 | - Input: 459 | - handle: symmetric_state 460 | - Output: 461 | - mut_ptr 462 | 463 | function symmetric_state_squeeze_key(): crypto_errno 464 | - Input: 465 | - handle: symmetric_state 466 | - alg_str: string 467 | - Output: 468 | - mut_ptr 469 | 470 | function symmetric_state_max_tag_len(): crypto_errno 471 | - Input: 472 | - handle: symmetric_state 473 | - Output: 474 | - mut_ptr 475 | 476 | function symmetric_state_encrypt(): crypto_errno 477 | - Input: 478 | - handle: symmetric_state 479 | - out: mut_ptr 480 | - out_len: size 481 | - data: ptr 482 | - data_len: size 483 | - Output: 484 | - mut_ptr 485 | 486 | function symmetric_state_encrypt_detached(): crypto_errno 487 | - Input: 488 | - handle: symmetric_state 489 | - out: mut_ptr 490 | - out_len: size 491 | - data: ptr 492 | - data_len: size 493 | - Output: 494 | - mut_ptr 495 | 496 | function symmetric_state_decrypt(): crypto_errno 497 | - Input: 498 | - handle: symmetric_state 499 | - out: mut_ptr 500 | - out_len: size 501 | - data: ptr 502 | - data_len: size 503 | - Output: 504 | - mut_ptr 505 | 506 | function symmetric_state_decrypt_detached(): crypto_errno 507 | - Input: 508 | - handle: symmetric_state 509 | - out: mut_ptr 510 | - out_len: size 511 | - data: ptr 512 | - data_len: size 513 | - raw_tag: ptr 514 | - raw_tag_len: size 515 | - Output: 516 | - mut_ptr 517 | 518 | function symmetric_state_ratchet(): crypto_errno 519 | - Input: 520 | - handle: symmetric_state 521 | - No output 522 | 523 | function symmetric_tag_len(): crypto_errno 524 | - Input: 525 | - symmetric_tag: symmetric_tag 526 | - Output: 527 | - mut_ptr 528 | 529 | function symmetric_tag_pull(): crypto_errno 530 | - Input: 531 | - symmetric_tag: symmetric_tag 532 | - buf: mut_ptr 533 | - buf_len: size 534 | - Output: 535 | - mut_ptr 536 | 537 | function symmetric_tag_verify(): crypto_errno 538 | - Input: 539 | - symmetric_tag: symmetric_tag 540 | - expected_raw_tag_ptr: ptr 541 | - expected_raw_tag_len: size 542 | - No output 543 | 544 | function symmetric_tag_close(): crypto_errno 545 | - Input: 546 | - symmetric_tag: symmetric_tag 547 | - No output 548 | 549 | 550 | ---------------------- Module: [wasi_ephemeral_crypto_signatures] ---------------------- 551 | 552 | alias signature_keypair = handle 553 | 554 | alias signature_publickey = handle 555 | 556 | alias signature_secretkey = handle 557 | 558 | function signature_export(): crypto_errno 559 | - Input: 560 | - signature: signature 561 | - encoding: signature_encoding 562 | - Output: 563 | - mut_ptr 564 | 565 | function signature_import(): crypto_errno 566 | - Input: 567 | - algorithm: string 568 | - encoded: ptr 569 | - encoded_len: size 570 | - encoding: signature_encoding 571 | - Output: 572 | - mut_ptr 573 | 574 | function signature_state_open(): crypto_errno 575 | - Input: 576 | - kp: signature_keypair 577 | - Output: 578 | - mut_ptr 579 | 580 | function signature_state_update(): crypto_errno 581 | - Input: 582 | - state: signature_state 583 | - input: ptr 584 | - input_len: size 585 | - No output 586 | 587 | function signature_state_sign(): crypto_errno 588 | - Input: 589 | - state: signature_state 590 | - Output: 591 | - mut_ptr 592 | 593 | function signature_state_close(): crypto_errno 594 | - Input: 595 | - state: signature_state 596 | - No output 597 | 598 | function signature_verification_state_open(): crypto_errno 599 | - Input: 600 | - kp: signature_publickey 601 | - Output: 602 | - mut_ptr 603 | 604 | function signature_verification_state_update(): crypto_errno 605 | - Input: 606 | - state: signature_verification_state 607 | - input: ptr 608 | - input_len: size 609 | - No output 610 | 611 | function signature_verification_state_verify(): crypto_errno 612 | - Input: 613 | - state: signature_verification_state 614 | - signature: signature 615 | - No output 616 | 617 | function signature_verification_state_close(): crypto_errno 618 | - Input: 619 | - state: signature_verification_state 620 | - No output 621 | 622 | function signature_close(): crypto_errno 623 | - Input: 624 | - signature: signature 625 | - No output 626 | 627 | 628 | ---------------------- Module: [wasi_ephemeral_crypto_kx] ---------------------- 629 | 630 | alias kx_keypair = handle 631 | 632 | alias kx_publickey = handle 633 | 634 | alias kx_secretkey = handle 635 | 636 | function kx_dh(): crypto_errno 637 | - Input: 638 | - pk: publickey 639 | - sk: secretkey 640 | - Output: 641 | - mut_ptr 642 | 643 | function kx_encapsulate(): crypto_errno 644 | - Input: 645 | - pk: publickey 646 | - Output: 647 | - mut_ptr 648 | - mut_ptr 649 | 650 | function kx_decapsulate(): crypto_errno 651 | - Input: 652 | - sk: secretkey 653 | - encapsulated_secret: ptr 654 | - encapsulated_secret_len: size 655 | - Output: 656 | - mut_ptr 657 | 658 | 659 | ---------------------- Module: [wasi_ephemeral_crypto_external_secrets] ---------------------- 660 | 661 | function external_secret_store(): crypto_errno 662 | - Input: 663 | - secrets_manager: secrets_manager 664 | - secret: ptr 665 | - secret_len: size 666 | - expiration: timestamp 667 | - secret_id: mut_ptr 668 | - secret_id_max_len: size 669 | - No output 670 | 671 | function external_secret_replace(): crypto_errno 672 | - Input: 673 | - secrets_manager: secrets_manager 674 | - secret: ptr 675 | - secret_len: size 676 | - expiration: timestamp 677 | - secret_id: ptr 678 | - secret_id_len: size 679 | - Output: 680 | - mut_ptr 681 | 682 | function external_secret_from_id(): crypto_errno 683 | - Input: 684 | - secrets_manager: secrets_manager 685 | - secret_id: ptr 686 | - secret_id_len: size 687 | - secret_version: version 688 | - Output: 689 | - mut_ptr 690 | 691 | function external_secret_invalidate(): crypto_errno 692 | - Input: 693 | - secrets_manager: secrets_manager 694 | - secret_id: ptr 695 | - secret_id_len: size 696 | - secret_version: version 697 | - No output 698 | 699 | function external_secret_encapsulate(): crypto_errno 700 | - Input: 701 | - secrets_manager: secrets_manager 702 | - secret: ptr 703 | - secret_len: size 704 | - expiration: timestamp 705 | - Output: 706 | - mut_ptr 707 | 708 | function external_secret_decapsulate(): crypto_errno 709 | - Input: 710 | - secrets_manager: secrets_manager 711 | - encrypted_secret: ptr 712 | - encrypted_secret_len: size 713 | - Output: 714 | - mut_ptr 715 | 716 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_asymmetric_common.witx: -------------------------------------------------------------------------------- 1 | (module $wasi_ephemeral_crypto_asymmetric_common 2 | (use * from $wasi_ephemeral_crypto_common) 3 | 4 | ;;; Generate a new key pair. 5 | ;;; 6 | ;;; Internally, a key pair stores the supplied algorithm and optional parameters. 7 | ;;; 8 | ;;; Trying to use that key pair with different parameters will throw an `invalid_key` error. 9 | ;;; 10 | ;;; This function may return `$crypto_errno.unsupported_feature` if key generation is not supported by the host for the chosen algorithm. 11 | ;;; 12 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 13 | ;;; 14 | ;;; Finally, if generating that type of key pair is an expensive operation, the function may return `in_progress`. 15 | ;;; In that case, the guest should retry with the same parameters until the function completes. 16 | ;;; 17 | ;;; Example usage: 18 | ;;; 19 | ;;; ```rust 20 | ;;; let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?; 21 | ;;; ``` 22 | (@interface func (export "keypair_generate") 23 | (param $algorithm_type $algorithm_type) 24 | (param $algorithm string) 25 | (param $options $opt_options) 26 | (result $error (expected $keypair (error $crypto_errno))) 27 | ) 28 | 29 | ;;; Import a key pair. 30 | ;;; 31 | ;;; This function creates a `keypair` object from existing material. 32 | ;;; 33 | ;;; It may return `unsupported_algorithm` if the encoding scheme is not supported, or `invalid_key` if the key cannot be decoded. 34 | ;;; 35 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 36 | ;;; 37 | ;;; Example usage: 38 | ;;; 39 | ;;; ```rust 40 | ;;; let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?; 41 | ;;; ``` 42 | (@interface func (export "keypair_import") 43 | (param $algorithm_type $algorithm_type) 44 | (param $algorithm string) 45 | (param $encoded (@witx const_pointer u8)) 46 | (param $encoded_len $size) 47 | (param $encoding $keypair_encoding) 48 | (result $error (expected $keypair (error $crypto_errno))) 49 | ) 50 | 51 | ;;; __(optional)__ 52 | ;;; Generate a new managed key pair. 53 | ;;; 54 | ;;; The key pair is generated and stored by the secrets management facilities. 55 | ;;; 56 | ;;; It may be used through its identifier, but the host may not allow it to be exported. 57 | ;;; 58 | ;;; The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host, 59 | ;;; or `unsupported_algorithm` if a key cannot be created for the chosen algorithm. 60 | ;;; 61 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 62 | ;;; 63 | ;;; This is also an optional import, meaning that the function may not even exist. 64 | (@interface func (export "keypair_generate_managed") 65 | (param $secrets_manager $secrets_manager) 66 | (param $algorithm_type $algorithm_type) 67 | (param $algorithm string) 68 | (param $options $opt_options) 69 | (result $error (expected $keypair (error $crypto_errno))) 70 | ) 71 | 72 | ;;; __(optional)__ 73 | ;;; Store a key pair into the secrets manager. 74 | ;;; 75 | ;;; On success, the function stores the key pair identifier into `$kp_id`, 76 | ;;; into which up to `$kp_id_max_len` can be written. 77 | ;;; 78 | ;;; The function returns `overflow` if the supplied buffer is too small. 79 | (@interface func (export "keypair_store_managed") 80 | (param $secrets_manager $secrets_manager) 81 | (param $kp $keypair) 82 | (param $kp_id (@witx pointer u8)) 83 | (param $kp_id_max_len $size) 84 | (result $error (expected (error $crypto_errno))) 85 | ) 86 | 87 | ;;; __(optional)__ 88 | ;;; Replace a managed key pair. 89 | ;;; 90 | ;;; This function crates a new version of a managed key pair, by replacing `$kp_old` with `$kp_new`. 91 | ;;; 92 | ;;; It does several things: 93 | ;;; 94 | ;;; - The key identifier for `$kp_new` is set to the one of `$kp_old`. 95 | ;;; - A new, unique version identifier is assigned to `$kp_new`. This version will be equivalent to using `$version_latest` until the key is replaced. 96 | ;;; - The `$kp_old` handle is closed. 97 | ;;; 98 | ;;; Both keys must share the same algorithm and have compatible parameters. If this is not the case, `incompatible_keys` is returned. 99 | ;;; 100 | ;;; The function may also return the `unsupported_feature` error code if secrets management facilities are not supported by the host, 101 | ;;; or if keys cannot be rotated. 102 | ;;; 103 | ;;; Finally, `prohibited_operation` can be returned if `$kp_new` wasn't created by the secrets manager, and the secrets manager prohibits imported keys. 104 | ;;; 105 | ;;; If the operation succeeded, the new version is returned. 106 | ;;; 107 | ;;; This is an optional import, meaning that the function may not even exist. 108 | (@interface func (export "keypair_replace_managed") 109 | (param $secrets_manager $secrets_manager) 110 | (param $kp_old $keypair) 111 | (param $kp_new $keypair) 112 | (result $error (expected $version (error $crypto_errno))) 113 | ) 114 | 115 | ;;; __(optional)__ 116 | ;;; Return the key pair identifier and version of a managed key pair. 117 | ;;; 118 | ;;; If the key pair is not managed, `unsupported_feature` is returned instead. 119 | ;;; 120 | ;;; This is an optional import, meaning that the function may not even exist. 121 | (@interface func (export "keypair_id") 122 | (param $kp $keypair) 123 | (param $kp_id (@witx pointer u8)) 124 | (param $kp_id_max_len $size) 125 | (result $error (expected (tuple $size $version) (error $crypto_errno))) 126 | ) 127 | 128 | ;;; __(optional)__ 129 | ;;; Return a managed key pair from a key identifier. 130 | ;;; 131 | ;;; `kp_version` can be set to `version_latest` to retrieve the most recent version of a key pair. 132 | ;;; 133 | ;;; If no key pair matching the provided information is found, `not_found` is returned instead. 134 | ;;; 135 | ;;; This is an optional import, meaning that the function may not even exist. 136 | ;;; ``` 137 | (@interface func (export "keypair_from_id") 138 | (param $secrets_manager $secrets_manager) 139 | (param $kp_id (@witx const_pointer u8)) 140 | (param $kp_id_len $size) 141 | (param $kp_version $version) 142 | (result $error (expected $keypair (error $crypto_errno))) 143 | ) 144 | 145 | ;;; Create a key pair from a public key and a secret key. 146 | (@interface func (export "keypair_from_pk_and_sk") 147 | (param $publickey $publickey) 148 | (param $secretkey $secretkey) 149 | (result $error (expected $keypair (error $crypto_errno))) 150 | ) 151 | 152 | ;;; Export a key pair as the given encoding format. 153 | ;;; 154 | ;;; May return `prohibited_operation` if this operation is denied or `unsupported_encoding` if the encoding is not supported. 155 | (@interface func (export "keypair_export") 156 | (param $kp $keypair) 157 | (param $encoding $keypair_encoding) 158 | (result $error (expected $array_output (error $crypto_errno))) 159 | ) 160 | 161 | ;;; Get the public key of a key pair. 162 | (@interface func (export "keypair_publickey") 163 | (param $kp $keypair) 164 | (result $error (expected $publickey (error $crypto_errno))) 165 | ) 166 | 167 | ;;; Get the secret key of a key pair. 168 | (@interface func (export "keypair_secretkey") 169 | (param $kp $keypair) 170 | (result $error (expected $secretkey (error $crypto_errno))) 171 | ) 172 | 173 | ;;; Destroy a key pair. 174 | ;;; 175 | ;;; The host will automatically wipe traces of the secret key from memory. 176 | ;;; 177 | ;;; If this is a managed key, the key will not be removed from persistent storage, and can be reconstructed later using the key identifier. 178 | (@interface func (export "keypair_close") 179 | (param $kp $keypair) 180 | (result $error (expected (error $crypto_errno))) 181 | ) 182 | 183 | ;;; Import a public key. 184 | ;;; 185 | ;;; The function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type. 186 | ;;; 187 | ;;; It may also return `invalid_key` if the key doesn't appear to match the supplied algorithm. 188 | ;;; 189 | ;;; Finally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host. 190 | ;;; 191 | ;;; Example usage: 192 | ;;; 193 | ;;; ```rust 194 | ;;; let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?; 195 | ;;; ``` 196 | (@interface func (export "publickey_import") 197 | (param $algorithm_type $algorithm_type) 198 | (param $algorithm string) 199 | (param $encoded (@witx const_pointer u8)) 200 | (param $encoded_len $size) 201 | (param $encoding $publickey_encoding) 202 | (result $error (expected $publickey (error $crypto_errno))) 203 | ) 204 | 205 | ;;; Export a public key as the given encoding format. 206 | ;;; 207 | ;;; May return `unsupported_encoding` if the encoding is not supported. 208 | (@interface func (export "publickey_export") 209 | (param $pk $publickey) 210 | (param $encoding $publickey_encoding) 211 | (result $error (expected $array_output (error $crypto_errno))) 212 | ) 213 | 214 | ;;; Check that a public key is valid and in canonical form. 215 | ;;; 216 | ;;; This function may perform stricter checks than those made during importation at the expense of additional CPU cycles. 217 | ;;; 218 | ;;; The function returns `invalid_key` if the public key didn't pass the checks. 219 | (@interface func (export "publickey_verify") 220 | (param $pk $publickey) 221 | (result $error (expected (error $crypto_errno))) 222 | ) 223 | 224 | ;;; Compute the public key for a secret key. 225 | (@interface func (export "publickey_from_secretkey") 226 | (param $sk $secretkey) 227 | (result $error (expected $publickey (error $crypto_errno))) 228 | ) 229 | 230 | ;;; Destroy a public key. 231 | ;;; 232 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 233 | (@interface func (export "publickey_close") 234 | (param $pk $publickey) 235 | (result $error (expected (error $crypto_errno))) 236 | ) 237 | 238 | ;;; Import a secret key. 239 | ;;; 240 | ;;; The function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type. 241 | ;;; 242 | ;;; It may also return `invalid_key` if the key doesn't appear to match the supplied algorithm. 243 | ;;; 244 | ;;; Finally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host. 245 | ;;; 246 | ;;; Example usage: 247 | ;;; 248 | ;;; ```rust 249 | ;;; let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?; 250 | ;;; ``` 251 | (@interface func (export "secretkey_import") 252 | (param $algorithm_type $algorithm_type) 253 | (param $algorithm string) 254 | (param $encoded (@witx const_pointer u8)) 255 | (param $encoded_len $size) 256 | (param $encoding $secretkey_encoding) 257 | (result $error (expected $secretkey (error $crypto_errno))) 258 | ) 259 | 260 | ;;; Export a secret key as the given encoding format. 261 | ;;; 262 | ;;; May return `unsupported_encoding` if the encoding is not supported. 263 | (@interface func (export "secretkey_export") 264 | (param $sk $secretkey) 265 | (param $encoding $secretkey_encoding) 266 | (result $error (expected $array_output (error $crypto_errno))) 267 | ) 268 | 269 | ;;; Destroy a secret key. 270 | ;;; 271 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 272 | (@interface func (export "secretkey_close") 273 | (param $sk $secretkey) 274 | (result $error (expected (error $crypto_errno))) 275 | ) 276 | ) 277 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_common.md: -------------------------------------------------------------------------------- 1 | 2 | # Module: wasi_ephemeral_crypto_common 3 | 4 | ## Table of contents 5 | 6 | ### Types list: 7 | 8 | [**[All](#types)**] - [_[`crypto_errno`](#crypto_errno)_] - [_[`keypair_encoding`](#keypair_encoding)_] - [_[`publickey_encoding`](#publickey_encoding)_] - [_[`secretkey_encoding`](#secretkey_encoding)_] - [_[`signature_encoding`](#signature_encoding)_] - [_[`algorithm_type`](#algorithm_type)_] - [_[`version`](#version)_] - [_[`size`](#size)_] - [_[`timestamp`](#timestamp)_] - [_[`u64`](#u64)_] - [_[`array_output`](#array_output)_] - [_[`options`](#options)_] - [_[`secrets_manager`](#secrets_manager)_] - [_[`keypair`](#keypair)_] - [_[`signature_state`](#signature_state)_] - [_[`signature`](#signature)_] - [_[`publickey`](#publickey)_] - [_[`secretkey`](#secretkey)_] - [_[`signature_verification_state`](#signature_verification_state)_] - [_[`symmetric_state`](#symmetric_state)_] - [_[`symmetric_key`](#symmetric_key)_] - [_[`symmetric_tag`](#symmetric_tag)_] - [_[`opt_options_u`](#opt_options_u)_] - [_[`opt_options`](#opt_options)_] - [_[`opt_symmetric_key_u`](#opt_symmetric_key_u)_] - [_[`opt_symmetric_key`](#opt_symmetric_key)_] 9 | 10 | ### Functions list: 11 | 12 | [**[All](#functions)**] - [[`options_open()`](#options_open)] - [[`options_close()`](#options_close)] - [[`options_set()`](#options_set)] - [[`options_set_u64()`](#options_set_u64)] - [[`options_set_guest_buffer()`](#options_set_guest_buffer)] - [[`array_output_len()`](#array_output_len)] - [[`array_output_pull()`](#array_output_pull)] - [[`secrets_manager_open()`](#secrets_manager_open)] - [[`secrets_manager_close()`](#secrets_manager_close)] - [[`secrets_manager_invalidate()`](#secrets_manager_invalidate)] 13 | 14 | ## Types 15 | 16 | ### _[`crypto_errno`](#crypto_errno)_ 17 | 18 | Enumeration with tag type: `u16`, and the following members: 19 | 20 | * **`success`**: _[`crypto_errno`](#crypto_errno)_ 21 | * **`guest_error`**: _[`crypto_errno`](#crypto_errno)_ 22 | * **`not_implemented`**: _[`crypto_errno`](#crypto_errno)_ 23 | * **`unsupported_feature`**: _[`crypto_errno`](#crypto_errno)_ 24 | * **`prohibited_operation`**: _[`crypto_errno`](#crypto_errno)_ 25 | * **`unsupported_encoding`**: _[`crypto_errno`](#crypto_errno)_ 26 | * **`unsupported_algorithm`**: _[`crypto_errno`](#crypto_errno)_ 27 | * **`unsupported_option`**: _[`crypto_errno`](#crypto_errno)_ 28 | * **`invalid_key`**: _[`crypto_errno`](#crypto_errno)_ 29 | * **`invalid_length`**: _[`crypto_errno`](#crypto_errno)_ 30 | * **`verification_failed`**: _[`crypto_errno`](#crypto_errno)_ 31 | * **`rng_error`**: _[`crypto_errno`](#crypto_errno)_ 32 | * **`algorithm_failure`**: _[`crypto_errno`](#crypto_errno)_ 33 | * **`invalid_signature`**: _[`crypto_errno`](#crypto_errno)_ 34 | * **`closed`**: _[`crypto_errno`](#crypto_errno)_ 35 | * **`invalid_handle`**: _[`crypto_errno`](#crypto_errno)_ 36 | * **`overflow`**: _[`crypto_errno`](#crypto_errno)_ 37 | * **`internal_error`**: _[`crypto_errno`](#crypto_errno)_ 38 | * **`too_many_handles`**: _[`crypto_errno`](#crypto_errno)_ 39 | * **`key_not_supported`**: _[`crypto_errno`](#crypto_errno)_ 40 | * **`key_required`**: _[`crypto_errno`](#crypto_errno)_ 41 | * **`invalid_tag`**: _[`crypto_errno`](#crypto_errno)_ 42 | * **`invalid_operation`**: _[`crypto_errno`](#crypto_errno)_ 43 | * **`nonce_required`**: _[`crypto_errno`](#crypto_errno)_ 44 | * **`invalid_nonce`**: _[`crypto_errno`](#crypto_errno)_ 45 | * **`option_not_set`**: _[`crypto_errno`](#crypto_errno)_ 46 | * **`not_found`**: _[`crypto_errno`](#crypto_errno)_ 47 | * **`parameters_missing`**: _[`crypto_errno`](#crypto_errno)_ 48 | * **`in_progress`**: _[`crypto_errno`](#crypto_errno)_ 49 | * **`incompatible_keys`**: _[`crypto_errno`](#crypto_errno)_ 50 | * **`expired`**: _[`crypto_errno`](#crypto_errno)_ 51 | 52 | > Error codes. 53 | 54 | 55 | --- 56 | 57 | ### _[`keypair_encoding`](#keypair_encoding)_ 58 | 59 | Enumeration with tag type: `u16`, and the following members: 60 | 61 | * **`raw`**: _[`keypair_encoding`](#keypair_encoding)_ 62 | * **`pkcs8`**: _[`keypair_encoding`](#keypair_encoding)_ 63 | * **`pem`**: _[`keypair_encoding`](#keypair_encoding)_ 64 | * **`local`**: _[`keypair_encoding`](#keypair_encoding)_ 65 | 66 | > Encoding to use for importing or exporting a key pair. 67 | 68 | 69 | --- 70 | 71 | ### _[`publickey_encoding`](#publickey_encoding)_ 72 | 73 | Enumeration with tag type: `u16`, and the following members: 74 | 75 | * **`raw`**: _[`publickey_encoding`](#publickey_encoding)_ 76 | * **`pkcs8`**: _[`publickey_encoding`](#publickey_encoding)_ 77 | * **`pem`**: _[`publickey_encoding`](#publickey_encoding)_ 78 | * **`sec`**: _[`publickey_encoding`](#publickey_encoding)_ 79 | * **`local`**: _[`publickey_encoding`](#publickey_encoding)_ 80 | 81 | > Encoding to use for importing or exporting a public key. 82 | 83 | 84 | --- 85 | 86 | ### _[`secretkey_encoding`](#secretkey_encoding)_ 87 | 88 | Enumeration with tag type: `u16`, and the following members: 89 | 90 | * **`raw`**: _[`secretkey_encoding`](#secretkey_encoding)_ 91 | * **`pkcs8`**: _[`secretkey_encoding`](#secretkey_encoding)_ 92 | * **`pem`**: _[`secretkey_encoding`](#secretkey_encoding)_ 93 | * **`sec`**: _[`secretkey_encoding`](#secretkey_encoding)_ 94 | * **`local`**: _[`secretkey_encoding`](#secretkey_encoding)_ 95 | 96 | > Encoding to use for importing or exporting a secret key. 97 | 98 | 99 | --- 100 | 101 | ### _[`signature_encoding`](#signature_encoding)_ 102 | 103 | Enumeration with tag type: `u16`, and the following members: 104 | 105 | * **`raw`**: _[`signature_encoding`](#signature_encoding)_ 106 | * **`der`**: _[`signature_encoding`](#signature_encoding)_ 107 | 108 | > Encoding to use for importing or exporting a signature. 109 | 110 | 111 | --- 112 | 113 | ### _[`algorithm_type`](#algorithm_type)_ 114 | 115 | Enumeration with tag type: `u16`, and the following members: 116 | 117 | * **`signatures`**: _[`algorithm_type`](#algorithm_type)_ 118 | * **`symmetric`**: _[`algorithm_type`](#algorithm_type)_ 119 | * **`key_exchange`**: _[`algorithm_type`](#algorithm_type)_ 120 | 121 | > An algorithm category. 122 | 123 | 124 | --- 125 | 126 | ### _[`version`](#version)_ 127 | Alias for `u64`. 128 | 129 | Predefined constants for _[`version`](#version)_: 130 | 131 | * **`unspecified`** = `0xff00000000000000` 132 | * **`latest`** = `0xff00000000000001` 133 | * **`all`** = `0xff00000000000002` 134 | 135 | > Version of a managed key. 136 | > 137 | > A version can be an arbitrary `u64` integer, with the exception of some reserved values. 138 | 139 | 140 | --- 141 | 142 | ### _[`size`](#size)_ 143 | Alias for `usize`. 144 | 145 | 146 | > Size of a value. 147 | 148 | 149 | --- 150 | 151 | ### _[`timestamp`](#timestamp)_ 152 | Alias for `u64`. 153 | 154 | 155 | > A UNIX timestamp, in seconds since 01/01/1970. 156 | 157 | 158 | --- 159 | 160 | ### _[`u64`](#u64)_ 161 | Alias for `u64`. 162 | 163 | 164 | > A 64-bit value 165 | 166 | 167 | --- 168 | 169 | ### _[`array_output`](#array_output)_ 170 | Alias for `handle`. 171 | 172 | 173 | > Handle for functions returning output whose size may be large or not known in advance. 174 | > 175 | > An `array_output` object contains a host-allocated byte array. 176 | > 177 | > A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. 178 | > In addition, the content of such an object can be consumed by a guest in a streaming fashion. 179 | > 180 | > An `array_output` handle is automatically closed after its full content has been consumed. 181 | 182 | 183 | --- 184 | 185 | ### _[`options`](#options)_ 186 | Alias for `handle`. 187 | 188 | 189 | > A set of options. 190 | > 191 | > This type is used to set non-default parameters. 192 | > 193 | > The exact set of allowed options depends on the algorithm being used. 194 | 195 | 196 | --- 197 | 198 | ### _[`secrets_manager`](#secrets_manager)_ 199 | Alias for `handle`. 200 | 201 | 202 | > A handle to the optional secrets management facilities offered by a host. 203 | > 204 | > This is used to generate, retrieve and invalidate managed keys. 205 | 206 | 207 | --- 208 | 209 | ### _[`keypair`](#keypair)_ 210 | Alias for `handle`. 211 | 212 | 213 | > A key pair. 214 | 215 | 216 | --- 217 | 218 | ### _[`signature_state`](#signature_state)_ 219 | Alias for `handle`. 220 | 221 | 222 | > A state to absorb data to be signed. 223 | > 224 | > After a signature has been computed or verified, the state remains valid for further operations. 225 | > 226 | > A subsequent signature would sign all the data accumulated since the creation of the state object. 227 | 228 | 229 | --- 230 | 231 | ### _[`signature`](#signature)_ 232 | Alias for `handle`. 233 | 234 | 235 | > A signature. 236 | 237 | 238 | --- 239 | 240 | ### _[`publickey`](#publickey)_ 241 | Alias for `handle`. 242 | 243 | 244 | > A public key, for key exchange and signature verification. 245 | 246 | 247 | --- 248 | 249 | ### _[`secretkey`](#secretkey)_ 250 | Alias for `handle`. 251 | 252 | 253 | > A secret key, for key exchange mechanisms. 254 | 255 | 256 | --- 257 | 258 | ### _[`signature_verification_state`](#signature_verification_state)_ 259 | Alias for `handle`. 260 | 261 | 262 | > A state to absorb signed data to be verified. 263 | 264 | 265 | --- 266 | 267 | ### _[`symmetric_state`](#symmetric_state)_ 268 | Alias for `handle`. 269 | 270 | 271 | > A state to perform symmetric operations. 272 | > 273 | > The state is not reset nor invalidated after an option has been performed. 274 | > Incremental updates and sessions are thus supported. 275 | 276 | 277 | --- 278 | 279 | ### _[`symmetric_key`](#symmetric_key)_ 280 | Alias for `handle`. 281 | 282 | 283 | > A symmetric key. 284 | > 285 | > The key can be imported from raw bytes, or can be a reference to a managed key. 286 | > 287 | > If it was imported, the host will wipe it from memory as soon as the handle is closed. 288 | 289 | 290 | --- 291 | 292 | ### _[`symmetric_tag`](#symmetric_tag)_ 293 | Alias for `handle`. 294 | 295 | 296 | > An authentication tag. 297 | > 298 | > This is an object returned by functions computing authentication tags. 299 | > 300 | > A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function. 301 | > 302 | > This object type can't be directly created from raw bytes. They are only returned by functions computing MACs. 303 | > 304 | > The host is responsible for securely wiping them from memory on close. 305 | 306 | 307 | --- 308 | 309 | ### _[`opt_options_u`](#opt_options_u)_ 310 | 311 | Enumeration with tag type: `u8`, and the following members: 312 | 313 | * **`some`**: _[`opt_options_u`](#opt_options_u)_ 314 | * **`none`**: _[`opt_options_u`](#opt_options_u)_ 315 | 316 | > Options index, only required by the Interface Types translation layer. 317 | 318 | 319 | --- 320 | 321 | ### _[`opt_options`](#opt_options)_ 322 | Tagged union with tag type: `u8` and the following possibilities: 323 | 324 | * **`some`**: _[`options`](#options)_ 325 | * **`none`**: _(empty)_ 326 | 327 | > An optional options set. 328 | > 329 | > This union simulates an `Option\` type to make the `options` parameter of some functions optional. 330 | 331 | 332 | --- 333 | 334 | ### _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 335 | 336 | Enumeration with tag type: `u8`, and the following members: 337 | 338 | * **`some`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 339 | * **`none`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 340 | 341 | > Symmetric key index, only required by the Interface Types translation layer. 342 | 343 | 344 | --- 345 | 346 | ### _[`opt_symmetric_key`](#opt_symmetric_key)_ 347 | Tagged union with tag type: `u8` and the following possibilities: 348 | 349 | * **`some`**: _[`symmetric_key`](#symmetric_key)_ 350 | * **`none`**: _(empty)_ 351 | 352 | > An optional symmetric key. 353 | > 354 | > This union simulates an `Option\` type to make the `symmetric_key` parameter of some functions optional. 355 | 356 | 357 | --- 358 | 359 | ## Functions 360 | 361 | ### [`options_open()`](#options_open) 362 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 363 | 364 | #### Input: 365 | 366 | * **`algorithm_type`**: _[`algorithm_type`](#algorithm_type)_ 367 | 368 | #### Output: 369 | 370 | * _[`options`](#options)_ mutable pointer 371 | 372 | > Create a new object to set non-default options. 373 | > 374 | > Example usage: 375 | > 376 | > ```rust 377 | > let options_handle = options_open(AlgorithmType::Symmetric)?; 378 | > options_set(options_handle, "context", context)?; 379 | > options_set_u64(options_handle, "threads", 4)?; 380 | > let state = symmetric_state_open("BLAKE3", None, Some(options_handle))?; 381 | > options_close(options_handle)?; 382 | > ``` 383 | 384 | 385 | --- 386 | 387 | ### [`options_close()`](#options_close) 388 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 389 | 390 | #### Input: 391 | 392 | * **`handle`**: _[`options`](#options)_ 393 | 394 | This function has no output. 395 | 396 | > Destroy an options object. 397 | > 398 | > Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 399 | 400 | 401 | --- 402 | 403 | ### [`options_set()`](#options_set) 404 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 405 | 406 | #### Input: 407 | 408 | * **`handle`**: _[`options`](#options)_ 409 | * **`name`**: `string` 410 | * **`value`**: `u8` pointer 411 | * **`value_len`**: _[`size`](#size)_ 412 | 413 | This function has no output. 414 | 415 | > Set or update an option. 416 | > 417 | > This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. 418 | > 419 | > This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. 420 | 421 | 422 | --- 423 | 424 | ### [`options_set_u64()`](#options_set_u64) 425 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 426 | 427 | #### Input: 428 | 429 | * **`handle`**: _[`options`](#options)_ 430 | * **`name`**: `string` 431 | * **`value`**: `u64` 432 | 433 | This function has no output. 434 | 435 | > Set or update an integer option. 436 | > 437 | > This is used to set algorithm-specific parameters. 438 | > 439 | > This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. 440 | 441 | 442 | --- 443 | 444 | ### [`options_set_guest_buffer()`](#options_set_guest_buffer) 445 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 446 | 447 | #### Input: 448 | 449 | * **`handle`**: _[`options`](#options)_ 450 | * **`name`**: `string` 451 | * **`buffer`**: `u8` mutable pointer 452 | * **`buffer_len`**: _[`size`](#size)_ 453 | 454 | This function has no output. 455 | 456 | > Set or update a guest-allocated memory that the host can use or return data into. 457 | > 458 | > This is for example used to set the scratch buffer required by memory-hard functions. 459 | > 460 | > This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. 461 | 462 | 463 | --- 464 | 465 | ### [`array_output_len()`](#array_output_len) 466 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 467 | 468 | #### Input: 469 | 470 | * **`array_output`**: _[`array_output`](#array_output)_ 471 | 472 | #### Output: 473 | 474 | * _[`size`](#size)_ mutable pointer 475 | 476 | > Return the length of an `array_output` object. 477 | > 478 | > 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. 479 | 480 | 481 | --- 482 | 483 | ### [`array_output_pull()`](#array_output_pull) 484 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 485 | 486 | #### Input: 487 | 488 | * **`array_output`**: _[`array_output`](#array_output)_ 489 | * **`buf`**: `u8` mutable pointer 490 | * **`buf_len`**: _[`size`](#size)_ 491 | 492 | #### Output: 493 | 494 | * _[`size`](#size)_ mutable pointer 495 | 496 | > Copy the content of an `array_output` object into an application-allocated buffer. 497 | > 498 | > Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. 499 | > 500 | > 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()`. 501 | > 502 | > The handle is automatically closed after all the data has been consumed. 503 | > 504 | > Example usage: 505 | > 506 | > ```rust 507 | > let len = array_output_len(output_handle)?; 508 | > let mut out = vec![0u8; len]; 509 | > array_output_pull(output_handle, &mut out)?; 510 | > ``` 511 | 512 | 513 | --- 514 | 515 | ### [`secrets_manager_open()`](#secrets_manager_open) 516 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 517 | 518 | #### Input: 519 | 520 | * **`options`**: _[`opt_options`](#opt_options)_ 521 | 522 | #### Output: 523 | 524 | * _[`secrets_manager`](#secrets_manager)_ mutable pointer 525 | 526 | > __(optional)__ 527 | > Create a context to use a secrets manager. 528 | > 529 | > The set of required and supported options is defined by the host. 530 | > 531 | > The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. 532 | > This is also an optional import, meaning that the function may not even exist. 533 | 534 | 535 | --- 536 | 537 | ### [`secrets_manager_close()`](#secrets_manager_close) 538 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 539 | 540 | #### Input: 541 | 542 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 543 | 544 | This function has no output. 545 | 546 | > __(optional)__ 547 | > Destroy a secrets manager context. 548 | > 549 | > The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. 550 | > This is also an optional import, meaning that the function may not even exist. 551 | 552 | 553 | --- 554 | 555 | ### [`secrets_manager_invalidate()`](#secrets_manager_invalidate) 556 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 557 | 558 | #### Input: 559 | 560 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 561 | * **`key_id`**: `u8` pointer 562 | * **`key_id_len`**: _[`size`](#size)_ 563 | * **`key_version`**: _[`version`](#version)_ 564 | 565 | This function has no output. 566 | 567 | > __(optional)__ 568 | > Invalidate a managed key or key pair given an identifier and a version. 569 | > 570 | > This asks the secrets manager to delete or revoke a stored key, a specific version of a key. 571 | > 572 | > `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. 573 | > 574 | > 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. 575 | > 576 | > This is an optional import, meaning that the function may not even exist. 577 | 578 | 579 | --- 580 | 581 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_external_secrets.md: -------------------------------------------------------------------------------- 1 | 2 | # Module: wasi_ephemeral_crypto_external_secrets 3 | 4 | ## Table of contents 5 | 6 | ### Types list: 7 | 8 | [**[All](#types)**] - [_[`crypto_errno`](#crypto_errno)_] - [_[`keypair_encoding`](#keypair_encoding)_] - [_[`publickey_encoding`](#publickey_encoding)_] - [_[`secretkey_encoding`](#secretkey_encoding)_] - [_[`signature_encoding`](#signature_encoding)_] - [_[`algorithm_type`](#algorithm_type)_] - [_[`version`](#version)_] - [_[`size`](#size)_] - [_[`timestamp`](#timestamp)_] - [_[`u64`](#u64)_] - [_[`array_output`](#array_output)_] - [_[`options`](#options)_] - [_[`secrets_manager`](#secrets_manager)_] - [_[`keypair`](#keypair)_] - [_[`signature_state`](#signature_state)_] - [_[`signature`](#signature)_] - [_[`publickey`](#publickey)_] - [_[`secretkey`](#secretkey)_] - [_[`signature_verification_state`](#signature_verification_state)_] - [_[`symmetric_state`](#symmetric_state)_] - [_[`symmetric_key`](#symmetric_key)_] - [_[`symmetric_tag`](#symmetric_tag)_] - [_[`opt_options_u`](#opt_options_u)_] - [_[`opt_options`](#opt_options)_] - [_[`opt_symmetric_key_u`](#opt_symmetric_key_u)_] - [_[`opt_symmetric_key`](#opt_symmetric_key)_] 9 | 10 | ### Functions list: 11 | 12 | [**[All](#functions)**] - [[`external_secret_store()`](#external_secret_store)] - [[`external_secret_replace()`](#external_secret_replace)] - [[`external_secret_from_id()`](#external_secret_from_id)] - [[`external_secret_invalidate()`](#external_secret_invalidate)] - [[`external_secret_encapsulate()`](#external_secret_encapsulate)] - [[`external_secret_decapsulate()`](#external_secret_decapsulate)] 13 | 14 | ## Types 15 | 16 | ### _[`crypto_errno`](#crypto_errno)_ 17 | 18 | Enumeration with tag type: `u16`, and the following members: 19 | 20 | * **`success`**: _[`crypto_errno`](#crypto_errno)_ 21 | * **`guest_error`**: _[`crypto_errno`](#crypto_errno)_ 22 | * **`not_implemented`**: _[`crypto_errno`](#crypto_errno)_ 23 | * **`unsupported_feature`**: _[`crypto_errno`](#crypto_errno)_ 24 | * **`prohibited_operation`**: _[`crypto_errno`](#crypto_errno)_ 25 | * **`unsupported_encoding`**: _[`crypto_errno`](#crypto_errno)_ 26 | * **`unsupported_algorithm`**: _[`crypto_errno`](#crypto_errno)_ 27 | * **`unsupported_option`**: _[`crypto_errno`](#crypto_errno)_ 28 | * **`invalid_key`**: _[`crypto_errno`](#crypto_errno)_ 29 | * **`invalid_length`**: _[`crypto_errno`](#crypto_errno)_ 30 | * **`verification_failed`**: _[`crypto_errno`](#crypto_errno)_ 31 | * **`rng_error`**: _[`crypto_errno`](#crypto_errno)_ 32 | * **`algorithm_failure`**: _[`crypto_errno`](#crypto_errno)_ 33 | * **`invalid_signature`**: _[`crypto_errno`](#crypto_errno)_ 34 | * **`closed`**: _[`crypto_errno`](#crypto_errno)_ 35 | * **`invalid_handle`**: _[`crypto_errno`](#crypto_errno)_ 36 | * **`overflow`**: _[`crypto_errno`](#crypto_errno)_ 37 | * **`internal_error`**: _[`crypto_errno`](#crypto_errno)_ 38 | * **`too_many_handles`**: _[`crypto_errno`](#crypto_errno)_ 39 | * **`key_not_supported`**: _[`crypto_errno`](#crypto_errno)_ 40 | * **`key_required`**: _[`crypto_errno`](#crypto_errno)_ 41 | * **`invalid_tag`**: _[`crypto_errno`](#crypto_errno)_ 42 | * **`invalid_operation`**: _[`crypto_errno`](#crypto_errno)_ 43 | * **`nonce_required`**: _[`crypto_errno`](#crypto_errno)_ 44 | * **`invalid_nonce`**: _[`crypto_errno`](#crypto_errno)_ 45 | * **`option_not_set`**: _[`crypto_errno`](#crypto_errno)_ 46 | * **`not_found`**: _[`crypto_errno`](#crypto_errno)_ 47 | * **`parameters_missing`**: _[`crypto_errno`](#crypto_errno)_ 48 | * **`in_progress`**: _[`crypto_errno`](#crypto_errno)_ 49 | * **`incompatible_keys`**: _[`crypto_errno`](#crypto_errno)_ 50 | * **`expired`**: _[`crypto_errno`](#crypto_errno)_ 51 | 52 | > Error codes. 53 | 54 | 55 | --- 56 | 57 | ### _[`keypair_encoding`](#keypair_encoding)_ 58 | 59 | Enumeration with tag type: `u16`, and the following members: 60 | 61 | * **`raw`**: _[`keypair_encoding`](#keypair_encoding)_ 62 | * **`pkcs8`**: _[`keypair_encoding`](#keypair_encoding)_ 63 | * **`pem`**: _[`keypair_encoding`](#keypair_encoding)_ 64 | * **`local`**: _[`keypair_encoding`](#keypair_encoding)_ 65 | 66 | > Encoding to use for importing or exporting a key pair. 67 | 68 | 69 | --- 70 | 71 | ### _[`publickey_encoding`](#publickey_encoding)_ 72 | 73 | Enumeration with tag type: `u16`, and the following members: 74 | 75 | * **`raw`**: _[`publickey_encoding`](#publickey_encoding)_ 76 | * **`pkcs8`**: _[`publickey_encoding`](#publickey_encoding)_ 77 | * **`pem`**: _[`publickey_encoding`](#publickey_encoding)_ 78 | * **`sec`**: _[`publickey_encoding`](#publickey_encoding)_ 79 | * **`local`**: _[`publickey_encoding`](#publickey_encoding)_ 80 | 81 | > Encoding to use for importing or exporting a public key. 82 | 83 | 84 | --- 85 | 86 | ### _[`secretkey_encoding`](#secretkey_encoding)_ 87 | 88 | Enumeration with tag type: `u16`, and the following members: 89 | 90 | * **`raw`**: _[`secretkey_encoding`](#secretkey_encoding)_ 91 | * **`pkcs8`**: _[`secretkey_encoding`](#secretkey_encoding)_ 92 | * **`pem`**: _[`secretkey_encoding`](#secretkey_encoding)_ 93 | * **`sec`**: _[`secretkey_encoding`](#secretkey_encoding)_ 94 | * **`local`**: _[`secretkey_encoding`](#secretkey_encoding)_ 95 | 96 | > Encoding to use for importing or exporting a secret key. 97 | 98 | 99 | --- 100 | 101 | ### _[`signature_encoding`](#signature_encoding)_ 102 | 103 | Enumeration with tag type: `u16`, and the following members: 104 | 105 | * **`raw`**: _[`signature_encoding`](#signature_encoding)_ 106 | * **`der`**: _[`signature_encoding`](#signature_encoding)_ 107 | 108 | > Encoding to use for importing or exporting a signature. 109 | 110 | 111 | --- 112 | 113 | ### _[`algorithm_type`](#algorithm_type)_ 114 | 115 | Enumeration with tag type: `u16`, and the following members: 116 | 117 | * **`signatures`**: _[`algorithm_type`](#algorithm_type)_ 118 | * **`symmetric`**: _[`algorithm_type`](#algorithm_type)_ 119 | * **`key_exchange`**: _[`algorithm_type`](#algorithm_type)_ 120 | 121 | > An algorithm category. 122 | 123 | 124 | --- 125 | 126 | ### _[`version`](#version)_ 127 | Alias for `u64`. 128 | 129 | 130 | > Version of a managed key. 131 | > 132 | > A version can be an arbitrary `u64` integer, with the expection of some reserved values. 133 | 134 | 135 | --- 136 | 137 | ### _[`size`](#size)_ 138 | Alias for `usize`. 139 | 140 | 141 | > Size of a value. 142 | 143 | 144 | --- 145 | 146 | ### _[`timestamp`](#timestamp)_ 147 | Alias for `u64`. 148 | 149 | 150 | > A UNIX timestamp, in seconds since 01/01/1970. 151 | 152 | 153 | --- 154 | 155 | ### _[`u64`](#u64)_ 156 | Alias for `u64`. 157 | 158 | 159 | > A 64-bit value 160 | 161 | 162 | --- 163 | 164 | ### _[`array_output`](#array_output)_ 165 | Alias for `handle`. 166 | 167 | 168 | > Handle for functions returning output whose size may be large or not known in advance. 169 | > 170 | > An `array_output` object contains a host-allocated byte array. 171 | > 172 | > A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. 173 | > In addition, the content of such an object can be consumed by a guest in a streaming fashion. 174 | > 175 | > An `array_output` handle is automatically closed after its full content has been consumed. 176 | 177 | 178 | --- 179 | 180 | ### _[`options`](#options)_ 181 | Alias for `handle`. 182 | 183 | 184 | > A set of options. 185 | > 186 | > This type is used to set non-default parameters. 187 | > 188 | > The exact set of allowed options depends on the algorithm being used. 189 | 190 | 191 | --- 192 | 193 | ### _[`secrets_manager`](#secrets_manager)_ 194 | Alias for `handle`. 195 | 196 | 197 | > A handle to the optional secrets management facilities offered by a host. 198 | > 199 | > This is used to generate, retrieve and invalidate managed keys. 200 | 201 | 202 | --- 203 | 204 | ### _[`keypair`](#keypair)_ 205 | Alias for `handle`. 206 | 207 | 208 | > A key pair. 209 | 210 | 211 | --- 212 | 213 | ### _[`signature_state`](#signature_state)_ 214 | Alias for `handle`. 215 | 216 | 217 | > A state to absorb data to be signed. 218 | > 219 | > After a signature has been computed or verified, the state remains valid for further operations. 220 | > 221 | > A subsequent signature would sign all the data accumulated since the creation of the state object. 222 | 223 | 224 | --- 225 | 226 | ### _[`signature`](#signature)_ 227 | Alias for `handle`. 228 | 229 | 230 | > A signature. 231 | 232 | 233 | --- 234 | 235 | ### _[`publickey`](#publickey)_ 236 | Alias for `handle`. 237 | 238 | 239 | > A public key, for key exchange and signature verification. 240 | 241 | 242 | --- 243 | 244 | ### _[`secretkey`](#secretkey)_ 245 | Alias for `handle`. 246 | 247 | 248 | > A secret key, for key exchange mechanisms. 249 | 250 | 251 | --- 252 | 253 | ### _[`signature_verification_state`](#signature_verification_state)_ 254 | Alias for `handle`. 255 | 256 | 257 | > A state to absorb signed data to be verified. 258 | 259 | 260 | --- 261 | 262 | ### _[`symmetric_state`](#symmetric_state)_ 263 | Alias for `handle`. 264 | 265 | 266 | > A state to perform symmetric operations. 267 | > 268 | > The state is not reset nor invalidated after an option has been performed. 269 | > Incremental updates and sessions are thus supported. 270 | 271 | 272 | --- 273 | 274 | ### _[`symmetric_key`](#symmetric_key)_ 275 | Alias for `handle`. 276 | 277 | 278 | > A symmetric key. 279 | > 280 | > The key can be imported from raw bytes, or can be a reference to a managed key. 281 | > 282 | > If it was imported, the host will wipe it from memory as soon as the handle is closed. 283 | 284 | 285 | --- 286 | 287 | ### _[`symmetric_tag`](#symmetric_tag)_ 288 | Alias for `handle`. 289 | 290 | 291 | > An authentication tag. 292 | > 293 | > This is an object returned by functions computing authentication tags. 294 | > 295 | > A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function. 296 | > 297 | > This object type can't be directly created from raw bytes. They are only returned by functions computing MACs. 298 | > 299 | > The host is reponsible for securely wiping them from memory on close. 300 | 301 | 302 | --- 303 | 304 | ### _[`opt_options_u`](#opt_options_u)_ 305 | 306 | Enumeration with tag type: `u8`, and the following members: 307 | 308 | * **`some`**: _[`opt_options_u`](#opt_options_u)_ 309 | * **`none`**: _[`opt_options_u`](#opt_options_u)_ 310 | 311 | > Options index, only required by the Interface Types translation layer. 312 | 313 | 314 | --- 315 | 316 | ### _[`opt_options`](#opt_options)_ 317 | Tagged union with tag type: `u8` and the following possibilities: 318 | 319 | * **`some`**: _[`options`](#options)_ 320 | * **`none`**: _(empty)_ 321 | 322 | > An optional options set. 323 | > 324 | > This union simulates an `Option\` type to make the `options` parameter of some functions optional. 325 | 326 | 327 | --- 328 | 329 | ### _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 330 | 331 | Enumeration with tag type: `u8`, and the following members: 332 | 333 | * **`some`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 334 | * **`none`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 335 | 336 | > Symmetric key index, only required by the Interface Types translation layer. 337 | 338 | 339 | --- 340 | 341 | ### _[`opt_symmetric_key`](#opt_symmetric_key)_ 342 | Tagged union with tag type: `u8` and the following possibilities: 343 | 344 | * **`some`**: _[`symmetric_key`](#symmetric_key)_ 345 | * **`none`**: _(empty)_ 346 | 347 | > An optional symmetric key. 348 | > 349 | > This union simulates an `Option\` type to make the `symmetric_key` parameter of some functions optional. 350 | 351 | 352 | --- 353 | 354 | ## Functions 355 | 356 | ### [`external_secret_store()`](#external_secret_store) 357 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 358 | 359 | #### Input: 360 | 361 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 362 | * **`secret`**: `u8` pointer 363 | * **`secret_len`**: _[`size`](#size)_ 364 | * **`expiration`**: _[`timestamp`](#timestamp)_ 365 | * **`secret_id`**: `u8` mutable pointer 366 | * **`secret_id_max_len`**: _[`size`](#size)_ 367 | 368 | This function has no output. 369 | 370 | > Store an external secret into the secrets manager. 371 | > 372 | > `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. 373 | > An expiration date is mandatory. 374 | > 375 | > On success, the secret identifier is put into `$secret_id` if it fits into `$secret_id_max_len` bytes. 376 | > If the supplied ouptut buffer is too small, `$overflow` is returned. 377 | > 378 | > If this function is not supported by the host the `$unsupported_feature` error is returned. 379 | 380 | 381 | --- 382 | 383 | ### [`external_secret_replace()`](#external_secret_replace) 384 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 385 | 386 | #### Input: 387 | 388 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 389 | * **`secret`**: `u8` pointer 390 | * **`secret_len`**: _[`size`](#size)_ 391 | * **`expiration`**: _[`timestamp`](#timestamp)_ 392 | * **`secret_id`**: `u8` pointer 393 | * **`secret_id_len`**: _[`size`](#size)_ 394 | 395 | #### Output: 396 | 397 | * _[`version`](#version)_ mutable pointer 398 | 399 | > Replace a managed external with a new version. 400 | > 401 | > `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. 402 | > An expiration date is mandatory. 403 | > 404 | > On success, a new version is created and returned. 405 | > 406 | > If this function is not supported by the host the `$unsupported_feature` error is returned. 407 | 408 | 409 | --- 410 | 411 | ### [`external_secret_from_id()`](#external_secret_from_id) 412 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 413 | 414 | #### Input: 415 | 416 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 417 | * **`secret_id`**: `u8` pointer 418 | * **`secret_id_len`**: _[`size`](#size)_ 419 | * **`secret_version`**: _[`version`](#version)_ 420 | 421 | #### Output: 422 | 423 | * _[`array_output`](#array_output)_ mutable pointer 424 | 425 | > Get a copy of an external secret given an identifier and version. 426 | > 427 | > `secret_version` can be set to a version number, or to `version.latest` to retrieve the most recent version of a secret. 428 | > 429 | > On success, a copy of the secret is returned. 430 | > 431 | > 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. 432 | 433 | 434 | --- 435 | 436 | ### [`external_secret_invalidate()`](#external_secret_invalidate) 437 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 438 | 439 | #### Input: 440 | 441 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 442 | * **`secret_id`**: `u8` pointer 443 | * **`secret_id_len`**: _[`size`](#size)_ 444 | * **`secret_version`**: _[`version`](#version)_ 445 | 446 | This function has no output. 447 | 448 | > Invalidate an external secret given an identifier and a version. 449 | > 450 | > This asks the secrets manager to delete or revoke a stored secret, a specific version of a secret. 451 | > 452 | > `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. 453 | > 454 | > 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. 455 | 456 | 457 | --- 458 | 459 | ### [`external_secret_encapsulate()`](#external_secret_encapsulate) 460 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 461 | 462 | #### Input: 463 | 464 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 465 | * **`secret`**: `u8` pointer 466 | * **`secret_len`**: _[`size`](#size)_ 467 | * **`expiration`**: _[`timestamp`](#timestamp)_ 468 | 469 | #### Output: 470 | 471 | * _[`array_output`](#array_output)_ mutable pointer 472 | 473 | > Encrypt an external secret. 474 | > 475 | > Applications don't have access to the encryption key, and the secrets manager is free to choose any suitable algorithm. 476 | > 477 | > However, the returned ciphertext must include and authenticate both the secret and the expiration date. 478 | > 479 | > On success, the ciphertext is returned. 480 | 481 | 482 | --- 483 | 484 | ### [`external_secret_decapsulate()`](#external_secret_decapsulate) 485 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 486 | 487 | #### Input: 488 | 489 | * **`secrets_manager`**: _[`secrets_manager`](#secrets_manager)_ 490 | * **`encrypted_secret`**: `u8` pointer 491 | * **`encrypted_secret_len`**: _[`size`](#size)_ 492 | 493 | #### Output: 494 | 495 | * _[`array_output`](#array_output)_ mutable pointer 496 | 497 | > Decrypt an external secret previously encrypted by the secrets manager. 498 | > 499 | > Returns the original secret if the ciphertext is valid. 500 | > Returns `$expired` if the current date is past the stored expiration date. 501 | > Returns `$verification_failed` if the ciphertext format is invalid or if its authentication tag couldn't be verified. 502 | 503 | 504 | --- 505 | 506 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_external_secrets.witx: -------------------------------------------------------------------------------- 1 | ;;; External secrets storage. 2 | ;;; 3 | ;;; 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. 4 | ;;; These secrets can be securely stored, and then retrieved using an identifier. 5 | ;;; 6 | ;;; Alternatively, the secrets manager can encrypt them, and applications will supply the ciphertext get the original secret back. 7 | ;;; 8 | ;;; The whole module is optional. 9 | ;;; 10 | ;;; __(optional)__ 11 | (module $wasi_ephemeral_crypto_external_secrets 12 | (use * from $wasi_ephemeral_crypto_common) 13 | 14 | ;;; Store an external secret into the secrets manager. 15 | ;;; 16 | ;;; `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. 17 | ;;; An expiration date is mandatory. 18 | ;;; 19 | ;;; On success, the secret identifier is put into `$secret_id` if it fits into `$secret_id_max_len` bytes. 20 | ;;; If the supplied ouptut buffer is too small, `$overflow` is returned. 21 | ;;; 22 | ;;; If this function is not supported by the host the `$unsupported_feature` error is returned. 23 | (@interface func (export "external_secret_store") 24 | (param $secrets_manager $secrets_manager) 25 | (param $secret (@witx const_pointer u8)) 26 | (param $secret_len $size) 27 | (param $expiration $timestamp) 28 | (param $secret_id (@witx pointer u8)) 29 | (param $secret_id_max_len $size) 30 | (result $error (expected (error $crypto_errno))) 31 | ) 32 | 33 | ;;; Replace a managed external with a new version. 34 | ;;; 35 | ;;; `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. 36 | ;;; An expiration date is mandatory. 37 | ;;; 38 | ;;; On success, a new version is created and returned. 39 | ;;; 40 | ;;; If this function is not supported by the host the `$unsupported_feature` error is returned. 41 | (@interface func (export "external_secret_replace") 42 | (param $secrets_manager $secrets_manager) 43 | (param $secret (@witx const_pointer u8)) 44 | (param $secret_len $size) 45 | (param $expiration $timestamp) 46 | (param $secret_id (@witx const_pointer u8)) 47 | (param $secret_id_len $size) 48 | (result $error (expected $version (error $crypto_errno))) 49 | ) 50 | 51 | ;;; Get a copy of an external secret given an identifier and version. 52 | ;;; 53 | ;;; `secret_version` can be set to a version number, or to `version.latest` to retrieve the most recent version of a secret. 54 | ;;; 55 | ;;; On success, a copy of the secret is returned. 56 | ;;; 57 | ;;; 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. 58 | (@interface func (export "external_secret_from_id") 59 | (param $secrets_manager $secrets_manager) 60 | (param $secret_id (@witx const_pointer u8)) 61 | (param $secret_id_len $size) 62 | (param $secret_version $version) 63 | (result $error (expected $array_output (error $crypto_errno))) 64 | ) 65 | 66 | ;;; Invalidate an external secret given an identifier and a version. 67 | ;;; 68 | ;;; This asks the secrets manager to delete or revoke a stored secret, a specific version of a secret. 69 | ;;; 70 | ;;; `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. 71 | ;;; 72 | ;;; 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. 73 | (@interface func (export "external_secret_invalidate") 74 | (param $secrets_manager $secrets_manager) 75 | (param $secret_id (@witx const_pointer u8)) 76 | (param $secret_id_len $size) 77 | (param $secret_version $version) 78 | (result $error (expected (error $crypto_errno))) 79 | ) 80 | 81 | ;;; Encrypt an external secret. 82 | ;;; 83 | ;;; Applications don't have access to the encryption key, and the secrets manager is free to choose any suitable algorithm. 84 | ;;; 85 | ;;; However, the returned ciphertext must include and authenticate both the secret and the expiration date. 86 | ;;; 87 | ;;; On success, the ciphertext is returned. 88 | (@interface func (export "external_secret_encapsulate") 89 | (param $secrets_manager $secrets_manager) 90 | (param $secret (@witx const_pointer u8)) 91 | (param $secret_len $size) 92 | (param $expiration $timestamp) 93 | (result $error (expected $array_output (error $crypto_errno))) 94 | ) 95 | 96 | ;;; Decrypt an external secret previously encrypted by the secrets manager. 97 | ;;; 98 | ;;; Returns the original secret if the ciphertext is valid. 99 | ;;; Returns `$expired` if the current date is past the stored expiration date. 100 | ;;; Returns `$verification_failed` if the ciphertext format is invalid or if its authentication tag couldn't be verified. 101 | (@interface func (export "external_secret_decapsulate") 102 | (param $secrets_manager $secrets_manager) 103 | (param $encrypted_secret (@witx const_pointer u8)) 104 | (param $encrypted_secret_len $size) 105 | (result $error (expected $array_output (error $crypto_errno))) 106 | ) 107 | ) 108 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_kx.md: -------------------------------------------------------------------------------- 1 | 2 | # Module: wasi_ephemeral_crypto_kx 3 | 4 | ## Table of contents 5 | 6 | ### Types list: 7 | 8 | [**[All](#types)**] - [_[`crypto_errno`](#crypto_errno)_] - [_[`keypair_encoding`](#keypair_encoding)_] - [_[`publickey_encoding`](#publickey_encoding)_] - [_[`secretkey_encoding`](#secretkey_encoding)_] - [_[`signature_encoding`](#signature_encoding)_] - [_[`algorithm_type`](#algorithm_type)_] - [_[`version`](#version)_] - [_[`size`](#size)_] - [_[`timestamp`](#timestamp)_] - [_[`u64`](#u64)_] - [_[`array_output`](#array_output)_] - [_[`options`](#options)_] - [_[`secrets_manager`](#secrets_manager)_] - [_[`keypair`](#keypair)_] - [_[`signature_state`](#signature_state)_] - [_[`signature`](#signature)_] - [_[`publickey`](#publickey)_] - [_[`secretkey`](#secretkey)_] - [_[`signature_verification_state`](#signature_verification_state)_] - [_[`symmetric_state`](#symmetric_state)_] - [_[`symmetric_key`](#symmetric_key)_] - [_[`symmetric_tag`](#symmetric_tag)_] - [_[`opt_options_u`](#opt_options_u)_] - [_[`opt_options`](#opt_options)_] - [_[`opt_symmetric_key_u`](#opt_symmetric_key_u)_] - [_[`opt_symmetric_key`](#opt_symmetric_key)_] - [_[`kx_keypair`](#kx_keypair)_] - [_[`kx_publickey`](#kx_publickey)_] - [_[`kx_secretkey`](#kx_secretkey)_] 9 | 10 | ### Functions list: 11 | 12 | [**[All](#functions)**] - [[`kx_dh()`](#kx_dh)] - [[`kx_encapsulate()`](#kx_encapsulate)] - [[`kx_decapsulate()`](#kx_decapsulate)] 13 | 14 | ## Types 15 | 16 | ### _[`crypto_errno`](#crypto_errno)_ 17 | 18 | Enumeration with tag type: `u16`, and the following members: 19 | 20 | * **`success`**: _[`crypto_errno`](#crypto_errno)_ 21 | * **`guest_error`**: _[`crypto_errno`](#crypto_errno)_ 22 | * **`not_implemented`**: _[`crypto_errno`](#crypto_errno)_ 23 | * **`unsupported_feature`**: _[`crypto_errno`](#crypto_errno)_ 24 | * **`prohibited_operation`**: _[`crypto_errno`](#crypto_errno)_ 25 | * **`unsupported_encoding`**: _[`crypto_errno`](#crypto_errno)_ 26 | * **`unsupported_algorithm`**: _[`crypto_errno`](#crypto_errno)_ 27 | * **`unsupported_option`**: _[`crypto_errno`](#crypto_errno)_ 28 | * **`invalid_key`**: _[`crypto_errno`](#crypto_errno)_ 29 | * **`invalid_length`**: _[`crypto_errno`](#crypto_errno)_ 30 | * **`verification_failed`**: _[`crypto_errno`](#crypto_errno)_ 31 | * **`rng_error`**: _[`crypto_errno`](#crypto_errno)_ 32 | * **`algorithm_failure`**: _[`crypto_errno`](#crypto_errno)_ 33 | * **`invalid_signature`**: _[`crypto_errno`](#crypto_errno)_ 34 | * **`closed`**: _[`crypto_errno`](#crypto_errno)_ 35 | * **`invalid_handle`**: _[`crypto_errno`](#crypto_errno)_ 36 | * **`overflow`**: _[`crypto_errno`](#crypto_errno)_ 37 | * **`internal_error`**: _[`crypto_errno`](#crypto_errno)_ 38 | * **`too_many_handles`**: _[`crypto_errno`](#crypto_errno)_ 39 | * **`key_not_supported`**: _[`crypto_errno`](#crypto_errno)_ 40 | * **`key_required`**: _[`crypto_errno`](#crypto_errno)_ 41 | * **`invalid_tag`**: _[`crypto_errno`](#crypto_errno)_ 42 | * **`invalid_operation`**: _[`crypto_errno`](#crypto_errno)_ 43 | * **`nonce_required`**: _[`crypto_errno`](#crypto_errno)_ 44 | * **`invalid_nonce`**: _[`crypto_errno`](#crypto_errno)_ 45 | * **`option_not_set`**: _[`crypto_errno`](#crypto_errno)_ 46 | * **`not_found`**: _[`crypto_errno`](#crypto_errno)_ 47 | * **`parameters_missing`**: _[`crypto_errno`](#crypto_errno)_ 48 | * **`in_progress`**: _[`crypto_errno`](#crypto_errno)_ 49 | * **`incompatible_keys`**: _[`crypto_errno`](#crypto_errno)_ 50 | * **`expired`**: _[`crypto_errno`](#crypto_errno)_ 51 | 52 | > Error codes. 53 | 54 | 55 | --- 56 | 57 | ### _[`keypair_encoding`](#keypair_encoding)_ 58 | 59 | Enumeration with tag type: `u16`, and the following members: 60 | 61 | * **`raw`**: _[`keypair_encoding`](#keypair_encoding)_ 62 | * **`pkcs8`**: _[`keypair_encoding`](#keypair_encoding)_ 63 | * **`pem`**: _[`keypair_encoding`](#keypair_encoding)_ 64 | * **`local`**: _[`keypair_encoding`](#keypair_encoding)_ 65 | 66 | > Encoding to use for importing or exporting a key pair. 67 | 68 | 69 | --- 70 | 71 | ### _[`publickey_encoding`](#publickey_encoding)_ 72 | 73 | Enumeration with tag type: `u16`, and the following members: 74 | 75 | * **`raw`**: _[`publickey_encoding`](#publickey_encoding)_ 76 | * **`pkcs8`**: _[`publickey_encoding`](#publickey_encoding)_ 77 | * **`pem`**: _[`publickey_encoding`](#publickey_encoding)_ 78 | * **`sec`**: _[`publickey_encoding`](#publickey_encoding)_ 79 | * **`local`**: _[`publickey_encoding`](#publickey_encoding)_ 80 | 81 | > Encoding to use for importing or exporting a public key. 82 | 83 | 84 | --- 85 | 86 | ### _[`secretkey_encoding`](#secretkey_encoding)_ 87 | 88 | Enumeration with tag type: `u16`, and the following members: 89 | 90 | * **`raw`**: _[`secretkey_encoding`](#secretkey_encoding)_ 91 | * **`pkcs8`**: _[`secretkey_encoding`](#secretkey_encoding)_ 92 | * **`pem`**: _[`secretkey_encoding`](#secretkey_encoding)_ 93 | * **`sec`**: _[`secretkey_encoding`](#secretkey_encoding)_ 94 | * **`local`**: _[`secretkey_encoding`](#secretkey_encoding)_ 95 | 96 | > Encoding to use for importing or exporting a secret key. 97 | 98 | 99 | --- 100 | 101 | ### _[`signature_encoding`](#signature_encoding)_ 102 | 103 | Enumeration with tag type: `u16`, and the following members: 104 | 105 | * **`raw`**: _[`signature_encoding`](#signature_encoding)_ 106 | * **`der`**: _[`signature_encoding`](#signature_encoding)_ 107 | 108 | > Encoding to use for importing or exporting a signature. 109 | 110 | 111 | --- 112 | 113 | ### _[`algorithm_type`](#algorithm_type)_ 114 | 115 | Enumeration with tag type: `u16`, and the following members: 116 | 117 | * **`signatures`**: _[`algorithm_type`](#algorithm_type)_ 118 | * **`symmetric`**: _[`algorithm_type`](#algorithm_type)_ 119 | * **`key_exchange`**: _[`algorithm_type`](#algorithm_type)_ 120 | 121 | > An algorithm category. 122 | 123 | 124 | --- 125 | 126 | ### _[`version`](#version)_ 127 | Alias for `u64`. 128 | 129 | 130 | > Version of a managed key. 131 | > 132 | > A version can be an arbitrary `u64` integer, with the expection of some reserved values. 133 | 134 | 135 | --- 136 | 137 | ### _[`size`](#size)_ 138 | Alias for `usize`. 139 | 140 | 141 | > Size of a value. 142 | 143 | 144 | --- 145 | 146 | ### _[`timestamp`](#timestamp)_ 147 | Alias for `u64`. 148 | 149 | 150 | > A UNIX timestamp, in seconds since 01/01/1970. 151 | 152 | 153 | --- 154 | 155 | ### _[`u64`](#u64)_ 156 | Alias for `u64`. 157 | 158 | 159 | > A 64-bit value 160 | 161 | 162 | --- 163 | 164 | ### _[`array_output`](#array_output)_ 165 | Alias for `handle`. 166 | 167 | 168 | > Handle for functions returning output whose size may be large or not known in advance. 169 | > 170 | > An `array_output` object contains a host-allocated byte array. 171 | > 172 | > A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. 173 | > In addition, the content of such an object can be consumed by a guest in a streaming fashion. 174 | > 175 | > An `array_output` handle is automatically closed after its full content has been consumed. 176 | 177 | 178 | --- 179 | 180 | ### _[`options`](#options)_ 181 | Alias for `handle`. 182 | 183 | 184 | > A set of options. 185 | > 186 | > This type is used to set non-default parameters. 187 | > 188 | > The exact set of allowed options depends on the algorithm being used. 189 | 190 | 191 | --- 192 | 193 | ### _[`secrets_manager`](#secrets_manager)_ 194 | Alias for `handle`. 195 | 196 | 197 | > A handle to the optional secrets management facilities offered by a host. 198 | > 199 | > This is used to generate, retrieve and invalidate managed keys. 200 | 201 | 202 | --- 203 | 204 | ### _[`keypair`](#keypair)_ 205 | Alias for `handle`. 206 | 207 | 208 | > A key pair. 209 | 210 | 211 | --- 212 | 213 | ### _[`signature_state`](#signature_state)_ 214 | Alias for `handle`. 215 | 216 | 217 | > A state to absorb data to be signed. 218 | > 219 | > After a signature has been computed or verified, the state remains valid for further operations. 220 | > 221 | > A subsequent signature would sign all the data accumulated since the creation of the state object. 222 | 223 | 224 | --- 225 | 226 | ### _[`signature`](#signature)_ 227 | Alias for `handle`. 228 | 229 | 230 | > A signature. 231 | 232 | 233 | --- 234 | 235 | ### _[`publickey`](#publickey)_ 236 | Alias for `handle`. 237 | 238 | 239 | > A public key, for key exchange and signature verification. 240 | 241 | 242 | --- 243 | 244 | ### _[`secretkey`](#secretkey)_ 245 | Alias for `handle`. 246 | 247 | 248 | > A secret key, for key exchange mechanisms. 249 | 250 | 251 | --- 252 | 253 | ### _[`signature_verification_state`](#signature_verification_state)_ 254 | Alias for `handle`. 255 | 256 | 257 | > A state to absorb signed data to be verified. 258 | 259 | 260 | --- 261 | 262 | ### _[`symmetric_state`](#symmetric_state)_ 263 | Alias for `handle`. 264 | 265 | 266 | > A state to perform symmetric operations. 267 | > 268 | > The state is not reset nor invalidated after an option has been performed. 269 | > Incremental updates and sessions are thus supported. 270 | 271 | 272 | --- 273 | 274 | ### _[`symmetric_key`](#symmetric_key)_ 275 | Alias for `handle`. 276 | 277 | 278 | > A symmetric key. 279 | > 280 | > The key can be imported from raw bytes, or can be a reference to a managed key. 281 | > 282 | > If it was imported, the host will wipe it from memory as soon as the handle is closed. 283 | 284 | 285 | --- 286 | 287 | ### _[`symmetric_tag`](#symmetric_tag)_ 288 | Alias for `handle`. 289 | 290 | 291 | > An authentication tag. 292 | > 293 | > This is an object returned by functions computing authentication tags. 294 | > 295 | > A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function. 296 | > 297 | > This object type can't be directly created from raw bytes. They are only returned by functions computing MACs. 298 | > 299 | > The host is reponsible for securely wiping them from memory on close. 300 | 301 | 302 | --- 303 | 304 | ### _[`opt_options_u`](#opt_options_u)_ 305 | 306 | Enumeration with tag type: `u8`, and the following members: 307 | 308 | * **`some`**: _[`opt_options_u`](#opt_options_u)_ 309 | * **`none`**: _[`opt_options_u`](#opt_options_u)_ 310 | 311 | > Options index, only required by the Interface Types translation layer. 312 | 313 | 314 | --- 315 | 316 | ### _[`opt_options`](#opt_options)_ 317 | Tagged union with tag type: `u8` and the following possibilities: 318 | 319 | * **`some`**: _[`options`](#options)_ 320 | * **`none`**: _(empty)_ 321 | 322 | > An optional options set. 323 | > 324 | > This union simulates an `Option\` type to make the `options` parameter of some functions optional. 325 | 326 | 327 | --- 328 | 329 | ### _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 330 | 331 | Enumeration with tag type: `u8`, and the following members: 332 | 333 | * **`some`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 334 | * **`none`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 335 | 336 | > Symmetric key index, only required by the Interface Types translation layer. 337 | 338 | 339 | --- 340 | 341 | ### _[`opt_symmetric_key`](#opt_symmetric_key)_ 342 | Tagged union with tag type: `u8` and the following possibilities: 343 | 344 | * **`some`**: _[`symmetric_key`](#symmetric_key)_ 345 | * **`none`**: _(empty)_ 346 | 347 | > An optional symmetric key. 348 | > 349 | > This union simulates an `Option\` type to make the `symmetric_key` parameter of some functions optional. 350 | 351 | 352 | --- 353 | 354 | ### _[`kx_keypair`](#kx_keypair)_ 355 | 356 | Alias for `handle`. 357 | 358 | 359 | > `$kx_keypair` is just an alias for `$keypair` 360 | > 361 | > However, bindings may want to define a specialized type `kx_keypair` as a super class of `keypair`. 362 | 363 | 364 | --- 365 | 366 | ### _[`kx_publickey`](#kx_publickey)_ 367 | 368 | Alias for `handle`. 369 | 370 | 371 | > `$kx_publickey` is just an alias for `$publickey` 372 | > 373 | > However, bindings may want to define a specialized type `kx_publickey` as a super class of `publickey`, with additional methods such as `dh`. 374 | 375 | 376 | --- 377 | 378 | ### _[`kx_secretkey`](#kx_secretkey)_ 379 | 380 | Alias for `handle`. 381 | 382 | 383 | > `$kx_secretkey` is just an alias for `$secretkey` 384 | > 385 | > However, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkeykey`, with additional methods such as `dh`. 386 | 387 | 388 | --- 389 | 390 | ## Functions 391 | 392 | ### [`kx_dh()`](#kx_dh) 393 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 394 | 395 | #### Input: 396 | 397 | * **`pk`**: _[`publickey`](#publickey)_ 398 | * **`sk`**: _[`secretkey`](#secretkey)_ 399 | 400 | #### Output: 401 | 402 | * _[`array_output`](#array_output)_ mutable pointer 403 | 404 | > Perform a simple Diffie-Hellman key exchange. 405 | > 406 | > Both keys must be of the same type, or else the `$crypto_errno.incompatible_keys` error is returned. 407 | > 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. 408 | > 409 | > Otherwide, a raw shared key is returned, and can be imported as a symmetric key. 410 | > ``` 411 | 412 | 413 | --- 414 | 415 | ### [`kx_encapsulate()`](#kx_encapsulate) 416 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 417 | 418 | #### Input: 419 | 420 | * **`pk`**: _[`publickey`](#publickey)_ 421 | 422 | #### Output: 423 | 424 | * _[`array_output`](#array_output)_ mutable pointer 425 | * _[`array_output`](#array_output)_ mutable pointer 426 | 427 | > Create a shared secret and encrypt it for the given public key. 428 | > 429 | > This operation is only compatible with specific algorithms. 430 | > If a selected algorithm doesn't support it, `$crypto_errno.invalid_operation` is returned. 431 | > 432 | > On success, both the shared secret and its encrypted version are returned. 433 | 434 | 435 | --- 436 | 437 | ### [`kx_decapsulate()`](#kx_decapsulate) 438 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 439 | 440 | #### Input: 441 | 442 | * **`sk`**: _[`secretkey`](#secretkey)_ 443 | * **`encapsulated_secret`**: `u8` pointer 444 | * **`encapsulated_secret_len`**: _[`size`](#size)_ 445 | 446 | #### Output: 447 | 448 | * _[`array_output`](#array_output)_ mutable pointer 449 | 450 | > Decapsulate an encapsulated secret crated with `kx_encapsulate` 451 | > 452 | > Return the secret, or `$crypto_errno.verification_failed` on error. 453 | 454 | 455 | --- 456 | 457 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_kx.witx: -------------------------------------------------------------------------------- 1 | ;;; Key exchange operations. 2 | (module $wasi_ephemeral_crypto_kx 3 | (use * from $wasi_ephemeral_crypto_common) 4 | 5 | ;;; `$kx_keypair` is just an alias for `$keypair` 6 | ;;; 7 | ;;; However, bindings may want to define a specialized type `kx_keypair` as a super class of `keypair`. 8 | (typename $kx_keypair $keypair) 9 | 10 | ;;; `$kx_publickey` is just an alias for `$publickey` 11 | ;;; 12 | ;;; However, bindings may want to define a specialized type `kx_publickey` as a super class of `publickey`, with additional methods such as `dh`. 13 | (typename $kx_publickey $publickey) 14 | 15 | ;;; `$kx_secretkey` is just an alias for `$secretkey` 16 | ;;; 17 | ;;; However, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkeykey`, with additional methods such as `dh`. 18 | (typename $kx_secretkey $secretkey) 19 | 20 | ;;; Perform a simple Diffie-Hellman key exchange. 21 | ;;; 22 | ;;; Both keys must be of the same type, or else the `$crypto_errno.incompatible_keys` error is returned. 23 | ;;; 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. 24 | ;;; 25 | ;;; Otherwide, a raw shared key is returned, and can be imported as a symmetric key. 26 | ;;; ``` 27 | (@interface func (export "kx_dh") 28 | (param $pk $publickey) 29 | (param $sk $secretkey) 30 | (result $error (expected $array_output (error $crypto_errno))) 31 | ) 32 | 33 | ;;; Create a shared secret and encrypt it for the given public key. 34 | ;;; 35 | ;;; This operation is only compatible with specific algorithms. 36 | ;;; If a selected algorithm doesn't support it, `$crypto_errno.invalid_operation` is returned. 37 | ;;; 38 | ;;; On success, both the shared secret and its encrypted version are returned. 39 | (@interface func (export "kx_encapsulate") 40 | (param $pk $publickey) 41 | (result $error (expected (tuple $array_output $array_output) (error $crypto_errno))) 42 | ) 43 | 44 | ;;; Decapsulate an encapsulated secret crated with `kx_encapsulate` 45 | ;;; 46 | ;;; Return the secret, or `$crypto_errno.verification_failed` on error. 47 | (@interface func (export "kx_decapsulate") 48 | (param $sk $secretkey) 49 | (param $encapsulated_secret (@witx const_pointer u8)) 50 | (param $encapsulated_secret_len $size) 51 | (result $error (expected $array_output (error $crypto_errno))) 52 | ) 53 | ) 54 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_signatures.witx: -------------------------------------------------------------------------------- 1 | ;;; Digital signatures. 2 | (module $wasi_ephemeral_crypto_signatures 3 | (use * from $wasi_ephemeral_crypto_common) 4 | 5 | ;;; `$signature_keypair` is just an alias for `$keypair` 6 | ;;; 7 | ;;; However, bindings may want to define a specialized type `signature_keypair` as a super class of `keypair`, with additional methods such as `sign`. 8 | (typename $signature_keypair $keypair) 9 | 10 | ;;; `$signature_publickey` is just an alias for `$publickey` 11 | ;;; 12 | ;;; However, bindings may want to define a specialized type `signature_publickey` as a super class of `publickey`, with additional methods such as `verify`. 13 | (typename $signature_publickey $publickey) 14 | 15 | ;;; `$signature_secretkey` is just an alias for `$secretkey` 16 | ;;; 17 | ;;; However, bindings may want to define a specialized type `signature_secretkey` as a super class of `secretkey`. 18 | (typename $signature_secretkey $secretkey) 19 | 20 | ;;; Export a signature. 21 | ;;; 22 | ;;; This function exports a signature object using the specified encoding. 23 | ;;; 24 | ;;; May return `unsupported_encoding` if the signature cannot be encoded into the given format. 25 | (@interface func (export "signature_export") 26 | (param $signature $signature) 27 | (param $encoding $signature_encoding) 28 | (result $error (expected $array_output (error $crypto_errno))) 29 | ) 30 | 31 | ;;; Create a signature object. 32 | ;;; 33 | ;;; This object can be used along with a public key to verify an existing signature. 34 | ;;; 35 | ;;; 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. 36 | ;;; 37 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 38 | ;;; 39 | ;;; Example usage: 40 | ;;; 41 | ;;; ```rust 42 | ;;; let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", SignatureEncoding::DER, encoded)?; 43 | ;;; ``` 44 | (@interface func (export "signature_import") 45 | (param $algorithm string) 46 | (param $encoded (@witx const_pointer u8)) 47 | (param $encoded_len $size) 48 | (param $encoding $signature_encoding) 49 | (result $error (expected $signature (error $crypto_errno))) 50 | ) 51 | 52 | ;;; Create a new state to collect data to compute a signature on. 53 | ;;; 54 | ;;; This function allows data to be signed to be supplied in a streaming fashion. 55 | ;;; 56 | ;;; 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. 57 | ;;; 58 | ;;; Example usage - signature creation 59 | ;;; 60 | ;;; ```rust 61 | ;;; let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "Ed25519ph", keypair, KeypairEncoding::Raw)?; 62 | ;;; let state_handle = ctx.signature_state_open(kp_handle)?; 63 | ;;; ctx.signature_state_update(state_handle, b"message part 1")?; 64 | ;;; ctx.signature_state_update(state_handle, b"message part 2")?; 65 | ;;; let sig_handle = ctx.signature_state_sign(state_handle)?; 66 | ;;; let raw_sig = ctx.signature_export(sig_handle, SignatureEncoding::Raw)?; 67 | ;;; ``` 68 | (@interface func (export "signature_state_open") 69 | (param $kp $signature_keypair) 70 | (result $error (expected $signature_state (error $crypto_errno))) 71 | ) 72 | 73 | ;;; Absorb data into the signature state. 74 | ;;; 75 | ;;; This function may return `unsupported_feature` is the selected algorithm doesn't support incremental updates. 76 | (@interface func (export "signature_state_update") 77 | (param $state $signature_state) 78 | (param $input (@witx const_pointer u8)) 79 | (param $input_len $size) 80 | (result $error (expected (error $crypto_errno))) 81 | ) 82 | 83 | ;;; Compute a signature for all the data collected up to that point. 84 | ;;; 85 | ;;; The function can be called multiple times for incremental signing. 86 | (@interface func (export "signature_state_sign") 87 | (param $state $signature_state) 88 | (result $error (expected $array_output (error $crypto_errno))) 89 | ) 90 | 91 | ;;; Destroy a signature state. 92 | ;;; 93 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 94 | ;;; 95 | ;;; Note that closing a signature state doesn't close or invalidate the key pair object, that be reused for further signatures. 96 | (@interface func (export "signature_state_close") 97 | (param $state $signature_state) 98 | (result $error (expected (error $crypto_errno))) 99 | ) 100 | 101 | ;;; Create a new state to collect data to verify a signature on. 102 | ;;; 103 | ;;; This is the verification counterpart of `signature_state`. 104 | ;;; 105 | ;;; Data can be injected using `signature_verification_state_update()`, and the state is not closed after a verification, allowing incremental verification. 106 | ;;; 107 | ;;; Example usage - signature verification: 108 | ;;; 109 | ;;; ```rust 110 | ;;; let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_pk, PublicKeyEncoding::Sec)?; 111 | ;;; let signature_handle = ctx.signature_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_sig, SignatureEncoding::Der)?; 112 | ;;; let state_handle = ctx.signature_verification_state_open(pk_handle)?; 113 | ;;; ctx.signature_verification_state_update(state_handle, "message")?; 114 | ;;; ctx.signature_verification_state_verify(signature_handle)?; 115 | ;;; ``` 116 | (@interface func (export "signature_verification_state_open") 117 | (param $kp $signature_publickey) 118 | (result $error (expected $signature_verification_state (error $crypto_errno))) 119 | ) 120 | 121 | ;;; Absorb data into the signature verification state. 122 | ;;; 123 | ;;; This function may return `unsupported_feature` is the selected algorithm doesn't support incremental updates. 124 | (@interface func (export "signature_verification_state_update") 125 | (param $state $signature_verification_state) 126 | (param $input (@witx const_pointer u8)) 127 | (param $input_len $size) 128 | (result $error (expected (error $crypto_errno))) 129 | ) 130 | 131 | ;;; Check that the given signature is verifies for the data collected up to that point point. 132 | ;;; 133 | ;;; The state is not closed and can absorb more data to allow for incremental verification. 134 | ;;; 135 | ;;; The function returns `invalid_signature` if the signature doesn't appear to be valid. 136 | (@interface func (export "signature_verification_state_verify") 137 | (param $state $signature_verification_state) 138 | (param $signature $signature) 139 | (result $error (expected (error $crypto_errno))) 140 | ) 141 | 142 | ;;; Destroy a signature verification state. 143 | ;;; 144 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 145 | ;;; 146 | ;;; Note that closing a signature state doesn't close or invalidate the public key object, that be reused for further verifications. 147 | (@interface func (export "signature_verification_state_close") 148 | (param $state $signature_verification_state) 149 | (result $error (expected (error $crypto_errno))) 150 | ) 151 | 152 | ;;; Destroy a signature. 153 | ;;; 154 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 155 | (@interface func (export "signature_close") 156 | (param $signature $signature) 157 | (result $error (expected (error $crypto_errno))) 158 | ) 159 | ) 160 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_signatures_batch.md: -------------------------------------------------------------------------------- 1 | 2 | # Module: wasi_ephemeral_crypto_signatures_batch 3 | 4 | ## Table of contents 5 | 6 | ### Types list: 7 | 8 | [**[All](#types)**] - [_[`crypto_errno`](#crypto_errno)_] - [_[`array_output`](#array_output)_] - [_[`signature`](#signature)_] - [_[`signature_state`](#signature_state)_] - [_[`signature_verification_state`](#signature_verification_state)_] - [_[`signature_sign_result`](#signature_sign_result)_] - [_[`signature_results`](#signature_results)_] - [_[`signature_verification_input`](#signature_verification_input)_] - [_[`signature_verification_results`](#signature_verification_results)_] 9 | 10 | ### Functions list: 11 | 12 | [**[All](#functions)**] - [[`batch_signature_state_sign()`](#batch_signature_state_sign)] - [[`batch_signature_state_verify()`](#batch_signature_state_verify)] 13 | 14 | ## Types 15 | 16 | ### _[`crypto_errno`](#crypto_errno)_ 17 | 18 | Enumeration with tag type: `u16`, and the following members: 19 | 20 | * **`success`**: _[`crypto_errno`](#crypto_errno)_ 21 | * **`guest_error`**: _[`crypto_errno`](#crypto_errno)_ 22 | * **`not_implemented`**: _[`crypto_errno`](#crypto_errno)_ 23 | * **`unsupported_feature`**: _[`crypto_errno`](#crypto_errno)_ 24 | * **`prohibited_operation`**: _[`crypto_errno`](#crypto_errno)_ 25 | * **`unsupported_encoding`**: _[`crypto_errno`](#crypto_errno)_ 26 | * **`unsupported_algorithm`**: _[`crypto_errno`](#crypto_errno)_ 27 | * **`unsupported_option`**: _[`crypto_errno`](#crypto_errno)_ 28 | * **`invalid_key`**: _[`crypto_errno`](#crypto_errno)_ 29 | * **`invalid_length`**: _[`crypto_errno`](#crypto_errno)_ 30 | * **`verification_failed`**: _[`crypto_errno`](#crypto_errno)_ 31 | * **`rng_error`**: _[`crypto_errno`](#crypto_errno)_ 32 | * **`algorithm_failure`**: _[`crypto_errno`](#crypto_errno)_ 33 | * **`invalid_signature`**: _[`crypto_errno`](#crypto_errno)_ 34 | * **`closed`**: _[`crypto_errno`](#crypto_errno)_ 35 | * **`invalid_handle`**: _[`crypto_errno`](#crypto_errno)_ 36 | * **`overflow`**: _[`crypto_errno`](#crypto_errno)_ 37 | * **`internal_error`**: _[`crypto_errno`](#crypto_errno)_ 38 | * **`too_many_handles`**: _[`crypto_errno`](#crypto_errno)_ 39 | * **`key_not_supported`**: _[`crypto_errno`](#crypto_errno)_ 40 | * **`key_required`**: _[`crypto_errno`](#crypto_errno)_ 41 | * **`invalid_tag`**: _[`crypto_errno`](#crypto_errno)_ 42 | * **`invalid_operation`**: _[`crypto_errno`](#crypto_errno)_ 43 | * **`nonce_required`**: _[`crypto_errno`](#crypto_errno)_ 44 | * **`invalid_nonce`**: _[`crypto_errno`](#crypto_errno)_ 45 | * **`option_not_set`**: _[`crypto_errno`](#crypto_errno)_ 46 | * **`not_found`**: _[`crypto_errno`](#crypto_errno)_ 47 | * **`parameters_missing`**: _[`crypto_errno`](#crypto_errno)_ 48 | * **`in_progress`**: _[`crypto_errno`](#crypto_errno)_ 49 | * **`incompatible_keys`**: _[`crypto_errno`](#crypto_errno)_ 50 | * **`expired`**: _[`crypto_errno`](#crypto_errno)_ 51 | 52 | > Error codes. 53 | 54 | 55 | --- 56 | 57 | ### _[`array_output`](#array_output)_ 58 | Alias for `handle`. 59 | 60 | 61 | > Handle for functions returning output whose size may be large or not known in advance. 62 | > 63 | > An `array_output` object contains a host-allocated byte array. 64 | > 65 | > A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. 66 | > In addition, the content of such an object can be consumed by a guest in a streaming fashion. 67 | > 68 | > An `array_output` handle is automatically closed after its full content has been consumed. 69 | 70 | 71 | --- 72 | 73 | ### _[`signature`](#signature)_ 74 | Alias for `handle`. 75 | 76 | 77 | > A signature. 78 | 79 | 80 | --- 81 | 82 | ### _[`signature_state`](#signature_state)_ 83 | Alias for `handle`. 84 | 85 | 86 | > A state to absorb data to be signed. 87 | > 88 | > After a signature has been computed or verified, the state remains valid for further operations. 89 | > 90 | > A subsequent signature would sign all the data accumulated since the creation of the state object. 91 | 92 | 93 | --- 94 | 95 | ### _[`signature_verification_state`](#signature_verification_state)_ 96 | Alias for `handle`. 97 | 98 | 99 | > A state to absorb signed data to be verified. 100 | 101 | 102 | --- 103 | 104 | ### _[`signature_sign_result`](#signature_sign_result)_ 105 | Tuple, representing (_[`array_output`](#array_output)_, _[`crypto_errno`](#crypto_errno)_). 106 | 107 | 108 | > The result of a signature sign operation. A pair of the signature and an error code. 109 | 110 | 111 | --- 112 | 113 | ### _[`signature_results`](#signature_results)_ 114 | Alias for _[`signature_sign_result`](#signature_sign_result)_ mutable slice. 115 | 116 | 117 | > A list of signature_sign results. 118 | 119 | 120 | --- 121 | 122 | ### _[`signature_verification_input`](#signature_verification_input)_ 123 | Tuple, representing (_[`signature_verification_state`](#signature_verification_state)_, _[`signature`](#signature)_). 124 | 125 | 126 | > A tuple of a signature verification state and the signature to verify. 127 | > 128 | > Used for grouping signature verification state to be verified with the signature to verify. 129 | > Used with batch_signature_state_verify(). 130 | 131 | 132 | --- 133 | 134 | ### _[`signature_verification_results`](#signature_verification_results)_ 135 | Alias for _[`crypto_errno`](#crypto_errno)_ mutable slice. 136 | 137 | 138 | --- 139 | 140 | ## Functions 141 | 142 | ### [`batch_signature_state_sign()`](#batch_signature_state_sign) 143 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 144 | 145 | #### Input: 146 | 147 | * **`states`**: _[`signature_state`](#signature_state)_ mutable slice 148 | 149 | #### Output: 150 | 151 | * _[`signature_results`](#signature_results)_ mutable pointer 152 | 153 | > Compute a batch of signatures. 154 | > 155 | > This is a batch version of the signature_state_sign operation and is an extension of the wasi_empemeral_crypto_signatures module. 156 | > 157 | > If the entire batch could not be processed an error code of type 158 | > $crypto_errno is returned. If part of the batch was successfully 159 | > processed and part (one or more) resulted in a failure, each result 160 | > is a pair of an error code and a signature. The signature is only valid 161 | > if the error code indicates success. 162 | > 163 | > Example usage: 164 | > 165 | > ```rust 166 | > let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; 167 | > 168 | > let mut state_handles = Vec::new(); 169 | > 170 | > let state_handle = signature_state_open(kp_handle)?; 171 | > signature_state_update(state_handle, b"message part 1")?; 172 | > signature_state_update(state_handle, b"message part 2")?; 173 | > state_handles.push(state_handle); 174 | > 175 | > let state_handle = signature_state_open(kp_handle)?; 176 | > signature_state_update(state_handle, b"message part 1")?; 177 | > signature_state_update(state_handle, b"message part 2")?; 178 | > state_handles.push(state_handle); 179 | > 180 | > let sig_handles = batch_signature_state_sign(state_handles)?; 181 | > 182 | > let raw_sig1 = signature_export(sig_handle[0], SignatureEncoding::Raw)?; 183 | > let raw_sig2 = signature_export(sig_handle[1], SignatureEncoding::Raw)?; 184 | > ``` 185 | 186 | 187 | --- 188 | 189 | ### [`batch_signature_state_verify()`](#batch_signature_state_verify) 190 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 191 | 192 | #### Input: 193 | 194 | * **`states`**: _[`signature_verification_input`](#signature_verification_input)_ mutable slice 195 | 196 | #### Output: 197 | 198 | * _[`signature_verification_results`](#signature_verification_results)_ mutable pointer 199 | 200 | > Verify a batch of signatures. 201 | > 202 | > This is a batch version of the signature_state_verify operation and is 203 | > an extension of the wasi_empemeral_crypto_signatures module. 204 | > 205 | > Each entry in the input list has a corresponding error state returned 206 | > to indicate if the verification succeeded or encountered and error. 207 | > If the batch could not be processed an error code is returned, 208 | > otherwise a list of verification results is produced. 209 | > Each entry in the list is an error code that indicates the verification 210 | > result for the corresponding entry in the verification input list. 211 | > 212 | > Example usage: 213 | > 214 | > ```rust 215 | > let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; 216 | > 217 | > let mut batch = Vec::new(); 218 | > 219 | > let state_handle = signature_verification_state_open(kp_handle)?; 220 | > signature_verification_state_update(state_handle, b"message part 1")?; 221 | > signature_verification_state_update(state_handle, b"message part 2")?; 222 | > state_handles.push((state_handle, signature1)); 223 | > 224 | > let state_handle = signature_state_open(kp_handle)?; 225 | > signature_state_update(state_handle, b"message part 1")?; 226 | > signature_state_update(state_handle, b"message part 2")?; 227 | > state_handles.push((state_handle, signature2)); 228 | > 229 | > let results = batch_signature_state_verify(state_handles)?; 230 | > ``` 231 | 232 | 233 | --- 234 | 235 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_signatures_batch.witx: -------------------------------------------------------------------------------- 1 | ;;; Digital Signature Batch Operations 2 | (module $wasi_ephemeral_crypto_signatures_batch 3 | (use $crypto_errno from $wasi_ephemeral_crypto_common) 4 | (use $array_output from $wasi_ephemeral_crypto_common) 5 | (use $signature from $wasi_ephemeral_crypto_signatures) 6 | (use $signature_state from $wasi_ephemeral_crypto_signatures) 7 | (use $signature_verification_state from $wasi_ephemeral_crypto_signatures) 8 | 9 | ;;; The result of a signature sign operation. A pair of the signature and an error code. 10 | (typename $signature_sign_result (tuple $array_output $crypto_errno)) 11 | 12 | ;;; A list of signature_sign results. 13 | (typename $signature_results (list $signature_sign_result)) 14 | 15 | ;;; A tuple of a signature verification state and the signature to verify. 16 | ;;; 17 | ;;; Used for grouping signature verification state to be verified with the signature to verify. 18 | ;;; Used with batch_signature_state_verify(). 19 | (typename $signature_verification_input (tuple $signature_verification_state $signature)) 20 | 21 | (typename $signature_verification_results (list $crypto_errno)) 22 | 23 | 24 | ;;; Compute a batch of signatures. 25 | ;;; 26 | ;;; This is a batch version of the signature_state_sign operation and is an extension of the wasi_emphemeral_crypto_signatures module. 27 | ;;; 28 | ;;; The batch operation returns an error code of type $crypto_errno that 29 | ;;; indicates if the batch was processed or if the batch could not be 30 | ;;; processed. 31 | ;;; 32 | ;;; Batch processing error codes: 33 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 34 | ;;; - `not_implemented`: Batch functionality is not supported. 35 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 36 | ;;; 37 | ;;; If the batch was processed, the result of each operation in the batch 38 | ;;; is a pair of a $crypto_errno error code and a signature. The error code 39 | ;;; indicates if that operation succeeded or failed. The signature is only 40 | ;;; valid if the error code indicates success. 41 | ;;; 42 | ;;; Example usage: 43 | ;;; 44 | ;;; ```rust 45 | ;;; let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; 46 | ;;; 47 | ;;; let mut state_handles = Vec::new(); 48 | ;;; 49 | ;;; let state_handle = signature_state_open(kp_handle)?; 50 | ;;; signature_state_update(state_handle, b"message part 1")?; 51 | ;;; signature_state_update(state_handle, b"message part 2")?; 52 | ;;; state_handles.push(state_handle); 53 | ;;; 54 | ;;; let state_handle = signature_state_open(kp_handle)?; 55 | ;;; signature_state_update(state_handle, b"message part 1")?; 56 | ;;; signature_state_update(state_handle, b"message part 2")?; 57 | ;;; state_handles.push(state_handle); 58 | ;;; 59 | ;;; let sig_handles = batch_signature_state_sign(state_handles)?; 60 | ;;; 61 | ;;; let raw_sig1 = signature_export(sig_handle[0], SignatureEncoding::Raw)?; 62 | ;;; let raw_sig2 = signature_export(sig_handle[1], SignatureEncoding::Raw)?; 63 | ;;; ``` 64 | (@interface func (export "batch_signature_state_sign") 65 | (param $states (list $signature_state)) 66 | (result $error (expected $signature_results (error $crypto_errno))) 67 | ) 68 | 69 | ;;; Verify a batch of signatures. 70 | ;;; 71 | ;;; This is a batch version of the signature_state_verify operation and is 72 | ;;; an extension of the wasi_empemeral_crypto_signatures module. 73 | ;;; 74 | ;;; The batch operation returns an error code of type $crypto_errno that 75 | ;;; indicates if the batch was processed (`success`) or if the batch could 76 | ;;; not be processed. 77 | ;;; 78 | ;;; Batch processing failure cases are: 79 | ;;; - `not_implemented`: Batch functionality is not supported. 80 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 81 | ;;; 82 | ;;; If the batch was processed, a list of verification results is produced. 83 | ;;; Each entry in the input list has a corresponding error state returned 84 | ;;; in the verification results list to indicate if the verification 85 | ;;; succeeded or encountered and error. 86 | ;;; 87 | ;;; Example usage: 88 | ;;; 89 | ;;; ```rust 90 | ;;; let kp_handle = keypair_import(AlgorithmType::Signatures, "Ed25519", encoded, KeypairEncoding::Raw)?; 91 | ;;; 92 | ;;; let mut batch = Vec::new(); 93 | ;;; 94 | ;;; let state_handle = signature_verification_state_open(kp_handle)?; 95 | ;;; signature_verification_state_update(state_handle, b"message part 1")?; 96 | ;;; signature_verification_state_update(state_handle, b"message part 2")?; 97 | ;;; state_handles.push((state_handle, signature1)); 98 | ;;; 99 | ;;; let state_handle = signature_state_open(kp_handle)?; 100 | ;;; signature_state_update(state_handle, b"message part 1")?; 101 | ;;; signature_state_update(state_handle, b"message part 2")?; 102 | ;;; state_handles.push((state_handle, signature2)); 103 | ;;; 104 | ;;; let results = batch_signature_state_verify(state_handles)?; 105 | ;;; ``` 106 | (@interface func (export "batch_signature_state_verify") 107 | (param $states (list $signature_verification_input)) 108 | (result $error (expected $signature_verification_results (error $crypto_errno))) 109 | ) 110 | ) 111 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_symmetric_batch.md: -------------------------------------------------------------------------------- 1 | 2 | # Module: wasi_ephemeral_crypto_symmetric_batch 3 | 4 | ## Table of contents 5 | 6 | ### Types list: 7 | 8 | [**[All](#types)**] - [_[`crypto_errno`](#crypto_errno)_] - [_[`keypair_encoding`](#keypair_encoding)_] - [_[`publickey_encoding`](#publickey_encoding)_] - [_[`secretkey_encoding`](#secretkey_encoding)_] - [_[`signature_encoding`](#signature_encoding)_] - [_[`algorithm_type`](#algorithm_type)_] - [_[`version`](#version)_] - [_[`size`](#size)_] - [_[`timestamp`](#timestamp)_] - [_[`u64`](#u64)_] - [_[`array_output`](#array_output)_] - [_[`options`](#options)_] - [_[`secrets_manager`](#secrets_manager)_] - [_[`keypair`](#keypair)_] - [_[`signature_state`](#signature_state)_] - [_[`signature`](#signature)_] - [_[`publickey`](#publickey)_] - [_[`secretkey`](#secretkey)_] - [_[`signature_verification_state`](#signature_verification_state)_] - [_[`symmetric_state`](#symmetric_state)_] - [_[`symmetric_key`](#symmetric_key)_] - [_[`symmetric_tag`](#symmetric_tag)_] - [_[`opt_options_u`](#opt_options_u)_] - [_[`opt_options`](#opt_options)_] - [_[`opt_symmetric_key_u`](#opt_symmetric_key_u)_] - [_[`opt_symmetric_key`](#opt_symmetric_key)_] - [_[`output`](#output)_] - [_[`output_len`](#output_len)_] - [_[`data`](#data)_] - [_[`data_len`](#data_len)_] - [_[`raw_tag`](#raw_tag)_] - [_[`raw_tag_len`](#raw_tag_len)_] - [_[`encrypt_params`](#encrypt_params)_] - [_[`decrypt_detached_params`](#decrypt_detached_params)_] - [_[`encrypt_result`](#encrypt_result)_] - [_[`batch_encrypt_results`](#batch_encrypt_results)_] - [_[`encrypt_detached_result`](#encrypt_detached_result)_] - [_[`batch_encrypt_detached_results`](#batch_encrypt_detached_results)_] - [_[`squeeze_params`](#squeeze_params)_] - [_[`squeeze_results`](#squeeze_results)_] 9 | 10 | ### Functions list: 11 | 12 | [**[All](#functions)**] - [[`batch_symmetric_state_squeeze()`](#batch_symmetric_state_squeeze)] - [[`batch_symmetric_state_squeeze_tag()`](#batch_symmetric_state_squeeze_tag)] - [[`batch_symmetric_state_encrypt()`](#batch_symmetric_state_encrypt)] - [[`batch_symmetric_state_encrypt_detached()`](#batch_symmetric_state_encrypt_detached)] - [[`batch_symmetric_state_decrypt()`](#batch_symmetric_state_decrypt)] - [[`batch_symmetric_state_decrypt_detached()`](#batch_symmetric_state_decrypt_detached)] 13 | 14 | ## Types 15 | 16 | ### _[`crypto_errno`](#crypto_errno)_ 17 | 18 | Enumeration with tag type: `u16`, and the following members: 19 | 20 | * **`success`**: _[`crypto_errno`](#crypto_errno)_ 21 | * **`guest_error`**: _[`crypto_errno`](#crypto_errno)_ 22 | * **`not_implemented`**: _[`crypto_errno`](#crypto_errno)_ 23 | * **`unsupported_feature`**: _[`crypto_errno`](#crypto_errno)_ 24 | * **`prohibited_operation`**: _[`crypto_errno`](#crypto_errno)_ 25 | * **`unsupported_encoding`**: _[`crypto_errno`](#crypto_errno)_ 26 | * **`unsupported_algorithm`**: _[`crypto_errno`](#crypto_errno)_ 27 | * **`unsupported_option`**: _[`crypto_errno`](#crypto_errno)_ 28 | * **`invalid_key`**: _[`crypto_errno`](#crypto_errno)_ 29 | * **`invalid_length`**: _[`crypto_errno`](#crypto_errno)_ 30 | * **`verification_failed`**: _[`crypto_errno`](#crypto_errno)_ 31 | * **`rng_error`**: _[`crypto_errno`](#crypto_errno)_ 32 | * **`algorithm_failure`**: _[`crypto_errno`](#crypto_errno)_ 33 | * **`invalid_signature`**: _[`crypto_errno`](#crypto_errno)_ 34 | * **`closed`**: _[`crypto_errno`](#crypto_errno)_ 35 | * **`invalid_handle`**: _[`crypto_errno`](#crypto_errno)_ 36 | * **`overflow`**: _[`crypto_errno`](#crypto_errno)_ 37 | * **`internal_error`**: _[`crypto_errno`](#crypto_errno)_ 38 | * **`too_many_handles`**: _[`crypto_errno`](#crypto_errno)_ 39 | * **`key_not_supported`**: _[`crypto_errno`](#crypto_errno)_ 40 | * **`key_required`**: _[`crypto_errno`](#crypto_errno)_ 41 | * **`invalid_tag`**: _[`crypto_errno`](#crypto_errno)_ 42 | * **`invalid_operation`**: _[`crypto_errno`](#crypto_errno)_ 43 | * **`nonce_required`**: _[`crypto_errno`](#crypto_errno)_ 44 | * **`invalid_nonce`**: _[`crypto_errno`](#crypto_errno)_ 45 | * **`option_not_set`**: _[`crypto_errno`](#crypto_errno)_ 46 | * **`not_found`**: _[`crypto_errno`](#crypto_errno)_ 47 | * **`parameters_missing`**: _[`crypto_errno`](#crypto_errno)_ 48 | * **`in_progress`**: _[`crypto_errno`](#crypto_errno)_ 49 | * **`incompatible_keys`**: _[`crypto_errno`](#crypto_errno)_ 50 | * **`expired`**: _[`crypto_errno`](#crypto_errno)_ 51 | 52 | > Error codes. 53 | 54 | 55 | --- 56 | 57 | ### _[`keypair_encoding`](#keypair_encoding)_ 58 | 59 | Enumeration with tag type: `u16`, and the following members: 60 | 61 | * **`raw`**: _[`keypair_encoding`](#keypair_encoding)_ 62 | * **`pkcs8`**: _[`keypair_encoding`](#keypair_encoding)_ 63 | * **`pem`**: _[`keypair_encoding`](#keypair_encoding)_ 64 | * **`local`**: _[`keypair_encoding`](#keypair_encoding)_ 65 | 66 | > Encoding to use for importing or exporting a key pair. 67 | 68 | 69 | --- 70 | 71 | ### _[`publickey_encoding`](#publickey_encoding)_ 72 | 73 | Enumeration with tag type: `u16`, and the following members: 74 | 75 | * **`raw`**: _[`publickey_encoding`](#publickey_encoding)_ 76 | * **`pkcs8`**: _[`publickey_encoding`](#publickey_encoding)_ 77 | * **`pem`**: _[`publickey_encoding`](#publickey_encoding)_ 78 | * **`sec`**: _[`publickey_encoding`](#publickey_encoding)_ 79 | * **`local`**: _[`publickey_encoding`](#publickey_encoding)_ 80 | 81 | > Encoding to use for importing or exporting a public key. 82 | 83 | 84 | --- 85 | 86 | ### _[`secretkey_encoding`](#secretkey_encoding)_ 87 | 88 | Enumeration with tag type: `u16`, and the following members: 89 | 90 | * **`raw`**: _[`secretkey_encoding`](#secretkey_encoding)_ 91 | * **`pkcs8`**: _[`secretkey_encoding`](#secretkey_encoding)_ 92 | * **`pem`**: _[`secretkey_encoding`](#secretkey_encoding)_ 93 | * **`sec`**: _[`secretkey_encoding`](#secretkey_encoding)_ 94 | * **`local`**: _[`secretkey_encoding`](#secretkey_encoding)_ 95 | 96 | > Encoding to use for importing or exporting a secret key. 97 | 98 | 99 | --- 100 | 101 | ### _[`signature_encoding`](#signature_encoding)_ 102 | 103 | Enumeration with tag type: `u16`, and the following members: 104 | 105 | * **`raw`**: _[`signature_encoding`](#signature_encoding)_ 106 | * **`der`**: _[`signature_encoding`](#signature_encoding)_ 107 | 108 | > Encoding to use for importing or exporting a signature. 109 | 110 | 111 | --- 112 | 113 | ### _[`algorithm_type`](#algorithm_type)_ 114 | 115 | Enumeration with tag type: `u16`, and the following members: 116 | 117 | * **`signatures`**: _[`algorithm_type`](#algorithm_type)_ 118 | * **`symmetric`**: _[`algorithm_type`](#algorithm_type)_ 119 | * **`key_exchange`**: _[`algorithm_type`](#algorithm_type)_ 120 | 121 | > An algorithm category. 122 | 123 | 124 | --- 125 | 126 | ### _[`version`](#version)_ 127 | Alias for `u64`. 128 | 129 | 130 | > Version of a managed key. 131 | > 132 | > A version can be an arbitrary `u64` integer, with the expection of some reserved values. 133 | 134 | 135 | --- 136 | 137 | ### _[`size`](#size)_ 138 | Alias for `usize`. 139 | 140 | 141 | > Size of a value. 142 | 143 | 144 | --- 145 | 146 | ### _[`timestamp`](#timestamp)_ 147 | Alias for `u64`. 148 | 149 | 150 | > A UNIX timestamp, in seconds since 01/01/1970. 151 | 152 | 153 | --- 154 | 155 | ### _[`u64`](#u64)_ 156 | Alias for `u64`. 157 | 158 | 159 | > A 64-bit value 160 | 161 | 162 | --- 163 | 164 | ### _[`array_output`](#array_output)_ 165 | Alias for `handle`. 166 | 167 | 168 | > Handle for functions returning output whose size may be large or not known in advance. 169 | > 170 | > An `array_output` object contains a host-allocated byte array. 171 | > 172 | > A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. 173 | > In addition, the content of such an object can be consumed by a guest in a streaming fashion. 174 | > 175 | > An `array_output` handle is automatically closed after its full content has been consumed. 176 | 177 | 178 | --- 179 | 180 | ### _[`options`](#options)_ 181 | Alias for `handle`. 182 | 183 | 184 | > A set of options. 185 | > 186 | > This type is used to set non-default parameters. 187 | > 188 | > The exact set of allowed options depends on the algorithm being used. 189 | 190 | 191 | --- 192 | 193 | ### _[`secrets_manager`](#secrets_manager)_ 194 | Alias for `handle`. 195 | 196 | 197 | > A handle to the optional secrets management facilities offered by a host. 198 | > 199 | > This is used to generate, retrieve and invalidate managed keys. 200 | 201 | 202 | --- 203 | 204 | ### _[`keypair`](#keypair)_ 205 | Alias for `handle`. 206 | 207 | 208 | > A key pair. 209 | 210 | 211 | --- 212 | 213 | ### _[`signature_state`](#signature_state)_ 214 | Alias for `handle`. 215 | 216 | 217 | > A state to absorb data to be signed. 218 | > 219 | > After a signature has been computed or verified, the state remains valid for further operations. 220 | > 221 | > A subsequent signature would sign all the data accumulated since the creation of the state object. 222 | 223 | 224 | --- 225 | 226 | ### _[`signature`](#signature)_ 227 | Alias for `handle`. 228 | 229 | 230 | > A signature. 231 | 232 | 233 | --- 234 | 235 | ### _[`publickey`](#publickey)_ 236 | Alias for `handle`. 237 | 238 | 239 | > A public key, for key exchange and signature verification. 240 | 241 | 242 | --- 243 | 244 | ### _[`secretkey`](#secretkey)_ 245 | Alias for `handle`. 246 | 247 | 248 | > A secret key, for key exchange mechanisms. 249 | 250 | 251 | --- 252 | 253 | ### _[`signature_verification_state`](#signature_verification_state)_ 254 | Alias for `handle`. 255 | 256 | 257 | > A state to absorb signed data to be verified. 258 | 259 | 260 | --- 261 | 262 | ### _[`symmetric_state`](#symmetric_state)_ 263 | Alias for `handle`. 264 | 265 | 266 | > A state to perform symmetric operations. 267 | > 268 | > The state is not reset nor invalidated after an option has been performed. 269 | > Incremental updates and sessions are thus supported. 270 | 271 | 272 | --- 273 | 274 | ### _[`symmetric_key`](#symmetric_key)_ 275 | Alias for `handle`. 276 | 277 | 278 | > A symmetric key. 279 | > 280 | > The key can be imported from raw bytes, or can be a reference to a managed key. 281 | > 282 | > If it was imported, the host will wipe it from memory as soon as the handle is closed. 283 | 284 | 285 | --- 286 | 287 | ### _[`symmetric_tag`](#symmetric_tag)_ 288 | Alias for `handle`. 289 | 290 | 291 | > An authentication tag. 292 | > 293 | > This is an object returned by functions computing authentication tags. 294 | > 295 | > A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function. 296 | > 297 | > This object type can't be directly created from raw bytes. They are only returned by functions computing MACs. 298 | > 299 | > The host is reponsible for securely wiping them from memory on close. 300 | 301 | 302 | --- 303 | 304 | ### _[`opt_options_u`](#opt_options_u)_ 305 | 306 | Enumeration with tag type: `u8`, and the following members: 307 | 308 | * **`some`**: _[`opt_options_u`](#opt_options_u)_ 309 | * **`none`**: _[`opt_options_u`](#opt_options_u)_ 310 | 311 | > Options index, only required by the Interface Types translation layer. 312 | 313 | 314 | --- 315 | 316 | ### _[`opt_options`](#opt_options)_ 317 | Tagged union with tag type: `u8` and the following possibilities: 318 | 319 | * **`some`**: _[`options`](#options)_ 320 | * **`none`**: _(empty)_ 321 | 322 | > An optional options set. 323 | > 324 | > This union simulates an `Option\` type to make the `options` parameter of some functions optional. 325 | 326 | 327 | --- 328 | 329 | ### _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 330 | 331 | Enumeration with tag type: `u8`, and the following members: 332 | 333 | * **`some`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 334 | * **`none`**: _[`opt_symmetric_key_u`](#opt_symmetric_key_u)_ 335 | 336 | > Symmetric key index, only required by the Interface Types translation layer. 337 | 338 | 339 | --- 340 | 341 | ### _[`opt_symmetric_key`](#opt_symmetric_key)_ 342 | Tagged union with tag type: `u8` and the following possibilities: 343 | 344 | * **`some`**: _[`symmetric_key`](#symmetric_key)_ 345 | * **`none`**: _(empty)_ 346 | 347 | > An optional symmetric key. 348 | > 349 | > This union simulates an `Option\` type to make the `symmetric_key` parameter of some functions optional. 350 | 351 | 352 | --- 353 | 354 | ### _[`output`](#output)_ 355 | Alias for `u8` mutable slice. 356 | 357 | 358 | > An output buffer 359 | 360 | 361 | --- 362 | 363 | ### _[`output_len`](#output_len)_ 364 | 365 | Alias for `usize`. 366 | 367 | 368 | --- 369 | 370 | ### _[`data`](#data)_ 371 | Alias for `u8` slice. 372 | 373 | 374 | > A non-mutable data buffer 375 | 376 | 377 | --- 378 | 379 | ### _[`data_len`](#data_len)_ 380 | 381 | Alias for `usize`. 382 | 383 | 384 | --- 385 | 386 | ### _[`raw_tag`](#raw_tag)_ 387 | Alias for `u8` slice. 388 | 389 | 390 | > An raw tag buffer 391 | 392 | 393 | --- 394 | 395 | ### _[`raw_tag_len`](#raw_tag_len)_ 396 | 397 | Alias for `usize`. 398 | 399 | 400 | --- 401 | 402 | ### _[`encrypt_params`](#encrypt_params)_ 403 | Tuple, representing (_[`symmetric_state`](#symmetric_state)_, _[`output`](#output)_, _[`output_len`](#output_len)_, _[`data`](#data)_, _[`data_len`](#data_len)_). 404 | 405 | 406 | > A tuple of parameters for an encryption operation. 407 | 408 | 409 | --- 410 | 411 | ### _[`decrypt_detached_params`](#decrypt_detached_params)_ 412 | Tuple, representing (_[`symmetric_state`](#symmetric_state)_, _[`output`](#output)_, _[`output_len`](#output_len)_, _[`data`](#data)_, _[`data_len`](#data_len)_, _[`raw_tag`](#raw_tag)_, _[`raw_tag_len`](#raw_tag_len)_). 413 | 414 | 415 | > A tuple of parameters for a detached decryption operation. 416 | 417 | 418 | --- 419 | 420 | ### _[`encrypt_result`](#encrypt_result)_ 421 | Tuple, representing (_[`size`](#size)_, _[`crypto_errno`](#crypto_errno)_). 422 | 423 | 424 | --- 425 | 426 | ### _[`batch_encrypt_results`](#batch_encrypt_results)_ 427 | Alias for _[`encrypt_result`](#encrypt_result)_ mutable slice. 428 | 429 | 430 | --- 431 | 432 | ### _[`encrypt_detached_result`](#encrypt_detached_result)_ 433 | Tuple, representing (_[`symmetric_tag`](#symmetric_tag)_, _[`crypto_errno`](#crypto_errno)_). 434 | 435 | 436 | --- 437 | 438 | ### _[`batch_encrypt_detached_results`](#batch_encrypt_detached_results)_ 439 | Alias for _[`encrypt_detached_result`](#encrypt_detached_result)_ mutable slice. 440 | 441 | 442 | --- 443 | 444 | ### _[`squeeze_params`](#squeeze_params)_ 445 | Tuple, representing (_[`symmetric_state`](#symmetric_state)_, _[`data`](#data)_, _[`data_len`](#data_len)_). 446 | 447 | 448 | --- 449 | 450 | ### _[`squeeze_results`](#squeeze_results)_ 451 | Alias for _[`crypto_errno`](#crypto_errno)_ mutable slice. 452 | 453 | 454 | --- 455 | 456 | ## Functions 457 | 458 | ### [`batch_symmetric_state_squeeze()`](#batch_symmetric_state_squeeze) 459 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 460 | 461 | #### Input: 462 | 463 | * **`params`**: _[`squeeze_params`](#squeeze_params)_ mutable slice 464 | 465 | #### Output: 466 | 467 | * _[`squeeze_results`](#squeeze_results)_ mutable pointer 468 | 469 | > Batch of operations to squeeze bytes from the state. 470 | > 471 | > - **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. 472 | > - **Key derivation functions:** : outputs an arbitrary-long derived key. 473 | > - **RNGs, DRBGs, stream ciphers:**: outputs arbitrary-long data. 474 | > - **Stateful hash objects, permutation-based constructions:** squeeze. 475 | > 476 | > Other kinds of algorithms may return `invalid_operation` instead. 477 | > 478 | > For password-stretching functions, the function may return `in_progress`. 479 | > In that case, the guest should retry with the same parameters until the function completes. 480 | 481 | 482 | --- 483 | 484 | ### [`batch_symmetric_state_squeeze_tag()`](#batch_symmetric_state_squeeze_tag) 485 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 486 | 487 | #### Input: 488 | 489 | * **`states`**: _[`symmetric_state`](#symmetric_state)_ mutable slice 490 | 491 | #### Output: 492 | 493 | * _[`batch_encrypt_detached_results`](#batch_encrypt_detached_results)_ mutable pointer 494 | 495 | > Batch of operations to compute and return a tag for all the data 496 | > injected into the state so far. 497 | > 498 | > - **MAC functions**: returns a tag authenticating the absorbed data. 499 | > - **Tuplehash-like constructions:** returns a tag authenticating all the absorbed tuples. 500 | > - **Password-hashing functions:** returns a standard string containing all the required parameters for password verification. 501 | > 502 | > Other kinds of algorithms may return `invalid_operation` instead. 503 | > 504 | > For password-stretching functions, the function may return `in_progress`. 505 | > In that case, the guest should retry with the same parameters until the function completes. 506 | > 507 | > TODO: Refactor return type to share a more generic common type with encrypt detached results 508 | 509 | 510 | --- 511 | 512 | ### [`batch_symmetric_state_encrypt()`](#batch_symmetric_state_encrypt) 513 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 514 | 515 | #### Input: 516 | 517 | * **`batch`**: (_[`symmetric_state`](#symmetric_state)_, _[`output`](#output)_, _[`output_len`](#output_len)_, _[`data`](#data)_, _[`data_len`](#data_len)_) mutable slice 518 | 519 | #### Output: 520 | 521 | * _[`batch_encrypt_results`](#batch_encrypt_results)_ mutable pointer 522 | 523 | > Perform a batch of symmetric encrypt operations. 524 | > 525 | > This is a batch version of the symmetric_state_encrypto operation and 526 | > is an extension of the wasi_empemeral_crypto_symmetric module. 527 | > 528 | > Each entry in the batch corresponds to an individual encrypt operation. 529 | > The parameters associated with each encrypt operation are grouped into a 530 | > tuple. 531 | > 532 | > If the entire batch could not be processed an error code of type 533 | > $crypto_errno is returned. If part of the batch was successfully 534 | > processed and part (one or more) resulted in a failure, each result 535 | > is a pair of an error code and a size. The size is only valid 536 | > if the error code indicates success. 537 | > 538 | > The size corresponds to the actual size of the ciphertext and the tag 539 | > in the ouput buffer. 540 | > 541 | > Example usage: 542 | > 543 | > ```rust 544 | > let mut batch = Vec::new(); 545 | > 546 | > let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; 547 | > let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; 548 | > batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); 549 | > 550 | > let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; 551 | > let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; 552 | > batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); 553 | > 554 | > let results = ctx.batch_symmetric_state_encrypt(batch)?; 555 | > ``` 556 | 557 | 558 | --- 559 | 560 | ### [`batch_symmetric_state_encrypt_detached()`](#batch_symmetric_state_encrypt_detached) 561 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 562 | 563 | #### Input: 564 | 565 | * **`batch`**: (_[`symmetric_state`](#symmetric_state)_, _[`output`](#output)_, _[`output_len`](#output_len)_, _[`data`](#data)_, _[`data_len`](#data_len)_) mutable slice 566 | 567 | #### Output: 568 | 569 | * _[`batch_encrypt_detached_results`](#batch_encrypt_detached_results)_ mutable pointer 570 | 571 | > Perform a batch of symmetric encrypt operations with detached tags. 572 | 573 | 574 | --- 575 | 576 | ### [`batch_symmetric_state_decrypt()`](#batch_symmetric_state_decrypt) 577 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 578 | 579 | #### Input: 580 | 581 | * **`batch`**: (_[`symmetric_state`](#symmetric_state)_, _[`output`](#output)_, _[`output_len`](#output_len)_, _[`data`](#data)_, _[`data_len`](#data_len)_) mutable slice 582 | 583 | #### Output: 584 | 585 | * _[`batch_encrypt_results`](#batch_encrypt_results)_ mutable pointer 586 | 587 | > Perform a batch of symmetric decrypt operations. 588 | 589 | 590 | --- 591 | 592 | ### [`batch_symmetric_state_decrypt_detached()`](#batch_symmetric_state_decrypt_detached) 593 | Returned error type: _[`crypto_errno`](#crypto_errno)_ 594 | 595 | #### Input: 596 | 597 | * **`batch`**: (_[`symmetric_state`](#symmetric_state)_, _[`output`](#output)_, _[`output_len`](#output_len)_, _[`data`](#data)_, _[`data_len`](#data_len)_, _[`raw_tag`](#raw_tag)_, _[`raw_tag_len`](#raw_tag_len)_) mutable slice 598 | 599 | #### Output: 600 | 601 | * _[`batch_encrypt_results`](#batch_encrypt_results)_ mutable pointer 602 | 603 | > Perform a batch of symmetric decrypt operations with detached tags. 604 | > 605 | > TODO: Replace the encrypt_params type with something more generic that 606 | > that works for both encrypt and decrypt. 607 | 608 | 609 | --- 610 | 611 | -------------------------------------------------------------------------------- /witx/witx-0.10/wasi_ephemeral_crypto_symmetric_batch.witx: -------------------------------------------------------------------------------- 1 | ;;; Symmetric Batch Operations 2 | (module $wasi_ephemeral_crypto_symmetric_batch 3 | (use * from $wasi_ephemeral_crypto_common) 4 | 5 | ;;; An output buffer 6 | (typename $output (out-buffer u8)) 7 | (typename $output_len $size) 8 | 9 | ;;; A non-mutable data buffer 10 | (typename $data (in-buffer u8)) 11 | (typename $data_len $size) 12 | 13 | ;;; An raw tag buffer 14 | (typename $raw_tag (in-buffer u8)) 15 | (typename $raw_tag_len $size) 16 | 17 | ;;; Tuple representing results and size produced by an encrypt/decrypt operation. 18 | (typename $crypt_result (tuple $size $crypto_errno)) 19 | 20 | ;;; A list of results from the individual encrypt/decrypt operations within a batch operation. 21 | (typename $batch_crypt_results (list $crypt_result)) 22 | 23 | ;;; Tuple representing results and size produced by a detached encrypt operation. 24 | (typename $encrypt_detached_result (tuple $symmetric_tag $crypto_errno)) 25 | 26 | ;;; A list of results from the individual encrypt/decrypt operations within a batch operation. 27 | (typename $batch_encrypt_detached_results (list $encrypt_detached_result)) 28 | 29 | ;;; A list of results from squeeze operation within a batch operation. 30 | (typename $batch_squeeze_results (list $crypto_errno)) 31 | 32 | ;;; Tuple representing results and tag and error produced by a detached squeeze operation. 33 | (typename $squeeze_detached_result (tuple $symmetric_tag $crypto_errno)) 34 | 35 | ;;; A list of results from the individual detached squeeze operations within a batch operation. 36 | (typename $batch_squeeze_detached_results (list $squeeze_detached_result)) 37 | 38 | ;;; Batch of operations to squeeze bytes from a batch of states. 39 | ;;; 40 | ;;; This is a batch version of the $symmetric_state_squeeze operation. 41 | ;;; 42 | ;;; Each entry in the batch corresponds to an individual squeeze operation. 43 | ;;; The parameters associated with each operation are grouped into a tuple. 44 | ;;; 45 | ;;; The batch operation returns an error code of type $crypto_errno that 46 | ;;; indicates if the batch was processed or if the batch could not be 47 | ;;; processed. 48 | ;;; 49 | ;;; Batch processing error codes: 50 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 51 | ;;; - `not_implemented`: Batch functionality is not supported. 52 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 53 | ;;; 54 | ;;; If the batch was processed, the result is a list of $crypto_errno error 55 | ;;; codes that represent the status of the operation in the input list at 56 | ;;; the same list offset. 57 | ;;; 58 | (@interface func (export "batch_symmetric_state_squeeze") 59 | (param $batch (list (tuple $symmetric_state $data $data_len))) 60 | (result $error (expected $batch_squeeze_results (error $crypto_errno))) 61 | ) 62 | 63 | ;;; Batch of operations to compute and return a tag for all the data 64 | ;;; injected into the state so far. 65 | ;;; 66 | ;;; This is a batch version of the $symmetric_state_squeeze_tag operation. 67 | ;;; 68 | ;;; Each entry in the batch corresponds to an individual squeeze_tag 69 | ;;; operation. The parameters associated with each operation are grouped 70 | ;;; into a tuple. 71 | ;;; 72 | ;;; The batch operation returns an error code of type $crypto_errno that 73 | ;;; indicates if the batch was processed or if the batch could not be 74 | ;;; processed. 75 | ;;; 76 | ;;; Batch processing error codes: 77 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 78 | ;;; - `not_implemented`: Batch functionality is not supported. 79 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 80 | ;;; 81 | ;;; If the batch was processed, the result is a list of tuples, with each 82 | ;;; list entry corresponding to the operation in the input list at the same 83 | ;;; list offset. Each tuple contains a $crypto_errno error code and a tag. 84 | ;;; The error code represents the status of the operation and the tag is the 85 | ;;; tag generated from the squeeze operation. The tag is only valid if the 86 | ;;; tuple's error code is `success`. 87 | ;;; 88 | (@interface func (export "batch_symmetric_state_squeeze_tag") 89 | (param $states (list $symmetric_state)) 90 | (result $error (expected $batch_squeeze_detached_results (error $crypto_errno))) 91 | ) 92 | 93 | ;;; Perform a batch of symmetric encrypt operations. 94 | ;;; 95 | ;;; This is a batch version of the symmetric_state_encrypt operation. 96 | ;;; 97 | ;;; Each entry in the batch corresponds to an individual encrypt operation. 98 | ;;; The parameters associated with each encrypt operation are grouped into a 99 | ;;; tuple. 100 | ;;; 101 | ;;; The batch operation returns an error code of type $crypto_errno that 102 | ;;; indicates if the batch was processed or if the batch could not be 103 | ;;; processed. 104 | ;;; 105 | ;;; Batch processing error codes: 106 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 107 | ;;; - `not_implemented`: Batch functionality is not supported. 108 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 109 | ;;; 110 | ;;; If the batch was processed, the result is a list of tuples, with each 111 | ;;; list entry corresponding to the operation in the input list at the same 112 | ;;; list offset. 113 | ;;; Each tuple contains a size and a $crypto_errno error code. 114 | ;;; The error code represents the status of the operation and the size is 115 | ;;; the actual size of the ciphertext and the tag in the ouput buffer. The 116 | ;;; size value is only valid if the tuple's error code is `success`. 117 | ;;; 118 | ;;; Example usage: 119 | ;;; 120 | ;;; ```rust 121 | ;;; let mut batch = Vec::new(); 122 | ;;; 123 | ;;; let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; 124 | ;;; let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; 125 | ;;; batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); 126 | ;;; 127 | ;;; let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; 128 | ;;; let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; 129 | ;;; batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); 130 | ;;; 131 | ;;; let results = ctx.batch_symmetric_state_encrypt(batch)?; 132 | ;;; ``` 133 | (@interface func (export "batch_symmetric_state_encrypt") 134 | (param $batch (list (tuple $symmetric_state $output $output_len $data $data_len))) 135 | (result $error (expected $batch_crypt_results (error $crypto_errno))) 136 | ) 137 | 138 | ;;; Perform a batch of symmetric encrypt operations with detached tags. 139 | ;;; 140 | ;;; This is a batch version of the symmetric_state_encrypt_detached 141 | ;;; operation. 142 | ;;; 143 | ;;; Each entry in the batch corresponds to an individual encrypt operation. 144 | ;;; The parameters associated with each encrypt operation are grouped into a 145 | ;;; tuple. 146 | ;;; 147 | ;;; The batch operation returns an error code of type $crypto_errno that 148 | ;;; indicates if the batch was processed or if the batch could not be 149 | ;;; processed. 150 | ;;; 151 | ;;; Batch processing error codes: 152 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 153 | ;;; - `not_implemented`: Batch functionality is not supported. 154 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 155 | ;;; 156 | ;;; If the batch was processed, the result is a list of tuples, with each 157 | ;;; list entry corresponding to the operation in the input list at the same 158 | ;;; list offset. 159 | ;;; Each tuple contains a tag and a $crypto_errno error code. 160 | ;;; The error code represents the status of the operation and the tag is 161 | ;;; the tag generated by the operation. The tag is only valid if the tuple's 162 | ;;; error code is `success`. 163 | ;;; 164 | ;;; Example usage: 165 | ;;; 166 | ;;; ```rust 167 | ;;; let mut batch = Vec::new(); 168 | ;;; 169 | ;;; let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle1), Some(options_handle1))?; 170 | ;;; let mut ciphertext = vec![0u8; message.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; 171 | ;;; batch.push((batch, state_handle, ciphertext, ciphertext.len(), message, message.len())); 172 | ;;; 173 | ;;; let state_handle = ctx.symmetric_state_open("AES-256-GCM", Some(key_handle2), Some(options_handle2))?; 174 | ;;; let mut ciphertext = vec![0u8; message2.len() + ctx.symmetric_state_max_tag_len(state_handle)?]; 175 | ;;; batch.push((batch, state_handle, ciphertext, ciphertext.len(), message2, message2.len())); 176 | ;;; 177 | ;;; let results = ctx.batch_symmetric_state_encrypt_detached(batch)?; 178 | ;;; ``` 179 | (@interface func (export "batch_symmetric_state_encrypt_detached") 180 | (param $batch (list (tuple $symmetric_state $output $output_len $data $data_len))) 181 | (result $error (expected $batch_encrypt_detached_results (error $crypto_errno))) 182 | ) 183 | 184 | ;;; Perform a batch of symmetric decrypt operations. 185 | ;;; 186 | ;;; This is a batch version of the symmetric_state_decrypt operation. 187 | ;;; 188 | ;;; Each entry in the batch corresponds to an individual decrypt operation. 189 | ;;; The parameters associated with each decrypt operation are grouped into a 190 | ;;; tuple. 191 | ;;; 192 | ;;; The batch operation returns an error code of type $crypto_errno that 193 | ;;; indicates if the batch was processed or if the batch could not be 194 | ;;; processed. 195 | ;;; 196 | ;;; Batch processing error codes: 197 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 198 | ;;; - `not_implemented`: Batch functionality is not supported. 199 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 200 | ;;; 201 | ;;; If the batch was processed, the result is a list of tuples, with each 202 | ;;; list entry corresponding to the operation in the input list at the same 203 | ;;; list offset. 204 | ;;; Each tuple contains a size and a $crypto_errno error code. 205 | ;;; The error code represents the status of the operation and the size is 206 | ;;; the actual size of the decrypted data in the ouput buffer. The size 207 | ;;; value is only valid if the tuple's error code is `success`. 208 | ;;; 209 | (@interface func (export "batch_symmetric_state_decrypt") 210 | (param $batch (list (tuple $symmetric_state $output $output_len $data $data_len))) 211 | (result $error (expected $batch_crypt_results (error $crypto_errno))) 212 | ) 213 | 214 | ;;; Perform a batch of symmetric decrypt operations with detached tags. 215 | ;;; 216 | ;;; This is a batch version of the symmetric_state_decrypt_detached operation. 217 | ;;; 218 | ;;; Each entry in the batch corresponds to an individual decrypt operation. 219 | ;;; The parameters associated with each decrypt operation are grouped into a 220 | ;;; tuple. 221 | ;;; 222 | ;;; The batch operation returns an error code of type $crypto_errno that 223 | ;;; indicates if the batch was processed or if the batch could not be 224 | ;;; processed. 225 | ;;; 226 | ;;; Batch processing error codes: 227 | ;;; - `success`: Batch was processed. The status of each operation is indicated in the results list. 228 | ;;; - `not_implemented`: Batch functionality is not supported. 229 | ;;; - `unsupported_feature`: Inconsistent operations within the batch, e.g. not all operations in the batch use the same algorithm. 230 | ;;; 231 | ;;; If the batch was processed, the result is a list of tuples, with each 232 | ;;; list entry corresponding to the operation in the input list at the same 233 | ;;; list offset. 234 | ;;; Each tuple contains a size and a $crypto_errno error code. 235 | ;;; The error code represents the status of the operation and the size is 236 | ;;; the actual size of the decrypted data in the ouput buffer. The size 237 | ;;; value is only valid if the tuple's error code is `success`. 238 | ;;; 239 | (@interface func (export "batch_symmetric_state_decrypt_detached") 240 | (param $batch (list (tuple $symmetric_state $output $output_len $data $data_len $raw_tag $raw_tag_len))) 241 | (result $error (expected $batch_crypt_results (error $crypto_errno))) 242 | ) 243 | ) -------------------------------------------------------------------------------- /witx/witx-0.9/proposal_asymmetric_common.witx: -------------------------------------------------------------------------------- 1 | (use "proposal_common.witx") 2 | 3 | (module $wasi_ephemeral_crypto_asymmetric_common 4 | (import "memory" (memory)) 5 | 6 | ;;; Generate a new key pair. 7 | ;;; 8 | ;;; Internally, a key pair stores the supplied algorithm and optional parameters. 9 | ;;; 10 | ;;; Trying to use that key pair with different parameters will throw an `invalid_key` error. 11 | ;;; 12 | ;;; This function may return `$crypto_errno.unsupported_feature` if key generation is not supported by the host for the chosen algorithm. 13 | ;;; 14 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 15 | ;;; 16 | ;;; Finally, if generating that type of key pair is an expensive operation, the function may return `in_progress`. 17 | ;;; In that case, the guest should retry with the same parameters until the function completes. 18 | ;;; 19 | ;;; Example usage: 20 | ;;; 21 | ;;; ```rust 22 | ;;; let kp_handle = ctx.keypair_generate(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", None)?; 23 | ;;; ``` 24 | (@interface func (export "keypair_generate") 25 | (param $algorithm_type $algorithm_type) 26 | (param $algorithm string) 27 | (param $options $opt_options) 28 | (result $error (expected $keypair (error $crypto_errno))) 29 | ) 30 | 31 | ;;; Import a key pair. 32 | ;;; 33 | ;;; This function creates a `keypair` object from existing material. 34 | ;;; 35 | ;;; It may return `unsupported_algorithm` if the encoding scheme is not supported, or `invalid_key` if the key cannot be decoded. 36 | ;;; 37 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 38 | ;;; 39 | ;;; Example usage: 40 | ;;; 41 | ;;; ```rust 42 | ;;; let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "RSA_PKCS1_2048_SHA256", KeypairEncoding::PKCS8)?; 43 | ;;; ``` 44 | (@interface func (export "keypair_import") 45 | (param $algorithm_type $algorithm_type) 46 | (param $algorithm string) 47 | (param $encoded (@witx const_pointer u8)) 48 | (param $encoded_len $size) 49 | (param $encoding $keypair_encoding) 50 | (result $error (expected $keypair (error $crypto_errno))) 51 | ) 52 | 53 | ;;; __(optional)__ 54 | ;;; Generate a new managed key pair. 55 | ;;; 56 | ;;; The key pair is generated and stored by the secrets management facilities. 57 | ;;; 58 | ;;; It may be used through its identifier, but the host may not allow it to be exported. 59 | ;;; 60 | ;;; The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host, 61 | ;;; or `unsupported_algorithm` if a key cannot be created for the chosen algorithm. 62 | ;;; 63 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 64 | ;;; 65 | ;;; This is also an optional import, meaning that the function may not even exist. 66 | (@interface func (export "keypair_generate_managed") 67 | (param $secrets_manager $secrets_manager) 68 | (param $algorithm_type $algorithm_type) 69 | (param $algorithm string) 70 | (param $options $opt_options) 71 | (result $error (expected $keypair (error $crypto_errno))) 72 | ) 73 | 74 | ;;; __(optional)__ 75 | ;;; Store a key pair into the secrets manager. 76 | ;;; 77 | ;;; On success, the function stores the key pair identifier into `$kp_id`, 78 | ;;; into which up to `$kp_id_max_len` can be written. 79 | ;;; 80 | ;;; The function returns `overflow` if the supplied buffer is too small. 81 | (@interface func (export "keypair_store_managed") 82 | (param $secrets_manager $secrets_manager) 83 | (param $kp $keypair) 84 | (param $kp_id (@witx pointer u8)) 85 | (param $kp_id_max_len $size) 86 | (result $error (expected (error $crypto_errno))) 87 | ) 88 | 89 | ;;; __(optional)__ 90 | ;;; Replace a managed key pair. 91 | ;;; 92 | ;;; This function crates a new version of a managed key pair, by replacing `$kp_old` with `$kp_new`. 93 | ;;; 94 | ;;; It does several things: 95 | ;;; 96 | ;;; - The key identifier for `$kp_new` is set to the one of `$kp_old`. 97 | ;;; - A new, unique version identifier is assigned to `$kp_new`. This version will be equivalent to using `$version_latest` until the key is replaced. 98 | ;;; - The `$kp_old` handle is closed. 99 | ;;; 100 | ;;; Both keys must share the same algorithm and have compatible parameters. If this is not the case, `incompatible_keys` is returned. 101 | ;;; 102 | ;;; The function may also return the `unsupported_feature` error code if secrets management facilities are not supported by the host, 103 | ;;; or if keys cannot be rotated. 104 | ;;; 105 | ;;; Finally, `prohibited_operation` can be returned if `$kp_new` wasn't created by the secrets manager, and the secrets manager prohibits imported keys. 106 | ;;; 107 | ;;; If the operation succeeded, the new version is returned. 108 | ;;; 109 | ;;; This is an optional import, meaning that the function may not even exist. 110 | (@interface func (export "keypair_replace_managed") 111 | (param $secrets_manager $secrets_manager) 112 | (param $kp_old $keypair) 113 | (param $kp_new $keypair) 114 | (result $error (expected $version (error $crypto_errno))) 115 | ) 116 | 117 | ;;; __(optional)__ 118 | ;;; Return the key pair identifier and version of a managed key pair. 119 | ;;; 120 | ;;; If the key pair is not managed, `unsupported_feature` is returned instead. 121 | ;;; 122 | ;;; This is an optional import, meaning that the function may not even exist. 123 | (@interface func (export "keypair_id") 124 | (param $kp $keypair) 125 | (param $kp_id (@witx pointer u8)) 126 | (param $kp_id_max_len $size) 127 | (result $error (expected (tuple $size $version) (error $crypto_errno))) 128 | ) 129 | 130 | ;;; __(optional)__ 131 | ;;; Return a managed key pair from a key identifier. 132 | ;;; 133 | ;;; `kp_version` can be set to `version_latest` to retrieve the most recent version of a key pair. 134 | ;;; 135 | ;;; If no key pair matching the provided information is found, `not_found` is returned instead. 136 | ;;; 137 | ;;; This is an optional import, meaning that the function may not even exist. 138 | ;;; ``` 139 | (@interface func (export "keypair_from_id") 140 | (param $secrets_manager $secrets_manager) 141 | (param $kp_id (@witx const_pointer u8)) 142 | (param $kp_id_len $size) 143 | (param $kp_version $version) 144 | (result $error (expected $keypair (error $crypto_errno))) 145 | ) 146 | 147 | ;;; Create a key pair from a public key and a secret key. 148 | (@interface func (export "keypair_from_pk_and_sk") 149 | (param $publickey $publickey) 150 | (param $secretkey $secretkey) 151 | (result $error (expected $keypair (error $crypto_errno))) 152 | ) 153 | 154 | ;;; Export a key pair as the given encoding format. 155 | ;;; 156 | ;;; May return `prohibited_operation` if this operation is denied or `unsupported_encoding` if the encoding is not supported. 157 | (@interface func (export "keypair_export") 158 | (param $kp $keypair) 159 | (param $encoding $keypair_encoding) 160 | (result $error (expected $array_output (error $crypto_errno))) 161 | ) 162 | 163 | ;;; Get the public key of a key pair. 164 | (@interface func (export "keypair_publickey") 165 | (param $kp $keypair) 166 | (result $error (expected $publickey (error $crypto_errno))) 167 | ) 168 | 169 | ;;; Get the secret key of a key pair. 170 | (@interface func (export "keypair_secretkey") 171 | (param $kp $keypair) 172 | (result $error (expected $secretkey (error $crypto_errno))) 173 | ) 174 | 175 | ;;; Destroy a key pair. 176 | ;;; 177 | ;;; The host will automatically wipe traces of the secret key from memory. 178 | ;;; 179 | ;;; If this is a managed key, the key will not be removed from persistent storage, and can be reconstructed later using the key identifier. 180 | (@interface func (export "keypair_close") 181 | (param $kp $keypair) 182 | (result $error (expected (error $crypto_errno))) 183 | ) 184 | 185 | ;;; Import a public key. 186 | ;;; 187 | ;;; The function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type. 188 | ;;; 189 | ;;; It may also return `invalid_key` if the key doesn't appear to match the supplied algorithm. 190 | ;;; 191 | ;;; Finally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host. 192 | ;;; 193 | ;;; Example usage: 194 | ;;; 195 | ;;; ```rust 196 | ;;; let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, encoded, PublicKeyEncoding::Sec)?; 197 | ;;; ``` 198 | (@interface func (export "publickey_import") 199 | (param $algorithm_type $algorithm_type) 200 | (param $algorithm string) 201 | (param $encoded (@witx const_pointer u8)) 202 | (param $encoded_len $size) 203 | (param $encoding $publickey_encoding) 204 | (result $error (expected $publickey (error $crypto_errno))) 205 | ) 206 | 207 | ;;; Export a public key as the given encoding format. 208 | ;;; 209 | ;;; May return `unsupported_encoding` if the encoding is not supported. 210 | (@interface func (export "publickey_export") 211 | (param $pk $publickey) 212 | (param $encoding $publickey_encoding) 213 | (result $error (expected $array_output (error $crypto_errno))) 214 | ) 215 | 216 | ;;; Check that a public key is valid and in canonical form. 217 | ;;; 218 | ;;; This function may perform stricter checks than those made during importation at the expense of additional CPU cycles. 219 | ;;; 220 | ;;; The function returns `invalid_key` if the public key didn't pass the checks. 221 | (@interface func (export "publickey_verify") 222 | (param $pk $publickey) 223 | (result $error (expected (error $crypto_errno))) 224 | ) 225 | 226 | ;;; Compute the public key for a secret key. 227 | (@interface func (export "publickey_from_secretkey") 228 | (param $sk $secretkey) 229 | (result $error (expected $publickey (error $crypto_errno))) 230 | ) 231 | 232 | ;;; Destroy a public key. 233 | ;;; 234 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 235 | (@interface func (export "publickey_close") 236 | (param $pk $publickey) 237 | (result $error (expected (error $crypto_errno))) 238 | ) 239 | 240 | ;;; Import a secret key. 241 | ;;; 242 | ;;; The function may return `unsupported_encoding` if importing from the given format is not implemented or incompatible with the key type. 243 | ;;; 244 | ;;; It may also return `invalid_key` if the key doesn't appear to match the supplied algorithm. 245 | ;;; 246 | ;;; Finally, the function may return `unsupported_algorithm` if the algorithm is not supported by the host. 247 | ;;; 248 | ;;; Example usage: 249 | ;;; 250 | ;;; ```rust 251 | ;;; let pk_handle = ctx.secretkey_import(AlgorithmType::KX, encoded, SecretKeyEncoding::Raw)?; 252 | ;;; ``` 253 | (@interface func (export "secretkey_import") 254 | (param $algorithm_type $algorithm_type) 255 | (param $algorithm string) 256 | (param $encoded (@witx const_pointer u8)) 257 | (param $encoded_len $size) 258 | (param $encoding $secretkey_encoding) 259 | (result $error (expected $secretkey (error $crypto_errno))) 260 | ) 261 | 262 | ;;; Export a secret key as the given encoding format. 263 | ;;; 264 | ;;; May return `unsupported_encoding` if the encoding is not supported. 265 | (@interface func (export "secretkey_export") 266 | (param $sk $secretkey) 267 | (param $encoding $secretkey_encoding) 268 | (result $error (expected $array_output (error $crypto_errno))) 269 | ) 270 | 271 | ;;; Destroy a secret key. 272 | ;;; 273 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 274 | (@interface func (export "secretkey_close") 275 | (param $sk $secretkey) 276 | (result $error (expected (error $crypto_errno))) 277 | ) 278 | ) 279 | -------------------------------------------------------------------------------- /witx/witx-0.9/proposal_common.witx: -------------------------------------------------------------------------------- 1 | ;;; Error codes. 2 | (typename $crypto_errno 3 | (enum (@witx tag u16) 4 | ;;; Operation succeeded. 5 | $success 6 | 7 | ;;; An error occurred when trying to during a conversion from a host type to a guest type. 8 | ;;; 9 | ;;; Only an internal bug can throw this error. 10 | $guest_error 11 | 12 | ;;; The requested operation is valid, but not implemented by the host. 13 | $not_implemented 14 | 15 | ;;; The requested feature is not supported by the chosen algorithm. 16 | $unsupported_feature 17 | 18 | ;;; The requested operation is valid, but was administratively prohibited. 19 | $prohibited_operation 20 | 21 | ;;; Unsupported encoding for an import or export operation. 22 | $unsupported_encoding 23 | 24 | ;;; The requested algorithm is not supported by the host. 25 | $unsupported_algorithm 26 | 27 | ;;; The requested option is not supported by the currently selected algorithm. 28 | $unsupported_option 29 | 30 | ;;; An invalid or incompatible key was supplied. 31 | ;;; 32 | ;;; The key may not be valid, or was generated for a different algorithm or parameters set. 33 | $invalid_key 34 | 35 | ;;; The currently selected algorithm doesn't support the requested output length. 36 | ;;; 37 | ;;; This error is thrown by non-extensible hash functions, when requesting an output size larger than they produce out of a single block. 38 | $invalid_length 39 | 40 | ;;; A signature or authentication tag verification failed. 41 | $verification_failed 42 | 43 | ;;; A secure random numbers generator is not available. 44 | ;;; 45 | ;;; The requested operation requires random numbers, but the host cannot securely generate them at the moment. 46 | $rng_error 47 | 48 | ;;; An error was returned by the underlying cryptography library. 49 | ;;; 50 | ;;; 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. 51 | ;;; 52 | ;;; Ideally, the specification should provide enough details and guidance to make this error impossible to ever be thrown. 53 | ;;; 54 | ;;; Realistically, the WASI crypto module cannot possibly cover all possible error types implementations can return, especially since some of these may be language-specific. 55 | ;;; 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. 56 | $algorithm_failure 57 | 58 | ;;; The supplied signature is invalid, or incompatible with the chosen algorithm. 59 | $invalid_signature 60 | 61 | ;;; An attempt was made to close a handle that was already closed. 62 | $closed 63 | 64 | ;;; A function was called with an unassigned handle, a closed handle, or handle of an unexpected type. 65 | $invalid_handle 66 | 67 | ;;; The host needs to copy data to a guest-allocated buffer, but that buffer is too small. 68 | $overflow 69 | 70 | ;;; An internal error occurred. 71 | ;;; 72 | ;;; 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. 73 | $internal_error 74 | 75 | ;;; Too many handles are currently open, and a new one cannot be created. 76 | ;;; 77 | ;;; Implementations are free to represent handles as they want, and to enforce limits to limit resources usage. 78 | $too_many_handles 79 | 80 | ;;; A key was provided, but the chosen algorithm doesn't support keys. 81 | ;;; 82 | ;;; This is returned by symmetric operations. 83 | ;;; 84 | ;;; Many hash functions, in particular, do not support keys without being used in particular constructions. 85 | ;;; Blindly ignoring a key provided by mistake while trying to open a context for such as function could cause serious security vulnerabilities. 86 | ;;; 87 | ;;; These functions must refuse to create the context and return this error instead. 88 | $key_not_supported 89 | 90 | ;;; A key is required for the chosen algorithm, but none was given. 91 | $key_required 92 | 93 | ;;; The provided authentication tag is invalid or incompatible with the current algorithm. 94 | ;;; 95 | ;;; This error is returned by decryption functions and tag verification functions. 96 | ;;; 97 | ;;; Unlike `verification_failed`, this error code is returned when the tag cannot possibly verify for any input. 98 | $invalid_tag 99 | 100 | ;;; The requested operation is incompatible with the current scheme. 101 | ;;; 102 | ;;; For example, the `symmetric_state_encrypt()` function cannot complete if the selected construction is a key derivation function. 103 | ;;; This error code will be returned instead. 104 | $invalid_operation 105 | 106 | ;;; A nonce is required. 107 | ;;; 108 | ;;; Most encryption schemes require a nonce. 109 | ;;; 110 | ;;; 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. 111 | ;;; 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. 112 | $nonce_required 113 | 114 | ;;; The provided nonce doesn't have a correct size for the given cipher. 115 | $invalid_nonce 116 | 117 | ;;; The named option was not set. 118 | ;;; 119 | ;;; The caller tried to read the value of an option that was not set. 120 | ;;; 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. 121 | $option_not_set 122 | 123 | ;;; A key or key pair matching the requested identifier cannot be found using the supplied information. 124 | ;;; 125 | ;;; This error is returned by a secrets manager via the `keypair_from_id()` function. 126 | $not_found 127 | 128 | ;;; The algorithm requires parameters that haven't been set. 129 | ;;; 130 | ;;; Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm. 131 | $parameters_missing 132 | 133 | ;;; A requested computation is not done yet, and additional calls to the function are required. 134 | ;;; 135 | ;;; Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete. 136 | ;;; 137 | ;;; 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. 138 | $in_progress 139 | 140 | ;;; Multiple keys have been provided, but they do not share the same type. 141 | ;;; 142 | ;;; 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. 143 | $incompatible_keys 144 | 145 | ;;; A managed key or secret expired and cannot be used any more. 146 | $expired 147 | ) 148 | ) 149 | 150 | ;;; Encoding to use for importing or exporting a key pair. 151 | (typename $keypair_encoding 152 | (enum (@witx tag u16) 153 | ;;; Raw bytes. 154 | $raw 155 | 156 | ;;; PCSK8/DER encoding. 157 | $pkcs8 158 | 159 | ;;; PEM encoding. 160 | $pem 161 | 162 | ;;; Implementation-defined encoding. 163 | $local 164 | ) 165 | ) 166 | 167 | ;;; Encoding to use for importing or exporting a public key. 168 | (typename $publickey_encoding 169 | (enum (@witx tag u16) 170 | ;;; Raw bytes. 171 | $raw 172 | 173 | ;;; PKCS8/DER encoding. 174 | $pkcs8 175 | 176 | ;;; PEM encoding. 177 | $pem 178 | 179 | ;;; SEC-1 encoding. 180 | $sec 181 | 182 | ;;; Implementation-defined encoding. 183 | $local 184 | ) 185 | ) 186 | 187 | ;;; Encoding to use for importing or exporting a secret key. 188 | (typename $secretkey_encoding 189 | (enum (@witx tag u16) 190 | ;;; Raw bytes. 191 | $raw 192 | 193 | ;;; PKCS8/DER encoding. 194 | $pkcs8 195 | 196 | ;;; PEM encoding. 197 | $pem 198 | 199 | ;;; SEC-1 encoding. 200 | $sec 201 | 202 | ;;; Implementation-defined encoding. 203 | $local 204 | ) 205 | ) 206 | 207 | ;;; Encoding to use for importing or exporting a signature. 208 | (typename $signature_encoding 209 | (enum (@witx tag u16) 210 | ;;; Raw bytes. 211 | $raw 212 | 213 | ;;; DER encoding. 214 | $der 215 | ) 216 | ) 217 | 218 | ;;; An algorithm category. 219 | (typename $algorithm_type 220 | (enum (@witx tag u16) 221 | $signatures 222 | $symmetric 223 | $key_exchange 224 | ) 225 | ) 226 | 227 | ;;; Version of a managed key. 228 | ;;; 229 | ;;; A version can be an arbitrary `u64` integer, with the expection of some reserved values. 230 | (typename $version u64) 231 | ;;; Key doesn't support versioning. 232 | (@witx const $version $unspecified 0xff00000000000000) 233 | 234 | ;;; Use the latest version of a key. 235 | (@witx const $version $latest 0xff00000000000001) 236 | 237 | ;;; Perform an operation over all versions of a key. 238 | (@witx const $version $all 0xff00000000000002) 239 | 240 | ;;; Size of a value. 241 | (typename $size (@witx usize)) 242 | 243 | ;;; A UNIX timestamp, in seconds since 01/01/1970. 244 | (typename $timestamp u64) 245 | 246 | ;;; Handle for functions returning output whose size may be large or not known in advance. 247 | ;;; 248 | ;;; An `array_output` object contains a host-allocated byte array. 249 | ;;; 250 | ;;; A guest can get the size of that array after a function returns in order to then allocate a buffer of the correct size. 251 | ;;; In addition, the content of such an object can be consumed by a guest in a streaming fashion. 252 | ;;; 253 | ;;; An `array_output` handle is automatically closed after its full content has been consumed. 254 | (typename $array_output (handle)) 255 | 256 | ;;; A set of options. 257 | ;;; 258 | ;;; This type is used to set non-default parameters. 259 | ;;; 260 | ;;; The exact set of allowed options depends on the algorithm being used. 261 | (typename $options (handle)) 262 | 263 | ;;; A handle to the optional secrets management facilities offered by a host. 264 | ;;; 265 | ;;; This is used to generate, retrieve and invalidate managed keys. 266 | (typename $secrets_manager (handle)) 267 | 268 | ;;; A key pair. 269 | (typename $keypair (handle)) 270 | 271 | ;;; A state to absorb data to be signed. 272 | ;;; 273 | ;;; After a signature has been computed or verified, the state remains valid for further operations. 274 | ;;; 275 | ;;; A subsequent signature would sign all the data accumulated since the creation of the state object. 276 | (typename $signature_state (handle)) 277 | 278 | ;;; A signature. 279 | (typename $signature (handle)) 280 | 281 | ;;; A public key, for key exchange and signature verification. 282 | (typename $publickey (handle)) 283 | 284 | ;;; A secret key, for key exchange mechanisms. 285 | (typename $secretkey (handle)) 286 | 287 | ;;; A state to absorb signed data to be verified. 288 | (typename $signature_verification_state (handle)) 289 | 290 | ;;; A state to perform symmetric operations. 291 | ;;; 292 | ;;; The state is not reset nor invalidated after an option has been performed. 293 | ;;; Incremental updates and sessions are thus supported. 294 | (typename $symmetric_state (handle)) 295 | 296 | ;;; A symmetric key. 297 | ;;; 298 | ;;; The key can be imported from raw bytes, or can be a reference to a managed key. 299 | ;;; 300 | ;;; If it was imported, the host will wipe it from memory as soon as the handle is closed. 301 | (typename $symmetric_key (handle)) 302 | 303 | ;;; An authentication tag. 304 | ;;; 305 | ;;; This is an object returned by functions computing authentication tags. 306 | ;;; 307 | ;;; A tag can be compared against another tag (directly supplied as raw bytes) in constant time with the `symmetric_tag_verify()` function. 308 | ;;; 309 | ;;; This object type can't be directly created from raw bytes. They are only returned by functions computing MACs. 310 | ;;; 311 | ;;; The host is reponsible for securely wiping them from memory on close. 312 | (typename $symmetric_tag (handle)) 313 | 314 | ;;; Options index, only required by the Interface Types translation layer. 315 | (typename $opt_options_u (enum (@witx tag u8) $some $none)) 316 | 317 | ;;; An optional options set. 318 | ;;; 319 | ;;; This union simulates an `Option` type to make the `options` parameter of some functions optional. 320 | (typename $opt_options (variant (@witx tag $opt_options_u) (case $some $options) (case $none))) 321 | 322 | ;;; Symmetric key index, only required by the Interface Types translation layer. 323 | (typename $opt_symmetric_key_u (enum (@witx tag u8) $some $none)) 324 | 325 | ;;; An optional symmetric key. 326 | ;;; 327 | ;;; This union simulates an `Option` type to make the `symmetric_key` parameter of some functions optional. 328 | (typename $opt_symmetric_key (variant (@witx tag $opt_symmetric_key_u) (case $some $symmetric_key) (case $none))) 329 | 330 | (module $wasi_ephemeral_crypto_common 331 | (import "memory" (memory)) 332 | 333 | ;;; Create a new object to set non-default options. 334 | ;;; 335 | ;;; Example usage: 336 | ;;; 337 | ;;; ```rust 338 | ;;; let options_handle = options_open(AlgorithmType::Symmetric)?; 339 | ;;; options_set(options_handle, "context", context)?; 340 | ;;; options_set_u64(options_handle, "threads", 4)?; 341 | ;;; let state = symmetric_state_open("BLAKE3", None, Some(options_handle))?; 342 | ;;; options_close(options_handle)?; 343 | ;;; ``` 344 | (@interface func (export "options_open") 345 | (param $algorithm_type $algorithm_type) 346 | (result $error (expected $options (error $crypto_errno))) 347 | ) 348 | 349 | ;;; Destroy an options object. 350 | ;;; 351 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 352 | (@interface func (export "options_close") 353 | (param $handle $options) 354 | (result $error (expected (error $crypto_errno))) 355 | ) 356 | 357 | ;;; Set or update an option. 358 | ;;; 359 | ;;; This is used to set algorithm-specific parameters, but also to provide credentials for the secrets management facilities, if required. 360 | ;;; 361 | ;;; This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. 362 | (@interface func (export "options_set") 363 | (param $handle $options) 364 | (param $name string) 365 | (param $value (@witx const_pointer u8)) 366 | (param $value_len $size) 367 | (result $error (expected (error $crypto_errno))) 368 | ) 369 | 370 | ;;; Set or update an integer option. 371 | ;;; 372 | ;;; This is used to set algorithm-specific parameters. 373 | ;;; 374 | ;;; This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. 375 | (@interface func (export "options_set_u64") 376 | (param $handle $options) 377 | (param $name string) 378 | (param $value u64) 379 | (result $error (expected (error $crypto_errno))) 380 | ) 381 | 382 | ;;; Set or update a guest-allocated memory that the host can use or return data into. 383 | ;;; 384 | ;;; This is for example used to set the scratch buffer required by memory-hard functions. 385 | ;;; 386 | ;;; This function may return `unsupported_option` if an option that doesn't exist for any implemented algorithms is specified. 387 | (@interface func (export "options_set_guest_buffer") 388 | (param $handle $options) 389 | (param $name string) 390 | (param $buffer (@witx pointer u8)) 391 | (param $buffer_len $size) 392 | (result $error (expected (error $crypto_errno))) 393 | ) 394 | 395 | ;;; Return the length of an `array_output` object. 396 | ;;; 397 | ;;; 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. 398 | (@interface func (export "array_output_len") 399 | (param $array_output $array_output) 400 | (result $error (expected $size (error $crypto_errno))) 401 | ) 402 | 403 | ;;; Copy the content of an `array_output` object into an application-allocated buffer. 404 | ;;; 405 | ;;; Multiple calls to that function can be made in order to consume the data in a streaming fashion, if necessary. 406 | ;;; 407 | ;;; 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()`. 408 | ;;; 409 | ;;; The handle is automatically closed after all the data has been consumed. 410 | ;;; 411 | ;;; Example usage: 412 | ;;; 413 | ;;; ```rust 414 | ;;; let len = array_output_len(output_handle)?; 415 | ;;; let mut out = vec![0u8; len]; 416 | ;;; array_output_pull(output_handle, &mut out)?; 417 | ;;; ``` 418 | (@interface func (export "array_output_pull") 419 | (param $array_output $array_output) 420 | (param $buf (@witx pointer u8)) 421 | (param $buf_len $size) 422 | (result $error (expected $size (error $crypto_errno))) 423 | ) 424 | 425 | ;;; __(optional)__ 426 | ;;; Create a context to use a secrets manager. 427 | ;;; 428 | ;;; The set of required and supported options is defined by the host. 429 | ;;; 430 | ;;; The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. 431 | ;;; This is also an optional import, meaning that the function may not even exist. 432 | (@interface func (export "secrets_manager_open") 433 | (param $options $opt_options) 434 | (result $error (expected $secrets_manager (error $crypto_errno))) 435 | ) 436 | 437 | ;;; __(optional)__ 438 | ;;; Destroy a secrets manager context. 439 | ;;; 440 | ;;; The function returns the `unsupported_feature` error code if secrets management facilities are not supported by the host. 441 | ;;; This is also an optional import, meaning that the function may not even exist. 442 | (@interface func (export "secrets_manager_close") 443 | (param $secrets_manager $secrets_manager) 444 | (result $error (expected (error $crypto_errno))) 445 | ) 446 | 447 | ;;; __(optional)__ 448 | ;;; Invalidate a managed key or key pair given an identifier and a version. 449 | ;;; 450 | ;;; This asks the secrets manager to delete or revoke a stored key, a specific version of a key. 451 | ;;; 452 | ;;; `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. 453 | ;;; 454 | ;;; 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. 455 | ;;; 456 | ;;; This is an optional import, meaning that the function may not even exist. 457 | (@interface func (export "secrets_manager_invalidate") 458 | (param $secrets_manager $secrets_manager) 459 | (param $key_id (@witx const_pointer u8)) 460 | (param $key_id_len $size) 461 | (param $key_version $version) 462 | (result $error (expected (error $crypto_errno))) 463 | ) 464 | ) 465 | 466 | (typename $u64 u64) 467 | -------------------------------------------------------------------------------- /witx/witx-0.9/proposal_external_secrets.witx: -------------------------------------------------------------------------------- 1 | (use "proposal_common.witx") 2 | 3 | ;;; External secrets storage. 4 | ;;; 5 | ;;; 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. 6 | ;;; These secrets can be securely stored, and then retrieved using an identifier. 7 | ;;; 8 | ;;; Alternatively, the secrets manager can encrypt them, and applications will supply the ciphertext get the original secret back. 9 | ;;; 10 | ;;; The whole module is optional. 11 | ;;; 12 | ;;; __(optional)__ 13 | (module $wasi_ephemeral_crypto_exernal_secrets 14 | (import "memory" (memory)) 15 | 16 | ;;; Store an external secret into the secrets manager. 17 | ;;; 18 | ;;; `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. 19 | ;;; An expiration date is mandatory. 20 | ;;; 21 | ;;; On success, the secret identifier is put into `$secret_id` if it fits into `$secret_id_max_len` bytes. 22 | ;;; If the supplied ouptut buffer is too small, `$overflow` is returned. 23 | ;;; 24 | ;;; If this function is not supported by the host the `$unsupported_feature` error is returned. 25 | (@interface func (export "external_secret_store") 26 | (param $secrets_manager $secrets_manager) 27 | (param $secret (@witx const_pointer u8)) 28 | (param $secret_len $size) 29 | (param $expiration $timestamp) 30 | (param $secret_id (@witx pointer u8)) 31 | (param $secret_id_max_len $size) 32 | (result $error (expected (error $crypto_errno))) 33 | ) 34 | 35 | ;;; Replace a managed external with a new version. 36 | ;;; 37 | ;;; `$expiration` is the expiration date of the secret as a UNIX timestamp, in seconds. 38 | ;;; An expiration date is mandatory. 39 | ;;; 40 | ;;; On success, a new version is created and returned. 41 | ;;; 42 | ;;; If this function is not supported by the host the `$unsupported_feature` error is returned. 43 | (@interface func (export "external_secret_replace") 44 | (param $secrets_manager $secrets_manager) 45 | (param $secret (@witx const_pointer u8)) 46 | (param $secret_len $size) 47 | (param $expiration $timestamp) 48 | (param $secret_id (@witx const_pointer u8)) 49 | (param $secret_id_len $size) 50 | (result $error (expected $version (error $crypto_errno))) 51 | ) 52 | 53 | ;;; Get a copy of an external secret given an identifier and version. 54 | ;;; 55 | ;;; `secret_version` can be set to a version number, or to `version.latest` to retrieve the most recent version of a secret. 56 | ;;; 57 | ;;; On success, a copy of the secret is returned. 58 | ;;; 59 | ;;; 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. 60 | (@interface func (export "external_secret_from_id") 61 | (param $secrets_manager $secrets_manager) 62 | (param $secret_id (@witx const_pointer u8)) 63 | (param $secret_id_len $size) 64 | (param $secret_version $version) 65 | (result $error (expected $array_output (error $crypto_errno))) 66 | ) 67 | 68 | ;;; Invalidate an external secret given an identifier and a version. 69 | ;;; 70 | ;;; This asks the secrets manager to delete or revoke a stored secret, a specific version of a secret. 71 | ;;; 72 | ;;; `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. 73 | ;;; 74 | ;;; 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. 75 | (@interface func (export "external_secret_invalidate") 76 | (param $secrets_manager $secrets_manager) 77 | (param $secret_id (@witx const_pointer u8)) 78 | (param $secret_id_len $size) 79 | (param $secret_version $version) 80 | (result $error (expected (error $crypto_errno))) 81 | ) 82 | 83 | ;;; Encrypt an external secret. 84 | ;;; 85 | ;;; Applications don't have access to the encryption key, and the secrets manager is free to choose any suitable algorithm. 86 | ;;; 87 | ;;; However, the returned ciphertext must include and authenticate both the secret and the expiration date. 88 | ;;; 89 | ;;; On success, the ciphertext is returned. 90 | (@interface func (export "external_secret_encapsulate") 91 | (param $secrets_manager $secrets_manager) 92 | (param $secret (@witx const_pointer u8)) 93 | (param $secret_len $size) 94 | (param $expiration $timestamp) 95 | (result $error (expected $array_output (error $crypto_errno))) 96 | ) 97 | 98 | ;;; Decrypt an external secret previously encrypted by the secrets manager. 99 | ;;; 100 | ;;; Returns the original secret if the ciphertext is valid. 101 | ;;; Returns `$expired` if the current date is past the stored expiration date. 102 | ;;; Returns `$verification_failed` if the ciphertext format is invalid or if its authentication tag couldn't be verified. 103 | (@interface func (export "external_secret_decapsulate") 104 | (param $secrets_manager $secrets_manager) 105 | (param $encrypted_secret (@witx const_pointer u8)) 106 | (param $encrypted_secret_len $size) 107 | (result $error (expected $array_output (error $crypto_errno))) 108 | ) 109 | ) 110 | -------------------------------------------------------------------------------- /witx/witx-0.9/proposal_kx.witx: -------------------------------------------------------------------------------- 1 | (use "proposal_common.witx") 2 | 3 | ;;; `$kx_keypair` is just an alias for `$keypair` 4 | ;;; 5 | ;;; However, bindings may want to define a specialized type `kx_keypair` as a super class of `keypair`. 6 | (typename $kx_keypair $keypair) 7 | 8 | ;;; `$kx_publickey` is just an alias for `$publickey` 9 | ;;; 10 | ;;; However, bindings may want to define a specialized type `kx_publickey` as a super class of `publickey`, with additional methods such as `dh`. 11 | (typename $kx_publickey $publickey) 12 | 13 | ;;; `$kx_secretkey` is just an alias for `$secretkey` 14 | ;;; 15 | ;;; However, bindings may want to define a specialized type `kx_secretkey` as a super class of `secretkeykey`, with additional methods such as `dh`. 16 | (typename $kx_secretkey $secretkey) 17 | 18 | ;;; Key exchange operations. 19 | 20 | (module $wasi_ephemeral_crypto_kx 21 | (import "memory" (memory)) 22 | 23 | ;;; Perform a simple Diffie-Hellman key exchange. 24 | ;;; 25 | ;;; Both keys must be of the same type, or else the `$crypto_errno.incompatible_keys` error is returned. 26 | ;;; 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. 27 | ;;; 28 | ;;; Otherwide, a raw shared key is returned, and can be imported as a symmetric key. 29 | ;;; ``` 30 | (@interface func (export "kx_dh") 31 | (param $pk $publickey) 32 | (param $sk $secretkey) 33 | (result $error (expected $array_output (error $crypto_errno))) 34 | ) 35 | 36 | ;;; Create a shared secret and encrypt it for the given public key. 37 | ;;; 38 | ;;; This operation is only compatible with specific algorithms. 39 | ;;; If a selected algorithm doesn't support it, `$crypto_errno.invalid_operation` is returned. 40 | ;;; 41 | ;;; On success, both the shared secret and its encrypted version are returned. 42 | (@interface func (export "kx_encapsulate") 43 | (param $pk $publickey) 44 | (result $error (expected (tuple $array_output $array_output) (error $crypto_errno))) 45 | ) 46 | 47 | ;;; Decapsulate an encapsulated secret crated with `kx_encapsulate` 48 | ;;; 49 | ;;; Return the secret, or `$crypto_errno.verification_failed` on error. 50 | (@interface func (export "kx_decapsulate") 51 | (param $sk $secretkey) 52 | (param $encapsulated_secret (@witx const_pointer u8)) 53 | (param $encapsulated_secret_len $size) 54 | (result $error (expected $array_output (error $crypto_errno))) 55 | ) 56 | ) 57 | -------------------------------------------------------------------------------- /witx/witx-0.9/proposal_signatures.witx: -------------------------------------------------------------------------------- 1 | (use "proposal_asymmetric_common.witx") 2 | 3 | ;;; `$signature_keypair` is just an alias for `$keypair` 4 | ;;; 5 | ;;; However, bindings may want to define a specialized type `signature_keypair` as a super class of `keypair`, with additional methods such as `sign`. 6 | (typename $signature_keypair $keypair) 7 | 8 | ;;; `$signature_publickey` is just an alias for `$publickey` 9 | ;;; 10 | ;;; However, bindings may want to define a specialized type `signature_publickey` as a super class of `publickey`, with additional methods such as `verify`. 11 | (typename $signature_publickey $publickey) 12 | 13 | ;;; `$signature_secretkey` is just an alias for `$secretkey` 14 | ;;; 15 | ;;; However, bindings may want to define a specialized type `signature_secretkey` as a super class of `secretkey`. 16 | (typename $signature_secretkey $secretkey) 17 | 18 | ;;; Digital signatures. 19 | 20 | (module $wasi_ephemeral_crypto_signatures 21 | (import "memory" (memory)) 22 | 23 | ;;; Export a signature. 24 | ;;; 25 | ;;; This function exports a signature object using the specified encoding. 26 | ;;; 27 | ;;; May return `unsupported_encoding` if the signature cannot be encoded into the given format. 28 | (@interface func (export "signature_export") 29 | (param $signature $signature) 30 | (param $encoding $signature_encoding) 31 | (result $error (expected $array_output (error $crypto_errno))) 32 | ) 33 | 34 | ;;; Create a signature object. 35 | ;;; 36 | ;;; This object can be used along with a public key to verify an existing signature. 37 | ;;; 38 | ;;; 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. 39 | ;;; 40 | ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host. 41 | ;;; 42 | ;;; Example usage: 43 | ;;; 44 | ;;; ```rust 45 | ;;; let signature_handle = ctx.signature_import("ECDSA_P256_SHA256", SignatureEncoding::DER, encoded)?; 46 | ;;; ``` 47 | (@interface func (export "signature_import") 48 | (param $algorithm string) 49 | (param $encoded (@witx const_pointer u8)) 50 | (param $encoded_len $size) 51 | (param $encoding $signature_encoding) 52 | (result $error (expected $signature (error $crypto_errno))) 53 | ) 54 | 55 | ;;; Create a new state to collect data to compute a signature on. 56 | ;;; 57 | ;;; This function allows data to be signed to be supplied in a streaming fashion. 58 | ;;; 59 | ;;; 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. 60 | ;;; 61 | ;;; Example usage - signature creation 62 | ;;; 63 | ;;; ```rust 64 | ;;; let kp_handle = ctx.keypair_import(AlgorithmType::Signatures, "Ed25519ph", keypair, KeypairEncoding::Raw)?; 65 | ;;; let state_handle = ctx.signature_state_open(kp_handle)?; 66 | ;;; ctx.signature_state_update(state_handle, b"message part 1")?; 67 | ;;; ctx.signature_state_update(state_handle, b"message part 2")?; 68 | ;;; let sig_handle = ctx.signature_state_sign(state_handle)?; 69 | ;;; let raw_sig = ctx.signature_export(sig_handle, SignatureEncoding::Raw)?; 70 | ;;; ``` 71 | (@interface func (export "signature_state_open") 72 | (param $kp $signature_keypair) 73 | (result $error (expected $signature_state (error $crypto_errno))) 74 | ) 75 | 76 | ;;; Absorb data into the signature state. 77 | ;;; 78 | ;;; This function may return `unsupported_feature` is the selected algorithm doesn't support incremental updates. 79 | (@interface func (export "signature_state_update") 80 | (param $state $signature_state) 81 | (param $input (@witx const_pointer u8)) 82 | (param $input_len $size) 83 | (result $error (expected (error $crypto_errno))) 84 | ) 85 | 86 | ;;; Compute a signature for all the data collected up to that point. 87 | ;;; 88 | ;;; The function can be called multiple times for incremental signing. 89 | (@interface func (export "signature_state_sign") 90 | (param $state $signature_state) 91 | (result $error (expected $array_output (error $crypto_errno))) 92 | ) 93 | 94 | ;;; Destroy a signature state. 95 | ;;; 96 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 97 | ;;; 98 | ;;; Note that closing a signature state doesn't close or invalidate the key pair object, that be reused for further signatures. 99 | (@interface func (export "signature_state_close") 100 | (param $state $signature_state) 101 | (result $error (expected (error $crypto_errno))) 102 | ) 103 | 104 | ;;; Create a new state to collect data to verify a signature on. 105 | ;;; 106 | ;;; This is the verification counterpart of `signature_state`. 107 | ;;; 108 | ;;; Data can be injected using `signature_verification_state_update()`, and the state is not closed after a verification, allowing incremental verification. 109 | ;;; 110 | ;;; Example usage - signature verification: 111 | ;;; 112 | ;;; ```rust 113 | ;;; let pk_handle = ctx.publickey_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_pk, PublicKeyEncoding::Sec)?; 114 | ;;; let signature_handle = ctx.signature_import(AlgorithmType::Signatures, "ECDSA_P256_SHA256", encoded_sig, SignatureEncoding::Der)?; 115 | ;;; let state_handle = ctx.signature_verification_state_open(pk_handle)?; 116 | ;;; ctx.signature_verification_state_update(state_handle, "message")?; 117 | ;;; ctx.signature_verification_state_verify(signature_handle)?; 118 | ;;; ``` 119 | (@interface func (export "signature_verification_state_open") 120 | (param $kp $signature_publickey) 121 | (result $error (expected $signature_verification_state (error $crypto_errno))) 122 | ) 123 | 124 | ;;; Absorb data into the signature verification state. 125 | ;;; 126 | ;;; This function may return `unsupported_feature` is the selected algorithm doesn't support incremental updates. 127 | (@interface func (export "signature_verification_state_update") 128 | (param $state $signature_verification_state) 129 | (param $input (@witx const_pointer u8)) 130 | (param $input_len $size) 131 | (result $error (expected (error $crypto_errno))) 132 | ) 133 | 134 | ;;; Check that the given signature is verifies for the data collected up to that point point. 135 | ;;; 136 | ;;; The state is not closed and can absorb more data to allow for incremental verification. 137 | ;;; 138 | ;;; The function returns `invalid_signature` if the signature doesn't appear to be valid. 139 | (@interface func (export "signature_verification_state_verify") 140 | (param $state $signature_verification_state) 141 | (param $signature $signature) 142 | (result $error (expected (error $crypto_errno))) 143 | ) 144 | 145 | ;;; Destroy a signature verification state. 146 | ;;; 147 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 148 | ;;; 149 | ;;; Note that closing a signature state doesn't close or invalidate the public key object, that be reused for further verifications. 150 | (@interface func (export "signature_verification_state_close") 151 | (param $state $signature_verification_state) 152 | (result $error (expected (error $crypto_errno))) 153 | ) 154 | 155 | ;;; Destroy a signature. 156 | ;;; 157 | ;;; Objects are reference counted. It is safe to close an object immediately after the last function needing it is called. 158 | (@interface func (export "signature_close") 159 | (param $signature $signature) 160 | (result $error (expected (error $crypto_errno))) 161 | ) 162 | ) 163 | -------------------------------------------------------------------------------- /witx/witx-0.9/wasi_ephemeral_crypto.witx: -------------------------------------------------------------------------------- 1 | ;;; A WASI cryptography submodule proposal. 2 | 3 | (use "proposal_signatures.witx") 4 | (use "proposal_symmetric.witx") 5 | (use "proposal_kx.witx") 6 | --------------------------------------------------------------------------------