Skip to content

Start adding some more information to the readme #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 20, 2025
Merged

Start adding some more information to the readme #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 58 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,107 +4,103 @@

---

# [Example WASI proposal]

This template can be used to start a new proposal, which can then be proposed in the WASI Subgroup meetings.

The sections below are recommended. However, every proposal is different, and the community can help you flesh out the proposal, so don't block on having something filled in for each one of them.

Thank you to the W3C Privacy CG for the [inspiration](https://github.com/privacycg/template)!

# [Title]
# wasi-tls

A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.

### Current Phase

[Fill in the current phase, e.g. Phase 1]
wasi-tls is currently in [Phase 1](https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-1---feature-proposal-cg)

### Champions

<!---
Please limit to one champion per company or organization
-->
- [Champion 1]
- [Champion 2]
- [etc.]
- [Dave Bakker]([@badeend](https://github.com/badeend))
- [Joel Dice](https://github.com/dicej)
- [James Sturtevant](https://github.com/jsturtevant)

### Portability Criteria

TODO before entering Phase 2.

## Table of Contents [if the explainer is longer than one printed page]

- [Introduction](#introduction)
- [Goals [or Motivating Use Cases, or Scenarios]](#goals-or-motivating-use-cases-or-scenarios)
- [Non-goals](#non-goals)
- [API walk-through](#api-walk-through)
- [Use case 1](#use-case-1)
- [Use case 2](#use-case-2)
- [Detailed design discussion](#detailed-design-discussion)
- [[Tricky design choice 1]](#tricky-design-choice-1)
- [[Tricky design choice 2]](#tricky-design-choice-2)
- [Considered alternatives](#considered-alternatives)
- [[Alternative 1]](#alternative-1)
- [[Alternative 2]](#alternative-2)
- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback)
- [References & acknowledgements](#references--acknowledgements)
- [Transport Layer Security (TLS/SSL)](#transport-layer-security-tlsssl)
- [wasi-tls](#wasi-tls)
- [Current Phase](#current-phase)
- [Champions](#champions)
- [Portability Criteria](#portability-criteria)
- [Table of Contents \[if the explainer is longer than one printed page\]](#table-of-contents-if-the-explainer-is-longer-than-one-printed-page)
- [Introduction](#introduction)
- [Goals \[or Motivating Use Cases, or Scenarios\]](#goals-or-motivating-use-cases-or-scenarios)
- [Non-goals](#non-goals)
- [API walk-through](#api-walk-through)
- [Use with wasi-sockets to make tls connection](#use-with-wasi-sockets-to-make-tls-connection)
- [Use to make connection to database](#use-to-make-connection-to-database)
- [Detailed design discussion](#detailed-design-discussion)
- [\[Tricky design choice #1\]](#tricky-design-choice-1)
- [Considered alternatives](#considered-alternatives)
- [Compile libraries like OpenSSL to Wasm](#compile-libraries-like-openssl-to-wasm)
- [Use wasi-crypto](#use-wasi-crypto)
- [Stakeholder Interest \& Feedback](#stakeholder-interest--feedback)
- [References \& acknowledgements](#references--acknowledgements)

### Introduction

[The "executive summary" or "abstract". Explain in a few sentences what the goals of the project are, and a brief overview of how the solution works. This should be no more than 1-2 paragraphs.]
Wasi-tls is aimed at providing a high level api that provides the ability to read and write encrypted data over a stream. The API is a TLS specific way for clients and servers to configure the connection. The encryption work is done by the host allowing implementors to re-use hardened solutions and also perform more advance solutions such as hardware offloading and Kernel TLS.

### Goals [or Motivating Use Cases, or Scenarios]

[What is the end-user need which this project aims to address?]
- Use wasi-sockets to open a connection to a web server and then communicate using TLS via wasi-tls
- Enable mTLS connections to databases

### Non-goals

[If there are "adjacent" goals which may appear to be in scope but aren't, enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.]
- Provide a fully flushed out implementation of TLS/SSL
- Provide low level TLS primitives

### API walk-through

The full API documentation can be found [here](wasi-proposal-template.md).
The full API documentation can be found [in imports](imports.md).

[Walk through of how someone would use this API.]
#### Use with wasi-sockets to make tls connection

#### [Use case 1]
A simple example in sudo code:

[Provide example code snippets and diagrams explaining how the API would be used to solve the given problem]

#### [Use case 2]

[etc.]

### Detailed design discussion
```
// initiate and complete handshake
let handshake = ClientHandshake::new(DOMAIN, tcp_input, tcp_output);
let (client, tls_input, tls_output) = handshake.finish().await?;

[This section should mostly refer to the .wit.md file that specifies the API. This section is for any discussion of the choices made in the API which don't make sense to document in the spec file itself.]
// send data to server and read
tls_output.write("GET / HTTP/1.1\r\nHost: {DOMAIN}\r\n\r\n").await?;
tls_output.read(buffer).await?;

#### [Tricky design choice #1]
//close the connection
client.close_notify()?
```

[Talk through the tradeoffs in coming to the specific design point you want to make.]
#### Use to make connection to database

```
// Illustrated with example code.
```
TODO

[This may be an open question, in which case you should link to any active discussion threads.]
### Detailed design discussion

#### [Tricky design choice 2]
#### [Tricky design choice #1]

[etc.]
TODO

### Considered alternatives

[This section is not required if you already covered considered alternatives in the design discussion above.]
#### Compile libraries like OpenSSL to Wasm

#### [Alternative 1]
We opted to not go with this option due to no constant time operations in WASM and more advance scenarios like hardware acceleration could not be could be leveraged.

[Describe an alternative which was considered, and why you decided against it.]
#### Use wasi-crypto

#### [Alternative 2]

[etc.]
We opted to not go with this option since [wasi-crypto](https://github.com/WebAssembly/WASI-crypto) is intended for low level use cases and it would be difficult to use correctly and require developers to re-implement libraries that already exist. It might be possible to virtualize wasi-tls using wasi-crypto in the future.

### Stakeholder Interest & Feedback

Expand All @@ -114,6 +110,13 @@ TODO before entering Phase 3.

### References & acknowledgements

- [Pre-proposal](https://docs.google.com/presentation/d/1C55ph_fSTRhb4A4Nlpwvp9JGy8HBL6A1MvgY2jrapyQ/edit?usp=sharing)
- [Proposal to WG](https://github.com/WebAssembly/meetings/blob/main/wasi/2025/WASI-01-09.md)
- [Initial GitHub issue and discussion](https://github.com/WebAssembly/wasi-sockets/issues/100)
- [Draft PR, usage examples, and compatibility evaluation](https://github.com/WebAssembly/wasi-sockets/pull/104)
- [.NET guest + Wasmtime host proof-of-concept](https://github.com/dicej/dotnet-wasi-tls)
- [.NET runtime prototype](https://github.com/dotnet/runtime/compare/main...jsturtevant:runtime:wasi-tls-2)

Many thanks for valuable feedback and advice from:

- [Person 1]
Expand Down