# WebAssembly Module Signature

This repository describing the design and high-level overview of the WebAssembly Module Signature (WAMS)

## Overview

The WebAssembly Module Signature shall proof authenticity and integrity of the WebAssembly module, as file or parsed.

## Requirements

The WebAssembly Module Signature shall provide the following features

- It shall be possible to sign a WebAssembly Module file without parsing
- The signature signs the serialized, binary form of data in rest and data in transit.
- A module shall be signed as is, completely, including all custom-sections.
- The module sections shall not be re-ordered to meet a canonical form.
- All module signatures shall have equal byte-size.
- It shall be possible to verify a signature without parsing of the module
- It shall be possible with simple tools to split a WebAssembly module into both parts, the signature and the signed content
- Signatures shall use the ECDSA algorithm with SHA256.
- The public key may be publicly available and may be distributed using DNS-TXT-Records.

## Proposal

- The WebAssembly module signature is a Custom-Section with type id 0, the section name must be formed by 9 characters, so all signatures have equal byte-size
- A module shall contain just one signature (may be extended in future)
- A signature signs all sections of the module, as is.
- The custom-section with name "signature" (9 chars) is the default signature.
- The payload of the custom-section contains the ECDSA signature; the complete section has octet-size 118.
- New signature-sections shall be appended to the end of a module only.
- Removing the last 118 bytes from a module-bytecode, the signature-section is cut off.
- The tool shall support secp256k1 in initial version and in future versions Ed25519 and secp384r1 (hence the reserved bytes at end)


Each signature section ist formed of a sequence of 118 octets:

Fields                   |         Bytes
------------------------ | ----------------------------------------------------------------------------- 
Section Type (Custom):   |   `0`
Section Size:            |   `116`
Section Name Length:     |   `9`
Section Name Octets [9]: |   `[115, 105, 103, 110, 97, 116, 117, 114, 101]` (read as  "signature")
Signature Type   :       |   `0` which stands for ECDSA/SHA256 with max digest length of max. 72 bytes
Signature length:        |   Single byte value 72 or less
Signature:               |   `[...]`
Padding bytes:           |   0..33 padding bytes filling extending the digest-length to up to 104 bytes (secp384r1)

The signature is always attached to the end of a WASM-file. If receiving a signed WASM-file, the last 118 characters can be cut off to get the WASM-Signature section. The following indeces permit verification of the signature using  command line tools or Javascript, without the need to parse the WASM-module-bytecodes:

- **Index 0..11** Fixed byte-sequence `[0, 116, 9, 115, 105, 103, 110, 97, 116, 117, 114, 101]`
- **Index 12** SIGNATURE_TYPE (the only valid value is '0' for curve secp256k1/SHA256 for now)
- **Index 13** DIGEST_DATA_LENGTH, may range between 65..104 (if using secp256k1 usually a value of 70 or 71 or 72)
- **Index 14** DIGEST_DATA_START, first byte of digest
- **Index 14+DIGEST_DATA_LENGTH**, end of the digest
 
In case the digest has byte size 72 (secp256k1) the preamble looks like (followed by the ECDSA digest):
```
[0, 116, 9, 115, 105, 103, 110, 97, 116, 117, 114, 101, 0, 72 ]
```

The digest is calculated using ciphers secp256k1/SHA256.
Trailing padding bytes fill up to total length of 118 bytes.

## Usage

### Private Key Generation
This is the key that must be kept secret and is used to sign your WASM files.
```
openssl ecparam -name secp256k1 -genkey -noout -out signerkey.pem
```

### Public Key Generation
This is the key that should be published or embedded in your application.
```
openssl ec -in signerkey.pem -pubout -outform pem -out signerkey.pub.pem
```

### Signing the WASM file
The command line tool returns with exit code 0 on success, otherwise with error code 1
```
wasm-sign -k signerkey.pem module.wasm signed-module.wasm
```

### Verifying the WASM file
The command line tool returns with exit code 0 on success, otherwise with error code 1
```
wasm-sign -v -k signerkey.pub.pem signed-module.wasm
```

### Signature Example
Output of `hexdump -C signed-module.wasm`:

```
00000110
00000120  xx xx xx xx xx xx xx 00  74 09 73 69 67 6e 61 74  |j$......t.signat|
00000130  75 72 65 00 47 30 45 02  20 58 20 79 4b 91 52 39  |ure.G0E. X yK.R9|
00000140  75 52 69 f0 cf dc 81 8a  7c d8 ab 08 1d 49 ab c2  |uRi.....|....I..|
00000150  fa 19 79 f5 03 92 e9 9b  87 02 21 00 8f a0 ad 5a  |..y.......!....Z|
00000160  f2 55 ce cf c6 ed 82 15  5a ed 7a 47 43 d9 e5 4e  |.U......Z.zGC..N|
00000170  fd 74 79 e8 80 4e 82 9c  08 eb 8e 9a 00 00 00 00  |.ty..N..........|
00000180  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000190  00 00 00 00 00 00 00 00  00 00 00 00 00 00        |..............  |
```

## Build
```
cargo build --release
```
## Unit Test
```
cargo test
```
## End2End Test with command line tool
```
make test
```