pki

package module
v1.4.9 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2024 License: GPL-3.0 Imports: 19 Imported by: 0

README

PKI

Yum

Go Report Card GitHub Workflow Status License

What is this?

A tool to ease the headache of PKI infrastructure generation.

How to install

Open a terminal and run the following:

$ # For library usage
$ go get --ldflags "-s -w" --trimpath -u github.com/mjwhitta/pki
$ # For cli usage
$ go install --ldflags "-s -w" --trimpath \
    github.com/mjwhitta/pki/cmd/certify@latest

Or compile from source:

$ git clone https://github.com/mjwhitta/pki.git
$ cd pki
$ git submodule update --init
$ make

Usage

Note: Regardless of how you use this Go tool, you should be aware that the certificates on disk are used as a database. Moving or removing files can lead to unintended side-effects (failure to revoke, etc...). You have been warned.

CLI

To get started with a simple PKI:

$ mkdir -p .../path/to/pki
$ certify --sample >.../path/to/pki/.cfg
$ # Modify .cfg as needed
$ certify --pki .../path/to/pki

You now have a PKI with a self-signed CA ready to go. If you would like to use your own CA (maybe an intermediate CA signed by a Trusted Root CA), now is the time to overwrite ca/ca.cert.pem and private/ca.key.pem in the PKI directory. You can delete or overwrite the DER files as well. See certify --help for what to do next.

$ # Create server certificate
$ certify --pki .../path/to/pki test.example.com
$ # Create wildcard certificate
$ certify --pki .../path/to/pki "example.com:*.example.com"
Library
package main

import "github.com/mjwhitta/pki"

func main() {
    var e error
    var p *pki.PKI

    // Create PKI structure
    if p, e = pki.New(".../path/to/pki", pki.NewCfg()); e != nil {
        panic(e)
    }

    // Create CA
    if _, _, e = p.CreateCA(); e != nil {
        panic(e)
    }

    // Create server Certificate
    _, _, e = p.CreateCertFor("test.example.com", pki.ServerCert)
    if e != nil {
        panic(e)
    }

    // Create wildcard Certificate
    _, _, e = p.CreateCertFor(
        "example.com",
        pki.ServerCert,
        "*.example.com",
    )
    if e != nil {
        panic(e)
    }

    // Sync the ders and pems directories for convenience
    if e = p.Sync(); e != nil {
        panic(e)
    }
}

TODO

  • Consider support for intermediary CAs

Documentation

Overview

Package pki provides a platform-independent means of generating PKI infrastructure. It will accept a filepath (directory) and Cfg then create a Certificate Authority (CA) for signing client or server X509 Certificates. Below is some sample code to create a default self-signed PKI: 

var e error
var p *pki.PKI

if p, e = pki.New("/pki/root/dir", pki.NewCfg()); e != nil {
    panic(e)
}

From there, client and server Certificates can be created or Certificate Signing Requests (CSRs) can be imported and used to generate a Certificate for a third-party.

The PKI infrastructure contains a built-in database for tracking generated Certificates and if/when they expired or were revoked.

Index

Constants

View Source 
const Version string = "1.4.9"

Version is the package version.

Variables

This section is empty.

Functions

This section is empty.

Types

type CertType 

type CertType int

CertType is an enumeration of supported certificate types. 

const (
	CACert CertType = iota
	ClientCert
	ServerCert
)

Certificate types

type Cfg 

type Cfg struct {
	CADaysValid   int
	CertDaysValid int
	// contains filtered or unexported fields
}

Cfg contains any relevant configuration options for creating PKI infrastructure.

func CfgFromFile 

func CfgFromFile(fn string) (*Cfg, error)

CfgFromFile will parse the specified file and create a new Cfg instance.

func NewCfg 

func NewCfg() *Cfg

NewCfg will create a new default instance of Cfg.

func (*Cfg) City 

func (cfg *Cfg) City(c string)

City is an alias for Locality().

func (*Cfg) CommonName 

func (cfg *Cfg) CommonName(cn string)

CommonName will set the CN in the certificate's subject.

func (*Cfg) Company 

func (cfg *Cfg) Company(c string)

Company is an alias for Organization().

func (*Cfg) Country 

func (cfg *Cfg) Country(c string)

Country will set the C in the certificate's subject.

func (*Cfg) Locality 

func (cfg *Cfg) Locality(l string)

Locality will set the L in the certificate's subject.

func (*Cfg) Organization 

func (cfg *Cfg) Organization(o string)

Organization will set the O in the certificate's subject.

func (*Cfg) OrganizationalUnit 

func (cfg *Cfg) OrganizationalUnit(ou string)

OrganizationalUnit will set the OU in the certificate's subject.

func (*Cfg) Province 

func (cfg *Cfg) Province(p string)

Province will set the ST in the certificate's subject.

func (*Cfg) SetOption 

func (cfg *Cfg) SetOption(k, v string) error

SetOption will allow you to set supported configuration options.

func (*Cfg) State 

func (cfg *Cfg) State(s string)

State is an alias for Province().

func (*Cfg) String 

func (cfg *Cfg) String() string

String will return a string representation of the Cfg.

func (*Cfg) Subject 

func (cfg *Cfg) Subject(cn ...string) pkix.Name

Subject will return the constructed Subject.

func (*Cfg) Unit 

func (cfg *Cfg) Unit(u string)

Unit is an alias for OrganizationalUnit().

type PKI 

type PKI struct {
	Cfg     *Cfg
	KeySize int
	Root    string
	// contains filtered or unexported fields
}

PKI is a structure that contains the PKI config, key size for generated Certificates, and the root of the PKI infrastructure.

func New 

func New(root string, cfg *Cfg) (*PKI, error)

New will return a pointer to a new PKI instance as well as initialized the PKI infrastructure on disk.

func (*PKI) CreateCA 

func (p *PKI) CreateCA() (*x509.Certificate, *rsa.PrivateKey, error)

CreateCA will create a new self-signed CA Certificate and return the Certificate with its associated private key. If a CA and key already exist on disk, they will be parsed and returned instead.

func (*PKI) CreateCSRFor 

func (p *PKI) CreateCSRFor(
	cn string, key *rsa.PrivateKey, alts ...string,
) (*x509.CertificateRequest, error)

CreateCSRFor will create a Certificate request for the specified CommonName, signed by the provided private key.

func (*PKI) CreateCertFor 

func (p *PKI) CreateCertFor(
	cn string, certType CertType, alts ...string,
) (*x509.Certificate, *rsa.PrivateKey, error)

CreateCertFor will create a Certificate for the specified CommonName, signed by the PKI's CA. The new Certificate and its associated private key will be returned. If a Certificate and key already exist on disk, they will be parsed and returned instead. See CertType for supported Certificate types.

func (*PKI) CreateRSAKeyFor 

func (p *PKI) CreateRSAKeyFor(cn string) (*rsa.PrivateKey, error)

CreateRSAKeyFor will create an RSA private key for the specified CommonName.

func (*PKI) Erase 

func (p *PKI) Erase() error

Erase will erase all PKI related files and directories. Be careful. This is non-reversible.

func (*PKI) Fingerprint 

func (p *PKI) Fingerprint(cert *x509.Certificate) string

Fingerprint will return the sha1 hash of the provided Certificate.

func (*PKI) FingerprintFor 

func (p *PKI) FingerprintFor(cn string) string

FingerprintFor will return the sha1 hash of the Certificate for the specified CommonName, should it exist. If the Certificate does not exist or is revoked, it will return empty string.

func (*PKI) GetCAFile 

func (p *PKI) GetCAFile() string

GetCAFile will return the filepath for the CA. There is no guarantee that the file exists. Use HasCA() first.

func (*PKI) GetCSRFileFor 

func (p *PKI) GetCSRFileFor(cn string) string

GetCSRFileFor will return the filepath for the CSR. There is no guarantee that the file exists. Use HasCSRFor() first.

func (*PKI) GetCertFileFor 

func (p *PKI) GetCertFileFor(cn string) string

GetCertFileFor will return the filepath for the Certificate. There is no guarantee that the file exists. Use HasCertFor() first.

func (*PKI) GetKeyFileFor 

func (p *PKI) GetKeyFileFor(cn string) string

GetKeyFileFor will return the filepath for the private key. There is no guarantee that the file exists. Use HasKeyFor() first.

func (*PKI) HasCA 

func (p *PKI) HasCA() bool

HasCA will return whether or not a CA already exists. This only checks if the file exists on disk. It does not validate that the file contains a valid Certificate.

func (*PKI) HasCSRFor 

func (p *PKI) HasCSRFor(cn string) bool

HasCSRFor will return whether or not a CSR for the specified CommonName already exists. This only checks if the file exists on disk. It does not validate that the file contains a valid CSR.

func (*PKI) HasCertFor 

func (p *PKI) HasCertFor(cn string) bool

HasCertFor will return whether or not a Certificate for the specified CommonName already exists. This only checks if the file exists on disk. It does not validate that the file contains a valid Certificate.

func (*PKI) HasKeyFor 

func (p *PKI) HasKeyFor(cn string) bool

HasKeyFor will return whether or not a private key for the specified CommonName already exists. This only checks if the file exists on disk. It does not validate that the file contains a valid private key.

func (*PKI) HasSigned 

func (p *PKI) HasSigned(cert *x509.Certificate) bool

HasSigned will return whether or not the provided Certificate has been signed by the PKI's CA.

func (*PKI) ImportCSR 

func (p *PKI) ImportCSR(fn string) error

ImportCSR will read the provided CSR and attempt import it into the PKI. If the embedded CommonName already has a Certificate or CSR, an error will be returned.

func (*PKI) IsExpired 

func (p *PKI) IsExpired(cert *x509.Certificate) bool

IsExpired will return whether or not the specified Certificate has expired. This takes a Certificate b/c a CommonName is not enough info with "unique_subject = no".

func (*PKI) IsRevoked 

func (p *PKI) IsRevoked(cert *x509.Certificate) (bool, error)

IsRevoked will return whether or not the specified Certificate has been revoked. This takes a Certificate b/c a CommonName is not enough info with "unique_subject = no".

func (*PKI) RevokeCert 

func (p *PKI) RevokeCert(cert *x509.Certificate) error

RevokeCert will revoke the provided Certificate.

func (*PKI) RevokeCertFor 

func (p *PKI) RevokeCertFor(cn string) (*x509.Certificate, error)

RevokeCertFor will revoke the oldest Certificate with the specified CommonName and return it for any post-processing, such as manually maintaining a Certificate Revocation List (CRL).

func (*PKI) Sync 

func (p *PKI) Sync() error

Sync will make sure that all ders/pems are mirrored in the associated directories for convenient access.

func (*PKI) Undo 

func (p *PKI) Undo() error

Undo will rollback the PKI database and delete the most recently generated Certificate and its associated CSR and private key.

Source Files

View all Source files

Directories

Path Synopsis
cmd
certify

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.