Rust STUN协议库stun-rs的使用：实现NAT穿透和网络地址转换的高效通信

创建和编码STUN绑定请求示例

// 创建属性
let username = UserName::new("\u{30DE}\u{30C8}\u{30EA}\u{30C3}\u{30AF}\u{30B9}")?;
let nonce = Nonce::new("f//499k954d6OL34oL9FSTvy64sA")?;
let realm = Realm::new("example.org")?;
let password = "TheMatrIX";
let algorithm = Algorithm::from(AlgorithmId::MD5);
let key = HMACKey::new_long_term(&username, &realm, password, algorithm)?;
let integrity = MessageIntegrity::new(key);

// 创建消息
let msg = StunMessageBuilder::new(
  BINDING,
  MessageClass::Request,
)
.with_attribute(username)
.with_attribute(nce)
.with_attribute(realm)
.with_attribute(integrity)
.build();

// 创建编码器将消息编码到缓冲区
let encoder = MessageEncoderBuilder::default().build();
let mut buffer: [u8; 150] = [0x00; 150];
let size = encoder.encode(&mut buffer, &msg)?;
assert_eq!(size, 116);

解码STUN绑定响应并获取属性示例

// 这个响应使用以下参数:
// 密码: `VOkJxbRl1RmTxUk/WvJxBt` (不带引号)
// 软件名称: "test vector" (不带引号)
// 映射地址: 192.0.2.1 端口 32853
let sample_ipv4_response = [
    0x01, 0x01, 0x00, 0x3c, // 响应类型和消息长度
    0x21, 0x12, 0xa4, 0x42, // Magic cookie
    0xb7, 0xe7, 0xa7, 0x01, // }
    0xbc, 0x34, 0xd6, 0x86, // }  事务ID
    0xfa, 0x87, 0xdf, 0xae, // }
    0x80, 0x22, 0x00, 0x0b, // SOFTWARE属性头
    0x74, 0x65, 0x73, 0x74, // }
    0x20, 0x76, 0x65, 0x63, // }  UTF-8服务器名称
    0x74, 0x6f, 0x72, 0x20, // }
    0x00, 0x20, 0x00, 0x08, // XOR-MAPPED-ADDRESS属性头
    0x00, 0x01, 0xa1, 0x47, // 地址族(IPv4)和异或映射的端口号
    0xe1, 0x12, 0xa6, 0x43, // 异或映射的IPv4地址
    0x00, 0x08, 0x00, 0x14, // MESSAGE-INTEGRITY头
    0x2b, 0x91, 0xf5, 0x99, // }
    0xfd, 0x9e, 0x90, 0xc3, // }
    0x8c, 0x74, 0x89, 0xf9, // } HMAC-SHA1指纹
    0x2a, 0xf9, 0xba, 0x53, // }
    0xf0, 0x6b, 0xe7, 0xd7, // }
    0x80, 0x28, 0x00, 0x04, // FINGERPRINT属性头
    0xc0, 0x7d, 0x4c, 0x96, // 保留用于CRC32指纹
];

// 使用密码作为短期凭证机制创建STUN解码器上下文
// 并强制验证MESSAGE-INTEGRITY和FINGERPRINT
let ctx = DecoderContextBuilder::default()
  .with_key(
    HMACKey::new_short_term("VOkJxbRl1RmTxUk/WvJxBt")?,
  )
  .with_validation()
  .build();
let decoder = MessageDecoderBuilder::default().with_context(ctx).build();

let (msg, size) = decoder.decode(&sample_ipv4_response)?;
assert_eq!(size, sample_ipv4_response.len());

// 检查消息方法是否为BINDING响应
assert_eq!(msg.method(), BINDING);
assert_eq!(msg.class(), MessageClass::SuccessResponse);

let software = msg.get::<Software>()
  .ok_or("Software attribute not found")?
  .as_software()?;
assert_eq!(software, "test vector");

let xor_addr = msg.get::<XorMappedAddress>()
  .ok_or("XorMappedAddress attribute not found")?
  .as_xor_mapped_address()?;
let socket = xor_addr.socket_address();
assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)));
assert_eq!(socket.port(), 32853);
assert!(socket.is_ipv4());

完整STUN客户端示例

use stun_rs::{
    Attribute, DecoderContextBuilder, MessageClass, MessageDecoderBuilder,
    MessageEncoderBuilder, StunMessageBuilder, XorMappedAddress,
};
use stun_rs::attributes::{MessageIntegrity, Nonce, Realm, UserName};
use stun_rs::crypto::{Algorithm, AlgorithmId, HMACKey};
use stun_rs::methods::BINDING;
use std::net::{IpAddr, Ipv4Addr, UdpSocket};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建UDP套接字
    let socket = UdpSocket::bind("0.0.0.0:0")?;
    
    // STUN服务器地址
    let stun_server = "stun.l.google.com:19302";
    
    // 构建STUN请求消息
    let msg = StunMessageBuilder::new(
        BINDING,
        MessageClass::Request,
    ).build();
    
    // 编码消息
    let encoder = MessageEncoderBuilder::default().build();
    let mut buffer = [0u8; 512];
    let size = encoder.encode(&mut buffer, &msg)?;
    
    // 发送STUN请求
    socket.send_to(&buffer[..size], stun_server)?;
    
    // 接收响应
    let mut response = [0u8; 512];
    let (len, _) = socket.recv_from(&mut response)?;
    
    // 解码响应
    let decoder = MessageDecoderBuilder::default().build();
    let (msg, _) = decoder.decode(&response[..len])?;
    
    // 获取映射地址
    if let Some(xor_addr) = msg.get::<XorMappedAddress>() {
        let xor_addr = xor_addr.as_xor_mapped_address()?;
        println!("Public address: {}", xor_addr.socket_address());
    } else {
        println!("No mapped address found in response");
    }
    
    Ok(())
}

常见功能特性

这个库定义了以下可启用的功能标志：

• discovery: 扩展支持解析RFC5780中定义的属性。NAT行为发现使用会话穿越NAT实用程序(STUN)。
• mobility: 扩展支持解析RFC8016中定义的属性。使用中继穿越NAT(TURN)的移动性。
• turn: 扩展支持解析RFC8656中定义的属性。使用中继穿越NAT(TURN)。
• ice: 扩展支持解析RFC8445中定义的属性。交互式连接建立(ICE)。
• experiments: 这个标志可以用来调整库的一些行为，比如默认填充。在测试协议时，我们可以使用这个标志强制库保留与未知属性相关的数据。默认情况下，未知属性不存储数据以节省内存消耗。

安装

在项目目录中运行以下Cargo命令：

cargo add stun-rs

或者在Cargo.toml中添加以下行：

stun-rs = "0.1.11"

许可证

这个项目采用以下任一许可证：

• Apache License, Version 2.0
• MIT license