Documentation ¶
Overview ¶
Package pcert aims to ease the creation of x509 certificates and keys. This package provides the following main functions:
- Create: creates a certificate and a key
- Request: creates a CSR and a key
- Sign: signs a certificate or a CSR with an existing certificate and key
The results of the functions which return certificates, CSRs and keys are all PEM encoded.
All functions without special suffix refer to a certificates. Functions for CSR and Key use an appropriate suffix. For example the function Load loads a certificate from a file, whereas LoadKey or LoadCSR are for keys resp. CSRs.
import ( "io/ioutil" "github.com/dvob/pcert" ) func main() { cert := pcert.NewServerCertificate("www.example.local") // self-signed certPEM, keyPEM, _ := pcert.Create(cert, nil, nil) _ = ioutil.WriteFile("server.crt", certPEM, 0644) _ = ioutil.WriteFile("server.key", keyPEM, 0600) }
Index ¶
- Constants
- Variables
- func Create(cert, signCert *x509.Certificate, signKey crypto.PrivateKey) (certPEM, keyPEM []byte, err error)
- func CreateWithKeyOptions(cert *x509.Certificate, keyOptions KeyOptions, signCert *x509.Certificate, ...) (certPEM, keyPEM []byte, err error)
- func Encode(derBytes []byte) []byte
- func EncodeCSR(derBytes []byte) []byte
- func EncodeKey(priv any) ([]byte, error)
- func ExtKeyUsageToString(ku []x509.ExtKeyUsage) string
- func GenerateKey(opts KeyOptions) (crypto.PrivateKey, crypto.PublicKey, error)
- func KeyUsageToString(bitmask x509.KeyUsage) string
- func KeyUsageToStringSlice(bitmask x509.KeyUsage) []string
- func Load(f string) (*x509.Certificate, error)
- func LoadCSR(f string) (*x509.CertificateRequest, error)
- func LoadKey(f string) (any, error)
- func NewCACertificate(name string) *x509.Certificate
- func NewCertificate(name string) *x509.Certificate
- func NewClientCertificate(name string) *x509.Certificate
- func NewServerCertificate(name string) *x509.Certificate
- func Parse(pem []byte) (*x509.Certificate, error)
- func ParseAll(data []byte) ([]*x509.Certificate, error)
- func ParseCSR(pem []byte) (*x509.CertificateRequest, error)
- func ParseKey(pem []byte) (key any, err error)
- func Request(csr *x509.CertificateRequest) (csrPEM, keyPEM []byte, err error)
- func RequestWithKeyOptions(csr *x509.CertificateRequest, keyOptions KeyOptions) (csrPEM, keyPEM []byte, err error)
- func SetCAProfile(cert *x509.Certificate)
- func SetClientProfile(cert *x509.Certificate)
- func SetServerProfile(cert *x509.Certificate)
- func Sign(cert *x509.Certificate, publicKey any, signCert *x509.Certificate, signKey any) (certPEM []byte, err error)
- func SignCSR(csr *x509.CertificateRequest, cert, signCert *x509.Certificate, signKey any) (certPEM []byte, err error)
- type KeyOptions
Examples ¶
Constants ¶
const ( // DefaultValidityPeriod is the validity period used for certificates which have not set NotAfter explicitly DefaultValidityPeriod = time.Hour * 24 * 365 )
Variables ¶
var ExtKeyUsages = map[string]x509.ExtKeyUsage{ "Any": x509.ExtKeyUsageAny, "ClientAuth": x509.ExtKeyUsageClientAuth, "CodeSigning": x509.ExtKeyUsageCodeSigning, "EmailProtection": x509.ExtKeyUsageEmailProtection, "IPSECEndSystem": x509.ExtKeyUsageIPSECEndSystem, "IPSECTunnel": x509.ExtKeyUsageIPSECTunnel, "IPSECUser": x509.ExtKeyUsageIPSECUser, "MicrosoftCommercialCodeSigning": x509.ExtKeyUsageMicrosoftCommercialCodeSigning, "MicrosoftKernelCodeSigning": x509.ExtKeyUsageMicrosoftKernelCodeSigning, "MicrosoftServerGatedCrypto": x509.ExtKeyUsageMicrosoftServerGatedCrypto, "NetscapeServerGatedCrypto": x509.ExtKeyUsageNetscapeServerGatedCrypto, "OCSPSigning": x509.ExtKeyUsageOCSPSigning, "ServerAuth": x509.ExtKeyUsageServerAuth, "TimeStamping": x509.ExtKeyUsageTimeStamping, }
var KeyUsages = map[string]x509.KeyUsage{ "CRLSign": x509.KeyUsageCRLSign, "CertSign": x509.KeyUsageCertSign, "ContentCommitment": x509.KeyUsageContentCommitment, "DataEncipherment": x509.KeyUsageDataEncipherment, "DecipherOnly": x509.KeyUsageDecipherOnly, "DigitalSignature": x509.KeyUsageDigitalSignature, "EncipherOnly": x509.KeyUsageEncipherOnly, "KeyAgreement": x509.KeyUsageKeyAgreement, "KeyEncipherment": x509.KeyUsageKeyEncipherment, }
var PublicKeyAlgorithms = []x509.PublicKeyAlgorithm{ x509.RSA, x509.ECDSA, x509.Ed25519, }
PublicKeyAlgorithms which are supported to create x509 certificates
var SignatureAlgorithms = []x509.SignatureAlgorithm{ x509.DSAWithSHA1, x509.DSAWithSHA256, x509.ECDSAWithSHA1, x509.ECDSAWithSHA256, x509.ECDSAWithSHA384, x509.ECDSAWithSHA512, x509.MD2WithRSA, x509.MD5WithRSA, x509.PureEd25519, x509.SHA1WithRSA, x509.SHA256WithRSA, x509.SHA256WithRSAPSS, x509.SHA384WithRSA, x509.SHA384WithRSAPSS, x509.SHA512WithRSA, x509.SHA512WithRSAPSS, }
Functions ¶
func Create ¶
func Create(cert, signCert *x509.Certificate, signKey crypto.PrivateKey) (certPEM, keyPEM []byte, err error)
Create creates a x509.Certificate and a key with the default key options. See CreateWithKeyOptions for more details.
Example (SelfSigned) ¶
Create a key and a self-signed certificate and save it to server.crt and server.key
cert := NewServerCertificate("localhost") // self-signed certPEM, keyPEM, err := Create(cert, nil, nil) if err != nil { log.Fatal(err) } err = os.WriteFile("server.crt", certPEM, 0o644) if err != nil { log.Fatal(err) } err = os.WriteFile("server.crt", keyPEM, 0o600) if err != nil { log.Fatal(err) }
Output:
Example (Signed) ¶
Load a root CA from ca.crt and ca.key and use it to create a signed server certificate
// load root CA rootCACert, err := Load("ca.crt") if err != nil { log.Fatal(err) } rootCAKey, err := LoadKey("ca.key") if err != nil { log.Fatal(err) } // create signed server certificate cert := NewServerCertificate("localhost") certPEM, keyPEM, err := Create(cert, rootCACert, rootCAKey) if err != nil { log.Fatal(err) } err = os.WriteFile("server.crt", certPEM, 0o644) if err != nil { log.Fatal(err) } err = os.WriteFile("server.crt", keyPEM, 0o600) if err != nil { log.Fatal(err) }
Output:
func CreateWithKeyOptions ¶
func CreateWithKeyOptions(cert *x509.Certificate, keyOptions KeyOptions, signCert *x509.Certificate, signKey crypto.PrivateKey) (certPEM, keyPEM []byte, err error)
CreateWithKeyOptions creates a key and certificate. The certificate is signed used signCert and signKey. If signCert or signKey are nil, a self-signed certificate will be created. The certificate and the key are returned PEM encoded.
Example ¶
Create a self-signed certificate with a 4096 bit RSA key
cert := NewServerCertificate("localhost") keyOptions := KeyOptions{ Algorithm: x509.RSA, Size: 4096, } certPEM, keyPEM, err := CreateWithKeyOptions(cert, keyOptions, nil, nil) if err != nil { log.Fatal(err) } _, _ = os.Stdout.Write(certPEM) _, _ = os.Stdout.Write(keyPEM)
Output:
func EncodeKey ¶
EncodeKey encodes a *crypto.PrivateKey into PEM encoding by using x509.MarshalPKCS8PrivateKey
func ExtKeyUsageToString ¶
func ExtKeyUsageToString(ku []x509.ExtKeyUsage) string
ExtKeyUsageToString returns a string representation of a []x509.ExtKeyUsage slice
Example ¶
cert := NewClientCertificate("myUser") usageStr := ExtKeyUsageToString(cert.ExtKeyUsage) fmt.Println(usageStr)
Output: ClientAuth
func GenerateKey ¶
func GenerateKey(opts KeyOptions) (crypto.PrivateKey, crypto.PublicKey, error)
GenerateKey returns a private and a public key based on the options. If no PublicKeyAlgorithm is set in the options ECDSA is used. If no key size is set in the options 256 bit is used for ECDSA and 2048 bit for RSA. For ECDSA the following sizes are valid: 224, 256, 384 and 521. For the x509.Ed25519 algorithm the size in the KeyOptions is ignored.
func KeyUsageToString ¶
KeyUsageToString returns a string representation of a x509.KeyUsage bitmask
Example ¶
cert := NewCACertificate("My Super Root CA") usageStr := KeyUsageToString(cert.KeyUsage) fmt.Println(usageStr)
Output: CRLSign,CertSign
func KeyUsageToStringSlice ¶ added in v0.0.13
KeyUsageToStringSlice returns a slice with string representations of the x509.KeyUsage bitmask
func Load ¶
func Load(f string) (*x509.Certificate, error)
Load reads a *x509.Certificate from a PEM encoded file.
func LoadCSR ¶
func LoadCSR(f string) (*x509.CertificateRequest, error)
LoadCSR reads a *x509.CertificateRequest from a PEM encoded file.
func NewCACertificate ¶
func NewCACertificate(name string) *x509.Certificate
NewCACertificate returns a new certificate. The CommonName is set to name and typical CA certificate settings are set (see SetCAProfile function).
func NewCertificate ¶
func NewCertificate(name string) *x509.Certificate
NewCertificate returns a new certificate which have the CommonName set to name
func NewClientCertificate ¶
func NewClientCertificate(name string) *x509.Certificate
NewClientCertificate returns a new certificate. The CommonName is set to name and typical client certificate settings are set (see SetClientProfile function).
func NewServerCertificate ¶
func NewServerCertificate(name string) *x509.Certificate
NewServerCertificate returns a new certificate. The CommonName is set to name and typical server certificate settings are set (see SetServerProfile function).
func Parse ¶
func Parse(pem []byte) (*x509.Certificate, error)
Parse returns a *x509.Certificate from PEM encoded data.
func ParseAll ¶ added in v0.0.13
func ParseAll(data []byte) ([]*x509.Certificate, error)
ParseAll returns a list of x509.Certificates from a list of concatenated PEM encoded certificates.
func ParseCSR ¶
func ParseCSR(pem []byte) (*x509.CertificateRequest, error)
ParseCSR returns a *x509.CertificateRequest from PEM encoded data.
func Request ¶
func Request(csr *x509.CertificateRequest) (csrPEM, keyPEM []byte, err error)
Request creates a CSR and a key. The key is created with the default key options. See RequestWithKeyOptions for more details.
func RequestWithKeyOptions ¶
func RequestWithKeyOptions(csr *x509.CertificateRequest, keyOptions KeyOptions) (csrPEM, keyPEM []byte, err error)
RequestWithKeyOptions creates a CSR and a key based on key options. The key is created with the default key options.
func SetCAProfile ¶
func SetCAProfile(cert *x509.Certificate)
SetCAProfile sets typical characteristics of a CA certificate.
func SetClientProfile ¶
func SetClientProfile(cert *x509.Certificate)
SetClientProfile sets typical characteristics of a client certificate.
func SetServerProfile ¶
func SetServerProfile(cert *x509.Certificate)
SetServerProfile sets typical characteristics of a server certificate.
func Sign ¶
func Sign(cert *x509.Certificate, publicKey any, signCert *x509.Certificate, signKey any) (certPEM []byte, err error)
Sign set some defaults on a certificate and signs it with the signCert and the signKey. The following defaults are set they are not set explicitly in the certificate:
- SubjectKeyId is generated based on the publicKey
- The AuthorityKeyId is set based on the SubjectKeyId of the signCert
- NotBefore is set to time.Now()
- NotAfter is set to NotBefore + DefaultValidityPeriod
- SerialNumber is set to a randomly generated serial number
The created certificate is returned PEM encoded.
func SignCSR ¶
func SignCSR(csr *x509.CertificateRequest, cert, signCert *x509.Certificate, signKey any) (certPEM []byte, err error)
SignCSR applies the settings from csr and return the signed certificate
Types ¶
type KeyOptions ¶
type KeyOptions struct { Algorithm x509.PublicKeyAlgorithm Size int }
KeyOptions specifies a key algorithm and a size