forked from TrueCloudLab/frostfs-api
12 KiB
12 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.
| 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 | Dession 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 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. Filed 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.
| 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 |