mixmessages.proto

////////////////////////////////////////////////////////////////////////////////
// Copyright © 2019 Privategrity Corporation                                   /
//                                                                             /
// All rights reserved.                                                        /
////////////////////////////////////////////////////////////////////////////////

syntax = "proto3";

package mixmessages;

import "gitlab.com/xx_network/comms/messages/messages.proto";
import "google/protobuf/any.proto";

// SERVER MESSAGE SERVICE ------------------------------------------------------

service Node {
    // Handles AskOnline
    rpc AskOnline (messages.Ping) returns (messages.Ack) {
    }

    // CreatesNewRound makes a new round with a certain ID
    rpc CreateNewRound (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // PostNewBatch sends a batch to be processed in the server's realtime
    rpc PostNewBatch (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // FinishRealtime broadcasts when realtime is complete
    rpc FinishRealtime (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // PostPhase runs a cMix phase on another node
    rpc PostPhase (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // StreamPostPhase runs a cMix phase on another node
    // by using unary streaming of slots
    rpc StreamPostPhase (stream Slot) returns (messages.Ack) {
    }

    // GetRoundBufferInfo returns the # of rounds ready for messages
    rpc GetRoundBufferInfo (messages.AuthenticatedMessage) returns (RoundBufferInfo) {
    }

    // RequestNonce generates a nonce for user registration
    rpc RequestNonce (messages.AuthenticatedMessage) returns (Nonce) {
    }

    // ConfirmRegistration uses a nonce confirmation to finalize user registration
    rpc ConfirmRegistration (messages.AuthenticatedMessage) returns (RegistrationConfirmation) {
    }

    // PostPrecompResult finalizes the precomputation results with each node from the last node
    // sending the final PayloadA and PayloadB precomputations
    rpc PostPrecompResult (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // The gateway calls GetCompletedBatch to get any finished batch from a node
    rpc GetCompletedBatch (messages.AuthenticatedMessage) returns (Batch) {
    }

    //
    rpc GetMeasure (messages.AuthenticatedMessage) returns (RoundMetrics) {
    }

    // Gateway -> Server unified polling
    rpc Poll (messages.AuthenticatedMessage) returns (ServerPollResponse) {
    }

    // Round trip ping comm
    rpc SendRoundTripPing (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Round error comm
    rpc RoundError (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Server -> Gateway permissioning address
    rpc GetPermissioningAddress (messages.Ping) returns (StrAddress) {
    }

    // Server -> Server initiating multi-party round DH key generation
    rpc StartSharePhase (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Server -> Server passing state of multi-party round DH key generation
    rpc SharePhaseRound (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Server -> Server received final key
    rpc ShareFinalKey (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

}

// RoundInfo contains the # of precomputations ready for messages, among other
// information
message RoundBufferInfo {
    uint32 RoundBufferSize = 1;
}

//
message RoundPublicKey {
    RoundInfo Round = 1;
    bytes Key = 2;
}

//
message RoundMetrics {
    string RoundMetricJSON = 1;
}

// Contains the complete set of messages/slots for a round
message Batch {
    RoundInfo Round = 1;
    int32 FromPhase = 2;
    repeated Slot slots = 3;
}

message CompletedBatch {
    uint64 RoundID = 1;
    repeated Slot slots = 2;
}

// Used as part of header for streaming post phase
message BatchInfo {
    RoundInfo Round = 1;
    int32 FromPhase = 2;
    uint32 BatchSize = 3;
}

// Used for collecting metrics on a round trip of the system
message RoundTripPing {
    google.protobuf.Any Payload = 1;
    RoundInfo Round = 2;
}

// Unified Gateway->Server polling message
message ServerPoll {
    NDFHash Full = 1;
    NDFHash Partial = 2;
    uint64 LastUpdate = 3;
    string Error = 4; // Only Populated in the event of errors
    string gatewayVersion = 5;
    string gatewayAddress = 6;
}

// Unified Gateway->Server polling response
message ServerPollResponse {
    bytes Id = 1;
    NDF FullNDF = 2; //Empty if no update needed
    NDF PartialNDF = 3; //Empty if no update needed
    repeated RoundInfo Updates = 4; //Empty if no update needed
    RoundInfo BatchRequest = 5; //Empty if no update needed
    CompletedBatch Batch = 6; //Empty if no update needed
}

// Used as part of Share phase for generation
// of a multi-party Diffie-Helman key
// Node <-> Node message
message SharePiece {
    bytes Piece = 1; // In progress round public key
    repeated bytes participants = 2; // List of nodes who have participated
    uint64 roundID = 3; // Id of round tied to round key generation
    messages.RSASignature Signature = 4; // Signature tied to message sent by node

}

// GATEWAY MESSAGE SERVICE -----------------------------------------------------

service Gateway {
    // PutMessage on the cMix Gateway
    rpc PutMessage (GatewaySlot) returns (GatewaySlotResponse) {
    }

    // RequestNonce returns a Nonce to the user
    rpc RequestNonce (NonceRequest) returns (Nonce) {
    }

    // ConfirmNonce takes a client signed nonce for Registration Nonce Confirmation
    rpc ConfirmNonce (RequestRegistrationConfirmation) returns (RegistrationConfirmation) {
    }

    // Notifications->Gateway request for users with pending notifications
    rpc PollForNotifications (messages.AuthenticatedMessage) returns (UserIdList) {
    }

    // Client -> Gateway unified polling
    rpc Poll (GatewayPoll) returns (GatewayPollResponse) {
    }

    // Client -> Gateway historical round request
    rpc RequestHistoricalRounds(HistoricalRounds) returns (HistoricalRoundsResponse) {
    }

    // Client -> Gateway message request
    rpc RequestMessages(GetMessages) returns (GetMessagesResponse) {
    }

    // Gateway -> Gateway message sharing within a team
    // Has RoundMessages underlying type
    rpc ShareMessages(messages.AuthenticatedMessage) returns (messages.Ack) {
    }
}

// Client -> Gateway request for information about historical rounds
message HistoricalRounds{
    repeated uint64 rounds = 1;
}

// Gateway's response to client's request for previous (historical) rounds
message HistoricalRoundsResponse{
    repeated RoundInfo Rounds = 1;
}

// Client -> Gateway request for available messages
// The query will be a request for all messages
// available in a round.
message GetMessages{
    bytes ClientID = 1;
    uint64 RoundID = 2;
}

// Gateway response to a GetMessages request
message GetMessagesResponse{
    repeated Slot Messages = 1;
    bool HasRound = 2;
}

// Gateway -> Gateway message sharing within a team
message RoundMessages {
    uint64 RoundId = 1;
    repeated Slot Messages = 2;
}

// The message for clients to poll the gateway for Message IDs
message IDList {
    repeated string IDs = 1;
}

// Represents a single encrypted message in a batch
message Slot {
    // Index in batch this slot belongs in
    uint32 Index = 1;

    // Precomputation fields
    bytes EncryptedPayloadAKeys = 2;
    bytes EncryptedPayloadBKeys = 3;
    bytes PartialPayloadACypherText = 4;
    bytes PartialPayloadBCypherText = 5;
    bytes PartialRoundPublicCypherKey = 6;

    // Realtime/client fields
    bytes SenderID = 7; // 256 bit Sender Id
    bytes PayloadA = 8; // Len(Prime) bit length payload A (contains part of encrypted payload)
    bytes PayloadB = 9; // Len(Prime) bit length payload B (contains part of encrypted payload, and associated data)
    bytes Salt = 10; // Salt to identify message key
    repeated bytes KMACs = 11; // Individual Key MAC for each node in network
}

// Unified Client->Gateway polling message
message GatewayPoll {
    NDFHash Partial = 1;
    uint64 LastUpdate = 2;
    bytes ReceptionID = 3;

    // Define range for ClientBloomFilter searches
    int64 StartTimestamp = 4;
    int64 EndTimestamp = 5;

    bytes ClientVersion = 6;
}

// Unified Client->Gateway polling response
message GatewayPollResponse {
    NDF PartialNDF = 1; // Empty if no update needed
    repeated RoundInfo Updates = 2; // Empty if no update needed
    bytes KnownRounds = 3; // Rounds gateway knows about
    ClientBlooms Filters = 4; // Set of ClientBloomFilters requested by Client
    uint64 EarliestRound = 5; // The earliest round the gateway still has info for
}

// Holds a set of ClientBloom and their associated metadata
message ClientBlooms {
    int64 Period = 1;
    int64 FirstTimestamp = 2;  // Earliest timestamp of the included BloomFilters
    repeated ClientBloom Filters = 3;
}

// Hold a ClientBloomFilter and its associated metadata
message ClientBloom {
    bytes Filter = 1;
    uint64 FirstRound = 2;
    uint32 RoundRange = 3;
}

// Client -> Gateway authentication message
message GatewaySlot{
    Slot Message = 1;
    uint64 RoundID = 2;
    bytes MAC = 3;
}

// Gateway -> Client authentication response
message GatewaySlotResponse{
    bool accepted = 1;
    uint64 RoundID = 2;
}

// Gateway -> Gateway gossip of all Sender IDs in a Batch
message BatchSenders {
    repeated bytes SenderIds = 1;
    uint64 RoundID = 2;
}

// Gateway -> Gateway gossip of all recipient IDs in a Batch
message Recipients {
    repeated bytes RecipientIds = 1;
    uint64 RoundID = 2;
}


// REGISTRATION MESSAGE SERVICE ------------------------------------------------

// Registration service definition
service Registration {
    // Client uses this to register its user with the system
    rpc RegisterUser (UserRegistration) returns (UserRegistrationConfirmation) {
    }

    // Node registration for the permissioning server
    rpc RegisterNode (NodeRegistration) returns (messages.Ack) {
    }

    // Obtain NDF from the Registration Server
    rpc PollNdf (NDFHash) returns (NDF) {
    }

    // Server -> Permissioning unified polling
    rpc Poll (messages.AuthenticatedMessage) returns (PermissionPollResponse) {
    }

    // Checks if node has been registered
    rpc CheckRegistration (RegisteredNodeCheck) returns (RegisteredNodeConfirmation) {

    }
}

// Server -> Permissioning message for whether a node has been registered
message RegisteredNodeConfirmation {
    bool IsRegistered = 1;
}

message RegisteredNodeCheck {
    bytes  ID = 1;
}

//The ndf Hash used to compare ndf on permissioning and client
message NDFHash {
    bytes Hash = 1;
}

// The Network Definition File is defined as a
// JSON structure in primitives/ndf. Can be provided in a
// "complete" and "incomplete" format. An incomplete
// NDF is provided to level 4 (ie clients) to protect the inner levels
message NDF{
    bytes Ndf = 1;
    messages.RSASignature Signature = 2;
}

// NodeRegistration contains information to register a node.
// Note: this includes the desired server and gateway addresses.
// The registration server is free to ignore these addresses and
// derive the address from the network connection.
message NodeRegistration {
    bytes  Salt = 1;
    string ServerTlsCert = 2;
    string ServerAddress = 3;
    uint32 ServerPort = 4; // Note: there is no uint16
    string GatewayTlsCert = 5;
    string GatewayAddress = 6;
    uint32 GatewayPort = 7; // Note: there is no uint16
    string RegistrationCode = 8;
}

// UserRegistration message to initialize registration process
message UserRegistration {
    string RegistrationCode = 1;
    string ClientRSAPubKey = 2;
    string ClientReceptionRSAPubKey = 3;
}

// UserRegistrationConfirmation to confirm registration with users
message UserRegistrationConfirmation {
    // RegistrationServer-Signed Client Public Key
    messages.RSASignature ClientSignedByServer = 1;
    messages.RSASignature ClientReceptionSignedByServer = 2;
    string Error = 3;
}

// ClientVersion contains a version string for the client
message ClientVersion {
    string Version = 1;
}

// NonceRequest message to request nonce from client to server
message NonceRequest {
    bytes Salt = 1;
    string ClientRSAPubKey = 2;
    messages.RSASignature ClientSignedByServer = 3;
    bytes ClientDHPubKey = 4;
    messages.RSASignature RequestSignature = 5;
}

// Nonce message to reply to client from server (going through gateway)
message Nonce {
    bytes Nonce = 1;
    bytes DHPubKey = 2;
    string Error = 3;
}

// RequestRegistrationConfirmation returning proof of registration
message RequestRegistrationConfirmation {
    bytes userID = 1;
    messages.RSASignature NonceSignedByClient = 2;
    string Error = 3;
}

// RegistrationConfirmation returning proof of registration
message RegistrationConfirmation {
    messages.RSASignature ClientSignedByServer = 1;
    bytes ClientGatewayKey = 2;
    string Error = 3;
}

// Unified Server->Permissioning polling message
message PermissioningPoll {
    NDFHash Full = 1;
    NDFHash Partial = 2;
    uint64 LastUpdate = 3;
    uint32 Activity = 4;
    RoundError Error = 5; // Only Populated in the event of errors
    string gatewayAddress = 6;
    string gatewayVersion = 7;
    string serverAddress = 8;
    string serverVersion = 9;
    repeated ClientError ClientErrors = 10; // Client error information
}


// Info containing error among a client
// Passed server -> Permissioning via the poll comm
message ClientError {
    bytes ClientId = 1;
    string Error = 2;
}

// Unified Server->Permissioning polling response
message PermissionPollResponse {
    NDF FullNDF = 1; // Empty if no update needed
    NDF PartialNDF = 2; // Empty if no update needed
    repeated RoundInfo Updates = 3; // Empty if no update needed
}


// NOTIFICATION BOT MESSAGES --------------------------------------------------------

// NotificationBot service definition
service NotificationBot {
    // Unregister clients from push notifications
    rpc UnregisterForNotifications (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Register clients from push notifications
    rpc RegisterForNotifications (messages.AuthenticatedMessage) returns (messages.Ack) {
    }
}

// Registration token to be associated with the client
message NotificationToken {
    bytes Token = 1;
}

// The list of user IDS for notification polling
message UserIdList {
    repeated bytes IDs = 1;
}

// UDB MESSAGE SERVICE ---------------------------------------------------------

service UDB {
    // Handles a UDB user registration request
    rpc RegisterUser (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Handles a request to register a Fact into the Fact database
    rpc RegisterFact (messages.AuthenticatedMessage) returns (FactRegisterResponse) {
    }

    // Handles a request to confirm a Fact against the Fact database
    rpc ConfirmFact (messages.AuthenticatedMessage) returns (messages.Ack) {
    }

    // Handles a request to remove a Fact from the Fact database
    rpc RemoveFact (messages.AuthenticatedMessage) returns (messages.Ack) {
    }
}

// Holds information for a UDB user registration request
message UDBUserRegistration {
    bytes PermissioningSignature = 1;
    string RSAPublicPem = 2;
    Identity IdentityRegistration = 3;
    bytes IdentitySignature = 4; // (RSAPublicSign(Data.Digest()))
    FactRegisterRequest frs = 5;
    bytes UID = 6;
}

// Identity describes a user and their cryptographic info
message Identity {
    string Username = 1;
    bytes dhPubKey = 2;
    bytes Salt = 3;
}

// Holds information for a Fact registration request
message FactRegisterRequest {
    bytes UID = 1;
    Fact Fact = 2;
    bytes FactSig = 3;// (RSAPublicSign(Fact.Digest()))
}

// Fact describes a Fact, namely what it is and what type it is
message Fact {
    string Fact = 1;
    uint32 FactType = 2;
}

// FactRegisterResponse describes UDB's handling of a FactRegisterRequest request
message FactRegisterResponse {
    string ConfirmationID = 1;
}

// Holds information for a Fact confirmation request
message FactConfirmRequest {
    string ConfirmationID = 1;
    string Code = 2;
}

// Holds information for a Fact removal request
message FactRemovalRequest {
    bytes UID = 1;
    Fact RemovalData = 2;
}

// CONNECTIVITY CHECKER --------------------------------------------------------

// For sending permission address Server -> Gateway
message StrAddress {
    string address = 1;
}

// GENERAL USE MESSAGES --------------------------------------------------------

// Describes a round
message RoundInfo {
    uint64 ID = 1;
    uint64 UpdateID = 2;
    uint32 State = 3; // Precomp, Standby, Realtime, Completed, Failed
    uint32 BatchSize = 4;
    repeated bytes Topology = 5; // List of NodeIDs
    repeated uint64 Timestamps = 6; // List of state timestamps in UTC
    repeated RoundError Errors = 7; // List of round errors which occurred
    repeated ClientError ClientErrors = 8;
    uint32 ResourceQueueTimeoutMillis = 9; // Timeout for resource queue on nodes
    messages.RSASignature Signature = 10;
    uint32 AddressSpaceSize = 11;
}

// RoundError will be used to describe a round error
// Passed along to gateways (level 2) and clients (level 3)
message RoundError {
    uint64        Id = 1;
    bytes         NodeId = 2;
    string        Error = 3;
    messages.RSASignature  Signature = 4;
}