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