• Stars
    star
    134
  • Rank 269,239 (Top 6 %)
  • Language
    Rust
  • License
    MIT License
  • Created over 4 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

WITX code and documentation generator for AssemblyScript, Zig, Rust and more.

WITX code generator

CI status crates.io

WITX-CodeGen: A WITX code and documentation generator

WITX is a way to describe types and function interfaces for WebAssembly modules.

From this, code generators can produce code to access data, call or implement functions from different languages using the same layout and calling conventions.

WITX-CodeGen doesn't do transformations when functions are called. Instead, it exposes types that have the same layout in all languages, like a zero-copy serialization format. Data can thus be easily shared between guests and hosts without any overhead.

The generated code is compatible with the WebAssembly standard APIs (WASI).

This tool uses the next (as on June 9th, 2021) revision of the format definition, that will eventually be required for interface types.

witx-codegen is currently written in Rust, but it is totally language-agnostic. It is also compatible with all WebAssembly runtimes. The generated code is optimized for simplicity and readability.

The tool can also produce different documentation formats.

witx-codegen supersedes as-witx, zig-witx, witx-docgen, witx-overview-docgen and witx-generate-raw.

Installation

  • Via cargo:
cargo install witx-codegen
  • Precompiled binaries: tarballs and Debian/Ubuntu packages are available here.

Usage

WITX code generator for WebAssembly guest modules

USAGE:
    witx-codegen [FLAGS] [OPTIONS] <witx_files>...

FLAGS:
    -h, --help            Prints help information
    -H, --skip-header     Do not generate a header
    -I, --skip-imports    Ignores imported types and functions
    -V, --version         Prints version information

OPTIONS:
    -m, --module-name <module_name>
            Set the module name to use instead of reading it from the witx file

    -o, --output <output_file>         Output file, or - for the standard output
    -t, --output-type <output_type>
            Output type. One in: {assemblyscript, zig, rust, overview, markdown}
            [default: assemblyscript]

ARGS:
    <witx_files>...    WITX files

Backends

Support for additional languages is more than welcome!

Example inputs

See the tests folder for examples of WITX input files.

Other input formats may also be eventually supported, as well as extensions to produce more structured documentation.

WITX format

Basic types

bool, char, u8, u16, u32, u64, s8, s16, s32, s64

Other types

  • string: a read-only string.
  • (in-buffer u8): a read-only buffer whose elements are of type u8.
  • (out-buffer u8): a buffer whose elements are of type u8.
  • (@witx const_pointer u8): a read-only u8 pointer.
  • (@witx pointer u8): a u8 pointer.
  • (@witx usize): an object size.

Type aliases

  • (typename $status_code u16)
  • (typename $size (@witx usize))

Note that returned values from function must all be aliases, not raw types.

Handles

Handles are opaque references to objects managed by the host.

In order to use handles, a "resource" has to be declared:

(resource $http_handle)

A "resource" represent a group of handles. The same resource can be shared by all handle types from the same module.

Each handle type can then be declared as aliases:

(typename $query (handle $http_handle))
(typename $response_handle (handle $http_handle))

Constants

(typename $big_int u64)
(@witx const $big_int $zero 0)
(@witx const $big_int $a_hundred 100)
(@witx const $big_int $a_big_value 0xff00000000000000)
(@witx const $big_int $a_bigger_value 0xffffffffffffffff)

Structures

(typename $example_structure
  (record
    (field $first_member bool)
    (field $second_member u8)
    (field $third_member string)
  )
)

Structures that only contain booleans are encoded as bit sets.

Tuples

(typename $test_tuple (tuple $test_bool $test_medium_int $big_int))

Tagged unions

(typename $test_tagged_union
  (variant (@witx tag u16)
    (case $first_choice u8)
    (case $second_choice string)
    (case $third_choice f32)
    (case $empty_choice)
  )
)

This defines a union with a tag representing the active member. The example above generates a structure equivalent to:

struct {
    tag: u16,
    member: union {
        first_choice: u8,
        second_choice: string,
        third_choice: f32,
        empty_choice: (),
    }
}

Imports

Import some aliases, or all of them, from common.witx:

(use $some_type, $some_other_type from $common)
(use * from $common)

Modules

Only one module can be present in a file, whose name must match the module name. A module is defined as follows:

(module $module_name
...
)

It contains everything: types, handles, functions and imports.

Functions

(@interface func (export "symmetric_key_generate")
 (param $algorithm string)
 (param $options $opt_options)
 (result $error (expected $symmetric_key (error $crypto_errno)))
)

This declares a symmetric_key_generate function, with two input parameters (algorithm and options of type string and opt_options).

The function returns an error code of type $crypto_errno. Or, if no error occurred, the function returns a value of type $symmetric_key.

In Rust, an equivalent function would be:

fn symmetric_key_generate(algorithm: &str, options: OptOptions)
  -> Result<SymmetricKey, CryptoErrno>;

Returning multiple values:

(@interface func (export "symmetric_key_id")
  (param $key $symmetric_key)
  (param $key_id (@witx pointer u8))
  (param $key_id_max_len $size)
  (result $error (expected (tuple $size $version) (error $crypto_errno)))
)

The function returns either an error, or two values, of type $size and $version.

The above example is eauivalent to a declaration like that one in Rust:

fn symmetric_key_id(key: SymmetricKey, key_id: *mut u8, key_id_max_len: usize)
  -> Result<(Size, Version), CryptoErrno>;

More Repositories

1

libsodium

A modern, portable, easy to use crypto library.
C
12,131
star
2

dsvpn

A Dead Simple VPN.
C
5,068
star
3

piknik

Copy/paste anything over the network.
Go
2,342
star
4

minisign

A dead simple tool to sign files and verify digital signatures.
C
1,856
star
5

libsodium.js

libsodium compiled to Webassembly and pure JavaScript, with convenient wrappers.
HTML
899
star
6

libhydrogen

A lightweight, secure, easy-to-use crypto library suitable for constrained environments.
C
599
star
7

pure-ftpd

Pure FTP server
C
589
star
8

libsodium-php

The PHP extension for libsodium.
C
546
star
9

swift-sodium

Safe and easy to use crypto for iOS and macOS
C
510
star
10

edgedns

A high performance DNS cache designed for Content Delivery Networks
Rust
490
star
11

libpuzzle

A library to quickly find visually similar images
C
262
star
12

iptoasn-webservice

Web service to map IP addresses to AS information, using iptoasn.com
Rust
254
star
13

dnsblast

A simple and stupid load testing tool for DNS resolvers
C
233
star
14

as-wasi

An AssemblyScript API layer for WASI system calls.
TypeScript
232
star
15

rust-jwt-simple

A secure, standard-conformant, easy to use JWT implementation for Rust.
Rust
222
star
16

wasm-crypto

A WebAssembly (via AssemblyScript) set of cryptographic primitives for building authentication and key exchange protocols.
TypeScript
214
star
17

rust-bloom-filter

A fast Bloom filter implementation in Rust
Rust
187
star
18

encpipe

The dum^H^H^Hsimplest encryption tool in the world.
C
182
star
19

Pincaster

A fast persistent nosql database with a HTTP/JSON interface, not only for geographical data.
C
171
star
20

blacknurse

BlackNurse attack PoC
C
170
star
21

UCarp

UCARP allows a couple of hosts to share common virtual IP addresses in order to provide automatic failover. It is a portable userland implementation of the secure and patent-free Common Address Redundancy Protocol (CARP, OpenBSD's alternative to the patents-bloated VRRP).
M4
167
star
22

libsodium-doc

Gitbook documentation for libsodium
Shell
166
star
23

bitbar-dnscrypt-proxy-switcher

BitBar plugin to control dnscrypt-proxy usage
Shell
148
star
24

charm

A really tiny crypto library.
C
148
star
25

siphash-js

A Javascript implementation of SipHash-2-4
JavaScript
122
star
26

rust-ed25519-compact

Small, wasm-friendly, zero-dependencies Ed25519 and X25519 implementation for Rust.
Rust
120
star
27

rsign2

A command-line tool to sign files and verify signatures in pure Rust.
Rust
112
star
28

go-minisign

Minisign verification library for Golang.
Go
103
star
29

rust-nats

A simple NATS client library for Rust
Rust
102
star
30

zigly

The easiest way to write services for Fastly's Compute@Edge in Zig.
Zig
84
star
31

was-not-wasm

A hostile memory allocator to make WebAssembly applications more predictable.
Rust
81
star
32

webassembly-benchmarks

Libsodium WebAssembly benchmarks results.
79
star
33

rust-minisign

A pure Rust implementation of the Minisign signature tool.
Rust
78
star
34

zig-charm

A Zig version of the Charm crypto library.
Zig
74
star
35

rust-ffmpeg-wasi

ffmpeg 7 libraries precompiled for WebAsembly/WASI, as a Rust crate.
Rust
67
star
36

openssl-wasm

OpenSSL 3 compiled for WebAssembly/WASI (up-to-date, maintained)
C
66
star
37

rust-sthash

Very fast cryptographic hashing for large messages.
Rust
65
star
38

vtun

A mirror of VTUN, with some changes
C
63
star
39

iptrap

A simple, but damn fast sinkhole
Rust
62
star
40

boringssl-wasm

BoringSSL for WebAssembly/WASI
Zig
59
star
41

libsodium-signcryption

Signcryption using libsodium.
C
59
star
42

wasmsign

A tool to add and verify digital signatures to/from WASM binaries
Rust
56
star
43

libaegis

Portable C implementations of the AEGIS family of high-performance authenticated encryption algorithms.
C
56
star
44

blobcrypt

Authenticated encryption for streams and arbitrary large files using libsodium
C
54
star
45

rust-coarsetime

Time and duration crate optimized for speed
Rust
52
star
46

zig-minisign

Minisign reimplemented in Zig.
Zig
50
star
47

rust-siphash

SipHash (2-4, 1-3 + 128 bit variant) implementations for Rust
Rust
48
star
48

6Jack

A framework for analyzing/testing/fuzzing network applications.
C
46
star
49

rust-hyperloglog

A HyperLogLog implementation in Rust.
Rust
46
star
50

libchloride

Networking layer for libsodium, based on CurveCP
C
44
star
51

rust-qptrie

A qp-trie implementation in Rust
Rust
42
star
52

minicsv

A tiny, fast, simple, single-file, BSD-licensed CSV parsing library in C.
C
39
star
53

spake2-ee

A SPAKE2+ Elligator Edition implementation for libsodium 1.0.16+
C
36
star
54

massresolver

Mass DNS resolution tool
C
36
star
55

cpace

A CPace PAKE implementation using libsodium.
C
35
star
56

aegis-X

The AEGIS-128X and AEGIS-256X high performance ciphers.
Zig
34
star
57

rust-privdrop

A simple Rust crate to drop privileges
Rust
34
star
58

PureDB

PureDB is a portable and tiny set of libraries for creating and reading constant databases.
C
33
star
59

libclang_rt.builtins-wasm32.a

The missing libclang_rt.builtins-wasm32.a file to compile to WebAssembly.
32
star
60

c-ipcrypt

ipcrypt implementation in C
C
31
star
61

rust-dnsclient

A simple and secure DNS client crate for Rust.
Rust
29
star
62

rust-xoodyak

Xoodyak, a lightweight and versatile cryptographic scheme implemented in Rust.
Rust
29
star
63

fastly-terrarium-examples

Example code you can run in Fastly Terrarium: https://www.fastlylabs.com/
C
28
star
64

libsodium-xchacha20-siv

Deterministic/nonce-reuse resistant authenticated encryption scheme using XChaCha20, implemented on libsodium.
C
28
star
65

rust-geoip

GeoIP bindings for Rust
Rust
28
star
66

rust-minisign-verify

A small Rust crate to verify Minisign signatures.
Rust
27
star
67

whatsmyresolver

A tiny DNS server that returns the client (resolver) IP
Go
26
star
68

libsodium-sys-stable

Sodiumoxide's libsodium-sys crate, but that installs stable versions of libsodium.
Rust
26
star
69

spritz

A C implementation of Spritz, a spongy RC4-like stream cipher and hash function.
C
25
star
70

metrohash-c

C version of the MetroHash function
C
25
star
71

rust-hmac-sha256

A small, self-contained SHA256 and HMAC-SHA256 implementation.
Rust
25
star
72

rust-cpace

A Rust implementation of CPace, a balanced PAKE.
Rust
25
star
73

rust-clockpro-cache

CLOCK-Pro cache replacement algorithm for Rust
Rust
24
star
74

rust-blind-rsa-signatures

RSA blind signatures in Rust
Rust
24
star
75

PHP-OAuth2-Provider

Skyrock OAuth2 server
PHP
23
star
76

rust-aegis

AEGIS high performance ciphers for Rust.
Rust
23
star
77

openssl-family-bench

A quick benchmark of {Open,Libre,Boring}SSL
C
23
star
78

system-tuning-for-crypto

System tuning recommendations for running cryptographic applications
23
star
79

hashseq

A simple proof of work, mainly designed to mitigate DDoS attacks.
C
23
star
80

dnssector

A DNS library for Rust.
Rust
23
star
81

randen-rng

A port of the Google Randen fast backtracking-resistant random generator to the C language.
C
21
star
82

Blogbench

A filesystem benchmark tool that simulates a realistic load
C
21
star
83

vue-dnsstamp

DNS Stamp calculator component for VueJS
Vue
21
star
84

supercop

Always up-to-date mirror of the SUPERCOP cryptographic benchmark.
C
21
star
85

yaifo

YAIFO [remote OpenBSD installer] for OpenBSD-current
Shell
21
star
86

ratelimit

Plug-and-play IP rate limiter in C
C
21
star
87

draft-aegis-aead

The AEGIS cipher family - Draft.
20
star
88

go-hpke-compact

A small and easy to use HPKE implementation in Go.
Go
20
star
89

ipgrep

Extract, defang, resolve names and IPs from text
Python
20
star
90

zig-rocca-s

An implementation of the ROCCA-S encryption scheme.
Zig
19
star
91

Simple-Comet-Server

HTTP long-polling server and javascript client library.
Python
19
star
92

simpira384

An AES-based 384 bit permutation.
C
18
star
93

PHP-WebDAV-extension

The PHP WebDAV extension allows easy access to remote resources with PHP through the DAV protocol.
Shell
18
star
94

nonce-extension

Make AES-GCM safe to use with random nonces, for any practical number of messages.
Rust
17
star
95

rust-sealed_box

Sealed boxes implementation for Rust/WebAssembly.
Rust
16
star
96

zig-eddsa-key-blinding

A Zig implementation of EdDSA signatures with blind keys.
Zig
16
star
97

c-blind-rsa-signatures

Blind RSA signatures for OpenSSL/BoringSSL.
C
16
star
98

aes-torture

A software AES implementation to torture code generators.
C
16
star
99

js-base64-ct

Safe Base64 encoding/decoding in pure JavaScript.
TypeScript
16
star
100

rust-aes-wasm

Fast(er) AES-based constructions for WebAssembly and Rust.
Rust
16
star