certutil

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Feb 13, 2023 License: Apache-2.0, MPL-2.0, BSD-3-Clause Imports: 30 Imported by: 0

Documentation

Overview

Package certutil contains helper functions that are mostly used with the PKI backend but can be generally useful. Functionality includes helpers for converting a certificate/private key bundle between DER and PEM, printing certificate serial numbers, and more.

Functionality specific to the PKI backend includes some types and helper methods to make requesting certificates from the backend easy.

Index

Constants

View Source 
const (
	PrivateKeyTypeP521 = "p521"
)

Variables

This section is empty.

Functions

func AddExtKeyUsageOids 

func AddExtKeyUsageOids(data *CreationBundle, certTemplate *x509.Certificate)

addExtKeyUsageOids adds custom extended key usage OIDs to certificate

func AddKeyUsages 

func AddKeyUsages(data *CreationBundle, certTemplate *x509.Certificate)

addKeyUsages adds appropriate key usages to the template given the creation information

func AddPolicyIdentifiers 

func AddPolicyIdentifiers(data *CreationBundle, certTemplate *x509.Certificate)

addPolicyIdentifiers adds certificate policies extension

func ComparePublicKeys 

func ComparePublicKeys(key1Iface, key2Iface crypto.PublicKey) (bool, error)

ComparePublicKeys compares two public keys and returns true if they match

func DefaultOrValueHashBits added in v0.9.0 

func DefaultOrValueHashBits(keyType string, keyBits int, hashBits int) (int, error)

Returns default signature hash bit length for the specified key type and bits, or the present value if hashBits is non-zero. Returns an error under certain internal circumstances.

func DefaultOrValueKeyBits added in v0.9.0 

func DefaultOrValueKeyBits(keyType string, keyBits int) (int, error)

Returns default key bits for the specified key type, or the present value if keyBits is non-zero.

func GeneratePrivateKey 

func GeneratePrivateKey(keyType string, keyBits int, container ParsedPrivateKeyContainer) error

GeneratePrivateKey generates a private key with the specified type and key bits.

func GeneratePrivateKeyWithRandomSource 

func GeneratePrivateKeyWithRandomSource(keyType string, keyBits int, container ParsedPrivateKeyContainer, entropyReader io.Reader) error

GeneratePrivateKeyWithRandomSource generates a private key with the specified type and key bits. GeneratePrivateKeyWithRandomSource uses randomness from the entropyReader to generate the private key.

func GenerateSerialNumber 

func GenerateSerialNumber() (*big.Int, error)

GenerateSerialNumber generates a serial number suitable for a certificate

func GenerateSerialNumberWithRandomSource 

func GenerateSerialNumberWithRandomSource(randReader io.Reader) (*big.Int, error)

GenerateSerialNumberWithRandomSource generates a serial number suitable for a certificate with custom entropy.

func GetHexFormatted 

func GetHexFormatted(buf []byte, sep string) string

GetHexFormatted returns the byte buffer formatted in hex with the specified separator between bytes.

func GetPublicKeySize 

func GetPublicKeySize(key crypto.PublicKey) int

GetPublicKeySize returns the key size in bits for a given arbitrary crypto.PublicKey Returns -1 for an unsupported key type.

func GetSubjKeyID 

func GetSubjKeyID(privateKey crypto.Signer) ([]byte, error)

GetSubjKeyID returns the subject key ID. The computed ID is the SHA-1 hash of the marshaled public key according to https://tools.ietf.org/html/rfc5280#section-4.2.1.2 (1)

func HandleOtherCSRSANs 

func HandleOtherCSRSANs(in *x509.CertificateRequest, sans map[string][]string) error

func HandleOtherSANs 

func HandleOtherSANs(in *x509.Certificate, sans map[string][]string) error

func NewCertPool 

func NewCertPool(reader io.Reader) (*x509.CertPool, error)

func ParseHexFormatted 

func ParseHexFormatted(in, sep string) []byte

ParseHexFormatted returns the raw bytes from a formatted hex string

func ParsePublicKeyPEM 

func ParsePublicKeyPEM(data []byte) (interface{}, error)

ParsePublicKeyPEM is used to parse RSA and ECDSA public keys from PEMs

func StringToOid 

func StringToOid(in string) (asn1.ObjectIdentifier, error)

func ValidateDefaultOrValueKeyTypeSignatureLength added in v0.9.0 

func ValidateDefaultOrValueKeyTypeSignatureLength(keyType string, keyBits int, hashBits int) (int, int, error)

Validates that the combination of keyType, keyBits, and hashBits are valid together; replaces individual calls to ValidateSignatureLength and ValidateKeyTypeLength. Also updates the value of keyBits and hashBits on return.

func ValidateKeyTypeLength 

func ValidateKeyTypeLength(keyType string, keyBits int) error

func ValidateSignatureLength 

func ValidateSignatureLength(keyType string, hashBits int) error

Validates that the length of the hash (in bits) used in the signature calculation is a known, approved value.

Types

type BlockType 

type BlockType string

BlockType indicates the serialization format of the key 

const (
	PKCS1Block BlockType = "RSA PRIVATE KEY"
	PKCS8Block BlockType = "PRIVATE KEY"
	ECBlock    BlockType = "EC PRIVATE KEY"
)

Well-known formats

type CAInfoBundle 

type CAInfoBundle struct {
	ParsedCertBundle
	URLs *URLEntries
}

func (*CAInfoBundle) GetCAChain 

func (b *CAInfoBundle) GetCAChain() []*CertBlock

func (*CAInfoBundle) GetFullChain added in v0.9.0 

func (b *CAInfoBundle) GetFullChain() []*CertBlock

type CSRBundle 

type CSRBundle struct {
	PrivateKeyType PrivateKeyType `json:"private_key_type" structs:"private_key_type" mapstructure:"private_key_type"`
	CSR            string         `json:"csr" structs:"csr" mapstructure:"csr"`
	PrivateKey     string         `json:"private_key" structs:"private_key" mapstructure:"private_key"`
}

CSRBundle contains a key type, a PEM-encoded private key, and a PEM-encoded CSR

func (*CSRBundle) ToParsedCSRBundle 

func (c *CSRBundle) ToParsedCSRBundle() (*ParsedCSRBundle, error)

ToParsedCSRBundle converts a string-based CSR bundle to a byte-based raw CSR bundle

type CertBlock 

type CertBlock struct {
	Certificate *x509.Certificate
	Bytes       []byte
}

CertBlock contains the DER-encoded certificate and the PEM block's byte array

type CertBundle 

type CertBundle struct {
	PrivateKeyType PrivateKeyType `json:"private_key_type" structs:"private_key_type" mapstructure:"private_key_type"`
	Certificate    string         `json:"certificate" structs:"certificate" mapstructure:"certificate"`
	IssuingCA      string         `json:"issuing_ca" structs:"issuing_ca" mapstructure:"issuing_ca"`
	CAChain        []string       `json:"ca_chain" structs:"ca_chain" mapstructure:"ca_chain"`
	PrivateKey     string         `json:"private_key" structs:"private_key" mapstructure:"private_key"`
	SerialNumber   string         `json:"serial_number" structs:"serial_number" mapstructure:"serial_number"`
}

CertBundle contains a key type, a PEM-encoded private key, a PEM-encoded certificate, and a string-encoded serial number, returned from a successful Issue request

func (*CertBundle) ToPEMBundle 

func (c *CertBundle) ToPEMBundle() string

ToPEMBundle converts a string-based certificate bundle to a PEM-based string certificate bundle in trust path order, leaf certificate first

func (*CertBundle) ToParsedCertBundle 

func (c *CertBundle) ToParsedCertBundle() (*ParsedCertBundle, error)

ToParsedCertBundle converts a string-based certificate bundle to a byte-based raw certificate bundle

func (*CertBundle) ToParsedCertBundleWithExtractor added in v0.9.0 

func (c *CertBundle) ToParsedCertBundleWithExtractor(privateKeyExtractor PrivateKeyExtractor) (*ParsedCertBundle, error)

type CertExtKeyUsage 

type CertExtKeyUsage int
const (
	AnyExtKeyUsage CertExtKeyUsage = 1 << iota
	ServerAuthExtKeyUsage
	ClientAuthExtKeyUsage
	CodeSigningExtKeyUsage
	EmailProtectionExtKeyUsage
	IpsecEndSystemExtKeyUsage
	IpsecTunnelExtKeyUsage
	IpsecUserExtKeyUsage
	TimeStampingExtKeyUsage
	OcspSigningExtKeyUsage
	MicrosoftServerGatedCryptoExtKeyUsage
	NetscapeServerGatedCryptoExtKeyUsage
	MicrosoftCommercialCodeSigningExtKeyUsage
	MicrosoftKernelCodeSigningExtKeyUsage
)

type ClusterKeyParams 

type ClusterKeyParams struct {
	Type string   `json:"type" structs:"type" mapstructure:"type"`
	X    *big.Int `json:"x" structs:"x" mapstructure:"x"`
	Y    *big.Int `json:"y" structs:"y" mapstructure:"y"`
	D    *big.Int `json:"d" structs:"d" mapstructure:"d"`
}

This can be one of a few key types so the different params may or may not be filled

type CreationBundle 

type CreationBundle struct {
	Params        *CreationParameters
	SigningBundle *CAInfoBundle
	CSR           *x509.CertificateRequest
}

type CreationParameters 

type CreationParameters struct {
	Subject                       pkix.Name
	DNSNames                      []string
	EmailAddresses                []string
	IPAddresses                   []net.IP
	URIs                          []*url.URL
	OtherSANs                     map[string][]string
	IsCA                          bool
	KeyType                       string
	KeyBits                       int
	NotAfter                      time.Time
	KeyUsage                      x509.KeyUsage
	ExtKeyUsage                   CertExtKeyUsage
	ExtKeyUsageOIDs               []string
	PolicyIdentifiers             []string
	BasicConstraintsValidForNonCA bool
	SignatureBits                 int

	// Only used when signing a CA cert
	UseCSRValues        bool
	PermittedDNSDomains []string

	// URLs to encode into the certificate
	URLs *URLEntries

	// The maximum path length to encode
	MaxPathLength int

	// The duration the certificate will use NotBefore
	NotBeforeDuration time.Duration
}

type IssueData 

type IssueData struct {
	TTL        string `json:"ttl" structs:"ttl" mapstructure:"ttl"`
	CommonName string `json:"common_name" structs:"common_name" mapstructure:"common_name"`
	OU         string `json:"ou" structs:"ou" mapstructure:"ou"`
	AltNames   string `json:"alt_names" structs:"alt_names" mapstructure:"alt_names"`
	IPSANs     string `json:"ip_sans" structs:"ip_sans" mapstructure:"ip_sans"`
	CSR        string `json:"csr" structs:"csr" mapstructure:"csr"`
	OtherSANs  string `json:"other_sans" structs:"other_sans" mapstructure:"other_sans"`
}

IssueData is a structure that is suitable for marshaling into a request; either via JSON, or into a map[string]interface{} via the structs package

type KeyGenerator added in v0.9.0 

type KeyGenerator func(keyType string, keyBits int, container ParsedPrivateKeyContainer, entropyReader io.Reader) error

KeyGenerator Allow us to override how/what generates the private key

type ParsedCSRBundle 

type ParsedCSRBundle struct {
	PrivateKeyType  PrivateKeyType
	PrivateKeyBytes []byte
	PrivateKey      crypto.Signer
	CSRBytes        []byte
	CSR             *x509.CertificateRequest
}

ParsedCSRBundle contains a key type, a DER-encoded private key, and a DER-encoded certificate request

func CreateCSR 

func CreateCSR(data *CreationBundle, addBasicConstraints bool) (*ParsedCSRBundle, error)

CreateCSR creates a CSR with the default rand.Reader to generate a cert/keypair. This is currently only meant for use when generating an intermediate certificate.

func CreateCSRWithKeyGenerator added in v0.9.0 

func CreateCSRWithKeyGenerator(data *CreationBundle, addBasicConstraints bool, randReader io.Reader, keyGenerator KeyGenerator) (*ParsedCSRBundle, error)

CreateCSRWithKeyGenerator creates a CSR with a custom io.Reader for randomness to generate a cert/keypair with the provided private key generator.

func CreateCSRWithRandomSource 

func CreateCSRWithRandomSource(data *CreationBundle, addBasicConstraints bool, randReader io.Reader) (*ParsedCSRBundle, error)

CreateCSRWithRandomSource creates a CSR with a custom io.Reader for randomness to generate a cert/keypair.

func (*ParsedCSRBundle) SetParsedPrivateKey 

func (p *ParsedCSRBundle) SetParsedPrivateKey(privateKey crypto.Signer, privateKeyType PrivateKeyType, privateKeyBytes []byte)

SetParsedPrivateKey sets the private key parameters on the bundle

func (*ParsedCSRBundle) ToCSRBundle 

func (p *ParsedCSRBundle) ToCSRBundle() (*CSRBundle, error)

ToCSRBundle converts a byte-based raw DER certificate bundle to a PEM-based string certificate bundle

type ParsedCertBundle 

type ParsedCertBundle struct {
	PrivateKeyType   PrivateKeyType
	PrivateKeyFormat BlockType
	PrivateKeyBytes  []byte
	PrivateKey       crypto.Signer
	CertificateBytes []byte
	Certificate      *x509.Certificate
	CAChain          []*CertBlock
}

ParsedCertBundle contains a key type, a DER-encoded private key, and a DER-encoded certificate

func CreateCertificate 

func CreateCertificate(data *CreationBundle) (*ParsedCertBundle, error)

CreateCertificate uses CreationBundle and the default rand.Reader to generate a cert/keypair.

func CreateCertificateWithKeyGenerator added in v0.9.0 

func CreateCertificateWithKeyGenerator(data *CreationBundle, randReader io.Reader, keyGenerator KeyGenerator) (*ParsedCertBundle, error)

func CreateCertificateWithRandomSource 

func CreateCertificateWithRandomSource(data *CreationBundle, randReader io.Reader) (*ParsedCertBundle, error)

CreateCertificateWithRandomSource uses CreationBundle and a custom io.Reader for randomness to generate a cert/keypair.

func ParsePEMBundle 

func ParsePEMBundle(pemBundle string) (*ParsedCertBundle, error)

ParsePEMBundle takes a string of concatenated PEM-format certificate and private key values and decodes/parses them, checking validity along the way. The first certificate must be the subject certificate and issuing certificates may follow. There must be at most one private key.

func ParsePKIJSON 

func ParsePKIJSON(input []byte) (*ParsedCertBundle, error)

ParsePKIJSON takes a JSON-encoded string and returns a ParsedCertBundle.

This can be either the output of an issue call from the PKI backend or just its data member; or, JSON not coming from the PKI backend.

func ParsePKIMap 

func ParsePKIMap(data map[string]interface{}) (*ParsedCertBundle, error)

ParsePKIMap takes a map (for instance, the Secret.Data returned from the PKI backend) and returns a ParsedCertBundle.

func SignCertificate 

func SignCertificate(data *CreationBundle) (*ParsedCertBundle, error)

SignCertificate performs the heavy lifting of generating a certificate from a CSR. Returns a ParsedCertBundle sans private keys.

func SignCertificateWithRandomSource 

func SignCertificateWithRandomSource(data *CreationBundle, randReader io.Reader) (*ParsedCertBundle, error)

SignCertificateWithRandomSource generates a certificate from a CSR, using custom randomness from the randReader. Returns a ParsedCertBundle sans private keys.

func (*ParsedCertBundle) GetCertificatePath 

func (p *ParsedCertBundle) GetCertificatePath() []*CertBlock

GetCertificatePath returns a slice of certificates making up a path, pulled from the parsed cert bundle

func (*ParsedCertBundle) GetTLSConfig 

func (p *ParsedCertBundle) GetTLSConfig(usage TLSUsage) (*tls.Config, error)

getTLSConfig returns a TLS config generally suitable for client authentication. The returned TLS config can be modified slightly to be made suitable for a server requiring client authentication; specifically, you should set the value of ClientAuth in the returned config to match your needs.

func (*ParsedCertBundle) SetParsedPrivateKey 

func (p *ParsedCertBundle) SetParsedPrivateKey(privateKey crypto.Signer, privateKeyType PrivateKeyType, privateKeyBytes []byte)

SetParsedPrivateKey sets the private key parameters on the bundle

func (*ParsedCertBundle) ToCertBundle 

func (p *ParsedCertBundle) ToCertBundle() (*CertBundle, error)

ToCertBundle converts a byte-based raw DER certificate bundle to a PEM-based string certificate bundle

func (*ParsedCertBundle) Verify 

func (p *ParsedCertBundle) Verify() error

Verify checks if the parsed bundle is valid. It validates the public key of the certificate to the private key and checks the certificate trust chain for path issues.

type ParsedPrivateKeyContainer 

type ParsedPrivateKeyContainer interface {
	SetParsedPrivateKey(crypto.Signer, PrivateKeyType, []byte)
}

ParsedPrivateKeyContainer allows common key setting for certs and CSRs

type PrivateKeyExtractor added in v0.9.0 

type PrivateKeyExtractor func(c *CertBundle, parsedBundle *ParsedCertBundle) error

PrivateKeyExtractor extract out a private key from the passed in CertBundle and set the appropriate bits within the ParsedCertBundle.

type PrivateKeyType 

type PrivateKeyType string

PrivateKeyType holds a string representation of the type of private key (ec or rsa) referenced in CertBundle and ParsedCertBundle. This uses colloquial names rather than official names, to eliminate confusion 

const (
	UnknownPrivateKey PrivateKeyType = ""
	RSAPrivateKey     PrivateKeyType = "rsa"
	ECPrivateKey      PrivateKeyType = "ec"
	Ed25519PrivateKey PrivateKeyType = "ed25519"
	ManagedPrivateKey PrivateKeyType = "ManagedPrivateKey"
)

Well-known PrivateKeyTypes

type Secret 

type Secret struct {
	Data map[string]interface{} `json:"data"`
}

Secret is used to attempt to unmarshal a Vault secret JSON response, as a convenience

type TLSUsage 

type TLSUsage int

TLSUsage controls whether the intended usage of a *tls.Config returned from ParsedCertBundle.getTLSConfig is for server use, client use, or both, which affects which values are set 

const (
	TLSUnknown TLSUsage = 0
	TLSServer  TLSUsage = 1 << iota
	TLSClient
)

Well-known TLSUsage types

type URLEntries 

type URLEntries struct {
	IssuingCertificates   []string `json:"issuing_certificates" structs:"issuing_certificates" mapstructure:"issuing_certificates"`
	CRLDistributionPoints []string `json:"crl_distribution_points" structs:"crl_distribution_points" mapstructure:"crl_distribution_points"`
	OCSPServers           []string `json:"ocsp_servers" structs:"ocsp_servers" mapstructure:"ocsp_servers"`
}

Source Files

View all Source files

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.