zer0-secret-stream · protocol

pub const ALLOCATED_FEATURE_MASK: u64;

pub const INNER_BINDING_FEATURE: u64;

pub const MAX_BOOTSTRAP_BYTES: usize;

pub const MAX_TRANSPORT_PEER_ID_BYTES: usize;

pub const MAX_CAPABILITY_BYTES: usize;

pub const MAX_APPLICATION_IDENTITY_BYTES: usize;

pub const MAX_BOOTSTRAP_LIFETIME_MS: u64;

pub const MAX_APPLICATION_AUTH_LIFETIME_MS: u64;

#[derive(Debug, Error)]
pub enum ProtocolError {
    #[error("unsupported or malformed protocol identifier")]
    InvalidProtocolId,
    #[error("invalid endpoint profile {0}")]
    InvalidEndpointProfile(u64),
    #[error("service-role bitmap contains unallocated bits: {0:#06x}")]
    InvalidServiceRoles(u16),
    #[error("feature bitmap contains unallocated bits: {0:#018x}")]
    UnsupportedCriticalFeature(u64),
    #[error("selected features are not the exact supported-feature intersection")]
    InvalidSelectedFeatures,
    #[error("required features are not covered by the selected features")]
    MissingRequiredFeature,
    #[error("transport PeerId must be the canonical inline-Ed25519 libp2p encoding")]
    InvalidTransportPeerId,
    #[error("a pinned route must use a null digest and generation zero")]
    InvalidPinnedRoute,
    #[error("initiator and responder challenges must be independent")]
    ReusedChallenge,
    #[error("invalid bootstrap validity interval")]
    InvalidBootstrapLifetime,
    #[error("bootstrap was issued in the future")]
    BootstrapNotYetValid,
    #[error("bootstrap has expired")]
    BootstrapExpired,
    #[error("invalid application-authorization validity interval")]
    InvalidApplicationAuthLifetime,
    #[error("application protocol version must be ASCII semantic version without build metadata")]
    InvalidApplicationProtocolVersion,
    #[error("opaque requested capability exceeds 256 bytes")]
    CapabilityTooLarge,
    #[error("opaque application identity exceeds 4096 bytes")]
    ApplicationIdentityTooLarge,
    #[error("deterministic CBOR is malformed or non-canonical: {0}")]
    NonCanonicalCbor(&'static str),
    #[error("deterministic CBOR exceeds the Protocol 1.0 size limit")]
    CborTooLarge,
    #[error("received transcript does not exactly match the locally reconstructed transcript")]
    TranscriptMismatch,
    #[error("migration generation overflow")]
    MigrationGenerationOverflow,
    #[error("a replacement plan has already been issued for this session")]
    ReplacementAlreadyPlanned,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ProtocolId(String);

pub fn parse(value: impl Into<String>) -> Result<Self, ProtocolError>;

pub fn as_str(&self) -> &str;

pub fn wire_version(&self) -> &str;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u8)]
pub enum EndpointProfile {
    NativeFull = 0,
    NativeRestricted = 1,
    PortableMacosAlpha = 2,
    OfflineLan = 3,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ServiceRoles(u16);

pub fn new(bits: u16) -> Result<Self, ProtocolError>;

pub fn bits(self) -> u16;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct FeatureSet(u64);

pub fn new(bits: u64) -> Result<Self, ProtocolError>;

pub fn bits(self) -> u64;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TransportPeerId(Vec<u8>);

pub fn new(bytes: impl Into<Vec<u8>>) -> Result<Self, ProtocolError>;

pub fn as_bytes(&self) -> &[u8];

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteBinding {
pub route_set_digest: Option<[u8; 32]>,
pub generation: u64
}

pub fn pinned() -> Self;

pub fn routed(digest: [u8; 32], generation: u64) -> Self;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SessionBootstrapContext {
pub selected_protocol_id: ProtocolId,
pub initiator_endpoint_profile: EndpointProfile,
pub responder_endpoint_profile: EndpointProfile,
pub initiator_service_roles: ServiceRoles,
pub responder_service_roles: ServiceRoles,
pub initiator_transport_peer_id: TransportPeerId,
pub responder_transport_peer_id: TransportPeerId,
pub initiator_route: RouteBinding,
pub responder_route: RouteBinding,
pub initiator_supported_features: FeatureSet,
pub initiator_required_features: FeatureSet,
pub responder_supported_features: FeatureSet,
pub responder_required_features: FeatureSet,
pub selected_features: FeatureSet,
pub proposed_migration_generation: u64,
pub issued_at_ms: u64,
pub expires_at_ms: u64
}

pub fn validate(&self) -> Result<(), ProtocolError>;

pub fn validate_at(
        &self,
        now_ms: u64,
        handshake_lifetime_ms: u64,
    ) -> Result<(), ProtocolError>;

pub fn with_challenges(
        self,
        initiator_challenge: [u8; 32],
        responder_challenge: [u8; 32],
    ) -> Result<SessionBootstrapV1, ProtocolError>;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SessionBootstrapV1 {
pub version: u64,
pub selected_protocol_id: ProtocolId,
pub initiator_endpoint_profile: EndpointProfile,
pub responder_endpoint_profile: EndpointProfile,
pub initiator_service_roles: ServiceRoles,
pub responder_service_roles: ServiceRoles,
pub initiator_transport_peer_id: TransportPeerId,
pub responder_transport_peer_id: TransportPeerId,
pub initiator_challenge: [u8; 32],
pub responder_challenge: [u8; 32],
pub initiator_route: RouteBinding,
pub responder_route: RouteBinding,
pub initiator_supported_features: FeatureSet,
pub initiator_required_features: FeatureSet,
pub responder_supported_features: FeatureSet,
pub responder_required_features: FeatureSet,
pub selected_features: FeatureSet,
pub proposed_migration_generation: u64,
pub issued_at_ms: u64,
pub expires_at_ms: u64
}

pub fn validate(&self) -> Result<(), ProtocolError>;

pub fn validate_at(
        &self,
        now_ms: u64,
        handshake_lifetime_ms: u64,
    ) -> Result<(), ProtocolError>;

pub fn to_deterministic_cbor(&self) -> Result<Vec<u8>, ProtocolError>;

pub fn from_deterministic_cbor(input: &[u8]) -> Result<Self, ProtocolError>;

#[derive(PartialEq, Eq, Zeroize, ZeroizeOnDrop)]
pub struct ChannelBinding([u8; 32]);

pub fn derive(
        inner_handshake_hash: &[u8; 32],
        confirmed_bootstrap_cbor: &[u8],
    ) -> Result<Self, ProtocolError>;

pub fn as_bytes(&self) -> &[u8; 32];

pub fn digest(&self) -> [u8; 32];

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct OpaqueApplicationAuthInputs {
pub opaque_scope_digest: [u8; 32],
pub requested_capability: Vec<u8>,
pub proving_application_identity: Vec<u8>,
pub verifying_application_identity: Vec<u8>,
pub issued_at_ms: u64,
pub expires_at_ms: u64,
pub policy_generation: u64
}

#[derive(Debug, PartialEq, Eq)]
pub struct ApplicationAuthTranscriptV1 {

}

pub fn from_confirmed_session(
        bootstrap: &SessionBootstrapV1,
        channel_binding: &ChannelBinding,
        inputs: OpaqueApplicationAuthInputs,
    ) -> Result<Self, ProtocolError>;

pub fn to_deterministic_cbor(&self) -> Result<Vec<u8>, ProtocolError>;

pub fn proof_message(&self) -> Result<Vec<u8>, ProtocolError>;

pub fn confirm_exact(&self, received: &[u8]) -> Result<(), ProtocolError>;