credhub

package
v0.0.0-...-08dc844 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2017 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

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

More information on CredHub can be found at https://github.com/cloudfoundry-incubator/credhub

Server HTTP API specification can be found at http://credhub-api.cfapps.io

Example 
package main

import (
	"fmt"

	"github.com/cloudfoundry-incubator/credhub-cli/credhub"
	"github.com/cloudfoundry-incubator/credhub-cli/credhub/auth"
	"github.com/cloudfoundry-incubator/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, credhub.NoOverwrite)
		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

This section is empty.

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"

	"github.com/cloudfoundry-incubator/credhub-cli/credhub"
	"github.com/cloudfoundry-incubator/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"

	"github.com/cloudfoundry-incubator/credhub-cli/credhub"
	"github.com/cloudfoundry-incubator/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) AddPermissions 

func (ch *CredHub) AddPermissions(credName string, perms []permissions.Permission) ([]permissions.Permission, error)

AddPermissions adds permissions to a credential.

func (*CredHub) AuthURL 

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

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

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) DeletePermissions 

func (ch *CredHub) DeletePermissions(credName string, actor string) error

DeletePermissions deletes permissions on a credential by actor.

func (*CredHub) FindAllPaths 

func (ch *CredHub) FindAllPaths() (credentials.Paths, error)

FindAllPaths retrieves a list of all paths which contain credentials.

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) (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) 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) 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) GetPermissions 

func (ch *CredHub) GetPermissions(credName string) ([]permissions.Permission, error)

GetPermissions returns the permissions of a credential.

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) (credentials.Credential, error)

Regenerate generates and returns a new credential version using the same parameters 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{}) (*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"

	"github.com/cloudfoundry-incubator/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)
		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, overwrite Mode) (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{}, overwrite Mode) (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, overwrite Mode) (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, overwrite Mode) (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, overwrite Mode) (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, overwrite Mode) (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, overwrite Mode) (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, overwrite Mode) (credentials.Value, error)

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

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 Mode 

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

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(serverVersion string) Option

ServerVersion will set the version of server API to use (e.g. "1.2.3")

func SkipTLSValidation 

func SkipTLSValidation(skipTLSvalidation bool) Option

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

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.