mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document textual format of SocketAddrV{4,6}

Browse Source 
This commit adds new "Textual representation" documentation sections to
SocketAddrV4 and SocketAddrV6, by analogy to the existing
"textual representation" sections of Ipv4Addr and Ipv6Addr.

Rationale: Without documentation about which formats are actually
accepted, it's hard for a programmer to be sure that their code
will actually behave as expected when implementing protocols that
require support (or rejection) for particular representations.
This lack of clarity can in turn can lead to ambiguities and
security problems like those discussed in RFC 6942.

(I've tried to describe the governing RFCs or standards where I
could, but it's possible that the actual implementers had something
else in mind.  I could not find any standards that corresponded
_exactly_ to the one implemented in SocketAddrv6, but I have linked
the relevant documents that I could find.)
This commit is contained in:
Nick Mathewson 2024-10-16 09:34:34 -04:00
parent d829780c4e
commit 0e5c5a2596
1 changed files with 39 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
library/core/src/net/socket_addr.rs
View File

@ -49,6 +49,15 @@ pub enum SocketAddr {
/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
/// [`IPv4` address]: Ipv4Addr
///
/// # Textual representation
///
/// `SocketAddrV4` provides a [`FromStr`](crate::str::FromStr) implementation.
/// It accepts an IPv4 address in its [textual representation], followed by a
/// single `:`, followed by the port encoded as a decimal integer. Other
/// formats are not accepted.
///
/// [textual representation]: Ipv4Addr#textual-representation
///
/// # Examples
///
/// ```
@ -82,6 +91,32 @@ pub struct SocketAddrV4 {
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
/// [`IPv6` address]: Ipv6Addr
///
/// # Textual representation
///
/// `SocketAddrV6` provides a [`FromStr`](crate::str::FromStr) implementation,
/// based on the bracketed format recommended by [IETF RFC 5952],
/// with scope identifiers based on those specified in [IETF RFC 4007].
///
/// It accepts addresses consisting of the following elements, in order:
/// - A left square bracket (`[`)
/// - The [textual representation] of an IPv6 address
/// - _Optionally_, a percent sign (`%`) followed by the scope identifier
/// encoded as a decimal integer
/// - A right square bracket (`]`)
/// - A colon (`:`)
/// - The port, encoded as a decimal integer.
///
/// For example, the string `[2001:db8::413]:443` represents a `SocketAddrV6`
/// with the address `2001:db8::413` and port `443`. The string
/// `[2001:db8::413%612]:443` represents the same address and port, with a
/// scope identifier of `612`.
///
/// Other formats are not accepted.
///
/// [IETF RFC 5952]: https://tools.ietf.org/html/rfc5952#section-6
/// [IETF RFC 4007]: https://tools.ietf.org/html/rfc4007#section-11
/// [textual representation]: Ipv6Addr#textual-representation
///
/// # Examples
///
/// ```
@ -92,6 +127,10 @@ pub struct SocketAddrV4 {
/// assert_eq!("[2001:db8::1]:8080".parse(), Ok(socket));
/// assert_eq!(socket.ip(), &Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
/// assert_eq!(socket.port(), 8080);
///
/// let mut with_scope = socket.clone();
/// with_scope.set_scope_id(3);
/// assert_eq!("[2001:db8::1%3]:8080".parse(), Ok(with_scope));
/// ```
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
#[stable(feature = "rust1", since = "1.0.0")]