bearer

Documentation

Overview

Package bearer provides bearer token definition.

Bearer token is attached to the object service requests, and it can override APE policy set on the container. Mainly it is used to provide access to private data for specific user. Therefore, it must be signed by owner of the container.

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

var bearerToken bearer.Token
bearerToken.SetExp(500)
bearerToken.SetIat(10)
bearerToken.SetNbf(10)
bearerToken.SetAPEOverride(apeOverride)
bearerToken.ForUser(ownerID)

Bearer token must be signed by owner of the container.

err := bearerToken.Sign(privateKey)

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

import sdkClient "git.frostfs.info/TrueCloudLab/frostfs-sdk-go/client"

response, err := client.ObjectHead(ctx, sdkClient.PrmObjectHead{BearerToken: bearerToken})

Index

• func ResolveIssuer(b Token) (usr user.ID)
• type APEOverride
  • func (c *APEOverride) FromV2(tokenAPEChains *acl.APEOverride) error
  • func (c *APEOverride) Marshal() ([]byte, error)
  • func (c *APEOverride) MarshalJSON() ([]byte, error)
  • func (c *APEOverride) ToV2() *acl.APEOverride
  • func (c *APEOverride) Unmarshal(data []byte) error
  • func (c *APEOverride) UnmarshalJSON(data []byte) error
• type Token
  • func (b *Token) APEOverride() APEOverride
  • func (b Token) AssertContainer(cnr cid.ID) bool
  • func (b Token) AssertUser(id user.ID) bool
  • func (b Token) EACLTable() eacl.Table
  • func (b *Token) ForUser(id user.ID)
  • func (b Token) Impersonate() bool
  • func (b Token) InvalidAt(epoch uint64) bool
  • func (b Token) Marshal() []byte
  • func (b Token) MarshalJSON() ([]byte, error)
  • func (b *Token) ReadFromV2(m acl.BearerToken) error
  • func (b *Token) SetAPEOverride(v APEOverride)
  • func (b *Token) SetEACLTable(table eacl.Table)
  • func (b *Token) SetExp(exp uint64)
  • func (b *Token) SetIat(iat uint64)
  • func (b *Token) SetImpersonate(v bool)
  • func (b *Token) SetNbf(nbf uint64)
  • func (b *Token) Sign(key ecdsa.PrivateKey) error
  • func (b Token) SigningKeyBytes() []byte
  • func (b *Token) Unmarshal(data []byte) error
  • func (b *Token) UnmarshalJSON(data []byte) error
  • func (b Token) VerifySignature() bool
  • func (b Token) WriteToV2(m *acl.BearerToken)

Functions

func ResolveIssuer

func ResolveIssuer(b Token) (usr 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 SigningKeyBytes.

Types

type APEOverride

type APEOverride struct {
	// Target for which chains are applied.
	Target apeSDK.ChainTarget

	// The list of APE chains.
	Chains []apeSDK.Chain
}

APEOverride is the list of APE chains defined for a target. These chains are meant to serve as overrides to the already defined (or even undefined) APE chains for the target (see contract `Policy`).

The server-side processing of the bearer token with set APE overrides must verify if a client is permitted to override chains for the target, preventing unauthorized access through the APE mechanism.

func (*APEOverride) FromV2

func (c *APEOverride) FromV2(tokenAPEChains *acl.APEOverride) error

func (*APEOverride) Marshal

func (c *APEOverride) Marshal() ([]byte, error)

Marshal marshals APEOverride into a protobuf binary form.

func (*APEOverride) MarshalJSON

func (c *APEOverride) MarshalJSON() ([]byte, error)

MarshalJSON encodes APEOverride to protobuf JSON format.

func (*APEOverride) ToV2

func (c *APEOverride) ToV2() *acl.APEOverride

func (*APEOverride) Unmarshal

func (c *APEOverride) Unmarshal(data []byte) error

Unmarshal unmarshals protobuf binary representation of APEOverride.

func (*APEOverride) UnmarshalJSON

func (c *APEOverride) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes APEOverride from protobuf JSON format.

type Token

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

Token represents bearer token for object service operations.

Token is mutually compatible with git.frostfs.info/TrueCloudLab/frostfs-sdk-go/api/acl.BearerToken message. See ReadFromV2 / WriteToV2 methods.

Instances can be created using built-in var declaration.

func (*Token) APEOverride

func (b *Token) APEOverride() APEOverride

APEOverride returns APE override set by SetAPEOverride.

Zero Token has zero APEOverride.

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

func (b Token) Impersonate() bool

Impersonate returns true if token is impersonated.

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 FrostFS 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 FrostFS 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) SetAPEOverride

func (b *Token) SetAPEOverride(v APEOverride)

SetAPEOverride sets APE override to the bearer token.

See also: APEOverride.

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 FrostFS 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 FrostFS 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 FrostFS 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) SetImpersonate

func (b *Token) SetImpersonate(v bool)

SetImpersonate mark token as impersonate to consider token signer as request owner. If this field is true extended EACLTable in token body isn't processed.

func (*Token) SetNbf

func (b *Token) SetNbf(nbf uint64)

SetNbf sets "nbf" (not before) claim which identifies the time (in FrostFS 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(key ecdsa.PrivateKey) error

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

Sign MUST be called if Token is going to be transmitted over FrostFS 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 VerifySignature, Issuer.

func (Token) SigningKeyBytes

func (b Token) SigningKeyBytes() []byte

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

Unsigned Token has empty key.

See also ResolveIssuer.

func (*Token) Unmarshal

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

Unmarshal decodes FrostFS 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 FrostFS 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.