security

Documentation

Overview

Package security implements utilities for creating and using Vanadium security primitives.

Index

• Constants
• Variables
• func CreatePersistentPrincipal(dir string, passphrase []byte) (principal security.Principal, err error)
• func FixedBlessingsStore(b security.Blessings, dcache DischargeCache) security.BlessingStore
• func ForkPrincipal(p security.Principal, store security.BlessingStore, ...) (security.Principal, error)
• func ImmutableBlessingRoots(r security.BlessingRoots) security.BlessingRoots
• func ImmutableBlessingStore(s security.BlessingStore) security.BlessingStore
• func InitDefaultBlessings(p security.Principal, name string) error
• func LoadPEMKey(r io.Reader, passphrase []byte) (interface{}, error)
• func LoadPersistentPrincipal(dir string, passphrase []byte) (security.Principal, error)
• func MustForkPrincipal(p security.Principal, store security.BlessingStore, ...) security.Principal
• func NewBlessingRoots() security.BlessingRoots
• func NewPrincipal() (security.Principal, error)
• func NewPrincipalFromSigner(signer security.Signer, state *PrincipalStateSerializer) (security.Principal, error)
• func NewPrincipalKey() (security.PublicKey, *ecdsa.PrivateKey, error)
• func PrepareDischarges(ctx *context.T, blessings security.Blessings, serverBlessings []string, ...) (map[string]security.Discharge, time.Time)
• func SavePEMKey(w io.Writer, key interface{}, passphrase []byte) error
• func SetDefaultBlessings(p security.Principal, blessings security.Blessings) error
• type CachedDischarge
  • func (x CachedDischarge) VDLIsZero() bool
  • func (x *CachedDischarge) VDLRead(dec vdl.Decoder) error
  • func (CachedDischarge) VDLReflect(struct{ ... })
  • func (x CachedDischarge) VDLWrite(enc vdl.Encoder) error
• type DischargeCache
• type FileSerializer
  • func NewFileSerializer(dataFilePath, signatureFilePath string) *FileSerializer
  • func (fs *FileSerializer) Readers() (io.ReadCloser, io.ReadCloser, error)
  • func (fs *FileSerializer) Writers() (io.WriteCloser, io.WriteCloser, error)
• type PrincipalStateSerializer
  • func NewPrincipalStateSerializer(dir string) (*PrincipalStateSerializer, error)
• type SerializerReaderWriter

Constants

const DischargeRefreshFraction = 0.5

DischargeRefreshFraction determines how early before their expiration time we refresh discharges. A value of 0.5 means we refresh when it is only half way to is expiration time.

Variables

var (
	// ErrBadPassphrase is a possible return error from LoadPEMKey()
	ErrBadPassphrase = verror.Register(pkgPath+".errBadPassphrase", verror.NoRetry, "{1:}{2:} passphrase incorrect for decrypting private key{:_}")
	// ErrPassphraseRequired is a possible return error from LoadPEMKey()
	ErrPassphraseRequired = verror.Register(pkgPath+".errPassphraseRequired", verror.NoRetry, "{1:}{2:} passphrase required for decrypting private key{:_}")
)

Functions

func CreatePersistentPrincipal

func CreatePersistentPrincipal(dir string, passphrase []byte) (principal security.Principal, err error)

CreatePersistentPrincipal creates a new principal (private key, BlessingRoots, BlessingStore) and commits all state changes to the provided directory.

The generated private key is serialized and saved encrypted if the 'passphrase' is non-nil, and unencrypted otherwise.

If the directory has any preexisting principal data, CreatePersistentPrincipal will return an error.

The specified directory may not exist, in which case it gets created by this function.

func FixedBlessingsStore

func FixedBlessingsStore(b security.Blessings, dcache DischargeCache) security.BlessingStore

FixedBlessingsStore returns a BlessingStore implementation that always returns a fixed set of blessings (b) for both Default and ForPeer.

If dcache is non-nil, then it will be used to cache discharges, otherwise it will create a cache of its own.

func ForkPrincipal

func ForkPrincipal(p security.Principal, store security.BlessingStore, roots security.BlessingRoots) (security.Principal, error)

ForkPrincipal returns a principal that has the same private key as p but uses store and roots instead of the BlessingStore and BlessingRoots in p.

func ImmutableBlessingRoots

func ImmutableBlessingRoots(r security.BlessingRoots) security.BlessingRoots

ImmutableBlessingRoots returns a BlessingRoots implementation that is identical to r, except that all mutation operations fail.

func ImmutableBlessingStore

func ImmutableBlessingStore(s security.BlessingStore) security.BlessingStore

ImmutableBlessingStore returns a BlessingStore implementation that is identical to r, except that Set* methods will fail. (Mutation in the form of adding discharges via CacheDischarge are still allowed).

func InitDefaultBlessings

func InitDefaultBlessings(p security.Principal, name string) error

InitDefaultBlessings uses the provided principal to create a self blessing for name 'name', sets it as default on the principal's BlessingStore and adds it as root to the principal's BlessingRoots. TODO(ataly): Get rid this function given that we have SetDefaultBlessings.

func LoadPEMKey

func LoadPEMKey(r io.Reader, passphrase []byte) (interface{}, error)

LoadPEMKey loads a key from 'r'. returns ErrBadPassphrase for incorrect Passphrase. If the key held in 'r' is unencrypted, 'passphrase' will be ignored.

func LoadPersistentPrincipal

func LoadPersistentPrincipal(dir string, passphrase []byte) (security.Principal, error)

LoadPersistentPrincipal reads state for a principal (private key, BlessingRoots, BlessingStore) from the provided directory 'dir' and commits all state changes to the same directory. If private key file does not exist then an error 'err' is returned such that os.IsNotExist(err) is true. If private key file exists then 'passphrase' must be correct, otherwise ErrBadPassphrase will be returned.

func MustForkPrincipal

func MustForkPrincipal(p security.Principal, store security.BlessingStore, roots security.BlessingRoots) security.Principal

MustForkPrincipal is identical to ForkPrincipal, except that it panics on error (such as if store is bound to a different PublicKey than p).

func NewBlessingRoots

func NewBlessingRoots() security.BlessingRoots

NewBlessingRoots returns an implementation of security.BlessingRoots that keeps all state in memory.

func NewPrincipal

func NewPrincipal() (security.Principal, error)

NewPrincipal mints a new private key and generates a principal based on this key, storing its BlessingRoots and BlessingStore in memory.

func NewPrincipalFromSigner

func NewPrincipalFromSigner(signer security.Signer, state *PrincipalStateSerializer) (security.Principal, error)

NewPrincipalFromSigner creates a new principal using the provided Signer. If previously persisted state is available, we use the serializers to populate BlessingRoots/BlessingStore for the Principal. If provided, changes to the state are persisted and committed with the same serializers. Otherwise, the state (ie: BlessingStore, BlessingRoots) is kept in memory.

func NewPrincipalKey

func NewPrincipalKey() (security.PublicKey, *ecdsa.PrivateKey, error)

NewPrincipalKey generates an ECDSA (public, private) key pair.

func PrepareDischarges

func PrepareDischarges(
	ctx *context.T,
	blessings security.Blessings,
	serverBlessings []string,
	method string,
	args []interface{}) (map[string]security.Discharge, time.Time)

PrepareDischarges retrieves the caveat discharges required for using blessings at server. The discharges are either found in the dischargeCache, in the call options, or requested from the discharge issuer indicated on the caveat. Note that requesting a discharge is an rpc call, so one copy of this function must be able to successfully terminate while another is blocked. PrepareDischarges also returns a refreshTime, which is the time at which PrepareDischarges should be called again (or zero if none of the discharges expire).

func SavePEMKey

func SavePEMKey(w io.Writer, key interface{}, passphrase []byte) error

SavePEMKey marshals 'key', encrypts it using 'passphrase', and saves the bytes to 'w' in PEM format. If passphrase is nil, the key will not be encrypted.

For example, if key is an ECDSA private key, it will be marshaled in ASN.1, DER format, encrypted, and then written in a PEM block.

func SetDefaultBlessings

func SetDefaultBlessings(p security.Principal, blessings security.Blessings) error

SetDefaultBlessings sets the provided blessings as default and shareable with all peers on provided principal's BlessingStore, and also adds it as a root to the principal's BlessingRoots.

Types

type CachedDischarge

type CachedDischarge struct {
	Discharge security.Discharge
	// CacheTime is the time at which the discharge was first cached.
	CacheTime time.Time
}

func (CachedDischarge) VDLIsZero

func (x CachedDischarge) VDLIsZero() bool

func (*CachedDischarge) VDLRead

func (x *CachedDischarge) VDLRead(dec vdl.Decoder) error

func (CachedDischarge) VDLReflect

func (CachedDischarge) VDLReflect(struct {
	Name string `vdl:"v.io/x/ref/lib/security.CachedDischarge"`
})

func (CachedDischarge) VDLWrite

func (x CachedDischarge) VDLWrite(enc vdl.Encoder) error

type DischargeCache

type DischargeCache interface {
	CacheDischarge(discharge security.Discharge, caveat security.Caveat, impetus security.DischargeImpetus)
	ClearDischarges(discharges ...security.Discharge)
	Discharge(caveat security.Caveat, impetus security.DischargeImpetus) (security.Discharge, time.Time)
}

DischargeCache is a subset of the security.BlessingStore interface that deals with caching discharges.

type FileSerializer

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

FileSerializer implements SerializerReaderWriter that persists state to files.

func NewFileSerializer

func NewFileSerializer(dataFilePath, signatureFilePath string) *FileSerializer

NewFileSerializer creates a FileSerializer with the given data and signature files.

func (*FileSerializer) Readers

func (fs *FileSerializer) Readers() (io.ReadCloser, io.ReadCloser, error)

func (*FileSerializer) Writers

func (fs *FileSerializer) Writers() (io.WriteCloser, io.WriteCloser, error)

type PrincipalStateSerializer

type PrincipalStateSerializer struct {
	BlessingRoots SerializerReaderWriter
	BlessingStore SerializerReaderWriter
}

PrincipalStateSerializer is used to persist BlessingRoots/BlessingStore state for a principal with the provided SerializerReaderWriters.

func NewPrincipalStateSerializer

func NewPrincipalStateSerializer(dir string) (*PrincipalStateSerializer, error)

NewPrincipalStateSerializer is a convenience function that returns a serializer for BlessingStore and BlessingRoots given a directory location. We create the directory if it does not already exist.

type SerializerReaderWriter

type SerializerReaderWriter interface {
	// Readers returns io.ReadCloser for reading serialized data and its
	// integrity signature.
	Readers() (data io.ReadCloser, signature io.ReadCloser, err error)
	// Writers returns io.WriteCloser for writing serialized data and its
	// integrity signature.
	Writers() (data io.WriteCloser, signature io.WriteCloser, err error)
}

SerializerReaderWriter is a factory for managing the readers and writers used for serialization and deserialization of signed data.