credentials

package
Version: v0.33.0 Latest Latest
Warning

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

Go to latest
Published: Aug 20, 2021 License: Apache-2.0 Imports: 22 Imported by: 2

Documentation

Overview

Package credentials provides utilities for managing SecretHub API credentials.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidCredential                 = errCredentials.Code("invalid_credential")
	ErrInvalidNumberOfCredentialSegments = errCredentials.Code("invalid_number_of_credential_segments").ErrorPref("credential contains an invalid number of segments: %d")
	ErrEmptyCredentialHeader             = errCredentials.Code("invalid_empty_credential_header").Error("credential header cannot be empty")
	ErrEmptyCredentialPassphrase         = errCredentials.Code("invalid_empty_credential_passphrase").Error("credential passphrase cannot be empty for encrypted credentials")
	ErrInvalidCredentialHeaderField      = errCredentials.Code("invalid_credential_header_field").ErrorPref("invalid header field: %s")
	ErrCannotDecodeCredentialHeader      = errCredentials.Code("invalid_credential_header").ErrorPref("cannot decode credential header: %v")
	ErrUnsupportedCredentialType         = errCredentials.Code("unsupported_credential_type").ErrorPref("unsupported credential type: %s")
	ErrCannotDecodeCredentialPayload     = errCredentials.Code("invalid_credential_header").ErrorPref("cannot decode credential payload: %v")
	ErrCannotDecodeEncryptedCredential   = errCredentials.Code("cannot_decode_encrypted_credential").Error("cannot decode an encrypted credential without a key")
	ErrCannotDecryptCredential           = errCredentials.Code("cannot_decrypt_credential").Error("passphrase is incorrect")
	ErrNeedPassphrase                    = errCredentials.Code("credential_passphrase_required").Error("credential is password-protected. Configure a credential passphrase through the SECRETHUB_CREDENTIAL_PASSPHRASE environment variable or use a credential that is not password-protected")
	ErrMalformedCredential               = errCredentials.Code("malformed_credential").ErrorPref("credential is malformed: %v")
	ErrInvalidKey                        = errCredentials.Code("invalid_key").Error("the given key is not valid for the encryption algorithm")
)

Errors

View Source
var (
	// DefaultDecoders defines the default list of supported decoders.
	DefaultDecoders = []Decoder{rsaPrivateKeyDecoder{}}
)

Functions

func EncodeCredential

func EncodeCredential(credential EncodableCredential) ([]byte, error)

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

func EncodeEncryptedCredential

func EncodeEncryptedCredential(credential EncodableCredential, key PassBasedKey) ([]byte, error)

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

func ValidateBootstrapCode added in v0.25.0

func ValidateBootstrapCode(code string) error

ValidateBootstrapCode validates a string and checks whether it is a valid bootstrap code.

Types

type BackupCodeCreator added in v0.25.0

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

BackupCodeCreator creates a new credential based on a backup code.

func CreateBackupCode added in v0.25.0

func CreateBackupCode() *BackupCodeCreator

CreateBackupCode returns a Creator that creates a backup code credential.

func (*BackupCodeCreator) Code added in v0.25.0

func (b *BackupCodeCreator) Code() (string, error)

Code returns the string representation of the backup code. Can only be called after the credential has been created.

func (*BackupCodeCreator) Create added in v0.25.0

func (b *BackupCodeCreator) Create() error

Create generates a new code and stores it in the BackupCodeCreator.

func (*BackupCodeCreator) Encrypter added in v0.25.0

func (b *BackupCodeCreator) Encrypter() Encrypter

Encrypter returns a Encrypter that can be used to encrypt data with this backup code.

func (*BackupCodeCreator) Metadata added in v0.25.0

func (b *BackupCodeCreator) Metadata() map[string]string

Metadata returns the metadata for a backup code.

func (*BackupCodeCreator) Verifier added in v0.25.0

func (b *BackupCodeCreator) Verifier() Verifier

Verifier returns a Verifier that can be used for creating a new credential from this backup code.

type Creator

type Creator interface {
	// Create creates the actual credential (e.g. by generating a key).
	Create() error
	// Verifier returns information that the server can use to verify a request authenticated with the credential.
	Verifier() Verifier
	// Encrypter returns a wrapper that is used to encrypt data, typically an account key.
	Encrypter() Encrypter
	// Metadata returns a set of metadata about the credential. The result can be empty if no metadata is provided.
	Metadata() map[string]string
}

Creator is an interface is accepted by functions that need a new credential to be created.

func CreateAWS

func CreateAWS(kmsKeyID string, roleARN string, awsCfg ...*awssdk.Config) Creator

CreateAWS returns a Creator that creates an AWS-based credential. The kmsKeyID is the ID of the key in KMS that is used to encrypt the account key. The roleARN is for the IAM role that should be assumed to use this credential. The role should have decryption permission on the provided KMS key. awsCfg can be used to optionally configure the used AWS client. For example to set the region. The KMS key id and role are returned in the credentials metadata.

Example
package main

import (
	"github.com/secrethub/secrethub-go/pkg/secrethub"
	"github.com/secrethub/secrethub-go/pkg/secrethub/credentials"
)

func main() {
	client := secrethub.Must(secrethub.NewClient())

	credential := credentials.CreateAWS("1234abcd-12ab-34cd-56ef-1234567890ab", "MyIAMRole")
	_, err := client.Services().Create("my/repo", "description", credential)
	if err != nil {
		// handle error
	}
}
Output:

Example (SetRegion)
package main

import (
	"github.com/aws/aws-sdk-go/aws"
	"github.com/secrethub/secrethub-go/pkg/secrethub"
	"github.com/secrethub/secrethub-go/pkg/secrethub/credentials"
)

func main() {
	client := secrethub.Must(secrethub.NewClient())

	credential := credentials.CreateAWS(
		"1234abcd-12ab-34cd-56ef-1234567890ab",
		"MyIAMRole",
		&aws.Config{Region: aws.String("eu-west-1")})
	_, err := client.Services().Create("my/repo", "description", credential)
	if err != nil {
		// handle error
	}
}
Output:

func CreateGCPServiceAccount added in v0.29.0

func CreateGCPServiceAccount(serviceAccountEmail string, keyResourceID string, gcpOptions ...option.ClientOption) Creator

CreateGCPServiceAccount returns a Creator that creates a credential for a GCP Service Account. The serviceAccountEmail is the email of the GCP Service Account that can use this SecretHub service account. The kmsResourceID is the Resource ID of the key in KMS that is used to encrypt the account key. The service account should have decryption permission on the provided KMS key. gcpOptions can be used to optionally configure the used GCP client. For example to set a custom API key. The KMS key id and service account email are returned in the credentials metadata.

type CreatorProvider

type CreatorProvider interface {
	Creator
	Provider
}

CreatorProvider is both a credential creator and provider.

type CredentialSource added in v0.32.0

type CredentialSource interface {
	Source() string
}

CredentialSource should be implemented by credential readers to allow returning credential reading errors that include the credentials source (e.g. path to credential file, environment variable etc.).

type Decoder

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

Decoder converts a payload into a Credential.

type Decrypter

type Decrypter interface {
	// Unwrap decrypts data, typically an account key.
	Unwrap(ciphertext *api.EncryptedData) ([]byte, error)
}

Decrypter decrypts data, typically an account key.

type EncodableCredential

type EncodableCredential interface {
	// Encode the credential to a format that can be decoded by its Decoder.
	Encode() []byte
	// Decoder returns a Decoder that can decode an exported key back into a Credential.
	Decoder() Decoder
}

EncodableCredential used to be an interface that contained functions to encrypt, decrypt and authenticate. We'll migrate away from using it and use smaller interfaces instead. See Verifier, Decrypter and Encrypter for the smaller interfaces.

type Encrypter

type Encrypter interface {
	// Wrap encrypts data, typically an account key.
	Wrap(plaintext []byte) (*api.EncryptedData, error)
}

Encrypter encrypts data, typically an account key.

type ErrLoadingCredential added in v0.32.0

type ErrLoadingCredential struct {
	Location string
	Err      error
}

func (ErrLoadingCredential) Error added in v0.32.0

func (e ErrLoadingCredential) Error() string

type Key

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

Key is a credential that uses a local key for all its operations.

func ImportKey

func ImportKey(credentialReader, passphraseReader Reader) (Key, error)

ImportKey returns a Key by loading it from the provided credentialReader. If the key is encrypted with a passphrase, passphraseReader should be provided. This is used to read a passphrase from that is used for decryption. If the passphrase is incorrect, a new passphrase will be read up to 3 times.

func (Key) Encrypter

func (k Key) Encrypter() Encrypter

Encrypter returns a Encrypter that can be used to encrypt data with this Key.

func (Key) Export

func (k Key) Export() ([]byte, error)

Export the key of this credential to string format to save for later use. If a passphrase was set with Passphrase(), this passphrase is used for encrypting the key.

func (Key) Passphrase

func (k Key) Passphrase(passphraseReader Reader) Key

Passphrase returns a new Key that uses the provided passphraseReader to obtain a passphrase that is used for encryption when Export() is called.

func (Key) Provide

func (k Key) Provide(httpClient *http.Client) (auth.Authenticator, Decrypter, error)

Provide implements the Provider interface for a Key.

func (Key) Verifier

func (k Key) Verifier() Verifier

Verifier returns a Verifier that can be used for creating a new credential from this Key.

type KeyCreator

type KeyCreator struct {
	Key
}

KeyCreator is used to create a new key-based credential.

func CreateKey

func CreateKey() *KeyCreator

CreateKey returns a Creator that creates a key based credential. After use, the key can be accessed with the Export() method. The user of CreateKey() is responsible for saving the exported key. If this is not done, the credential will be unusable.

Example
package main

import (
	"fmt"

	"github.com/secrethub/secrethub-go/pkg/secrethub"
	"github.com/secrethub/secrethub-go/pkg/secrethub/credentials"
)

func main() {
	client := secrethub.Must(secrethub.NewClient())

	credential := credentials.CreateKey()
	_, err := client.Services().Create("my/repo", "description", credential)
	if err != nil {
		// handle error
	}
	key, err := credential.Export()
	if err != nil {
		// handle error
	}
	fmt.Printf("The key credential of the service is:\n%s", key)
}
Output:

func (*KeyCreator) Create

func (kc *KeyCreator) Create() error

Create generates a new key and stores it in the KeyCreator.

func (*KeyCreator) Metadata

func (kc *KeyCreator) Metadata() map[string]string

Metadata returns a set of metadata associated with this credential.

type KeyProvider

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

KeyProvider is a Provider that reads a key from a Reader. If the key is encrypted with a passphrase, Passphrase() should be called on the KeyProvider to set the Reader that provides the passphrase that can be used to decrypt the key.

func UseKey

func UseKey(credentialReader Reader) KeyProvider

UseKey returns a Provider that reads a key credential from credentialReader. If the key credential is encrypted, a passphrase must be set by calling Passphrase on the returned KeyProvider,

Usage:

credentials.UseKey(credentials.FromString("<a credential>"))
credentials.UseKey(credentials.FromFile("/path/to/credential")).Passphrase(credentials.FromString("passphrase"))

func (KeyProvider) Passphrase

func (k KeyProvider) Passphrase(passphraseReader Reader) Provider

Passphrase returns a new Provider that uses the passphraseReader to read a passphrase if the read key is encrypted.

func (KeyProvider) Provide

func (k KeyProvider) Provide(httpClient *http.Client) (auth.Authenticator, Decrypter, error)

Provide implements the Provider interface for a KeyProvider.

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 Provider

type Provider interface {
	Provide(*http.Client) (auth.Authenticator, Decrypter, error)
}

Provider provides a credential that can be used for authentication and decryption when called.

func UseAWS

func UseAWS(awsCfg ...*awssdk.Config) Provider

UseAWS returns a Provider that can be used to use an assumed AWS role as a credential for SecretHub. The provided awsCfg is used to configure the AWS client. If used on AWS (e.g. from an EC2-instance), this extra configuration is not required and the correct configuration should be auto-detected by the AWS client.

Usage:

credentials.UseAWS()
credentials.UseAWS(&aws.Config{Region: aws.String("eu-west-1")})

func UseBackupCode added in v0.25.0

func UseBackupCode(code string) Provider

UseBackupCode returns a Provider for authentication and decryption with the given backup code.

func UseGCPServiceAccount added in v0.29.0

func UseGCPServiceAccount(gcpOptions ...option.ClientOption) Provider

UseGCPServiceAccount returns a Provider that can be used to use a GCP Service Account as a credential for SecretHub. The provided gcpOptions is used to configure the GCP client. If used on GCP (e.g. from a Compute Engine instance), this extra configuration is not required and the correct configuration should be auto-detected by the GCP client.

Access to the GCP metadata server is required for this function to work. In practice, this means that it can only be run on GCP.

Usage:

credentials.UseGCPServiceAccount()

type RSACredential

type RSACredential struct {
	crypto.RSAPrivateKey
}

RSACredential implements a Credential for an RSA key.

func GenerateRSACredential

func GenerateRSACredential(keyLength int) (*RSACredential, error)

GenerateRSACredential generates a new credential that has uses RSA key with keyLength bits for encryption and authentication.

func (RSACredential) AddProof

AddProof add the proof for possession of this credential to a CreateCredentialRequest .

func (RSACredential) Authenticate

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

Authenticate implements the auth.Authenticator interface.

func (RSACredential) Decoder

func (c RSACredential) Decoder() Decoder

Decoder returns the Decoder for the rsa private key.

func (RSACredential) Export

func (c RSACredential) Export() ([]byte, string, error)

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

func (RSACredential) ID

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

ID returns a string by which the credential can be identified.

func (RSACredential) Provide

Provide implements the credentials.Provider interface.

func (RSACredential) Sign

func (c RSACredential) Sign(data []byte) ([]byte, error)

Sign provides proof the given bytes are processed by the owner of the credential.

func (RSACredential) SignMethod

func (c RSACredential) SignMethod() string

SignMethod returns a string by which the signing method can be identified.

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 *api.EncryptedData) ([]byte, error)

Unwrap decrypts data, typically an account key.

func (RSACredential) Wrap

func (c RSACredential) Wrap(plaintext []byte) (*api.EncryptedData, error)

Wrap encrypts data, typically an account key.

type Reader

type Reader interface {
	// Read reads from the reader and returns the resulting bytes.
	Read() ([]byte, error)
}

Reader helps with reading bytes from a configured source.

func FromBytes

func FromBytes(raw []byte) Reader

FromBytes returns a reader that simply returns the given bytes when Read() is called.

func FromEnv

func FromEnv(key string) Reader

FromEnv returns a reader that reads the contents of an environment variable, e.g. a credential or a passphrase.

func FromFile

func FromFile(path string) Reader

FromFile returns a reader that reads the contents of a file, e.g. a credential or a passphrase.

func FromString

func FromString(raw string) Reader

FromString returns a reader that simply returns the given string as a byte slice when Read() is called.

type SetupCode added in v0.31.0

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

func NewSetupCode added in v0.31.0

func NewSetupCode(code string) *SetupCode

func (*SetupCode) Authenticate added in v0.31.0

func (s *SetupCode) Authenticate(r *http.Request) error

Authenticate authenticates the given request with a setup code, by providing the "SetupCode" tag and the setup code in the "Authorization" header.

func (*SetupCode) Provide added in v0.31.0

func (s *SetupCode) Provide(client *httpclient.Client) (auth.Authenticator, Decrypter, error)

Provide implements the Provider interface for the setup code. Note that no decrypter is ever returned as setup codes cannot be used to decrypt secrets.

type Verifier

type Verifier interface {
	// Export returns the data to be stored server side to verify an http request authenticated with this credential.
	Export() (verifierBytes []byte, fingerprint string, err error)
	// Type returns what type of credential this is.
	Type() api.CredentialType
	// AddProof adds the proof of this credential's possession to a CreateCredentialRequest.
	AddProof(req *api.CreateCredentialRequest) error
}

Verifier exports verification bytes that can be used to verify signed data is processed by the owner of a signer.

Directories

Path Synopsis
Package sessions provides session authentication to the SecretHub API for the HTTP client.
Package sessions provides session authentication to the SecretHub API for the HTTP client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL