okapi

README

Okapi is a collection of interfaces providing universal API to third-party cryptographic libraries. The intent is to be able transparently mix and match implementations from various sources.

Subpackages implement these interfaces by calling external libraries (e.g. OpenSSL's libcrypto, or Microsoft's CNG). These subpackages serve both as default implemenations as well as templates for plugging in other libraries (e.g. cryptographic tokens, hardware accellerators, etc.)

Usage

An application will need to import both the general okapi package to get access to the API, but also any implementation packages that it wants to employ. However if the application doesn't use any implementation specific types directly, which should be the usual case, Go will complain about an unused import. In this case a blank import of the implementation has to be used, for example:

import (
  "github.com/mkobetic/okapi"
  _ "github.com/mkobetic/okapi/libcrypto"
)

See tests subdirectory for usage examples, the test files are mostly go testing style examples.

DONE

• libcrypto: hashes, symmetric ciphers, RSA, DSA and DH
• gocrypto: hashes and symmetric ciphers
• mscng: only a sketch of hash implementation, may not even compile yet (having difficulties with cgo dev on Windows)

TODO

• libcrypto: ECDH, ECDSA
• libcrypto: add PKCS8 import/export for PrivateKey
• libcrypto: add X.509 import/export for PublicKey
• libcrypto: portable signature import/export
• figure out proper GCM interface
• gocrypto: AEAD
• gocrypto: RSA, DSA, DH
• gocrypto: ECDSA, ECDH
• benchmarks
• mscng: catch up
• more test coverage

Documentation

Overview

Okapi is a collection of interfaces providing universal API to third-party cryptographic libraries. The intent is to be able transparently mix and match implementations from various sources.

Subpackages implement these interfaces by calling external libraries (e.g. OpenSSL's libcrypto, or Microsoft's CNG)

Index

• Variables
• type Cipher
• type CipherReader
  • func NewCipherReader(in io.Reader, cs CipherSpec, key, iv, buffer []byte) *CipherReader
  • func (r *CipherReader) Close() error
  • func (r *CipherReader) Read(out []byte) (int, error)
• type CipherSpec
• type CipherWriter
  • func NewCipherWriter(out io.Writer, cs CipherSpec, key, iv, buffer []byte) *CipherWriter
  • func (w *CipherWriter) Close() error
  • func (w *CipherWriter) Write(in []byte) (int, error)
• type Hash
• type HashSpec
• type KeyConstructor
• type MACSpec
• type PrivateKey
• type PublicKey
• type Random
• type RandomSpec

Variables

var DefaultBufferSize = 16 * 1024

Types

type Cipher

type Cipher interface {
	// Update processes (encrypts or decrypts) input slice and writes the result into the output slice.
	// It returns the number of bytes read and written. The input and output may be the same slice.
	// Update will return with no progress (0,0), if there is not at least
	// a block size worth of room in out slice.
	Update(in, out []byte) (ins, outs int)
	// Finish completes the last block of data and writes out whatever is left
	// in the internal buffers and returns the number of bytes written.
	// If the configured cipher mode requires multiples of block size of input (e.g. ECB, CBC),
	// Finish will panic if that condition wasn't met.
	// Update calls are not allowed after Finish is called.
	Finish(out []byte) int
	// BlockSize returns the block size of the underlying encryption algorithm in bytes.
	// For stream ciphers the block size is 1.
	BlockSize() int
	// KeySize returns the size of the encryption key in bytes. For some algorithms
	// it is constant for others it can be variable.
	KeySize() int
	// Close MUST be called to securely discard and release any associated secrets and resources.
	Close()
	// Cipher must keep track of how much buffered/unprocessed input it's buffering,
	// this should always be less than block size
	BufferedSize() int
}

Cipher is a symmetric/secret key encryption algorithm, meaning the same key is used to both encrypt and decrypt the data and therefore must be kept secret. The Cipher API is deliberately simple and consequently somewhat less convenient, CipherWriter and CipherReader should be used instead whenever possible.

type CipherReader

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

CipherReader decrypts bytes read from the underlying Reader. CipherReader MUST be closed before it's discarded.

func NewCipherReader

func NewCipherReader(in io.Reader, cs CipherSpec, key, iv, buffer []byte) *CipherReader

NewCipherReader creates CipherReader wrapped around provided Reader. The associated cipher is created from the provided CipherSpec, key and iv. The optional buffer is used internally. If buffer is not provided, it will be created with DefaultBufferSize.

func (*CipherReader) Close

func (r *CipherReader) Close() error

Close checks that there isn't any pending input left, then releases any associated resources, e.g. the cipher. If the underlying Reader is a Closer, then it Closes it as well.

func (*CipherReader) Read

func (r *CipherReader) Read(out []byte) (int, error)

Read reads necessary amount of input from the underlying Reader and decrypts it into the provided slice. It conforms to the io.Reader interface. Note that due to the nature of block ciphers, certain amount of read-ahead is necessary to provide the requested amount of bytes, although best effort is made to minimize the amount of read-ahead (generally only the input necessary to decrypt the last partially read block).

type CipherSpec

type CipherSpec interface {
	// New creates a Cipher from the CipherSpec, key and iv. The encrypt boolean
	// indicates whether the Cipher will be used for encryption or decryption.
	New(key, iv []byte, encrypt bool) Cipher
	// NewReader creates CipherReader wrapped around provided Reader.
	// The associated Cipher is created from the CipherSpec, key and iv.
	// The optional buffer is used internally. If buffer is not provided,
	// it will be created with DefaultBufferSize.
	NewReader(in io.Reader, key, iv, buffer []byte) *CipherReader
	// NewWriter creates CipherWriter wrapped around provided Writer.
	// The associated cipher is created from the CipherSpec, key and iv.
	// The optional buffer is used internally. If buffer is not provided,
	// it will be created with DefaultBufferSize.
	NewWriter(out io.Writer, key, iv, buffer []byte) *CipherWriter
}

CipherSpecs are used to create instances of Ciphers from a secret key and an optional initialization vector (iv).

var (
	AES_ECB, AES_CBC, AES_OFB, AES_CFB, AES_CTR, AES_GCM,
	BF_ECB, BF_CBC, BF_OFB, BF_CFB,
	DES3_ECB, DES3_CBC, DES3_OFB, DES3_CFB,
	RC4 CipherSpec
)

Predefined CipherSpecs for known encryption algorithms and modes. Implementations are provided by subpackages.` Note that the set of supported algorithms/modes can differ among implementations. If given algorithm/mode combination is not supported by the imported implementations, the value of the corresponding variable will be nil.

type CipherWriter

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

CipherWriter encrypts written bytes then writes the encrypted bytes into the underlying Writer. CipherWriter MUST be closed before it's discarded.

func NewCipherWriter

func NewCipherWriter(out io.Writer, cs CipherSpec, key, iv, buffer []byte) *CipherWriter

NewCipherWriter creates CipherWriter wrapped around the provided Writer. The associated cipher is created from the provided CipherSpec, key and iv. The optional buffer is used internally. If buffer is not provided, it will be created with DefaultBufferSize.

func (*CipherWriter) Close

func (w *CipherWriter) Close() error

Close finishes encryption of any pending input and writes it into the underlying Writer. Then it releases associated resources, e.g. the cipher. If the underlying Writer is a Closer, it will close it as well.

func (*CipherWriter) Write

func (w *CipherWriter) Write(in []byte) (int, error)

Write encrypts bytes from the provided slice and writes the encrypted bytes into the underlying writer.

type Hash

type Hash interface {
	// Write is used to submit input to the Hash compution.
	// It conforms to standard Writer interface
	Write([]byte) (int, error)
	// Digest finalizes the hash computation and provides the digest value.
	// No more input into the hash is possible after Digest is called (unless the Hash is Reset)
	Digest() []byte
	// Size returns the byte size of the digest value (this is constant
	// and depends solely on the type of hash algorithm used)
	Size() int
	// BlockSize returns byte size of the hash algorithm block (this is constant
	// and depends solely on the type of the hash algorithm used)
	BlockSize() int
	// Clone creates a complete copy of the Hash. The copy is in the same state
	// as if it processed the same input as the original Hash.
	// This can be used to obtain intermediate digest values or to diverge along different input paths.
	Clone() Hash
	// Reset reinitializes the Hash to initial state as if no input was processed yet.
	// This can be used to recycle Hash instances.
	Reset()
	// Close MUST be called before a Hash is discarded, to properly discard and release its associated resources
	Close()
}

Hash is a cryptographic hash algorithm that computes a fixed sized digest from arbitrary amount of byte input. Input is written into Hashes the same way as into Writers. Unlike hash.Hash, computing the digest finalizes the internal state of the Hash and no more input can be written into it (unless it is Reset first). If an intermediate digest is required, or the hash computation needs to diverge and continue along separate input lines, clone the Hash after processing the common initial part of the input.

type HashSpec

type HashSpec interface {
	New() Hash
}

HashSpecs are used to create instances of Hashes.

var (
	MD4, MD5, SHA1,
	SHA224, SHA256, SHA384, SHA512,
	RIPEMD160 HashSpec
)

Predefined HashSpecs for known hash algorithms. Implementations are provided by sub-packages.

type KeyConstructor

type KeyConstructor func(parameters interface{}) (PrivateKey, error)

KeyConstructor creates a PrivateKey for given algorithm and purpose. The parameters contain the required constituents of the key which are algorithm and key type specific. If parameters contain only public key constituents the constructor returns a partially initialized PrivateKey that can only be used to obtain a PublicKey from it. The parameters may also contain key generation parameters in which case a full PrivateKey will be generated

var (
	// encryption PKCS1 v1.5 & v2.0
	RSA, RSA_OAEP,

	RSA_MD5, RSA_SHA1, RSA_SHA224, RSA_SHA256, RSA_SHA384, RSA_SHA512,

	RSA_PSS_MD5, RSA_PSS_SHA1, RSA_PSS_SHA224, RSA_PSS_SHA256, RSA_PSS_SHA384, RSA_PSS_SHA512,

	DSA_SHA1, DSA_SHA224, DSA_SHA256, DSA_SHA384, DSA_SHA512,
	ECDSA_SHA1, ECDSA_224, ECDSA_SHA256, ECDSA_384, ECDSA_SHA512,

	DH, ECDH KeyConstructor
)

Predefined key constructors for known algorithms and purposes, implementations are provided by subpackages. Note that different implementations can support different set of algorithms/purposes. If given algorithm/purpose combination is not supported by the imported implementations, the value of the corresponding variable will be nil.

type MACSpec

type MACSpec interface {
	New(hash HashSpec, key []byte) Hash
}

MAC is a keyed Hash. MACs support the Hash interface, the only difference is That they require a HashSpec and a key being created. MACSpec is used to create instances of MACs.

var (
	HMAC MACSpec
)

Predefined MACSpecs for know MAC algorithms. Implementations are provided by sub-packages.

type PrivateKey

type PrivateKey interface {
	// Decrypt decrypts provided input.
	Decrypt(encrypted []byte) (decrypted []byte, err error)
	// Sign generates a signature for the provided input digest.
	// The digest must match the configured key type.
	// The signature format is algorithm specific
	Sign(digest []byte) (signature []byte, err error)
	// Derive generates a shared secret from the public key
	// provided by the other participant of the key agreement
	Derive(peer PublicKey) (secret []byte, err error)
	// Extract a PublicKey from the PrivateKey
	PublicKey() PublicKey
	// Close MUST be called before discarding a key instance to securely discard and release any associated resources.
	Close()
}

PrivateKey provides private key operations for given public key algorithm and purpose. The purpose determines which operations are available: * encryption: Decrypt * signing: Sign * key agreement: Derive

type PublicKey

type PublicKey interface {
	// Encrypt encrypts provided input.
	// Note that the size of input is constrained by the size of the PrivateKey
	Encrypt(plain []byte) (encrypted []byte, err error)
	// Verify checks whether provided signature matches the provided digest.
	// The digest and signature type must match the configured key type.
	Verify(signature []byte, digest []byte) (valid bool, err error)
	// Close MUST be called before discarding a key instance to securely discard and release any associated resources.
	Close()
}

PublicKey provides public key operations for given public key algorithm and purpose. The purpose determines which operations are available: * encryption: Encrypt * signing: Verify

type Random

type Random interface {
	// Read fills provided size with random bytes.
	Read([]byte) (int, error)
	// Close MUST be called before a Random is discarded, to properly discard and release its associated resources
	Close()
}

Random is a cryptographicly secure pseudo-random byte generator. The interface complies with io.Reader interface (similarly to crypto/rand package). The interface also include a Close method to allow resource release in specific implementations.

type RandomSpec

type RandomSpec interface {
	New() Random
}

RandomSpecs are used to create instances of Random.

var (
	// Default represents the default (unspecified) PRNG of imported implementation.
	DefaultRandom RandomSpec
)

Set of predefined (well known) RandomSpecs.