frostfs-api/proto-docs/session.md
Stanislav Bogatyrev a37a7c5ef4 Release v2.3.0 - Seonyudo (선유도, 仙遊島)
UN-LOCODE support and Container's used space reporting

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
2021-02-11 16:38:54 +03:00

13 KiB

Protocol Documentation

Table of Contents

Top

session/service.proto

Service "neo.fs.v2.session.SessionService"

SessionService allows to establish a temporary trust relationship between two peer nodes and generate a SessionToken as the proof of trust to be attached in requests for further verification. Please see corresponding section of NeoFS Technical Specification for details.

rpc Create(CreateRequest) returns (CreateResponse);

Method Create

Opens a new session between two peers.

Name Input Output
Create CreateRequest CreateResponse

Message CreateRequest

Information necessary for opening a session.

Field Type Label Description
body CreateRequest.Body Body of create session token request message.
meta_header RequestMetaHeader Carries request meta information. Header data is used only to regulate message transport and does not affect request execution.
verify_header RequestVerificationHeader Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message CreateRequest.Body

Session creation request body

Field Type Label Description
owner_id neo.fs.v2.refs.OwnerID Session initiating user's or node's key derived OwnerID
expiration uint64 Session expiration Epoch

Message CreateResponse

Information about the opened session.

Field Type Label Description
body CreateResponse.Body Body of create session token response message.
meta_header ResponseMetaHeader Carries response meta information. Header data is used only to regulate message transport and does not affect request execution.
verify_header ResponseVerificationHeader Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission.

Message CreateResponse.Body

Session creation response body

Field Type Label Description
id bytes Identifier of a newly created session
session_key bytes Public key used for session

Top

session/types.proto

Message ObjectSessionContext

Context information for Session Tokens related to ObjectService requests

Field Type Label Description
verb ObjectSessionContext.Verb Type of request for which the token is issued
address neo.fs.v2.refs.Address Related Object address

Message RequestMetaHeader

Meta information attached to the request. When forwarded between peers, request meta headers are folded in matryoshka style.

Field Type Label Description
version neo.fs.v2.refs.Version Peer's API version used
epoch uint64 Peer's local epoch number. Set to 0 if unknown.
ttl uint32 Maximum number of intermediate nodes in the request route
x_headers XHeader repeated Request X-Headers
session_token SessionToken Session token within which the request is sent
bearer_token neo.fs.v2.acl.BearerToken BearerToken with eACL overrides for the request
origin RequestMetaHeader RequestMetaHeader of the origin request

Message RequestVerificationHeader

Verification info for request signed by all intermediate nodes.

Field Type Label Description
body_signature neo.fs.v2.refs.Signature Request Body signature. Should be generated once by request initiator.
meta_signature neo.fs.v2.refs.Signature Request Meta signature is added and signed by each intermediate node
origin_signature neo.fs.v2.refs.Signature Signature of previous hops
origin RequestVerificationHeader Chain of previous hops signatures

Message ResponseMetaHeader

Information about the response

Field Type Label Description
version neo.fs.v2.refs.Version Peer's API version used
epoch uint64 Peer's local epoch number
ttl uint32 Maximum number of intermediate nodes in the request route
x_headers XHeader repeated Response X-Headers
origin ResponseMetaHeader ResponseMetaHeader of the origin request

Message ResponseVerificationHeader

Verification info for response signed by all intermediate nodes

Field Type Label Description
body_signature neo.fs.v2.refs.Signature Response Body signature. Should be generated once by answering node.
meta_signature neo.fs.v2.refs.Signature Response Meta signature is added and signed by each intermediate node
origin_signature neo.fs.v2.refs.Signature Signature of previous hops
origin ResponseVerificationHeader Chain of previous hops signatures

Message SessionToken

NeoFS Session Token.

Field Type Label Description
body SessionToken.Body Session Token contains the proof of trust between peers to be attached in requests for further verification. Please see corresponding section of NeoFS Technical Specification for details.
signature neo.fs.v2.refs.Signature Signature of SessionToken information

Message SessionToken.Body

Session Token body

Field Type Label Description
id bytes Token identifier is a valid UUIDv4 in binary form
owner_id neo.fs.v2.refs.OwnerID Identifier of the session initiator
lifetime SessionToken.Body.TokenLifetime Lifetime of the session
session_key bytes Public key used in session
object ObjectSessionContext ObjectService session context

Message SessionToken.Body.TokenLifetime

Lifetime parameters of the token. Field names taken from rfc7519.

Field Type Label Description
exp uint64 Expiration Epoch
nbf uint64 Not valid before Epoch
iat uint64 Issued at Epoch

Message XHeader

Extended headers for Request/Response. May contain any user-defined headers to be interpreted on application level.

Key name must be unique valid UTF-8 string. Value can't be empty. Requests or Responses with duplicated header names or headers with empty values will be considered invalid.

There are some "well-known" headers starting with __NEOFS__ prefix that affect system behaviour:

  • __NEOFS__NETMAP_EPOCH
    Netmap epoch to use for object placement calculation. The value is string encoded uint64 in decimal presentation. If set to '0' or not set, the current epoch only will be used.
  • __NEOFS__NETMAP_LOOKUP_DEPTH
    If object can't be found using current epoch's netmap, this header limits how many past epochs back the node can lookup. The value is string encoded uint64 in decimal presentation. If set to '0' or not set, the current epoch only will be used.
Field Type Label Description
key string Key of the X-Header
value string Value of the X-Header

ObjectSessionContext.Verb

Object request verbs

Name Number Description
VERB_UNSPECIFIED 0 Unknown verb
PUT 1 Refers to object.Put RPC call
GET 2 Refers to object.Get RPC call
HEAD 3 Refers to object.Head RPC call
SEARCH 4 Refers to object.Search RPC call
DELETE 5 Refers to object.Delete RPC call
RANGE 6 Refers to object.GetRange RPC call
RANGEHASH 7 Refers to object.GetRangeHash RPC call

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