session

package
v0.0.0-...-5e759bf Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2023 License: Apache-2.0 Imports: 12 Imported by: 15

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://github.com/TrueCloudLab/frostfs-api).

On client side: 

import "github.com/TrueCloudLab/frostfs-api-go/v2/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

Constants

This section is empty.

Variables

This section is empty.

Functions

func IssuedBy 

func IssuedBy(cnr Container, id user.ID) bool

IssuedBy checks if Container session is issued by the given user.

See also Container.Issuer.

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 github.com/TrueCloudLab/frostfs-api-go/v2/session.Token message. See ReadFromV2 / WriteToV2 methods.

Instances can be created using built-in var declaration.

func (Container) AppliedTo 

func (x Container) AppliedTo(cnr cid.ID) bool

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 

func (x *Container) ApplyOnlyTo(cnr cid.ID)

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 

func (x Container) ID() uuid.UUID

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 

func (x Container) InvalidAt(epoch uint64) bool

InvalidAt asserts "exp", "nbf" and "iat" claims.

Zero session is invalid in any epoch.

See also SetExp, SetNbf, SetIat.

func (Container) Issuer 

func (x Container) Issuer() user.ID

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 

func (x Container) Marshal() []byte

Marshal encodes Container into a binary format of the FrostFS API protocol (Protocol Buffers with direct field order).

See also Unmarshal.

func (Container) MarshalJSON 

func (x Container) MarshalJSON() ([]byte, error)

MarshalJSON encodes Container into a JSON format of the FrostFS API protocol (Protocol Buffers JSON).

See also UnmarshalJSON.

func (*Container) ReadFromV2 

func (x *Container) ReadFromV2(m session.Token) error

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 

func (x *Container) SetID(id uuid.UUID)

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 

func (x *Container) Unmarshal(data []byte) error

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 

func (x *Container) UnmarshalJSON(data []byte) error

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 

func (x Container) VerifySessionDataSignature(data, signature []byte) bool

VerifySessionDataSignature verifies signature of the session data. In practice, the method is used to authenticate an operation with session data.

func (Container) VerifySignature 

func (x Container) VerifySignature() bool

VerifySignature checks if Container signature is presented and valid.

Zero Container fails the check.

See also Sign.

func (Container) WriteToV2 

func (x Container) WriteToV2(m *session.Token)

WriteToV2 writes Container to the session.Token message. The message must not be nil.

See also ReadFromV2.

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 github.com/TrueCloudLab/frostfs-api-go/v2/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 

func (x Object) AssertContainer(cnr cid.ID) bool

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 

func (x Object) AssertObject(obj oid.ID) bool

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 

func (x *Object) BindContainer(cnr cid.ID)

BindContainer binds the Object session to a given container. Each session MUST be bound to exactly one container.

See also AssertContainer.

func (Object) ExpiredAt 

func (x Object) ExpiredAt(epoch uint64) bool

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 

func (x Object) ID() uuid.UUID

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 

func (x Object) InvalidAt(epoch uint64) bool

InvalidAt asserts "exp", "nbf" and "iat" claims.

Zero session is invalid in any epoch.

See also SetExp, SetNbf, SetIat.

func (Object) Issuer 

func (x Object) Issuer() user.ID

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 

func (x *Object) LimitByObjects(objs ...oid.ID)

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 

func (x Object) Marshal() []byte

Marshal encodes Object into a binary format of the FrostFS API protocol (Protocol Buffers with direct field order).

See also Unmarshal.

func (Object) MarshalJSON 

func (x Object) MarshalJSON() ([]byte, error)

MarshalJSON encodes Object into a JSON format of the FrostFS API protocol (Protocol Buffers JSON).

See also UnmarshalJSON.

func (*Object) ReadFromV2 

func (x *Object) ReadFromV2(m session.Token) error

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 

func (x *Object) SetID(id uuid.UUID)

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 

func (x *Object) Unmarshal(data []byte) error

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 

func (x *Object) UnmarshalJSON(data []byte) error

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 

func (x Object) VerifySignature() bool

VerifySignature checks if Object signature is presented and valid.

Zero Object fails the check.

See also Sign.

func (Object) WriteToV2 

func (x Object) WriteToV2(m *session.Token)

WriteToV2 writes Object to the session.Token message. The message must not be nil.

See also ReadFromV2.

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
)

Source Files

View all Source files

Directories

Path Synopsis
Package sessiontest provides functions for convenient testing of session package API.
 Package sessiontest provides functions for convenient testing of session package API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.