|
6 | 6 | // option. This file may not be copied, modified, or distributed |
7 | 7 | // except according to those terms. |
8 | 8 |
|
| 9 | +//! # stun-proto |
| 10 | +//! |
| 11 | +//! A sans-IO implementation of a STUN agent as specified in [RFC5389] and [RFC8489]. |
| 12 | +//! |
| 13 | +//! [RFC8489]: https://tools.ietf.org/html/rfc8489 |
| 14 | +//! [RFC5389]: https://tools.ietf.org/html/rfc5389 |
| 15 | +//! |
| 16 | +//! ## Example |
| 17 | +//! |
| 18 | +//! ``` |
| 19 | +//! # use std::net::SocketAddr; |
| 20 | +//! use stun_proto::types::TransportType; |
| 21 | +//! use stun_proto::types::attribute::{MessageIntegrity, XorMappedAddress}; |
| 22 | +//! use stun_proto::types::message::{ |
| 23 | +//! BINDING, IntegrityAlgorithm, Message, MessageIntegrityCredentials, ShortTermCredentials |
| 24 | +//! }; |
| 25 | +//! use stun_proto::agent::{HandleStunReply, StunAgent}; |
| 26 | +//! let local_addr = "10.0.0.1:12345".parse().unwrap(); |
| 27 | +//! let remote_addr = "10.0.0.2:3478".parse().unwrap(); |
| 28 | +//! |
| 29 | +//! let mut agent = StunAgent::builder(TransportType::Udp, local_addr).build(); |
| 30 | +//! |
| 31 | +//! // short term or short term credentials may optionally be configured on the agent. |
| 32 | +//! let local_credentials = ShortTermCredentials::new(String::from("local_password")); |
| 33 | +//! let remote_credentials = ShortTermCredentials::new(String::from("remote_password")); |
| 34 | +//! agent.set_local_credentials(local_credentials.clone().into()); |
| 35 | +//! agent.set_remote_credentials(remote_credentials.clone().into()); |
| 36 | +//! |
| 37 | +//! // and we can send a Message |
| 38 | +//! let mut msg = Message::new_request(BINDING); |
| 39 | +//! msg.add_message_integrity(&local_credentials.clone().into(), IntegrityAlgorithm::Sha1).unwrap(); |
| 40 | +//! let transmit = agent.send(msg, remote_addr).unwrap(); |
| 41 | +//! |
| 42 | +//! // The transmit struct indicates what data and where to send it. |
| 43 | +//! let request = Message::from_bytes(&transmit.data).unwrap(); |
| 44 | +//! |
| 45 | +//! let mut response = Message::new_success(&request); |
| 46 | +//! let xor_addr = XorMappedAddress::new(transmit.from, request.transaction_id()); |
| 47 | +//! response.add_attribute(xor_addr).unwrap(); |
| 48 | +//! response.add_message_integrity(&remote_credentials.clone().into(), IntegrityAlgorithm::Sha1).unwrap(); |
| 49 | +//! |
| 50 | +//! // when receiving data on the associated socket, we should pass it through the Agent so it can |
| 51 | +//! // parse and handle any STUN messages. |
| 52 | +//! let data = response.to_bytes(); |
| 53 | +//! let to = transmit.to; |
| 54 | +//! let reply = agent.handle_incoming_data(&data, to).unwrap(); |
| 55 | +//! |
| 56 | +//! // If running over TCP then there may be multiple messages parsed. However UDP will only ever |
| 57 | +//! // have a single message per datagram. |
| 58 | +//! assert!(matches!(reply[0], HandleStunReply::StunResponse(_, _))); |
| 59 | +//! |
| 60 | +//! // Once valid STUN data has been sent and received, then data can be sent and received from the |
| 61 | +//! // peer. |
| 62 | +//! let data = vec![42; 8]; |
| 63 | +//! let transmit = agent.send_data(&data, remote_addr); |
| 64 | +//! assert_eq!(transmit.data(), &data); |
| 65 | +//! assert_eq!(transmit.from, local_addr); |
| 66 | +//! assert_eq!(transmit.to, remote_addr); |
| 67 | +//! ``` |
| 68 | +
|
9 | 69 | pub mod agent; |
10 | 70 |
|
11 | | -// reexport stun_types; |
12 | 71 | pub use stun_types as types; |
13 | 72 |
|
14 | 73 | #[derive(Clone)] |
|
0 commit comments