README
¶
Autocert
Usage
Import the library with
import "github.com/FlowFabricator/autocert"
To issue certificates, first create a CA
caCertsOpts := autocert.&CertificateOptions{
SubjectName: "test-ca",
}
rootCA, err := autocert.InitialiseCA(caCertsOpts)
Or import an existing CA using a PEM encoded certificate and private key. Note: when importing an existing CA, it must be a root CA. Importing intermediate CAs will return an error
caCert, caKey := getExistingCA()
err := autocert.ImportCA(caCert, caKey)
To issue certificates signed by this CA:
certsOpts := &autocert.CertificateOptions{
SubjectName: "test1",
IsPemEncoded: true,
DNSNames: []string{"localhost", "mydomain"},
IPAddresses: []net.IP{
net.ParseIP("127.0.0.1"),
net.ParseIP("::"),
net.ParseIP("192.32.471.2"),
},
}
pemEncCert, pemEncKey, err := autocert.RequestCertificate(certsOpts)
CA certificates have a minimum time to live of 5 years, attempting to make a CA with a shorter time to live will result in an error. Certificates signed by the CA have a maximum time to live of 1 hour, attempting to create longer lived certificates will result in an error.
Certificate time to live is set in CertificateOptions as follows:
caOpts := &autocert.CertificateOptions{
SubjectName: "test1",
ExpiryDate: time.Now().AddDate(10, 0, 0), /* 10 years from now */
}
// Or
certOpts := &autocert.CertificateOptions{
SubjectName: "test1",
ExpiryDate: time.Now().Add(time.Minute * 10), /* 10 minutes from now */
}
All CA certificates are saved both PEM encoded and non PEM encoded, the CertificateOptions parameter IsPemEncoded has no effect in CA certificates.
When getting a CA certificate or key, you can get either version as follows:
// Get non PEM encoded
rootCa := autocert.GetCACertificate() /* Returns *x509.Certificate */
rootCaKey := autocert.GetCAKey(false)
// Get PEM encoded
rootCa := autocert.GetPemEncodedCACertificate() /* Returns byte array */
rootCaKey := autocert.GetCAKey(true)
Documentation
¶
Overview ¶
Package autocert is an opinionated pki library for non-production use. This library can be used to set up a CA and sign certificates. There can only be 1 CA, and it must use a long-lived certificate (5+ years). All certificates use ed25519 public keys. CAs can be imported however they must be a root CA certificate.
Index ¶
- Variables
- func ClearCA()
- func GetCACertificate() *x509.Certificate
- func GetCAKey(pemEncoded bool) []byte
- func GetPemEncodedCACertificate() []byte
- func ImportCA(certificate []byte, key []byte) error
- func InitialiseCA(certOpts *CertificateOptions) ([]byte, error)
- func ParseRootCA(certificate []byte, key []byte) (*x509.Certificate, tls.Certificate, error)
- func RequestCertificate(certOpts *CertificateOptions) ([]byte, []byte, error)
- type CertificateOptions
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCAAlreadyInitialised Returned when a CA initialisation request is made while there is already a CA ErrCAAlreadyInitialised = errors.New("CA is already initialised") // ErrCANotInitialised Returned when a certificate is requested but no CA is initialised ErrCANotInitialised = errors.New("CA has not been initialised") // ErrCAIsNotRootCA Returned when a CA is imported which is an intermediate CA certificate ErrCAIsNotRootCA = errors.New("CA must be a root CA") // ErrCertificateNotPemEncoded Returned when a CA is imported but the CA certificate is not PEM encoded ErrCertificateNotPemEncoded = errors.New("provided certificate was not PEM encoded") // ErrKeyNotPemEncoded Returned when a CA is imported but the CA private key is not PEM encoded ErrKeyNotPemEncoded = errors.New("provided key was not PEM encoded") // ErrNameNotProvided Returned when a certificate is requested but no SubjectName or Subject.CommonName is given ErrNameNotProvided = errors.New("certificate subject name not provided") // ErrCAExpiryDateBelowMinimum Returned when a CA is initialised with an expiry date less than 5 years from now ErrCAExpiryDateBelowMinimum = errors.New("CA certificate expiry date must be minimum of 5 years from now") // ErrCertExpiryExceedsMaximum Returned when a certificate is requested but the expiry date is greater than 1 hour from now ErrCertExpiryExceedsMaximum = errors.New("certificate expiry date exceeds maximum value of 1 hour from now") )
Functions ¶
func ClearCA ¶ added in v0.1.4
func ClearCA()
ClearCA removes any stored CA data. In order to issue certificates, InitialiseCA or ImportCA will have to be called again.
func GetCACertificate ¶
func GetCACertificate() *x509.Certificate
GetCACertificate Returns the current CA certificate
func GetCAKey ¶
GetCAKey Return current CA private key. If pemEncoded is true, return PEM encoded key, otherwise return non pem encoded key
func GetPemEncodedCACertificate ¶
func GetPemEncodedCACertificate() []byte
GetPemEncodedCACertificate Returns current CA certificate, PEM encoded
func ImportCA ¶
ImportCA Parses a PEM encoded certificate and key, and sets it as the current CA. Must be a root CA certificate, intermediate CAs will return ErrCAIsNotRootCA
func InitialiseCA ¶
func InitialiseCA(certOpts *CertificateOptions) ([]byte, error)
InitialiseCA Creates a root CA and sets it as the current CA. Returns the CA certificate as raw bytes. If certOpts.IsPemEncoded is true, returns raw bytes PEM encoded
func ParseRootCA ¶ added in v0.1.5
func ParseRootCA(certificate []byte, key []byte) (*x509.Certificate, tls.Certificate, error)
func RequestCertificate ¶
func RequestCertificate(certOpts *CertificateOptions) ([]byte, []byte, error)
RequestCertificate Returns a certificate signed by the current CA. Requires a CA to already be initialised. Returns the certificate and private key as raw bytes. If certOpts.IsPemEncoded is true, returns the certificate and key as PEM encoded byte arrays.
Types ¶
type CertificateOptions ¶
type CertificateOptions struct {
// SubjectName Required field. Overrides Subject.CommonName.
// If nil, ErrNameNotProvided is returned
SubjectName string
// Subject Optional details field for the certificate subject.
// SubjectName will override the Subject.CommonName field
Subject pkix.Name
// ExpiryDate The time this certificate will expire.
// CA certificates must be at least five years from now or ErrCAExpiryDateBelowMinimum will be returned.
// Other certificates must be less than an hour from now or ErrCertExpiryExceedsMaximum will be returned.
ExpiryDate time.Time
// IsPemEncoded Dictates whether returned certificates are PEM encoded or not.
// CA certificates are available both PEM encoded and non-PEM encoded,
// when creating CA certificates, this option will only determine which is returned.
IsPemEncoded bool
// DNSNames DNS names which this certificate is valid for.
DNSNames []string
// IPAddresses IP addresses which this certificate is valid for.
IPAddresses []net.IP
// URIs URLs which this certificate is valid for.
URIs []*url.URL
}
CertificateOptions Configuration options for a certificate
Source Files