17 KiB
testca
import "github.com/effective-security/xpki/testca"
Package testca provides utilities for creating test Certificate Authorities and certificates for testing and development purposes.
This package supports:
- Generation of test CA certificates and private keys
- Creation of end-entity certificates signed by test CAs
- Certificate chain building for testing
- Generation of various key types (RSA, ECDSA) for testing
- PEM encoding/decoding utilities for test certificates
The package is primarily intended for use in unit tests and development environments where real certificates are not required or desired.
Default common names and issuer serial numbers are allocated safely across concurrent NewEntity and Entity.Issue calls. Configure package defaults, entity fields, and option data before starting concurrent calls, and leave them unchanged until the calls finish. Custom private keys must support concurrent signing. Access Entity.NextSN directly only while issuance and Entity.IncrementSN calls are stopped; do not copy an Entity after first use.
Note: Certificates generated by this package should never be used in production environments as they are not trusted by any real PKI.
Index
- Variables
- func GenerateECDSAKeyInPEM(rand io.Reader, c elliptic.Curve) ([]byte, error)
- func GenerateRSAKeyInPEM(rand io.Reader, size int) ([]byte, error)
- func MakeInvalidCertsChainTSA(t *testing.T, hours int) (crypto.Signer, *x509.Certificate, []*x509.Certificate, *x509.Certificate)
- func MakeSelfCertECDSA(hours int) (*x509.Certificate, crypto.PrivateKey, error)
- func MakeSelfCertECDSAPem(hours int) (pemCert, pemKey []byte, err error)
- func MakeSelfCertRSA(hours int) (*x509.Certificate, crypto.PrivateKey, error)
- func MakeSelfCertRSAPem(hours int) (pemCert, pemKey []byte, err error)
- func MakeValidCertsChainTSA(t *testing.T, hours int, ec bool) (crypto.Signer, *x509.Certificate, []*x509.Certificate, *x509.Certificate)
- func PrivKeyToPEM(priv any) []byte
- func SetSAN(template *x509.Certificate, SAN []string)
- func ToDER(priv any) []byte
- func ToPEM(cert *x509.Certificate) []byte
- func ToPFX(cert *x509.Certificate, priv any, password string) []byte
- func ToPKCS8(priv any) []byte
- type Entity
- func NewEntity(opts ...Option) *Entity
- func (id *Entity) Chain() []*x509.Certificate
- func (id *Entity) ChainPool() *x509.CertPool
- func (id *Entity) IncrementSN() int64
- func (id *Entity) Issue(opts ...Option) *Entity
- func (id *Entity) KeyAndCertChain() *KeyAndCertChain
- func (id *Entity) PFX(password string) []byte
- func (id *Entity) Root() *x509.Certificate
- func (id *Entity) SaveCertAndKey(certFile string, keyFile string, withChain bool) (err error)
- type KeyAndCertChain
- type Option
- func CrlDpURL(value ...string) Option
- func DNSName(value ...string) Option
- func ExtKeyUsage(value x509.ExtKeyUsage) Option
- func Extensions(value []pkix.Extension) Option
- func Issuer(value *Entity) Option
- func IssuingCertificateURL(value ...string) Option
- func KeyUsage(value x509.KeyUsage) Option
- func NextSerialNumber(value int64) Option
- func NotAfter(value time.Time) Option
- func NotBefore(value time.Time) Option
- func OCSPServer(value ...string) Option
- func PrivateKey(value crypto.Signer) Option
- func Subject(value pkix.Name) Option
Variables
var (
// DefaultCountry is the default subject Country.
DefaultCountry = []string{"US"}
// DefaultProvince is the default subject Province.
DefaultProvince = []string{"CA"}
// DefaultLocality is the default subject Locality.
DefaultLocality = []string{"San Francisco"}
// DefaultStreetAddress is the default subject StreetAddress.
DefaultStreetAddress = []string(nil)
// DefaultPostalCode is the default subject PostalCode.
DefaultPostalCode = []string(nil)
// DefaultCommonName is the default subject CommonName.
DefaultCommonName = "[TEST]"
)
func GenerateECDSAKeyInPEM
func GenerateECDSAKeyInPEM(rand io.Reader, c elliptic.Curve) ([]byte, error)
GenerateECDSAKeyInPEM returns PEM encoded ECDSA key
func GenerateRSAKeyInPEM
func GenerateRSAKeyInPEM(rand io.Reader, size int) ([]byte, error)
GenerateRSAKeyInPEM returns PEM encoded RSA key
func MakeInvalidCertsChainTSA
func MakeInvalidCertsChainTSA(t *testing.T, hours int) (crypto.Signer, *x509.Certificate, []*x509.Certificate, *x509.Certificate)
MakeInvalidCertsChainTSA creates invalid TSA cert with several critical EKU extensions
func MakeSelfCertECDSA
func MakeSelfCertECDSA(hours int) (*x509.Certificate, crypto.PrivateKey, error)
MakeSelfCertECDSA creates self-signed cert
func MakeSelfCertECDSAPem
func MakeSelfCertECDSAPem(hours int) (pemCert, pemKey []byte, err error)
MakeSelfCertECDSAPem creates self-signed cert in PEM format
func MakeSelfCertRSA
func MakeSelfCertRSA(hours int) (*x509.Certificate, crypto.PrivateKey, error)
MakeSelfCertRSA creates self-signed cert
func MakeSelfCertRSAPem
func MakeSelfCertRSAPem(hours int) (pemCert, pemKey []byte, err error)
MakeSelfCertRSAPem creates self-signed cert in PEM format
func MakeValidCertsChainTSA
func MakeValidCertsChainTSA(t *testing.T, hours int, ec bool) (crypto.Signer, *x509.Certificate, []*x509.Certificate, *x509.Certificate)
MakeValidCertsChainTSA creates valid TSA cert with the only critical EKU extension for timestamping
func PrivKeyToPEM
func PrivKeyToPEM(priv any) []byte
PrivKeyToPEM exports private key to PEM
func SetSAN
func SetSAN(template *x509.Certificate, SAN []string)
SetSAN fills template's IPAddresses, EmailAddresses, and DNSNames with the content of SAN, if it is not nil.
func ToDER
func ToDER(priv any) []byte
ToDER exports private key to DER
func ToPEM
func ToPEM(cert *x509.Certificate) []byte
ToPEM exports cert to PEM
func ToPFX
func ToPFX(cert *x509.Certificate, priv any, password string) []byte
ToPFX wraps cert and its private key in a password-protected PKCS#12 (PFX) packet encoded with pkcs12.Modern2023 (PBES2 with PBKDF2-HMAC-SHA-256 and AES-256-CBC, HMAC-SHA-256 MAC), readable by OpenSSL 1.1.1+, Java 12+ and Windows Server 2019+. The password may be empty and may contain any character of the Basic Multilingual Plane, since PKCS#12 encodes it as a BMPString (UCS-2); a character outside it, such as an emoji, cannot be encoded and panics (XPKI-063: the former OpenSSL-based implementation allowed alphanumeric passwords only). priv must be an *rsa.PrivateKey, *ecdsa.PrivateKey or ed25519.PrivateKey; anything else panics, as does an encoding failure.
func ToPKCS8
func ToPKCS8(priv any) []byte
ToPKCS8 exports the private key as an unencrypted PKCS#8 PEM block ("PRIVATE KEY"), the same form `openssl pkcs8 -topk8 -nocrypt` produced (XPKI-063). priv must be an *rsa.PrivateKey, *ecdsa.PrivateKey or ed25519.PrivateKey; anything else panics.
type Entity
Entity is a certificate and private key. An Entity must not be copied after first use.
type Entity struct {
Issuer *Entity
PrivateKey crypto.Signer
Certificate *x509.Certificate
// NextSN is the serial number to allocate on the next IncrementSN call.
// Read or write it directly only when no IncrementSN or Issue calls,
// including NewEntity calls using this entity as Issuer, are in flight.
NextSN int64
// contains filtered or unexported fields
}
func NewEntity
func NewEntity(opts ...Option) *Entity
NewEntity creates a new CA.
func (*Entity) Chain
func (id *Entity) Chain() []*x509.Certificate
Chain builds a slice of *x509.Certificate from this CA and its issuers.
func (*Entity) ChainPool
func (id *Entity) ChainPool() *x509.CertPool
ChainPool builds an *x509.CertPool from this CA and its issuers.
func (*Entity) IncrementSN
func (id *Entity) IncrementSN() int64
IncrementSN returns the current NextSN and increments it atomically with respect to other IncrementSN calls on this entity.
func (*Entity) Issue
func (id *Entity) Issue(opts ...Option) *Entity
Issue issues a new Entity with this one as its parent. Concurrent calls are safe if the issuer's fields and option data remain unchanged and its private key supports concurrent signing. The caller's option slice is not modified; this issuer takes precedence over any Issuer option in opts.
func (*Entity) KeyAndCertChain
func (id *Entity) KeyAndCertChain() *KeyAndCertChain
KeyAndCertChain returns chain for the PrivateKey
func (*Entity) PFX
func (id *Entity) PFX(password string) []byte
PFX wraps the certificate and private key in a password-protected PKCS#12 packet; see ToPFX for the password rules (any BMP characters, or empty).
func (*Entity) Root
func (id *Entity) Root() *x509.Certificate
Root returns root CA for this entity.
func (*Entity) SaveCertAndKey
func (id *Entity) SaveCertAndKey(certFile string, keyFile string, withChain bool) (err error)
SaveCertAndKey stores the cert and key to provided locations withChain specifies to store entire chain up to the root in cert's pem file
type KeyAndCertChain
KeyAndCertChain provides PrivateKey and its certificates chain
type KeyAndCertChain struct {
PrivateKey crypto.Signer
Certificate *x509.Certificate
Chain []*x509.Certificate
Root *x509.Certificate
}
type Option
Option is an option that can be passed to New().
type Option option
Authority is an Option for making an entity a certificate authority.
var Authority Option = func(c *configuration) {
c.isCA = true
}
func CrlDpURL
func CrlDpURL(value ...string) Option
CrlDpURL is an Option for setting the entity's certificate's CRL Distribution Point.
func DNSName
func DNSName(value ...string) Option
DNSName is an Option for setting the SAN.
func ExtKeyUsage
func ExtKeyUsage(value x509.ExtKeyUsage) Option
ExtKeyUsage is an Option for setting the extended key usage.
func Extensions
func Extensions(value []pkix.Extension) Option
Extensions is an Option for setting extensions.
func Issuer
func Issuer(value *Entity) Option
Issuer is an Option for setting the entity's issuer.
func IssuingCertificateURL
func IssuingCertificateURL(value ...string) Option
IssuingCertificateURL is an Option for setting the entity's certificate's IssuingCertificateURL.
func KeyUsage
func KeyUsage(value x509.KeyUsage) Option
KeyUsage is an Option for setting the key usage.
func NextSerialNumber
func NextSerialNumber(value int64) Option
NextSerialNumber is an Option that determines the SN of the next issued certificate.
func NotAfter
func NotAfter(value time.Time) Option
NotAfter is an Option for setting the entity's certificate's NotAfter.
func NotBefore
func NotBefore(value time.Time) Option
NotBefore is an Option for setting the entity's certificate's NotBefore.
func OCSPServer
func OCSPServer(value ...string) Option
OCSPServer is an Option for setting the entity's certificate's OCSPServer.
func PrivateKey
func PrivateKey(value crypto.Signer) Option
PrivateKey is an Option for setting the entity's private key.
func Subject
func Subject(value pkix.Name) Option
Subject is an Option that sets a entity's subject field.
Generated by gomarkdoc