pylibtls
About
Developed initially in september 2021 on FreeBSD 13.0 with LibreSSL 3.3.3 with API Version 20200120
.
The aim is to just wrap the API as thinly as possible. A few principles:
str
is encoded using default encoding (just callingencode()
)- Epochs are converted to UTC datetime
- Return code
-1
is made intoTLSError
- Returned
1
s and0
s are cast toboolean
- Returned strings are converted with
decode()
tls_read()
andtls_write()
expectsbytes
though- The order of the functions defined matches that of libtls.h
- Argument names are not always pythonic but matches that of libtls.h
Background
I always thought it was a bit of a mistake for LibreSSL to be an drop-in replacement for OpenSSL. I just wanted to use libtls and be done with it. But since LibreSSL always replaced OpenSSL and that always seemed to be problematic I looked for ways to install just libtls, but to no awail. Until April 18, 2021 when version 3.3.2 of LibreSSL was released.
From the release notes (way down):
Added '--enable-libtls-only' build option, which builds and installs a statically-linked libtls, skipping libcrypto and libssl. This is useful for systems that ship with OpenSSL but wish to also package libtls.
YEY!
Some time after it was made a flavor of the FreeBSD LibreSSL port. So now I finally had it! So I started looking for Python wrappers for it. I found python-libtls by Vinay Sajip. Last update in 2017, looked abandoned, so I made a new one.
Getting started
Getting libtls
First thing is getting libtls somehow. If you already have LibreSSL you should be good to go. Otherwise hope the ‑‑enable‑libtls‑only build flag is used somehow in whatever package thingamajig you're using.
FreeBSD
pkg install libressl-libtls
MacOS
I was suprised to find out Apple deprecated OpenSSL after High Sierra and now ships with LibreSSL. But you can't use it =/. But install it with Homebrew!
brew install libressl
It's not linked since it would mess with the one shipped with MacOS. Set the env variable PYLIBTLS_LIBTLS_PATH
to /usr/local/opt/libressl/lib/libtls.dylib
and you're good to go.
Linux (Rocky Linux 8.4)
There's no love for libtls in the Linux community! So no package in rpm. Beware of the package libretls
, it's libtls on top of OpenSSL!
But thankfully it's pretty easy to compile it yourself. This is how I installed it on Rocky Linux, YMMW. Instructions @ GitHub
dnf install wget
wget https://ftp.openbsd.org/pub/OpenBSD/LibreSSL/libressl-3.3.5.tar.gz
cd libressl-3.3.5
./configure --enable-libtls-only # very important flag!
make check # as recommended on GitHub
make install
Now it's installed in /usr/local/lib
but you need to tell the linker that. There's a few ways to do that. I added the path to /etc/ld.so.con
. You can also add it to env var LD_LIBRARY_PATH
.
Then you need to tell libtls how to find your CA bundle. The default path is apparently hard coded to /etc/ssl/cert.pem
. This is NOT where Rocky Linux keeps them, so I soft linked it like so:
ln -s /etc/pki/tls/cert.pem /etc/ssl/cert.pem
This all depends on your distro. All RHEL derivaties keep their bundle in /etc/pki/tls/cert.pem
.
Environment variables
There's an env variable you can use to specify the path to libtls if ctypes
is unable to find it automagically and that's PYLIBTLS_LIBTLS_PATH
.
Getting pylibtls
Just use pip:
$> pip install pylibtls
and in your script
import tls
Usage
Oh the fun part!
Functions are named the same so tls_init()
is tls.tls_init()
and so on. Constants from header file are just tls.TLS_A_CONSTANT
.
from tls import (tls_config_new, tls_client, tls_configure, tls_connect, tls_write,
tls_read, tls_config_free, tls_close, tls_free)
cfg = tls_config_new()
ctx = tls_client()
tls_configure(ctx, cfg)
host = 'www.openbsd.org'
tls_connect(ctx, host, 443)
query = "HEAD / HTTP/1.0\r\nHost: {}\r\n\r\n".format(host)
tls_write(ctx, query.encode())
r = tls_read(ctx)
print(r.decode())
tls_config_free(cfg)
tls_close(ctx)
tls_free(ctx)
The full monty
from tls import *
print('Version:', TLS_API)
cfg = tls_config_new()
tls_config_set_ca_file(cfg, "/etc/ssl/cert.pem")
print(tls_default_ca_cert_file())
tls_config_set_protocols(cfg, TLS_PROTOCOL_TLSv1_2)
ctx = tls_client()
tls_configure(ctx, cfg)
host = 'www.openbsd.org'
print('host:', host)
print('connect_socket')
tls_connect(ctx, host, 443)
tls_handshake(ctx)
print("Cert provided:", tls_peer_cert_provided(ctx))
print("Hash (SHA256):", tls_peer_cert_hash(ctx))
print("Issuer:", tls_peer_cert_issuer(ctx))
print("Subject:", tls_peer_cert_subject(ctx))
print("NotBefore (UTC):", tls_peer_cert_notbefore(ctx))
print("NotAfter (UTC):", tls_peer_cert_notafter(ctx))
print("ALPN:", tls_conn_alpn_selected(ctx))
print("Cipher:", tls_conn_cipher(ctx))
print("Servername:", tls_conn_servername(ctx))
print("Resumed:", tls_conn_session_resumed(ctx))
print("TLS Version:", tls_conn_version(ctx))
print("OCSP URL:", tls_peer_ocsp_url(ctx))
print("OCSP result:", tls_peer_ocsp_result(ctx))
if tls_peer_ocsp_result(ctx) is not None:
print("OCSP Response Status:", TLS_OCSP_RESPONSE[tls_peer_ocsp_response_status(ctx)])
print("OCSP Cert Status:", TLS_OCSP_CERT[tls_peer_ocsp_cert_status(ctx)])
print("OCSP CRL Reason:", TLS_CRL_REASON[tls_peer_ocsp_crl_reason(ctx)])
print("OCSP revocation:", tls_peer_ocsp_revocation_time(ctx))
print("OCSP this update:", tls_peer_ocsp_this_update(ctx))
print("OCSP next update:", tls_peer_ocsp_next_update(ctx))
print()
query = "HEAD / HTTP/1.0\r\nHost: {}\r\n\r\n".format(host)
print('tls_write', query)
r = tls_write(ctx, query.encode())
print(r, 'bytes')
print('read')
r = tls_read(ctx)
print(len(r), 'bytes')
print(r.decode())
tls_config_free(cfg)
tls_close(ctx)
tls_free(ctx)
This is using the extra dict
s I put in for reverse lookup of values-to-name: TLS_OCSP_RESPONSE
, TLS_OCSP_CERT
and TLS_CRL_REASON
. They require that OCSP stapling is active on the server in question. In the example, it is.
Very simple server
from tls import *
import socket
cfg = tls_config_new()
tls_config_set_keypair_file(cfg, 'cert.pem', 'privkey.pem')
ctx = tls_server()
tls_configure(ctx, cfg)
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.bind(('www.example.com', 2345))
s.listen(10)
print('Listening on socket...')
c, addr = s.accept()
print(addr, 'connected')
cctx = tls_accept_socket(ctx, c)
tls_write(cctx, 'Hello World'.encode())
print(tls_read(cctx))
tls_close(cctx)
tls_free(cctx)
tls_config_free(cfg)
tls_free(ctx)
s.close()
Accepts a single connection and writes Hello World
then reads once and shuts down.
Documentation
None yet, apart from this README. See the OpenBSD documentation for reference. It should get you up and running somewhat.
Status
2021-10-17
Instructions for Linux (Rocky Linux 8.4)
2021-10-13
Instructions for simple server
2021-10-09
Published on PyPi!
2021-10-08
First pushed to GitHub (A bit nervous). Most of the API implemented. Only client functionality tested. No local OCSP-stuff (getting the staple file is HARD). Only tested on FreeBSD. Should work fine on Linux at least. No libtls-only
brew Formulae so MacOS is out (might be next project). Windows seems to be a sad chapter in general. Vinay stranded here more or less.
TODO
- All
mem
-functions that read stuff from memory loaded withtls_load_file()
- Callbacks versions of
tls_accept()
andtls_connect()
- File descriptor versions of the same
-
tls_peer_cert_chain_pem()
-
assert
a few things here and there
Acknowledgments
- python-libtls and python-gnutls for inspiration