goca

package module
v0.0.0-...-0d802d7 Latest Latest
Warning

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

Go to latest
Published: Jul 12, 2024 License: MIT Imports: 13 Imported by: 0

README

Go Certificate Authority management package

Go Report Card Build Status Go Reference Docker Pulls

GocA provides a Certificate Authority (CA) framework managing, a Simple PKI.

GoCA is a framework that uses mainly crypto/x509 to manage Certificate Authorities.

Using GoCA makes it easy to create a CA and issue certificates, signing Certificates Signing Request (CSR), and revoke certificate generating Certificates Request List (CRL).

Content:

GoCA Package

go get github.com/kairoaraujo/goca

All files are store in the $CAPATH. The $CAPATH is an environment variable that defines where all files (keys, certificates, etc.) are stored. It is essential to have this folder in a safe place.

$CPATH structure:


$CPATH
├── <CA Common Name>
    ├── ca
    │   ├── <CA Common Name>.crl
    │   ├── <CA Common Name>.crt
    │   ├── key.pem
    │   └── key.pub
    └── certs
        └── <Certificate Common Name>
            ├── <Certificate Common Name>.crt
            ├── <Certificate Common Name>.csr
            ├── key.pem
            └── key.pub

GoCA also make it easier to manipulate files such as Private and Public Keys, Certificate Signing Request, Certificate Request Lists, and Certificates for other Go applications.

This example shows

  1. Creating a Certificate Authority (Root) or Loading if it already exists
  2. Issue a new Certificate
  3. Shows the certificate

// Define the GOCAPTH (Default is current dir)
os.Setenv("CAPATH", "/opt/GoCA/CA")

// RootCAIdentity for creation
rootCAIdentity := goca.Identity{
    Organization:       "GO CA Root Company Inc.",
    OrganizationalUnit: "Certificates Management",
    Country:            "NL",
    Locality:           "Noord-Brabant",
    Province:           "Veldhoven",
    Intermediate:       false,
}

// (1) Create the New Root CA or loads existent from disk ($CAPATH)
RootCA, err := goca.New("mycompany.com", rootCAIdentity)
if err != nil {
    // Loads in case it exists
    fmt.Println("Loading CA")
    RootCA, err = goca.Load("gocaroot.nl")
    if err != nil {
        log.Fatal(err)
    }

    // Check the CA status and shows the CA Certificate
    fmt.Println(RootCA.Status())
    fmt.Println(RootCA.GetCertificate())

} else {
    log.Fatal(err)
}

// (2) Issue certificate for example intranet server
intranetIdentity := goca.Identity{
    Organization:       "Intranet Company Inc.",
    OrganizationalUnit: "Global Intranet",
    Country:            "NL",
    Locality:           "Noord-Brabant",
    Province:           "Veldhoven",
    Intermediate:       false,
    DNSNames:           []string{"w3.intranet.example.com", "www.intranet.example.com"},
}

intranetCert, err := RootCA.IssueCertificate("intranet.example.com", intranetIdentity)
if err != nil {
    log.Fatal(err)
}

// (3) Shows the Certificate (string)
fmt.Println(intranetCert.GetCertificate())

// Shows all CA Certificates
fmt.Println(RootCA.ListCertificates())

GoCA HTTP REST API

GoCA also provides an implementation using HTTP REST API.

This is available in rest-api folder.

GoCA Docker Container

GoCA Docker ready to use HTTP Rest API that uses mainly crypto/x509 to manage Certificate Authorities and Certificates such as a simple PKI Service.

The API Documentation is online available at http://kairoaraujo.github.io/goca/.

More details in Docker README.

GoCA Docker Image is available at https://hub.docker.com/r/kairoaraujo/goca/

Contributing

See CONTRIBUTING.

Documentation

Overview

Package goca provides Certificate Authority (CA) framework managing

GoCA is an API Framework that uses mainly crypto/x509 to manage Certificate Authorities.

Using GoCA makes easy to create a CA and issue certificates, signing Certificates Signing Request (CSR) and revoke certificate generating Certificates Request List (CRL).

All files are stored in the “$CAPATH“. The “$CAPATH“ is an environment variable the defines were all files (keys, certificates, etc) will be stored. It is importante to have this folder in a safety place.

GoCA also make easier manipulate files such as Private and Public Keys, Certificate Signing Request, Certificate Request Lists and Certificates for other Go applications.

Example (Minimal)
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/MarcHammerSC/goca/"
)

func main() {

	// Define the GOCAPTH (Default is current dir)
	os.Setenv("CAPATH", "/opt/GoCA/CA")

	// RootCAIdentity for creation
	rootCAIdentity := goca.Identity{
		Organization:       "GO CA Root Company Inc.",
		OrganizationalUnit: "Certificates Management",
		Country:            "NL",
		Locality:           "Noord-Brabant",
		Province:           "Veldhoven",
		Intermediate:       false,
	}

	// Create the New Root CA or loads existent from disk ($CAPATH)
	RootCA, err := goca.New("mycompany.com", rootCAIdentity)
	if err != nil {
		// Loads in case it exists
		fmt.Println("Loading CA")
		RootCA, err = goca.Load("gocaroot.nl")
		if err != nil {
			log.Fatal(err)
		}

		// Check the CA status and shows the CA Certificate
		fmt.Println(RootCA.Status())
		fmt.Println(RootCA.GetCertificate())

	} else {
		log.Fatal(err)
	}

	// Issue certificate for example intranet server
	intranetIdentity := goca.Identity{
		Organization:       "Intranet Company Inc.",
		OrganizationalUnit: "Global Intranet",
		Country:            "NL",
		Locality:           "Noord-Brabant",
		Province:           "Veldhoven",
		Intermediate:       false,
		DNSNames:           []string{"w3.intranet.example.com", "www.intranet.example.com"},
	}

	intranetCert, err := RootCA.IssueCertificate("intranet.example.com", intranetIdentity)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(intranetCert.GetCertificate())

	// Shows all CA Certificates
	fmt.Println(RootCA.ListCertificates())
}
Output:

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrCAGenerateExists = errors.New("a Certificate Authority with this common name already exists")

ErrCAGenerateExists means that the CA with the same Common Name exists in the $CAPATH.

View Source
var ErrCALoadNotFound = errors.New("the requested Certificate Authority does not exist")

ErrCALoadNotFound means that CA was not found in $CAPATH to be loaded.

View Source
var ErrCAMissingInfo = errors.New("all CA details ('Organization', 'Organizational Unit', 'Country', 'Locality', 'Province') are required")

ErrCAMissingInfo means that all information goca.Information{} is required

View Source
var ErrCertLoadNotFound = errors.New("the requested Certificate does not exist")

ErrCertLoadNotFound means that certificate was not found in $CAPATH to be loaded.

View Source
var ErrCertRevoked = errors.New("the requested Certificate is already revoked")

ErrCertRevoked means that certificate was not found in $CAPATH to be loaded.

View Source
var ErrParentCommonNameNotSpecified = errors.New("parent common name is empty when creating an intermediate CA certificate")

Functions

func List

func List() []string

List list all existent Certificate Authorities in $CAPATH

Types

type CA

type CA struct {
	CommonName string // Certificate Authority Common Name
	Data       CAData // Certificate Authority Data (CAData{})
}

CA represents the basic CA data

func Load

func Load(commonName string) (ca CA, err error)

Load an existent Certificate Authority from $CAPATH

func New

func New(commonName string, identity Identity) (ca CA, err error)

New creat new Certificate Authority

func NewCA

func NewCA(commonName, parentCommonName string, identity Identity) (ca CA, err error)

New create a new Certificate Authority

func (*CA) GetCRL

func (c *CA) GetCRL() string

GetCRL returns Certificate Revocation List as x509 CRL string

func (*CA) GetCSR

func (c *CA) GetCSR() string

GetCSR returns the Certificate Signing Request as string

func (*CA) GetCertificate

func (c *CA) GetCertificate() string

GetCertificate returns Certificate Authority Certificate as string

func (*CA) GetPrivateKey

func (c *CA) GetPrivateKey() string

GetPrivateKey returns the Private Key as string

func (*CA) GetPublicKey

func (c *CA) GetPublicKey() string

GetPublicKey returns the PublicKey as string

func (*CA) GoCRL

func (c *CA) GoCRL() *x509.RevocationList

GoCRL returns Certificate Revocation List as Go bytes *x509.RevocationList

func (*CA) GoCSR

func (c *CA) GoCSR() *x509.CertificateRequest

GoCSR return the Certificate Signing Request as Go bytes *x509.CertificateRequest

func (*CA) GoCertificate

func (c *CA) GoCertificate() *x509.Certificate

GoCertificate returns Certificate Authority Certificate as Go bytes *x509.Certificate

func (*CA) GoPrivateKey

func (c *CA) GoPrivateKey() rsa.PrivateKey

GoPrivateKey returns the Private Key as Go bytes rsa.PrivateKey

func (*CA) GoPublicKey

func (c *CA) GoPublicKey() rsa.PublicKey

GoPublicKey returns the Public Key as Go bytes rsa.PublicKey

func (*CA) IsIntermediate

func (c *CA) IsIntermediate() bool

IsIntermediate returns if the CA is Intermediate CA (true)

func (*CA) IssueCertificate

func (c *CA) IssueCertificate(commonName string, id Identity, ExtKeyUsage []x509.ExtKeyUsage) (certificate Certificate, err error)

IssueCertificate creates a new certificate

It is import create an Identity{} with Certificate Client/Server information.

func (*CA) ListCertificates

func (c *CA) ListCertificates() []string

ListCertificates returns all certificates in the CA

func (*CA) LoadCertificate

func (c *CA) LoadCertificate(commonName string) (certificate Certificate, err error)

LoadCertificate loads a certificate managed by the Certificate Authority

The method ListCertificates can be used to list all available certificates.

func (*CA) RevokeCertificate

func (c *CA) RevokeCertificate(commonName string) error

RevokeCertificate revokes a certificate managed by the Certificate Authority

The method ListCertificates can be used to list all available certificates.

func (*CA) SignCSR

func (c *CA) SignCSR(csr x509.CertificateRequest, valid int, ExtKeyUsage []x509.ExtKeyUsage) (certificate Certificate, err error)

SignCSR perform a creation of certificate from a CSR (x509.CertificateRequest) and returns *x509.Certificate

func (*CA) Status

func (c *CA) Status() string

Status get details about Certificate Authority status.

type CAData

type CAData struct {
	CRL         string `json:"crl" example:"-----BEGIN X509 CRL-----...-----END X509 CRL-----\n"`                       // Revocation List string
	Certificate string `json:"certificate" example:"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n"`         // Certificate string
	CSR         string `json:"csr" example:"-----BEGIN CERTIFICATE REQUEST-----...-----END CERTIFICATE REQUEST-----\n"` // Certificate Signing Request string
	PrivateKey  string `json:"private_key" example:"-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----\n"`         // Private Key string
	PublicKey   string `json:"public_key" example:"-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----\n"`            // Public Key string

	IsIntermediate bool
	// contains filtered or unexported fields
}

A CAData represents all the Certificate Authority Data as RSA Keys, CRS, CRL, Certificates etc

type Certificate

type Certificate struct {
	Certificate   string `json:"certificate" example:"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n"`         // Certificate certificate string
	CSR           string `json:"csr" example:"-----BEGIN CERTIFICATE REQUEST-----...-----END CERTIFICATE REQUEST-----\n"` // Certificate Signing Request string
	PrivateKey    string `json:"private_key" example:"-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----\n"`         // Certificate Private Key string
	PublicKey     string `json:"public_key" example:"-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----\n"`            // Certificate Public Key string
	CACertificate string `json:"ca_certificate" example:"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\n"`      // CA Certificate as string
	// contains filtered or unexported fields
}

Certificate represents a Certificate data

func (*Certificate) GetCACertificate

func (c *Certificate) GetCACertificate() string

GetCACertificate returns the certificate as string.

func (*Certificate) GetCSR

func (c *Certificate) GetCSR() string

GetCSR returns the certificate as string.

func (*Certificate) GetCertificate

func (c *Certificate) GetCertificate() string

GetCertificate returns the certificate as string.

func (*Certificate) GoCACertificate

func (c *Certificate) GoCACertificate() x509.Certificate

GoCACertificate returns the certificate *x509.Certificate.

func (*Certificate) GoCSR

func (c *Certificate) GoCSR() x509.CertificateRequest

GoCSR returns the certificate as Go x509.Certificate.

func (*Certificate) GoCert

func (c *Certificate) GoCert() x509.Certificate

GoCert returns the certificate as Go x509.Certificate.

type Identity

type Identity struct {
	Organization       string   `json:"organization" example:"Company"`                         // Organization name
	OrganizationalUnit string   `json:"organization_unit" example:"Security Management"`        // Organizational Unit name
	Country            string   `json:"country" example:"NL"`                                   // Country (two letters)
	Locality           string   `json:"locality" example:"Noord-Brabant"`                       // Locality name
	Province           string   `json:"province" example:"Veldhoven"`                           // Province name
	EmailAddresses     string   `json:"email" example:"sec@company.com"`                        // Email Address
	DNSNames           []string `json:"dns_names" example:"ca.example.com,root-ca.example.com"` // DNS Names list
	IPAddresses        []net.IP `json:"ip_addresses,omitempty"`                                 // IP Address list
	Intermediate       bool     `json:"intermediate" example:"false"`                           // Intermendiate Certificate Authority (default is false)
	KeyBitSize         int      `json:"key_size" example:"2048"`                                // Key Bit Size (defaul: 2048)
	Valid              int      `json:"valid" example:"365"`                                    // Minimum 1 day, maximum 825 days -- Default: 397
}

A Identity represents the Certificate Authority Identity Information

Directories

Path Synopsis
MIT License
MIT License
Package cert provides RSA Key API management for crypto/x509 certificates.
Package cert provides RSA Key API management for crypto/x509 certificates.
Package docs Code generated by swaggo/swag.
Package docs Code generated by swaggo/swag.
Package key provides RSA Key API management for crypto/x509/rsa.
Package key provides RSA Key API management for crypto/x509/rsa.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL