README
¶
tlsconfig
tlsconfig generates shared crypto/tls configurations for internal and external-facing services in Cloud Foundry. This module is considered internal to Cloud Foundry, and does not provide any stability guarantees for external usage.
Getting Started
Usage
Import this module as code.cloudfoundry.org/tlsconfig.
Update to the latest version of the library off the main branch with:
go get -u code.cloudfoundry.org/tlsconfig@main
Running the tests
All the tests use the standard go testing library and can be run with:
go test ./...
Contributing
Cloud Foundry uses GitHub to manage reviews of pull requests and issues.
- If you have a trivial fix or improvement, go ahead and create a pull request.
- If you plan to do something more involved, first discuss your ideas in Slack. This will help avoid unnecessary work :).
- Make sure you've signed the CLA!
Versioning
This module is not currently versioned. Whatever is on the main branch is considered to be the latest release of the module.
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package tlsconfig provides opintionated helpers for building tls.Configs. It keeps up to date with internal CloudFoundry best practices and external industry best practices.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClientOption ¶
ClientOption can be used to configure a TLS configuration for a client.
func WithAuthority ¶
func WithAuthority(authority *x509.CertPool) ClientOption
WithAuthority makes the client verify that the server presents an identity that can be validated by the certificate pool provided.
func WithAuthorityBuilder ¶
func WithAuthorityBuilder(builder PoolBuilder) ClientOption
WithAuthorityBuilder uses the passed PoolBuilder to create the certificate pool to use as the authority.
func WithAuthorityFromFile ¶
func WithAuthorityFromFile(caPath string) ClientOption
WithAuthorityFromFile makes the client verify that the server presents an identity that can be validated by the CA file provided.
func WithServerName ¶
func WithServerName(name string) ClientOption
WithServerName makes the client verify that the server name in the certificate presented by the server.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config represents a half configured TLS configuration. It can be made usable by calling either of its two methods.
func (Config) Client ¶
func (c Config) Client(opts ...ClientOption) (*tls.Config, error)
Client can be used to build a TLS configuration suitable for clients (GRPC, HTTP, etc.). The options are applied in order. It is possible for a later option to undo the configuration that an earlier one applied. Care must be taken.
func (Config) Server ¶
func (c Config) Server(opts ...ServerOption) (*tls.Config, error)
Server can be used to build a TLS configuration suitable for servers (GRPC, HTTP, etc.). The options are applied in order. It is possible for a later option to undo the configuration that an earlier one applied. Care must be taken.
type PoolBuilder ¶
type PoolBuilder struct {
// contains filtered or unexported fields
}
PoolBuilder is used to build a certificate pool. You normally won't need to Build this yourself and instead should use the WithAuthorityBuilder and WithClientAuthenticationBuilder functions.
func FromEmptyPool ¶
func FromEmptyPool(opts ...PoolOption) PoolBuilder
FromEmptyPool creates a PoolBuilder from an empty certificate pool. The options passed can amend the returned pool.
func FromSystemPool ¶
func FromSystemPool(opts ...PoolOption) PoolBuilder
FromSystemPool creates a PoolBuilder from the system's certificate pool. The options passed can amend the returned pool.
type PoolOption ¶
PoolOption is an functional option type that can be used to configure a certificate pool.
func WithCert ¶
func WithCert(cert *x509.Certificate) PoolOption
WithCert will add the certificate directly to a certificate pool.
func WithCertsFromFile ¶
func WithCertsFromFile(path string) PoolOption
WithCertsFromFile will add all of the certificates found in a PEM-encoded file to a certificate pool.
type ServerOption ¶
ServerOption can be used to configure a TLS configuration for a server.
func WithClientAuthentication ¶
func WithClientAuthentication(authority *x509.CertPool) ServerOption
WithClientAuthentication makes the server verify that all clients present an identity that can be validated by the certificate pool provided.
func WithClientAuthenticationBuilder ¶
func WithClientAuthenticationBuilder(builder PoolBuilder) ServerOption
WithClientAuthenticationBuilder uses the passed PoolBuilder to create the certificate pool to use as the authority when verifying client certificates.
func WithClientAuthenticationFromFile ¶
func WithClientAuthenticationFromFile(caPath string) ServerOption
WithClientAuthenticationFromFile makes the server verify that all clients present an identity that can be validated by the CA file provided.
type TLSOption ¶
TLSOption can be used to configure a TLS configuration for both clients and servers.
func WithExternalServiceDefaults ¶
func WithExternalServiceDefaults() TLSOption
WithExternalServiceDefaults modifies a *tls.Config that is suitable for use in communication between clients and servers where we do not control one end of the connection. It is less strict than the WithInternalServiceDefaults helper.
The standards here are taken from the Mozilla SSL configuration generator set to "Intermediate" on Dec 19, 2019.
func WithIdentity ¶
func WithIdentity(cert tls.Certificate) TLSOption
WithIdentity sets the identity of the server or client which will be presented to its peer upon connection.
func WithIdentityFromFile ¶
WithIdentityFromFile sets the identity of the server or client which will be presented to its peer upon connection from provided cert and key files.
func WithInternalServiceDefaults ¶
func WithInternalServiceDefaults() TLSOption
WithInternalServiceDefaults modifies a *tls.Config that is suitable for use in communication links between internal services. It is not guaranteed to be suitable for communication to other external services as it contains a strict definition of acceptable standards.
The standards were taken from the "Consolidated Remarks" internal document from Pivotal. The one exception to this is the use of the P256 curve in order to support gRPC clients which hardcode this configuration.
Note: Due to the aggressive nature of the ciphersuites chosen here (they do not support any ECC signing) it is not possible to use ECC keys with this option.
Source Files
Directories