25. Implementation internals

Base class for AE (Authenticated Encryption) algorithms.

AE algorithms behave like a combination of a Cipher and a HMAC.

Note that no actual AE algorithm is implemented in the base class. They are implemented in classes that inherit this class.

AEAD

Calling `() will return a State object.

Returns the size of a hash digest.

Base class for AEAD (Authenticated Encryption with Associated Data) algorithms.

AEAD algorithms behave like a combination of a Cipher and a HMAC.

Note that no actual AEAD algorithm is implemented in the base class. They are implemented in classes that inherit this class.

AE

Calling `() will return a State object.

Base class for block cipher algorithms.

Implements some common convenience functions, and prototypes.

It also implements operating modes other than ECB.

Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit this class.

Mixin class for block cipher algorithms that have a 16 byte block size.

Implements some common convenience functions, and prototypes.

Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that (indirectly) inherit this class.

Base class for cipher algorithms.

Implements some common convenience functions, and prototypes.

Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit (usually via predef::Nettle.Cipher) this class.

predef::Nettle.Cipher, Crypto.Cipher

Calling `() will return a State object.

The block size of the cipher (1 for stream ciphers).

Works as a shortcut for obj->set_decrypt_key(key)->crypt(data)

Works as a shortcut for obj->set_encrypt_key(key)->crypt(data)

The recommended key size for the cipher.

Returns a human readable name for the algorithm.

Base class for Elliptic Curve Definitions.

Crypto.ECC.Curve, Nettle.ECC_Curve

Return the JOSE name of the Curve (if any).

The default implementation returns UNDEFINED.

Return the name of the Curve.

Generate a new scalar suitable for use as an ECDSA private key or as an ECDH secret factor.

Returns the scalar in the preferred representation for the Curve.

Return the size in bits of a single coordinate on the curve.

Base class for hash algorithms.

Implements common meta functions, such as key expansion algoritms and convenience functions.

Note that no actual hash algorithm is implemented in the base class. They are implemented in classes that inherit this class.

JWS algorithm id (if any) for the HMAC sub-module. Overloaded by the actual implementations.

This is the Password-Based Key Derivation Function used in TLS.

The prf secret.

The prf seed.

Ignored.

The number of bytes to generate.

Calling `() will return a State object.

Password hashing function in crypt_md5()-style.

Implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

This is the algorithm used by crypt(2) in methods $5$ (SHA256) and $6$ (SHA512). See crypt_hash_pike() for details.

In Pike 8.0.1876 and earlier this function generated incompatible hashes for passwords that had a length that was a power of 2. See crypt_hash_pike() for details.

crypt_md5(), crypt_hash_pike()

Password hashing function in crypt_md5()-style.

Almost implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

This function is provided for compatibility with hashes generated by Pike 8.0.1876 and earlier.

It differs from crypt_hash() for passwords that have a length that is a power of 2 (phase 11).

Do not use unless you know what you are doing!

crypt_md5(), crypt_hash()

crypt()-style function using pbkdf2().

Compatible with PassLib and Phpass password hashing schemes "pbdkf2", "pbdkf2-sha256" and "pbdkf2-sha512".

This function is provided for interoperability with password hashes provided from PassLib and/or Phpass. It is not recommended for use for new code, as this is not the indended use for the pbkdf2 algorithm.

pbkdf2(), Crypto.Password.hash(), Crypto.Password.verify()

Password hashing PHP Portable Hash-style.

Password to hash.

7 bit string of length 8 or 9. The first character may encode the exponent for the number of rounds if rounds is 0.

Number of rounds. Defaults to taking the value from the salt if the salt has length 9, otherwise defaults to 1<<19.

This algorithm used with Crypto.MD5 is the one used for PHP Portable Hashes (aka "$P$" and "$H$").

Used with Crypto.SHA1 it should be compatible with hashes from Escher CMS (aka "$Q$").

Used with Crypto.SHA512 it should be compatible with hashes from Drupal (aka "$S$").

crypt_hash(), Crypto.Password

Decode an EME-OAEP encoded string.

Message to decode.

Label that was used when the message was encoded. Defaults to "".

Mask generation function to use. Defaults to mgf1().

Returns the decoded message on success, and 0 (zero) on failure.

The decoder attempts to take a constant amount of time on failure.

eme_oaep_encode(), RFC 3447 section 7.1.2

This is the encoding algorithm used in RSAES-OAEP (RFC 3447 section 7.1.1).

Message to encode.

Number of bytes of destination encoding.

A string of random bytes at least digest_size() long.

An optional encoding label. Defaults to "".

The mask generation function to use. Defaults to mgf1().

Returns the encoded string on success and 0 (zero) on failure (typically too few bytes to represent the result).

eme_oaep_decode()

This is the signature digest algorithm used in RSASSA-PSS (RFC 3447 section 9.1.1).

Message to sign.

Number of bits in result.

Random string to salt the signature. Defaults to the empty string.

Mask generation function to use. Defaults to mgf1().

Returns the signature digest on success and 0 (zero) on failure (typically too few bits to represent the result).

emsa_pss_verify(), mgf1().

This is the algorithm used to verify in RSASSA-PSS (RFC 3447 section 9.1.2).

Message that was signed.

Signature digest to verify.

Number of significant bits in sign.

Length of the salt used.

Mask generation function to use. Defaults to mgf1().

Returns 1 on success and 0 (zero) on failure.

emsa_pss_verify(), mgf1().

Works as a (possibly faster) shortcut for e.g. State(data)->digest(), where State is the hash state class corresponding to this Hash.

String to hash.

Stdio.File, State()->update() and State()->digest().

Works as a (possibly faster) shortcut for e.g. State(   obj->read() )->digest(), where State is the hash state class corresponding to this Hash.

Object to read some data to hash from.

The number of bytes of the source object that should be hashed. Zero and negative values are ignored and the whole file is hashed. Support for negative values is deprecated.

Stdio.File, Stdio.Buffer, String.Buffer, System.Memory

HMAC-Based One-Time Password as defined by RFC 4226.

Can be used to implement the RFC 6238 Time-Based One-Time Password Algorithm by giving the factor (time()-T0)/X. Specifically for Google Authenticator this is Crypto.SHA1.hotp(secret,time()/30), using an 80 bit secret.

A shared secret between both parties. Typically the same size as the hash output.

A moving factor. Defined in RFC 4226 to be a counter synchronized between both parties.

The maximum number of digits of the one-time password. Defaults to 6. Note that the result is usually 0-padded to this length for user display purposes.

This is the mask generation function MFG1 from RFC 3447 appendix B.2.1.

Seed from which the mask is to be generated.

Length of output.

Returns a pseudo-random string of length bytes.

This function is compatible with the mask generation functions defined in PKCS #1, IEEE 1363-2000 and ANSI X9.44.

Password Based Key Derivation Function from OpenSSL.

This when used with Crypto.MD5 and a single round is the function used to derive the key to encrypt Standards.PEM body data.

pbkdf1(), pbkdf2(), crypt_password()

Password Based Key Derivation Function #1 from RFC 2898. This method is compatible with the one from PKCS#5 v1.5.

Password and salt for the keygenerator.

The number of iterations to rehash the input.

The number of bytes of output. Note that this has an upper limit of the size of a single digest.

Returns the derived key.

RFC 2898 does not recommend this function for anything else than compatibility with existing applications, due to the limits in the length of the generated keys.

hkdf(), pbkdf2(), openssl_pbkdf(), crypt_password()

Password Based Key Derivation Function #2 from RFC 2898, PKCS#5 v2.0.

Password and salt for the keygenerator.

The number of iterations to rehash the input.

The number of bytes of output.

Returns the derived key.

hkdf(), pbkdf1(), openssl_pbkdf(), crypt_password()

Make a PKCS-1 digest info block with the message s.

Standards.PKCS.build_digestinfo()

Base class for Message Authentication Codes (MAC)s.

These are hashes that have been extended with a secret key.

JWS algorithm id (if any). Overloaded by the actual implementations.

Never access this value directly. Use jwa().

jwa()

Returns the size of the iv/nonce (if any).

Some MACs like eg Crypto.SHA1.HMAC have fixed ivs, in which case this function will return 0.

JWS algorithm identifier (if any, otherwise 0).

RFC 7518 section 3.1

Returns the recomended size of the key.

Base class for cryptographic signature algorithms.

Typical classes implementing this API are Crypto.RSA, Crypto.DSA and Crypto.ECC.Curve.ECDSA.

Check whether two objects are equivalent.

This includes checking both the public and private keys.

public_key_equal()

Verify and decode a JOSE JWS signed value.

A JSON Web Signature as returned by jose_sign().

Returns 0 (zero) on failure, and an array

The default implementation returns 0 for all parameters, and can thus serve as a fallback for signature algorithms that don't support or aren't supported by JWS (eg Crypto.DSA).

jose_sign(), pkcs_verify(), RFC 7515

Signs the message with a JOSE JWS signature using hash algorithm h and JOSE headers headers.

Message to sign.

JOSE headers to use. Typically a mapping with a single element "typ".

Hash algorithm to use. Valid hashes depend on the signature algorithm. The default value depends on the signature algorithm.

Returns the signature on success, and 0 (zero) on failure (typically that either the hash algorithm is invalid for this signature algorithm),

The default implementation returns 0 for all parameters, and can thus serve as a fallback for signature algorithms that don't support or aren't supported by JWS (eg Crypto.DSA).

jose_decode(), pkcs_sign(), RFC 7515

Generate a JOSE JWK mapping representation of the object.

If true, include private fields in the result.

Returns a mapping as per RFC 7517 section 4 on success, and 0 (zero) on failure (typically that the object isn't initialized properly, or that it isn't supported by JWK).

Web.encode_jwk(), Web.decode_jwk(), RFC 7517 section 4

Generate a JOSE JWK Thumbprint of the object.

Hash algorithm to use.

Returns the thumbprint (ie hash of the public fields) on success, and 0 (zero) on failure (typically that the object isn't initialized properly, or that it isn't supported by JWK).

A typical use for this function is to generate a kid (key ID) value (cf RFC 7638 section 1.

jwk(), RFC 7638

Returns the number of bits in the private key.

Returns the printable name of the signing algorithm.

Returns the PKCS-1 AlgorithmIdentifier.

Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.

Signs the message with a PKCS-1 signature using hash algorithm h.

Returns the PKCS-1 algorithm identifier for the signing algorithm with the provided hash algorithm.

Verify PKCS-1 signature sign of message message using hash algorithm h.

Check whether the public key is the same in two objects.

This function differs from _equal() in that only the public key is regarded, and that it only needs to regard objects implementing Crypto.Sign.

_equal()

Base class for hash algorithms.

Note that no actual hash algorithm is implemented in the base class. They are implemented in classes that inherit this class.

Returns the internal block size of the hash algorithm.

Returns the size of a hash digest.

Returns a human readable name for the algorithm.

The promise result class; it will contain the results of a query.

Promise, Connection.promise_query()

The number of affected rows.

The parameter bindings belonging to the query.

The returned raw unadorned records, all typed data. Once get() has been accessed, data will point to the same adorned records.

Sql.Connection->big_typed_query()

The description of the fields in a record.

The SQL query.

The status of the completed command. If the command is still in progress, the value is null. If an error has occurred, it contains the backtrace of that error.

The returned labeled records, all typed data.

Sql.Connection->query(), data

This class is the base class for promise based SQL queries. future() will return a future which carries FutureResult objects to contain the result of the query.

FutureResult, Connection.promise_query()

Discard any records over this number. -1 means do not discard any records (default).

If the query returns more than this number of records, fail the future. -1 means no maximum (default).

If the query returns less than this number of records, fail the future. Defaults to 0.

Wrapper to handle conversion of zero to NULL in Connection()->handle_extraargs().

zero

Returns the following:

Otherwise it formats a 0 (zero).