crypto

Documentation

Index

• Constants
• type AEAD
• type AEADTypeEnum
• type CFSSLClient
  • func NewCFSSLClient(logTags log.Fields, baseURL *url.URL, httpClient *resty.Client, ...) (CFSSLClient, error)
• type CertSigningRequestParams
• type ECDHKeyPair
• type ECDHSessionKeys
• type Engine
  • func NewEngine(logTags log.Fields) (Engine, error)
• type Hasher
• type SecureCSlice

Constants

const (
	// SodiumPBKDFOutputMin minimum PBKDF target key length
	SodiumPBKDFOutputMin = C.crypto_pwhash_BYTES_MIN
	// SodiumPBKDFOutputMax maximum PBKDF target key length
	SodiumPBKDFOutputMax = C.crypto_pwhash_BYTES_MAX

	// SodiumPBKDFPasswdMin minimum PBKDF input password length
	SodiumPBKDFPasswdMin = C.crypto_pwhash_PASSWD_MIN

	// SodiumPBKDFOpsLimitMin minimum PBKDF OPS limit
	SodiumPBKDFOpsLimitMin = C.crypto_pwhash_OPSLIMIT_MIN
	// SodiumPBKDFOpsLimitFast fast PBKDF OPS limit
	SodiumPBKDFOpsLimitFast = C.crypto_pwhash_OPSLIMIT_INTERACTIVE
	// SodiumPBKDFOpsLimitMed medium PBKDF OPS limit
	SodiumPBKDFOpsLimitMed = C.crypto_pwhash_OPSLIMIT_MODERATE
	// SodiumPBKDFOpsLimitSlow slow PBKDF OPS limit
	SodiumPBKDFOpsLimitSlow = C.crypto_pwhash_OPSLIMIT_SENSITIVE
	// SodiumPBKDFOpsLimitMax maximum PBKDF OPS limit
	SodiumPBKDFOpsLimitMax = C.crypto_pwhash_OPSLIMIT_MAX

	// SodiumPBKDFMemLimitMin minimum PBKDF MEM limit
	SodiumPBKDFMemLimitMin = C.crypto_pwhash_MEMLIMIT_MIN
	// SodiumPBKDFMemLimitFast fast PBKDF MEM limit
	SodiumPBKDFMemLimitFast = C.crypto_pwhash_MEMLIMIT_INTERACTIVE
	// SodiumPBKDFMemLimitMed medium PBKDF MEM limit
	SodiumPBKDFMemLimitMed = C.crypto_pwhash_MEMLIMIT_MODERATE
	// SodiumPBKDFMemLimitSlow slow PBKDF MEM limit
	SodiumPBKDFMemLimitSlow = C.crypto_pwhash_MEMLIMIT_SENSITIVE
	// SodiumPBKDFMemLimitMax maximum PBKDF MEM limit
	SodiumPBKDFMemLimitMax = C.crypto_pwhash_MEMLIMIT_MAX
)

Types

type AEAD

type AEAD interface {
	/*
		ExpectedKeyLen get the expected encryption key len

			@returns expected encryption key len
	*/
	ExpectedKeyLen() int

	/*
		SetKey set the encryption key

			@param key SecureCSlice - the encryption key
	*/
	SetKey(key SecureCSlice) error

	/*
		ExpectedNonceLen get the expected nonce len

			@returns expected nonce len
	*/
	ExpectedNonceLen() int

	/*
		SetNonce set the nonce

			@param nonce SecureCSlice - the nonce
	*/
	SetNonce(nonce SecureCSlice) error

	/*
		ResetNonce reset the AEAD nonce value

			@param ctxt context.Context - calling context
	*/
	ResetNonce(ctxt context.Context) error

	/*
		Type get the AEAD implementation

			@returns AEAD type
	*/
	Type() AEADTypeEnum

	/*
		Nonce return the current nonce value

			@returns the nonce
	*/
	Nonce() SecureCSlice

	/*
		ExpectedCipherLen compute the expected cipher text len given the plain text length

			@returns the expected cipher text length
	*/
	ExpectedCipherLen(plainTextLen int64) int64

	/*
		ExpectedPlainTextLen compute the expected plain text len given the cipher text length

			@returns the expected plain text length
	*/
	ExpectedPlainTextLen(cipherLen int64) int64

	/*
		Seal encrypt plain text with associated additional data.

			@param ctxt context.Context - calling context
			@param msgIndex int64 - the message index within a stream
			@param plainText []byte - the plain text to encrypt
			@param additional []byte - the associated additional data
			@param cipherText []byte - the output buffer for the cipher text
	*/
	Seal(
		ctxt context.Context, msgIndex int64, plainText []byte, additional []byte, cipherText []byte,
	) error

	/*
		Unseal decrypt cipher text with associated additional data.

			@param ctxt context.Context - calling context
			@param msgIndex int64 - the message index within a stream
			@param cipherText []byte - the cipher text to decrypt
			@param additional []byte - the associated additional data
			@param plainText []byte - the output buffer for plain text
	*/
	Unseal(
		ctxt context.Context, msgIndex int64, cipherText []byte, additional []byte, plainText []byte,
	) error
}

AEAD a AEAD engine

type AEADTypeEnum

type AEADTypeEnum string

AEADTypeEnum AEAD type description ENUM

const (
	AEADTypeXChaCha20Poly1305 AEADTypeEnum = "XChaCha20-Poly1305"
	AEADTypeAes256gcm         AEADTypeEnum = "AES256-GCM"
)

Supported AEAD types

type CFSSLClient

type CFSSLClient interface {
	/*
		SignCSR request CFSSL to sign a certificate signing request, and return the certificate

			@param ctxt context.Context - calling context
			@param csfPayload string - the CSR in PEM encoding
			@param certProfile string - the CFSSL cert profile to sign the cert with
			@returns the new certificate signed by CFSSL
	*/
	SignCSR(ctxt context.Context, csrPayload string, certProfile string) (string, error)
}

CFSSLClient client for interacting with CFSSL

func NewCFSSLClient

func NewCFSSLClient(
	logTags log.Fields,
	baseURL *url.URL,
	httpClient *resty.Client,
	requestIDHeader string,
) (CFSSLClient, error)

NewCFSSLClient define a new CFSSL client

@param logTags log.Fields - component log tags
@param baseURL string - CFSSL API base URL
@param httpClient *resty.Client - core HTTP client
@param requestIDHeader string - request tracking ID header field
@returns new CFSSL client

type CertSigningRequestParams

type CertSigningRequestParams struct {
	// Subject certificate subject
	Subject pkix.Name
	// DNSNames DNS subject alt name
	DNSNames []string
	// EmailAddresses Email subject alt name
	EmailAddresses []string
	// IPAddresses IP subject alt name
	IPAddresses []net.IP
	// URIs URI subject all name
	URIs []*url.URL
}

CertSigningRequestParams set of parameters needed when defining a CSR

type ECDHKeyPair

type ECDHKeyPair struct {
	// Private the private portion of the DC key pair
	Private SecureCSlice
	// Public the public portion of the DC key pair
	Public SecureCSlice
}

ECDHKeyPair a ECDH key pair

type ECDHSessionKeys

type ECDHSessionKeys struct {
	// RX key associated with data received from the other side
	RX SecureCSlice
	// TX key associated with data sent to the other side
	TX SecureCSlice
}

ECDHSessionKeys set of ECDH session keys

type Engine

type Engine interface {
	/*
		AllocateSecureCSlice allocate a libsodium secure memory backed slice

			@param length uint64 - length of the array
			@return CSlice object
	*/
	AllocateSecureCSlice(length int) (SecureCSlice, error)

	/*
		GetRandomBuf get a buffer of random data with the specified length

			@param ctxt context.Context - calling context
			@param length int - the length of the buffer to fill
	*/
	GetRandomBuf(ctxt context.Context, length int) (SecureCSlice, error)

	/*
		GetHasherKey get a key for the cryptographic hasher

			@param ctxt context.Context - calling context
			@returns new key
	*/
	GetHasherKey(ctxt context.Context) (SecureCSlice, error)

	/*
		GetHasher get a libsodium cryptographic hasher

			@param ctxt context.Context - calling context
			@param key CryptoCSlice - for keyed hashing function
			@returns the hasher
	*/
	GetHasher(ctxt context.Context, key SecureCSlice) (Hasher, error)

	/*
		GetPBKDFSalt get a salt for use with PBKDF

			@param ctxt context.Context - calling context
			@returns new salt
	*/
	GetPBKDFSalt(ctxt context.Context) (SecureCSlice, error)

	/*
		PBKDF perform password based key derivation

			@param ctxt context.Context - calling context
			@param passwd []byte - starting password
			@param salt CryptoCSlice - associated salt
			@param opsLimit uint64 - computation complexity limit
			@param memLimit uint64 - memory complexity limit (in bytes)
			@param outLength uint64 - target output key length
			@returns the generated key
	*/
	PBKDF(
		ctxt context.Context,
		passwd []byte,
		salt SecureCSlice,
		opsLimit uint64,
		memLimit uint64,
		outLength int,
	) (SecureCSlice, error)

	/*
		CreateED25519CSR create an ED25519 private key and associated certificate signing request

			@param ctxt context.Context - calling context
			@param csrParams CertSigningRequestParams - CSR generation parameters
			@returns the ed25519 private key and the associated certificate signing request
	*/
	CreateED25519CSR(
		ctxt context.Context, csrParams CertSigningRequestParams,
	) (ed25519.PrivateKey, []byte, error)

	/*
		ParseCertificateFromPEM parse a PEM block for a certificate

			@param ctxt context.Context - calling context
			@param certPem string - the PEM string
			@returns the parsed certificate
	*/
	ParseCertificateFromPEM(ctxt context.Context, certPem string) (*x509.Certificate, error)

	/*
		ReadED25519PublicKeyFromCert read the ED25519 public from certificate

			@param ctxt context.Context - calling context
			@param cert *x509.Certificate - certificate
			@returns the ED25519 public key
	*/
	ReadED25519PublicKeyFromCert(_ context.Context, cert *x509.Certificate) (ed25519.PublicKey, error)

	/*
		NewECDHKeyPair generate a new ECDH key pair

			@param ctxt context.Context - calling context
			@returns the generated key pair
	*/
	NewECDHKeyPair(ctxt context.Context) (ECDHKeyPair, error)

	/*
		ComputeClientECDHSessionKeys run client side ECDH and generate client side ECDH session keys

			@param ctxt context.Context - calling context
			@param clientKeys ECDHKeyPair - client ECDH key pair
			@param serverPublic SecureCSlice - server public key
			@returns client side ECDH session keys
	*/
	ComputeClientECDHSessionKeys(
		ctxt context.Context, clientKeys ECDHKeyPair, serverPublic SecureCSlice,
	) (ECDHSessionKeys, error)

	/*
		ComputeServerECDHSessionKeys run server side ECDH and generate server side ECDH session keys

			@param ctxt context.Context - calling context
			@param serverKeys ECDHKeyPair - server ECDH key pair
			@param clientPublic SecureCSlice - client public key
			@returns server side ECDH session keys
	*/
	ComputeServerECDHSessionKeys(
		ctxt context.Context, serverKeys ECDHKeyPair, clientPublic SecureCSlice,
	) (ECDHSessionKeys, error)

	/*
		GetAEAD define a new AEAD instance

			@param ctxt context.Context - calling context
			@param aeadType AEADTypeEnum - the AEAD implementation to use
			@returns the AEAD generator
	*/
	GetAEAD(ctxt context.Context, aeadType AEADTypeEnum) (AEAD, error)
}

Engine wrapper object for performing cryptographic operations on data

func NewEngine

func NewEngine(logTags log.Fields) (Engine, error)

NewEngine define a new Engine object.

@param logTags log.Fields - component log tags
@returns new Engine object

type Hasher

type Hasher interface {
	/*
		Update update the hash compute with new data

			@param buf []byte - new data
	*/
	Update(buf []byte) error

	/*
		Finalize finalize the hash computation
	*/
	Finalize() error

	/*
		GetHash query the computed hash
	*/
	GetHash() []byte
}

Hasher a cryptographic hash generator

type SecureCSlice

type SecureCSlice interface {
	/*
		Zero zero the contents of the buffer
	*/
	Zero() error

	/*
		GetLen return the length of slice

			@returns the slice length
	*/
	GetLen() (int, error)

	/*
		GetSlice return reference to the slice

			@returns the managed slice
	*/
	GetSlice() ([]byte, error)

	/*
		GetCArray return reference to the C buffer

			@returns the C slice
	*/
	GetCArray() (unsafe.Pointer, error)

	/*
		IncrementValue treat the content of the buffer as a large number, and increment by one
	*/
	IncrementValue() error

	/*
		AddValue treat the content of the buffer as a large number, and add another value to it.

			@param value *big.Int - the value to add to current content of the buffer
	*/
	AddValue(value *big.Int) error
}

SecureCSlice a CSlice specifically designed for use with crypto libraries. They implement additional features.