pcert

package module
v0.0.13 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2023 License: Apache-2.0 Imports: 17 Imported by: 0

README

pcert

PkgGoDev Go Report Card Build

plaincert aims to ease the creation of x509 certificates and keys. It can be used as CLI tool or as Go library (pkg.go.dev).

Quick Start

# create CA (myca.crt and myca.key)
pcert create myca --ca

# create server certificate
pcert create myapp.company.com --with myca \
	--server \
	--dns api.myapp.company.com \
	--dns localhost \
	--ip 127.0.0.1 \
	--ip 192.168.10.5

# create client certificate
pcert create myuser --client --with myca

General

With pcert create <name> you can create a new certificate and key. The output file names are constructed using the name (<name>.crt and <name>.key). This can be changed by using the options --cert <file> and --key <file>.
The name is also set as the common name in the subject of the certificate. This can be changed with the --subject option (e.g --subject "CN=My fancy name").
All created certificates, keys and CSRs are saved PEM encoded and all files which are read are expected to be PEM encoded as well.
All options can also be specified using environment variables in the form PCERT_<OPTION> (e.g. --sign-cert is PCERT_SIGN_CERT).
Shell completion can be enabled for bash, zsh, fish and ps (Power Shell). It supports not only completion for the commands, but also for certain flags (e.g. --key-usage, --ext-key-usage, --sign-alg) where the valid options are hard to remember.

source <( pcert completion bash )
Self-Signed Certificates

If no options for signing are specified a self-signed certificate is created. This is used for the creation of a CA certificates or for test purposes.

Create a CA certificate myca.crt and key myca.key:

pcert create myca --ca
Signed Certificates

To sign a new certificate with an existing certificate and key, you can use the options --sign-cert <file> and --sign-key <file>. For these two options there is also the shortform --with <name>, which uses the files <name>.crt and <name>.key.

Create a server certificate signed from myca.crt and myca.key:

pcert create api.test.local --server --with myca

Create a client certificate signed from myca.crt and myca.key:

pcert create myUser --client --with myca
Subject Alternative Names (SANs)

To set subject alternative names on certificates you can use the options --dns, --ip, --email and --uri:

pcert create api.test.local --with myca --server \
	--dns api1.test.local \
	--dns superapi.test.local \
	--ip 127.0.0.1 \
	--ip 192.168.23.5
Profiles

To ease the creation of certificates with certain characteristics theare are three predefined profiles:

  • CA: --ca
  • Server: --server
  • Client: --client

If you use these options, settings (e.g key usage) which are typical for the specific profile are set for you. The same effect can be achieved by using the appropriate options individually.

Expiry

The validity period of certificates default to one year starting from the creation time. The period can be changed by using the options --not-before, --not-after and --expiry. The options --not-before and --not-after allow to set the NotBefore and NotAfter value to a certain date (RFC3339):

pcert create mycert --not-before 2020-01-01T12:00:00+01:00 --not-after 2020-06-01T12:00:00+01:00

The option --expiry allows to specify a duration instead of explicit dates:

# certificate valid until 90days from now
pcert create mycert --expiry 90d

# certificate valid until 3 years (3 * 365 days)
pcert create mycert --expiry 3y
Subject

With the option --subject you can set the subject of the certificate:

pcert create myclient --client --subject "CN=My User/O=Snakeoil Ltd./OU=My Team"

If the option is specified multiple times the values are combined:

export PCERT_SUBJECT="C=CH/L=Bern/O=Snakeoil Ltd."
pcert create myclient --client --subject "CN=David Schneider" --subject "OU=My Org Unit"

This would result in: C=CH/L=Bern/O=Snakeoil Ltd./OU=My Org Unit/CN=David Schneider

Examples

Local CA

Here is an example of how you could use pcert to create a local CA:

Create CA certificate and key in ~/pki:

mkdir ~/pki
pcert create ca --ca --cert ~/pki/ca.crt --key ~/pki/ca.key

If you like you can add the newly created certificate ~/pki/ca.crt to you system trust store.

Now we set PCERT_SIGN_CERT and PCERT_SIGN_KEY that all newly created certificates are signed with our CA in ~/pki. This could be added for example to .bashrc:

export PCERT_SIGN_CERT=~/pki/ca.crt
export PCERT_SIGN_KEY=~/pki/ca.key

From now on if we use pcert create it creates certificates which are signed by our local CA.

Intermediate CA

This example shows how to make an intermediate CA certificate:

Create root CA certificate and key:

pcert create myroot --ca

Create intermediate CA certificate:

pcert create myindtermediate --ca --sign-cert myroot.crt --sign-key myroot.key

Create server certificate from the intermediate CA:

pcert create myserver --server --sign-cert myindtermediate.crt --sign-key myindtermediate.key

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

Examples

Constants

View Source 
const (
	// DefaultValidityPeriod is the validity period used for certificates which have not set NotAfter explicitly
	DefaultValidityPeriod = time.Hour * 24 * 365
)

Variables

View Source 
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,
}
View Source 
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,
}
View Source 
var PublicKeyAlgorithms = []x509.PublicKeyAlgorithm{
	x509.RSA,
	x509.ECDSA,
	x509.Ed25519,
}

PublicKeyAlgorithms which are supported to create x509 certificates

View Source 
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 Encode 

func Encode(derBytes []byte) []byte

Encode encodes DER encoded certificate into PEM encoding

func EncodeCSR 

func EncodeCSR(derBytes []byte) []byte

EncodeCSR encodes DER encoded CSR into PEM encoding

func EncodeKey 

func EncodeKey(priv any) ([]byte, error)

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 

func KeyUsageToString(bitmask x509.KeyUsage) string

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 

func KeyUsageToStringSlice(bitmask x509.KeyUsage) []string

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 LoadKey 

func LoadKey(f string) (any, error)

LoadKey reads a *crypto.PrivateKey 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 ParseKey 

func ParseKey(pem []byte) (key any, err error)

ParseKey returns a *crypto.PrivateKey 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

Source Files

View all Source files

Directories

Path Synopsis
cmd
pcert

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.