certificates: github.com/smallstep/certificates/ca Index | Files

package ca

import "github.com/smallstep/certificates/ca"

Index

Package Files

bootstrap.go ca.go client.go mutable_tls_config.go renew.go signal.go tls.go tls_options.go

func BootstrapClient Uses

func BootstrapClient(ctx context.Context, token string, options ...TLSOption) (*http.Client, error)

BootstrapClient is a helper function that using the given bootstrap token return an http.Client configured with a Transport prepared to do TLS connections using the client certificate returned by the certificate authority. By default the server will kick off a routine that will renew the certificate after 2/3rd of the certificate's lifetime has expired.

Usage:

// Default example with certificate rotation.
client, err := ca.BootstrapClient(ctx.Background(), token)

// Example canceling automatic certificate rotation.
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
client, err := ca.BootstrapClient(ctx, token)
if err != nil {
  return err
}
resp, err := client.Get("https://internal.smallstep.com")

func BootstrapListener Uses

func BootstrapListener(ctx context.Context, token string, inner net.Listener, options ...TLSOption) (net.Listener, error)

BootstrapListener is a helper function that using the given token returns a TLS listener which accepts connections from an inner listener and wraps each connection with Server.

Without any extra option the server will be configured for mTLS, it will require and verify clients certificates, but options can be used to drop this requirement, the most common will be only verify the certs if given with ca.VerifyClientCertIfGiven(), or add extra CAs with ca.AddClientCA(*x509.Certificate).

Usage:

inner, err := net.Listen("tcp", ":443")
if err != nil {
  return nil
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
lis, err := ca.BootstrapListener(ctx, token, inner)
if err != nil {
    return err
}
srv := grpc.NewServer()
... // register services
srv.Serve(lis)

func BootstrapServer Uses

func BootstrapServer(ctx context.Context, token string, base *http.Server, options ...TLSOption) (*http.Server, error)

BootstrapServer is a helper function that using the given token returns the given http.Server configured with a TLS certificate signed by the Certificate Authority. By default the server will kick off a routine that will renew the certificate after 2/3rd of the certificate's lifetime has expired.

Without any extra option the server will be configured for mTLS, it will require and verify clients certificates, but options can be used to drop this requirement, the most common will be only verify the certs if given with ca.VerifyClientCertIfGiven(), or add extra CAs with ca.AddClientCA(*x509.Certificate).

Usage:

// Default example with certificate rotation.
srv, err := ca.BootstrapServer(context.Background(), token, &http.Server{
    Addr: ":443",
    Handler: handler,
})

// Example canceling automatic certificate rotation.
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
srv, err := ca.BootstrapServer(ctx, token, &http.Server{
    Addr: ":443",
    Handler: handler,
})
if err != nil {
    return err
}
srv.ListenAndServeTLS("", "")

func Certificate Uses

func Certificate(sign *api.SignResponse) (*x509.Certificate, error)

Certificate returns the server or client certificate from the sign response.

func CreateSignRequest Uses

func CreateSignRequest(ott string) (*api.SignRequest, crypto.PrivateKey, error)

CreateSignRequest is a helper function that given an x509 OTT returns a simple but secure sign request as well as the private key used.

func IntermediateCertificate Uses

func IntermediateCertificate(sign *api.SignResponse) (*x509.Certificate, error)

IntermediateCertificate returns the CA intermediate certificate from the sign response.

func RootCertificate Uses

func RootCertificate(sign *api.SignResponse) (*x509.Certificate, error)

RootCertificate returns the root certificate from the sign response.

func StopReloaderHandler Uses

func StopReloaderHandler(servers ...StopReloader)

StopReloaderHandler watches SIGINT, SIGTERM and SIGHUP on a list of servers implementing the StopReloader interface, and when one of those signals is caught we'll run Stop (SIGINT, SIGTERM) or Reload (SIGHUP) on all servers.

func TLSCertificate Uses

func TLSCertificate(sign *api.SignResponse, pk crypto.PrivateKey) (*tls.Certificate, error)

TLSCertificate creates a new TLS certificate from the sign response and the private key used.

func WithRenewBefore Uses

func WithRenewBefore(b time.Duration) func(r *TLSRenewer) error

WithRenewBefore modifies a tlsRenewer by setting the renewBefore attribute.

func WithRenewJitter Uses

func WithRenewJitter(j time.Duration) func(r *TLSRenewer) error

WithRenewJitter modifies a tlsRenewer by setting the renewJitter attribute.

type CA Uses

type CA struct {
    // contains filtered or unexported fields
}

CA is the type used to build the complete certificate authority. It builds the HTTP server, set ups the middlewares and the HTTP handlers.

func New Uses

func New(config *authority.Config, opts ...Option) (*CA, error)

New creates and initializes the CA with the given configuration and options.

func (*CA) Init Uses

func (ca *CA) Init(config *authority.Config) (*CA, error)

Init initializes the CA with the given configuration.

func (*CA) Reload Uses

func (ca *CA) Reload() error

Reload reloads the configuration of the CA and calls to the server Reload method.

func (*CA) Run Uses

func (ca *CA) Run() error

Run starts the CA calling to the server ListenAndServe method.

func (*CA) Stop Uses

func (ca *CA) Stop() error

Stop stops the CA calling to the server Shutdown method.

type Client Uses

type Client struct {
    // contains filtered or unexported fields
}

Client implements an HTTP client for the CA server.

func Bootstrap Uses

func Bootstrap(token string) (*Client, error)

Bootstrap is a helper function that initializes a client with the configuration in the bootstrap token.

func NewClient Uses

func NewClient(endpoint string, opts ...ClientOption) (*Client, error)

NewClient creates a new Client with the given endpoint and options.

func (*Client) Federation Uses

func (c *Client) Federation() (*api.FederationResponse, error)

Federation performs the get federation request to the CA and returns the api.FederationResponse struct.

func (*Client) GetClientTLSConfig Uses

func (c *Client) GetClientTLSConfig(ctx context.Context, sign *api.SignResponse, pk crypto.PrivateKey, options ...TLSOption) (*tls.Config, error)

GetClientTLSConfig returns a tls.Config for client use configured with the sign certificate, and a new certificate pool with the sign root certificate. The client certificate will automatically rotate before expiring.

func (*Client) GetServerTLSConfig Uses

func (c *Client) GetServerTLSConfig(ctx context.Context, sign *api.SignResponse, pk crypto.PrivateKey, options ...TLSOption) (*tls.Config, error)

GetServerTLSConfig returns a tls.Config for server use configured with the sign certificate, and a new certificate pool with the sign root certificate. The returned tls.Config will only verify the client certificate if provided. The server certificate will automatically rotate before expiring.

func (*Client) Health Uses

func (c *Client) Health() (*api.HealthResponse, error)

Health performs the health request to the CA and returns the api.HealthResponse struct.

func (*Client) ProvisionerKey Uses

func (c *Client) ProvisionerKey(kid string) (*api.ProvisionerKeyResponse, error)

ProvisionerKey performs the request to the CA to get the encrypted key for the given provisioner kid and returns the api.ProvisionerKeyResponse struct with the encrypted key.

func (*Client) Provisioners Uses

func (c *Client) Provisioners(opts ...ProvisionerOption) (*api.ProvisionersResponse, error)

Provisioners performs the provisioners request to the CA and returns the api.ProvisionersResponse struct with a map of provisioners.

ProvisionerOption WithProvisionerCursor and WithProvisionLimit can be used to paginate the provisioners.

func (*Client) Renew Uses

func (c *Client) Renew(tr http.RoundTripper) (*api.SignResponse, error)

Renew performs the renew request to the CA and returns the api.SignResponse struct.

func (*Client) Root Uses

func (c *Client) Root(sha256Sum string) (*api.RootResponse, error)

Root performs the root request to the CA with the given SHA256 and returns the api.RootResponse struct. It uses an insecure client, but it checks the resulting root certificate with the given SHA256, returning an error if they do not match.

func (*Client) Roots Uses

func (c *Client) Roots() (*api.RootsResponse, error)

Roots performs the get roots request to the CA and returns the api.RootsResponse struct.

func (*Client) Sign Uses

func (c *Client) Sign(req *api.SignRequest) (*api.SignResponse, error)

Sign performs the sign request to the CA and returns the api.SignResponse struct.

func (*Client) Transport Uses

func (c *Client) Transport(ctx context.Context, sign *api.SignResponse, pk crypto.PrivateKey, options ...TLSOption) (*http.Transport, error)

Transport returns an http.Transport configured to use the client certificate from the sign response.

type ClientOption Uses

type ClientOption func(o *clientOptions) error

ClientOption is the type of options passed to the Client constructor.

func WithRootFile Uses

func WithRootFile(filename string) ClientOption

WithRootFile will create the transport using the given root certificate. If the root file is given it will have preference over WithRootSHA256, but less preference than WithTransport.

func WithRootSHA256 Uses

func WithRootSHA256(sum string) ClientOption

WithRootSHA256 will create the transport using an insecure client to retrieve the root certificate. It has less preference than WithTransport and WithRootFile.

func WithTransport Uses

func WithTransport(tr http.RoundTripper) ClientOption

WithTransport adds a custom transport to the Client. If the transport is given is given it will have preference over WithRootFile and WithRootSHA256.

type Option Uses

type Option func(o *options)

Option is the type of options passed to the CA constructor.

func WithConfigFile Uses

func WithConfigFile(name string) Option

WithConfigFile sets the given name as the configuration file name in the CA options.

func WithPassword Uses

func WithPassword(password []byte) Option

WithPassword sets the given password as the configured password in the CA options.

type ProvisionerOption Uses

type ProvisionerOption func(o *provisionerOptions) error

ProvisionerOption is the type of options passed to the Provisioner method.

func WithProvisionerCursor Uses

func WithProvisionerCursor(cursor string) ProvisionerOption

WithProvisionerCursor will request the provisioners starting with the given cursor.

func WithProvisionerLimit Uses

func WithProvisionerLimit(limit int) ProvisionerOption

WithProvisionerLimit will request the given number of provisioners.

type RenewFunc Uses

type RenewFunc func() (*tls.Certificate, error)

RenewFunc defines the type of the functions used to get a new tls certificate.

type StopReloader Uses

type StopReloader interface {
    Stop() error
    Reload() error
}

StopReloader is the interface that external commands can implement to stop the server and reload the configuration while running.

type TLSOption Uses

type TLSOption func(ctx *TLSOptionCtx) error

TLSOption defines the type of a function that modifies a tls.Config.

func AddClientCA Uses

func AddClientCA(cert *x509.Certificate) TLSOption

AddClientCA adds to the tls.Config ClientCAs the given certificate. ClientCAs defines the set of root certificate authorities that servers use if required to verify a client certificate by the policy in ClientAuth.

func AddFederationToCAs Uses

func AddFederationToCAs() TLSOption

AddFederationToCAs does a federation request and adds the resulting certs to the tls.Config RootCAs and ClientCAs. Combines the functionality of AddFederationToRootCAs and AddFederationToClientCAs.

func AddFederationToClientCAs Uses

func AddFederationToClientCAs() TLSOption

AddFederationToClientCAs does a federation request and adds to the tls.Config ClientCAs all the certificates in the response. ClientCAs defines the set of root certificate authorities that servers use if required to verify a client certificate by the policy in ClientAuth.

func AddFederationToRootCAs Uses

func AddFederationToRootCAs() TLSOption

AddFederationToRootCAs does a federation request and adds to the tls.Config RootCAs all the certificates in the response. RootCAs defines the set of root certificate authorities that clients use when verifying server certificates.

func AddRootCA Uses

func AddRootCA(cert *x509.Certificate) TLSOption

AddRootCA adds to the tls.Config RootCAs the given certificate. RootCAs defines the set of root certificate authorities that clients use when verifying server certificates.

func AddRootsToCAs Uses

func AddRootsToCAs() TLSOption

AddRootsToCAs does a roots request and adds the resulting certs to the tls.Config RootCAs and ClientCAs. Combines the functionality of AddRootsToRootCAs and AddRootsToClientCAs.

func AddRootsToClientCAs Uses

func AddRootsToClientCAs() TLSOption

AddRootsToClientCAs does a roots request and adds to the tls.Config ClientCAs all the certificates in the response. ClientCAs defines the set of root certificate authorities that servers use if required to verify a client certificate by the policy in ClientAuth.

BootstrapServer method includes this option by default.

func AddRootsToRootCAs Uses

func AddRootsToRootCAs() TLSOption

AddRootsToRootCAs does a roots request and adds to the tls.Config RootCAs all the certificates in the response. RootCAs defines the set of root certificate authorities that clients use when verifying server certificates.

BootstrapServer and BootstrapClient methods include this option by default.

func RequireAndVerifyClientCert Uses

func RequireAndVerifyClientCert() TLSOption

RequireAndVerifyClientCert is a tls.Config option used on servers to enforce a valid TLS client certificate. This is the default option for mTLS servers.

func VerifyClientCertIfGiven Uses

func VerifyClientCertIfGiven() TLSOption

VerifyClientCertIfGiven is a tls.Config option used on on servers to validate a TLS client certificate if it is provided. It does not requires a certificate.

type TLSOptionCtx Uses

type TLSOptionCtx struct {
    Client      *Client
    Config      *tls.Config
    Sign        *api.SignResponse
    OnRenewFunc []TLSOption
    // contains filtered or unexported fields
}

TLSOptionCtx is the context modified on TLSOption methods.

type TLSRenewer Uses

type TLSRenewer struct {
    sync.RWMutex
    RenewCertificate RenewFunc
    // contains filtered or unexported fields
}

TLSRenewer automatically renews a tls certificate using a RenewFunc.

func NewTLSRenewer Uses

func NewTLSRenewer(cert *tls.Certificate, fn RenewFunc, opts ...tlsRenewerOptions) (*TLSRenewer, error)

NewTLSRenewer creates a TLSRenewer for the given cert. It will use the given RenewFunc to get a new certificate when required.

func (*TLSRenewer) GetCertificate Uses

func (r *TLSRenewer) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate returns the current server certificate.

This method is set in the tls.Config GetCertificate property.

func (*TLSRenewer) GetCertificateForCA Uses

func (r *TLSRenewer) GetCertificateForCA(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificateForCA returns the current server certificate. It can only be used if the renew function creates the new certificate and do not uses a TLS request. It's intended to be use by the certificate authority server.

This method is set in the tls.Config GetCertificate property.

func (*TLSRenewer) GetClientCertificate Uses

func (r *TLSRenewer) GetClientCertificate(*tls.CertificateRequestInfo) (*tls.Certificate, error)

GetClientCertificate returns the current client certificate.

This method is set in the tls.Config GetClientCertificate property.

func (*TLSRenewer) Run Uses

func (r *TLSRenewer) Run()

Run starts the certificate renewer for the given certificate.

func (*TLSRenewer) RunContext Uses

func (r *TLSRenewer) RunContext(ctx context.Context)

RunContext starts the certificate renewer for the given certificate.

func (*TLSRenewer) Stop Uses

func (r *TLSRenewer) Stop() bool

Stop prevents the renew timer from firing.

Package ca imports 39 packages (graph) and is imported by 2 packages. Updated 2019-02-08. Refresh now. Tools for package owners.