threshold/internal/credential/credential.go

// Package credential defines interfaces shared by other packages that
// manage credentials for Boundary sessions.
package credential

import (
	"context"

	"github.com/hashicorp/boundary/internal/boundary"
)

// A Store is a resource that can store, retrieve, and potentially generate
// credentials of differing types and access levels. It belongs to a scope
// and must support the principle of least privilege by providing
// mechanisms to limit the credentials it can access to the minimum
// necessary for the scope it is in.
type Store interface {
	boundary.Resource
	GetScopeId() string
}

// Type is the type of credential provided by a library.
type Type string

// Credential type values.
const (
	UnspecifiedType  Type = "unspecified"
	UserPasswordType Type = "user_password"
)

// A Library is a resource that provides credentials that are of the same
// type and access level from a single store.
type Library interface {
	boundary.Resource
	GetStoreId() string

	// TODO(mgaffney) 10/2021: Add method for returning the credential type
	// of the library
}

// Purpose is the purpose of the credential.
type Purpose string

func (p Purpose) String() string {
	return string(p)
}

// Credential purpose values.
const (
	// ApplicationPurpose is a credential used for application specific
	// purposes. Application credentials are returned to the user.
	ApplicationPurpose Purpose = "application"

	// IngressPurpose is a credential used by a boundary worker to secure
	// the connection between the user and the worker. Ingress credentials
	// are never returned to the user.
	IngressPurpose Purpose = "ingress"

	// EgressPurpose is a credential used by a boundary worker to secure
	// the connection between the worker and the endpoint. Egress
	// credentials are never returned to the user.
	EgressPurpose Purpose = "egress"
)

// ValidPurposes are the set of all credential Purposes.
var ValidPurposes = []Purpose{
	ApplicationPurpose,
	IngressPurpose,
	EgressPurpose,
}

// SecretData represents secret data.
type SecretData interface{}

// Credential is an entity containing secret data.
type Credential interface {
	boundary.Entity
	Secret() SecretData
}

// Dynamic is a credential generated by a library for a specific session.
type Dynamic interface {
	Credential
	GetSessionId() string
	Library() Library
	Purpose() Purpose
}

// A Request represents a request for a credential from the SourceId for
// the given purpose. For dynamic credentials, the SourceId is the PublicId
// of a credential library.
type Request struct {
	SourceId string
	Purpose  Purpose
}

// Issuer issues dynamic credentials.
type Issuer interface {
	// Issue issues dynamic credentials for a session from the requested
	// libraries and for the requested purposes. The sessionId must be a
	// valid sessionId. The SourceId in each request must be the public id
	// of a library the Issuer can issue credentials from.
	//
	// If Issue encounters an error, it returns no credentials and revokes
	// any credentials issued before encountering the error.
	Issue(ctx context.Context, sessionId string, requests []Request) ([]Dynamic, error)
}

// Revoker revokes dynamic credentials.
type Revoker interface {
	// Revoke revokes the dynamic credentials issued for sessionid.
	Revoke(ctx context.Context, sessionId string) error
}

// Password represents a secret password.
type Password string

// PrivateKey represents a secret private key.
type PrivateKey []byte

// UserPassword is a credential containing a username and a password.
type UserPassword interface {
	Credential
	Username() string
	Password() Password
}

// KeyPair is a credential containing a username and a private key.
type KeyPair interface {
	Credential
	Username() string
	Private() PrivateKey
}

// Certificate is a credential containing a certificate and the private key
// for the certificate.
type Certificate interface {
	Credential
	Certificate() []byte
	Private() PrivateKey
}