展开描述
本节收集了针对不同目标的文档
§Customising private key usage
By default rustls supports PKCS#8-format1 RSA 或 ECDSA keys, plus PKCS#1-format RSA keys.
However, if your 私钥 resides in 一个 HSM, 或 in another process, 或 perhaps another machine, rustls has some extension points 到 support this:
此 main trait you must implement is sign::SigningKey。 此 primary method here
is choose_scheme() where you are given 一个 set of SignatureSchemes the client says
it supports: you must choose one (或 return None – this aborts the handshake)。 Having
done that, you return an implementation of the sign::Signer trait.
此 sign() performs the 签名并 returns it.
(Unfortunately this is currently designed 用于 keys with low latency access, like in 一个 PKCS#11 provider, Microsoft CryptoAPI, etc. so is blocking rather than asynchronous. It’s 一个 TODO 到 make these 并 other extension points async.)
Once you have these two pieces, configuring 一个 server 到 use them involves, briefly:
- packaging your
sign::SigningKeywith the matching certificate chain into asign::CertifiedKey - making a
ResolvesServerCertUsingSniand feeding in yoursign::CertifiedKeyfor all SNI hostnames you want to use it for, - setting that as your
ServerConfig’scert_resolver
For 一个 complete example of implementing 一个 custom sign::SigningKey 并
sign::Signer see the signer module in the rustls-cng crate。
§Unexpected EOF
TLS has 一个 close_notify mechanism 到 prevent truncation attacks2。
According 到 the TLS RFCs, each party is required 到 send 一个 close_notify message before
closing the write side of the connection. However, some implementations don’t send it.
So long as the application layer protocol (用于 instance HTTP/2) has message length framing
并 can 拒绝 truncated messages, this is not 一个 security problem.
Rustls treats an EOF without close_notify as an error of type std::io::Error with
ErrorKind::UnexpectedEof。 In some situations it’s appropriate 用于 the application 到 handle
this error the same way it would handle 一个 normal EOF (一个 read returning Ok(0))。 In particular
if UnexpectedEof occurs on an idle connection it is appropriate 到 treat it the same way as 一个
clean shutdown. And if an application always uses messages with length framing (in other words,
messages are never delimited by the close of the TCP connection), it can unconditionally
ignore UnexpectedEof errors 从 rustls.
§Debugging
If you encounter 一个 bug with Rustls it can be helpful 到 collect up as much diagnostic information as possible.
§Collecting logs
If your bug reproduces with one of the Rustls examples you can use the
RUST_LOG environment variable 到 increase the log verbosity. If you’re using
your own application, you may need 到 configure it with 一个 logging backend
like env_logger。
Consider reproducing your bug with RUST_LOG=rustls=trace 并 sharing 结果
in 一个 GitHub gist。
§Taking a packet capture
When logs ，’t enough taking 一个 packet capture (“pcap”) is another helpful tool. 此 details of how 到 accomplish this vary by operating system/context.
§tcpdump
例如，在 Linux 上使用 tcpdump 最为简便。
If you know the IP address of the remote server your bug demonstrates with you
could take 一个 short packet capture with this command (after replacing
XX.XX.XX.XX with the correct IP address):
sudo tcpdump -i any tcp and dst host XX.XX.XX.XX -C5 -w rustls.pcap此 -i any captures on any network interface. 此 tcp and dst host XX.XX.XX.XX
portion target the capture to TCP traffic to the specified IP address. 此 -C5
argument limits the capture to at most 5MB. Lastly the -w argument writes the
capture to rustls.pcap。
Another approach is to use tcp and port XXXX instead of tcp and dst host XX.XX.XX.XX
to capture all traffic to a specific port instead of a specific host server.
§SSLKEYLOGFILE
If the bug you are reporting happens after data is encrypted you may also wish to share the secret keys required to decrypt the post-handshake traffic.
If you’re using one of the Rustls examples you can set the SSLKEYLOGFILE environment
variable to a path where secrets will be written. E.g. SSLKEYLOGFILE=rustls.pcap.keys。
If you’re using your own application you may need to customize the Rustls ClientConfig
or ServerConfig’s key_log setting like the example applications do.
With the file 从 SSLKEYLOGFILE it is possible to use Wireshark or another tool to
decrypt the post-handshake messages, following these instructions。
Remember this allows plaintext decryption and should only be done in testing contexts where no sensitive data (API keys, etc) are being shared.
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. ↩