Expand description
Identity-bound TLS for Sidewinder access — the libp2p TLS handshake pattern rooted in an Algorand
identity, plus the endpoint-discovery codec. The single, publishable source of this logic, shared by
the Sidewinder node/server side (the sw-tls/sw-membership crates in the sidewinder repo re-export
from here) and the client side (sidewinder_ops).
A node or client presents a self-signed certificate with an ephemeral key (deliberately
unrelated to its long-lived Algorand key). The certificate carries a custom X.509 extension in which
the Algorand identity key (Ed25519) signs the ephemeral certificate’s SubjectPublicKeyInfo. A
peer verifies that signature, derives the Algorand address from the identity key, and checks it
against a MembershipAuthority — never validating a certificate chain against a Certificate
Authority (CA), and never calling a node/indexer.
generate mints an identity-bound certificate and verify_identity_cert runs the offline check.
The two ends of a mutual-TLS connection are assembled from separate modules so a build can take just
the half it needs:
client— authenticate the server by identity (client::IdentityServerVerifier) and build arustls::ClientConfig(client::client_config). Always available.server— authenticate the client by identity (server::IdentityClientVerifier) and build arustls::ServerConfig(server::server_config). Gated behind theservercargo feature, so a pure API client (default-features = false) never compiles the server-side verifier.
Discovery: EndpointRecord is the shared codec for a node’s reachable endpoint(s), and
EndpointResolver resolves the live (identity, endpoint) set of an application’s permitted nodes
off the incremental opted-in-accounts scan. The local-state decoders (MembershipDecoder,
bit_decoder, key_set_decoder) are the generic seam both discovery and the on-chain membership
sources (in the sidewinder sw-membership crate) build on.
Modules§
Structs§
- Endpoint
Record - a node’s published reachable endpoint(s): an optional IPv4 socket address and an optional IPv6 one, each independent (they need not share an address or a port). At least one is present in a valid record.
- Endpoint
Resolver - Resolves the published endpoints of the permitted cluster nodes of an application, backed by the incremental cached opted-in-accounts scan.
- Identity
Cert - A self-signed certificate bound to an Algorand identity, plus its ephemeral private key, ready to
hand to
rustlsas this endpoint’s own credential. - Static
Membership - A fixed, in-memory
MembershipAuthority— the authority for the staticallowlistauth mode, the single-identity pin a resolved-then-connected client uses, and the test double for the verifier suite. Built once from a known set of addresses; it never scans.
Enums§
- Role
- The capacity in which an identity is permitted on a Sidewinder network.
- Verify
Error - Why an identity certificate failed verification.
Constants§
- IDENTITY_
SIG_ PREFIX - The domain-separation prefix the identity key signs, ahead of the leaf
SubjectPublicKeyInfo. - SIDEWINDER_
IDENTITY_ EXT_ OID - The object identifier (OID) of the Sidewinder identity-binding certificate extension.
- SIDEWINDER_
IDENTITY_ EXT_ OID_ STR - The dotted-string form of
SIDEWINDER_IDENTITY_EXT_OID, for matching a parsed certificate’s extension without reconstructing an OID value.
Traits§
- Membership
Authority - Answers is this Algorand identity permitted, and as what for the TLS verifiers.
Functions§
- bit_
decoder - A decoder that treats an account as a member iff bit
bitof theuintlocal-state value underkeyis set. This is the Bingle membership shape (bingle_rust#234): the allow flags are packed into oneuintbitfield local-state slot —allow_sw_nodeandallow_sw_clientare distinct bits — so the cluster-node and client sources decode the same key at different bit positions.algo_opsrenders auintvalue as its decimal string; a value that does not parse (a missing or non-uintslot) reads as not-a-member (fail closed). - default_
provider - The crate’s crypto provider:
rustls’s ring provider, selected explicitly (not aws-lc-rs) to avoid a C toolchain build dependency. Both the config builders and the verifiers must share one provider; construct it here so consumers do not reach intorustls::cryptothemselves. - generate
- Generate an
IdentityCertbound toidentity. - key_
set_ decoder - A decoder that treats an account as a member iff its local state holds
keywith a truthy value — a non-empty value other than"0"or"false". Covers the usual “set bit / flag = member” schema (algo_opsdecodes auintflag to its decimal string and a byte value to its UTF-8 form). - verify_
identity_ cert - Verify that
end_entityis bound to an authorized Algorand identity, authorized as a member in any role, returning that identity’s address. This is the role-agnostic wrapper over the shared inner check (required = Noneadmits a member in any role). - verify_
identity_ cert_ for_ role - Verify that
end_entityis bound to an authorized Algorand identity that holds exactlyrole, returning that identity’s address. Rejects an authentic member of a different role (e.g. aRole::Clientpresenting on a node-to-node link that requiresRole::ClusterNode) withVerifyError::NotAuthorized, the same as an unknown identity. This is the role-gating the node-to-node (#373) and inbound-client (#374) surfaces apply.
Type Aliases§
- Membership
Decoder - Decides, from an account’s decoded local state for the membership app, whether the account is a
permitted member. The exact key/bit is the membership application’s schema, so it is injected; see
key_set_decoderfor the common “a named key is set” shape andbit_decoderfor a packed bitfield.