trust

package
v1.4.1 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2024 License: MIT Imports: 14 Imported by: 20

Documentation

Overview

Package trust provides support for handling PEM-encoded certificate chains. Its primary functionality is a trust Provider that manages a single chain (either public or public and private). A ProviderPool manages only public chains and is used to facilitate mTLS exchanges. This package also includes certificate serialization management and helpers, including compression utilities.

Index

Constants

View Source 
const (
	BlockPublicKey          = "PUBLIC KEY"
	BlockPrivateKey         = "PRIVATE KEY"
	BlockRSAPublicKey       = "RSA PUBLIC KEY"
	BlockRSAPrivateKey      = "RSA PRIVATE KEY"
	BlockECPrivateKey       = "EC PRIVATE KEY"
	BlockCertificate        = "CERTIFICATE"
	BlockCertificateRequest = "CERTIFICATE REQUEST"
)

PEM Block types

View Source 
const (
	CompressionGZIP = ".gz"
	CompressionZIP  = ".zip"
	CompressionNone = ".pem"
	CompressionAuto = "auto"
)

Compression

Variables

View Source 
var (
	ErrDecodePrivateKey  = errors.New("could not decode PEM private key")
	ErrDecodePublicKey   = errors.New("could not decode PEM public key")
	ErrDecodeCertificate = errors.New("could not decode PEM certificate")
	ErrDecodeCSR         = errors.New("could not decode PEM certificate request")
	ErrNoCertificates    = errors.New("provider does not contain any certificates")
	ErrKeyRequired       = errors.New("private key required")
	ErrZipEmpty          = errors.New("zip archive contains no providers")
	ErrZipTooMany        = errors.New("multiple providers in zip, is this a provider pool?")
)

Standard errors for error type checking

Functions

func PEMDecodeCSR 

func PEMDecodeCSR(in []byte) (*x509.CertificateRequest, error)

PEMDecodeCSR from PEM encoded block with type "CERTIFICATE REQUEST"

func PEMDecodeCertificate 

func PEMDecodeCertificate(in []byte) (*x509.Certificate, error)

PEMDecodeCertificate from PEM encoded block with type "CERTIFICATE"

func PEMDecodePrivateKey 

func PEMDecodePrivateKey(in []byte) (interface{}, error)

PEMDecodePrivateKey from a PEM encoded block. If the block type is "EC PRIVATE KEY", then the block is parsed as an EC private key in SEC 1, ASN.1 DER form. If the block is "RSA PRIVATE KEY" then it is decoded as a PKCS 1, ASN.1 DER form. If the block type is "PRIVATE KEY", the block is decoded as a PKCS 8 ASN.1 DER key, if that fails, then the PKCS 1 and EC parsers are tried in that order, before returning an error.

func PEMDecodePublicKey added in v0.3.3 

func PEMDecodePublicKey(in []byte) (interface{}, error)

PEMDecodePublicKey from a PEM encoded block. If the block type is "RSA PUBLIC KEY", then it is deocded as a PKCS 1, ASN.1 DER form. If the block is "PUBLIC KEY", then it is decoded from PKIX ASN1.1 DER form.

func PEMEncodeCSR 

func PEMEncodeCSR(c *x509.CertificateRequest) ([]byte, error)

PEMEncodeCSR and write a PEM block with type "CERTIFICATE REQUEST"

func PEMEncodeCertificate 

func PEMEncodeCertificate(c *x509.Certificate) ([]byte, error)

PEMEncodeCertificate and write a PEM block with type "CERTIFICATE"

func PEMEncodePrivateKey 

func PEMEncodePrivateKey(key interface{}) ([]byte, error)

PEMEncodePrivateKey as a PKCS8 ASN.1 DER key and write a PEM block with type "PRIVATE KEY"

func PEMEncodePublicKey added in v0.3.3 

func PEMEncodePublicKey(key interface{}) ([]byte, error)

PEMEncodePublicKey as a PKIX ASN1.1 DER key and write a PEM block with type "PUBLIC KEY"

func ParsePrivateKey added in v0.3.3 

func ParsePrivateKey(block *pem.Block) (interface{}, error)

ParsePrivateKey from PEM block. May return an *ecdsa.PrivateKey, *rsa.PrivateKey, or ed25519.PrivateKey depending on the block type and the x509 parsing method.

Types

type Provider 

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

Provider wraps a PEM-encoded certificate chain, which can optionally include private keys. Providers with keys (private providers) are used to instantiate mTLS servers, while public Providers are used in ProviderPools to facilitate mTLS clients.

func Decrypt 

func Decrypt(pfxData []byte, password string) (p *Provider, err error)

Decrypt pfxData from a PKCS12 encoded file using the specified password. The data must contain at least one certificate and only one private key. The first certificate in the data is assumed to be the leaf certificate and subsequent certificates are the CA chain. Certificates are appended to the provider leaf first, then CA chain.

func New 

func New(chain []byte) (p *Provider, err error)

New creates a Provider from PEM encoded blocks.

func (*Provider) Decode 

func (p *Provider) Decode(in []byte) (err error)

Decode PEM blocks and adds them to the provider. Certificates are appended to the Provider chain and Private Keys are Unmarshalled from PKCS8. All other block types return an error and stop processing the block or chain. Only the private key is verified for correctness, certificates are unvalidated.

func (*Provider) Encode 

func (p *Provider) Encode() (_ []byte, err error)

Encode Provider in PCKS12 PEM format for serialization. Certificates are written to the array first. If the private key exists, it is written as the last PEM block.

func (*Provider) Encrypt 

func (p *Provider) Encrypt(password string) (pfxData []byte, err error)

Encrypt Provider as pfxData containing a private key, the end-entity certificate as the leaf certificate, and the rest of the chain as CA certificates. The private key is encrypted with the provided password, however, because of the weak encryption primitives used by PKCS#12, it is strongly recommended that a hardcoded password (such as pkcs12.DefaultPassword) is specified and the pfxData is protected using other means. See the software.sslmate.com go-pkcs12 package for more details.

This method will return an error if the private key is nil, if there are no certificates stored on the provider, or if the certs cannot be parsed as x509 certs.

func (*Provider) GetCertPool 

func (p *Provider) GetCertPool() (_ *x509.CertPool, err error)

GetCertPool returns the x509.CertPool certificate set representing the root, intermediate, and leaf certificates of the Provider. This pool is provider-specific and does not include system certificates.

func (*Provider) GetKey 

func (p *Provider) GetKey() interface{}

GetKey returns the private key, or nil if this is a public provider.

func (*Provider) GetKeyPair 

func (p *Provider) GetKeyPair() (_ tls.Certificate, err error)

GetKeyPair returns a tls.Certificate parsed from the PEM encoded data maintained by the provider. This method uses tls.X509KeyPair to ensure that the public/private key pair are suitable for use with an HTTP Server.

func (*Provider) GetLeafCertificate 

func (p *Provider) GetLeafCertificate() (*x509.Certificate, error)

GetLeafCertificate returns the parsed x509 leaf certificate if it exists, returning an error if there are no certificates or if there is a parse error.

func (*Provider) GetRSAKeys 

func (p *Provider) GetRSAKeys() (key *rsa.PrivateKey, err error)

GetRSAKeys returns a fully constructed RSA PrivateKey that includes the public key material property. This method errors if the key is not an RSA key or does not exist.

func (*Provider) IsPrivate 

func (p *Provider) IsPrivate() bool

IsPrivate returns true if the Provider contains a non-nil key.

func (*Provider) Public 

func (p *Provider) Public() *Provider

Public returns a Provider without the key. If the Provider is already public, then the pointer to the same Provider is returned (does not clone).

func (*Provider) String 

func (p *Provider) String() string

String returns the common name of the Provider from the leaf certificate.

type ProviderPool 

type ProviderPool map[string]*Provider

ProviderPool is a collection of provider objects, used to collectively manage the public trust certificates of peers in the TRISA network. The Pool maps common names to the Provider certificates and ensures that only public providers without private keys are stored in the pool.

func NewPool 

func NewPool(providers ...*Provider) ProviderPool

NewPool from the specified providers (optional).

func (ProviderPool) Add 

func (pool ProviderPool) Add(p *Provider)

Add a provider to the pool, mapping its common name to the provider.

func (ProviderPool) GetCertPool 

func (pool ProviderPool) GetCertPool(includeSystem bool) (_ *x509.CertPool, err error)

GetCertPool returns the x509.CertPool certificates of all provider certificates with the intermediate and root CA certificates. If requested, the pool can also load the system certificates pool if any system certificates exit.

type Serializer 

type Serializer struct {
	// During extraction, if marked as private the serializer will expect PKCS12
	// decryption from the incoming data. During compression, if marked not private,
	// then the serializer will only serialize the public Provider. This has no effect
	// on ProviderPool serialization which can only be serialized/deserialized with the
	// public certificates.
	Private bool

	// The password for encryption or decryption; required if Private is set to true,
	// if empty then the pkcs12.DefaultPassword, "changeit" is used.
	Password string

	// Format is one of "gz", "zip", "pem" (for no compression) and auto. If auto, then
	// during extraction the format is detected from the file extension, otherwise an
	// error is returned if directly from bytes. During compression if auto, then the
	// format is "gz" for Providers and "zip" for ProviderPools.
	Format string
	// contains filtered or unexported fields
}

Serializer maintains options for compression, encoding, and pkcs12 encryption when serializing and deserializing Provider and ProviderPool objects to and from disk.

func NewSerializer 

func NewSerializer(private bool, opts ...string) (_ *Serializer, err error)

NewSerializer creates a serializer with default options ready to either extract or compress a Provider or a ProviderPool. The serializer takes additional positional arguments of password and format respectively.

func (*Serializer) Compress 

func (s *Serializer) Compress(p *Provider) (data []byte, err error)

Compress a Provider into the given format with the specified encryption or encoding.

func (*Serializer) CompressPool 

func (s *Serializer) CompressPool(pool ProviderPool) (data []byte, err error)

CompressPool into the given format with the specified encryption or encoding.

func (*Serializer) Extract 

func (s *Serializer) Extract(data []byte) (p *Provider, err error)

Extract a Provider object from the given data, decompressing according to the format and decoding or decrypting the data as needed. Returns an error if the format is not correctly set or available.

func (*Serializer) ExtractPool 

func (s *Serializer) ExtractPool(data []byte) (pool ProviderPool, err error)

ExtractPool from the given data, decompressing according to the format and decoding or decrypting the data as needed. Returns an error if the format is not correctly set or available on the serializer object.

func (*Serializer) Read 

func (s *Serializer) Read(r io.Reader) (_ *Provider, err error)

Read and extract a Provider from the reader object. If the Format is CompressionZip, this method expects an io.ReadCloser, returned from the zip.File.Open method. Archive handling must happen before this method is called.

func (*Serializer) ReadFile 

func (s *Serializer) ReadFile(path string) (p *Provider, err error)

ReadFile and extract a Provider from it. This function expects only a single provider so it handles Zip archives specially, requiring that the Zip archive only has a single file in it, otherwise an error is returned.

func (*Serializer) ReadPool 

func (s *Serializer) ReadPool(readers ...io.Reader) (pool ProviderPool, err error)

ReadPool and extract a ProviderPool from the reader objects. If no readers are provided then an empty pool is returned. If the Format is CompressionZip, this method expects that the archive has been opened and is operating on all internal readers.

func (*Serializer) ReadPoolFile 

func (s *Serializer) ReadPoolFile(path string) (p ProviderPool, err error)

ReadPoolFile and extract a ProviderPool from it. This method primarily expects a Zip archive with multiple public provider files contained. TODO: handle directories

func (*Serializer) Write 

func (s *Serializer) Write(p *Provider, w io.Writer) (err error)

Write the provider encoded to the writer object.

func (*Serializer) WriteFile 

func (s *Serializer) WriteFile(p *Provider, path string) (err error)

WriteFile with the encoded provider object.

func (*Serializer) WritePool 

func (s *Serializer) WritePool(pool ProviderPool, w io.Writer) (err error)

WritePool encoded to the writer object.

func (*Serializer) WritePoolFile 

func (s *Serializer) WritePoolFile(pool ProviderPool, path string) (err error)

WritePoolFile with the encoded provider pool object.

Source Files

View all Source files

Directories

Path Synopsis

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.