Skip to content

Latest commit

 

History

History
364 lines (238 loc) · 15.8 KB

session.md

File metadata and controls

364 lines (238 loc) · 15.8 KB

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

Open a new session between two peers.

Statuses:

  • OK (0, SECTION_SUCCESS): session has been successfully opened;
  • Common failures (SECTION_FAILURE_COMMON).
Name Input Output
Create CreateRequest CreateResponse

Message CreateRequest

Information necessary for opening a session.

Field Type Label Description
body CreateRequest.Body Body of a 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, the last epoch when session is valid.

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 ContainerSessionContext

Context information for Session Tokens related to ContainerService requests.

Field Type Label Description
verb ContainerSessionContext.Verb Type of request for which the token is issued
wildcard bool Spreads the action to all owner containers. If set, container_id field is ignored.
container_id neo.fs.v2.refs.ContainerID Particular container to which the action applies. Ignored if wildcard flag is set.

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
target ObjectSessionContext.Target Object session target. MUST be correctly formed and set. If objects field is not empty, then the session applies only to these elements, otherwise, to all objects from the specified container.

Message ObjectSessionContext.Target

Carries objects involved in the object session.

Field Type Label Description
container neo.fs.v2.refs.ContainerID Indicates which container the session is spread to. Field MUST be set and correct.
objects neo.fs.v2.refs.ObjectID repeated Indicates which objects the session is spread to. Objects are expected to be stored in the NeoFS container referenced by container field. Each element MUST have correct format.

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
magic_number uint64 NeoFS network magic. Must match the value for the network that the server belongs to.

Message RequestVerificationHeader

Verification info for the 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 the 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
status neo.fs.v2.status.Status Status return

Message ResponseVerificationHeader

Verification info for the 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 an 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
container ContainerSessionContext ContainerService session context

Message SessionToken.Body.TokenLifetime

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

Field Type Label Description
exp uint64 Expiration epoch, the last epoch when token is valid.
nbf uint64 Not valid before epoch, the first epoch when token is valid.
iat uint64 Issued at Epoch

Message XHeader

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

Key name must be a 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. DEPRECATED: header ignored by servers.
  • __NEOFS__NETMAP_LOOKUP_DEPTH
    If object can't be found using current epoch's netmap, this header limits how many past epochs the node can look up through. The value is string encoded uint64 in decimal presentation. If set to '0' or not set, only the current epoch will be used. DEPRECATED: header ignored by servers.
Field Type Label Description
key string Key of the X-Header
value string Value of the X-Header

ContainerSessionContext.Verb

Container request verbs

Name Number Description
VERB_UNSPECIFIED 0 Unknown verb
PUT 1 Refers to container.Put RPC call
DELETE 2 Refers to container.Delete RPC call
SETEACL 3 Refers to container.SetExtendedACL RPC call

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