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 ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultBufferSize = 16 * 1024
Functions ¶
This section is empty.
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.
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 ¶
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.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package gocrypto implements okapi interfaces using Go's crypto library.
|
Package gocrypto implements okapi interfaces using Go's crypto library. |
Package libcrypto implements okapi interfaces using OpenSSL's libcrypto library.
|
Package libcrypto implements okapi interfaces using OpenSSL's libcrypto library. |
Package mscng implements okapi interfaces using Microsoft CNG library (available on Windows Vista and later).
|
Package mscng implements okapi interfaces using Microsoft CNG library (available on Windows Vista and later). |