session

package
v1.0.0-rc.19 Latest Latest
Warning

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

 Go to latest Published: May 21, 2026 License: Apache-2.0 Imports: 15 Imported by: 38

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 protosession.SessionToken message. See Container.FromProtoMessage / Container.ProtoMessage 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
}

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

func (x *Container) AttachSignature(sig neofscrypto.Signature)

AttachSignature attaches given signature to the token. Use SignedData method for calculation. If signature instance itself is not needed, use Sign method.

func (*Container) AuthUser 

func (x *Container) AuthUser() (user.ID, error)

AuthUser returns user ID derived from the public key bound to the session. Zero session fails the check.

See also SetAuthKey and AssertAuthKey.

func (Container) CopyTo 

func (x Container) CopyTo(dst *Container)

CopyTo writes deep copy of the Container to dst.

func (Container) Exp 

func (x Container) Exp() uint64

Exp returns "exp" (expiration time) claim.

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

func (x *Container) FromProtoMessage(m *protosession.SessionToken) error

FromProtoMessage validates m according to the NeoFS API protocol and restores x from it.

See also Container.ProtoMessage.

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

func (x Container) Iat() uint64

Iat returns "iat" (issued at) claim.

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

func (x Container) Nbf() uint64

Nbf returns "nbf" (not before) claim.

func (Container) ProtoMessage 

func (x Container) ProtoMessage() *protosession.SessionToken

ProtoMessage converts x into message to transmit using the NeoFS API protocol.

See also Container.FromProtoMessage.

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

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

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

func (x Container) Signature() (neofscrypto.Signature, bool)

Signature returns token signature. If the signature is missing, false is returned. Use SignedData method for verification. If signature instance itself is not needed, use VerifySignature method.

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

func (x Container) ValidAt(epoch uint64) bool

ValidAt checks whether the token is still valid at the given epoch according to its lifetime claims.

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.

type ContainerVerb 

type ContainerVerb int32

ContainerVerb enumerates container operations. 

const (
	VerbContainerPut             ContainerVerb // Put rpc
	VerbContainerDelete                        // Delete rpc
	VerbContainerSetEACL                       // SetExtendedACL rpc
	VerbContainerSetAttribute                  // SetAttribute rpc
	VerbContainerRemoveAttribute               // RemoveAttribute 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 protosession.SessionToken message. See Object.FromProtoMessage / Object.ProtoMessage 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 (
	"github.com/nspcc-dev/neofs-sdk-go/session"
)

func main() {
	// On the client side.

	var tok session.Object

	msg := tok.ProtoMessage()
	// *send message*

	// On the server side.

	_ = tok.FromProtoMessage(msg)
}

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

func (x *Object) AttachSignature(sig neofscrypto.Signature)

AttachSignature attaches given signature to the token. Use SignedData method for calculation. If signature instance itself is not needed, use Sign method.

func (*Object) AuthUser 

func (x *Object) AuthUser() (user.ID, error)

AuthUser returns user ID derived from the public key bound to the session. Zero session fails the check.

See also SetAuthKey and AssertAuthKey.

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

func (x Object) Exp() uint64

Exp returns "exp" (expiration time) claim.

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

func (x *Object) FromProtoMessage(m *protosession.SessionToken) error

FromProtoMessage validates m according to the NeoFS API protocol and restores x from it.

See also Object.ProtoMessage.

func (*Object) FromProtoMessageWithVersion 

func (x *Object) FromProtoMessageWithVersion(m *protosession.SessionToken, version *version.Version) error

FromProtoMessageWithVersion validates m according to the NeoFS API protocol and restores x from it, taking into account the object version for backward compatibility.

See also Object.ProtoMessage.

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

func (x Object) Iat() uint64

Iat returns "iat" (issued at) claim.

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

func (x Object) Nbf() uint64

Nbf returns "nbf" (not before) claim.

func (Object) ProtoMessage 

func (x Object) ProtoMessage() *protosession.SessionToken

ProtoMessage converts x into message to transmit using the NeoFS API protocol.

See also Object.FromProtoMessage.

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

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

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

func (x Object) Signature() (neofscrypto.Signature, bool)

Signature returns token signature. If the signature is missing, false is returned. Use SignedData method for verification. If signature instance itself is not needed, use VerifySignature method.

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

func (x Object) ValidAt(epoch uint64) bool

ValidAt checks whether the token is still valid at the given epoch according to its lifetime claims.

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.

type ObjectVerb 

type ObjectVerb int32

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            // Deprecated: should not be used.
)

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.
Package session collects functionality of the NeoFS session token v2.
 Package session collects functionality of the NeoFS session token v2.

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.