credhub

package
v0.0.0-...-907ed54 Latest Latest
Warning

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

 Go to latest Published: Sep 6, 2024 License: Apache-2.0 Imports: 26 Imported by: 61

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"`
}

Source Files

View all Source files

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