Module rustls::manual::_03_howto

This section collects together goal-oriented documentation.

Customising private key usage

By default rustls supports PKCS#8-format¹ RSA or ECDSA keys, plus PKCS#1-format RSA keys.

However, if your private key resides in a HSM, or in another process, or perhaps another machine, rustls has some extension points to support this:

The main trait you must implement is sign::SigningKey. The primary method here is choose_scheme where you are given a set of SignatureSchemes the client says it supports: you must choose one (or return None – this aborts the handshake). Having done that, you return an implementation of the sign::Signer trait. The sign() performs the signature and returns it.

(Unfortunately this is currently designed for keys with low latency access, like in a PKCS#11 provider, Microsoft CryptoAPI, etc. so is blocking rather than asynchronous. It’s a TODO to make these and other extension points async.)

Once you have these two pieces, configuring a server to use them involves, briefly:

• packaging your sign::SigningKey with the matching certificate chain into a sign::CertifiedKey
• making a ResolvesServerCertUsingSNI and feeding in your sign::CertifiedKey for all SNI hostnames you want to use it for,
• setting that as your ServerConfig’s cert_resolver

---

1. For PKCS#8 it does not support password encryption – there’s not a meaningful threat model addressed by this, and the encryption supported is typically extremely poor. ↩