created_at2017-06-03 07:20:16.512728
updated_at2022-04-28 16:23:36.788932
descriptionTLS API without implementation
Stepan Koltsov (stepancheg)



GitHub Workflow Status License

One TLS API to rule them all


  • tokio and async-std
  • rustls, native-tls, openssl, security-framework

Crates in this repository

  • tls-api — TLS API without any implementation and without dependencies
  • tls-api-native-tls — implementation of TLS API over native-tls crate
  • tls-api-openssl — implementation of TLS API over openssl crate
  • tls-api-rustls — implementation of TLS API over rustls crate
  • tls-api-security-framework — implementation of TLS API over security framework crate
  • tls-api-schannel — missing implementation of TLS API over schannel crate
  • tls-api-stub — stub API implementation which returns an error on any operation
  • tls-api-not-tls — stub API implementation which pretends to be TLS, but returns wrapped plain socket
  • test-cert-gen — utility to generate certificate for unit tests

Why one might want to use TLS API instead of concrete implementation

  • it is not decided yet which TLS implementation is better, start prototyping with one, and then switch to another
  • something doesn't work, no idea why, maybe try another implementation which would provide better diagnostics
  • provide a library over TLS (like database client) and allow user do specify preferred TLS implementation
  • do a performace comparison of TLS implementations on the same code base
  • if one implementation is buggy, it's easy to switch to another without heavy rewrite

Example contains the implementation of simple TLS client downloading, which is invoked with four backends.

Implementations comparison

openssl rustls security-framework native-tls
Can fetch Yes Yes Yes Yes
Server works Yes Yes Yes Yes
Client ALPN Yes Yes Yes Yes
Server ALPN Yes Yes No No
Server init from DER key Yes Yes No No
Server init from PKCS12 Yes No Yes Yes

Why not simply use XXX

Why not simply use native-tls

  • does not support server side ALPN
  • requires PKCS #12 keys on the server side
  • building OpenSSL on Linux is not always trivial

Why not simply use openssl

  • sometimes it's hard to compile it
  • some concerns about OpenSSL safety

Why not simply use rustls

  • diagnostics of rustls is not perfect
  • certain TLS features are not supported

Why not simply use security-framework

  • only works on Apple
  • does not support server side ALPN
Commit count: 377

cargo fmt