Module key_cert

stem_rs::descriptor

Module key_cert 

Source
Expand description

Key certificate parsing for Tor directory authorities.

This module provides parsing for directory key certificates used by v3 network status documents to authenticate directory authorities. Key certificates bind a directory authority’s long-term identity key to a medium-term signing key used to sign consensus documents.

§Overview

Directory authorities use a two-tier key system for security:

  • Identity Key: A long-term RSA key that identifies the authority. This key is kept offline and used only to sign key certificates.
  • Signing Key: A medium-term RSA key used to sign votes and consensus documents. This key is rotated periodically.

Key certificates establish the binding between these keys, allowing clients to verify that a signing key is authorized by a known authority.

§Certificate Format

Key certificates follow the Tor directory specification format:

dir-key-certificate-version 3
dir-address <IP>:<port>
fingerprint <40 hex chars>
dir-key-published <YYYY-MM-DD HH:MM:SS>
dir-key-expires <YYYY-MM-DD HH:MM:SS>
dir-identity-key
-----BEGIN RSA PUBLIC KEY-----
<base64 encoded key>
-----END RSA PUBLIC KEY-----
dir-signing-key
-----BEGIN RSA PUBLIC KEY-----
<base64 encoded key>
-----END RSA PUBLIC KEY-----
dir-key-crosscert
-----BEGIN ID SIGNATURE-----
<signature>
-----END ID SIGNATURE-----
dir-key-certification
-----BEGIN SIGNATURE-----
<signature>
-----END SIGNATURE-----

§Example

use stem_rs::descriptor::KeyCertificate;

let cert_content = r#"dir-key-certificate-version 3
fingerprint BCB380A633592C218757BEE11E630511A485658A
dir-key-published 2024-01-01 00:00:00
dir-key-expires 2025-01-01 00:00:00
dir-identity-key
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA
-----END RSA PUBLIC KEY-----
dir-signing-key
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA
-----END RSA PUBLIC KEY-----
dir-key-certification
-----BEGIN SIGNATURE-----
AAAA
-----END SIGNATURE-----
"#;

let cert = KeyCertificate::parse(cert_content).unwrap();
assert_eq!(cert.version, Some(3));
assert_eq!(cert.fingerprint.as_deref(), Some("BCB380A633592C218757BEE11E630511A485658A"));

§Security Considerations

  • Always check is_expired() before trusting a certificate
  • The crosscert signature proves the signing key holder authorized the binding
  • The certification signature proves the identity key holder authorized the binding
  • Both signatures should be verified for full security (not implemented in this module)

§See Also

  • consensus: Network status documents that reference key certificates
  • authority: Directory authority information
  • certificate: Ed25519 certificates (different from key certificates)

Structs§

KeyCertificate
A directory authority key certificate.