Skip to content

Commit 11f58a6

Browse files
End-reyEnd-rey
committed
session: add a new session token v2
Session Token v2 solves the delegation, power of attorney, and chain-of-trust problems. It enables: - Account-based authority (direct or NNS-based indirect) - Multi-account subjects (multiple entities can use same token) - Multi-verb operations (GET, PUT, DELETE in single token) - Delegation chains (verifiable like X.509 certificates) - Indirect accounts (NeoFS Name Service resolution) Refs #241. Signed-off-by: Andrey Butusov <andrey@nspcc.io>
1 parent 2fb0e58 commit 11f58a6

File tree

3 files changed

+431
-15
lines changed

3 files changed

+431
-15
lines changed

‎proto-docs/session.md‎

Lines changed: 210 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,23 +10,34 @@
1010
- Messages
1111
- [CreateRequest](#neo.fs.v2.session.CreateRequest)
1212
- [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body)
13+
- [CreateRequestV2](#neo.fs.v2.session.CreateRequestV2)
14+
- [CreateRequestV2.Body](#neo.fs.v2.session.CreateRequestV2.Body)
1315
- [CreateResponse](#neo.fs.v2.session.CreateResponse)
1416
- [CreateResponse.Body](#neo.fs.v2.session.CreateResponse.Body)
17+
- [CreateResponseV2](#neo.fs.v2.session.CreateResponseV2)
18+
- [CreateResponseV2.Body](#neo.fs.v2.session.CreateResponseV2.Body)
1519

1620

1721
- [session/types.proto](#session/types.proto)
1822

1923
- Messages
24+
- [Account](#neo.fs.v2.session.Account)
2025
- [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext)
26+
- [ContainerSessionContextV2](#neo.fs.v2.session.ContainerSessionContextV2)
27+
- [DelegationInfo](#neo.fs.v2.session.DelegationInfo)
2128
- [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext)
2229
- [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target)
30+
- [ObjectSessionContextV2](#neo.fs.v2.session.ObjectSessionContextV2)
31+
- [ObjectSessionContextV2.Target](#neo.fs.v2.session.ObjectSessionContextV2.Target)
2332
- [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader)
2433
- [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader)
2534
- [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader)
2635
- [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader)
2736
- [SessionToken](#neo.fs.v2.session.SessionToken)
2837
- [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body)
29-
- [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime)
38+
- [SessionTokenV2](#neo.fs.v2.session.SessionTokenV2)
39+
- [SessionTokenV2.Body](#neo.fs.v2.session.SessionTokenV2.Body)
40+
- [TokenLifetime](#neo.fs.v2.session.TokenLifetime)
3041
- [XHeader](#neo.fs.v2.session.XHeader)
3142

3243

@@ -52,6 +63,7 @@ section of NeoFS Technical Specification for details.
5263

5364
```
5465
rpc Create(CreateRequest) returns (CreateResponse);
66+
rpc CreateV2(CreateRequestV2) returns (CreateResponseV2);
5567
5668
```
5769

@@ -67,6 +79,18 @@ session has been successfully opened;
6779
| Name | Input | Output |
6880
| ---- | ----- | ------ |
6981
| Create | [CreateRequest](#neo.fs.v2.session.CreateRequest) | [CreateResponse](#neo.fs.v2.session.CreateResponse) |
82+
#### Method CreateV2
83+
84+
Create a new session token v2 with delegation and chain-of-trust support.
85+
86+
Statuses:
87+
- **OK** (0, SECTION_SUCCESS):
88+
session token v2 has been successfully created;
89+
- Common failures (SECTION_FAILURE_COMMON).
90+
91+
| Name | Input | Output |
92+
| ---- | ----- | ------ |
93+
| CreateV2 | [CreateRequestV2](#neo.fs.v2.session.CreateRequestV2) | [CreateResponseV2](#neo.fs.v2.session.CreateResponseV2) |
7094
<!-- end services -->
7195

7296

@@ -95,6 +119,35 @@ Session creation request body
95119
| expiration | [uint64](#uint64) | | Session expiration epoch, the last epoch when session is valid. |
96120

97121

122+
<a name="neo.fs.v2.session.CreateRequestV2"></a>
123+
124+
### Message CreateRequestV2
125+
CreateRequestV2 is information necessary for creating a session token v2.
126+
127+
128+
| Field | Type | Label | Description |
129+
| ----- | ---- | ----- | ----------- |
130+
| body | [CreateRequestV2.Body](#neo.fs.v2.session.CreateRequestV2.Body) | | Body of create session token v2 request message |
131+
| meta_header | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
132+
| verify_header | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
133+
134+
135+
<a name="neo.fs.v2.session.CreateRequestV2.Body"></a>
136+
137+
### Message CreateRequestV2.Body
138+
Session creation request v2 body
139+
140+
141+
| Field | Type | Label | Description |
142+
| ----- | ---- | ----- | ----------- |
143+
| issuer | [Account](#neo.fs.v2.session.Account) | | Issuer of the session token |
144+
| subjects | [Account](#neo.fs.v2.session.Account) | repeated | Subjects authorized by this token |
145+
| expiration | [int64](#int64) | | Session expiration time |
146+
| created_at | [int64](#int64) | | Session creation time |
147+
| object | [ObjectSessionContextV2](#neo.fs.v2.session.ObjectSessionContextV2) | | |
148+
| container | [ContainerSessionContextV2](#neo.fs.v2.session.ContainerSessionContextV2) | | |
149+
150+
98151
<a name="neo.fs.v2.session.CreateResponse"></a>
99152

100153
### Message CreateResponse
@@ -119,6 +172,30 @@ Session creation response body
119172
| id | [bytes](#bytes) | | Identifier of a newly created session |
120173
| session_key | [bytes](#bytes) | | Public key used for session |
121174

175+
176+
<a name="neo.fs.v2.session.CreateResponseV2"></a>
177+
178+
### Message CreateResponseV2
179+
CreateResponseV2 is information about a newly created session token v2.
180+
181+
182+
| Field | Type | Label | Description |
183+
| ----- | ---- | ----- | ----------- |
184+
| body | [CreateResponseV2.Body](#neo.fs.v2.session.CreateResponseV2.Body) | | Body of create session token v2 response message |
185+
| meta_header | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
186+
| verify_header | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
187+
188+
189+
<a name="neo.fs.v2.session.CreateResponseV2.Body"></a>
190+
191+
### Message CreateResponseV2.Body
192+
Session creation response v2 body
193+
194+
195+
| Field | Type | Label | Description |
196+
| ----- | ---- | ----- | ----------- |
197+
| token | [SessionTokenV2](#neo.fs.v2.session.SessionTokenV2) | | The session token v2 with delegation and chain-of-trust support |
198+
122199
<!-- end messages -->
123200

124201
<!-- end enums -->
@@ -134,6 +211,19 @@ Session creation response body
134211
<!-- end services -->
135212

136213

214+
<a name="neo.fs.v2.session.Account"></a>
215+
216+
### Message Account
217+
Account represents an identity in NeoFS.
218+
It can be either direct (OwnerID) or indirect (NNS domain).
219+
220+
221+
| Field | Type | Label | Description |
222+
| ----- | ---- | ----- | ----------- |
223+
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Direct account reference via OwnerID (hash of public key) |
224+
| nns_name | [string](#string) | | Indirect account reference via NeoFS Name Service |
225+
226+
137227
<a name="neo.fs.v2.session.ContainerSessionContext"></a>
138228

139229
### Message ContainerSessionContext
@@ -147,6 +237,35 @@ Context information for Session Tokens related to ContainerService requests.
147237
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Particular container to which the action applies. Ignored if wildcard flag is set. |
148238

149239

240+
<a name="neo.fs.v2.session.ContainerSessionContextV2"></a>
241+
242+
### Message ContainerSessionContextV2
243+
ContainerSessionContextV2 carries context for ContainerService requests.
244+
Extended version supporting multiple verbs.
245+
246+
247+
| Field | Type | Label | Description |
248+
| ----- | ---- | ----- | ----------- |
249+
| verbs | [ContainerSessionContextV2.Verb](#neo.fs.v2.session.ContainerSessionContextV2.Verb) | repeated | Multiple verbs this context authorizes |
250+
| wildcard | [bool](#bool) | | If true, applies to all containers owned by the subject |
251+
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Particular container to which the action applies Ignored if wildcard is true |
252+
253+
254+
<a name="neo.fs.v2.session.DelegationInfo"></a>
255+
256+
### Message DelegationInfo
257+
DelegationInfo represents a single delegation in a chain of trust.
258+
259+
260+
| Field | Type | Label | Description |
261+
| ----- | ---- | ----- | ----------- |
262+
| issuer | [Account](#neo.fs.v2.session.Account) | | Account that performed this delegation |
263+
| subject | [Account](#neo.fs.v2.session.Account) | | Account that received the delegation |
264+
| timestamp | [int64](#int64) | | Unix timestamp when this delegation was created |
265+
| verbs | [string](#string) | repeated | List of verbs authorized by this delegation |
266+
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the issuer confirming this delegation record. The signature is created over the deterministic serialization of this DelegationInfo message excluding this field. |
267+
268+
150269
<a name="neo.fs.v2.session.ObjectSessionContext"></a>
151270

152271
### Message ObjectSessionContext
@@ -171,6 +290,31 @@ Carries objects involved in the object session.
171290
| objects | [neo.fs.v2.refs.ObjectID](#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. |
172291

173292

293+
<a name="neo.fs.v2.session.ObjectSessionContextV2"></a>
294+
295+
### Message ObjectSessionContextV2
296+
ObjectSessionContextV2 carries context for ObjectService requests.
297+
Extended version supporting multiple verbs and targets.
298+
299+
300+
| Field | Type | Label | Description |
301+
| ----- | ---- | ----- | ----------- |
302+
| verbs | [ObjectSessionContextV2.Verb](#neo.fs.v2.session.ObjectSessionContextV2.Verb) | repeated | Multiple verbs this context authorizes |
303+
| targets | [ObjectSessionContextV2.Target](#neo.fs.v2.session.ObjectSessionContextV2.Target) | repeated | Target resource(s) this authorization applies to |
304+
305+
306+
<a name="neo.fs.v2.session.ObjectSessionContextV2.Target"></a>
307+
308+
### Message ObjectSessionContextV2.Target
309+
Target resource specification
310+
311+
312+
| Field | Type | Label | Description |
313+
| ----- | ---- | ----- | ----------- |
314+
| container | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container where operation is allowed |
315+
| objects | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Specific objects where operation is allowed Empty list means all objects in the container |
316+
317+
174318
<a name="neo.fs.v2.session.RequestMetaHeader"></a>
175319

176320
### Message RequestMetaHeader
@@ -256,15 +400,45 @@ Session Token body
256400
| ----- | ---- | ----- | ----------- |
257401
| id | [bytes](#bytes) | | Token identifier is a valid UUIDv4 in binary form |
258402
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the session initiator |
259-
| lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) | | Lifetime of the session |
403+
| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of the session |
260404
| session_key | [bytes](#bytes) | | Public key used in session |
261405
| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) | | ObjectService session context |
262406
| container | [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) | | ContainerService session context |
263407

264408

265-
<a name="neo.fs.v2.session.SessionToken.Body.TokenLifetime"></a>
409+
<a name="neo.fs.v2.session.SessionTokenV2"></a>
410+
411+
### Message SessionTokenV2
412+
SessionTokenV2 represents NeoFS Session Token with delegation support.
413+
414+
415+
| Field | Type | Label | Description |
416+
| ----- | ---- | ----- | ----------- |
417+
| body | [SessionTokenV2.Body](#neo.fs.v2.session.SessionTokenV2.Body) | | Session token body |
418+
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the body by the issuer |
266419

267-
### Message SessionToken.Body.TokenLifetime
420+
421+
<a name="neo.fs.v2.session.SessionTokenV2.Body"></a>
422+
423+
### Message SessionTokenV2.Body
424+
Session Token body
425+
426+
427+
| Field | Type | Label | Description |
428+
| ----- | ---- | ----- | ----------- |
429+
| version | [uint32](#uint32) | | Token version |
430+
| id | [bytes](#bytes) | | Token identifier (UUIDv4 in binary form) |
431+
| issuer | [Account](#neo.fs.v2.session.Account) | | Account that issued this token (who signed it) |
432+
| subjects | [Account](#neo.fs.v2.session.Account) | repeated | Accounts authorized by this token (who can use it) |
433+
| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of this token |
434+
| object | [ObjectSessionContextV2](#neo.fs.v2.session.ObjectSessionContextV2) | | ObjectService authorization context |
435+
| container | [ContainerSessionContextV2](#neo.fs.v2.session.ContainerSessionContextV2) | | ContainerService authorization context |
436+
| delegation_chain | [DelegationInfo](#neo.fs.v2.session.DelegationInfo) | repeated | Full history of authority delegation (chain of trust) |
437+
438+
439+
<a name="neo.fs.v2.session.TokenLifetime"></a>
440+
441+
### Message TokenLifetime
268442
Lifetime parameters of the token. Field names taken from rfc7519.
269443

270444

@@ -321,6 +495,20 @@ Container request verbs
321495

322496

323497

498+
<a name="neo.fs.v2.session.ContainerSessionContextV2.Verb"></a>
499+
500+
### ContainerSessionContextV2.Verb
501+
502+
503+
| Name | Number | Description |
504+
| ---- | ------ | ----------- |
505+
| VERB_UNSPECIFIED | 0 | |
506+
| PUT | 1 | |
507+
| DELETE | 2 | |
508+
| SETEACL | 3 | |
509+
510+
511+
324512
<a name="neo.fs.v2.session.ObjectSessionContext.Verb"></a>
325513

326514
### ObjectSessionContext.Verb
@@ -338,6 +526,24 @@ Object request verbs
338526
| RANGEHASH | 7 | Refers to object.GetRangeHash RPC call |
339527

340528

529+
530+
<a name="neo.fs.v2.session.ObjectSessionContextV2.Verb"></a>
531+
532+
### ObjectSessionContextV2.Verb
533+
534+
535+
| Name | Number | Description |
536+
| ---- | ------ | ----------- |
537+
| VERB_UNSPECIFIED | 0 | |
538+
| PUT | 1 | |
539+
| GET | 2 | |
540+
| HEAD | 3 | |
541+
| SEARCH | 4 | |
542+
| DELETE | 5 | |
543+
| RANGE | 6 | |
544+
| RANGEHASH | 7 | |
545+
546+
341547
<!-- end enums -->
342548

343549

‎session/service.proto‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,14 @@ service SessionService {
2020
// session has been successfully opened;
2121
// - Common failures (SECTION_FAILURE_COMMON).
2222
rpc Create(CreateRequest) returns (CreateResponse);
23+
24+
// Create a new session token v2 with delegation and chain-of-trust support.
25+
//
26+
// Statuses:
27+
// - **OK** (0, SECTION_SUCCESS):
28+
// session token v2 has been successfully created;
29+
// - Common failures (SECTION_FAILURE_COMMON).
30+
rpc CreateV2(CreateV2Request) returns (CreateV2Response);
2331
}
2432

2533
// Information necessary for opening a session.
@@ -67,3 +75,54 @@ message CreateResponse {
6775
// transmission.
6876
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
6977
}
78+
79+
// CreateV2Request is information necessary for creating a session token v2.
80+
message CreateV2Request {
81+
// Session creation request v2 body
82+
message Body {
83+
// Issuer of the session token
84+
neo.fs.v2.session.Account issuer = 1 [json_name = "issuer"];
85+
86+
// Subjects authorized by this token
87+
repeated neo.fs.v2.session.Account subjects = 2 [json_name = "subjects"];
88+
89+
// Session expiration time
90+
int64 expiration = 3 [json_name = "expiration"];
91+
92+
// Session creation time
93+
int64 created_at = 4 [json_name = "createdAt"];
94+
}
95+
96+
// Body of create session token v2 request message
97+
Body body = 1;
98+
99+
// Carries request meta information. Header data is used only to regulate
100+
// message transport and does not affect request execution.
101+
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
102+
103+
// Carries request verification information. This header is used to
104+
// authenticate the nodes of the message route and check the correctness of
105+
// transmission.
106+
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
107+
}
108+
109+
// CreateV2Response is information about a newly created session token v2.
110+
message CreateV2Response {
111+
// Session creation response v2 body
112+
message Body {
113+
// The session token v2 with delegation and chain-of-trust support
114+
neo.fs.v2.session.SessionTokenV2 token = 1 [json_name = "token"];
115+
}
116+
117+
// Body of create session token v2 response message
118+
Body body = 1;
119+
120+
// Carries response meta information. Header data is used only to regulate
121+
// message transport and does not affect request execution.
122+
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
123+
124+
// Carries response verification information. This header is used to
125+
// authenticate the nodes of the message route and check the correctness of
126+
// transmission.
127+
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
128+
}

0 commit comments

Comments
 (0)