Crate polyproto

polyproto

Crate supplying (generic) Rust types and traits to quickly get a polyproto implementation up and running, as well as an HTTP client for the polyproto API.

Overview/TL;DR • crates.io • Protocol Specification Overview/TL;DR • crates.io • Protocol Specification

Crate overview

Building upon types offered by the der, x509_cert and spki crates, this crate provides a set of types and traits to quickly implement the polyproto specification. Simply add cryptography and signature algorithm crates of your choice to the mix, and you are ready to go.

All polyproto certificate types can be converted to and from the types offered by the x509_cert crate.

Implementing polyproto

Start by implementing the trait crate::signature::Signature for a signature algorithm of your Start by implementing the trait crate::signature::Signature for a signature algorithm of your choice. Popular crates for cryptography and signature algorithms supply their own PublicKey and PrivateKey types. You should extend upon these types with your own structs and implement the crate::key traits for these new structs. crate::key traits for these new structs.

You can then use the crate::certs types to build certificates using your implementations of the You can then use the crate::certs types to build certificates using your implementations of the aforementioned traits.

View the examples directory for a simple example on how to implement and use this crate with the ED25519 signature algorithm.

Cryptography

This crate provides no cryptographic functionality whatsoever; its sole purpose is to aid in implementing polyproto by transforming the polyproto specification into well-defined yet adaptable Rust types.

Safety

Please refer to the documentation of individual functions for information on which safety guarantees they provide. Methods returning certificates, certificate requests and other types where the validity and correctness of the data has a chance of impacting the security of a system always mention the safety guarantees they provide in their respective documentation.

This crate has not undergone any security audits.

WebAssembly

!!! warning

As of v0.10, the wasm target is currently untested. Support will be re-added in the future.

!!! warning

As of v0.10, the wasm target is currently untested. Support will be re-added in the future.

This crate is designed to work with the wasm32-unknown-unknown target. To compile for wasm, you will have to use the wasm feature:

toml [dependencies] polyproto = { version = “0”, features = [“wasm”] }

HTTP API client through reqwest

If the reqwest feature is activated, this crate offers a polyproto HTTP API client, using the reqwest crate.

Alternatives to reqwest

If you would like to implement an HTTP client using something other than reqwest, simply enable the types and serde features. Using these features, you can implement your own HTTP client, with the polyproto crate acting as a single source of truth for request and response types, as well as request routes and methods through the exported static Routes.

WebSocket Gateway client

Since v0.10, this crate ships polyproto WebSocket Gateway client functionality, gated behind the gateway feature. The implementation of this feature is super backend-agnostic—though, for now, we have sealed the needed traits, and are only shipping a tokio-tungstenite backend for testing.

The gateway handles establishing a connection to the server, sending regular heartbeats at the specified interval and responding to Opcode 11—the manual heartbeat request.

Apart from the Hello payload, library consumers can easily get access to all messages received from the gateway by calling subscribe() on the internal tokio::sync::watch::Sender. This means that this crate handles only the bare necessities of connecting to the gateway, and that you are free to handle incoming messages however you would like to. Our GatewayMessage type is .into() and From::<>-compatible with tokio_tungstenite::tungstenite::Message, so that you are not locked into using our message types, should you not want that.

Versioning and MSRV

Semver v2.0 is used for the versioning scheme for this crate.

The default feature set of this crate is used to determine, verify and update the MSRV and semver version of this crate.

Logo

The polyproto logo was designed by the wonderful antidoxi. The polyproto logos provided in this document are not covered by the MPL-2.0 license covering the rest of this project.

Re-exports

pub use der;

pub use spki;

pub use url;

Modules

api

Ready-to-use API routes, implemented using reqwest

certs

Generic polyproto certificate types and traits.

errors

Error types used in this crate

key

Generic polyproto public- and private key traits.

signature

Generic polyproto signature traits.

types

Types used in polyproto and the polyproto HTTP/REST APIs

Structs

RdnSequence

X.501 RDNSequence as defined in RFC 5280 Section 4.1.2.4.

RelativeDistinguishedName

RelativeDistinguishedName as defined in RFC 5280 Section 4.1.2.4.

Constants

OID_RDN_COMMON_NAME

The OID for the commonName RDN

OID_RDN_DOMAIN_COMPONENT

The OID for the domainComponent RDN

OID_RDN_UID

The OID for the uid RDN

OID_RDN_UNIQUE_IDENTIFIER

The OID for the uniqueIdentifier RDN

Traits

Constrained

Types implementing Constrained can be validated to be well-formed.

Type Aliases

DistinguishedName

X.501 DistinguishedName as defined in RFC 5280 Section 4.1.2.4.

Name

X.501 Name as defined in RFC 5280 Section 4.1.2.4. X.501 Name is used to represent distinguished names.