session

package
v1.0.0-rc.12 Latest Latest
Warning

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

 Go to latest Published: May 29, 2024 License: Apache-2.0 Imports: 10 Imported by: 35

Documentation

Overview

Package session collects functionality of the NeoFS sessions.

Sessions are used in NeoFS 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 NeoFS 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).

The trusted member can perform operations on behalf of the trustee.

Index

Examples

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 NeoFS 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/nspcc-dev/neofs-api-go/v2/session.Token message. See ReadFromV2 / WriteToV2 methods.

Instances can be created using built-in var declaration.

Example

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). 

package main

import (
	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"

	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
	"github.com/nspcc-dev/neofs-sdk-go/session"
	"github.com/nspcc-dev/neofs-sdk-go/user"
)

func main() {
	// import neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
	// import "github.com/nspcc-dev/neofs-sdk-go/user"
	// import cid "github.com/nspcc-dev/neofs-sdk-go/container/id"

	// you private key/signer, to prove you are you
	var principalSigner user.Signer
	// trusted party, who can do action on behalf of you. Usually the key maybe taken from Client.SessionCreate.
	var trustedPubKey neofscrypto.PublicKey
	var cnr cid.ID

	var tok session.Object
	tok.ForVerb(session.VerbObjectPut)
	tok.SetAuthKey(trustedPubKey)
	tok.BindContainer(cnr)
	// ...

	_ = tok.Sign(principalSigner)

	// transfer the token to a trusted party
}

Output:

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 neofscrypto.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) CopyTo 

func (x Container) CopyTo(dst *Container)

CopyTo writes deep copy of the Container to dst.

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) IssuerPublicKeyBytes 

func (x *Container) IssuerPublicKeyBytes() []byte

IssuerPublicKeyBytes returns binary-encoded public key of the session issuer.

IssuerPublicKeyBytes MUST NOT be called before ReadFromV2 or Sign methods.

func (Container) Marshal 

func (x Container) Marshal() []byte

Marshal encodes Container into a binary format of the NeoFS 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 NeoFS 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 NeoFS API V2 protocol.

See also WriteToV2.

func (*Container) SetAuthKey 

func (x *Container) SetAuthKey(key neofscrypto.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 NeoFS 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 NeoFS 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) SetIssuer 

func (x *Container) SetIssuer(id user.ID)

SetIssuer allows to set issuer before Sign call. Using this method is not required when Sign is used (issuer will be derived from the signer automatically). When using it please ensure that the token is signed with the same signer as the issuer passed here.

func (*Container) SetNbf 

func (x *Container) SetNbf(nbf uint64)

SetNbf sets "nbf" (not before) claim which identifies the time (in NeoFS 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) SetSignature 

func (x *Container) SetSignature(signer neofscrypto.Signer) error

SetSignature allows to sign Container like Container.Sign but without issuer setting.

func (*Container) Sign 

func (x *Container) Sign(signer user.Signer) error

Sign calculates and writes signature of the Container data along with issuer ID using signer. 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 Container.VerifySignature, Container.SignedData.

func (*Container) SignedData 

func (x *Container) SignedData() []byte

SignedData returns actual payload to sign.

Using this method require to set issuer via Container.SetIssuer before SignedData call.

See also Container.Sign, Container.UnmarshalSignedData.

func (*Container) Unmarshal 

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

Unmarshal decodes NeoFS 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 NeoFS API protocol JSON format into the Container (Protocol Buffers JSON). Returns an error describing a format violation.

See also MarshalJSON.

func (*Container) UnmarshalSignedData 

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

UnmarshalSignedData is a reverse op to Container.SignedData.

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 NeoFS 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/nspcc-dev/neofs-api-go/v2/session.Token message. See ReadFromV2 / WriteToV2 methods.

Instances can be created using built-in var declaration.

Example (Marshalling)

Instances can be also used to process NeoFS API V2 protocol messages with [https://github.com/nspcc-dev/neofs-api] package. 

package main

import (
	apiGoSession "github.com/nspcc-dev/neofs-api-go/v2/session"
	"github.com/nspcc-dev/neofs-sdk-go/session"
)

func main() {
	// import apiGoSession "github.com/nspcc-dev/neofs-api-go/v2/session"

	// On the client side.

	var tok session.Object
	var msg apiGoSession.Token

	tok.WriteToV2(&msg)
	// *send message*

	// On the server side.

	_ = tok.ReadFromV2(msg)
}

Output:

func (Object) AssertAuthKey 

func (x Object) AssertAuthKey(key neofscrypto.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 NeoFS 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) CopyTo 

func (x Object) CopyTo(dst *Object)

CopyTo writes deep copy of the Container to dst.

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) IssuerPublicKeyBytes 

func (x *Object) IssuerPublicKeyBytes() []byte

IssuerPublicKeyBytes returns binary-encoded public key of the session issuer.

IssuerPublicKeyBytes MUST NOT be called before ReadFromV2 or Sign methods.

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 NeoFS 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 NeoFS 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 NeoFS API V2 protocol.

See also WriteToV2.

func (*Object) SetAuthKey 

func (x *Object) SetAuthKey(key neofscrypto.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 NeoFS 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 NeoFS 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) SetIssuer 

func (x *Object) SetIssuer(id user.ID)

SetIssuer allows to set issuer before Sign call. Using this method is not required when Sign is used (issuer will be derived from the signer automatically). When using it please ensure that the token is signed with the same signer as the issuer passed here.

func (*Object) SetNbf 

func (x *Object) SetNbf(nbf uint64)

SetNbf sets "nbf" (not before) claim which identifies the time (in NeoFS 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) SetSignature 

func (x *Object) SetSignature(signer neofscrypto.Signer) error

SetSignature allows to sign Object like Object.Sign but without issuer setting.

func (*Object) Sign 

func (x *Object) Sign(signer user.Signer) error

Sign calculates and writes signature of the Object data along with issuer ID using signer. 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 Object.VerifySignature, Object.SignedData.

func (*Object) SignedData 

func (x *Object) SignedData() []byte

SignedData returns actual payload to sign.

See also Object.Sign, Object.UnmarshalSignedData.

func (*Object) Unmarshal 

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

Unmarshal decodes NeoFS 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 NeoFS API protocol JSON format into the Object (Protocol Buffers JSON). Returns an error describing a format violation.

See also MarshalJSON.

func (*Object) UnmarshalSignedData 

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

UnmarshalSignedData is a reverse op to Object.SignedData.

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.