parlca

package
v0.4.243 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2025 License: ISC Imports: 18 Imported by: 0

Documentation

Overview

Package parlca is simple 2 ms type-safe self-signed certificate authority CA X509 ED25519 RSA ECDSA PKCS#8 PEM DER © 2021–present Harald Rudell <[email protected]>.

Index

Constants

View Source 
const (
	// extension for binary keys and certificates “.der”
	//	- der: Distinguished Encoding Rules binary format
	//	- mim types:
	//		‘application/pkix-cert’ certificate
	//		‘application/pkcs8’ key
	//		RFC 2585 for a DER-encoded X.509 certificate
	DerExt = ".der"
	// extension for text
	//	- private enhanced mail
	//	- mime-types:
	//		‘application/x-pem-file’
	//		‘application/x-x509-user-cert’
	//		‘application/x-x509-ca-cert’
	PemExt = ".pem"
)
View Source 
const (
	NoAppName   = ""
	DotLocalDir = ""
)
View Source 
const (
	DefaultCAName = ""
)
View Source 
const (
	NotFoundNotError = true
)
View Source 
const (
	RsaDefaultBits = 2048
)

Variables

This section is empty.

Functions

func CreateCredentials added in v0.4.241 

func CreateCredentials(
	algo x509.PublicKeyAlgorithm,
	canonicalName string,
	ipsAndDomains ...parl.AnyCount[pnet.Address],
) (
	cert parl.Certificate,
	serverSigner parl.PrivateKey,
	caCertDER parl.CertificateDer,
	caKey parl.PrivateKey,
	err error,
)

CreateCredentialsEd25519 returns TLS credentials and ca certificate and key

  • algo:
  • — x509.Ed25519 smallest key size but as of 2024 not supported by browsers
  • — x509.RSA the most commonly used algorithm for browsers
  • — x509.ECDSA
  • canonicalName: a name that uniquely identifies the CA. Signed certificates will refer to this string to identify the authority.
  • canonicalName parlca.DefaultCAName "": use default
  • — default common-name is “[hostname]ca-241231” ie. the host’s name, the word “ca” and a date6. On macOS, name is used to uniquify, so it must be unique.
  • ipsAndDomains: a list of IP literals and domain names for the certificate
  • ipsAndDomains missing: certificate is for localhost: “127.0.0.1” “::1” “localhost”
  • cert: binary server certificate. Typed byte-slice
  • — to get x509 struct, use cert.ParseCertificate
  • serverSigner: binary and crypto.Signer used to run the server. Implementation depends on algorithm but is typically a typed byte-slice with identifying methods
  • caCert: binary private key and binary DER ASN.1 certificate. Typed byte-slice
  • caKey the certificate authority private key. Typed byte-slice
  • err: empty domain-name or unexpected error from signing-code
  • —
  • browsers do not support ed25519, so other algorithms with larger keys should be used
  • ca subject is hostname + "ca"

func CreateEd25519 added in v0.4.241 

func CreateEd25519() (cert parl.Certificate, key parl.PrivateKey)

CreateEd25519 creates server credentials for testing without browser in less than 2 ms

  • macOS 26.0 250927 if certificate’s public key algorithm is ed25519, TLS handshake error is “certificate is using a broken key size”
  • — “certificate is not standards compliant” means unknown self-signed certificate authority
  • consider using github.com/haraldrudell/parl/parlca/calib.CertLocalhost RSA
  • to get x509 struct use cert.ParseCertificate
  • certificate cacnonical name is host’s name, valid for 10 years
  • panic on error which never happens

func CreateRSA added in v0.4.241 

func CreateRSA() (cert parl.Certificate, key parl.PrivateKey)

CreateRSA creates server credentials for testing without browser in 262 ms. RSA credentials can be parsed from pem in 850 µs. Ed25519 credential can be generated in 2 ms. calib exports rsa-2048 localhost credentials

func NewPrivateKey added in v0.4.26 

func NewPrivateKey(algo x509.PublicKeyAlgorithm) (privateKey parl.PrivateKey, err error)

NewPrivateKey returns key-pair for selected algorithm

func ParsePem added in v0.4.240 

func ParsePem(pemData parl.PemBytes) (
	certificate parl.Certificate,
	privateKey parl.PrivateKey,
	publicKey parl.PublicKey,
	err error,
)

ParsePem reads the content in a pem-format byte sequence

  • pemData: text pem-format data byte-sequence
  • certificate: non-nil if the first pem-block successfully parsed as a “CERTIFICATE”
  • privateKey: non-nil if the first pem contained a pkcs8 “PRIVATE KEY”
  • publicKey: non-nil if the first pem contained a pkix encoded “PUBLIC KEY”
  • can do rsa, ecdsa, ed25519 keys and x.509 certificates
  • reads the first pem-block present
  • errors:
  • — no pem-block found
  • — pem parsing failed
  • — a different pem block type was encountered

func ReadCredentials added in v0.4.241 

func ReadCredentials(certFile, keyFile string) (
	cert parl.Certificate,
	key parl.PrivateKey,
	isFileNotFound bool,
	err error,
)

ReadCredentials returns server credentials by reading pem files

  • isFileNotFound true: err is nil

func ReadOrCreateCredentials added in v0.4.241 

func ReadOrCreateCredentials(
	appName,
	dirName string,
	algo x509.PublicKeyAlgorithm,
	canonicalName string,
	log parl.PrintfFunc,
	ipsAndDomains ...parl.AnyCount[pnet.Address],
) (
	cert parl.Certificate,
	key parl.PrivateKey,
	err error,
)

ReadOrCreateCredentials does write-once server-credentials caching

  • appName: the app’s name used for naming files and directories
  • appName NoAppName "": use “test”
  • dirname: directory for pem format pki files
  • dirname DotLocalDir "": directory is: ~/.local/[appName]
  • algo: algorithm for keys and certificates
  • canonicalName: unique name for certificate authority
  • canonicalName DefaultCAName "": CA certificate subject is “[hostname]ca-[date6]” “hostca-251231”
  • log: printing filenames being written for certificates and keys
  • ipsAndDomains: the IP literals and domain names for which the certificate is valid
  • ipsAndDomains missing: IPs are “::1” “127.0.0.1” domains are “localhost”

func ReadPemFromFile added in v0.4.240 

func ReadPemFromFile(filename string, allowNotFound ...bool) (
	certificate parl.Certificate,
	privateKey parl.PrivateKey,
	publicKey parl.PublicKey,
	err error,
)

ReadPemFromFile reads a file for a single entity

  • either certificate, private key or public key or error

Types

type Certificate 

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

Certificate wraps a der format x509 certificate.

func NewCertificate added in v0.4.26 

func NewCertificate(certificateDer parl.CertificateDer, fieldp ...*Certificate) (certificate *Certificate)

NewCertificate returns an object that can produce:

func (*Certificate) DER 

func (c *Certificate) DER() (certificateDer parl.CertificateDer)

DER returns the binary der asn.1 format of the certificate

func (*Certificate) PEM added in v0.4.26 

func (c *Certificate) PEM() (pemBytes parl.PemBytes)

PEM returns a file-writable and human-readable pem block

  • “==… CERTIFICATE…”

func (*Certificate) ParseCertificate added in v0.4.26 

func (c *Certificate) ParseCertificate() (certificate *x509.Certificate, err error)

ParseCertificate returns expanded x509.Certificate format

  • allows certificate to be used as parent argument to x509.CreateCertificate
  • provides access to certificate datapoints

type EcdsaPrivateKey added in v0.4.26 

type EcdsaPrivateKey struct {
	*ecdsa.PrivateKey
}

EcdsaPrivateKey wraps a binary ecdsa key-pair with methods

func NewEcdsa added in v0.4.26 

func NewEcdsa(fieldp ...*EcdsaPrivateKey) (privateKey *EcdsaPrivateKey, err error)

NewEcdsa

  • —
  • returns pointer beacuse ecdsa can only generate pointer

func (*EcdsaPrivateKey) Algo added in v0.4.26 

func (key *EcdsaPrivateKey) Algo() (algo x509.PublicKeyAlgorithm)

Algo returns algorithm x509.ECDSA “ECDSA”

func (*EcdsaPrivateKey) DER added in v0.4.26 

func (key *EcdsaPrivateKey) DER() (bytes parl.PrivateKeyDer, err error)

DER returns PKCS#8 binary form

func (*EcdsaPrivateKey) DERe added in v0.4.26 

func (key *EcdsaPrivateKey) DERe() (privateKeyDer parl.PrivateKeyDer)

DERe returns PKCS#8 with panic on error

func (*EcdsaPrivateKey) PEM added in v0.4.26 

func (key *EcdsaPrivateKey) PEM() (pemBytes parl.PemBytes, err error)

PEM returns text format “-----PRIVATE KEY …”

func (*EcdsaPrivateKey) PEMe added in v0.4.26 

func (key *EcdsaPrivateKey) PEMe() (pemBytes parl.PemBytes)

PEMe returns text format “-----PRIVATE KEY …” panic on error

func (*EcdsaPrivateKey) PublicKey added in v0.4.26 

func (key *EcdsaPrivateKey) PublicKey() (publicKey parl.PublicKey)

PublicKey returns the key-pair’s public key

func (*EcdsaPrivateKey) Validate added in v0.4.26 

func (key *EcdsaPrivateKey) Validate() (err error)

Validate ensures a private key is present

type EcdsaPublicKey added in v0.4.26 

type EcdsaPublicKey struct {
	ecdsa.PublicKey
}

EcdsaPublicKey is container for public key in efficient binary form

func (*EcdsaPublicKey) Algo added in v0.4.26 

func (key *EcdsaPublicKey) Algo() (algo x509.PublicKeyAlgorithm)

Algo returns algorithm x509.ECDSA “ECDSA”

func (*EcdsaPublicKey) DER added in v0.4.26 

func (key *EcdsaPublicKey) DER() (publicKeyDer parl.PublicKeyDer, err error)

DER returns public key as PKCS#1 ASN.1 DER

func (*EcdsaPublicKey) DERe added in v0.4.26 

func (key *EcdsaPublicKey) DERe() (publicKeyDer parl.PublicKeyDer)

DERe returns public key as PKCS#1 ASN.1 DER panic on error

func (*EcdsaPublicKey) PEM added in v0.4.26 

func (key *EcdsaPublicKey) PEM() (pemBytes parl.PemBytes, err error)

PEM returns public key in text form “-----RSA PUBLIC KEY …”

func (*EcdsaPublicKey) PEMe added in v0.4.26 

func (key *EcdsaPublicKey) PEMe() (pemBytes parl.PemBytes)

PEMe returns public key in text form “-----RSA PUBLIC KEY …” panic on error

type Ed25519PrivateKey added in v0.4.26 

type Ed25519PrivateKey struct {
	// func (ed25519.PrivateKey).Equal(x crypto.PrivateKey) bool
	// func (ed25519.PrivateKey).Public() crypto.PublicKey
	// func (ed25519.PrivateKey).Seed() []byte
	// func (ed25519.PrivateKey).Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)
	// implements crypto.Signer: Public, Sign
	//	- type: []byte
	ed25519.PrivateKey
}

Ed25519 is efficient binary container for Ed25519 key-pair with wrapped methods

func MakeEd25519 added in v0.4.240 

func MakeEd25519() (privateKey Ed25519PrivateKey, err error)

MakeEd25519 returns Ed25519 key-pair implementing parl.PrivateKey and [cypto.Signer]

func (*Ed25519PrivateKey) Algo added in v0.4.26 

func (e *Ed25519PrivateKey) Algo() (algo x509.PublicKeyAlgorithm)

Algo returns algorithm x509.Ed25519 “Ed25519”

func (*Ed25519PrivateKey) DER added in v0.4.26 

func (e *Ed25519PrivateKey) DER() (privateKeyDer parl.PrivateKeyDer, err error)

DER returns PKCS#8 binary form

func (*Ed25519PrivateKey) DERe added in v0.4.26 

func (e *Ed25519PrivateKey) DERe() (privateKeyDer parl.PrivateKeyDer)

DERe returns PKCS#8 with panic on error

func (*Ed25519PrivateKey) PEM added in v0.4.26 

func (e *Ed25519PrivateKey) PEM() (pemBytes parl.PemBytes, err error)

PEM returns text format “-----PRIVATE KEY …”

func (*Ed25519PrivateKey) PEMe added in v0.4.26 

func (e *Ed25519PrivateKey) PEMe() (pemBytes parl.PemBytes)

PEMe returns text format “-----PRIVATE KEY …” panic on error

func (*Ed25519PrivateKey) PublicKey added in v0.4.26 

func (e *Ed25519PrivateKey) PublicKey() (publicKey parl.PublicKey)

PublicKey returns the key-pair’s public key

func (*Ed25519PrivateKey) Validate added in v0.4.26 

func (e *Ed25519PrivateKey) Validate() (err error)

Validate ensures a private key is present

type Ed25519PublicKey added in v0.4.26 

type Ed25519PublicKey struct {
	// Equal()
	ed25519.PublicKey
}

Ed25519PublicKey is public Ed25519 key

func (*Ed25519PublicKey) Algo added in v0.4.26 

func (key *Ed25519PublicKey) Algo() (algo x509.PublicKeyAlgorithm)

Algo returns algorithm x509.Ed25519 “Ed25519”

func (*Ed25519PublicKey) DER added in v0.4.26 

func (key *Ed25519PublicKey) DER() (publicKeyDer parl.PublicKeyDer, err error)

DER returns public key as PKCS#1 ASN.1 DER

func (*Ed25519PublicKey) DERe added in v0.4.26 

func (key *Ed25519PublicKey) DERe() (publicKeyDer parl.PublicKeyDer)

DERe returns public key as PKCS#1 ASN.1 DER panic on error

func (*Ed25519PublicKey) PEM added in v0.4.26 

func (key *Ed25519PublicKey) PEM() (pemBytes parl.PemBytes, err error)

PEM returns public key in text form “-----PUBLIC KEY …”

func (*Ed25519PublicKey) PEMe added in v0.4.26 

func (key *Ed25519PublicKey) PEMe() (pemBytes parl.PemBytes)

PEMe returns public key in text form “-----PUBLIC KEY …” panic on error

type RsaPrivateKey added in v0.4.26 

type RsaPrivateKey struct {
	// Decrypt(rand io.Reader, ciphertext []byte, opts crypto.DecrypterOpts) (plaintext []byte, err error)
	// Equal(x crypto.PrivateKey) bool
	// Precompute()
	// Public() crypto.PublicKey
	// Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
	// Size() int
	// Validate() error
	//	- 6 pointers 2 slices and int
	*rsa.PrivateKey
}

RsaPrivateKey wraps an RSA key-pair

  • a composite binary struct
  • rsa package can only generate pointer
  • rsa.PrivateKey is multiple fields with no self-referencing pointers, atomics or locks, ie. it can be copied
  • RsaPrivateKey will be used as parl.PrivateKey interface, meaning a pointer to it will be used
  • deserializing a key with x509.ParsePKCS8PrivateKey produces *rsa.PrivateKey
  • because the private key is always be a pointer, nothing is saved by copying it to a value-field but the copy incurs cost
  • a fieldp allows RsaPrivateKey to be stack-allocated or a field from a previous allocation

func NewRsa added in v0.4.26 

func NewRsa(fieldp ...*RsaPrivateKey) (privateKey *RsaPrivateKey)

NewRsa returns 2048-bit RSA private key-pair

func NewRsaBits added in v0.4.26 

func NewRsaBits(bits int, fieldp ...*RsaPrivateKey) (privateKey *RsaPrivateKey, err error)

NewRsaBits returns RSA private key-pair of specific bit-size

func (*RsaPrivateKey) Algo added in v0.4.26 

func (k *RsaPrivateKey) Algo() (algo x509.PublicKeyAlgorithm)

Algo returns algorithm x509.RSA “RSA”

func (*RsaPrivateKey) DER added in v0.4.26 

func (k *RsaPrivateKey) DER() (bytes parl.PrivateKeyDer, err error)

DER returns PKCS#8 binary form

func (*RsaPrivateKey) DERe added in v0.4.26 

func (k *RsaPrivateKey) DERe() (privateKeyDer parl.PrivateKeyDer)

DERe returns PKCS#8 with panic on error

func (*RsaPrivateKey) PEM added in v0.4.26 

func (k *RsaPrivateKey) PEM() (pemBytes parl.PemBytes, err error)

PEM returns text format “-----PRIVATE KEY …”

func (*RsaPrivateKey) PEMe added in v0.4.26 

func (k *RsaPrivateKey) PEMe() (pemBytes parl.PemBytes)

PEMe returns text format “-----PRIVATE KEY …” panic on error

func (*RsaPrivateKey) PublicKey added in v0.4.26 

func (k *RsaPrivateKey) PublicKey() (publicKey parl.PublicKey)

PublicKey returns the key-pair’s public key

func (*RsaPrivateKey) Validate added in v0.4.26 

func (k *RsaPrivateKey) Validate() (err error)

Validate ensures a private key is present

type RsaPublicKey added in v0.4.26 

type RsaPublicKey struct {
	rsa.PublicKey
}

RsaPublicKey is container for public key in efficient binary form

func (*RsaPublicKey) Algo added in v0.4.26 

func (key *RsaPublicKey) Algo() (algo x509.PublicKeyAlgorithm)

Algo returns x509.RSA “RSA”

func (*RsaPublicKey) DER added in v0.4.26 

func (key *RsaPublicKey) DER() (publicKeyDer parl.PublicKeyDer, err error)

DER returns public key as PKCS#1 ASN.1 DER

func (*RsaPublicKey) DERe added in v0.4.26 

func (key *RsaPublicKey) DERe() (publicKeyDer parl.PublicKeyDer)

DERe returns public key as PKCS#1 ASN.1 DER panic on error

func (*RsaPublicKey) PEM added in v0.4.26 

func (key *RsaPublicKey) PEM() (pemBytes parl.PemBytes, err error)

PEM returns public key in text form “-----RSA PUBLIC KEY …”

func (*RsaPublicKey) PEMe added in v0.4.26 

func (key *RsaPublicKey) PEMe() (pemBytes parl.PemBytes)

PEMe returns public key in text form “-----RSA PUBLIC KEY …” panic on error

type SelfSigned 

type SelfSigned struct {
	// DER() PEM()
	parl.Certificate
	PrivateKey parl.PrivateKey
}

SelfSigned is self0signed certificate authority

func NewSelfSigned 

func NewSelfSigned(
	canonicalName string,
	algo x509.PublicKeyAlgorithm,
	fieldp ...*SelfSigned,
) (ca *SelfSigned, err error)

NewSelfSigned creates a 10-year self-signed certificate authority

  • canonicalName: a name that uniquely identifies the CA. Signed certificates will refer to this string to identify the authority.
  • canonicalName DefaultCAName "": use default
  • — default common-name is “[hostname]ca-241231” ie. the host’s name, the word ca and a date6
  • algo:
  • — x509.Ed25519 smallest key size but as of 2024 not supported by browsers
  • — x509.RSA the most commonly used algorithm for browsers
  • — x509.ECDSA
  • ca: certificate authority with embedded private key
  • err: key generation failure, certificate creation failure
  • —
  • because parl.CertificateAuthority requires pointer, a pointer is returned
  • fieldp allows for stack-allocated or use of field from previous allocation
  • — implementation is parlca.Certificate, ie. binary der format

func NewSelfSignedFromKeyCert added in v0.4.240 

func NewSelfSignedFromKeyCert(
	privateKey parl.PrivateKey,
	certificate parl.Certificate,
	fieldp ...*SelfSigned,
) (ca *SelfSigned)

NewSelfSigned creates a self-signed certificate authority from existing cert and key possibly read from storage

func (*SelfSigned) Private added in v0.4.27 

func (ca *SelfSigned) Private() (privateKey parl.PrivateKey)

Private returns the certificate authority’s private key

func (*SelfSigned) Sign 

func (ca *SelfSigned) Sign(
	template *x509.Certificate,
	publicKey crypto.PublicKey,
) (certDER parl.CertificateDer, err error)

Sign returns an authorized certificate from an x509 struct

  • template is a populated x509 struct
  • publicKey is the key from a key-pair that will be inserted into the new certificate

func (*SelfSigned) Validate added in v0.4.240 

func (ca *SelfSigned) Validate() (cert *x509.Certificate, err error)

Validate validates the certificate authority and returns x509 struct format

Source Files

View all Source files

Directories

Path Synopsis
Package calib provides supporting identifiers for github.com/haraldrudell/parl/parlca RSA 2,048 Cert Key PEM for localhost © 2021–present Harald Rudell <[email protected]>.
 Package calib provides supporting identifiers for github.com/haraldrudell/parl/parlca RSA 2,048 Cert Key PEM for localhost © 2021–present Harald Rudell <[email protected]>.

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.