v.io: v.io/x/ref/lib/security Index | Files | Directories

package security

import "v.io/x/ref/lib/security"

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.


Package Files

blessingroots.go blessingstore.go create_principal.go doc.go forked_principal.go prepare_discharges.go principal.go security.vdl.go serializer_reader_writer.go storage.go util.go


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.


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")
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.

func CreatePersistentPrincipal Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

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

func MustForkPrincipal Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func ZeroPassphrase(pass []byte)

ZeroPassphrase overwrites the passphrase.

type CachedDischarge Uses

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

func (CachedDischarge) VDLIsZero Uses

func (x CachedDischarge) VDLIsZero() bool

func (*CachedDischarge) VDLRead Uses

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

func (CachedDischarge) VDLReflect Uses

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

func (CachedDischarge) VDLWrite Uses

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

type DischargeCache Uses

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 Uses

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 Uses

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 Uses

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.


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

Package security imports 38 packages (graph) and is imported by 78 packages. Updated 2021-01-28. Refresh now. Tools for package owners.