Lines
11.48 %
Functions
1.02 %
Branches
100 %
//! Relay channel code.
//!
//! This contains relay specific channel code. In other words, everything that a relay needs to
//! establish a channel according to the Tor protocol.
pub(crate) mod handshake;
pub(crate) mod initiator;
pub(crate) mod responder;
pub use responder::MaybeVerifiableRelayResponderChannel;
use digest::Digest;
use futures::{AsyncRead, AsyncWrite};
use rand::Rng;
use safelog::Sensitive;
use std::net::IpAddr;
use std::sync::Arc;
use std::time::UNIX_EPOCH;
use tor_cell::chancell::msg;
use tor_cert::EncodedEd25519Cert;
use tor_cert::rsa::EncodedRsaCrosscert;
use tor_cert::x509::TlsKeyAndCert;
use tor_error::internal;
use tor_linkspec::{HasRelayIds, OwnedChanTarget, RelayIdRef, RelayIdType};
use tor_llcrypto as ll;
use tor_llcrypto::pk::{
ed25519::{Ed25519Identity, Ed25519SigningKey},
rsa,
rsa::RsaIdentity,
};
use tor_relay_crypto::pk::RelayLinkSigningKeypair;
use tor_rtcompat::{CertifiedConn, CoarseTimeProvider, SleepProvider, StreamOps};
use crate::channel::handshake::VerifiedChannel;
use crate::peer::PeerAddr;
use crate::relay::channel::handshake::{AUTHTYPE_ED25519_SHA256_RFC5705, RelayResponderHandshake};
use crate::{Error, Result, channel::RelayInitiatorHandshake, memquota::ChannelAccount};
// TODO(relay): We should probably get those values from protover crate or some other
// crate that have all "network parameters" we support?
/// A list of link authentication that we support (LinkAuth).
pub(crate) static LINK_AUTH: &[u16] = &[AUTHTYPE_ED25519_SHA256_RFC5705];
/// Object containing the key and certificate that basically identifies us as a relay. They are
/// used for channel authentication.
///
/// We use this intermediary object in order to not have tor-proto crate have access to the KeyMgr
/// meaning access to all keys. This restricts the view to what is needed.
pub struct RelayIdentities {
/// The SHA256(DER(KP_relayid_rsa)) digest for the AUTHENTICATE cell CID.
pub(crate) rsa_id_der_digest: [u8; 32],
/// Our RSA identity `KP_relayid_rsa` (SHA1). Needed for HasRelayIds which is required to
/// compare this with a [`tor_linkspec::ChanTarget`].
pub(crate) rsa_id: RsaIdentity,
/// Our Ed identity key (KP_relayid_ed). For the [`msg::Authenticate`] cell CID_ED field.
pub(crate) ed_id: Ed25519Identity,
/// Our link signing keypair. Used to sign the [`msg::Authenticate`] cell.
pub(crate) link_sign_kp: RelayLinkSigningKeypair,
/// The Ed25519 identity signing cert (CertType 4) for the [`msg::Certs`] cell.
pub(crate) cert_id_sign_ed: EncodedEd25519Cert,
/// The Ed25519 signing TLS cert (CertType 5) for the [`msg::Certs`] cell.
pub(crate) cert_sign_tls_ed: EncodedEd25519Cert,
/// The Ed25519 signing link auth cert (CertType 6) for the [`msg::Certs`] cell.
pub(crate) cert_sign_link_auth_ed: EncodedEd25519Cert,
/// Legacy: the RSA identity X509 cert (CertType 2) for the [`msg::Certs`] cell.
/// We only have the bytes here as create_legacy_rsa_id_cert() takes a key and gives us back
/// the encoded cert.
pub(crate) cert_id_x509_rsa: Vec<u8>,
/// Legacy: the RSA identity cert (CertType 7) for the [`msg::Certs`] cell.
pub(crate) cert_id_rsa: EncodedRsaCrosscert,
/// Tls key and cert. This is for the TLS acceptor object needed to be a responder (TLS server
/// side).
pub(crate) tls_key_and_cert: TlsKeyAndCert,
}
impl RelayIdentities {
/// Constructor.
#[allow(clippy::too_many_arguments)] // Yes, plethora of keys...
pub fn new(
rsa_id_pk: &rsa::PublicKey,
ed_id: Ed25519Identity,
link_sign_kp: RelayLinkSigningKeypair,
cert_id_sign_ed: EncodedEd25519Cert,
cert_sign_tls_ed: EncodedEd25519Cert,
cert_sign_link_auth_ed: EncodedEd25519Cert,
cert_id_x509_rsa: Vec<u8>,
cert_id_rsa: EncodedRsaCrosscert,
tls_key_and_cert: TlsKeyAndCert,
) -> Self {
Self {
rsa_id_der_digest: ll::d::Sha256::digest(rsa_id_pk.to_der()).into(),
rsa_id: rsa_id_pk.to_rsa_identity(),
ed_id,
link_sign_kp,
cert_id_sign_ed,
cert_sign_tls_ed,
cert_sign_link_auth_ed,
cert_id_x509_rsa,
cert_id_rsa,
tls_key_and_cert,
/// Return the TLS key and certificate to use for the underlying TLS provider.
/// This is used by the TLS acceptor that acts as the TLS server provider.
pub fn tls_key_and_cert(&self) -> &TlsKeyAndCert {
&self.tls_key_and_cert
/// Return our Ed identity key (KP_relayid_ed) as bytes.
pub(crate) fn ed_id_bytes(&self) -> [u8; 32] {
self.ed_id.into()
impl HasRelayIds for RelayIdentities {
fn identity(&self, key_type: RelayIdType) -> Option<RelayIdRef<'_>> {
match key_type {
RelayIdType::Ed25519 => Some(RelayIdRef::from(&self.ed_id)),
RelayIdType::Rsa => Some(RelayIdRef::from(&self.rsa_id)),
_ => None, // Non-exhaustive...
/// Structure for building and launching a relay Tor channel.
#[derive(Default)]
#[non_exhaustive]
pub struct RelayChannelBuilder;
impl RelayChannelBuilder {
pub fn new() -> Self {
Self::default()
/// Launch a new handshake over a TLS stream.
/// After calling this function, you'll need to call `connect()` on the result to start the
/// handshake. If that succeeds, you'll have authentication info from the relay: call
/// `check()` on the result to check that. Finally, to finish the handshake, call `finish()`
/// on the result of _that_.
#[allow(clippy::too_many_arguments)] // TODO consider if we want a builder
pub fn launch<T, S>(
self,
tls: T,
sleep_prov: S,
identities: Arc<RelayIdentities>,
my_addrs: Vec<IpAddr>,
peer: &OwnedChanTarget,
memquota: ChannelAccount,
) -> RelayInitiatorHandshake<T, S>
where
T: AsyncRead + AsyncWrite + CertifiedConn + StreamOps + Send + Unpin + 'static,
S: CoarseTimeProvider + SleepProvider,
{
RelayInitiatorHandshake::new(tls, sleep_prov, identities, my_addrs, peer, memquota)
/// Accept a new handshake over a TLS stream.
pub fn accept<T, S>(
peer_addr: Sensitive<PeerAddr>,
) -> RelayResponderHandshake<T, S>
RelayResponderHandshake::new(peer_addr, my_addrs, tls, sleep_prov, identities, memquota)
/// Channel authentication data. This is only relevant for a Relay to Relay channel which are
/// authenticated using this buffet of bytes.
#[derive(Debug)]
pub(crate) struct ChannelAuthenticationData {
/// Authentication method to use.
pub(crate) link_auth: u16,
/// SHA256 digest of the initiator KP_relayid_rsa.
pub(crate) cid: [u8; 32],
/// SHA256 digest of the responder KP_relayid_rsa.
pub(crate) sid: [u8; 32],
/// The initiator KP_relayid_ed.
pub(crate) cid_ed: [u8; 32],
/// The responder KP_relayid_ed.
pub(crate) sid_ed: [u8; 32],
/// Initiator log SHA256 digest.
pub(crate) clog: [u8; 32],
/// Responder log SHA256 digest.
pub(crate) slog: [u8; 32],
/// SHA256 of responder's TLS certificate.
pub(crate) scert: [u8; 32],
impl ChannelAuthenticationData {
/// Helper: return the authentication type string from the given link auth version.
const fn auth_type_bytes(link_auth: u16) -> Result<&'static [u8]> {
match link_auth {
3 => Ok(b"AUTH0003"),
_ => Err(Error::BadCellAuth),
/// Helper: return the keying material label from the given link auth version.
const fn keying_material_label_bytes(link_auth: u16) -> Result<&'static [u8]> {
3 => Ok(b"EXPORTER FOR TOR TLS CLIENT BINDING AUTH0003"),
/// Return a vector of bytes of an [`msg::Authenticate`] cell but without the random bytes and
/// the signature.
/// This is needed so a responder can compare what is expected from what it got. A responder
/// can only verify the signature and so we can't compare the full [`msg::Authenticate`]
/// message we received with what we expect.
pub(crate) fn as_body_no_rand<C: CertifiedConn>(&self, tls: &C) -> Result<Vec<u8>> {
// The body is exactly 352 bytes so optimize a bit memory.
let mut body = Vec::with_capacity(352);
// Obviously, ordering matteres. See tor-spec section Ed25519-SHA256-RFC5705
body.extend_from_slice(Self::auth_type_bytes(self.link_auth)?);
body.extend_from_slice(&self.cid);
body.extend_from_slice(&self.sid);
body.extend_from_slice(&self.cid_ed);
body.extend_from_slice(&self.sid_ed);
body.extend_from_slice(&self.slog);
body.extend_from_slice(&self.clog);
body.extend_from_slice(&self.scert);
// TLSSECRETS is built from the CID.
let tls_secrets = tls.export_keying_material(
32,
Self::keying_material_label_bytes(self.link_auth)?,
Some(&self.cid[..]),
)?;
body.extend_from_slice(tls_secrets.as_slice());
Ok(body)
/// Consume ourself and return an AUTHENTICATE cell from the data we hold.
pub(crate) fn into_authenticate<C: CertifiedConn>(
tls: &C,
link_ed: &RelayLinkSigningKeypair,
) -> Result<msg::Authenticate> {
// Get us everything except the random bytes and signature.
let mut body = self.as_body_no_rand(tls)?;
// Add the random bytes.
let random: [u8; 24] = rand::rng().random();
body.extend_from_slice(&random);
// Create signature with our KP_link_ed and append it to body. We hard expect the
// KP_link_ed because this would be a code flow error.
let sig = link_ed.sign(&body);
body.extend_from_slice(&sig.to_bytes());
// Lets go with the AUTHENTICATE cell.
Ok(msg::Authenticate::new(self.link_auth, body))
/// Build a [`ChannelAuthenticationData`] for an initiator channel handshake.
/// `auth_challenge_cell` is the [`msg::AuthChallenge`] we recevied during the handshake.
/// `identities` are our [`RelayIdentities`]
/// `verified` is a [`VerifiedChannel`] which we need to consume the CLOG/SLOG
/// `peer_cert_digest` is the TLS certificate presented by the peer.
pub(crate) fn build_initiator<T, S>(
auth_challenge_cell: &msg::AuthChallenge,
identities: &Arc<RelayIdentities>,
clog: [u8; 32],
slog: [u8; 32],
verified: &mut VerifiedChannel<T, S>,
peer_cert_digest: [u8; 32],
) -> Result<ChannelAuthenticationData>
// Keep what we know from the AUTH_CHALLENGE and we max() on it.
let link_auth = *LINK_AUTH
.iter()
.filter(|m| auth_challenge_cell.methods().contains(m))
.max()
.ok_or(Error::BadCellAuth)?;
// The ordering matter as this is an initiator.
let cid = identities.rsa_id_der_digest;
let sid = verified.rsa_id_digest;
let cid_ed = identities.ed_id_bytes();
let sid_ed = (*verified
.relay_ids()
.ed_identity()
.expect("Verified channel without Ed25519 identity"))
.into();
Ok(Self {
link_auth,
cid,
sid,
cid_ed,
sid_ed,
clog,
slog,
scert: peer_cert_digest,
})
/// `initiator_auth_type` is the authentication type from the [`msg::Authenticate`] received
/// from the initiator.
/// `our_cert_digest` is our TLS certificate that we presented as a channel responder.
/// IMPORTANT: The CLOG and SLOG from the framed_tls codec is consumed here so calling twice
/// build_auth_data() will result in different AUTHENTICATE cells.
pub(crate) fn build_responder<T, S>(
initiator_auth_type: u16,
our_cert_digest: [u8; 32],
// Max on what we know.
let link_auth = if LINK_AUTH.contains(&initiator_auth_type) {
initiator_auth_type
} else {
return Err(Error::UnsupportedAuth(initiator_auth_type));
// The ordering matter as this is a respodner. It is inversed from the initiator.
// Notice, everything is inversed here as the responder.
cid: sid,
sid: cid,
cid_ed: sid_ed,
sid_ed: cid_ed,
scert: our_cert_digest,
/// Helper: Build a [`msg::Certs`] cell for the given relay identities and channel type.
/// Both relay initiator and responder handshake use this.
pub(crate) fn build_certs_cell(
is_responder: bool,
) -> msg::Certs {
let mut certs = msg::Certs::new_empty();
// Push into the cell the CertType 2 RSA (RSA_ID_X509)
certs.push_cert_body(
tor_cert::CertType::RSA_ID_X509,
identities.cert_id_x509_rsa.clone(),
);
// Push into the cell the CertType 7 RSA (RSA_ID_V_IDENTITY)
certs.push_cert(&identities.cert_id_rsa);
// Push into the cell the CertType 4 Ed25519 (IDENTITY_V_SIGNING)
certs.push_cert(&identities.cert_id_sign_ed);
// Push into the cell the CertType 5/6 Ed25519
if is_responder {
// Responder has CertType 5 (SIGNING_V_TLS)
certs.push_cert(&identities.cert_sign_tls_ed);
// Initiator has CertType 6 (SIGINING_V_LINK_AUTH)
certs.push_cert(&identities.cert_sign_link_auth_ed);
certs
/// Build a [`msg::Netinfo`] cell from the given peer IPs and our advertised addresses.
pub(crate) fn build_netinfo_cell<S>(
peer_ip: Option<IpAddr>,
sleep_prov: &S,
) -> Result<msg::Netinfo>
// Unix timestamp but over 32bit. This will be sad in 2038 but proposal 338 addresses this
// issue with a change to 64bit.
let timestamp = sleep_prov
.wallclock()
.duration_since(UNIX_EPOCH)
.map_err(|e| internal!("Wallclock may have gone backwards: {e}"))?
.as_secs()
.try_into()
.map_err(|e| internal!("Wallclock secs fail to convert to 32bit: {e}"))?;
Ok(msg::Netinfo::from_relay(timestamp, peer_ip, my_addrs))