hb46pp 0.1.2

Client library for the HTTP-Based IPv4 over IPv6 Provisioning Protocol
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

# hb46pp

`hb46pp` is a Rust client for the
[HTTP-Based IPv4 over IPv6 Provisioning Protocol][hb46pp-spec] used to discover
provisioning parameters for IPv4-over-IPv6 methods. It implements bootstrap TXT
discovery, request and response validation, IPv6-only HTTP transport, protocol
redirects, and retry timing and migration-state guidance.

Provisioning data for each supported IPv4-over-IPv6 method is retained as
JSON. Applications select a method and interpret its parameters.

## Example

The default features provide a [Hickory][hickory] DNS resolver and a
[Reqwest][reqwest] HTTP transport with a total timeout of 30 seconds per
provisioning request. `DefaultClient::try_new` uses the default client settings,
but callers can customize them with `DefaultClient::builder`.

```rust
# #[cfg(feature = "default-client")]
# mod example {
use hb46pp::{Capability, FirmwareVersion, Product, ProvisioningRequest, VendorId};
use hb46pp::client::{DefaultClient, ProvisioningOutcome};

async fn provision() -> Result<(), Box<dyn std::error::Error>> {
    let mut request = ProvisioningRequest::new(
        "000000".parse::<VendorId>()?,
        "example-router".parse::<Product>()?,
        "1_0_0".parse::<FirmwareVersion>()?,
        vec![Capability::DsLite],
        None,
        None,
    )?;
    let client = DefaultClient::try_new()?;

    let outcome = client.provision(&request).await?;
    let window = outcome.next_attempt_window();

    match outcome {
        ProvisioningOutcome::Provisioned(response) => {
            if let Some(offer) = response.data().select(&[Capability::DsLite]) {
                println!("DS-Lite parameters: {}", offer.parameters());
            }

            if let Some(token) = response.data().token().cloned() {
                request.set_token(Some(token));
            }
        }
        ProvisioningOutcome::NotFound => {
            println!("disable the previous HB46PP-provisioned mechanism");
        }
    }
    println!(
        "make another attempt after a delay between {:?} and {:?}",
        window.min(),
        window.max()
    );

    Ok(())
}
# }
```

The library provides retry timing and uses `ClientError::retry_action` to
distinguish disabling from preserving the previous migration mechanism. It does
not choose a random delay, sleep, monitor network changes, modify network
configuration, or persist data. Those responsibilities remain with the
application.

## Features

- `default-client` (default): default DNS resolver and HTTP transport.
- `client`: protocol flow and adapter traits without concrete network adapters.
- `default-resolver`: Hickory-based discovery resolver.
- `default-transport`: Reqwest-based IPv6-only HTTP transport.
- No features: protocol models and validation only.

Custom transports must use IPv6, apply the requested TLS policy, avoid
automatic redirects, and bound response resource usage.

## Security

HB46PP bootstrap discovery trusts the DNS response for `4over6.info`. Requiring
certificate validation protects communication with the hostname in that
response, but does not independently authenticate that DNS selected the
intended provider. Applications should use HB46PP discovery only where the
access-network DNS is trusted.

The client rejects bootstrap policy `t=a` by default because it permits HTTP or
HTTPS without certificate validation. Applications that require compatibility
with such a provider must explicitly select
`ProvisioningAuthenticationPolicy::AllowUnauthenticated`.

## License

Licensed under either of the following:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))

[hb46pp-spec]: https://github.com/v6pc/v6mig-prov/blob/9020a1bd5f2f8f83712b1180db70af7dc0dad638/spec.md
[hickory]: https://crates.io/crates/hickory-resolver
[reqwest]: https://crates.io/crates/reqwest