README.md — sigil-tls

1# sigil-tls

3TLS/SSL client connections for [Sigil](https://codeberg.org/sigil/sigil).

5Secure TCP connections using mbedTLS. Supports TLS 1.2 client connections

6with system CA certificate verification, non-blocking I/O, and STARTTLS

7upgrades of existing sockets.

9## Modules

11| Module | Purpose |

12|----------------|-----------------------------------------|

13| `(sigil tls)` | TLS 1.2 client connections |

15## API summary

17| Procedure | Purpose |

18|---------------------------|--------------------------------------------------------|

19| `tls-connect` | Open a TLS connection to a host/port |

20| `tls-upgrade` | Upgrade an existing TCP socket to TLS (STARTTLS) |

21| `tls-read` | Read a string from a TLS connection |

22| `tls-read-bytevector` | Read raw bytes from a TLS connection |

23| `tls-write` | Write a string or bytevector to a TLS connection |

24| `tls-close` | Close a TLS connection |

25| `tls-closed?` | Whether a connection is closed |

26| `tls-connection?` | Whether a value is a TLS connection |

27| `tls-set-non-blocking!` | Toggle non-blocking mode on the underlying socket |

29## System prerequisites

31None beyond a working C toolchain. mbedTLS is consumed transitively via

32[sigil-crypto](https://codeberg.org/sigil/sigil-crypto), which vendors

33mbedTLS and exposes its headers to downstream consumers automatically.

35## Dependencies

37- sigil-stdlib

38- sigil-crypto (vendors mbedTLS)

40## Build

42```sh

43sigil deps install

44sigil build

45sigil test --report

46```

48## Usage

50```scheme

51(import (sigil tls))

53(let ((conn (tls-connect "example.com" 443)))

54 (tls-write conn "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")

55 (display (tls-read conn))

56 (tls-close conn))

57```

59Set `SIGIL_TLS_INSECURE=1` to skip certificate verification (testing only).

61## License

63BSD-3-Clause. See sigil-crypto for the vendored mbedTLS license terms.