secrethub

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: May 2, 2019 License: Apache-2.0 Imports: 18 Imported by: 6

Documentation

Index

Constants

View Source 
const (
	// DefaultServerURL defines the default SecretHub API endpoint.
	DefaultServerURL = "https://api.secrethub.io"
	// DefaultTimeout defines the default client http timeout.
	DefaultTimeout = time.Second * 10
)
View Source 
const ClientVersion = "v0.19.0"

ClientVersion is the current version of the client Do not edit this unless you know what you're doing.

View Source 
const DefaultAccountKeyLength = 4096

DefaultAccountKeyLength defines the default bit size for account keys.

View Source 
const (
	// MaxSecretSize is the maximum size of a secret before encryption.
	MaxSecretSize = 512 * units.KiB
)

Variables

View Source 
var (
	ErrInvalidCredential                 = errClient.Code("invalid_credential")
	ErrInvalidNumberOfCredentialSegments = errClient.Code("invalid_number_of_credential_segments").ErrorPref("credential contains an invalid number of segments: %d")
	ErrEmptyCredentialHeader             = errClient.Code("invalid_empty_credential_header").Error("credential header cannot be empty")
	ErrEmptyCredentialPassphrase         = errClient.Code("invalid_empty_credential_passphrase").Error("credential passphrase cannot be empty for encrypted credentials")
	ErrInvalidCredentialHeaderField      = errClient.Code("invalid_credential_header_field").ErrorPref("invalid header field: %s")
	ErrCannotDecodeCredentialHeader      = errClient.Code("invalid_credential_header").ErrorPref("cannot decode credential header: %v")
	ErrUnsupportedCredentialType         = errClient.Code("unsupported_credential_type").ErrorPref("unsupported credential type: %s")
	ErrCannotDecodeCredentialPayload     = errClient.Code("invalid_credential_header").ErrorPref("cannot decode credential payload: %v")
	ErrCannotDecodeEncryptedCredential   = errClient.Code("cannot_decode_encrypted_credential").Error("cannot decode an encrypted credential without a key")
	ErrCannotDecryptCredential           = errClient.Code("cannot_decrypt_credential").Error("passphrase is incorrect")
	ErrInvalidKey                        = errClient.Code("invalid_key").Error("the given key is not valid for the encryption algorithm")
)

Errors

View Source 
var (
	// DefaultCredentialParser defines the default parser for credentials.
	DefaultCredentialParser = NewCredentialParser(DefaultCredentialDecoders)
	// DefaultCredentialDecoders defines the default list of supported decoders.
	DefaultCredentialDecoders = []CredentialDecoder{RSAPrivateKeyDecoder{}}
	// DefaultCredentialEncoding defines the default encoding used for encoding credential segments.
	DefaultCredentialEncoding = base64.URLEncoding.WithPadding(base64.NoPadding)
)
View Source 
var (
	ErrSecretTooBig         = errClient.Code("secret_too_big").Error(fmt.Sprintf("maximum size of a secret is %s", units.BytesSize(MaxSecretSize)))
	ErrEmptySecret          = errClient.Code("empty_secret").Error("secret is empty")
	ErrCannotWriteToVersion = errClient.Code("cannot_write_version").Error("cannot (over)write a specific secret version, they are append only")
)

Errors

View Source 
var (
	ErrWrongContentType = errClient.Code("wrong_content_type").Error("server returned wrong content type in header")
)

Errors

Functions

func EncodeCredential 

func EncodeCredential(credential Credential) (string, error)

EncodeCredential encodes a Credential as a one line string that can be transferred.

func EncodeEncryptedCredential 

func EncodeEncryptedCredential(credential Credential, key PassBasedKey) (string, error)

EncodeEncryptedCredential encrypts and encodes a Credential as a one line string token that can be transferred.

Types

type AccessRuleService 

type AccessRuleService interface {
	// Delete removes the accessrule for the given directory and account.
	Delete(path string, accountName string) error
	// Get retrieves the access rule for the given account on the given directory.
	Get(path string, accountName string) (*api.AccessRule, error)
	// List etrieves all access rules that apply to a directory, including
	// rules that apply to its children up to a specified depth. When ancestors is set
	// to true, it also includes rules for any parent directories. When the depth is
	// set to -1, all children are retrieved without limit.
	List(path string, depth int, ancestors bool) ([]*api.AccessRule, error)
	// ListLevels lists the access levels on the given directory.
	ListLevels(path string) ([]*api.AccessLevel, error)
	// Set sets an access rule with a certain permission level for an account to a path.
	Set(path string, permission api.Permission, accountName string) (*api.AccessRule, error)
}

AccessRuleService handles operations on access rules from SecretHub.

type AccountKeyService 

type AccountKeyService interface {
	// Create creates an account key for the client's credential.
	Create() (*api.EncryptedAccountKey, error)
	// Exists returns whether an account key exists for the client's credential.
	Exists() (bool, error)
}

AccountKeyService handles operations on SecretHub account keys.

type AccountService 

type AccountService interface {
	// Get retrieves an account by name.
	Get(name string) (*api.Account, error)
	// Keys returns an account key service.
	Keys() AccountKeyService
}

AccountService handles operations on SecretHub accounts.

type Client 

type Client interface {
	AccessRules() AccessRuleService
	Accounts() AccountService
	Dirs() DirService
	Me() MeService
	Orgs() OrgService
	Repos() RepoService
	Secrets() SecretService
	Services() ServiceService
	Users() UserService
}

Client is the SecretHub client.

func NewClient 

func NewClient(credential Credential, opts *ClientOptions) Client

NewClient creates a new SecretHub client. It overrides the default configuration with the options when given.

type ClientOptions 

type ClientOptions struct {
	ServerURL string
	Timeout   time.Duration
}

ClientOptions define client options, overriding the default settings.

type Credential 

type Credential interface {
	auth.Credential
	// Fingerprint returns an identifier by which the server can identify the credential, e.g. a username of a fingerprint.
	Fingerprint() (string, error)
	// Verifier returns the data to be stored server side to verify an http request authenticated with this credential.
	Verifier() ([]byte, error)
	// Wrap encrypts data, typically an account key.
	Wrap(plaintext []byte) (crypto.CiphertextRSAAES, error)
	// Unwrap decrypts data, typically an account key.
	Unwrap(ciphertext crypto.CiphertextRSAAES) ([]byte, error)
	// Export exports the credential in a format that can be decoded by its Decoder.
	Export() []byte
	// Decoder returns a decoder that can decode an exported key back into a Credential.
	Decoder() CredentialDecoder
	// Type returns what type of credential this is.
	Type() api.CredentialType
}

Credential can be used to encrypt and decrypt data and to authenticate http requests.

func GenerateCredential 

func GenerateCredential() (Credential, error)

GenerateCredential generates a new credential to be used to authenticate the account and to decrypt the account key.

func NewCredential 

func NewCredential(credential string, passphrase string) (Credential, error)

NewCredential is a shorthand function to decode a credential string and optionally decrypt it with a passphrase. When an encrypted credential is given, the passphrase cannot be empty.

Note that when you want to customize the process of parsing and decoding/decrypting a credential (e.g. to prompt only for a passphrase when the credential is encrypted), it is recommended you use a CredentialParser instead (e.g. DefaultCredentialParser).

type CredentialDecoder 

type CredentialDecoder interface {
	// Decode decodes a payload into a Credential.
	Decode(payload []byte) (Credential, error)
	// Name returns the name of the encoding.
	Name() string
}

CredentialDecoder converts a payload into a Credential.

type DirService 

type DirService interface {
	// Create a directory at a given path.
	Create(path string) (*api.Dir, error)
	// Delete removes the directory at the given path.
	Delete(path string) error
	// GetTree retrieves a directory at a given path and all of its descendants up to a given depth.
	// When the depth <= 0, all descendants are returned. When ancestors is true, the parent directories
	// of the dir at the given path will also be included in the tree.
	GetTree(path string, depth int, ancestors bool) (*api.Tree, error)
}

DirService handles operations on directories from SecretHub.

type EncodedCredential 

type EncodedCredential struct {
	// Raw is the raw credential string.
	// Populated when you Parse a credential.
	Raw string
	// Header is the decoded first part of the credential string.
	Header map[string]interface{}
	// RawHeader is the first part of the credential string, encoded as json.
	RawHeader []byte
	// Payload is the second part of the credential string.
	Payload []byte
	// EncryptionAlgorithm contains the name of the encryption algorithm if the payload is encrypted.
	EncryptionAlgorithm string
	// Decoder is used to decode the payload into a Credential.
	// Populated when you Parse a credential string.
	Decoder CredentialDecoder
}

EncodedCredential is an intermediary format for encoding and decoding credentials.

func (EncodedCredential) Decode 

func (c EncodedCredential) Decode() (Credential, error)

Decode decodes an unencrypted credential string into a Credential.

func (EncodedCredential) DecodeEncrypted 

func (c EncodedCredential) DecodeEncrypted(key PassBasedKey) (Credential, error)

DecodeEncrypted decodes and decrypts an encrypted credential string using the given key.

func (EncodedCredential) IsEncrypted 

func (c EncodedCredential) IsEncrypted() bool

IsEncrypted returns true when the credential is encrypted.

type MeService added in v0.18.0 

type MeService interface {
	// ListRepos retrieves all repositories of the current user.
	ListRepos() ([]*api.Repo, error)
	// GetUser retrieves the current users details.
	GetUser() (*api.User, error)
	// SendVerificationEmail sends an email to the authenticated user's registered email address
	// for them to prove they own that email address.
	SendVerificationEmail() error
}

MeService handles operations on the authenticated account.

type OrgMemberService 

type OrgMemberService interface {
	// Get retrieves a users organization membership details.
	Get(org string, username string) (*api.OrgMember, error)
	// Invite invites a user to an organization.
	Invite(org string, username string, role string) (*api.OrgMember, error)
	// List retrieves all members of the given organization.
	List(org string) ([]*api.OrgMember, error)
	// Revoke removes the given user from the organization.
	Revoke(org string, username string, opts *api.RevokeOpts) (*api.RevokeOrgResponse, error)
	// Update updates the role of a member of the organization.
	Update(org string, username string, role string) (*api.OrgMember, error)
}

OrgMemberService handles operations on organization members.

type OrgService 

type OrgService interface {
	// Create creates an organization.
	Create(name string, description string) (*api.Org, error)
	// Delete removes an organization.
	Delete(name string) error
	// Get retrieves an organization.
	Get(name string) (*api.Org, error)
	// Members returns an OrgMemberService.
	Members() OrgMemberService
	// ListMine returns the organizations of the current user.
	ListMine() ([]*api.Org, error)
}

OrgService handles operations on organisations on SecretHub.

type Parser 

type Parser struct {
	SupportedDecoders map[string]CredentialDecoder
}

Parser parses a credential string with support for different credential decoders.

func NewCredentialParser 

func NewCredentialParser(decoders []CredentialDecoder) Parser

NewCredentialParser returns a new credential parser

func (Parser) Parse 

func (p Parser) Parse(raw string) (*EncodedCredential, error)

Parse parses a credential string.

type PassBasedKey 

type PassBasedKey interface {
	// Name returns the name of the key derivation algorithm.
	Name() string
	// Encrypt encrypts a given payload with the passphrase derived key and returns encrypted bytes and header with encryption parameter values.
	Encrypt(payload []byte) ([]byte, map[string]interface{}, error)
	// Decrypt decrypts a payload with the key and accepts the raw JSON header to read values from.
	Decrypt(payload []byte, header []byte) ([]byte, error)
}

PassBasedKey can encrypt a Credential into token values.

func NewPassBasedKey 

func NewPassBasedKey(passphrase []byte) (PassBasedKey, error)

NewPassBasedKey generates a new key from a passphrase.

type RSACredential 

type RSACredential struct {
	crypto.RSAPrivateKey
}

RSACredential implements a Credential for an RSA key.

func (RSACredential) AddAuthentication 

func (c RSACredential) AddAuthentication(r *http.Request) error

AddAuthentication adds authentication to an http request.

func (RSACredential) Decoder 

func (c RSACredential) Decoder() CredentialDecoder

Decoder returns the decoder for the rsa private key.

func (RSACredential) Fingerprint 

func (c RSACredential) Fingerprint() (string, error)

Fingerprint returns the key identifier by which the server can identify the credential.

func (RSACredential) Type 

func (c RSACredential) Type() api.CredentialType

Type returns what type of credential this is.

func (RSACredential) Unwrap 

func (c RSACredential) Unwrap(ciphertext crypto.CiphertextRSAAES) ([]byte, error)

Unwrap decrypts data, typically an account key.

func (RSACredential) Verifier 

func (c RSACredential) Verifier() ([]byte, error)

Verifier returns the public key to be stored server side to verify an http request authenticated with this credential.

func (RSACredential) Wrap 

func (c RSACredential) Wrap(plaintext []byte) (crypto.CiphertextRSAAES, error)

Wrap encrypts data, typically an account key.

type RSAPrivateKeyDecoder 

type RSAPrivateKeyDecoder struct{}

RSAPrivateKeyDecoder implements the CredentialDecoder interface for an RSA private key.

func (RSAPrivateKeyDecoder) Decode 

func (d RSAPrivateKeyDecoder) Decode(payload []byte) (Credential, error)

Decode converts a EncodedCredential's payload into an RSA ClientKey.

func (RSAPrivateKeyDecoder) Name 

func (d RSAPrivateKeyDecoder) Name() string

Name returns the encoding name.

type RepoService 

type RepoService interface {
	// Create creates a new repo for the given owner and name.
	Create(path string) (*api.Repo, error)
	// Delete removes the repo with the given path.
	Delete(path string) error
	// Get retrieves the repo with the given path.
	Get(path string) (*api.Repo, error)
	// List retrieves all repositories in the given namespace.
	List(namespace string) ([]*api.Repo, error)
	// ListAccounts lists the accounts in the repository.
	ListAccounts(path string) ([]*api.Account, error)
	// ListEvents retrieves all audit events for a given repo.
	ListEvents(path string, subjectTypes api.AuditSubjectTypeList) ([]*api.Audit, error)
	// ListMine retrieves all repositories of the current user.
	ListMine() ([]*api.Repo, error)
	// Users returns a RepoUserService that handles operations on users of a repository.
	Users() RepoUserService
	// Services returns a RepoServiceService that handles operations on services of a repository.
	Services() RepoServiceService
}

RepoService handles operations on repositories from SecretHub.

type RepoServiceService 

type RepoServiceService interface {
	// List lists the services of the given repository.
	List(path string) ([]*api.Service, error)
}

RepoServiceService handles operations on services of repositories.

type RepoUserService 

type RepoUserService interface {
	// Invite invites the user with given username to the repository at the given path.
	Invite(path string, username string) (*api.RepoMember, error)
	// List lists the users of the given repository.
	List(path string) ([]*api.User, error)
	// Revoke revokes the user with given username from the repository with the given path.
	Revoke(path string, username string) (*api.RevokeRepoResponse, error)
}

RepoUserService handles operations on users of a repository.

type SecretService 

type SecretService interface {
	// Delete removes the secret at the given path.
	Delete(path string) error
	// Exists returns whether a secret exists on the given path.
	Exists(path string) (bool, error)
	// Get retrieves a Secret.
	Get(path string) (*api.Secret, error)
	// ListEvents retrieves all audit events for a given secret.
	ListEvents(path string, subjectTypes api.AuditSubjectTypeList) ([]*api.Audit, error)

	// Versions returns a SecretVersionService.
	Versions() SecretVersionService

	// Write encrypts and writes any secret data to SecretHub, always creating
	// a new secret version for the written data. This ensures secret data is
	// never overwritten.
	//
	// To ensure forward secrecy, a new secret key is used whenever the previously
	// used key has been flagged.
	//
	// Write accepts any non-empty byte data that is within the size limit of MaxSecretSize.
	// Note that data is encrypted as is. Sanitizing data is the responsibility of the
	// function caller.
	Write(path string, data []byte) (*api.SecretVersion, error)
}

SecretService handles operations on secrets from SecretHub.

type SecretVersionService 

type SecretVersionService interface {
	// Delete removes a secret version.
	Delete(path string) error
	// GetWithData gets a secret version, with the sensitive data.
	GetWithData(path string) (*api.SecretVersion, error)
	// GetWithoutData gets a secret version, without the sensitive data.
	GetWithoutData(path string) (*api.SecretVersion, error)
	// ListWithData lists secret versions, with the sensitive data.
	ListWithData(path string) ([]*api.SecretVersion, error)
	// ListWithoutData lists secret versions, without the sensitive data.
	ListWithoutData(path string) ([]*api.SecretVersion, error)
}

SecretVersionService handles operations on secret versions from SecretHub.

type ServiceService 

type ServiceService interface {
	// Create creates a new service account for the given repo.
	Create(path string, description string, credential Credential) (*api.Service, error)
	// Delete removes a service account by name.
	Delete(name string) (*api.RevokeRepoResponse, error)
	// Get retrieves a service account by name.
	Get(name string) (*api.Service, error)
	// List lists all service accounts in a given repository.
	List(path string) ([]*api.Service, error)
}

ServiceService handles operations on service accounts from SecretHub.

type UserService 

type UserService interface {
	// Me gets the account's user if it exists.
	Me() (*api.User, error)
	// Create creates a new user at SecretHub.
	Create(username, email, fullName string) (*api.User, error)
	// Get a user by their username.
	Get(username string) (*api.User, error)
}

UserService handles operations on users from SecretHub.

Source Files

View all Source files

Directories

Path Synopsis

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.