security

package
v0.1.18 Latest Latest
Warning

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

 Go to latest Published: Jun 21, 2021 License: BSD-3-Clause Imports: 37 Imported by: 59

Documentation

Overview

Package security implements utilities for creating and using Vanadium security primitives. In particular it provides support for creating and using persistent Vanadium principals whose keys and blessings are stored in a local file system directory. The blessings may be updated asynchronously and reloaded by a running service. Services may run in read-only mode whereby they can access updated blessings but cannot generate blessings of their own and hence only need access to a public key. Support is also provided for hosting private keys in ssh agents rather than the local file system and for all signing operations to be carried out by the agent.

Index

Constants

View Source 
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

View Source 
var (
	// ErrBadPassphrase is a possible return error from LoadPersistentPrincipal()
	ErrBadPassphrase = verror.NewID("errBadPassphrase")
	// ErrPassphraseRequired is a possible return error from LoadPersistentPrincipal()
	ErrPassphraseRequired = verror.NewID("errPassphraseRequired")
)
View Source 
var DefaultSSHAgentSockNameFunc = func() string {
	return os.Getenv("SSH_AUTH_SOCK")
}

DefaultSSHAgentSockNameFunc can be overridden to return the address of a custom ssh agent to use instead of the one specified by SSH_AUTH_SOCK. This is primarily intended for tests.

Functions

func CreatePersistentPrincipal 

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

CreatePersistentPrincipal wraps CreatePersistentPrincipalUsingKey to creates a new Principal using a newly generated ECSDA key.

func CreatePersistentPrincipalUsingKey added in v0.1.10 

func CreatePersistentPrincipalUsingKey(ctx context.Context, key interface{}, dir string, passphrase []byte) (security.Principal, error)

CreatePersistentPrincipalUsingKey creates a new Principal using the supplied key and commits all state changes to the provided directory.

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

If the directory has any preexisting principal data, an error is returned.

The specified directory may not exist, in which case it will be created. The follow key types are supported: *ecdsa.PrivateKey, ed25519.PrivateKey and SSHAgentHostedKey.

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 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. The newly loaded is principal's persistent store is locked and the returned unlock function must be called to release that lock.

func LoadPersistentPrincipalDaemon added in v0.1.10 

func LoadPersistentPrincipalDaemon(ctx context.Context, dir string, passphrase []byte, readonly bool, update time.Duration) (security.Principal, error)

LoadPersistentPrincipalDaemon is like LoadPersistentPrincipal but is intended for use in long running applications which may not need to initiate changes to the principal but may need to reload their blessings roots and stores. If readonly is true, the principal will not write changes to its underlying persistent store. If a non-zero update duration is specified then the principal will be reloaded at the frequency implied by that duration. In addition, on systems that support it, a SIGHUP can be used to request an immediate reload. If passphrase is nil, readonly is true and the private key file is encrypted LoadPersistentPrincipalDaemon will not attempt to create a signer and will instead just the principal's public key.

func LoadPersistentPrincipalWithPassphrasePrompt added in v0.1.10 

func LoadPersistentPrincipalWithPassphrasePrompt(dir string) (security.Principal, error)

LoadPersistentPrincipalWithPassphrasePrompt is like LoadPersistentPrincipal but will prompt for a passphrase if one is required.

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. The returned BlessingRoots is initialized with an empty set of keys.

func NewBlessingStore added in v0.1.10 

func NewBlessingStore(publicKey security.PublicKey) security.BlessingStore

NewBlessingStore returns an in-memory security.BlessingStore for a principal with the provided PublicKey.

The returned BlessingStore is initialized with an empty set of blessings.

func NewPersistentBlessingRoots added in v0.1.10 

func NewPersistentBlessingRoots(ctx context.Context, lockFilePath string, readers SerializerReader, writers SerializerWriter, signer serialization.Signer, publicKey security.PublicKey, update time.Duration) (security.BlessingRoots, error)

NewPersistentBlessingRoots returns a security.BlessingRoots for a principal that is initialized with the persisted data. The returned security.BlessingStore will persists any updates to its state if the supplied writers serializer is specified.

func NewPersistentBlessingStore added in v0.1.10 

func NewPersistentBlessingStore(ctx context.Context, lockFilePath string, readers SerializerReader, writers SerializerWriter, signer serialization.Signer, publicKey security.PublicKey, update time.Duration) (security.BlessingStore, error)

NewPersistentBlessingStore returns a security.BlessingStore for a principal that is initialized with the persisted data. The returned security.BlessingStore will persists any updates to its state if the supplied writers serializer is specified.

func NewPrincipal 

func NewPrincipal() (security.Principal, error)

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

func NewPrincipalFromSigner 

func NewPrincipalFromSigner(signer security.Signer) (security.Principal, error)

NewPrincipalFromSigner creates a new Principal using the provided Signer with in-memory blessing roots and blessings store.

func NewPrincipalFromSignerAndState added in v0.1.10 

func NewPrincipalFromSignerAndState(signer security.Signer, dir string) (security.Principal, error)

NewPrincipalFromSignerAndState creates a new Principal using the provided Signer with blessing roots and blessings store loaded from the supplied state directory.

func NewPrivateKey added in v0.1.10 

func NewPrivateKey(keyType string) (interface{}, error)

NewPrivateKey creates a new private key of the requested type. keyType must be one of ecdsa256, ecdsa384, ecdsa521 or ed25519.

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 SetDefaultBlessings 

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

SetDefault`Blessings `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.

func ZeroPassphrase added in v0.1.10 

func ZeroPassphrase(pass []byte)

ZeroPassphrase overwrites the passphrase.

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) error
	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 SSHAgentHostedKey added in v0.1.10 

type SSHAgentHostedKey struct {
	PublicKeyFile string
	Agent         *sshagent.Client
}

SSHAgentHostedKey represents a private key hosted by an ssh agent. The public key file must be accessible and is used to identify the private key hosted by the ssh agent. Currently ecdsa and ed25519 key types are supported.

type SerializerReader added in v0.1.10 

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

SerializerWriter is a factory for managing the readers used for deserialization of signed data.

type SerializerWriter added in v0.1.10 

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

SerializerWriter is a factory for managing the writers used for serialization of signed data.

Source Files

View all Source files

Directories

Path Synopsis
Package audit implements a mechanism for writing auditable events to an audit log.
 Package audit implements a mechanism for writing auditable events to an audit log.
Package bcrypter defines the mechanisms for blessings based encryption and decryption.
 Package bcrypter defines the mechanisms for blessings based encryption and decryption.
lockedfile
Package lockedfile creates and manipulates files whose contents should only change atomically.
 Package lockedfile creates and manipulates files whose contents should only change atomically.
lockedfile/filelock
Package filelock provides a platform-independent API for advisory file locking.
 Package filelock provides a platform-independent API for advisory file locking.
lockedfile/testenv
Package passphrase contains utilities for reading a passphrase.
 Package passphrase contains utilities for reading a passphrase.
Package securityflag implements utilities for creating security objects based on flags.
 Package securityflag implements utilities for creating security objects based on flags.
Package serialization implements utilities for reading and writing data with signature-based integrity checking.
 Package serialization implements utilities for reading and writing data with signature-based integrity checking.
internal
keyfile
Package keyfile provides a signing service that uses files to store keys.
 Package keyfile provides a signing service that uses files to store keys.
sshagent
Package sshagent provides the ability to use openssh's ssh-agent to carry out key signing operations using keys stored therein.
 Package sshagent provides the ability to use openssh's ssh-agent to carry out key signing operations using keys stored therein.

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.