certdeck

Cert Deck

go get github.com/a-novel-kit/certdeck

A x509 certificates management library.

• Cert Deck
  • Signer
  • Generating certs
    • Certificate keys
  • Leaf only
  • Self Signed
  • Update the issuer chain
• Store
• Collection
  • Default providers
    • File provider
    • HTTPS provider

Signer

store := newStore()

rootSigner := certdeck.NewSigner(&certdeck.SignerConfig{
	SerialStore: store,
})

rootKey, err := rsa.GenerateKey(rand.Reader, 8192)
rootKeyHash := certdeck.HashRSA(&rootKey.PublicKey)

rootCert, err := rootSigner.Sign(context.Background(), rootKey, rootKeyHash, &certdeck.Template{
	Exp: time.Hour,
	Name: pkix.Name{
		Country:       []string{"FR"},
		Organization:  []string{"A Novel Kit"},
		Locality:      []string{"Paris"},
		Province:      []string{""},
		StreetAddress: []string{"1 rue de la Paix"},
		PostalCode:    []string{"75000"},
	},
	IPAddresses: certdeck.IPLocalHost,
	DNSNames:    []string{"localhost"},
})

intermediateSigner := certdeck.NewSigner(&certdeck.SignerConfig{
	SerialStore: store,
	IssuerChain: []*x509.Certificate{rootCert},
	IssuerKey:   rootKey,
})

intermediateKey, err := ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
intermediateKeyHash := certdeck.HashECDSA(&intermediateKey.PublicKey)

intermediateCert, err := intermediateSigner.Sign(
	context.Background(), intermediateKey.Public(), intermediateKeyHash,
	&certdeck.Template{
		Exp: time.Hour,
		Name: pkix.Name{
			Country:       []string{"FR"},
			Organization:  []string{"A Novel Kit"},
			Locality:      []string{"Paris"},
			Province:      []string{""},
			StreetAddress: []string{"1 rue de la Paix"},
			PostalCode:    []string{"75000"},
		},
		IPAddresses: certdeck.IPLocalHost,
		DNSNames:    []string{"localhost"},
	},
)

leafSigner := certdeck.NewSigner(&certdeck.SignerConfig{
	SerialStore: store,
	IssuerChain: []*x509.Certificate{intermediateCert, rootCert},
	IssuerKey:   intermediateKey,
})

leafKey, _, err := ed25519.GenerateKey(rand.Reader)
leafKeyHash := certdeck.HashED25519(&leafKey)

leafCert, err := leafSigner.Sign(
	context.Background(), leafKey, leafKeyHash,
	&certdeck.Template{
		Exp: time.Hour,
		Name: pkix.Name{
			Country:       []string{"FR"},
			Organization:  []string{"A Novel Kit"},
			Locality:      []string{"Paris"},
			Province:      []string{""},
			StreetAddress: []string{"1 rue de la Paix"},
			PostalCode:    []string{"75000"},
		},
		IPAddresses: certdeck.IPLocalHost,
		DNSNames:    []string{"localhost"},
		LeafOnly:    true,
	},
)

The Signer interface requires you to provide a store for serial numbers. More information in the Store section.

Generating certs

The signer interface uses smart presets, to help you sign valid certificates for web with minimal configuration.

signer := certdeck.NewSigner(&certdeck.SignerConfig{
	SerialStore: store,
	IssuerChain: caChain,
	IssuerKey:   caKey,
})

The only 3 parameters you need to initialize a signer are

• Store: a persistent database of assigned serial numbers, to prevent duplicates
• IssuerChain: the chain of certificates used to sign issued certificates
• IssuerKey: the private key used to sign issued certificates, which must match that of the first certificate in the issuer chain

Once you have this set, you can call the sign method to issue new certificates. This method wraps the standard library with some default configuration, so you can focus on what is required to generate a certificate valid for the web.

cert, err := signer.Sign(context.Background(), key, keyHash, &certdeck.Template{
	// How long the certificate will be valid for. Default is 1 year.
	Exp: time.Hour,
	// Information about the certificate owner.
	Name: pkix.Name{
		Country:       []string{"FR"},
		Organization:  []string{"A Novel Kit"},
		Locality:      []string{"Paris"},
		Province:      []string{""},
		StreetAddress: []string{"1 rue de la Paix"},
		PostalCode:    []string{"75000"},
	},
	// The IP addresses the certificate is valid for.
	IPAddresses: certdeck.IPLocalHost,
	// The DNS names the certificate is valid for.
	DNSNames:    []string{"localhost"},
})

The Signer interface is thread-safe, so one instance should be shared across your application.

Certificate keys

To generate a certificate, you must also create a private/public key pair for it. The private key is used to generate signatures, or issue descendant certificates. The public key can be shared, and the certificate is used to validate it.

X509 only supports the following key types:

• RSA
• ECDSA
• ED25519

Go crypto library already provides generators for those keys. However, another field you must provide is a key ID. This ID can be randomly generated, or derived from the public key. This package provides methods for the second option:

Leaf only

By default, the generated certificates can be used to issue their own children. While this is useful to build chains, you should disable this if your certificate is only intended for key validation.

cert, err := signer.Sign(context.Background(), key, keyHash, &certdeck.Template{
	// ... other fields
	LeafOnly: true,
})

Self Signed

You can become your own root, by simply omitting the IssuerChain and IssuerKey fields, when initializing the signer.

rootSigner := certdeck.NewSigner(&certdeck.SignerConfig{
	SerialStore: store,
})

If using self-signed certificates, make sure they are added to the root system pool of the target machine, when verifying the issued certificates.

Update the issuer chain

You can update the certificates used by a signer, when new ones are available for example:

signer.Rotate(caChain, caKey)

Store

For security reason, you should provide a way to ensure uniqueness of serial numbers among the certificates from a given authority. Serial number should be unique even across revoked / expired certificates.

The best way to do this is to keep track of the serial numbers in a persistent database.

The Store is a simple interface, with a single method:

type SerialStore interface {
	Insert(ctx context.Context, serial *big.Int) error
}

The Insert method saves a new serial number in its database. If the number is already present, it MUST return the certdeck.ErrAlreadyExists error.

Below is an example with an in-memory, volatile store. You should build your own store with a persistent database instead.

type MemoryStore struct {
	serials map[string]bool
}

func (m *MemoryStore) Insert(ctx context.Context, serial *big.Int) error {
	if m.serials == nil {
		m.serials = make(map[string]bool)
	}

	serialStr := serial.String()
	if m.serials[serialStr] {
		return certdeck.ErrAlreadyExists
	}

	m.serials[serialStr] = true
	return nil
}

Collection

This package provides a Collection interface, to manage collections of certificates.

collection := certdeck.NewCollection(time.Hour)

provider := providers.NewHTTPS(&providers.HTTPSProviderConfig{
	ID: "my-website",
	CertsReq: func() (*http.Request, error) {
		return http.NewRequest(http.MethodGet, "https://my-website.com/certs", nil)
	},
	KeyReq: func() (*http.Request, error) {
		return http.NewRequest(http.MethodGet, "https://my-website.com/key", nil)
	},
})

data, err := collection.Get(provider)

certs := data.Certificates()
key := data.Key()

The argument of a collection is a duration, that indicates ho long values will be cached before being fetched again from the provider.

The returned value is a row, that returns the certificate chain and the private signature key, in both parsed and raw PEM formats.

Default providers

This package provides the following default providers:

File provider

The easier use case is to load certificates from files. First, you need to link your files to your Go code using a filesystem.

Given the following file tree.

- pkg
    - certs
        - files.go
        - 20241012.crt
        - 20241012.key
        - 20241010.crt
        - 20241010.key

The content of files.go should be:

//go:embed *.crt *.key
var CertsFS embed.FS

You can then create a file provider:

provider, err := providers.NewFile(&providers.FileProviderConfig{
	ID: "local",
	FS: CertsFS,
})

When loading files, they are sorted by creation date. The most recent one is used as the leaf certificate, and other are appended in a chain. The key returned is the one of the leaf.

You can customize the behavior of the file provider:

provider, err := providers.NewFile(&providers.FileProviderConfig{
	ID: "local",
	FS: CertsFS,

	// Customize the file pattern used to match certificates.
	CertsPattern: regexp.MustCompile(`\.crt$`)
	// Customize the file pattern used to match keys.
	KeysPattern:  regexp.MustCompile(`\.key$`)
	
	// Custom ordering of cert files. The first one is the leaf, then certificates must be sorted in order.
	SortCerts: providers.SortCreatedAt,
	// Custom ordering of key files. The first one is the key of the leaf, and is the only one actually parsed.
	SortKeys: providers.SortCreatedAt,
})

HTTPS provider

This provider fetches certificates from a remote server. It requires a function to create a request for the certificates and the key.

provider, err := providers.NewHTTPS(&providers.HTTPSProviderConfig{
	ID: "my-website",
	CertsReq: func() (*http.Request, error) {
		return http.NewRequest(http.MethodGet, "https://my-website.com/certs", nil)
	},
	KeyReq: func() (*http.Request, error) {
		return http.NewRequest(http.MethodGet, "https://my-website.com/key", nil)
	},
})