evan/protomask
1
Fork 0
Code

Document rfc6052 crate

Browse Source
This commit is contained in:
Evan Pratten 2023-08-04 18:20:56 -04:00
parent ba2072582f
commit 0e73584801
6 changed files with 141 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
.vscode/tasks.json vendored
View File

@ -27,6 +27,21 @@
"group": "test",
"label": "rust: cargo test"
},
{
"type": "cargo",
"command": "doc",
"args": [
"--no-deps",
"--workspace",
"--document-private-items"
],
"problemMatcher": [
"$rustc",
"$rust-panic"
],
"group": "build",
"label": "rust: cargo doc"
},
{
"type": "shell",
"command": "zola",

32
libs/rfc6052/README.md
View File

@ -2,4 +2,34 @@
[![Crates.io](https://img.shields.io/crates/v/rfc6052)](https://crates.io/crates/rfc6052)
[![Docs.rs](https://docs.rs/rfc6052/badge.svg)](https://docs.rs/rfc6052)
This library provides functions for interacting with [RFC6052](https://datatracker.ietf.org/doc/html/rfc6052) IPv4-Embedded IPv6 Addresses.
[RFC6052](https://datatracker.ietf.org/doc/html/rfc6052) defines *"the algorithmic translation of an IPv6 address to a corresponding IPv4 address, and vice versa, using only statically configured information"*. In simpler terms, this means *embedding IPv4 address into IPv6 addresses*. The primary use case of which being NAT64 translators.
The RFC defines the following scheme for embedding IPv4 addresses into IPv6 addresses:
```text
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|PL| 0-------------32--40--48--56--64--72--80--88--96--104---------|
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|32| prefix |v4(32) | u | suffix |
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|40| prefix |v4(24) | u |(8)| suffix |
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|48| prefix |v4(16) | u | (16) | suffix |
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|56| prefix |(8)| u | v4(24) | suffix |
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|64| prefix | u | v4(32) | suffix |
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|96| prefix | v4(32) |
+--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
```
- `PL` is the prefix length
- `u` is a reserved byte that **must** be set to `0`
## Safe vs. Unsafe
This library provides both a "regular" and "unchecked" version of the functions for embedding and extracting IPv4 addresses from IPv6 addresses.
The "regular" functions enforce the restricted set of IPv6 prefix lengths allowed by the RFC (32, 40, 48, 56, 64, and 96 bits long). The "unchecked" functions do not enforce this restriction, and will happily accept any prefix length at the cost of non-compliance with the RFC.

48
libs/rfc6052/src/embed.rs
View File

@ -1,3 +1,5 @@
//! IPv4 address embedding functions
use ipnet::Ipv6Net;
use std::cmp::{max, min};
use std::net::{Ipv4Addr, Ipv6Addr};
@ -6,6 +8,32 @@ use crate::error::Error;
use crate::ALLOWED_PREFIX_LENS;
/// Embeds an IPv4 address into an IPv6 prefix following the method defined in [RFC6052 Section 2.2](https://datatracker.ietf.org/doc/html/rfc6052#section-2.2)
///
/// # Examples
///
/// ```
/// # use ipnet::{Ipv6Net};
/// # use std::net::{Ipv4Addr, Ipv6Addr};
/// use rfc6052::embed_ipv4_addr;
///
/// // An IPv4 address can be embedded into an IPv6 prefix of acceptable length
/// assert_eq!(
/// embed_ipv4_addr(
/// "192.0.2.1".parse().unwrap(),
/// "64:ff9b::/32".parse().unwrap()
/// ),
/// Ok("64:ff9b:c000:0201::".parse::<Ipv6Addr>().unwrap())
/// );
///
/// // Using a prefix that is not an RFC-approved length (in this case 66) will fail
/// assert_eq!(
/// embed_ipv4_addr(
/// "192.0.2.1".parse().unwrap(),
/// "64:ff9b::/66".parse().unwrap()
/// ),
/// Err(rfc6052::Error::InvalidPrefixLength(66))
/// );
/// ```
pub fn embed_ipv4_addr(ipv4_addr: Ipv4Addr, ipv6_prefix: Ipv6Net) -> Result<Ipv6Addr, Error> {
// Fail if the prefix length is invalid
if !ALLOWED_PREFIX_LENS.contains(&ipv6_prefix.prefix_len()) {
@ -19,6 +47,26 @@ pub fn embed_ipv4_addr(ipv4_addr: Ipv4Addr, ipv6_prefix: Ipv6Net) -> Result<Ipv6
/// Embeds an IPv4 address into an IPv6 prefix following the method defined in [RFC6052 Section 2.2](https://datatracker.ietf.org/doc/html/rfc6052#section-2.2)
///
/// **Warning:** This function does not check that the prefix length is valid according to the RFC. Use `embed_ipv4_addr` instead.
///
/// # Examples
///
/// ```
/// # use ipnet::{Ipv6Net};
/// # use std::net::{Ipv4Addr, Ipv6Addr};
/// use rfc6052::embed_ipv4_addr_unchecked;
///
/// // Using a prefix that is not an RFC-approved length (in this case 66) will *succeed*
/// // This is *not* the behavior of `embed_ipv4_addr`
/// assert_eq!(
/// unsafe {
/// embed_ipv4_addr_unchecked(
/// "192.0.2.1".parse().unwrap(),
/// "64:ff9b::/66".parse().unwrap()
/// )
/// },
/// "64:ff9b::30:0:8040:0".parse::<Ipv6Addr>().unwrap()
/// );
/// ```
#[must_use]
#[allow(clippy::cast_lossless)]
#[allow(clippy::cast_possible_truncation)]

2
libs/rfc6052/src/error.rs
View File

@ -1,6 +1,6 @@
//! Error types for this library
#[derive(Debug, thiserror::Error)]
#[derive(Debug, thiserror::Error, PartialEq)]
pub enum Error {
#[error("Invalid IPv6 prefix length: {0}. Must be one of 32, 40, 48, 56, 64, or 96")]
InvalidPrefixLength(u8),

35
libs/rfc6052/src/extract.rs
View File

@ -1,8 +1,29 @@
//! IPv4 address extraction functions
use crate::{error::Error, ALLOWED_PREFIX_LENS};
use std::cmp::max;
use std::net::{Ipv4Addr, Ipv6Addr};
/// Extracts an IPv4 address from an IPv6 prefix following the method defined in [RFC6052 Section 2.2](https://datatracker.ietf.org/doc/html/rfc6052#section-2.2)
///
/// # Examples
///
/// ```
/// # use std::net::{Ipv4Addr, Ipv6Addr};
/// use rfc6052::extract_ipv4_addr;
///
/// // An IPv4 address can be extracted from an IPv6 prefix of acceptable length
/// assert_eq!(
/// extract_ipv4_addr_unchecked("64:ff9b:c000:0201::".parse().unwrap(), 32),
/// Ok("192.0.2.1".parse::<Ipv4Addr>().unwrap())
/// );
///
/// // Using a prefix that is not an RFC-approved length (in this case 66) will fail
/// assert_eq!(
/// extract_ipv4_addr_unchecked("64:ff9b:c000:0201::".parse().unwrap(), 66),
/// Err(rfc6052::Error::InvalidPrefixLength(66))
/// );
/// ```
pub fn extract_ipv4_addr(ipv6_addr: Ipv6Addr, prefix_length: u8) -> Result<Ipv4Addr, Error> {
// Fail if the prefix length is invalid
if !ALLOWED_PREFIX_LENS.contains(&prefix_length) {
@ -16,6 +37,20 @@ pub fn extract_ipv4_addr(ipv6_addr: Ipv6Addr, prefix_length: u8) -> Result<Ipv4A
/// Extracts an IPv4 address from an IPv6 prefix following the method defined in [RFC6052 Section 2.2](https://datatracker.ietf.org/doc/html/rfc6052#section-2.2)
///
/// **Warning:** This function does not check that the prefix length is valid according to the RFC. Use `extract_ipv4_addr` instead.
///
/// # Examples
///
/// ```
/// # use std::net::{Ipv4Addr, Ipv6Addr};
/// use rfc6052::extract_ipv4_addr_unchecked;
///
/// // Using a prefix that is not an RFC-approved length (in this case 66) will *succeed*
/// // This is *not* the behavior of `extract_ipv4_addr`
/// assert_eq!(
/// unsafe { extract_ipv4_addr_unchecked("64:ff9b::30:0:8040:0".parse().unwrap(), 66) },
/// "192.0.2.1".parse::<Ipv4Addr>().unwrap()
/// );
/// ```
#[must_use]
#[allow(clippy::cast_lossless)]
#[allow(clippy::cast_possible_truncation)]

13
libs/rfc6052/src/lib.rs
View File

@ -5,12 +5,21 @@
#![allow(clippy::missing_panics_doc)]
#![allow(clippy::missing_safety_doc)]
pub mod error;
mod error;
mod embed;
mod extract;
pub use embed::{embed_ipv4_addr, embed_ipv4_addr_unchecked};
pub use error::Error;
pub use extract::{extract_ipv4_addr, extract_ipv4_addr_unchecked};
/// All allowed IPv6 prefix lengths according to [RFC6052 Section 2.2](https://datatracker.ietf.org/doc/html/rfc6052#section-2.2)
///
/// While any prefix length between 32 and 96 bits can in theory work with this library,
/// the RFC strictly defines a list of allowed IPv6 prefix to be used for embedding IPv4 addresses. They are:
/// - 32 bits
/// - 40 bits
/// - 48 bits
/// - 56 bits
/// - 64 bits
/// - 96 bits
pub const ALLOWED_PREFIX_LENS: [u8; 6] = [32, 40, 48, 56, 64, 96];