frostfs-api/proto-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"

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

Method Create

Create is a method that used to 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

• First client stream message SHOULD BE type of CreateRequest_Init.
• First server stream message SHOULD BE type of CreateResponse_Unsigned.
• Second client stream message SHOULD BE type of CreateRequest_Signed.
• Second server stream message SHOULD BE type of CreateResponse_Result.

Name	Input	Output
Create	CreateRequest	CreateResponse

Message CreateRequest

Field	Type	Label	Description
Init	Token		Init is a message to initialize 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
Meta	service.RequestMetaHeader		RequestMetaHeader contains information about request meta headers (should be embedded into message)
Verify	service.RequestVerificationHeader		RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)

Message CreateResponse

Field	Type	Label	Description
Unsigned	Token		Unsigned token with token ID and session public key generated on server side
Result	Token		Result is a 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		OwnerID is an owner of manipulation object
FirstEpoch	uint64		FirstEpoch is an initial epoch of token lifetime
LastEpoch	uint64		LastEpoch is a last epoch of token lifetime
ObjectID	bytes	repeated	ObjectID is an object identifier of manipulation object
Signature	bytes		Signature is a token signature, signed by owner of manipulation object
ID	bytes		ID is a token identifier. valid UUIDv4 represented in bytes
PublicKeys	bytes	repeated	PublicKeys associated with owner

Message VerificationHeader

Field	Type	Label	Description
PublicKey	bytes		PublicKey is a session public key
KeySignature	bytes		KeySignature is a 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