//! 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, /// 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, 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> { 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 { /// Constructor. 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( self, tls: T, sleep_prov: S, identities: Arc, my_addrs: Vec, peer: &OwnedChanTarget, memquota: ChannelAccount, ) -> RelayInitiatorHandshake 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( self, peer_addr: Sensitive, my_addrs: Vec, tls: T, sleep_prov: S, identities: Arc, memquota: ChannelAccount, ) -> RelayResponderHandshake where T: AsyncRead + AsyncWrite + CertifiedConn + StreamOps + Send + Unpin + 'static, S: CoarseTimeProvider + SleepProvider, { 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]> { match link_auth { 3 => Ok(b"EXPORTER FOR TOR TLS CLIENT BINDING AUTH0003"), _ => Err(Error::BadCellAuth), } } /// 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(&self, tls: &C) -> Result> { // 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( self, tls: &C, link_ed: &RelayLinkSigningKeypair, ) -> Result { // 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( auth_challenge_cell: &msg::AuthChallenge, identities: &Arc, clog: [u8; 32], slog: [u8; 32], verified: &mut VerifiedChannel, peer_cert_digest: [u8; 32], ) -> Result where T: AsyncRead + AsyncWrite + CertifiedConn + StreamOps + Send + Unpin + 'static, S: CoarseTimeProvider + SleepProvider, { // 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, }) } /// Build a [`ChannelAuthenticationData`] for an initiator channel handshake. /// /// `initiator_auth_type` is the authentication type from the [`msg::Authenticate`] received /// from the initiator. /// /// `identities` are our [`RelayIdentities`] /// /// `verified` is a [`VerifiedChannel`] which we need to consume the CLOG/SLOG /// /// `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( initiator_auth_type: u16, identities: &Arc, clog: [u8; 32], slog: [u8; 32], verified: &mut VerifiedChannel, our_cert_digest: [u8; 32], ) -> Result where T: AsyncRead + AsyncWrite + CertifiedConn + StreamOps + Send + Unpin + 'static, S: CoarseTimeProvider + SleepProvider, { // 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. 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, // Notice, everything is inversed here as the responder. cid: sid, sid: cid, cid_ed: sid_ed, sid_ed: cid_ed, clog, slog, 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( identities: &Arc, 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); } else { // 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. /// /// Both relay initiator and responder handshake use this. pub(crate) fn build_netinfo_cell( peer_ip: Option, my_addrs: Vec, sleep_prov: &S, ) -> Result where S: CoarseTimeProvider + SleepProvider, { // 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)) }