Documentation ¶
Overview ¶
Package session collects functionality of the FrostFS sessions.
Sessions are used in FrostFS as a mechanism for transferring the power of attorney of actions to another network member.
Session tokens represent proof of trust. Each session has a limited lifetime and scope related to some FrostFS service: Object, Container, etc.
Both parties agree on a secret (private session key), the possession of which will be authenticated by a trusted person. The principal confirms his trust by signing the public part of the secret (public session key).
var tok Container tok.ForVerb(VerbContainerDelete) tok.SetAuthKey(trustedKey) // ... err := tok.Sign(principalKey) // ... // transfer the token to a trusted party
The trusted member can perform operations on behalf of the trustee.
Instances can be also used to process FrostFS API V2 protocol messages (see neo.fs.v2.accounting package in https://git.frostfs.info/TrueCloudLab/frostfs-api).
On client side:
import "git.frostfs.info/TrueCloudLab/frostfs-sdk-go/api/session" var msg session.Token tok.WriteToV2(&msg) // send msg
On server side:
// recv msg var tok session.Container tok.ReadFromV2(msg) // process cnr
Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible.
Index ¶
- func IssuedBy(cnr Container, id user.ID) bool
- type Container
- func (x Container) AppliedTo(cnr cid.ID) bool
- func (x *Container) ApplyOnlyTo(cnr cid.ID)
- func (x Container) AssertAuthKey(key frostfscrypto.PublicKey) bool
- func (x Container) AssertVerb(verb ContainerVerb) bool
- func (x *Container) ForVerb(verb ContainerVerb)
- func (x Container) ID() uuid.UUID
- func (x Container) InvalidAt(epoch uint64) bool
- func (x Container) Issuer() user.ID
- func (x Container) Marshal() []byte
- func (x Container) MarshalJSON() ([]byte, error)
- func (x *Container) ReadFromV2(m session.Token) error
- func (x *Container) SetAuthKey(key frostfscrypto.PublicKey)
- func (x *Container) SetExp(exp uint64)
- func (x *Container) SetID(id uuid.UUID)
- func (x *Container) SetIat(iat uint64)
- func (x *Container) SetNbf(nbf uint64)
- func (x *Container) Sign(key ecdsa.PrivateKey) error
- func (x *Container) Unmarshal(data []byte) error
- func (x *Container) UnmarshalJSON(data []byte) error
- func (x Container) VerifySessionDataSignature(data, signature []byte) bool
- func (x Container) VerifySignature() bool
- func (x Container) WriteToV2(m *session.Token)
- type ContainerVerb
- type Object
- func (x Object) AssertAuthKey(key frostfscrypto.PublicKey) bool
- func (x Object) AssertContainer(cnr cid.ID) bool
- func (x Object) AssertObject(obj oid.ID) bool
- func (x Object) AssertVerb(verbs ...ObjectVerb) bool
- func (x *Object) BindContainer(cnr cid.ID)
- func (x Object) ExpiredAt(epoch uint64) bool
- func (x *Object) ForVerb(verb ObjectVerb)
- func (x Object) ID() uuid.UUID
- func (x Object) InvalidAt(epoch uint64) bool
- func (x Object) Issuer() user.ID
- func (x *Object) LimitByObjects(objs ...oid.ID)
- func (x Object) Marshal() []byte
- func (x Object) MarshalJSON() ([]byte, error)
- func (x *Object) ReadFromV2(m session.Token) error
- func (x *Object) SetAuthKey(key frostfscrypto.PublicKey)
- func (x *Object) SetExp(exp uint64)
- func (x *Object) SetID(id uuid.UUID)
- func (x *Object) SetIat(iat uint64)
- func (x *Object) SetNbf(nbf uint64)
- func (x *Object) Sign(key ecdsa.PrivateKey) error
- func (x *Object) Unmarshal(data []byte) error
- func (x *Object) UnmarshalJSON(data []byte) error
- func (x Object) VerifySignature() bool
- func (x Object) WriteToV2(m *session.Token)
- type ObjectVerb
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container represents token of the FrostFS Container session. A session is opened between any two sides of the system, and implements a mechanism for transferring the power of attorney of actions to another network member. The session has a limited validity period, and applies to a strictly defined set of operations. See methods for details.
Container is mutually compatible with git.frostfs.info/TrueCloudLab/frostfs-sdk-go/api/session.Token message. See ReadFromV2 / WriteToV2 methods.
Instances can be created using built-in var declaration.
func (Container) AppliedTo ¶
AppliedTo checks if the session is propagated to the given container.
Zero Container is applied to all author's containers.
See also ApplyOnlyTo.
func (*Container) ApplyOnlyTo ¶
ApplyOnlyTo limits session scope to a given author container.
See also AppliedTo.
func (Container) AssertAuthKey ¶
func (x Container) AssertAuthKey(key frostfscrypto.PublicKey) bool
AssertAuthKey asserts public key bound to the session.
Zero session fails the check.
See also SetAuthKey.
func (Container) AssertVerb ¶
func (x Container) AssertVerb(verb ContainerVerb) bool
AssertVerb checks if Container relates to the given container operation.
Zero Container relates to zero (unspecified) verb.
See also ForVerb.
func (*Container) ForVerb ¶
func (x *Container) ForVerb(verb ContainerVerb)
ForVerb specifies the container operation of the session scope. Each Container is related to the single operation.
See also AssertVerb.
func (Container) ID ¶
ID returns a unique identifier for the session.
Zero session has empty UUID (all zeros, see uuid.Nil) which is legitimate but most likely not suitable.
See also SetID.
func (Container) InvalidAt ¶
InvalidAt asserts "exp", "nbf" and "iat" claims.
Zero session is invalid in any epoch.
See also SetExp, SetNbf, SetIat.
func (Container) Issuer ¶
Issuer returns user ID of the session issuer.
Makes sense only for signed session instances. For unsigned instances, Issuer returns zero user.ID.
See also Sign.
func (Container) Marshal ¶
Marshal encodes Container into a binary format of the FrostFS API protocol (Protocol Buffers with direct field order).
See also Unmarshal.
func (Container) MarshalJSON ¶
MarshalJSON encodes Container into a JSON format of the FrostFS API protocol (Protocol Buffers JSON).
See also UnmarshalJSON.
func (*Container) ReadFromV2 ¶
ReadFromV2 reads Container from the session.Token message. Checks if the message conforms to FrostFS API V2 protocol.
See also WriteToV2.
func (*Container) SetAuthKey ¶
func (x *Container) SetAuthKey(key frostfscrypto.PublicKey)
SetAuthKey public key corresponding to the private key bound to the session.
See also AssertAuthKey.
func (*Container) SetExp ¶
func (x *Container) SetExp(exp uint64)
SetExp sets "exp" (expiration time) claim which identifies the expiration time (in FrostFS epochs) after which the session MUST NOT be accepted for processing. The processing of the "exp" claim requires that the current epoch MUST be before or equal to the expiration epoch listed in the "exp" claim.
Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4.
See also ExpiredAt.
func (*Container) SetID ¶
SetID sets a unique identifier for the session. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different session.
ID format MUST be UUID version 4 (random). uuid.New can be used to generate a new ID. See https://datatracker.ietf.org/doc/html/rfc4122 and github.com/google/uuid package docs for details.
See also ID.
func (*Container) SetIat ¶
func (x *Container) SetIat(iat uint64)
SetIat sets "iat" (issued at) claim which identifies the time (in FrostFS epochs) at which the session was issued. This claim can be used to determine the age of the session.
Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6.
See also InvalidAt.
func (*Container) SetNbf ¶
func (x *Container) SetNbf(nbf uint64)
SetNbf sets "nbf" (not before) claim which identifies the time (in FrostFS epochs) before which the session MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim.
Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5.
See also InvalidAt.
func (*Container) Sign ¶
func (x *Container) Sign(key ecdsa.PrivateKey) error
Sign calculates and writes signature of the Container data. Returns signature calculation errors.
Zero Container is unsigned.
Note that any Container mutation is likely to break the signature, so it is expected to be calculated as a final stage of Container formation.
See also VerifySignature.
func (*Container) Unmarshal ¶
Unmarshal decodes FrostFS API protocol binary format into the Container (Protocol Buffers with direct field order). Returns an error describing a format violation.
See also Marshal.
func (*Container) UnmarshalJSON ¶
UnmarshalJSON decodes FrostFS API protocol JSON format into the Container (Protocol Buffers JSON). Returns an error describing a format violation.
See also MarshalJSON.
func (Container) VerifySessionDataSignature ¶
VerifySessionDataSignature verifies signature of the session data. In practice, the method is used to authenticate an operation with session data.
func (Container) VerifySignature ¶
VerifySignature checks if Container signature is presented and valid.
Zero Container fails the check.
See also Sign.
type ContainerVerb ¶
type ContainerVerb int8
ContainerVerb enumerates container operations.
const ( VerbContainerPut ContainerVerb // Put rpc VerbContainerDelete // Delete rpc VerbContainerSetEACL // SetExtendedACL rpc )
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
Object represents token of the FrostFS Object session. A session is opened between any two sides of the system, and implements a mechanism for transferring the power of attorney of actions to another network member. The session has a limited validity period, and applies to a strictly defined set of operations. See methods for details.
Object is mutually compatible with git.frostfs.info/TrueCloudLab/frostfs-sdk-go/api/session.Token message. See ReadFromV2 / WriteToV2 methods.
Instances can be created using built-in var declaration.
func (Object) AssertAuthKey ¶
func (x Object) AssertAuthKey(key frostfscrypto.PublicKey) bool
AssertAuthKey asserts public key bound to the session.
Zero session fails the check.
See also SetAuthKey.
func (Object) AssertContainer ¶
AssertContainer checks if Object session bound to a given container.
Zero Object isn't bound to any container which is incorrect according to FrostFS API protocol.
See also BindContainer.
func (Object) AssertObject ¶
AssertObject checks if Object session is applied to a given object.
Zero Object is applied to all objects in the container.
See also LimitByObjects.
func (Object) AssertVerb ¶
func (x Object) AssertVerb(verbs ...ObjectVerb) bool
AssertVerb checks if Object relates to one of the given object operations.
Zero Object relates to zero (unspecified) verb.
See also ForVerb.
func (*Object) BindContainer ¶
BindContainer binds the Object session to a given container. Each session MUST be bound to exactly one container.
See also AssertContainer.
func (Object) ExpiredAt ¶
ExpiredAt asserts "exp" claim.
Zero Object is expired in any epoch.
See also SetExp.
func (*Object) ForVerb ¶
func (x *Object) ForVerb(verb ObjectVerb)
ForVerb specifies the object operation of the session scope. Each Object is related to the single operation.
See also AssertVerb.
func (Object) ID ¶
ID returns a unique identifier for the session.
Zero session has empty UUID (all zeros, see uuid.Nil) which is legitimate but most likely not suitable.
See also SetID.
func (Object) InvalidAt ¶
InvalidAt asserts "exp", "nbf" and "iat" claims.
Zero session is invalid in any epoch.
See also SetExp, SetNbf, SetIat.
func (Object) Issuer ¶
Issuer returns user ID of the session issuer.
Makes sense only for signed session instances. For unsigned instances, Issuer returns zero user.ID.
See also Sign.
func (*Object) LimitByObjects ¶
LimitByObjects limits session scope to the given objects from the container to which Object session is bound.
Argument MUST NOT be mutated, make a copy first.
See also AssertObject.
func (Object) Marshal ¶
Marshal encodes Object into a binary format of the FrostFS API protocol (Protocol Buffers with direct field order).
See also Unmarshal.
func (Object) MarshalJSON ¶
MarshalJSON encodes Object into a JSON format of the FrostFS API protocol (Protocol Buffers JSON).
See also UnmarshalJSON.
func (*Object) ReadFromV2 ¶
ReadFromV2 reads Object from the session.Token message. Checks if the message conforms to FrostFS API V2 protocol.
See also WriteToV2.
func (*Object) SetAuthKey ¶
func (x *Object) SetAuthKey(key frostfscrypto.PublicKey)
SetAuthKey public key corresponding to the private key bound to the session.
See also AssertAuthKey.
func (*Object) SetExp ¶
func (x *Object) SetExp(exp uint64)
SetExp sets "exp" (expiration time) claim which identifies the expiration time (in FrostFS epochs) after which the session MUST NOT be accepted for processing. The processing of the "exp" claim requires that the current epoch MUST be before or equal to the expiration epoch listed in the "exp" claim.
Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4.
See also ExpiredAt.
func (*Object) SetID ¶
SetID sets a unique identifier for the session. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different session.
ID format MUST be UUID version 4 (random). uuid.New can be used to generate a new ID. See https://datatracker.ietf.org/doc/html/rfc4122 and github.com/google/uuid package docs for details.
See also ID.
func (*Object) SetIat ¶
func (x *Object) SetIat(iat uint64)
SetIat sets "iat" (issued at) claim which identifies the time (in FrostFS epochs) at which the session was issued. This claim can be used to determine the age of the session.
Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6.
See also InvalidAt.
func (*Object) SetNbf ¶
func (x *Object) SetNbf(nbf uint64)
SetNbf sets "nbf" (not before) claim which identifies the time (in FrostFS epochs) before which the session MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim.
Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5.
See also InvalidAt.
func (*Object) Sign ¶
func (x *Object) Sign(key ecdsa.PrivateKey) error
Sign calculates and writes signature of the Object data. Returns signature calculation errors.
Zero Object is unsigned.
Note that any Object mutation is likely to break the signature, so it is expected to be calculated as a final stage of Object formation.
See also VerifySignature.
func (*Object) Unmarshal ¶
Unmarshal decodes FrostFS API protocol binary format into the Object (Protocol Buffers with direct field order). Returns an error describing a format violation.
See also Marshal.
func (*Object) UnmarshalJSON ¶
UnmarshalJSON decodes FrostFS API protocol JSON format into the Object (Protocol Buffers JSON). Returns an error describing a format violation.
See also MarshalJSON.
func (Object) VerifySignature ¶
VerifySignature checks if Object signature is presented and valid.
Zero Object fails the check.
See also Sign.
type ObjectVerb ¶
type ObjectVerb int8
ObjectVerb enumerates object operations.
const ( VerbObjectPut ObjectVerb // Put rpc VerbObjectGet // Get rpc VerbObjectHead // Head rpc VerbObjectSearch // Search rpc VerbObjectDelete // Delete rpc VerbObjectRange // GetRange rpc VerbObjectRangeHash // GetRangeHash rpc VerbObjectPatch // Patch rpc )