credentials

package
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 

func (c RSACredential) AddProof(_ *api.CreateCredentialRequest) error

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 

func (c RSACredential) Provide(_ *httpclient.Client) (auth.Authenticator, Decrypter, error)

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.