Commit 65467f53 authored by Loïck Bonniot's avatar Loïck Bonniot

[grpc] Add documentation

parent 543121d8
Pipeline #1660 passed with stages
......@@ -35,14 +35,24 @@ var _ = math.Inf
// is compatible with the proto package it is being compiled against.
const _ = proto.ProtoPackageIsVersion1
// / Context stores the current context of a specific promise or signature.
// It is a kind of "symbolic" promise, with no real cryptographic proofs inside.
type Context struct {
RecipientKeyHash []byte `protobuf:"bytes,1,opt,name=recipientKeyHash,proto3" json:"recipientKeyHash,omitempty"`
SenderKeyHash []byte `protobuf:"bytes,2,opt,name=senderKeyHash,proto3" json:"senderKeyHash,omitempty"`
Sequence []uint32 `protobuf:"varint,3,rep,name=sequence" json:"sequence,omitempty"`
Signers [][]byte `protobuf:"bytes,4,rep,name=signers,proto3" json:"signers,omitempty"`
ContractDocumentHash []byte `protobuf:"bytes,5,opt,name=contractDocumentHash,proto3" json:"contractDocumentHash,omitempty"`
SignatureUUID string `protobuf:"bytes,6,opt,name=signatureUUID" json:"signatureUUID,omitempty"`
SignedHash []byte `protobuf:"bytes,7,opt,name=signedHash,proto3" json:"signedHash,omitempty"`
// / SHA-512 certificate hash
RecipientKeyHash []byte `protobuf:"bytes,1,opt,name=recipientKeyHash,proto3" json:"recipientKeyHash,omitempty"`
// / SHA-512 certificate hash
SenderKeyHash []byte `protobuf:"bytes,2,opt,name=senderKeyHash,proto3" json:"senderKeyHash,omitempty"`
// / The signing sequence used
Sequence []uint32 `protobuf:"varint,3,rep,name=sequence" json:"sequence,omitempty"`
// / The list of signers hashes, as provided by the dfss file.
// The order is very important.
Signers [][]byte `protobuf:"bytes,4,rep,name=signers,proto3" json:"signers,omitempty"`
// / The contract document hash, as provided by the dfss file
ContractDocumentHash []byte `protobuf:"bytes,5,opt,name=contractDocumentHash,proto3" json:"contractDocumentHash,omitempty"`
// / The unique signature attemp ID, as provided by the platform during the ready signal
SignatureUUID string `protobuf:"bytes,6,opt,name=signatureUUID" json:"signatureUUID,omitempty"`
// / The signed metadata hashb, as provided by the platform during the ready signal
SignedHash []byte `protobuf:"bytes,7,opt,name=signedHash,proto3" json:"signedHash,omitempty"`
}
func (m *Context) Reset() { *m = Context{} }
......@@ -50,12 +60,13 @@ func (m *Context) String() string { return proto.CompactTextString(m)
func (*Context) ProtoMessage() {}
func (*Context) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{0} }
// Promise message contains all the required information to verify
// the identity of the sender and receiver, and the actual promise
type Promise struct {
// / Metadata
Context *Context `protobuf:"bytes,1,opt,name=context" json:"context,omitempty"`
Index uint32 `protobuf:"varint,2,opt,name=index" json:"index,omitempty"`
Payload []byte `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
// / The index of the sequence for this promise
Index uint32 `protobuf:"varint,2,opt,name=index" json:"index,omitempty"`
// / The crypographic payload, currently NOT IMPLEMENTED
Payload []byte `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
}
func (m *Promise) Reset() { *m = Promise{} }
......@@ -70,11 +81,11 @@ func (m *Promise) GetContext() *Context {
return nil
}
// Signature message contains all the required information to verify
// the identity of the sender and receiver, and the actual signature
type Signature struct {
// / Metadata
Context *Context `protobuf:"bytes,1,opt,name=context" json:"context,omitempty"`
Payload []byte `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
// / The crypographic payload, currently NOT IMPLEMENTED
Payload []byte `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
}
func (m *Signature) Reset() { *m = Signature{} }
......@@ -89,9 +100,9 @@ func (m *Signature) GetContext() *Context {
return nil
}
// Hello message is used when discovering peers.
// It contains the current version of the software.
// / Hello message is used when discovering peers.
type Hello struct {
// / Used version of DFSS client
Version string `protobuf:"bytes,1,opt,name=version" json:"version,omitempty"`
}
......@@ -118,8 +129,11 @@ const _ = grpc.SupportPackageIsVersion2
// Client API for Client service
type ClientClient interface {
// / Handle reception of promises.
TreatPromise(ctx context.Context, in *Promise, opts ...grpc.CallOption) (*api1.ErrorCode, error)
// / Handle receptions of signatures.
TreatSignature(ctx context.Context, in *Signature, opts ...grpc.CallOption) (*api1.ErrorCode, error)
// / Permits initial handshake for P2P between clients.
Discover(ctx context.Context, in *Hello, opts ...grpc.CallOption) (*Hello, error)
}
......@@ -161,8 +175,11 @@ func (c *clientClient) Discover(ctx context.Context, in *Hello, opts ...grpc.Cal
// Server API for Client service
type ClientServer interface {
// / Handle reception of promises.
TreatPromise(context.Context, *Promise) (*api1.ErrorCode, error)
// / Handle receptions of signatures.
TreatSignature(context.Context, *Signature) (*api1.ErrorCode, error)
// / Permits initial handshake for P2P between clients.
Discover(context.Context, *Hello) (*Hello, error)
}
......
/// Protobuf definitions for dfssc
syntax = "proto3";
package api;
import "dfss/dfssp/api/platform.proto";
/// Procedures offered by dfssc
service Client {
/// Handle reception of promises.
rpc TreatPromise(Promise) returns (ErrorCode) {}
/// Handle receptions of signatures.
rpc TreatSignature(Signature) returns (ErrorCode) {}
/// Permits initial handshake for P2P between clients.
rpc Discover(Hello) returns (Hello) {}
}
/// Context stores the current context of a specific promise or signature.
// It is a kind of "symbolic" promise, with no real cryptographic proofs inside.
message Context {
bytes recipientKeyHash = 1; // SHA-512
bytes senderKeyHash = 2; // SHA-512
repeated uint32 sequence = 3; // Signing sequence
repeated bytes signers = 4; // List of the signers' hashes
/// SHA-512 certificate hash
bytes recipientKeyHash = 1;
/// SHA-512 certificate hash
bytes senderKeyHash = 2;
/// The signing sequence used
repeated uint32 sequence = 3;
/// The list of signers hashes, as provided by the dfss file.
// The order is very important.
repeated bytes signers = 4;
/// The contract document hash, as provided by the dfss file
bytes contractDocumentHash = 5;
/// The unique signature attemp ID, as provided by the platform during the ready signal
string signatureUUID = 6;
bytes signedHash = 7; // (sequence + signers' hashes + contractDocumentHash + signatureUUID) crypted by the platform
/// The signed metadata hashb, as provided by the platform during the ready signal
bytes signedHash = 7;
}
// Promise message contains all the required information to verify
// the identity of the sender and receiver, and the actual promise
message Promise {
/// Metadata
Context context = 1;
uint32 index = 2; // The index of the sequence for this message
/// The index of the sequence for this promise
uint32 index = 2;
/// The crypographic payload, currently NOT IMPLEMENTED
bytes payload = 3;
}
// Signature message contains all the required information to verify
// the identity of the sender and receiver, and the actual signature
message Signature {
/// Metadata
Context context = 1;
/// The crypographic payload, currently NOT IMPLEMENTED
bytes payload = 2;
}
// Hello message is used when discovering peers.
// It contains the current version of the software.
/// Hello message is used when discovering peers.
message Hello {
/// Used version of DFSS client
string version = 1;
}
......@@ -32,11 +32,14 @@ var _ = math.Inf
// is compatible with the proto package it is being compiled against.
const _ = proto.ProtoPackageIsVersion1
// Log message to display information
type Log struct {
Timestamp int64 `protobuf:"varint,1,opt,name=timestamp" json:"timestamp,omitempty"`
// / Unix nano timestamp as absolute time of event
Timestamp int64 `protobuf:"varint,1,opt,name=timestamp" json:"timestamp,omitempty"`
// / Identifier of the sender.
// Should be an email, "platform" or "ttp".
Identifier string `protobuf:"bytes,2,opt,name=identifier" json:"identifier,omitempty"`
Log string `protobuf:"bytes,3,opt,name=log" json:"log,omitempty"`
// / The log message
Log string `protobuf:"bytes,3,opt,name=log" json:"log,omitempty"`
}
func (m *Log) Reset() { *m = Log{} }
......@@ -44,7 +47,7 @@ func (m *Log) String() string { return proto.CompactTextString(m) }
func (*Log) ProtoMessage() {}
func (*Log) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{0} }
// Empty ack message
// / Acknowledgement message
type Ack struct {
}
......@@ -69,10 +72,7 @@ const _ = grpc.SupportPackageIsVersion2
// Client API for Demonstrator service
type DemonstratorClient interface {
// Log message.
//
// Send the UnixNano timetamp, sender's identifier and log message
// Returns nothing ?
// / Send a new log line to the demonstrator
SendLog(ctx context.Context, in *Log, opts ...grpc.CallOption) (*Ack, error)
}
......@@ -96,10 +96,7 @@ func (c *demonstratorClient) SendLog(ctx context.Context, in *Log, opts ...grpc.
// Server API for Demonstrator service
type DemonstratorServer interface {
// Log message.
//
// Send the UnixNano timetamp, sender's identifier and log message
// Returns nothing ?
// / Send a new log line to the demonstrator
SendLog(context.Context, *Log) (*Ack, error)
}
......
/// Protobuf definitions for dfssd
syntax = "proto3";
package api;
/// Procedures offered by dfssd
service Demonstrator {
// Log message.
//
// Send the UnixNano timetamp, sender's identifier and log message
// Returns nothing ?
rpc SendLog(Log) returns (Ack) {}
/// Send a new log line to the demonstrator
rpc SendLog(Log) returns (Ack) {}
}
// Log message to display information
message Log {
int64 timestamp = 1;
string identifier = 2;
string log = 3;
/// Unix nano timestamp as absolute time of event
int64 timestamp = 1;
/// Identifier of the sender.
// Should be an email, "platform" or "ttp".
string identifier = 2;
/// The log message
string log = 3;
}
// Empty ack message
/// Acknowledgement message
message Ack {
}
This diff is collapsed.
/// Protobuf definitions for dfssp
syntax = "proto3";
package api;
/// Procedures offered by dfssp
service Platform {
/// Register a new user, no authentication required.
rpc Register(RegisterRequest) returns (ErrorCode) {}
/// Authenticate a previously registered user, no authentication required.
rpc Auth(AuthRequest) returns (RegisteredUser) {}
/// Unregister a new user, authentication required.
rpc Unregister(Empty) returns (ErrorCode) {}
/// Create a new contract, authentication required.
rpc PostContract(PostContractRequest) returns (ErrorCode) {}
/// Fetch a previously create contract, authentication required.
rpc GetContract(GetContractRequest) returns (Contract) {}
/// Join a signature discovery room, authentication required.
// The stream is triggered for each new user connected in this channel.
rpc JoinSignature(JoinSignatureRequest) returns (stream UserConnected) {}
rpc ReadySign(ReadySignRequest) returns (LaunchSignature) {} // Warning, LaunchSignature can be emitted with a very high delay
/// Join an ignition room, authentication required.
// The response is returned when every signer is ready for a specific contract.
// Warning, can me answered with a very high delay.
rpc ReadySign(ReadySignRequest) returns (LaunchSignature) {}
}
// RegisterRequest message contains the client's email adress and his
// request (ie the PEM-encoded certificate request)
message RegisterRequest {
/// User mail
string email = 1;
/// Certificate request (CSR) as PEM
string request = 2;
}
// ErrorCode message contains an error code and a message
/// ErrorCode message contains an error code and a message.
//
// Above or zero : target-side error
//
// Less than 0 : local error
message ErrorCode {
enum Code {
// SUCCESS is the error code for a successful request
/// the error code for a successful request
SUCCESS = 0;
// INVARG is the error code for an invalid argument
/// the error code for an invalid argument
INVARG = 1;
// BADAUTH is the error code for a bad authentication
/// the error code for a bad authentication
BADAUTH = 2;
// WARNING is the error code for a success state containing a specific warning message
/// the error code for a success state containing a specific warning message
WARNING = 3;
// INTERR is the error code for an internal server error
/// the error code for an internal server error
INTERR = -1;
// TIMEOUT is the error code for a timeout or unreacheable target
/// the error code for a timeout or unreacheable target
TIMEOUT = -2;
}
Code code = 1;
/// An additional message, if needed
string message = 2;
}
// AuthRequest message contains the client's email adress and the token used
// for authentication
message AuthRequest {
/// User email
string email = 1;
/// User authentication token
string token = 2;
}
// RegisteredUser message contains the generated client certificate
// (PEM-encoded)
message RegisteredUser {
/// User certificate, as generated by the platform (PEM)
string clientCert = 1;
}
// Empty message is an empty message
/// An empty message, used when no parameters are required for a query or an answer.
message Empty {
}
// PostContractRequest message contains the contract as SHA-512 hash, its filename,
// the list of signers as an array of strings, and a comment
message PostContractRequest {
/// Contract SHA-512 hash
bytes hash = 1;
/// Contract filename
string filename = 2;
/// List of signers emails
repeated string signer = 3;
/// Additional comment
string comment = 4;
}
// GetContractRequest message contains the uuid of the asked contract
message GetContractRequest {
/// UUID of the requested contract
string uuid = 1;
}
// Contract is the return value when a contract is fetched from the platform.
// The contract is in json format to avoid duplicating structures.
/// The fetched contract when using GetContract
message Contract {
/// The result code
ErrorCode errorCode = 1;
/// The JSON object of the contract, equivalent to the one that was sent by mail to signers
bytes json = 2;
}
// JoinSignatureRequest message contains the contract to join unique identifier
// and the port the client will be listening at
message JoinSignatureRequest {
/// The contract UUID to join
string contractUuid = 1;
/// The open port for P2P communication of the client
uint32 port = 2;
}
// UserConnected is emitted by the platform to the client to announce a new client connection
/// UserConnected is emitted by the platform to the client to announce a new client connection, through a stream.
// Previously connected clients are also emitted one by one just after the beginning of the stream.
message UserConnected {
/// The result code.
// Very bad if not equals to SUCCESS, in this case the client should close the connection
ErrorCode errorCode = 1;
/// A confirmation about the contract UUID
string contractUuid = 2;
/// One user connecting to this contract's room
User user = 3;
}
message User {
/// The certificate hash of the user
bytes keyHash = 1;
string email = 2;
/// The IP offered by the user for P2P
string ip = 3;
/// The port offered by the user for P2P
uint32 port = 4;
}
// ReadySignRequest contains the contract unique identitier that is ready to be signed
message ReadySignRequest {
/// The contract UUID to be ready for
string contractUuid = 1;
}
// LaunchSignature is emitted by the platform when every signers are ready
/// LaunchSignature is emitted by the platform when every signers of a specific contract are ready.
message LaunchSignature {
/// The result code
ErrorCode errorCode = 1;
/// The unique signature generated by the platform for this specific signature attempt
string signatureUuid = 2;
/// A confirmation of client hashes for communication authentication
repeated bytes keyHash = 3;
/// The signing sequence generated on-the-fly by the platform
repeated uint32 sequence = 4;
bytes hash = 5; // (text Hash + sequence + signatureUUID + signers' hashes ) crypted by the platform
/// The cryptographic object of the signature of this structure (hash excepted) by the platform, for data certification.
bytes hash = 5;
}
......@@ -34,8 +34,8 @@ var _ = math.Inf
// is compatible with the proto package it is being compiled against.
const _ = proto.ProtoPackageIsVersion1
// Alert message sent by a signer
type AlertRequest struct {
// / Promises obtained at this point of the main protocol
Promises []*api2.Promise `protobuf:"bytes,1,rep,name=promises" json:"promises,omitempty"`
}
......@@ -51,7 +51,6 @@ func (m *AlertRequest) GetPromises() []*api2.Promise {
return nil
}
// RecoverRequest message to get a signed contract
type RecoverRequest struct {
SignatureUUID string `protobuf:"bytes,1,opt,name=signatureUUID" json:"signatureUUID,omitempty"`
}
......@@ -61,11 +60,9 @@ func (m *RecoverRequest) String() string { return proto.CompactTextSt
func (*RecoverRequest) ProtoMessage() {}
func (*RecoverRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{1} }
// TTPResponse message to answer an Alert or Recover message
type TTPResponse struct {
// Yes for abort token, No for signed contract
Abort bool `protobuf:"varint,1,opt,name=abort" json:"abort,omitempty"`
// Nil for abort token, non-empty otherwise
// / True for abort token, False when the TTP was able to generate the fully signed contract
Abort bool `protobuf:"varint,1,opt,name=abort" json:"abort,omitempty"`
Contract []byte `protobuf:"bytes,2,opt,name=contract,proto3" json:"contract,omitempty"`
}
......@@ -91,7 +88,11 @@ const _ = grpc.SupportPackageIsVersion2
// Client API for TTP service
type TTPClient interface {
// / Sent by a client when a signature encounters a problem.
// Triggers the resolve protocol.
Alert(ctx context.Context, in *AlertRequest, opts ...grpc.CallOption) (*TTPResponse, error)
// / Sent by a client after a crash or a self-deconnection.
// Tries to fetch the result of the resolve protocol, if any.
Recover(ctx context.Context, in *RecoverRequest, opts ...grpc.CallOption) (*TTPResponse, error)
}
......@@ -124,7 +125,11 @@ func (c *tTPClient) Recover(ctx context.Context, in *RecoverRequest, opts ...grp
// Server API for TTP service
type TTPServer interface {
// / Sent by a client when a signature encounters a problem.
// Triggers the resolve protocol.
Alert(context.Context, *AlertRequest) (*TTPResponse, error)
// / Sent by a client after a crash or a self-deconnection.
// Tries to fetch the result of the resolve protocol, if any.
Recover(context.Context, *RecoverRequest) (*TTPResponse, error)
}
......
/// Protobuf definitions for dfsst
syntax = "proto3";
package api;
import "dfss/dfssc/api/client.proto";
/// Procedures offered by dfsst
service TTP {
rpc Alert(AlertRequest) returns (TTPResponse) {}
rpc Recover(RecoverRequest) returns (TTPResponse) {}
/// Sent by a client when a signature encounters a problem.
// Triggers the resolve protocol.
rpc Alert(AlertRequest) returns (TTPResponse) {}
/// Sent by a client after a crash or a self-deconnection.
// Tries to fetch the result of the resolve protocol, if any.
rpc Recover(RecoverRequest) returns (TTPResponse) {}
}
// Alert message sent by a signer
message AlertRequest {
/// Promises obtained at this point of the main protocol
repeated Promise promises = 1;
}
// RecoverRequest message to get a signed contract
message RecoverRequest {
string signatureUUID = 1;
}
// TTPResponse message to answer an Alert or Recover message
message TTPResponse {
// Yes for abort token, No for signed contract
bool abort = 1;
// Nil for abort token, non-empty otherwise
bytes contract = 2;
/// True for abort token, False when the TTP was able to generate the fully signed contract
bool abort = 1;
bytes contract = 2;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment