certmin

README

certmin

Description

certmin is a small, minimalistic library with high level functions for X509 certificates (SSL). It supports certificates and keys with PEM and DER encoding in PKCS1, PKCS5, PKCS7, PKCS8 and PKCS12 containers. Available functions include decoding and encoding of certificates and keys, verify certificates against chains and verify a certificate against a key. Utilities include checking if a cert is a root CA, finding the leaf certificate, split certs, sort chains in intermediates and roots and retrieving of certificates and chains. See: API documentation at pkg.go.dev.

There is also a companion certmin CLI application that consumes many of the functionalities of the library:

$ ./certmin
certmin, 0.5.11. A minimalist certificate utility.
See https://github.com/nxadm/certmin for more information.

Usage:
  certmin skim cert-location1 [cert-location2...] 
    [--leaf|--follow] [--no-roots]
    [--sort|--rsort] [--once] [--keep] [--no-colour]
  certmin verify-chain cert-location [cert-location2...]
    [--root=ca-file1 --root=ca-file2...]
    [--inter=inter-file1 --inter=inter-file2...]
    [--leaf|--follow] [--no-roots]
    [--sort|--rsort] [--keep] [--no-colour]
  certmin verify-key key-file cert-location1 [cert-location2...]
    [--keep] [--no-colour]
  certmin [-h]
  certmin [-v]

Certificate locations can be local files or remote addresses. Remote locations
can be a hostname with optionally a port attached by ":" (defaults to port
443) or an URL (scheme://hostname for known schemes like https, ldaps, smtps,
etc. or scheme://hostname:port for non-standard ports). When verifying a
chain, the OS trust store will be used if no roots certificates are given as
files or remotely requested. 

Actions:
  skim         | sc : skim certificates (including bundles).
  verify-chain | vc : match certificates again its chain(s).
  verify-key   | vk : match keys against certificate(s).

Global options (optional):
  --leaf      | -l  : show only the local or remote leaf, not the chain.
  --no-roots  | -n  : don't retrieve root certificates.
  --follow    | -f  : follow Issuer Certificate URIs to retrieve chain.
  --root      | -r  : root certificate file(s).
  --inter     | -i  : intermediate certificate file(s).
  --sort      | -s  : sort the certificates and chains from leaf to root.
  --rsort     | -z  : sort the certificates and chains from root to leaf.
  --once      | -o  : if within a location several certificates share an
                      intermediate/root, don't show certificates more than
                      once to visually complete the chain. If "rsort" not
                      given it enables "sort".  
  --keep      | -k  : write the requested certificates and chains to files
                      as PKCS1 PEM files (converting if necessary). 
  --no-colour | -c  : don't colourise the output.
  --help      | -h  : this help message.
  --version   | -v  : version message.

Installation

certmin is available using the standard go get command.

Install by running:

go get github.com/nxadm/certmin

The CLI tool can be installed by running:

go get github.com/nxadm/certmin/cmd/certmin

Usage

certmin can be loaded by a regular import:

import "github.com/nxadm/certmin"

API

Read the API documentation at pkg.go.dev.

Documentation

Index

• func DecodeCertBytes(certBytes []byte, password string) ([]*x509.Certificate, error)
• func DecodeCertBytesPKCS12(certBytes []byte, password string) ([]*x509.Certificate, error)
• func DecodeCertBytesPKCS1DER(certBytes []byte) ([]*x509.Certificate, error)
• func DecodeCertBytesPKCS1PEM(certBytes []byte) ([]*x509.Certificate, error)
• func DecodeCertBytesPKCS7DER(certBytes []byte) ([]*x509.Certificate, error)
• func DecodeCertBytesPKCS7PEM(certBytes []byte) ([]*x509.Certificate, error)
• func DecodeCertFile(certFile, password string) ([]*x509.Certificate, error)
• func DecodeKeyBytes(keyBytes []byte, password string) (*pem.Block, error)
• func DecodeKeyBytesPKCS1(keyBytes []byte) (*pem.Block, error)
• func DecodeKeyBytesPKCS12(keyBytes []byte, password string) (*pem.Block, error)
• func DecodeKeyBytesPKCS8(keyBytes []byte, password string) (*pem.Block, error)
• func DecodeKeyFile(keyFile string, password string) (*pem.Block, error)
• func EncodeCertAsPKCS1PEM(cert *x509.Certificate) ([]byte, error)
• func EncodeKeyAsPKCS1PEM(key *pem.Block) ([]byte, error)
• func FindLeaf(certs []*x509.Certificate) (*x509.Certificate, error)
• func IsRootCA(cert *x509.Certificate) bool
• func RetrieveCertsFromAddr(addr string, timeOut time.Duration) ([]*x509.Certificate, error, error)
• func RetrieveChainFromIssuerURLs(cert *x509.Certificate, timeOut time.Duration) ([]*x509.Certificate, error)
• func SortCerts(certs []*x509.Certificate, reverse bool) []*x509.Certificate
• func SortCertsAsChains(certs []*x509.Certificate, reverse bool) (map[string][]*x509.Certificate, map[string]*x509.Certificate, []string)
• func VerifyCertAndKey(cert *x509.Certificate, key *pem.Block) bool
• func VerifyChain(tree *CertTree) (bool, string)
• type CertTree
  • func SplitCertsAsTree(certs []*x509.Certificate) *CertTree

Functions

func DecodeCertBytes

func DecodeCertBytes(certBytes []byte, password string) ([]*x509.Certificate, error)

DecodeCertBytes reads a []byte with DER or PEM PKCS1, PKCS7 and PKCS12 encoded certificates, and returns the contents as a []*x509.Certificate and an error if encountered. A password is only needed for PKCS12.

func DecodeCertBytesPKCS12

func DecodeCertBytesPKCS12(certBytes []byte, password string) ([]*x509.Certificate, error)

DecodeCertBytesPKCS12 reads a []byte with PKCS12 encoded certificates (e.g. read from a file of a HTTP response body) and a password. It returns the contents as a []*x509.Certificate and an error if encountered. If you don't know in what format the data is encoded, use DecodeCertBytes.

func DecodeCertBytesPKCS1DER

func DecodeCertBytesPKCS1DER(certBytes []byte) ([]*x509.Certificate, error)

DecodeCertBytesPKCS1DER reads a []byte with PKCS1 DER encoded certificates (e.g. read from a file of a HTTP response body), and returns the contents as a []*x509.Certificate and an error if encountered. If you don't know in what format the data is encoded, use DecodeCertBytes.

func DecodeCertBytesPKCS1PEM

func DecodeCertBytesPKCS1PEM(certBytes []byte) ([]*x509.Certificate, error)

DecodeCertBytesPKCS1PEM reads a []byte with PKCS1 PEM encoded certificates (e.g. read from a file of a HTTP response body), and returns the contents as a []*x509.Certificate and an error if encountered. If you don't know in what format the data is encoded, use DecodeCertBytes.

func DecodeCertBytesPKCS7DER

func DecodeCertBytesPKCS7DER(certBytes []byte) ([]*x509.Certificate, error)

DecodeCertBytesPKCS7DER reads a []byte with PKCS7 DER encoded certificates (e.g. read from a file of a HTTP response body), and returns the contents as a []*x509.Certificate and an error if encountered. If you don't know in what format the data is encoded, use DecodeCertBytes.

func DecodeCertBytesPKCS7PEM

func DecodeCertBytesPKCS7PEM(certBytes []byte) ([]*x509.Certificate, error)

DecodeCertBytesPKCS7PEM reads a []byte with PKCS7 PEM encoded certificates (e.g. read from a file of a HTTP response body), and returns the contents as a []*x509.Certificate and an error if encountered. If you don't know in what format the data is encoded, use DecodeCertBytes.

func DecodeCertFile

func DecodeCertFile(certFile, password string) ([]*x509.Certificate, error)

DecodeCertFile reads a file with DER or PEM encoded certificates and returns the contents as a []*x509.Certificate and an error if encountered.

func DecodeKeyBytes

func DecodeKeyBytes(keyBytes []byte, password string) (*pem.Block, error)

DecodeKeyBytes reads a []byte with a key and returns a *pem.Block and an error if encountered.

func DecodeKeyBytesPKCS1

func DecodeKeyBytesPKCS1(keyBytes []byte) (*pem.Block, error)

DecodeKeyBytesPKCS1 reads a []byte with a PKCS1 PEM encoded key and returns a *pem.Block and an error if encountered. If you don't know in what format the data is encoded, use DecodeKeyBytes.

func DecodeKeyBytesPKCS12

func DecodeKeyBytesPKCS12(keyBytes []byte, password string) (*pem.Block, error)

DecodeKeyBytesPKCS12 reads a []byte with an encrypted PKCS12 encoded key and returns a *pem.Block and an error if encountered. If you don't know in what format the data is encoded, use DecodeKeyBytes.

func DecodeKeyBytesPKCS8

func DecodeKeyBytesPKCS8(keyBytes []byte, password string) (*pem.Block, error)

DecodeKeyBytesPKCS8 reads a []byte with an encrypted PKCS8 PEM encoded key and returns a *pem.Block and an error if encountered. If you don't know in what format the data is encoded, use DecodeKeyBytes.

func DecodeKeyFile

func DecodeKeyFile(keyFile string, password string) (*pem.Block, error)

DecodeKeyFile reads a file with PEM encoded key and returns the contents as a *pem.Block and an error if encountered.

func EncodeCertAsPKCS1PEM

func EncodeCertAsPKCS1PEM(cert *x509.Certificate) ([]byte, error)

EncodeCertAsPKCS1PEM converts *x509.Certificate to a []byte with data encoded as PKCS1 PEM and an error.

func EncodeKeyAsPKCS1PEM

func EncodeKeyAsPKCS1PEM(key *pem.Block) ([]byte, error)

EncodeKeyAsPKCS1PEM converts *pem.Block private key to a []byte with data encoded as PKCS1 PEM and an error.

func FindLeaf

func FindLeaf(certs []*x509.Certificate) (*x509.Certificate, error)

FindLeaf looks for the leaf certificate in a chain, this being the farthest certificate from the Root CA (usually the certificate of a server). It takes a []*x509.Certificate as chain with cert and it returns a *x509.Certificate as leaf and an error if zero or more than one leaf could be found.

func IsRootCA

func IsRootCA(cert *x509.Certificate) bool

IsRootCA returns for a given *x509.Certificate true if the CA is marked as IsCA and the Subject and the Issuer are the same.

func RetrieveCertsFromAddr

func RetrieveCertsFromAddr(addr string, timeOut time.Duration) ([]*x509.Certificate, error, error)

RetrieveCertsFromAddr retrieves all the certificates offered by the remote host. As parameters it takes an address string in the form of hostname:port and a time-out duration for the connection. The time-out is used for both the TCP and the SSL connection, with 0 disabling it. The return values are a []*x509.Certificate (with the first element being the certificate of the server), an error with a warning (e.g. mismatch between the hostname and the CN or DNS alias in the certificate) and an error in case of failure.

func RetrieveChainFromIssuerURLs

func RetrieveChainFromIssuerURLs(cert *x509.Certificate, timeOut time.Duration) ([]*x509.Certificate, error)

RetrieveChainFromIssuerURLs retrieves the chain for a certificate by following the Issuing Certificate URLs field in the certificate (if present) and consecutively following the Issuing Certificate URLs from issuing certificates. As parameters it takes a *x509.Certificate and a time-out duration for the HTTP connection with 0 disabling it. The return values are a []*x509.Certificate (with the first element being the supplied certificate) and an error in case of failure.

func SortCerts

func SortCerts(certs []*x509.Certificate, reverse bool) []*x509.Certificate

SortCerts sorts a []*x509.Certificate from leaf to root CA, or the other way around if a the supplied boolean is set to true. Double elements are removed.

func SortCertsAsChains

func SortCertsAsChains(
	certs []*x509.Certificate, reverse bool) (map[string][]*x509.Certificate, map[string]*x509.Certificate, []string)

SortCertsAsChains sorts a []*x509.Certificate from leaf to root CA, or the other way around if a the boolean parameter is set to true. The function returns three elements: a map[string][]*x509.Certificate with the subject as key and the chain as value, a map[string]*x509.Certificate with the the subject as key and the corresponding *x509.Certificate as value and a []string with Subjects that are used as keys in the first map, in the order the where found in the given []*x509.Certificate parameter.

func VerifyCertAndKey

func VerifyCertAndKey(cert *x509.Certificate, key *pem.Block) bool

VerifyCertAndKey verifies that a certificate (*x509.Certificate) and a key (*pem.Block) match, returning the result as a bool.

func VerifyChain

func VerifyChain(tree *CertTree) (bool, string)

VerifyChain verifies the chain of a certificate as part of a CertTree. When the Roots field is nil, the OS trust store is used. The function return a boolean with the verification result and an string with an associated message with the reason of a negative result.

Types

type CertTree

type CertTree struct {
	Certificate          *x509.Certificate
	Intermediates, Roots []*x509.Certificate
}

CertTree represents a chain where certificates are assigned as a Certificate, Intermediates and Roots.

func SplitCertsAsTree

func SplitCertsAsTree(certs []*x509.Certificate) *CertTree

SplitCertsAsTree returns a *CertTree where the given certificates are assigned as Certificate, Intermediates and Roots. The starting leaf certificate must be the first element of the given []*x509.Certificate.