bearer

package
v1.0.0-rc.11 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2023 License: Apache-2.0 Imports: 9 Imported by: 17

Documentation

Overview

Package bearer provides bearer token definition.

Bearer token is attached to the object service requests, and it overwrites extended ACL of the container. Mainly it is used to provide access of private data for specific user. Therefore, it must be signed by owner of the container.

Example

Define bearer token by setting correct lifetime, extended ACL and owner ID of the user that will attach token to its requests. 

package main

import (
	"github.com/nspcc-dev/neofs-sdk-go/bearer"

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

func main() {
	// import "github.com/nspcc-dev/neofs-sdk-go/eacl"
	// import "github.com/nspcc-dev/neofs-sdk-go/user"

	var bearerToken bearer.Token
	var ownerID user.ID
	var eaclTable eacl.Table

	bearerToken.SetExp(500)
	bearerToken.SetIat(10)
	bearerToken.SetNbf(10)
	bearerToken.SetEACLTable(eaclTable)
	bearerToken.ForUser(ownerID)

	// Bearer token must be signed by owner of the container.
	// import neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"

	var signer neofscrypto.Signer
	// signer initialization, bearerToken initialization, other steps ...

	_ = bearerToken.Sign(signer)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Token 

type Token struct {
	// contains filtered or unexported fields
}

Token represents bearer token for object service operations.

Token is mutually compatible with github.com/nspcc-dev/neofs-api-go/v2/acl.BearerToken message. See ReadFromV2 / WriteToV2 methods.

Instances can be created using built-in var declaration.

Example (AttachToRequest)

Provide signed token in JSON or binary format to the request sender. Request sender can attach this bearer token to the object service requests. 

package main

import (
	"context"

	"github.com/nspcc-dev/neofs-sdk-go/bearer"
	"github.com/nspcc-dev/neofs-sdk-go/client"

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

	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
	"github.com/nspcc-dev/neofs-sdk-go/user"
)

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

	var bearerToken bearer.Token
	var sdkClient *client.Client
	var signer user.Signer

	// init bearerToken, sdkClient, signer, other steps ...

	var headParams client.PrmObjectHead
	headParams.WithBearerToken(bearerToken)
	// ...

	response, err := sdkClient.ObjectHead(context.Background(), cid.ID{}, oid.ID{}, signer, headParams)

	_ = response
	_ = err
}

Output:

func (Token) AssertContainer 

func (b Token) AssertContainer(cnr cid.ID) bool

AssertContainer checks if the token is valid within the given container.

Note: cnr is assumed to refer to the issuer's container, otherwise the check is meaningless.

Zero Token is valid in any container.

See also SetEACLTable.

func (Token) AssertUser 

func (b Token) AssertUser(id user.ID) bool

AssertUser checks if the Token is issued to the given user.

Zero Token is available to any user.

See also ForUser.

func (Token) EACLTable 

func (b Token) EACLTable() eacl.Table

EACLTable returns extended ACL table set by SetEACLTable.

Zero Token has zero eacl.Table.

func (*Token) ForUser 

func (b *Token) ForUser(id user.ID)

ForUser specifies ID of the user who can use the Token for the operations within issuer's container(s).

Optional: by default, any user has access to Token usage.

See also AssertUser.

func (Token) InvalidAt 

func (b Token) InvalidAt(epoch uint64) bool

InvalidAt asserts "exp", "nbf" and "iat" claims for the given epoch.

Zero Container is invalid in any epoch.

See also SetExp, SetNbf, SetIat.

func (Token) Marshal 

func (b Token) Marshal() []byte

Marshal encodes Token into a binary format of the NeoFS API protocol (Protocol Buffers V3 with direct field order).

See also Unmarshal.

func (Token) MarshalJSON 

func (b Token) MarshalJSON() ([]byte, error)

MarshalJSON encodes Token into a JSON format of the NeoFS API protocol (Protocol Buffers V3 JSON).

See also UnmarshalJSON.

func (*Token) ReadFromV2 

func (b *Token) ReadFromV2(m acl.BearerToken) error

ReadFromV2 reads Token from the acl.BearerToken message.

See also WriteToV2.

func (Token) ResolveIssuer 

func (b Token) ResolveIssuer() user.ID

ResolveIssuer resolves issuer's user.ID from the key used for Token signing. Returns zero user.ID if Token is unsigned or key has incorrect format.

See also Token.SigningKeyBytes.

func (*Token) SetEACLTable 

func (b *Token) SetEACLTable(table eacl.Table)

SetEACLTable sets eacl.Table that replaces the one from the issuer's container. If table has specified container, bearer token can be used only for operations within this specific container. Otherwise, Token can be used within any issuer's container.

SetEACLTable MUST be called if Token is going to be transmitted over NeoFS API V2 protocol.

See also EACLTable, AssertContainer.

func (*Token) SetExp 

func (b *Token) SetExp(exp uint64)

SetExp sets "exp" (expiration time) claim which identifies the expiration time (in NeoFS epochs) after which the Token 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 InvalidAt.

func (*Token) SetIat 

func (b *Token) SetIat(iat uint64)

SetIat sets "iat" (issued at) claim which identifies the time (in NeoFS epochs) at which the Token was issued. This claim can be used to determine the age of the Token.

Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6.

See also InvalidAt.

func (*Token) SetNbf 

func (b *Token) SetNbf(nbf uint64)

SetNbf sets "nbf" (not before) claim which identifies the time (in NeoFS epochs) before which the Token MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current epoch MUST be after or equal to the not-before epoch listed in the "nbf" claim.

Naming is inspired by https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5.

See also InvalidAt.

func (*Token) Sign 

func (b *Token) Sign(signer neofscrypto.Signer) error

Sign calculates and writes signature of the Token data using issuer's signer. Returns signature calculation errors.

Sign MUST be called if Token is going to be transmitted over NeoFS API V2 protocol.

Note that any Token mutation is likely to break the signature, so it is expected to be calculated as a final stage of Token formation.

See also Token.VerifySignature, [Token.Issuer], Token.SignedData.

func (*Token) SignedData 

func (b *Token) SignedData() []byte

SignedData returns actual payload to sign.

See also Token.Sign.

func (Token) SigningKeyBytes 

func (b Token) SigningKeyBytes() []byte

SigningKeyBytes returns issuer's public key in a binary format of NeoFS API protocol.

Unsigned Token has empty key.

The resulting slice of bytes is a serialized compressed public key. See [elliptic.MarshalCompressed]. Use [neofsecdsa.PublicKey.Decode] to decode it into a type-specific structure.

The value returned shares memory with the structure itself, so changing it can lead to data corruption. Make a copy if you need to change it.

See also Token.ResolveIssuer.

func (*Token) Unmarshal 

func (b *Token) Unmarshal(data []byte) error

Unmarshal decodes NeoFS API protocol binary data into the Token (Protocol Buffers V3 with direct field order). Returns an error describing a format violation.

See also Marshal.

func (*Token) UnmarshalJSON 

func (b *Token) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes NeoFS API protocol JSON data into the Token (Protocol Buffers V3 JSON). Returns an error describing a format violation.

See also MarshalJSON.

func (Token) VerifySignature 

func (b Token) VerifySignature() bool

VerifySignature checks if Token signature is presented and valid.

Zero Token fails the check.

See also Sign.

func (Token) WriteToV2 

func (b Token) WriteToV2(m *acl.BearerToken)

WriteToV2 writes Token to the acl.BearerToken message. The message must not be nil.

See also ReadFromV2.

Source Files

View all Source files

Directories

Path Synopsis
Package bearertest provides functions for testing bearer package.
 Package bearertest provides functions for testing bearer package.

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.