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 http://credhub-api.cfapps.io
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 ¶
- type CredHub
- func (ch *CredHub) AddPermission(path string, actor string, ops []string) (*permissions.Permission, error)
- func (ch *CredHub) AuthURL() (string, error)
- func (ch *CredHub) BulkRegenerate(signedBy string) (credentials.BulkRegenerateResults, error)
- func (ch *CredHub) Client() *http.Client
- func (ch *CredHub) Delete(name string) error
- func (ch *CredHub) DeletePermission(uuid string) (*permissions.Permission, error)
- func (ch *CredHub) FindByPartialName(nameLike string) (credentials.FindResults, error)
- func (ch *CredHub) FindByPath(path string) (credentials.FindResults, error)
- func (ch *CredHub) GenerateCertificate(name string, gen generate.Certificate, overwrite Mode) (credentials.Certificate, error)
- func (ch *CredHub) GenerateCredential(name, credType string, gen interface{}, overwrite Mode) (credentials.Credential, error)
- func (ch *CredHub) GeneratePassword(name string, gen generate.Password, overwrite Mode) (credentials.Password, error)
- func (ch *CredHub) GenerateRSA(name string, gen generate.RSA, overwrite Mode) (credentials.RSA, error)
- func (ch *CredHub) GenerateSSH(name string, gen generate.SSH, overwrite Mode) (credentials.SSH, error)
- func (ch *CredHub) GenerateUser(name string, gen generate.User, overwrite Mode) (credentials.User, error)
- func (ch *CredHub) GetAllCertificatesMetadata() ([]credentials.CertificateMetadata, error)
- func (ch *CredHub) GetAllVersions(name string) ([]credentials.Credential, error)
- func (ch *CredHub) GetById(id string) (credentials.Credential, error)
- func (ch *CredHub) GetLatestCertificate(name string) (credentials.Certificate, error)
- func (ch *CredHub) GetLatestJSON(name string) (credentials.JSON, error)
- func (ch *CredHub) GetLatestPassword(name string) (credentials.Password, error)
- func (ch *CredHub) GetLatestRSA(name string) (credentials.RSA, error)
- func (ch *CredHub) GetLatestSSH(name string) (credentials.SSH, error)
- func (ch *CredHub) GetLatestUser(name string) (credentials.User, error)
- func (ch *CredHub) GetLatestValue(name string) (credentials.Value, error)
- func (ch *CredHub) GetLatestVersion(name string) (credentials.Credential, error)
- func (ch *CredHub) GetNVersions(name string, numberOfVersions int) ([]credentials.Credential, error)
- func (ch *CredHub) GetPermissionByPathActor(path string, actor string) (*permissions.Permission, error)
- func (ch *CredHub) GetPermissionByUUID(uuid string) (*permissions.Permission, error)
- func (ch *CredHub) GetPermissions(name string) ([]permissions.V1_Permission, error)
- func (ch *CredHub) Info() (*server.Info, error)
- func (ch *CredHub) InterpolateString(vcapServicesBody string) (string, error)
- func (ch *CredHub) Regenerate(name string) (credentials.Credential, error)
- func (ch *CredHub) Request(method string, pathStr string, query url.Values, body interface{}, ...) (*http.Response, error)
- func (ch *CredHub) ServerVersion() (*version.Version, error)
- func (ch *CredHub) SetCertificate(name string, value values.Certificate) (credentials.Certificate, error)
- func (ch *CredHub) SetCredential(name, credType string, value interface{}) (credentials.Credential, error)
- func (ch *CredHub) SetJSON(name string, value values.JSON) (credentials.JSON, error)
- func (ch *CredHub) SetPassword(name string, value values.Password) (credentials.Password, error)
- func (ch *CredHub) SetRSA(name string, value values.RSA) (credentials.RSA, error)
- func (ch *CredHub) SetSSH(name string, value values.SSH) (credentials.SSH, error)
- func (ch *CredHub) SetUser(name string, value values.User) (credentials.User, error)
- func (ch *CredHub) SetValue(name string, value values.Value) (credentials.Value, error)
- func (ch *CredHub) UpdatePermission(uuid string, path string, actor string, ops []string) (*permissions.Permission, error)
- type DialFunc
- type Error
- type Mode
- type NotFoundError
- type Option
- type ProxyDialer
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" "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 ¶
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 ¶
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) 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) (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) 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) InterpolateString ¶
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{}, 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 (*CredHub) SetCertificate ¶
func (ch *CredHub) SetCertificate(name string, value values.Certificate) (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{}) (credentials.Credential, error)
SetCredential sets a credential of any type with a user-provided value.
func (*CredHub) SetPassword ¶
SetPassword sets a password 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 ¶
func SOCKS5DialFuncFromEnvironment ¶
func SOCKS5DialFuncFromEnvironment(origDialer DialFunc, socks5Proxy ProxyDialer) DialFunc
type NotFoundError ¶
type NotFoundError struct {
Description string `json:"error"`
}
func (*NotFoundError) Error ¶
func (e *NotFoundError) Error() string
type Option ¶
Option can be provided to New() to specify additional parameters for connecting to the CredHub server
func Auth ¶
Auth specifies the authentication Strategy. See the auth package for a full list of supported strategies.
func AuthURL ¶
AuthURL specifies the authentication server for the OAuth strategy. If AuthURL provided, the AuthURL will be fetched from /info.
func CaCerts ¶
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 ¶
ClientCert will use a certificate for authentication
func ServerVersion ¶
func SkipTLSValidation ¶
SkipTLSValidation will skip root certificate verification for HTTPS. Not recommended!
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 |