Skip to main content

Crate sw_identity_tls

Crate sw_identity_tls 

Source
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:

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§

client
Client-side identity-bound TLS.
server
Server-side identity-bound TLS.

Structs§

EndpointRecord
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.
EndpointResolver
Resolves the published endpoints of the permitted cluster nodes of an application, backed by the incremental cached opted-in-accounts scan.
IdentityCert
A self-signed certificate bound to an Algorand identity, plus its ephemeral private key, ready to hand to rustls as this endpoint’s own credential.
StaticMembership
A fixed, in-memory MembershipAuthority — the authority for the static allowlist auth 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.
VerifyError
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§

MembershipAuthority
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 bit of the uint local-state value under key is set. This is the Bingle membership shape (bingle_rust#234): the allow flags are packed into one uint bitfield local-state slot — allow_sw_node and allow_sw_client are distinct bits — so the cluster-node and client sources decode the same key at different bit positions. algo_ops renders a uint value as its decimal string; a value that does not parse (a missing or non-uint slot) 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 into rustls::crypto themselves.
generate
Generate an IdentityCert bound to identity.
key_set_decoder
A decoder that treats an account as a member iff its local state holds key with a truthy value — a non-empty value other than "0" or "false". Covers the usual “set bit / flag = member” schema (algo_ops decodes a uint flag to its decimal string and a byte value to its UTF-8 form).
verify_identity_cert
Verify that end_entity is 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 = None admits a member in any role).
verify_identity_cert_for_role
Verify that end_entity is bound to an authorized Algorand identity that holds exactly role, returning that identity’s address. Rejects an authentic member of a different role (e.g. a Role::Client presenting on a node-to-node link that requires Role::ClusterNode) with VerifyError::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§

MembershipDecoder
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_decoder for the common “a named key is set” shape and bit_decoder for a packed bitfield.