Skip to content

Commit 7a51333

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 7a51333

File tree

5 files changed

+430
-16
lines changed

5 files changed

+430
-16
lines changed

‎proto-docs/refs.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
- [refs/types.proto](#refs/types.proto)
77

88
- Messages
9+
- [Account](#neo.fs.v2.refs.Account)
910
- [Address](#neo.fs.v2.refs.Address)
1011
- [Checksum](#neo.fs.v2.refs.Checksum)
1112
- [ContainerID](#neo.fs.v2.refs.ContainerID)
@@ -30,6 +31,19 @@
3031
<!-- end services -->
3132

3233

34+
<a name="neo.fs.v2.refs.Account"></a>
35+
36+
### Message Account
37+
Account represents an identity in NeoFS.
38+
It can be either direct (OwnerID) or indirect (NNS domain).
39+
40+
41+
| Field | Type | Label | Description |
42+
| ----- | ---- | ----- | ----------- |
43+
| owner_id | [OwnerID](#neo.fs.v2.refs.OwnerID) | | Direct account reference via OwnerID (hash of public key). |
44+
| nns_name | [string](#string) | | Indirect account reference via NeoFS Name Service. |
45+
46+
3347
<a name="neo.fs.v2.refs.Address"></a>
3448

3549
### Message Address

‎proto-docs/session.md‎

Lines changed: 195 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,31 @@
1212
- [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body)
1313
- [CreateResponse](#neo.fs.v2.session.CreateResponse)
1414
- [CreateResponse.Body](#neo.fs.v2.session.CreateResponse.Body)
15+
- [CreateV2Request](#neo.fs.v2.session.CreateV2Request)
16+
- [CreateV2Request.Body](#neo.fs.v2.session.CreateV2Request.Body)
17+
- [CreateV2Response](#neo.fs.v2.session.CreateV2Response)
18+
- [CreateV2Response.Body](#neo.fs.v2.session.CreateV2Response.Body)
1519

1620

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

1923
- Messages
2024
- [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext)
25+
- [ContainerSessionContextV2](#neo.fs.v2.session.ContainerSessionContextV2)
26+
- [DelegationInfo](#neo.fs.v2.session.DelegationInfo)
2127
- [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext)
2228
- [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target)
29+
- [ObjectSessionContextV2](#neo.fs.v2.session.ObjectSessionContextV2)
30+
- [ObjectSessionContextV2.Target](#neo.fs.v2.session.ObjectSessionContextV2.Target)
2331
- [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader)
2432
- [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader)
2533
- [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader)
2634
- [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader)
2735
- [SessionToken](#neo.fs.v2.session.SessionToken)
2836
- [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body)
29-
- [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime)
37+
- [SessionTokenV2](#neo.fs.v2.session.SessionTokenV2)
38+
- [SessionTokenV2.Body](#neo.fs.v2.session.SessionTokenV2.Body)
39+
- [TokenLifetime](#neo.fs.v2.session.TokenLifetime)
3040
- [XHeader](#neo.fs.v2.session.XHeader)
3141

3242

@@ -52,6 +62,7 @@ section of NeoFS Technical Specification for details.
5262

5363
```
5464
rpc Create(CreateRequest) returns (CreateResponse);
65+
rpc CreateV2(CreateV2Request) returns (CreateV2Response);
5566
5667
```
5768

@@ -67,6 +78,18 @@ session has been successfully opened;
6778
| Name | Input | Output |
6879
| ---- | ----- | ------ |
6980
| Create | [CreateRequest](#neo.fs.v2.session.CreateRequest) | [CreateResponse](#neo.fs.v2.session.CreateResponse) |
81+
#### Method CreateV2
82+
83+
Create a new session token v2 with delegation and chain-of-trust support.
84+
85+
Statuses:
86+
- **OK** (0, SECTION_SUCCESS):
87+
session token v2 has been successfully created;
88+
- Common failures (SECTION_FAILURE_COMMON).
89+
90+
| Name | Input | Output |
91+
| ---- | ----- | ------ |
92+
| CreateV2 | [CreateV2Request](#neo.fs.v2.session.CreateV2Request) | [CreateV2Response](#neo.fs.v2.session.CreateV2Response) |
7093
<!-- end services -->
7194

7295

@@ -119,6 +142,57 @@ Session creation response body
119142
| id | [bytes](#bytes) | | Identifier of a newly created session |
120143
| session_key | [bytes](#bytes) | | Public key used for session |
121144

145+
146+
<a name="neo.fs.v2.session.CreateV2Request"></a>
147+
148+
### Message CreateV2Request
149+
CreateV2Request is information necessary for creating a session token v2.
150+
151+
152+
| Field | Type | Label | Description |
153+
| ----- | ---- | ----- | ----------- |
154+
| body | [CreateV2Request.Body](#neo.fs.v2.session.CreateV2Request.Body) | | Body of create session token v2 request message. |
155+
| 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. |
156+
| 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. |
157+
158+
159+
<a name="neo.fs.v2.session.CreateV2Request.Body"></a>
160+
161+
### Message CreateV2Request.Body
162+
Session creation request v2 body.
163+
164+
165+
| Field | Type | Label | Description |
166+
| ----- | ---- | ----- | ----------- |
167+
| issuer | [neo.fs.v2.refs.Account](#neo.fs.v2.refs.Account) | | Issuer of the session token. |
168+
| subjects | [neo.fs.v2.refs.Account](#neo.fs.v2.refs.Account) | repeated | Subjects authorized by this token. |
169+
| expiration | [int64](#int64) | | Session expiration time. |
170+
| created_at | [int64](#int64) | | Session creation time. |
171+
172+
173+
<a name="neo.fs.v2.session.CreateV2Response"></a>
174+
175+
### Message CreateV2Response
176+
CreateV2Response is information about a newly created session token v2.
177+
178+
179+
| Field | Type | Label | Description |
180+
| ----- | ---- | ----- | ----------- |
181+
| body | [CreateV2Response.Body](#neo.fs.v2.session.CreateV2Response.Body) | | Body of create session token v2 response message. |
182+
| 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. |
183+
| 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. |
184+
185+
186+
<a name="neo.fs.v2.session.CreateV2Response.Body"></a>
187+
188+
### Message CreateV2Response.Body
189+
Session creation response v2 body.
190+
191+
192+
| Field | Type | Label | Description |
193+
| ----- | ---- | ----- | ----------- |
194+
| token | [SessionTokenV2](#neo.fs.v2.session.SessionTokenV2) | | The session token v2 with delegation and chain-of-trust support. |
195+
122196
<!-- end messages -->
123197

124198
<!-- end enums -->
@@ -147,6 +221,35 @@ Context information for Session Tokens related to ContainerService requests.
147221
| 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. |
148222

149223

224+
<a name="neo.fs.v2.session.ContainerSessionContextV2"></a>
225+
226+
### Message ContainerSessionContextV2
227+
ContainerSessionContextV2 carries context for ContainerService requests.
228+
Extended version supporting multiple verbs.
229+
230+
231+
| Field | Type | Label | Description |
232+
| ----- | ---- | ----- | ----------- |
233+
| verbs | [ContainerSessionContextV2.Verb](#neo.fs.v2.session.ContainerSessionContextV2.Verb) | repeated | Multiple verbs this context authorizes. |
234+
| wildcard | [bool](#bool) | | If true, applies to all containers owned by the subject. |
235+
| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Particular container to which the action applies. Ignored if wildcard is true. |
236+
237+
238+
<a name="neo.fs.v2.session.DelegationInfo"></a>
239+
240+
### Message DelegationInfo
241+
DelegationInfo represents a single delegation in a chain of trust.
242+
243+
244+
| Field | Type | Label | Description |
245+
| ----- | ---- | ----- | ----------- |
246+
| issuer | [neo.fs.v2.refs.Account](#neo.fs.v2.refs.Account) | | Account that performed this delegation. |
247+
| subject | [neo.fs.v2.refs.Account](#neo.fs.v2.refs.Account) | | Account that received the delegation. |
248+
| timestamp | [int64](#int64) | | Unix timestamp when this delegation was created. |
249+
| verbs | [string](#string) | repeated | List of verbs authorized by this delegation. |
250+
| 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. |
251+
252+
150253
<a name="neo.fs.v2.session.ObjectSessionContext"></a>
151254

152255
### Message ObjectSessionContext
@@ -171,6 +274,31 @@ Carries objects involved in the object session.
171274
| 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. |
172275

173276

277+
<a name="neo.fs.v2.session.ObjectSessionContextV2"></a>
278+
279+
### Message ObjectSessionContextV2
280+
ObjectSessionContextV2 carries context for ObjectService requests.
281+
Extended version supporting multiple verbs and targets.
282+
283+
284+
| Field | Type | Label | Description |
285+
| ----- | ---- | ----- | ----------- |
286+
| verbs | [ObjectSessionContextV2.Verb](#neo.fs.v2.session.ObjectSessionContextV2.Verb) | repeated | Multiple verbs this context authorizes. |
287+
| targets | [ObjectSessionContextV2.Target](#neo.fs.v2.session.ObjectSessionContextV2.Target) | repeated | Target resource(s) this authorization applies to. |
288+
289+
290+
<a name="neo.fs.v2.session.ObjectSessionContextV2.Target"></a>
291+
292+
### Message ObjectSessionContextV2.Target
293+
Target resource specification.
294+
295+
296+
| Field | Type | Label | Description |
297+
| ----- | ---- | ----- | ----------- |
298+
| container | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container where operation is allowed. |
299+
| 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. |
300+
301+
174302
<a name="neo.fs.v2.session.RequestMetaHeader"></a>
175303

176304
### Message RequestMetaHeader
@@ -256,23 +384,53 @@ Session Token body
256384
| ----- | ---- | ----- | ----------- |
257385
| id | [bytes](#bytes) | | Token identifier is a valid UUIDv4 in binary form |
258386
| 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 |
387+
| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of the session |
260388
| session_key | [bytes](#bytes) | | Public key used in session |
261389
| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) | | ObjectService session context |
262390
| container | [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) | | ContainerService session context |
263391

264392

265-
<a name="neo.fs.v2.session.SessionToken.Body.TokenLifetime"></a>
393+
<a name="neo.fs.v2.session.SessionTokenV2"></a>
394+
395+
### Message SessionTokenV2
396+
SessionTokenV2 represents NeoFS Session Token with delegation support.
397+
398+
399+
| Field | Type | Label | Description |
400+
| ----- | ---- | ----- | ----------- |
401+
| body | [SessionTokenV2.Body](#neo.fs.v2.session.SessionTokenV2.Body) | | Session token body. |
402+
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the body by the issuer. |
403+
404+
405+
<a name="neo.fs.v2.session.SessionTokenV2.Body"></a>
406+
407+
### Message SessionTokenV2.Body
408+
Session Token body.
409+
410+
411+
| Field | Type | Label | Description |
412+
| ----- | ---- | ----- | ----------- |
413+
| version | [uint32](#uint32) | | Token version. |
414+
| id | [bytes](#bytes) | | Token identifier (UUIDv4 in binary form). |
415+
| issuer | [neo.fs.v2.refs.Account](#neo.fs.v2.refs.Account) | | Account that issued this token (who signed it). |
416+
| subjects | [neo.fs.v2.refs.Account](#neo.fs.v2.refs.Account) | repeated | Accounts authorized by this token (who can use it). |
417+
| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of this token. |
418+
| object | [ObjectSessionContextV2](#neo.fs.v2.session.ObjectSessionContextV2) | | ObjectService authorization context. |
419+
| container | [ContainerSessionContextV2](#neo.fs.v2.session.ContainerSessionContextV2) | | ContainerService authorization context. |
420+
| delegation_chain | [DelegationInfo](#neo.fs.v2.session.DelegationInfo) | repeated | Full history of authority delegation (chain of trust). |
421+
266422

267-
### Message SessionToken.Body.TokenLifetime
423+
<a name="neo.fs.v2.session.TokenLifetime"></a>
424+
425+
### Message TokenLifetime
268426
Lifetime parameters of the token. Field names taken from rfc7519.
269427

270428

271429
| Field | Type | Label | Description |
272430
| ----- | ---- | ----- | ----------- |
273431
| exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. |
274432
| nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. |
275-
| iat | [uint64](#uint64) | | Issued at Epoch |
433+
| iat | [uint64](#uint64) | | Issued at epoch. |
276434

277435

278436
<a name="neo.fs.v2.session.XHeader"></a>
@@ -321,6 +479,20 @@ Container request verbs
321479

322480

323481

482+
<a name="neo.fs.v2.session.ContainerSessionContextV2.Verb"></a>
483+
484+
### ContainerSessionContextV2.Verb
485+
Container request verbs.
486+
487+
| Name | Number | Description |
488+
| ---- | ------ | ----------- |
489+
| VERB_UNSPECIFIED | 0 | Unknown verb. |
490+
| PUT | 1 | Refers to container.Put RPC call. |
491+
| DELETE | 2 | Refers to container.Delete RPC call. |
492+
| SETEACL | 3 | Refers to container.SetExtendedACL RPC call. |
493+
494+
495+
324496
<a name="neo.fs.v2.session.ObjectSessionContext.Verb"></a>
325497

326498
### ObjectSessionContext.Verb
@@ -338,6 +510,24 @@ Object request verbs
338510
| RANGEHASH | 7 | Refers to object.GetRangeHash RPC call |
339511

340512

513+
514+
<a name="neo.fs.v2.session.ObjectSessionContextV2.Verb"></a>
515+
516+
### ObjectSessionContextV2.Verb
517+
Object request verbs.
518+
519+
| Name | Number | Description |
520+
| ---- | ------ | ----------- |
521+
| VERB_UNSPECIFIED | 0 | Unknown verb. |
522+
| PUT | 1 | Refers to object.Put RPC call. |
523+
| GET | 2 | Refers to object.Get RPC call. |
524+
| HEAD | 3 | Refers to object.Head RPC call. |
525+
| SEARCH | 4 | Refers to object.Search RPC call. |
526+
| DELETE | 5 | Refers to object.Delete RPC call. |
527+
| RANGE | 6 | Refers to object.GetRange RPC call. |
528+
| RANGEHASH | 7 | Refers to object.GetRangeHash RPC call. |
529+
530+
341531
<!-- end enums -->
342532

343533

‎refs/types.proto‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,19 @@ message OwnerID {
7979
bytes value = 1 [json_name = "value"];
8080
}
8181

82+
// Account represents an identity in NeoFS.
83+
// It can be either direct (OwnerID) or indirect (NNS domain).
84+
message Account {
85+
// Account identifier.
86+
oneof identifier {
87+
// Direct account reference via OwnerID (hash of public key).
88+
OwnerID owner_id = 1 [json_name = "ownerID"];
89+
90+
// Indirect account reference via NeoFS Name Service.
91+
string nns_name = 2 [json_name = "nnsName"];
92+
}
93+
}
94+
8295
// NeoFS subnetwork identifier.
8396
//
8497
// String representation of a value is base-10 integer.

0 commit comments

Comments
 (0)