credhub

package
Version: v0.0.0-...-4dad804 Latest Latest
Warning

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

Go to latest
Published: May 16, 2022 License: Apache-2.0 Imports: 27 Imported by: 37

Documentation

Overview

Package credhub is a client library for interacting with a CredHub server.

More information on CredHub can be found at https://code.cloudfoundry.org/credhub

Server HTTP API specification can be found at https://docs.cloudfoundry.org/api/credhub/

Example
package main

import (
	"fmt"

	"code.cloudfoundry.org/credhub-cli/credhub"
	"code.cloudfoundry.org/credhub-cli/credhub/auth"
	"code.cloudfoundry.org/credhub-cli/credhub/credentials/generate"
)

func main() {
	_ = func() {
		// CredHub server at https://example.com, using UAA Password grant
		ch, err := credhub.New("https://example.com",
			credhub.CaCerts(string("--- BEGIN ---\nroot-certificate\n--- END ---")),
			credhub.Auth(auth.UaaPassword("credhub_cli", "", "username", "password")),
		)

		// We'll be working with a certificate stored at "/my-certificates/the-cert"
		path := "/my-certificates/"
		name := "the-cert"

		// If the certificate already exists, delete it
		cert, err := ch.GetLatestCertificate(path + name)
		if err == nil {
			ch.Delete(cert.Name)
		}

		// Generate a new certificate
		gen := generate.Certificate{
			CommonName: "pivotal",
			KeyLength:  2048,
		}
		cert, err = ch.GenerateCertificate(path+name, gen, credhub.NoOverwrite)
		if err != nil {
			panic("couldn't generate certificate")
		}

		// Use the generated certificate's values to create a new certificate
		dupCert, err := ch.SetCertificate(path+"dup-cert", cert.Value)
		if err != nil {
			panic("couldn't create certificate")
		}

		if dupCert.Value.Certificate != cert.Value.Certificate {
			panic("certs don't match")
		}

		// List all credentials in "/my-certificates"
		creds, err := ch.FindByPath(path)
		if err != nil {
			panic("couldn't list certificates")
		}

		fmt.Println("Found the following credentials in " + path + ":")
		for _, cred := range creds.Credentials {
			fmt.Println(cred.Name)
		}
		// Sample Output:
		// Found the following credentials in /my-certificates:
		// /my-certificates/dup-cert
		// /my-certificates/the-cert
	}
}
Output:

Index

Examples

Constants

This section is empty.

Variables

View Source
var ServerDoesNotSupportMetadataError = errors.New("the server does not support credential metadata, requires >= 2.6.x")

Functions

This section is empty.

Types

type CredHub

type CredHub struct {
	// ApiURL is the host and port of the CredHub server to target
	// Example: https://credhub.example.com:8844
	ApiURL string

	// Auth provides an authentication Strategy for authenticated requests to the CredHub server
	// Can be type asserted to a specific Strategy type to get additional functionality and information.
	// eg. auth.OAuthStrategy provides Logout(), Refresh(), AccessToken() and RefreshToken()
	Auth auth.Strategy
	// contains filtered or unexported fields
}

CredHub client to access CredHub APIs.

Use New() to construct a new CredHub object, which can then interact with the CredHub API.

Example
package main

import (
	"fmt"

	"code.cloudfoundry.org/credhub-cli/credhub"
	"code.cloudfoundry.org/credhub-cli/credhub/auth"
)

func main() {
	_ = func() {
		// Use a CredHub server on "https://example.com" using UAA password grant
		ch, err := credhub.New("https://example.com",
			credhub.SkipTLSValidation(true),
			credhub.Auth(auth.UaaPassword("credhub_cli", "", "username", "password")))

		if err != nil {
			panic("credhub client configured incorrectly: " + err.Error())
		}

		authUrl, err := ch.AuthURL()
		if err != nil {
			panic("couldn't fetch authurl")
		}

		fmt.Println("CredHub server: ", ch.ApiURL)
		fmt.Println("Auth server: ", authUrl)

		// Retrieve a password stored at "/my/password"
		password, err := ch.GetLatestPassword("/my/password")
		if err != nil {
			panic("password not found")
		}

		fmt.Println("My password: ", password.Value)

		// Manually refresh the access token
		uaa, ok := ch.Auth.(*auth.OAuthStrategy) // This works because we authenticated with auth.UaaPasswordGrant
		if !ok {
			panic("not using uaa")
		}

		fmt.Println("Old access token: ", uaa.AccessToken())

		uaa.Refresh() // For demo purposes only, tokens will be automatically refreshed by auth.OAuthStrategy

		fmt.Println("New access token:", uaa.AccessToken())
		// Sample Output:
		// CredHub server: https://example.com
		// Auth server: https://uaa.example.com
		// My password: random-password
		// Old access token: some-access-token
		// New access token: new-access-token
	}
}
Output:

func New

func New(target string, options ...Option) (*CredHub, error)

New provides a CredHub API client for the target server. Options can be provided to specify additional parameters, including authentication. See the Option type for a list of supported options.

When targeting multiple CredHub servers, use a new CredHub API client for each target server.

Example
package main

import (
	"fmt"

	"code.cloudfoundry.org/credhub-cli/credhub"
	"code.cloudfoundry.org/credhub-cli/credhub/auth"
)

func main() {
	_ = func() {
		ch, _ := credhub.New(
			"https://example.com",
			credhub.SkipTLSValidation(true),
			credhub.Auth(auth.UaaClientCredentials("client-id", "client-secret")),
		)

		fmt.Println("Connected to ", ch.ApiURL)
	}
}
Output:

func (*CredHub) AddPermission

func (ch *CredHub) AddPermission(path string, actor string, ops []string) (*permissions.Permission, error)

func (*CredHub) AuthURL

func (ch *CredHub) AuthURL() (string, error)

AuthURL returns the targeted CredHub server's trusted authentication server URL.

func (*CredHub) BulkRegenerate

func (ch *CredHub) BulkRegenerate(signedBy string) (credentials.BulkRegenerateResults, error)

func (*CredHub) Client

func (ch *CredHub) Client() *http.Client

Client provides an unauthenticated http.Client to the CredHub server

func (*CredHub) Delete

func (ch *CredHub) Delete(name string) error

Delete will delete all versions of a credential by name

func (*CredHub) DeletePermission

func (ch *CredHub) DeletePermission(uuid string) (*permissions.Permission, error)

func (*CredHub) FindByPartialName

func (ch *CredHub) FindByPartialName(nameLike string) (credentials.FindResults, error)

FindByPartialName retrieves a list of stored credential names which contain the search.

func (*CredHub) FindByPath

func (ch *CredHub) FindByPath(path string) (credentials.FindResults, error)

FindByPath retrieves a list of stored credential names which are within the specified path.

func (*CredHub) GenerateCertificate

func (ch *CredHub) GenerateCertificate(name string, gen generate.Certificate, overwrite Mode) (credentials.Certificate, error)

GenerateCertificate generates a certificate credential based on the provided parameters.

func (*CredHub) GenerateCredential

func (ch *CredHub) GenerateCredential(name, credType string, gen interface{}, overwrite Mode, options ...GenerateOption) (credentials.Credential, error)

GenerateCredential generates any credential type based on the credType given provided parameters.

func (*CredHub) GeneratePassword

func (ch *CredHub) GeneratePassword(name string, gen generate.Password, overwrite Mode) (credentials.Password, error)

GeneratePassword generates a password credential based on the provided parameters.

func (*CredHub) GenerateRSA

func (ch *CredHub) GenerateRSA(name string, gen generate.RSA, overwrite Mode) (credentials.RSA, error)

GenerateRSA generates an RSA credential based on the provided parameters.

func (*CredHub) GenerateSSH

func (ch *CredHub) GenerateSSH(name string, gen generate.SSH, overwrite Mode) (credentials.SSH, error)

GenerateSSH generates an SSH credential based on the provided parameters.

func (*CredHub) GenerateUser

func (ch *CredHub) GenerateUser(name string, gen generate.User, overwrite Mode) (credentials.User, error)

GenerateUser generates a user credential based on the provided parameters.

func (*CredHub) GetAllCertificatesMetadata

func (ch *CredHub) GetAllCertificatesMetadata() ([]credentials.CertificateMetadata, error)

func (*CredHub) GetAllVersions

func (ch *CredHub) GetAllVersions(name string) ([]credentials.Credential, error)

GetAllVersions returns all credential versions for a given credential name. The returned credentials will be encoded as a list of maps and may be of any type.

func (*CredHub) GetById

func (ch *CredHub) GetById(id string) (credentials.Credential, error)

GetById returns a credential version by ID. The returned credential will be encoded as a map and may be of any type.

func (*CredHub) GetCertificateMetadataByName

func (ch *CredHub) GetCertificateMetadataByName(name string) (credentials.CertificateMetadata, error)

func (*CredHub) GetLatestCertificate

func (ch *CredHub) GetLatestCertificate(name string) (credentials.Certificate, error)

GetLatestCertificate returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'certificate'.

func (*CredHub) GetLatestJSON

func (ch *CredHub) GetLatestJSON(name string) (credentials.JSON, error)

GetLatestJSON returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'json'.

func (*CredHub) GetLatestPassword

func (ch *CredHub) GetLatestPassword(name string) (credentials.Password, error)

GetLatestPassword returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'password'.

func (*CredHub) GetLatestRSA

func (ch *CredHub) GetLatestRSA(name string) (credentials.RSA, error)

GetLatestRSA returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'rsa'.

func (*CredHub) GetLatestSSH

func (ch *CredHub) GetLatestSSH(name string) (credentials.SSH, error)

GetLatestSSH returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'ssh'.

func (*CredHub) GetLatestUser

func (ch *CredHub) GetLatestUser(name string) (credentials.User, error)

GetLatestUser returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'user'.

func (*CredHub) GetLatestValue

func (ch *CredHub) GetLatestValue(name string) (credentials.Value, error)

GetLatestValue returns the current credential version for a given credential name. The returned credential will be encoded as a map and must be of type 'value'.

func (*CredHub) GetLatestVersion

func (ch *CredHub) GetLatestVersion(name string) (credentials.Credential, error)

GetLatestVersion returns the current credential version for a given credential name. The returned credential will be encoded as a map and may be of any type.

func (*CredHub) GetNVersions

func (ch *CredHub) GetNVersions(name string, numberOfVersions int) ([]credentials.Credential, error)

GetNVersions returns the N most recent credential versions for a given credential name. The returned credentials will be encoded as a list of maps and may be of any type.

func (*CredHub) GetPermissionByPathActor

func (ch *CredHub) GetPermissionByPathActor(path string, actor string) (*permissions.Permission, error)

func (*CredHub) GetPermissionByUUID

func (ch *CredHub) GetPermissionByUUID(uuid string) (*permissions.Permission, error)

func (*CredHub) GetPermissions

func (ch *CredHub) GetPermissions(name string) ([]permissions.V1_Permission, error)

func (*CredHub) Info

func (ch *CredHub) Info() (*server.Info, error)

Info returns the targeted CredHub server information.

func (*CredHub) InterpolateString

func (ch *CredHub) InterpolateString(vcapServicesBody string) (string, error)

InterpolateString translates credhub refs in a VCAP_SERVICES object into actual credentials

func (*CredHub) Regenerate

func (ch *CredHub) Regenerate(name string, options ...RegenerateOption) (credentials.Credential, error)

Regenerate generates and returns a new credential version using the same parameters as the existing credential. The returned credential may be of any type.

func (*CredHub) Request

func (ch *CredHub) Request(method string, pathStr string, query url.Values, body interface{}, checkServerErr bool) (*http.Response, error)

Request sends an authenticated request to the CredHub server.

The pathStr should include the full path (eg. /api/v1/data). The request body should be marshallable to JSON, but can be left nil for GET requests.

Request() is used by other CredHub client methods to send authenticated requests to the CredHub server.

Use Request() directly to send authenticated requests to the CredHub server. For unauthenticated requests (eg. /health), use Config.Client() instead.

Example
package main

import (
	"encoding/json"
	"fmt"

	"code.cloudfoundry.org/credhub-cli/credhub"
)

func main() {
	_ = func() {
		ch, _ := credhub.New("https://example.com")

		// Get encryption key usage
		response, err := ch.Request("GET", "/api/v1/key-usage", nil, nil, true)
		if err != nil {
			panic("couldn't get key usage")
		}

		var keyUsage map[string]int
		decoder := json.NewDecoder(response.Body)
		err = decoder.Decode(&keyUsage)
		if err != nil {
			panic("couldn't parse response")
		}

		fmt.Println("Active Key: ", keyUsage["active_key"])
		// Sample Output:
		// Active Key: 1231231
	}
}
Output:

func (*CredHub) ServerVersion

func (ch *CredHub) ServerVersion() (*version.Version, error)

func (*CredHub) SetCertificate

func (ch *CredHub) SetCertificate(name string, value values.Certificate, options ...SetOption) (credentials.Certificate, error)

SetCertificate sets a certificate credential with a user-provided value.

func (*CredHub) SetCredential

func (ch *CredHub) SetCredential(name, credType string, value interface{}, options ...SetOption) (credentials.Credential, error)

SetCredential sets a credential of any type with a user-provided value.

func (*CredHub) SetJSON

func (ch *CredHub) SetJSON(name string, value values.JSON, options ...SetOption) (credentials.JSON, error)

SetJSON sets a JSON credential with a user-provided value.

func (*CredHub) SetPassword

func (ch *CredHub) SetPassword(name string, value values.Password, options ...SetOption) (credentials.Password, error)

SetPassword sets a password credential with a user-provided value.

func (*CredHub) SetRSA

func (ch *CredHub) SetRSA(name string, value values.RSA, options ...SetOption) (credentials.RSA, error)

SetRSA sets an RSA credential with a user-provided value.

func (*CredHub) SetSSH

func (ch *CredHub) SetSSH(name string, value values.SSH, options ...SetOption) (credentials.SSH, error)

SetSSH sets an SSH credential with a user-provided value.

func (*CredHub) SetUser

func (ch *CredHub) SetUser(name string, value values.User, options ...SetOption) (credentials.User, error)

SetUser sets a user credential with a user-provided value.

func (*CredHub) SetValue

func (ch *CredHub) SetValue(name string, value values.Value, options ...SetOption) (credentials.Value, error)

SetValue sets a value credential with a user-provided value.

func (*CredHub) UpdatePermission

func (ch *CredHub) UpdatePermission(uuid string, path string, actor string, ops []string) (*permissions.Permission, error)

type DialFunc

type DialFunc func(network, address string) (net.Conn, error)

func SOCKS5DialFuncFromEnvironment

func SOCKS5DialFuncFromEnvironment(origDialer DialFunc, socks5Proxy ProxyDialer) DialFunc

func (DialFunc) Dial

func (f DialFunc) Dial(network, address string) (net.Conn, error)

type Error

type Error struct {
	Name        string `json:"error"`
	Description string `json:"error_description"`
}

Error provides errors for the CredHub client

func (*Error) Error

func (e *Error) Error() string

type GenerateOption

type GenerateOption func(*GenerateOptions) error

type GenerateOptions

type GenerateOptions struct {
	Metadata credentials.Metadata `json:"metadata,omitempty"`
}

type Mode

type Mode string
const (
	Overwrite   Mode = "overwrite"
	NoOverwrite Mode = "no-overwrite"
	Converge    Mode = "converge"
)

type NotFoundError

type NotFoundError struct {
	Description string `json:"error"`
}

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type Option

type Option func(*CredHub) error

Option can be provided to New() to specify additional parameters for connecting to the CredHub server

func Auth

func Auth(method auth.Builder) Option

Auth specifies the authentication Strategy. See the auth package for a full list of supported strategies.

func AuthURL

func AuthURL(authURL string) Option

AuthURL specifies the authentication server for the OAuth strategy. If AuthURL provided, the AuthURL will be fetched from /info.

func CaCerts

func CaCerts(certs ...string) Option

CaCerts specifies the root certificates for HTTPS connections with the CredHub server.

If the OAuthStrategy is used for Auth, the root certificates will also be used for HTTPS connections with the OAuth server.

func ClientCert

func ClientCert(certificate, key string) Option

ClientCert will use a certificate for authentication

func ServerVersion

func ServerVersion(version string) Option

func SetHttpTimeout

func SetHttpTimeout(timeout *time.Duration) Option

SetHttpTimeout will set the timeout for the CredHub client

func SkipTLSValidation

func SkipTLSValidation(skipTLSvalidation bool) Option

SkipTLSValidation will skip root certificate verification for HTTPS. Not recommended!

type ProxyDialer

type ProxyDialer interface {
	Dialer(string, string, string) (proxy.DialFunc, error)
}

type RegenerateOption

type RegenerateOption func(options *RegenerateOptions) error

type RegenerateOptions

type RegenerateOptions struct {
	Metadata credentials.Metadata `json:"metadata,omitempty"`
}

type SetOption

type SetOption func(*SetOptions) error

Option can be provided to New() to specify additional parameters for connecting to the CredHub server

type SetOptions

type SetOptions struct {
	Metadata credentials.Metadata `json:"metadata,omitempty"`
}

Directories

Path Synopsis
CredHub authentication strategies
CredHub authentication strategies
uaa
UAA client for token grants and revocation
UAA client for token grants and revocation
CredHub credential types
CredHub credential types
generate
CredHub credential types for generating credentials
CredHub credential types for generating credentials
values
CredHub credential value types
CredHub credential value types
CredHub permission types
CredHub permission types
CredHub server types
CredHub server types

Jump to

Keyboard shortcuts

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