Pike Manual

Home Docs

Module Builtin

Method _get_setter: function(mixed_void:void)|zero_get_setter(objecto, stringvarname)
Description: Get a setter for the variable named varname in object o.
Returns: Returns a Setter()->`()() for the variable if it exists, and UNDEFINED otherwise.
See also: object_variablep()

Class Builtin.Future (< ValueType >)

Description: Prototype class for Concurrent.Future.
See also: Concurrent.Future, Promise

Generic ValueType: __generic__mixedValueType = mixed

Method delay: Future(< ValueType >) delay(int|floatseconds)

Method filter: Future(< ValueType >) filter(function(ValueType, __unknown__ ... :bool) fun, mixed ... extra)

Method get: ValueTypeget()

Method get: zero|ValueTypeget()

Method get_backend: Backendget_backend()

Method map: Future(< mixed >) map(function(ValueType, __unknown__ ... :mixed) fun, mixed ... extra)

Method map_with: Future(< mixed >) map_with(function(ValueType, __unknown__ ... :Future(< mixed >)) fun, mixed ... extra)

Method on_await: Future(< ValueType >) on_await(function(mixed, function(mixed, __unknown__ ... :void)|void:void) cb)

Method on_failure: Future(< ValueType >) on_failure(function(mixed, __unknown__ ... :void) cb, mixed ... extra)

Method on_success: Future(< ValueType >) on_success(function(ValueType, __unknown__ ... :void) cb, mixed ... extra)

Method promise_factory: Promisepromise_factory()

Method query_failure_callbacks: array(function(mixed, __unknown__ ... :void)) query_failure_callbacks()

Method query_success_callbacks: array(function(ValueType, __unknown__ ... :void)) query_success_callbacks()

Method recover: Future(< mixed >) recover(function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Method recover_with: Future(< mixed >) recover_with(function(mixed, __unknown__ ... :Future(< mixed >)) fun, mixed ... extra)

Method set_backend: voidset_backend(Backendbackend)

Method then: Future(< mixed >) then(function(ValueType, __unknown__ ... :mixed)|voidonfullfillment, function(mixed, __unknown__ ... :mixed)|voidonrejected, mixed ... extra)

Method thencatch: Future(< mixed >) thencatch(function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)

Method timeout: Future(< ValueType >) timeout(int|floatseconds)

Method transform: Future(< mixed >) transform(function(ValueType, __unknown__ ... :Future(< mixed >)) fun, function(mixed, __unknown__ ... :Future(< mixed >)) fun, mixed ... extra)

Method transform: Future(< mixed >) transform(function(ValueType, __unknown__ ... :mixed) fun, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Method wait: Future(< ValueType >) wait()

Method zip: array(Future(< mixed >)) zip(array(Future(< mixed >)) others)
array(Future(< mixed >)) zip(Future(< mixed >) ... others)

Class Builtin.Null

Description: This class is used to implement the low-level aspects of Val.Null.
Note: This class should typically not be used directly. Use Val.Null instead.
Note: This class was previously available as Sql.Null. Any such use should be replaced with Val.Null.
Deprecated: Replaced by Val.Null.
See also: Val.Null, Val.null

Constant is_sql_null: constantint Builtin.Null.is_sql_null
Description: SQL Null marker.
Deprecated: Replaced by is_val_null.

Constant is_val_null: constantint Builtin.Null.is_val_null
Description: Nonzero recognition constant.

Method encode_json: stringencode_json()
Description: Defined for use with Standards.JSON.encode, so that it formats NULL as null.

Class Builtin.Pointer

Description: This class is used to implement the low-level aspects of Val.Pointer.
Note: This class should typically not be used directly. Use Val.Pointer instead.
See also: Val.Pointer

Class Builtin.Promise (< ValueType >)

Description: Prototype class for Concurrent.Promise.
See also: Concurrent.Promise, Future

Generic ValueType: __generic__mixedValueType = mixed

Inherit Future: inherit Future(< ValueType >) : Future

Method failure: Promise(< ValueType >) failure(mixedvalue, int|voidtry)

Method future: Future(< ValueType >) future()

Method success: Promise(< ValueType >) success(ValueTypevalue, int|voidtry)

Method try_failure: Promise(< ValueType >) try_failure(mixedvalue)

Method try_success: Promise(< ValueType >) try_success(ValueTypevalue)

Class Builtin.Setter

Description

Internal class for implementing setters.

This class is used by _get_setter().

See also

_get_setter()

Method `()

void res = Builtin.Setter()()

Description

Set the variable for the setter to val.

This is the function returned by _get_setter().

Class Builtin.__master

Description: Used to prototype the master object.

Method _main: void_main(array(string) argv, array(string) env)

Method cast_to_object: objectcast_to_object(stringoname, stringcurrent_file)

Method cast_to_program: programcast_to_program(stringpname, stringcurrent_file, object|voidhandler)

Method compile_error: voidcompile_error(stringfile, intline, stringerr)

Method compile_warning: voidcompile_warning(stringfile, intline, stringwarn)

Method decode_charset: stringdecode_charset(stringdata, stringcharset)

Method describe_backtrace: stringdescribe_backtrace(object|arraytrace, int|voidline_width)

Method handle_error: voidhandle_error(array|objecttrace)

Method handle_import: mixedhandle_import(stringwhat, string|voidcurrent_file, object|voidhandler)

Method handle_include: stringhandle_include(stringf, stringcurrent_file, boollocal_include)

Method handle_inherit: programhandle_inherit(stringpname, stringcurrent_file, object|voidhandler)

Method read_include: stringread_include(stringpath)

Method resolv: mixedresolv(stringidentifier, string|voidcurrent_file, object|voidhandler)

Method werror: voidwerror(stringfmt, mixed ... args)

Method write: voidwrite(stringfmt, mixed ... args)

Class Builtin.automap_marker

Description

This is an internal class used by __automap__().

It may show up during module dumping or in backtraces and the like.

It should in normal circumstances never be used directly.

See also

__automap__(), map()

Method create: Builtin.automap_markerBuiltin.automap_marker(arrayarr, intdepth)
Parameter arr: Array that __automap__() is to loop over.
Parameter depth: Recursion depth of arr where the loop will be.

Module __builtin

Description

Low-level modules.

This module contains various base classes that are intended to be inherited and/or used from C-code.

Some of the base classes are:

__builtin.Nettle.BlockCipher
Base class for block cipher algorithms.
__builtin.Sql.Connection
Base class for connections to SQL servers. It is a generic interface on top of which the DB server specific implement their specifics.
__builtin.Stack (aka ADT.LowLevelStack)
Simple stack implementation.

Inherit Builtin: inherit _static_modules.Builtin : Builtin

Module __builtin.Nettle

Class __builtin.Nettle.AE

Description

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.

See also

AEAD

Inherit Cipher: inherit __builtin.Nettle.Cipher : Cipher

Method `(): State res = __builtin.Nettle.AE()()
Description: Calling `() will return a State object.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Class __builtin.Nettle.AE.State

Description

This is the context for a single incrementally updated AE cipher.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Inherit State: inherit Cipher::State : State

Method digest: string(8bit)digest(int|voidlength)
Description: Generates a digest, and resets the hashing contents.
Parameter length: If the length argument is provided, the digest is truncated to the given length.
Returns: The digest.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Class __builtin.Nettle.AEAD

Description

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.

See also

AE

Inherit AE: inherit __builtin.Nettle.AE : AE

Inherit __Hash: inherit __builtin.Nettle.__Hash : __Hash

Method `(): State res = __builtin.Nettle.AEAD()()
Description: Calling `() will return a State object.

Class __builtin.Nettle.AEAD.State

Description

This is the context for a single incrementally updated AEAD cipher.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Inherit State: inherit Cipher::State : State

Inherit State: inherit __Hash::State : State

Class __builtin.Nettle.BlockCipher

Description

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.

Inherit Cipher: inherit .Cipher : Cipher

Module __builtin.Nettle.BlockCipher.CTR

Description

Implementation of Counter Mode (CTR). Works as a wrapper for the cipher algorithm in the parent module.

This cipher mode works like a stream cipher with a block size >= 1. This means that the same key and initialization vector (aka counter) should never be reused, since a simple xor would reveal information about the plain text. It also means that it should never be used without a suiteable Message Authentication Code (MAC).

See also

predef::Nettle.BlockCipher.CBC, predef::Nettle.BlockCipher.CCM, predef::Nettle.BlockCipher.GCM, MAC

Inherit Cipher: inherit .Cipher : Cipher

Method name: string(7bit)name()
Description: Returns the name of the base cipher extended with ".CTR".

Class __builtin.Nettle.BlockCipher.CTR.State

Description: The state for the embedded algorithm

Inherit this_program: inherit ::this_program : this_program

Class __builtin.Nettle.BlockCipher16Mixin

Description

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.

Class __builtin.Nettle.Cipher

Description

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.

See also

predef::Nettle.Cipher, Crypto.Cipher

Method `(): State res = __builtin.Nettle.Cipher()()
Description: Calling `() will return a State object.

Method block_size: int(0..)block_size()
Returns: The block size of the cipher (1 for stream ciphers).

Method decrypt: stringdecrypt(string(8bit)key, string(8bit)data)
Description: Works as a shortcut for obj->set_decrypt_key(key)->crypt(data)

Method encrypt: stringencrypt(string(8bit)key, string(8bit)data)
Description: Works as a shortcut for obj->set_encrypt_key(key)->crypt(data)

Method key_size: int(0..)key_size()
Returns: The recommended key size for the cipher.

Method name: string(7bit)name()
Description: Returns a human readable name for the algorithm.

Class __builtin.Nettle.Cipher.State

Description

This is the context for a single incrementally updated cipher.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Method block_size

int(0..)block_size()

Returns

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

Defaults to just returning global::block_size().

Method crypt: string(8bit)crypt(string(8bit)data)
Description: Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.
Parameter data: For block ciphers, data must be an integral number of blocks.
Returns: The encrypted or decrypted data.

Method key_size

int(0..)key_size()

Returns

The actual key size for this cipher.

Defaults to just returning global::key_size().

Method make_key: string(8bit)make_key()
Description: Generate a key by calling random_string and initialize the object for encryption with that key.
Returns: The generated key.
See also: set_encrypt_key

Method name

string(7bit)name()

Description

Returns a human readable name for the algorithm.

Defaults to just returning global::name().

Method set_decrypt_key: this_programset_decrypt_key(string(8bit)key, void|intforce)
Description: Initializes the object for decryption.
See also: set_encrypt_key, crypt

Method set_encrypt_key: this_programset_encrypt_key(string(8bit)key, void|intforce)
Description: Initializes the object for encryption.
See also: set_decrypt_key, crypt

Class __builtin.Nettle.ECC_Curve

Description: Base class for Elliptic Curve Definitions.
See also: Crypto.ECC.Curve, Nettle.ECC_Curve

Method jose_name: string(7bit)jose_name()
Description: Return the JOSE name of the Curve (if any).
Returns: The default implementation returns UNDEFINED.

Method name: externstring(7bit)name()
Description: Return the name of the Curve.

Method new_scalar: string(8bit)|Gmp.mpznew_scalar(function(int(0..):string(8bit)) rnd)
Description: Generate a new scalar suitable for use as an ECDSA private key or as an ECDH secret factor.
Note: Returns the scalar in the preferred representation for the Curve.

Method size: externintsize()
Description: Return the size in bits of a single coordinate on the curve.

Class __builtin.Nettle.ECC_Curve.Point

Description: Base class for a point on an elliptic curve.

Method create

__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point()
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(Pointp)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(mapping(string(7bit):int|Gmp.mpz|string(8bit)) p)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(mapping(string(7bit):string(7bit)) jwk)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(Gmp.mpz|intx, Gmp.mpz|inty)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(Stdio.Buffer|string(8bit)data)

Description

Initialize the object and optionally also select a point on the curve.

The point on the curve can be selected via either via specifying the two coordinates explicitly, or via

`Point`	A `Point` on the same `Curve` to copy.
`mapping(string(7bit):int\|Gmp.mpz)`	A mapping with integer coordinates `"x"` and `"y"`.
`mapping(string(7bit):string(7bit))`	A mapping representing a JWK for the `Point` on the same `Curve`.
`mapping(string(7bit):string(8bit))`	A mapping with coordinates `"x"` and `"y"` in big-endian.
`Stdio.Buffer\|string(8bit)`	The ANSI x9.62 representation of the `Point`. Cf `encode()`.

Note

Throws errors if the point isn't on the Curve.

Method encode

stringencode()

Description

Serialize the Point.

The default implementation serializes according to ANSI x9.62 encoding #4 (uncompressed point format).

Method get_curve: global::this_programget_curve()
Description: Get the Crypto.ECC.Curve that this Point belongs to.

Method get_x
Method get_y: externGmp.mpz|string(8bit)get_x()
externGmp.mpz|string(8bit)get_y()
Description: Get the coordinates for the curve in the preferred representation.

Method get_x_num: Gmp.mpzget_x_num()
Description: Get the numeric representation of the x coordinate.

Method get_x_str: string(8bit)get_x_str()
Description: Get the canonic string representation of the x coordinate.

Method get_y_num: Gmp.mpzget_y_num()
Description: Get the numeric representation of the y coordinate.

Method get_y_str: string(8bit)get_y_str()
Description: Get the canonic string representation of the y coordinate.

Method set: externvoidset(Gmp.mpz|intx, Gmp.mpz|inty)
variantvoidset(string(8bit)x, string(8bit)y)
Description: Set a new coordinate on the Curve for the Point.
Note: Some curves (eg Crypto.ECC.Curve25519 do not support numeric coordinates); on the other hand the SECP curves prefer numeric coordinates.

Class __builtin.Nettle.Hash

Description

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.

Inherit __Hash: inherit .__Hash : __Hash

Constant hmac_jwa_id: protected constantstring __builtin.Nettle.Hash.hmac_jwa_id
Description: JWS algorithm id (if any) for the HMAC sub-module. Overloaded by the actual implementations.

Method P_hash: string(8bit)P_hash(string(8bit)password, string(8bit)salt, introunds, intbytes)
Description: This is the Password-Based Key Derivation Function used in TLS.
Parameter password: The prf secret.
Parameter salt: The prf seed.
Parameter rounds: Ignored.
Parameter bytes: The number of bytes to generate.

Method `(): State res = __builtin.Nettle.Hash()()
Description: Calling `() will return a State object.

Method crypt_hash

string(7bit)crypt_hash(string(8bit)password, string(8bit)salt, int(0..)rounds)

Description

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.

Note

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.

See also

crypt_md5(), crypt_hash_pike()

Method crypt_hash_pike

string(7bit)crypt_hash_pike(string(8bit)password, string(8bit)salt, int(0..)rounds)

Description

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).

Note

Do not use unless you know what you are doing!

See also

crypt_md5(), crypt_hash()

Method crypt_pbkdf2

string(7bit)crypt_pbkdf2(string(8bit)password, string(7bit)salt, introunds)

Description

crypt()-style function using pbkdf2().

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

Note

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.

See also

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

Method crypt_php

string(7bit)crypt_php(string(8bit)password, string(7bit)salt, int(0..)|voidrounds)

Description

Password hashing PHP Portable Hash-style.

Parameter password

Password to hash.

Parameter salt

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

Parameter rounds

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$").

See also

crypt_hash(), Crypto.Password

Method eme_oaep_decode: string(8bit)|zeroeme_oaep_decode(string(8bit)message, string(8bit)|voidlabel, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: Decode an EME-OAEP encoded string.
Parameter message: Message to decode.
Parameter label: Label that was used when the message was encoded. Defaults to "".
Parameter mgf: Mask generation function to use. Defaults to mgf1().
Returns: Returns the decoded message on success, and 0 (zero) on failure.
Note: The decoder attempts to take a constant amount of time on failure.
See also: eme_oaep_encode(), RFC 3447 section 7.1.2

Method eme_oaep_encode: string(8bit)|zeroeme_oaep_encode(string(8bit)message, int(1..)bytes, string(8bit)seed, string(8bit)|voidlabel, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: This is the encoding algorithm used in RSAES-OAEP (RFC 3447 section 7.1.1).
Parameter message: Message to encode.
Parameter bytes: Number of bytes of destination encoding.
Parameter seed: A string of random bytes at least digest_size() long.
Parameter label: An optional encoding label. Defaults to "".
Parameter mgf: The mask generation function to use. Defaults to mgf1().
Returns: Returns the encoded string on success and 0 (zero) on failure (typically too few bytes to represent the result).
See also: eme_oaep_decode()

Method emsa_pss_encode: string(8bit)|zeroemsa_pss_encode(string(8bit)message, int(1..)bits, string(8bit)|voidsalt, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: This is the signature digest algorithm used in RSASSA-PSS (RFC 3447 section 9.1.1).
Parameter message: Message to sign.
Parameter bits: Number of bits in result.
Parameter salt: Random string to salt the signature. Defaults to the empty string.
Parameter mgf: Mask generation function to use. Defaults to mgf1().
Returns: Returns the signature digest on success and 0 (zero) on failure (typically too few bits to represent the result).
See also: emsa_pss_verify(), mgf1().

Method emsa_pss_verify: boolemsa_pss_verify(string(8bit)message, string(8bit)sign, int(1..)bits, int(0..)|voidsaltlen, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: This is the algorithm used to verify in RSASSA-PSS (RFC 3447 section 9.1.2).
Parameter message: Message that was signed.
Parameter sign: Signature digest to verify.
Parameter bits: Number of significant bits in sign.
Parameter saltlen: Length of the salt used.
Parameter mgf: Mask generation function to use. Defaults to mgf1().
Returns: Returns 1 on success and 0 (zero) on failure.
See also: emsa_pss_verify(), mgf1().

Method hash: string(8bit)hash(string(8bit)data)
Description: Works as a (possibly faster) shortcut for e.g. State(data)->digest(), where State is the hash state class corresponding to this Hash.
Parameter data: String to hash.
See also: Stdio.File, State()->update() and State()->digest().

Method hash

variantstring(8bit)hash(Stdio.File|Stdio.Buffer|String.Buffer|System.Memorysource, int(0..)|voidbytes)

Description

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

Parameter source

Object to read some data to hash from.

Parameter bytes

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

Method hotp

inthotp(string(8bit)secret, intfactor, int(1..)|voidlength)

Description

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.

Parameter secret

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

Parameter factor

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

Parameter length

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.

Method mgf1: string(8bit)mgf1(string(8bit)seed, int(0..)bytes)
Description: This is the mask generation function MFG1 from RFC 3447 appendix B.2.1.
Parameter seed: Seed from which the mask is to be generated.
Parameter bytes: Length of output.
Returns: Returns a pseudo-random string of length bytes.
Note: This function is compatible with the mask generation functions defined in PKCS #1, IEEE 1363-2000 and ANSI X9.44.

Method openssl_pbkdf

string(8bit)openssl_pbkdf(string(8bit)password, string(8bit)salt, introunds, intbytes)

Description

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.

FIXME

Derived from OpenSSL. Is there any proper specification?

It seems to be related to PBKDF1 from RFC 2898.

See also

pbkdf1(), pbkdf2(), crypt_password()

Method pbkdf1: string(8bit)pbkdf1(string(8bit)password, string(8bit)salt, introunds, intbytes)
Description: Password Based Key Derivation Function #1 from RFC 2898. This method is compatible with the one from PKCS#5 v1.5.
Parameter password
Parameter salt: Password and salt for the keygenerator.
Parameter rounds: The number of iterations to rehash the input.
Parameter bytes: The number of bytes of output. Note that this has an upper limit of the size of a single digest.
Returns: Returns the derived key.
Note: 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.
See also: hkdf(), pbkdf2(), openssl_pbkdf(), crypt_password()

Method pbkdf2: string(8bit)pbkdf2(string(8bit)password, string(8bit)salt, introunds, intbytes)
Description: Password Based Key Derivation Function #2 from RFC 2898, PKCS#5 v2.0.
Parameter password
Parameter salt: Password and salt for the keygenerator.
Parameter rounds: The number of iterations to rehash the input.
Parameter bytes: The number of bytes of output.
Returns: Returns the derived key.
See also: hkdf(), pbkdf1(), openssl_pbkdf(), crypt_password()

Method pkcs_digest: string(8bit)pkcs_digest(object|string(8bit)s)
Description: Make a PKCS-1 digest info block with the message s.
See also: Standards.PKCS.build_digestinfo()

Class __builtin.Nettle.Hash.HKDF

Description: HMAC-based Extract-and-Expand Key Derivation Function, HKDF, RFC 5869. This is very similar to pbkdf2, with a few important differences. HKDF can use an "info" string that binds a generated password to a specific use or application (e.g. port number or cipher suite). It does not however support multiple rounds of hashing to add computational cost to brute force attacks.

Method create: __builtin.Nettle.Hash.HKDF__builtin.Nettle.Hash.HKDF(string(8bit)password, string(8bit)|voidsalt)
Description: Initializes the HKDF object with a RFC 5869 2.2 HKDF-Extract(salt, IKM) call.

Method expand: string(8bit)expand(string(8bit)info, intbytes)
Description: This is similar to the RFC 5869 2.3 HKDF-Expand(PRK, info, L) function, but PRK is taken from the object.

Method extract: string(8bit)extract(string(8bit)password)
Description: This is similar to the RFC 5869 2.2 HKDF-Extract(salt, IKM) function, but the salt is the previously generated PRK.

Class __builtin.Nettle.Hash.SCRAM

Description

SCRAM, defined by RFC 5802.

This implements both the client- and the serverside. You normally run either the server or the client, but if you would run both (use a separate client and a separate server object!), the sequence would be:

client_1 -> server_1 -> server_2 -> client_2 -> server_3 -> client_3

Note

If you are a client, you must use the client_* methods; if you are a server, you must use the server_* methods. You cannot mix both client and server methods in a single object.

Note

This implementation does not pretend to support the full protocol. Most notably optional extension arguments are not supported (yet).

See also

client_1, server_1

Method client_1: string(7bit)client_1(void|stringusername)
Description: Client-side step 1 in the SCRAM handshake.
Parameter username: The username to feed to the server. Some servers already received the username through an alternate channel (usually during the hash-function selection handshake), in which case it should be omitted here.
Returns: The client-first request to send to the server.
See also: client_2

Method client_2: string(7bit)|zeroclient_2(string(8bit)line, stringpass)
Description: Client-side step 2 in the SCRAM handshake.
Parameter line: The received server-first challenge from the server.
Parameter pass: The password to feed to the server.
Returns: The client-final response to send to the server. If the response is null, the server sent something unacceptable or unparseable.
See also: client_3

Method client_3: boolclient_3(string(8bit)line)
Description: Final client-side step in the SCRAM handshake. If we get this far, the server has already verified that we supplied the correct credentials. If this step fails, it means the server does not have our credentials at all and is an imposter.
Parameter line: The received server-final verification response.
Returns: True if the server is valid, false if the server is invalid.

Method server_1: string|zeroserver_1(string(8bit)line)
Description: Server-side step 1 in the SCRAM handshake.
Parameter line: The received client-first request from the client.
Returns: The username specified by the client. Returns null if the response could not be parsed.
See also: server_2

Method server_2: string(7bit)server_2(string(8bit)salt, intiters)
Description: Server-side step 2 in the SCRAM handshake.
Parameter salt: The salt corresponding to the username that has been specified earlier.
Parameter iters: The number of iterations the hashing algorithm should perform to compute the authentication hash.
Returns: The server-first challenge to send to the client.
See also: server_3

Method server_3: string(7bit)|zeroserver_3(string(8bit)line, string(8bit)salted_password)
Description: Final server-side step in the SCRAM handshake.
Parameter line: The received client-final challenge and response from the client.
Parameter salted_password: The salted (using the salt provided earlier) password belonging to the specified username.
Returns: The server-final response to send to the client. If the response is null, the client did not supply the correct credentials or the response was unparseable.

Module __builtin.Nettle.Hash.HMAC

Description

HMAC (Hashing for Message Authenticity Control) for the hash algorithm. Typically used as e.g. Crypto.SHA256.HMAC(key)(data) or Crypto.SHA256.HMAC(key)->update(data)->update(more_data)->digest().

RFC 2104.

See also

Crypto.HMAC

Inherit MAC: inherit .MAC : MAC

Method `(): State res = __builtin.Nettle.Hash()()
Description: Returns a new State object initialized with a password, and optionally block size b. Block size defaults to the hash function block size.

Method iv_size: int(0)iv_size()
Description: HMAC has no modifiable iv.

Method jwa: string(7bit)jwa()
Description: JWS algorithm identifier (if any, otherwise 0).
See also: RFC 7518 section 3.1

Method key_size: int(0..)key_size()
Description: Returns the block size of the encapsulated hash.
Note: Other key sizes are allowed, and will be expanded/compressed to this size.

Class __builtin.Nettle.Hash.HMAC.State

Description: The HMAC hash state.

Inherit this_program: inherit ::this_program : this_program

Method `()

string(8bit) res = __builtin.Nettle.Hash.HMAC.State()()

Description

Hashes the text according to the HMAC algorithm and returns the hash value.

This works as a combined update() and digest().

Method create: __builtin.Nettle.Hash.HMAC.State__builtin.Nettle.Hash.HMAC.State(string(8bit)passwd, int(1..)|voidb)
Parameter passwd: The secret password (K).
Parameter b: Block size. Must be larger than or equal to the digest_size(). Defaults to the block_size().

Method digest_info: string(8bit)digest_info(string(8bit)text)
Description: Hashes the text according to the HMAC algorithm and returns the hash value as a PKCS-1 digestinfo block.

Method jwk: mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_key)
Description: Generate a JWK-style mapping of the object.
Parameter private_key: Ignored.
Returns: Returns a JWK-style mapping on success, and 0 (zero) on failure.
See also: create(), Web.encode_jwk(), RFC 7517 section 4, RFC 7518 section 6.4

Method set_iv: this_programset_iv(string(8bit)iv)
Description: HMAC does not have a modifiable iv.

Class __builtin.Nettle.MAC

Description

Base class for Message Authentication Codes (MAC)s.

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

Inherit __Hash: inherit .__Hash : __Hash

Constant mac_jwa_id: protected constantstring __builtin.Nettle.MAC.mac_jwa_id
Description: JWS algorithm id (if any). Overloaded by the actual implementations.
Note: Never access this value directly. Use jwa().
See also: jwa()

Method iv_size

int(0..)iv_size()

Description

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.

Method jwa: string(7bit)jwa()
Description: JWS algorithm identifier (if any, otherwise 0).
See also: RFC 7518 section 3.1

Method key_size: int(0..)key_size()
Description: Returns the recomended size of the key.

Class __builtin.Nettle.MAC.State

Description: The state for the MAC.

Inherit this_program: inherit ::this_program : this_program

Method create: __builtin.Nettle.MAC.State__builtin.Nettle.MAC.State(stringkey)
Parameter key: The secret key for the hash.

Method iv_size

int(0..)iv_size()

Description

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.

Method jose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_decode(string(7bit)jws)

Description

Verify and decode a JOSE JWS MAC signed value.

Parameter jws

A JSON Web Signature as returned by jose_sign().

Returns

Returns 0 (zero) on failure, and an array

Array
`mapping(string(7bit):string(7bit)\|int) 0`	The JOSE header.
`string(8bit)1`	The signed message.

on success.

See also

jose_sign(), RFC 7515 section 3.5

Method jose_sign: string(7bit)|zerojose_sign(string(8bit)message, mapping(string(7bit):string(7bit)|int)|voidheaders)
Description: Signs the message with a JOSE JWS MAC signature.
Parameter message: Message to sign.
Parameter headers: JOSE headers to use. Typically a mapping with a single element "typ".
Returns: Returns the signature on success, and 0 (zero) on failure (typically that JOSE doesn't support this MAC).
See also: jose_decode(), RFC 7515

Method key_size: int(0..)key_size()
Description: Returns the recomended size of the key.

Class __builtin.Nettle.Sign

Description

Base class for cryptographic signature algorithms.

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

Method _equal

boolequal(__builtin.Nettle.Signfrom, mixedx)

Description

Check whether two objects are equivalent.

This includes checking both the public and private keys.

See also

public_key_equal()

Method jose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_decode(string(7bit)jws)

Description

Verify and decode a JOSE JWS signed value.

Parameter jws

A JSON Web Signature as returned by jose_sign().

Returns

Returns 0 (zero) on failure, and an array

Array
`mapping(string(7bit):string(7bit)\|int) 0`	The JOSE header.
`string(8bit)1`	The signed message.

Note

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).

See also

jose_sign(), pkcs_verify(), RFC 7515

Method jose_sign: string(7bit)|zerojose_sign(string(8bit)message, mapping(string(7bit):string(7bit)|int)|voidheaders, .Hash|voidh)
Description: Signs the message with a JOSE JWS signature using hash algorithm h and JOSE headers headers.
Parameter message: Message to sign.
Parameter headers: JOSE headers to use. Typically a mapping with a single element "typ".
Parameter h: Hash algorithm to use. Valid hashes depend on the signature algorithm. The default value depends on the signature algorithm.
Returns: Returns the signature on success, and 0 (zero) on failure (typically that either the hash algorithm is invalid for this signature algorithm),
Note: 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).
See also: jose_decode(), pkcs_sign(), RFC 7515

Method jwk: mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_key)
Description: Generate a JOSE JWK mapping representation of the object.
Parameter private_key: If true, include private fields in the result.
Returns: 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).
See also: Web.encode_jwk(), Web.decode_jwk(), RFC 7517 section 4

Method jwk_thumbprint

string(8bit)|zerojwk_thumbprint(.Hashh)

Description

Generate a JOSE JWK Thumbprint of the object.

Parameter h

Hash algorithm to use.

Returns

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.

See also

jwk(), RFC 7638

Method key_size: int(0..)key_size()
Description: Returns the number of bits in the private key.

Method name: string(7bit)name()
Description: Returns the printable name of the signing algorithm.

Method pkcs_algorithm_identifier: Sequence|zeropkcs_algorithm_identifier()
Description: Returns the PKCS-1 AlgorithmIdentifier.

Method pkcs_public_key: Sequencepkcs_public_key()
Description: Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.

Method pkcs_sign: string(8bit)pkcs_sign(string(8bit)message, .Hashh)
Description: Signs the message with a PKCS-1 signature using hash algorithm h.

Method pkcs_signature_algorithm_id: Sequence|zeropkcs_signature_algorithm_id(.Hashhash)
Description: Returns the PKCS-1 algorithm identifier for the signing algorithm with the provided hash algorithm.

Method pkcs_verify: boolpkcs_verify(string(8bit)message, .Hashh, string(8bit)sign)
Description: Verify PKCS-1 signature sign of message message using hash algorithm h.

Method public_key_equal: boolpublic_key_equal(this_programother)
Description: Check whether the public key is the same in two objects.
Note: This function differs from _equal() in that only the public key is regarded, and that it only needs to regard objects implementing Crypto.Sign.
See also: _equal()

Class __builtin.Nettle.__Hash

Description

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.

Method block_size: int(1..)block_size()
Description: Returns the internal block size of the hash algorithm.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Method name: string(7bit)name()
Description: Returns a human readable name for the algorithm.

Class __builtin.Nettle.__Hash.State

Description

This is the context for a single incrementally updated hash.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Method block_size: int(1..)block_size()
Description: Returns the internal block size of the hash algorithm.

Method create

__builtin.Nettle.__Hash.State__builtin.Nettle.__Hash.State(string(8bit)|voiddata)

Description

Create the new context, and optionally add some initial data to hash.

The default implementation calls update() with data if any, so there's usually no reason to override this function, since overriding update() should be sufficient.

Method digest: string(8bit)digest(int|voidlength)
Description: Generates a digest, and resets the hashing contents.
Parameter length: If the length argument is provided, the digest is truncated to the given length.
Returns: The digest.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Method init: this_programinit(string(8bit)|voiddata)
Description: Reset the context, and optionally add some initial data to the hash.

Method name: string(7bit)name()
Description: Returns a human readable name for the algorithm.

Method update: this_programupdate(string(8bit)data)
Description: Add some more data to hash.

Module __builtin.Sql

Description: Generic base classes for the Sql interfaces.

Constant QUERY_OPTION_CHARSET: constantstring __builtin.Sql.QUERY_OPTION_CHARSET
Description: Field to set in the query bindings mapping to set a character set for just the current query. Only supported by some databases.

Variable zero_arg: ZeroWrapper __builtin.Sql.zero_arg
Description: Instance of ZeroWrapper used by Connection()->handle_extraargs().

Class __builtin.Sql.FutureResult

Description: The promise result class; it will contain the results of a query.
See also: Promise, Connection.promise_query()

Variable affected_rows: finalint __builtin.Sql.FutureResult.affected_rows
Description: The number of affected rows.

Variable bindings: finalmapping(string:mixed)|zero __builtin.Sql.FutureResult.bindings
Description: The parameter bindings belonging to the query.

Variable data: finalarray(mixed)|zero __builtin.Sql.FutureResult.data
Description: The returned raw unadorned records, all typed data. Once get() has been accessed, data will point to the same adorned records.
See also: Sql.Connection->big_typed_query()

Variable fields: finalarray(mapping(string:mixed))|zero __builtin.Sql.FutureResult.fields
Description: The description of the fields in a record.

Variable query: finalstring|zero __builtin.Sql.FutureResult.query
Description: The SQL query.

Variable status_command_complete: finalstring|mixed __builtin.Sql.FutureResult.status_command_complete
Description: 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.

Method get: finalarray(mapping(string:mixed)) get()
Returns: The returned labeled records, all typed data.
See also: Sql.Connection->query(), data

Class __builtin.Sql.Promise

Description: 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.
See also: FutureResult, Connection.promise_query()

Inherit Promise: inherit Concurrent.Promise : Promise

Method discard_records: finalthis_programdiscard_records(int(-1..)over)
Parameter over: Discard any records over this number. -1 means do not discard any records (default).

Method max_records: finalthis_programmax_records(int(-1..)max)
Parameter max: If the query returns more than this number of records, fail the future. -1 means no maximum (default).

Method min_records: finalthis_programmin_records(int(0..)min)
Parameter min: If the query returns less than this number of records, fail the future. Defaults to 0.

Class __builtin.Sql.ZeroWrapper

Description: Wrapper to handle conversion of zero to NULL in Connection()->handle_extraargs().
See also: zero

Method _sprintf

stringsprintf(stringformat, ... __builtin.Sql.ZeroWrapperarg ... )

Returns

Returns the following:

`"NULL"`	If `fmt` is `'s'`.
`"ZeroWrapper()"`	If `fmt` is `'O'`.

Otherwise it formats a 0 (zero).

Variable _static_modules

object_static_modules

Description

This is an object containing the classes for all static (ie non-dynamic) C-modules.

In a typic Pike with support for dynamic modules the contained module classes are:

If the Pike binary lacks support for dynamic modules, all C-modules will show up here.

26. Implementation internals

Module Builtin

Class Builtin.Future (< ValueType >)

Class Builtin.Null

Class Builtin.Pointer

Class Builtin.Promise (< ValueType >)

Class Builtin.Setter

Class Builtin.__master

Class Builtin.automap_marker

Module __builtin

Module __builtin.Nettle

Class __builtin.Nettle.AE

Class __builtin.Nettle.AE.State

Class __builtin.Nettle.AEAD

Class __builtin.Nettle.AEAD.State

Class __builtin.Nettle.BlockCipher

Module __builtin.Nettle.BlockCipher.CTR

Class __builtin.Nettle.BlockCipher.CTR.State

Class __builtin.Nettle.BlockCipher16Mixin

Class __builtin.Nettle.Cipher

Class __builtin.Nettle.Cipher.State

Class __builtin.Nettle.ECC_Curve

Class __builtin.Nettle.ECC_Curve.Point

Class __builtin.Nettle.Hash

Class __builtin.Nettle.Hash.HKDF

Class __builtin.Nettle.Hash.SCRAM

Module __builtin.Nettle.Hash.HMAC

Class __builtin.Nettle.Hash.HMAC.State

Class __builtin.Nettle.MAC

Class __builtin.Nettle.MAC.State

Class __builtin.Nettle.Sign

Class builtin.Nettle.Hash

Class builtin.Nettle.Hash.State

Module __builtin.Sql

Class __builtin.Sql.FutureResult

Class __builtin.Sql.Promise

Class __builtin.Sql.ZeroWrapper

26. Implementation internals

Module Builtin

Class Builtin.Future (< ValueType >)

Class Builtin.Null

Class Builtin.Pointer

Class Builtin.Promise (< ValueType >)

Class Builtin.Setter

Class Builtin.__master

Class Builtin.automap_marker

Module __builtin

Module __builtin.Nettle

Class __builtin.Nettle.AE

Class __builtin.Nettle.AE.State

Class __builtin.Nettle.AEAD

Class __builtin.Nettle.AEAD.State

Class __builtin.Nettle.BlockCipher

Module __builtin.Nettle.BlockCipher.CTR

Class __builtin.Nettle.BlockCipher.CTR.State

Class __builtin.Nettle.BlockCipher16Mixin

Class __builtin.Nettle.Cipher

Class __builtin.Nettle.Cipher.State

Class __builtin.Nettle.ECC_Curve

Class __builtin.Nettle.ECC_Curve.Point

Class __builtin.Nettle.Hash

Class __builtin.Nettle.Hash.HKDF

Class __builtin.Nettle.Hash.SCRAM

Module __builtin.Nettle.Hash.HMAC

Class __builtin.Nettle.Hash.HMAC.State

Class __builtin.Nettle.MAC

Class __builtin.Nettle.MAC.State

Class __builtin.Nettle.Sign

Class __builtin.Nettle.__Hash

Class __builtin.Nettle.__Hash.State

Module __builtin.Sql

Class __builtin.Sql.FutureResult

Class __builtin.Sql.Promise

Class __builtin.Sql.ZeroWrapper

Class builtin.Nettle.Hash

Class builtin.Nettle.Hash.State