ceremonyclient/node/protobufs/channel.proto

181 lines
8.5 KiB
Protocol Buffer
Raw Normal View History

2023-09-03 23:47:09 +00:00
syntax = "proto3";
package quilibrium.node.channel.pb;
option go_package = "source.quilibrium.com/quilibrium/monorepo/node/protobufs";
import "keys.proto";
// Describes a general channel envelope for a message.
message P2PChannelEnvelope {
// A general protocol identifier as a uint32 this is expected to rarely
// iterate, and should be uniquely identifying both protocol and version.
// Pragmatically speaking, this implies that the least significant byte
// specifies version (which should iterate most minimally), and the three most
// significant bytes should specify protocol. Recipients SHOULD ignore
// messages with incompatible protocol identifiers, but also SHOULD warn on
// identifiers with versions higher than the supported protocol. A large
// number of unsupported protocol messages may indicate spam/some other
// attack, whereas a large number of unsupported protocol versions may
// indicate an out of date client, respective to which side is the maximum of
// the version number.
uint32 protocol_identifier = 1;
// The encrypted message header. Message header encryption is mandatory
// P2P channels in some cases pre-empt the mixnet and leaky information from
// unencrypted message headers could de-anonymize the recipient. It is thus
// also mandatory at the protocol implementation level that header sizes are
// consistent within a protocol so as to not leak metadata. An example of this
// is in Double and Triple-Ratchet, where the sequence identifiers MUST be
// encoded as fixed-length integers, as variable encoding can indicate a
// message being in the first 256, 65,536, etc. if an exchange is highly
// asymmetrical in sends/receives. This is especially critical in long
// running protocols with a need for fixed length messages (see message_body
// notes).
MessageCiphertext message_header = 2;
// The encrypted message body. Message bodies are variable length ciphertext
// could range widely, however if this metadata is pertinent to determining
// protocol state, such as knowing what round an encapsulated protocol is in,
// or potentially what might be transferred over the protocol, protocol
// implementers SHOULD utilize chunking and send fixed length messages.
// Additionally, if rounds themselves are highly asymmetric or have
// long-standing processing times that could dangerously leak information of
// round state, implementers SHOULD defer protocol use to leverage the mixnet.
// If this is not feasible, the implementation details are left up to the
// exercise of the protocol author.
MessageCiphertext message_body = 3;
}
// Describes a general ciphertext payload.
message MessageCiphertext {
// The intialization vector used for encryption. While cipher specific,
// typically this should be a unique value for every ciphertext. If this is
// not the case for a protocol where it should be, this SHOULD be considered
// an invalid message and warned, as it could either indicate compromise,
// or a faulty cryptographic implementation such as a faulty PKCS#11
// implementation that has a code path to handle HSM vendors which mandate
// zeroed IVs before passing into encryption methods, as they will update the
// IV within the HSM through hardware-supplied entropy.
bytes initialization_vector = 1;
// The raw ciphertext byte string. This will be cipher specific, however some
// general attributes are expected to be followed. If there is a common
// layout expected, such as AES-GCM having the GCM tag appended to the
// ciphertext, please follow the common layout.
bytes ciphertext = 2;
// The associated data byte string, if available. This will be highly protocol
// specific, but SHOULD NOT leak metadata.
bytes associated_data = 3;
}
// Describes the announcement of a new proving key.
message ProvingKeyAnnouncement {
// The commitment to a Schnorr proof of the Identity Key. The commitment is
// produced by taking a hash of the C and S components of the proof.
bytes identity_commitment = 1;
// The commitment to a Schnorr proof of the Signed Pre Key. The commitment is
// produced by taking a hash of the C and S components of the proof.
bytes prekey_commitment = 2;
oneof proving_key_signature {
quilibrium.node.keys.pb.Ed448Signature proving_key_signature_ed448 = 3;
}
}
// Represents a request for a proving key.
message ProvingKeyRequest {
bytes proving_key_bytes = 1;
}
// Describes the aggregation of inclusion commitments for a given clock frame
message InclusionAggregateProof {
// The filter in which the inclusion proof was produced.
bytes filter = 1;
// The frame number in which the inclusion proof was added.
uint64 frame_number = 2;
// The collection of inclusion commitments, in order.
repeated InclusionCommitment inclusion_commitments = 3;
// The raw serialized proof, mirroring the type of commitment scheme used
// within the inclusion proofs.
bytes proof = 4;
}
// Describes the commitment of a data's inclusion in a given clock frame
message InclusionCommitment {
// The filter in which the inclusion aggregate proof was produced.
bytes filter = 1;
// The frame number in which the inclusion aggregate proof was added.
uint64 frame_number = 2;
// The position of the data in the proof.
uint32 position = 3;
// The specific type url represented by the data.
string type_url = 4;
// The raw serialized data as incorporated into the inclusion proof. Due to
// the non-deterministic nature of protobuf serialization, this data is an
// opaque binary string so that inclusion proofs can be accurately assessed
// between various node implementations, and retain forwards-compatibility
// with additional properties in future revisions to types.
bytes data = 5;
// The raw serialized commitment. Similar to data, this commitment data is an
// opaque binary string so that future commitment types can be added without
// having to break the underlying inclusion structure.
bytes commitment = 6;
}
// Describes the announcement of both an identity key and signed pre key. This
// is expected to be used for the initial announcement of a key bundle, and
// subsequent full revocations if identity key and signed pre keys are both
// suspected of/known to be compromised. Signatures under KeyBundleAnnouncement
// are expected to be cross-signed, such that the signature on the identity key
// is produced through the prover key, the signature on the signed pre key is
// produced through the identity key. ProvingKeyAnnouncements may be repeated
// whenever a key bundle update is expected only the first proving key
// announcement is retained in inclusion proofs, but the announcements
// necessarily are required for key bundle updates, as they provide a commitment
// to the updated keys' Schnorr proofs. An updated KeyBundleAnnouncement must
// be captured in an inclusion proof before it may be used for communication
// channels, and may only be used in communication channels once a lobby has
// opened _after_ the inclusion proof. If a lobby is open during the time the
// inclusion proof has been created, the announcement is not yet considered
// valid.
message KeyBundleAnnouncement {
IdentityKey identity_key = 1;
SignedPreKey signed_pre_key = 2;
bytes proving_key_bytes = 3;
}
// Describes the Identity Key and corresponding Schnorr proof. Schnorr proofs
// are expected to mirror the EC parameters of the proving and identity key. If
// they do not, validation will fail.
message IdentityKey {
// The C component of the Schnorr proof, serialized as big endian.
bytes challenge = 1;
// The S component of the Schnorr proof, serialized as big endian.
bytes response = 2;
// The Statement component of the Schnorr proof, serialized as an (compressed,
// if possible) affine representation of the point.
bytes statement = 3;
oneof identity_key_signature {
quilibrium.node.keys.pb.Ed448Signature public_key_signature_ed448 = 4;
}
}
// Describes the Signed Pre Key and corresponding Schnorr proof. Schnorr proofs
// are expected to mirror the EC parameters of the identity and signed pre key.
// If they do not, validation will fail.
message SignedPreKey {
// The C component of the Schnorr proof, serialized as big endian.
bytes challenge = 1;
// The S component of the Schnorr proof, serialized as big endian.
bytes response = 2;
// The Statement component of the Schnorr proof, serialized as an (compressed,
// if possible) affine representation of the point.
bytes statement = 3;
oneof signed_pre_key_signature {
quilibrium.node.keys.pb.Ed448Signature public_key_signature_ed448 = 4;
}
}