//! Different kinds of messages that can be encoded in channel cells.

use super::{BoxedCellBody, CELL_DATA_LEN, ChanCmd, RawCellBody};

use std::net::{IpAddr, Ipv4Addr};

use tor_basic_utils::skip_fmt;

use tor_bytes::{self, EncodeError, EncodeResult, Error, Readable, Reader, Result, Writer};

use tor_memquota::derive_deftly_template_HasMemoryCost;

use tor_units::IntegerMilliseconds;

use caret::caret_int;

use derive_deftly::Deftly;

use educe::Educe;

/// Trait for the 'bodies' of channel messages.

pub trait Body: Readable {

    /// Decode a channel cell body from a provided reader.

    /// Consume this message and encode its body onto `w`.

    ///

    /// Does not encode anything _but_ the cell body, and does not pad

    /// to the cell length.

    fn encode_onto<W: Writer + ?Sized>(self, w: &mut W) -> EncodeResult<()>;

}

crate::restrict::restricted_msg! {

/// Decoded message from a channel.

///

/// A ChanMsg is an item received on a channel -- a message from

/// another Tor client or relay that we are connected to directly over

/// a TLS connection.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

#[non_exhaustive]

@omit_from "avoid_conflict_with_a_blanket_implementation"

pub enum AnyChanMsg : ChanMsg {

    /// A Padding message

    Padding,

    /// Variable-length padding message

    Vpadding,

    /// (Deprecated) TAP-based cell to create a new circuit.

    Create,

    /// (Mostly deprecated) HMAC-based cell to create a new circuit.

    CreateFast,

    /// Cell to create a new circuit

    Create2,

    /// (Deprecated) Answer to a Create cell

    Created,

    /// (Mostly Deprecated) Answer to a CreateFast cell

    CreatedFast,

    /// Answer to a Create2 cell

    Created2,

    /// A message sent along a circuit, likely to a more-distant relay.

    Relay,

    /// A message sent along a circuit (limited supply)

    RelayEarly,

    /// Tear down a circuit

    Destroy,

    /// Part of channel negotiation: describes our position on the network

    Netinfo,

    /// Part of channel negotiation: describes what link protocol versions

    /// we support

    Versions,

    /// Negotiates what kind of channel padding to send

    PaddingNegotiate,

    /// Part of channel negotiation: additional certificates not in the

    /// TLS handshake

    Certs,

    /// Part of channel negotiation: additional random material to be used

    /// as part of authentication

    AuthChallenge,

    /// Part of channel negotiation: used to authenticate relays when they

    /// initiate the channel.

    Authenticate,

    _ =>

    /// Any cell whose command we don't recognize

    Unrecognized,

}

}

/// A Padding message is a fixed-length message on a channel that is

/// ignored.

///

/// Padding message can be used to disguise the true amount of data on a

/// channel, or as a "keep-alive".

///

/// The correct response to a padding cell is to drop it and do nothing.

#[derive(Clone, Debug, Default, Deftly)]

#[derive_deftly(HasMemoryCost)]

#[non_exhaustive]

pub struct Padding {}

impl Padding {

    /// Create a new fixed-length padding cell

}

impl Body for Padding {

}

impl Readable for Padding {

}

/// A VPadding message is a variable-length padding message.

///

/// The correct response to a padding cell is to drop it and do nothing.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Vpadding {

    /// How much padding to send in this cell's body.

    len: u16,

}

impl Vpadding {

    /// Return a new vpadding cell with given length.

}

impl Body for Vpadding {

}

impl Readable for Vpadding {

}

/// helper -- declare a fixed-width cell for handshake commands, in which

/// a fixed number of bytes matter and the rest are ignored

macro_rules! fixed_len_handshake {

    {

        $(#[$meta:meta])*

        $name:ident , $cmd:ident, $len:ident

    } => {

        $(#[$meta])*

        #[derive(Clone,Debug,Deftly)]

        #[derive_deftly(HasMemoryCost)]

        pub struct $name {

            handshake: Vec<u8>

        }

        impl $name {

            /// Create a new cell from a provided handshake.

            {

        }

        impl Body for $name {

        }

        impl Readable for $name {

                Ok($name {

                })

        }

    }

}

/// Number of bytes used for a TAP handshake by the initiator.

pub(crate) const TAP_C_HANDSHAKE_LEN: usize = 128 + 16 + 42;

/// Number of bytes used for a TAP handshake response

pub(crate) const TAP_S_HANDSHAKE_LEN: usize = 128 + 20;

/// Number of bytes used for a CREATE_FAST handshake by the initiator

const FAST_C_HANDSHAKE_LEN: usize = 20;

/// Number of bytes used for a CREATE_FAST handshake response

const FAST_S_HANDSHAKE_LEN: usize = 20 + 20;

fixed_len_handshake! {

    /// A Create message creates a circuit, using the TAP handshake.

    ///

    /// TAP is an obsolete handshake based on RSA-1024 and DH-1024.

    /// Relays respond to Create message with a Created reply on

    /// success, or a Destroy message on failure.

    ///

    /// In Tor today, Create is only used for the deprecated v2 onion

    /// service protocol.

    Create, CREATE, TAP_C_HANDSHAKE_LEN

}

fixed_len_handshake! {

    /// A Created message responds to a Created message, using the TAP

    /// handshake.

    ///

    /// TAP is an obsolete handshake based on RSA-1024 and DH-1024.

    Created, CREATED, TAP_S_HANDSHAKE_LEN

}

fixed_len_handshake! {

    /// A CreateFast message creates a circuit using no public-key crypto.

    ///

    /// CreateFast is safe only when used on an already-secure TLS

    /// connection.  It can only be used for the first hop of a circuit.

    ///

    /// Relays reply to a CreateFast message with CreatedFast on

    /// success, or a Destroy message on failure.

    ///

    /// This handshake was originally used for the first hop of every

    /// circuit.  Nowadays it is used for creating one-hop circuits

    /// when we don't know any onion key for the first hop.

    CreateFast, CREATE_FAST, FAST_C_HANDSHAKE_LEN

}

impl CreateFast {

    /// Return the content of this handshake

}

fixed_len_handshake! {

    /// A CreatedFast message responds to a CreateFast message

    ///

    /// Relays send this message back to indicate that the CrateFast handshake

    /// is complete.

    CreatedFast, CREATED_FAST, FAST_S_HANDSHAKE_LEN

}

impl CreatedFast {

    /// Consume this message and return the content of this handshake

}

caret_int! {

    /// Handshake type, corresponding to [`HTYPE` in

    /// tor-spec](https://spec.torproject.org/tor-spec/create-created-cells.html).

    #[derive(Deftly)]

    #[derive_deftly(HasMemoryCost)]

    pub struct HandshakeType(u16) {

        /// [TAP](https://spec.torproject.org/tor-spec/create-created-cells.html#TAP) -- the original Tor handshake.

        TAP = 0,

        // 1 is reserved

        /// [ntor](https://spec.torproject.org/tor-spec/create-created-cells.html#ntor) -- the ntor+curve25519+sha256 handshake.

        NTOR = 2,

        /// [ntor-v3](https://spec.torproject.org/tor-spec/create-created-cells.html#ntor-v3) -- ntor extended with extra data.

        NTOR_V3 = 3,

    }

}

/// A Create2 message create a circuit on the current channel.

///

/// To create a circuit, the client sends a Create2 cell containing a

/// handshake of a given type; the relay responds with a Created2 cell

/// containing a reply.

///

/// Currently, most Create2 cells contain a client-side instance of the

/// "ntor" handshake.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Create2 {

    /// Identifier for what kind of handshake this is.

    handshake_type: HandshakeType,

    /// Body of the handshake.

    handshake: Vec<u8>,

}

impl Body for Create2 {

}

impl Readable for Create2 {

}

impl Create2 {

    /// Wrap a typed handshake as a Create2 message

    {

    /// Return the type of this handshake.

    /// Return the body of this handshake.

}

/// A Created2 message completes a circuit-creation handshake.

///

/// When a relay receives a valid Create2 message that it can handle, it

/// establishes the circuit and replies with a Created2.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Created2 {

    /// Body of the handshake reply

    handshake: Vec<u8>,

}

impl Created2 {

    /// Create a new Created2 to hold a given handshake.

    {

    /// Consume this created2 cell and return its body.

}

impl Body for Created2 {

}

impl Readable for Created2 {

}

/// A Relay cell - that is, one transmitted over a circuit.

///

/// Once a circuit has been established, relay cells can be sent over

/// it.  Clients can send relay cells to any relay on the circuit. Any

/// relay on the circuit can send relay cells to the client, either

/// directly (if it is the first hop), or indirectly through the

/// intermediate hops.

///

/// A different protocol is defined over the relay cells; it is implemented

/// in the [crate::relaycell] module.

#[derive(Clone, Educe, derive_more::From, Deftly)]

#[derive_deftly(HasMemoryCost)]

#[educe(Debug)]

pub struct Relay {

    /// The contents of the relay cell as encoded for transfer.

    ///

    /// TODO(nickm): It's nice that this is boxed, since we don't want to copy

    /// cell data all over the place. But unfortunately, there are some other

    /// places where we _don't_ Box things that we should, and more copies than

    /// necessary happen. We should refactor our data handling until we're mostly

    /// moving around pointers rather than copying data;  see ticket #7.

    #[educe(Debug(method = "skip_fmt"))]

    body: BoxedCellBody,

}

impl Relay {

    /// Construct a Relay message from a slice containing its contents.

    {

        // TODO: This will panic if body is too long, but that would be a

        // programming error anyway.

    /// Construct a Relay message from its body.

    /// Consume this Relay message and return a BoxedCellBody for

    /// encryption/decryption.

    /// Wrap this Relay message into a RelayMsg as a RELAY_EARLY cell.

}

impl Body for Relay {

}

impl Readable for Relay {

}

/// A Relay cell that is allowed to contain a CREATE message.

///

/// Only a limited number of these may be sent on each circuit.

#[derive(Clone, Debug, derive_more::Deref, derive_more::From, derive_more::Into, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct RelayEarly(Relay);

impl Readable for RelayEarly {

}

impl Body for RelayEarly {

}

impl RelayEarly {

    /// Consume this RelayEarly message and return a BoxedCellBody for

    /// encryption/decryption.

    //

    // (Since this method takes `self` by value, we can't take advantage of

    // Deref.)

}

/// The Destroy message tears down a circuit.

///

/// On receiving a Destroy message, a Tor implementation should

/// tear down the associated circuit, and pass the destroy message

/// down the circuit to later/earlier hops on the circuit (if any).

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Destroy {

    /// Reason code given for tearing down this circuit

    reason: DestroyReason,

}

impl Destroy {

    /// Create a new destroy cell.

    ///

    /// If generating a new destroy cell,

    /// you should always create it with [`DestroyReason::NONE`].

    ///

    /// `tor-spec/tearing-down-circuits.md`:

    ///

    /// > Implementations SHOULD always use the NONE reason to avoid side channels: [...]

    /// Return the provided reason for destroying the circuit.

}

impl Body for Destroy {

}

impl Readable for Destroy {

}

caret_int! {

    /// Declared reason for ending a circuit.

    #[derive(Deftly)]

    #[derive_deftly(HasMemoryCost)]

    pub struct DestroyReason(u8) {

        /// No reason given.

        ///

        /// This is the only reason that clients send.

        NONE = 0,

        /// Protocol violation

        PROTOCOL = 1,

        /// Internal error.

        INTERNAL = 2,

        /// Client sent a TRUNCATE command.

        REQUESTED = 3,

        /// Relay is hibernating and not accepting requests

        HIBERNATING = 4,

        /// Ran out of memory, sockets, or circuit IDs

        RESOURCELIMIT = 5,

        /// Couldn't connect to relay.

        CONNECTFAILED = 6,

        /// Connected to a relay, but its OR identity wasn't as requested.

        OR_IDENTITY = 7,

        /// One of the OR channels carrying this circuit died.

        CHANNEL_CLOSED = 8,

        /// Circuit expired for being too dirty or old

        FINISHED = 9,

        /// Circuit construction took too long

        TIMEOUT = 10,

        /// Circuit was destroyed w/o client truncate (?)

        DESTROYED = 11,

        /// Request for unknown onion service

        NOSUCHSERVICE = 12

    }

}

impl DestroyReason {

    /// Return a human-readable string for this reason.

        }

}

/// The netinfo message ends channel negotiation.

///

/// It tells the other party on the channel our view of the current time,

/// our own list of public addresses, and our view of its address.

///

/// When we get a netinfo cell, we can start creating circuits on a

/// channel and sending data.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Netinfo {

    /// Time when this cell was sent, or 0 if this cell is sent by a client.

    ///

    /// TODO-SPEC(nickm): Y2038 issue here.  Better add a new handshake version

    /// to solve it.  See

    /// [torspec#80](https://gitlab.torproject.org/tpo/core/torspec/-/issues/80).

    timestamp: u32,

    /// Observed address for party that did not send the netinfo cell.

    their_addr: Option<IpAddr>,

    /// Canonical addresses for the party that did send the netinfo cell.

    my_addr: Vec<IpAddr>,

}

/// helper: encode a single address in the form that netinfo messages expect

    }

/// helper: take an address as encoded in a netinfo message

        (0x04, 4) => {

        }

        (0x06, 16) => {

            // TODO(nickm) is there a better way?

        }

    }

impl Netinfo {

    /// Construct a new Netinfo to be sent by a client.

    /// Construct a new Netinfo to be sent by a relay

    {

    /// Return the time reported in this NETINFO cell.

        use std::time::{Duration, SystemTime};

        } else {

        }

    /// Return a reference to the their address field.

    ///

    /// None is returned if their address is 0.0.0.0/:: (unspecified).

    /// Return a reference to the my address field.

}

impl Body for Netinfo {

}

impl Readable for Netinfo {

        }

}

/// A Versions message begins channel negotiation.

///

/// Every channel must begin by sending a Versions message.  This message

/// lists the link protocol versions that this Tor implementation supports.

///

/// Note that we should never actually send Versions cells using the

/// usual channel cell encoding: Versions cells _always_ use two-byte

/// circuit IDs, whereas all the other cell types use four-byte

/// circuit IDs [assuming a non-obsolete version is negotiated].

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Versions {

    /// List of supported link protocol versions

    versions: Vec<u16>,

}

impl Versions {

    /// Construct a new Versions message using a provided list of link

    /// protocols.

    ///

    /// Returns an error if the list of versions is too long.

    {

        } else {

        }

    /// Encode this VERSIONS cell in the manner expected for a handshake.

    ///

    /// (That's different from a standard cell encoding, since we

    /// have not negotiated versions yet, and so our circuit-ID length

    /// is an obsolete 2 bytes).

    /// Return the best (numerically highest) link protocol that is

    /// shared by this versions cell and my_protos.

        // NOTE: this implementation is quadratic, but it shouldn't matter

        // much so long as my_protos is small.

}

impl Body for Versions {

}

impl Readable for Versions {

        }

}

caret_int! {

    /// A ChanCmd is the type of a channel cell.  The value of the ChanCmd

    /// indicates the meaning of the cell, and (possibly) its length.

    #[derive(Deftly)]

    #[derive_deftly(HasMemoryCost)]

    pub struct PaddingNegotiateCmd(u8) {

        /// Start padding

        START = 2,

        /// Stop padding

        STOP = 1,

    }

}

/// A PaddingNegotiate message is used to negotiate channel padding.

///

/// Sent by a client to its guard node,

/// to instruct the relay to enable/disable channel padding.

/// (Not relevant for channels used only for directory lookups,

/// nor inter-relay channels.)

/// See `padding-spec.txt`, section 2.2.

///

/// This message is constructed in the channel manager and transmitted by the reactor.

///

/// The `Default` impl is the same as [`start_default()`](PaddingNegotiate::start_default`)

#[derive(Clone, Debug, Eq, PartialEq, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct PaddingNegotiate {

    /// Whether to start or stop padding

    command: PaddingNegotiateCmd,

    /// Suggested lower-bound value for inter-packet timeout in msec.

    // TODO(nickm) is that right?

    ito_low_ms: u16,

    /// Suggested upper-bound value for inter-packet timeout in msec.

    // TODO(nickm) is that right?

    ito_high_ms: u16,

}

impl PaddingNegotiate {

    /// Create a new PADDING_NEGOTIATE START message requesting consensus timing parameters.

    ///

    /// This message restores the state to the one which exists at channel startup.

        // Tor Spec section 7.3, padding-spec section 2.5.

    /// Create a new PADDING_NEGOTIATE START message.

        // Tor Spec section 7.3

    /// Create a new PADDING_NEGOTIATE STOP message.

        // Tor Spec section 7.3

    /// Construct from the three fields: command, low_ms, high_ms, as a tuple

    ///

    /// For testing only

    #[cfg(feature = "testing")]

}

impl Default for PaddingNegotiate {

}

impl Body for PaddingNegotiate {

}

impl Readable for PaddingNegotiate {

}

/// A single certificate in a Certs cell.

///

/// The formats used here are implemented in tor-cert. Ed25519Cert is the

/// most common.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

struct TorCert {

    /// Type code for this certificate.

    certtype: u8,

    /// Encoded certificate

    cert: Vec<u8>,

}

/// encode a single TorCert `c` onto a Writer `w`.

/// Try to extract a TorCert from the reader `r`.

/// A Certs message is used as part of the channel handshake to send

/// additional certificates.

///

/// These certificates are not presented as part of the TLS handshake.

/// Originally this was meant to make Tor TLS handshakes look "normal", but

/// nowadays it serves less purpose, especially now that we have TLS 1.3.

///

/// Every relay sends this message as part of channel negotiation;

/// clients do not send them.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Certs {

    /// The certificates in this cell

    certs: Vec<TorCert>,

}

impl Certs {

    /// Return a new empty certs cell.

    /// Add a new encoded certificate to this cell.

    ///

    /// Does not check anything about the well-formedness of the certificate.

    {

    /// Add a new encoded certificate to this cell,

    /// taking taking the type from the certificate itself.

    #[cfg(feature = "relay")]

    {

    /// Return the body of the certificate tagged with 'tp', if any.

    /// Look for a certificate of type 'tp' in this cell; return it if

    /// there is one.

            parsed: "ed25519 certificate",

}

impl Body for Certs {

        }

}

impl Readable for Certs {

        }

}

/// Length of the body for an authentication challenge

const CHALLENGE_LEN: usize = 32;

/// An AuthChallenge message is part of negotiation, sent by

/// responders to initiators.

///

/// The AuthChallenge cell is used to ensure that some unpredictable material

/// has been sent on the channel, and to tell the initiator what

/// authentication methods will be accepted.

///

/// Clients can safely ignore this message: they don't need to authenticate.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct AuthChallenge {

    /// Random challenge to be used in generating response

    challenge: [u8; CHALLENGE_LEN],

    /// List of permitted authentication methods

    methods: Vec<u16>,

}

impl AuthChallenge {

    /// Construct a new AuthChallenge cell with a given challenge

    /// value (chosen randomly) and a set of acceptable authentication methods.

    {

    /// Return a reference to the list of methods.

}

impl Body for AuthChallenge {

}

impl Readable for AuthChallenge {

        //let challenge = r.take(CHALLENGE_LEN)?.into();

        }

}

/// Part of negotiation: sent by initiators to responders.

///

/// The Authenticate cell proves the initiator's identity to the

/// responder, even if TLS client authentication was not used.

///

/// Clients do not use this.

#[derive(Clone, Debug, Deftly, Eq, PartialEq)]

#[derive_deftly(HasMemoryCost)]

pub struct Authenticate {

    /// Authentication method in use

    authtype: u16,

    /// Encoded authentication object

    auth: Vec<u8>,

}

impl Authenticate {

    /// The signature field length.

    const SIG_LEN: usize = 64;

    /// The body length that is all fields except the rand and signature.

    pub const BODY_LEN: usize = 264;

    /// Create a new Authenticate message from a given type and body.

    {

    /// Return the authentication type value.

    /// Return a referrence to the body of the cell that is all fields minus the random bytes

    /// located before the signature.

        // The RAND field length.

        const RAND_LEN: usize = 24;

    /// Return a referrence to the body of the cell that is all fields except the signature.

    /// Return a reference to the authentcation object.

    /// Return a reference to the signature bytes.

}

impl Body for Authenticate {

}

impl Readable for Authenticate {

}

/// Holds any message whose command we don't recognize.

///

/// Well-behaved Tor implementations are required to ignore commands

/// like this.

///

/// TODO: I believe that this is not a risky case of Postel's law,

/// since it is only for channels, but we should be careful here.

#[derive(Clone, Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Unrecognized {

    /// The channel command that we got with this cell

    cmd: ChanCmd,

    /// The contents of the cell

    content: Vec<u8>,

}

impl Unrecognized {

    /// Construct a new cell of arbitrary or unrecognized type.

    {

    /// Return the command from this cell.

    /// Take an unrecognized cell's body from a reader `r`, and apply

    /// the given command to it.

}

impl Body for Unrecognized {

}

impl Readable for Unrecognized {

        Ok(Unrecognized {

        })

}

/// Helper: declare a From<> implementation from message types for

/// cells that don't take a circid.

macro_rules! msg_into_cell {

    ($body:ident) => {

        impl From<$body> for super::AnyChanCell {

        }

    };

}

msg_into_cell!(Padding);

msg_into_cell!(Vpadding);

msg_into_cell!(Netinfo);

msg_into_cell!(Versions);

msg_into_cell!(PaddingNegotiate);

msg_into_cell!(Certs);

msg_into_cell!(AuthChallenge);

msg_into_cell!(Authenticate);

/// Helper: declare a ChanMsg implementation for a message type that has a

/// fixed command.

//

// TODO: It might be better to merge Body with ChanMsg, but that is complex,

// since their needs are _slightly_ different.

//

// TODO: If we *do* make the change above, then perhaps we should also implement

// our restricted enums in terms of this, so that there is only one instance of

// [<$body:snake:upper>]

macro_rules! msg_impl_chanmsg {

    ($($body:ident,)*) =>

    {paste::paste!{

       $(impl crate::chancell::ChanMsg for $body {

        })*

    }}

}

// We implement ChanMsg for every body type, so that you can write code that does

// e.g. ChanCell<Relay>.

msg_impl_chanmsg!(

    Padding,

    Vpadding,

    Create,

    CreateFast,

    Create2,

    Created,

    CreatedFast,

    Created2,

    Relay,

    RelayEarly,

    Destroy,

    Netinfo,

    Versions,

    PaddingNegotiate,

    Certs,

    AuthChallenge,

    Authenticate,

);

#[cfg(test)]

mod test {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_time_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    #![allow(clippy::string_slice)] // See arti#2571

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    #[test]

    fn destroy_reason() {

        let r1 = DestroyReason::CONNECTFAILED;

        assert_eq!(r1.human_str(), "Couldn't connect to relay");