15 KiB
15 KiB
Protocol Documentation
Table of Contents
-
Services
-
Messages
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.
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 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 |
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 | |
| 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 |
|
| magic_number | uint64 | NeoFS network magic. Must match the value for the network that the server belongs to. |
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 |
|
| status | neo.fs.v2.status.Status | Status return |
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 | |
| 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 | |
| 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. Thevalueis string encodeduint64in 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. Thevalueis string encodeduint64in 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 |
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 |