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 and TLS 1.3 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 and TLS 1.3 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## Connection diagnostics

31`tls-connect/details` and `tls-upgrade/details` accept the same arguments as

32their `/status` counterparts and return a dictionary. The existing connection

33and `/status` APIs retain their return shapes.

35`status:` gives the stable outcome and `connection:` is the connection or

36`#f`. `error-code:`, `error-message:`, and `handshake-state:` describe a

37failed handshake. `protocol:` and `cipher:` identify a successful negotiation.

38Details belong to that attempt and survive later connections. Handshake state

39names are diagnostic information; use `status:` for application decisions.

41## System prerequisites

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

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

45mbedTLS and exposes its headers to downstream consumers automatically.

47## Dependencies

49- sigil-stdlib

50- sigil-crypto (vendors mbedTLS)

52## Build

54```sh

55sigil deps install

56sigil build

57sigil test --report

58```

60## Usage

62```scheme

63(import (sigil tls))

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

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

67 (display (tls-read conn))

68 (tls-close conn))

69```

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

73## License

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