certutil

package module
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: May 1, 2021 License: MIT Imports: 15 Imported by: 0

README

Certificate Utilities

A collection of convenience utilities for working with PKI certificates.

Most functions work with PKCS8 unencrypted PEM encoding only.

Only Ed25519 and a subset of EC and RSA algorithms are supported. This is purposely designed to reduce complexity.

Documentation

Overview

Package certutil are convenience utilities for working with PKI certificates.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewCSR 

func NewCSR(key *PrivateKey, opts *CertOption) ([]byte, error)

NewCSR creates a new certificate signing request. Returns the PEM encoded CSR string.

func NewCert 

func NewCert(pemcsr []byte, pemCA []byte, caKey *PrivateKey, opts *CertOption) ([]byte, error)

NewCert creates a new certificate by signing the PEM encoded certificate signing request pemcsr with a CA's credentials (pemCA and caKey). The certificate can be customized by opts.

Example 
package main

import (
	"fmt"
	"github.com/gozl/certutil"
)

func main() {
	// create a CA first
	caKey, err := certutil.NewPrivateKey(certutil.Ed25519)
	if err != nil {
		fmt.Println(err.Error())
	}
	caCertOpts := certutil.NewCertOptions().CN("FullTrust CA")
	caCertPEM, err := certutil.NewRootCA(caKey, caCertOpts)
	if err != nil {
		fmt.Println(err.Error())
	}

	// create a user private key
	userKey, err := certutil.NewPrivateKey(certutil.Ed25519)
	if err != nil {
		fmt.Println(err.Error())
	}

	// now create a csr (certificate signing request) using the user's private
	// key.
	userCertOpts := certutil.NewCertOptions().CN("example.com")
	userCSRPEM, err := certutil.NewCSR(userKey, userCertOpts)
	if err != nil {
		fmt.Println(err.Error())
	}

	userCSR, err := certutil.ParseCSR(userCSRPEM)
	if err != nil {
		fmt.Println(err.Error())
	}
	fmt.Printf("User CSR subject common name: %s\n", userCSR.Subject.CommonName)

	// sign the CSR using the CA's certificate and private key. Extra options
	// can be specified with userCertOpts.
	userCertPEM, err := certutil.NewCert(userCSRPEM, caCertPEM, caKey, userCertOpts)
	if err != nil {
		fmt.Println(err.Error())
	}

	userCert, err := certutil.ParseCert(userCertPEM)
	if err != nil {
		fmt.Println(err.Error())
	}
	fmt.Printf("User cert subject common name: %s\n", userCert.Subject.CommonName)

}

Output:

User CSR subject common name: example.com
User cert subject common name: example.com

func NewRootCA 

func NewRootCA(key *PrivateKey, opts *CertOption) ([]byte, error)

NewRootCA creates a self-signed CA certificate in PEM encoded format.

Example 
package main

import (
	"crypto/x509"
	"fmt"
	"github.com/gozl/certutil"
)

func main() {
	caKey, err := certutil.NewPrivateKey(certutil.Ed25519)
	if err != nil {
		fmt.Println(err.Error())
	}

	caCertOpts := certutil.NewCertOptions().
		CN("FullTrust CA").
		KeyUsage(x509.KeyUsageCRLSign).
		ExtKeyUsage(x509.ExtKeyUsageMicrosoftKernelCodeSigning)

	caCertPEM, err := certutil.NewRootCA(caKey, caCertOpts)
	if err != nil {
		fmt.Println(err.Error())
	}

	// a PEM encoded cert is printable
	//fmt.Printf("CA cert:\n%s\n", caCertPEM)

	caCert, err := certutil.ParseCert(caCertPEM)
	if err != nil {
		fmt.Println(err.Error())
	}
	fmt.Printf("CA cert common name: %s\n", caCert.Subject.CommonName)

}

Output:

CA cert common name: FullTrust CA

func ParseCSR 

func ParseCSR(pemcsr []byte) (*x509.CertificateRequest, error)

ParseCSR unmarshals the PEM encoded certificate signing request to a x509.CertificateRequest instance.

func ParseCert 

func ParseCert(pemcert []byte) (*x509.Certificate, error)

ParseCert unmarshals the PEM encoded certificate to a x509.Certificate instance.

Types

type CertOption 

type CertOption struct {
	// contains filtered or unexported fields
}

CertOption builds certificate creation options in fluent pattern.

func NewCertOptions 

func NewCertOptions() *CertOption

NewCertOptions creates a new CertOption instance. Set parameters for the CertOption instance by calling its various methods.

func (*CertOption) CA 

func (certopt *CertOption) CA(isCA bool) *CertOption

CA indicates a certificate authority if isCA is true. A certificate authority can sign other certificates.

func (*CertOption) CN 

func (certopt *CertOption) CN(name string) *CertOption

CN sets the subject common name to name. Do not pass in an empty string. You are required to set the common name.

func (*CertOption) Country 

func (certopt *CertOption) Country(name string) *CertOption

Country sets the subject country. This is optional.

func (*CertOption) Email 

func (certopt *CertOption) Email(addrs ...string) *CertOption

Email sets the subject email addresses. This is optional.

func (*CertOption) ExtKeyUsage 

func (certopt *CertOption) ExtKeyUsage(usage ...x509.ExtKeyUsage) *CertOption

ExtKeyUsage sets the certificate extended key usage. This is optional.

func (*CertOption) IPAddr 

func (certopt *CertOption) IPAddr(ipaddrs ...string) *CertOption

Email sets the subject IP addresses. This is optional.

func (*CertOption) KeyUsage 

func (certopt *CertOption) KeyUsage(usage ...x509.KeyUsage) *CertOption

KeyUsage sets the certificate key usage. This is optional.

func (*CertOption) Locality 

func (certopt *CertOption) Locality(name string) *CertOption

Locality sets the subject locality. This is optional.

func (*CertOption) NotAfter 

func (certopt *CertOption) NotAfter(timestamp time.Time) *CertOption

NotAfter sets the time that the certificate will expire. Defaults to the 1 hour from the time when calling NewCertOptions. If you prefer specifying validity in terms of duration, use ValidFor.

func (*CertOption) NotBefore 

func (certopt *CertOption) NotBefore(timestamp time.Time) *CertOption

NotBefore sets the time that the certificate is valid from. Defaults to the time when calling NewCertOptions.

func (*CertOption) Org 

func (certopt *CertOption) Org(name string) *CertOption

Org sets the subject organization. This is optional.

func (*CertOption) Orgunit 

func (certopt *CertOption) Orgunit(name string) *CertOption

Orgunit sets the subject organization unit. This is optional.

func (*CertOption) Postcode 

func (certopt *CertOption) Postcode(name string) *CertOption

Postcode sets the subject postal code. This is optional.

func (*CertOption) SAN 

func (certopt *CertOption) SAN(domains ...string) *CertOption

SAN sets the subject alternate names. This is optional.

func (*CertOption) Street 

func (certopt *CertOption) Street(name string) *CertOption

Street sets the subject street address. This is optional.

func (*CertOption) URL 

func (certopt *CertOption) URL(urls ...string) *CertOption

URL sets the subject URIs. This is optional.

func (*CertOption) ValidFor 

func (certopt *CertOption) ValidFor(period time.Duration) *CertOption

ValidFor sets the duration that the certificate will be valid for, starting from NotBefore. Defaults to the 1 hour from the time when calling NewCertOptions. If you prefering specifying validity in terms of expire time, use NotAfter.

func (*CertOption) Validate 

func (certopt *CertOption) Validate() (*CertOption, error)

Validate checks the current options for errors. You do not need to call this method before creating a certificate.

type KeyAlgorithm 

type KeyAlgorithm int

KeyAlgorithm is certificate cryptographic algorithm. 

const (
	// RSA2048 is RSA with 2048-bit long modulus.
	RSA2048 KeyAlgorithm = iota
	// RSA2048 is RSA with 4096-bit long modulus.
	RSA4096
	// P224 is an Ecdsa curve which implements P-224 (see FIPS 186-3, section
	// D.2.2).
	P224
	// Prime256v1 is Ecdsa curve which implements NIST P-256 (FIPS 186-3,
	// section D.2.3), also known as secp256r1 or prime256v1.
	Prime256v1
	// Secp384r1 is Ecdsa curve which implements NIST P-384 (FIPS 186-3,
	// section D.2.4), also known as secp384r1.
	Secp384r1
	// Secp521r1 is Ecdsa curve which implements NIST P-521 (FIPS 186-3,
	// section D.2.5), also known as secp521r1.
	Secp521r1
	// Ed25519 is Ed25519 signature algorithm (see https://ed25519.cr.yp.to).
	Ed25519
)

func (KeyAlgorithm) IsEC 

func (algo KeyAlgorithm) IsEC() bool

IsEC returns true if algo is based on elliptic curve encryption.

func (KeyAlgorithm) IsEd25519 

func (algo KeyAlgorithm) IsEd25519() bool

IsEd25519 returns true if algo is Ed25519.

func (KeyAlgorithm) IsRSA 

func (algo KeyAlgorithm) IsRSA() bool

IsRSA returns true if algo is based on RSA encryption.

func (KeyAlgorithm) String 

func (algo KeyAlgorithm) String() string

String returns the string representation of algo.

type PrivateKey 

type PrivateKey struct {
	// contains filtered or unexported fields
}

PrivateKey is a thin wrapper for the private key implementation of selected cryptographic algorithms.

func NewPrivateKey 

func NewPrivateKey(algo KeyAlgorithm) (*PrivateKey, error)

NewPrivateKey creates a new private key using algo as the cryptographic algorithm.

Example 
package main

import (
	"fmt"
	"github.com/gozl/certutil"
)

func main() {
	myKey, err := certutil.NewPrivateKey(certutil.Ed25519)
	if err != nil {
		fmt.Println(err.Error())
	}
	fmt.Printf("key algo: %s\n", myKey.Algorithm().String())

	// marshal private key to PEM encoded string
	myKeyPEM, err := myKey.Encode()
	if err != nil {
		fmt.Println(err.Error())
	}

	// unmarshal back
	myKey2, err := certutil.ParsePrivateKey(myKeyPEM)
	if err != nil {
		fmt.Println(err.Error())
	}
	fmt.Printf("key2 algo: %s\n", myKey2.Algorithm().String())

}

Output:

key algo: Ed25519
key2 algo: Ed25519

func ParsePrivateKey 

func ParsePrivateKey(pemkey []byte) (*PrivateKey, error)

ParsePrivateKey unmarshals a private key from PEM encoded data. See the PrivateKey.Encode method for marshaling private key to PEM encoded string.

func (*PrivateKey) Algorithm 

func (privkey *PrivateKey) Algorithm() KeyAlgorithm

Algorithm returns the private key algorithm.

func (*PrivateKey) EC 

func (privkey *PrivateKey) EC() (*ecdsa.PrivateKey, error)

EC returns the underlying EC private key.

func (*PrivateKey) Ed25519 

func (privkey *PrivateKey) Ed25519() (ed25519.PrivateKey, error)

Ed25519 returns the underlying Ed25519 private key.

func (*PrivateKey) Encode 

func (privkey *PrivateKey) Encode() ([]byte, error)

Encode marshals the private key to PEM encoded string. See the ParsePrivateKey method for unmarshaling PEM encoded private key to a PrivateKey instance.

func (*PrivateKey) Public 

func (privkey *PrivateKey) Public() (*PublicKey, error)

Public returns the public key associated with this private key.

func (*PrivateKey) RSA 

func (privkey *PrivateKey) RSA() (*rsa.PrivateKey, error)

RSA returns the underlying RSA private key.

type PublicKey 

type PublicKey struct {
	// contains filtered or unexported fields
}

PublicKey is a thin wrapper for the public key implementation of selected cryptographic algorithms.

func (*PublicKey) Algorithm 

func (pubkey *PublicKey) Algorithm() KeyAlgorithm

Algorithm returns the public key algorithm.

func (*PublicKey) Encode 

func (pubkey *PublicKey) Encode() ([]byte, error)

Encode marshals the public key to PEM encoded string. See the ParsePublicKey method for unmarshaling PEM encoded public key to a PublicKey instance.

Source Files

View all Source files

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.