From b72847006afadb19186f8a526125cd97f400fd7e Mon Sep 17 00:00:00 2001 From: Stanislav Bogatyrev Date: Fri, 16 Oct 2020 09:20:47 +0300 Subject: [PATCH] Update session package docs Signed-off-by: Stanislav Bogatyrev --- session/service.proto | 36 +++++++++++++---------- session/types.proto | 68 ++++++++++++++++++++++--------------------- 2 files changed, 55 insertions(+), 49 deletions(-) diff --git a/session/service.proto b/session/service.proto index 5ecfe52..40c5255 100644 --- a/session/service.proto +++ b/session/service.proto @@ -8,41 +8,45 @@ option csharp_namespace = "NeoFS.API.v2.Session"; import "refs/types.proto"; import "session/types.proto"; -// Create Session record on Node side +// `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. service SessionService { - // Create opens new session between the client and the server. + // Opens a new session between two peers. rpc Create (CreateRequest) returns (CreateResponse); } -// CreateRequest carries an information necessary for opening a session. +// Information necessary for opening a session. message CreateRequest { - // Request body + // Session creation request body message Body { - // Carries an identifier of a session initiator. + // Dession initiating user's or node's key derived `OwnerID`. neo.fs.v2.refs.OwnerID owner_id = 1; - // Expiration Epoch + // Session expiration `Epoch` uint64 expiration = 2; } // Body of create session token request message. Body body = 1; - // Carries request meta information. Header data is used only to regulate message - // transport and does not affect request execution. + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. neo.fs.v2.session.RequestMetaHeader meta_header = 2; - // Carries request verification information. This header is used to authenticate - // the nodes of the message route and check the correctness of transmission. + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } -// CreateResponse carries an information about the opened session. +// Information about the opened session. message CreateResponse { - // Response body + // Session creation response body message Body { - // id carries an identifier of session token. + // Identifier of a newly created session bytes id = 1; - // session_key carries a session public key. + // Public key used for session bytes session_key = 2; } @@ -54,7 +58,7 @@ message CreateResponse { neo.fs.v2.session.ResponseMetaHeader meta_header = 2; // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness - // of transmission. + // authenticate the nodes of the message route and check the correctness of + // transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } diff --git a/session/types.proto b/session/types.proto index 0f21b93..ed5442f 100644 --- a/session/types.proto +++ b/session/types.proto @@ -36,21 +36,21 @@ message ObjectSessionContext { // Refers to object.GetRangeHash RPC call RANGEHASH = 7; } - // Verb is a type of request for which the token is issued + // Type of request for which the token is issued Verb verb = 1; // Related Object address neo.fs.v2.refs.Address address = 2; } -// NeoFS session token. +// NeoFS Session Token. message SessionToken { - // Session token body + // Session Token body message Body { - // ID is a token identifier. valid UUIDv4 represented in bytes + // Token identifier is a valid UUIDv4 in binary form bytes id = 1; - // OwnerID carries identifier of the session initiator. + // Identifier of the session initiator neo.fs.v2.refs.OwnerID owner_id = 2; // Lifetime parameters of the token. Filed names taken from rfc7519. @@ -64,84 +64,86 @@ message SessionToken { // Issued at Epoch uint64 iat = 3; } - // Lifetime is a lifetime of the session + // Lifetime of the session TokenLifetime lifetime = 3; - // SessionKey is a public key of session key + // Public key used in session bytes session_key = 4; - // Carries context of the session. + // Session Context information oneof context { - // ObjectService session context. + // ObjectService session context ObjectSessionContext object = 5; } } - // Session Token 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. Body body = 1; - // Signature is a signature of session token information + // Signature of `SessionToken` information neo.fs.v2.refs.Signature signature = 2; } -// Extended headers for Request/Response +// Extended headers for Request/Response. message XHeader { - // Key of the X-Header. + // Key of the X-Header string key = 1; - // Value of the X-Header. + // Value of the X-Header string value = 2; } - -// Information about the request +// Meta information attached to the request. When forwarded between peers, +// request meta headers are folded in matryoshka style. message RequestMetaHeader { - // Client API version. + // Peer's API version used neo.fs.v2.refs.Version version = 1; - // Client local epoch number. Set to 0 if unknown. + // Peer's local epoch number. Set to 0 if unknown. uint64 epoch = 2; - // Maximum number of nodes in the request route. + // Maximum number of intermediate nodes in the request route uint32 ttl = 3; - // Request X-Headers. + // Request X-Headers repeated XHeader x_headers = 4; - // Token is a token of the session within which the request is sent + // Session token within which the request is sent SessionToken session_token = 5; - // Bearer is a Bearer token of the request + // `BearerToken` with eACL overrides for the request neo.fs.v2.acl.BearerToken bearer_token = 6; - // RequestMetaHeader of the origin request. + // `RequestMetaHeader` of the origin request RequestMetaHeader origin = 7; } // Information about the response message ResponseMetaHeader { - // Server API version. + // Peer's API version used neo.fs.v2.refs.Version version = 1; - // Server local epoch number. + // Peer's local epoch number uint64 epoch = 2; - // Maximum number of nodes in the response route. + // Maximum number of intermediate nodes in the request route uint32 ttl = 3; - // Response X-Headers. + // Response X-Headers repeated XHeader x_headers = 4; - // Carries response meta header of the origin response. + // `ResponseMetaHeader` of the origin request ResponseMetaHeader origin = 5; } -// Verification info for request signed by all intermediate nodes +// Verification info for request signed by all intermediate nodes. message RequestVerificationHeader { // Request Body signature. Should be generated once by request initiator. neo.fs.v2.refs.Signature body_signature = 1; - // Request Meta signature is added and signed by any intermediate node + // Request Meta signature is added and signed by each intermediate node neo.fs.v2.refs.Signature meta_signature = 2; - // Sign previous hops + // Signature of previous hops neo.fs.v2.refs.Signature origin_signature = 3; // Chain of previous hops signatures @@ -152,9 +154,9 @@ message RequestVerificationHeader { message ResponseVerificationHeader { // Response Body signature. Should be generated once by answering node. neo.fs.v2.refs.Signature body_signature = 1; - // Response Meta signature is added and signed by any intermediate node + // Response Meta signature is added and signed by each intermediate node neo.fs.v2.refs.Signature meta_signature = 2; - // Sign previous hops + // Signature of previous hops neo.fs.v2.refs.Signature origin_signature = 3; // Chain of previous hops signatures