stun-rs 0.1.11

Rust framework to manage STUN messages
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

pub trait HmacSha {
    fn hmac_sha(key: &[u8], message: &[u8]) -> Vec<u8>;
}

macro_rules! message_integrity_attribute {
    (
        $(#[$meta:meta])*
        $attr_class:ident,
        $attr_type:ident,
        $attr_size:ident
    ) => (
        paste::paste! {
            #[derive(Debug, Clone, PartialEq, Eq)]
            pub struct [<Encodable $attr_class>](crate::types::HMACKey);

            #[derive(Debug, Clone, PartialEq, Eq)]
            pub struct [<Decodable $attr_class>]([u8; $attr_size]);

            impl [<Decodable $attr_class>] {
                fn validate(&self, input: &[u8], key: &crate::types::HMACKey) -> bool {
                    let expected = $attr_class::hmac_sha(key.as_bytes(), input);
                    expected == self.0
                }
            }

            impl<'a> crate::Decode<'a> for [<Decodable $attr_class>] {
                fn decode(buffer: &[u8]) -> Result<(Self, usize), crate::StunError> {
                    crate::common::check_buffer_boundaries(buffer, $attr_size)?;
                    let hmac_sha1: [u8; $attr_size] = buffer.try_into()?;
                    Ok(([<Decodable $attr_class>](hmac_sha1), $attr_size))
                }
            }

            $(#[$meta])*
            #[derive(Debug, Clone, PartialEq, Eq)]
            pub enum $attr_class {
                /// Encodable version of this attribute. This is used when the attribute is added to a STUN message that is going to be sent to the network.
                Encodable([<Encodable $attr_class>]),
                /// Decodable version of this attribute. This is the decoded attribute received from the network.
                Decodable([<Decodable $attr_class>]),
            }

            impl $attr_class {
                /// Creates a new attribute.
                /// # Arguments:
                /// - `key` - The key used for the `HMAC` depends on which credential mechanism is in use.
                pub fn new(key: crate::types::HMACKey) -> Self {
                    $attr_class::Encodable([<Encodable $attr_class>](key))
                }

                #[doc = "Validates the message using the `HMAC` value generated from the key"]
                #[doc = "# Arguments:"]
                #[doc = "* `input`- the STUN message up to (but excluding) the [`" $attr_class "`] attribute itself."]
                #[doc = "* `key`- the [`HMACKey`](crate::types::HMACKey) key"]
                #[doc = "# Returns:"]
                #[doc = "true if the message integrity attribute matches the computed value."]
                pub fn validate(&self, input: &[u8], key: &crate::types::HMACKey) -> bool {
                    match self {
                        $attr_class::Decodable(attr) => attr.validate(input, key),
                        $attr_class::Encodable(_) => false,
                    }
                }
            }

            impl From<&[u8; $attr_size]> for $attr_class {
                fn from(val: &[u8; $attr_size]) -> Self {
                    $attr_class::Decodable([<Decodable $attr_class>](*val))
                }
            }

            impl From<[u8; $attr_size]> for $attr_class {
                fn from(val: [u8; $attr_size]) -> Self {
                    $attr_class::Decodable([<Decodable $attr_class>](val))
                }
            }

            impl crate::attributes::EncodeAttributeValue for $attr_class {
                fn encode(&self, mut ctx: crate::context::AttributeEncoderContext) -> Result<usize, crate::StunError> {
                    match self {
                        $attr_class::Encodable(_) => {
                            crate::common::check_buffer_boundaries(ctx.raw_value(), $attr_size)?;
                            let raw_value = ctx.raw_value_mut();
                            raw_value[0..$attr_size]
                                .iter_mut()
                                .for_each(|v| *v = 0);
                            Ok($attr_size)
                        }
                        _ => Err(crate::error::StunError::new(
                            crate::error::StunErrorType::InvalidParam,
                            format!("Not encodable attribute"),
                        )),
                    }
                }

                fn post_encode(&self, mut ctx: crate::context::AttributeEncoderContext) -> Result<(), crate::StunError> {
                    match self {
                        $attr_class::Encodable(attr) => {
                            crate::common::check_buffer_boundaries(ctx.raw_value(), $attr_size)?;
                            let hmac_sha = $attr_class::hmac_sha(attr.0.as_bytes(), ctx.encoded_message());
                            let raw_value = ctx.raw_value_mut();
                            raw_value[..$attr_size].copy_from_slice(&hmac_sha);
                            Ok(())
                        }
                        _ => Err(crate::error::StunError::new(
                            crate::error::StunErrorType::InvalidParam,
                            format!("Not encodable attribute"),
                        )),
                    }
                }
            }

            impl crate::attributes::DecodeAttributeValue for $attr_class {
                fn decode(ctx: crate::context::AttributeDecoderContext) -> Result<(Self, usize), crate::StunError> {
                    let (val, size) = [<Decodable $attr_class>]::decode(ctx.raw_value())?;
                    Ok(($attr_class::Decodable(val), size))
                }
            }
        } // paste

        impl crate::attributes::Verifiable for $attr_class {
            fn verify(&self, input: &[u8], ctx: &crate::DecoderContext) -> bool {
                match ctx.key() {
                    Some(k) => {
                        self.validate(input, k)
                    }
                    None => {
                        // HMACKey required for validation
                        false
                    }
                }
            }
        }

        impl crate::attributes::AsVerifiable for $attr_class {
            fn as_verifiable_ref(&self) -> Option<&dyn crate::attributes::Verifiable> {
                Some(self)
            }
        }

        crate::attributes::stunt_attribute!($attr_class, $attr_type);
    )
}

pub(crate) use message_integrity_attribute;