frostfs-api-go/docs/session.md

Protocol Documentation

Table of Contents

• session/service.proto

• Services

  • Session

• Messages

  • CreateRequest
  • CreateResponse

• session/types.proto

  • Messages
    • Token
    • VerificationHeader

• Scalar Value Types

Top

session/service.proto

Service "session.Session"

Open a trusted session to manipulate an object. In order to put or delete object client have to obtain session token with trusted node. Trusted node will modify client's object (add missing headers, checksums, homomorphic hash) and sign id with session key. Session is established during 4-step handshake in one gRPC stream

rpc Create(stream CreateRequest) returns (stream CreateResponse);

Method Create

Name	Input	Output
Create	CreateRequest	CreateResponse

Message CreateRequest

Field	Type	Label	Description
Init	Token		Message to init session opening. Carry: owner of manipulation object; ID of manipulation object; token lifetime bounds.
Signed	Token		Signed Init message response (Unsigned) from server with user private key

Message CreateResponse

Field	Type	Label	Description
Unsigned	Token		Unsigned token with token ID and session public key generated on server side
Result	Token		Resulting token which can be used for object placing through an trusted intermediary

Top

session/types.proto

Message Token

User token granting rights for object manipulation

Field	Type	Label	Description
Header	VerificationHeader		Header carries verification data of session key
OwnerID	bytes		Owner of manipulation object
FirstEpoch	uint64		Initial epoch of token lifetime
LastEpoch	uint64		Last epoch of token lifetime
ObjectID	bytes	repeated	ID of manipulation object
Signature	bytes		Token signature. Signed by owner of manipulation object
ID	bytes		Token ID (UUID)

Message VerificationHeader

Field	Type	Label	Description
PublicKey	bytes		Session public key
KeySignature	bytes		Session public key signature. Signed by trusted side

Scalar Value Types

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str