Installation

siotls is a typical pure Python library that can be installed using pip, but it requires additional backend libraries to perform cryptographic calculations (crypto backend) and validate a chain of certificates against a trusted authority (trust backend).

Backends

OpenSSL / cryptography

Recommended for general purpose.

  • ☑ crypto backend

  • ☑ trust backend

OpenSSL is a robust, commercial-grade, full-featured toolkit for general-purpose cryptography and secure communication. cryptography is the official python binding, maintained by PyCA.

The crypto backend supports all the cryptographic suites of TLS 1.3. It also offers a trust backend that aims to be compliant with the Baseline Requirements, a document that defines guidelines for the management of publicly-trusted TLS Server Certificates. This makes this backend well equipped to safely browse the web.

To use siotls with openssl/cryptography run:

pip install siotls[openssl]

HACL* / pyhacl

  • ☑ crypto backend

  • ☐ trust backend

The HACL* library is a High Assurance Cryptographic Library written in F*, a general-purpose proof-oriented programming language, and compiled in C. pyhacl is an unofficial cython binding, maintained by one of the authors of siotls.

There are only a very few algorithms available in pyhacl. It is notably lacking support for RSA and ECDSA P-384, both of which are required to validate certificates signed by Let’s Encrypt. This makes this backend ill-suited to browse the web. On the other hand, its small size and portable C code makes for an excellent choice for IoT devices and trusted_public_keys.

To use siotls with HACL*/pyhacl run:

pip install siotls[hacl]

OS Trust store

Planned.

  • ☐ crypto backend

  • ☑ trust backend

Use a crypto backend

Use siotls.crypto.install() to install one or several crypto backends.

Example:

import siotls.crypto

siotls.crypto.install('openssl')

Another example to install Chacha from HACL*, and the rest from OpenSSL:

import siotls.crypto
from siotls.iana import CipherSuites

siotls.crypto.install('hacl', [CipherSuites.TLS_CHACHA20_POLY1305_SHA256])
siotls.crypto.install('openssl', duplicate='skip')

The installation is global and it is possible to strip down the ciphers available on a connection using the three cipher_suites, key_exchanges and signature_algorithms configurations. The default configuration uses all installed ciphers.

Use a trust backend

Use siotls.trust.get_truststore() to find and instantiate a global truststore from the installed trust backends. Use it then when creating a TLSConfiguration.

Example:

from siotls import TLSConfiguration
from siotls.trust import get_truststore

tls_config = TLSConfiguration('client', truststore=get_truststore())

Alternatively, it is possible to manually import and instanciate the concrete TrustStore from one of the available backends.

Example, for OpenSSL:

from siotls import TLSConfiguration
from siotls.trust import get_ca_certificates
from siotls.trust.backends.openssl import OpensslTrustStore

truststore = OpensslTrustStore(get_ca_certificates())
tls_config = TLSConfiguration('client', truststore=truststore)