Pike Manual

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

Method_take_over_initial_predefines

mapping(string:mixed) _take_over_initial_predefines()

Description

Returns a mapping containing the set of predefined macros. These are typically the macros defined via the -D option when starting Pike.

This function is typically called by the MasterObject at initialization, and may only be called once. After it has been called, cpp() will start calling CompilationHandler->get_predefines() to retrieve the set of predefined macros.

See also

[cpp()], CompilationHandler->get_predefines()

Class Builtin.Future (< ValueType >)

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

GenericValueType: __generic__mixedValueType = mixed

Methoddelay: Futuredelay(int|floatseconds)

Methodfilter: Futurefilter(function(ValueType, __unknown__ ... :bool) fun, mixed ... extra)

Methodget: ValueTypeget()

Methodget: zero|ValueTypeget()

Methodget_backend: Backendget_backend()

Methodmap: Futuremap(function(ValueType, __unknown__ ... :mixed) fun, mixed ... extra)

Methodmap_with: Futuremap_with(function(ValueType, __unknown__ ... :Future) fun, mixed ... extra)

Methodon_await: Futureon_await(function(mixed, function(mixed, __unknown__ ... :void)|void:void) cb)

Methodon_failure: Futureon_failure(function(mixed, __unknown__ ... :void) cb, mixed ... extra)

Methodon_success: Futureon_success(function(ValueType, __unknown__ ... :void) cb, mixed ... extra)

Methodpromise_factory: Promisepromise_factory()

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

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

Methodrecover: Futurerecover(function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Methodrecover_with: Futurerecover_with(function(mixed, __unknown__ ... :Future) fun, mixed ... extra)

Methodset_backend: voidset_backend(Backendbackend)

Methodthen: Futurethen(function(ValueType, __unknown__ ... :mixed)|voidonfullfillment, function(mixed, __unknown__ ... :mixed)|voidonrejected, mixed ... extra)

Methodthencatch: Futurethencatch(function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)

Methodtimeout: Futuretimeout(int|floatseconds)

Methodtransform: Futuretransform(function(ValueType, __unknown__ ... :mixed) fun, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Methodtransform: Futuretransform(function(ValueType, __unknown__ ... :Future) fun, function(mixed, __unknown__ ... :Future) fun, mixed ... extra)

Methodwait: Futurewait()

Methodzip: array(Future) zip(array(Future) others)
array(Future) zip(Future ... 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

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

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

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

Class Builtin.Promise (< ValueType >)

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

GenericValueType: __generic__mixedValueType = mixed

InheritFuture: inherit Future(< ValueType >) : Future

Methodfailure: Promisefailure(mixedvalue, int|voidtry)

Methodfuture: Futurefuture()

Methodsuccess: Promisesuccess(ValueTypevalue, int|voidtry)

Methodtry_failure: Promisetry_failure(mixedvalue)

Methodtry_success: Promisetry_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)

Methodcast_to_object: objectcast_to_object(stringoname, stringcurrent_file)

Methodcast_to_program: programcast_to_program(stringpname, stringcurrent_file, object|voidhandler)

Methodcompile_error: voidcompile_error(stringfile, intline, stringerr)

Methodcompile_warning: voidcompile_warning(stringfile, intline, stringwarn)

Methoddecode_charset: stringdecode_charset(stringdata, stringcharset)

Methoddescribe_backtrace: stringdescribe_backtrace(object|arraytrace, int|voidline_width)

Methodhandle_error: voidhandle_error(array|objecttrace)

Methodhandle_import: mixedhandle_import(stringwhat, string|voidcurrent_file, object|voidhandler)

Methodhandle_include: stringhandle_include(stringf, stringcurrent_file, boollocal_include)

Methodhandle_inherit: programhandle_inherit(stringpname, stringcurrent_file, object|voidhandler)

Methodread_include: stringread_include(stringpath)

Methodresolv: mixedresolv(stringidentifier, string|voidcurrent_file, object|voidhandler)

Methodwerror: voidwerror(stringfmt, mixed ... args)

Methodwrite: 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()

Methodcreate: 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

Class __builtin.Stack

Description: This class implements a simple stack. Instead of adding and removing elements to an array, and thus making it vary in size for every push and pop operation, this stack tries to keep the stack size constant. If however the stack risks to overflow, it will allocate double its current size, i.e. pushing an element on an full 32 slot stack will result in a 64 slot stack with 33 elements.
Note: This class is usually accessed as ADT.LowLevelStack.

Method_search

intsearch(__builtin.Stackfrom, mixeditem)

Description

Return the stack-depth to item.

This function makes it possible to use eg search() and has_value() on the stack.

Method_sizeof: intsizeof(__builtin.Stackarg)
Description: sizeof on a stack returns the number of entries in the stack.

Method_values: arrayvalues(__builtin.Stackarg)
Description: values on a stack returns all the entries in the stack, in order.

Method`+: this_program res = __builtin.Stack() + s
Description: A stack added with another stack yields a new stack with all the elements from both stacks, and the elements from the second stack at the top of the new stack.

Methodcreate: __builtin.Stack__builtin.Stack(int|voidinitial_size)
Description: An initial stack size can be given when a stack is cloned. The default value is 32.

Methodpop: mixedpop(void|intval)
Description: Pops and returns entry val from the stack, counting from the top. If no value is given the top element is popped and returned. All popped entries are freed from the stack.
See also: quick_pop(), pop_to()

Methodpop_to

voidpop_to(intdepth)

Description

Pops entries from the stack until it reaches the specified depth.

The popped entries are not returned.

Throws

Throws an error if there are fewer than depth elements on the stack.

See also

pop(), quick_pop()

Methodpush: voidpush(mixedval)
Description: Push an element on the top of the stack.

Methodquick_pop: voidquick_pop(void|intval)
Description: Pops val entries from the stack, or one entry if no value is given. The popped entries are not returned.
See also: pop(), pop_to()

Methodreset: voidreset(int|voidinitial_size)
Description: Empties the stack, resets the stack pointer and shrinks the stack size to the given value or 32 if none is given.
See also: create

Methodset_stack: voidset_stack(arraystack)
Description: Sets the stacks content to the provided array.

Methodtop: mixedtop()
Description: Returns the top element from the stack, without popping it.
Throws: Throws an error if called on an empty stack.

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

InheritCipher: inherit __builtin.Nettle.Cipher : Cipher

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

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

InheritState: inherit Cipher::State : State

Methoddigest: 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.

Methoddigest_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

InheritAE: 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.

InheritState: inherit Cipher::State : State

InheritState: 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.

InheritCipher: 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

InheritCipher: inherit .Cipher : Cipher

Methodname: 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

Inheritthis_program: inherit ::this_program : this_program

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.

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

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

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

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

Methodname: 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.

Methodblock_size

int(0..)block_size()

Returns

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

Defaults to just returning global::block_size().

Methodcrypt: 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.

Methodkey_size

int(0..)key_size()

Returns

The actual key size for this cipher.

Defaults to just returning global::key_size().

Methodmake_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

Methodname

string(7bit)name()

Description

Returns a human readable name for the algorithm.

Defaults to just returning global::name().

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

Methodset_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

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

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

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

Methodsize: 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.

Methodcreate

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

Methodencode

stringencode()

Description

Serialize the Point.

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

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

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

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

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

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

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

Methodset: 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

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

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

Methodcrypt_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 also

crypt_md5(), crypt_hash_pike()

Methodcrypt_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()

Methodcrypt_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()

Methodcrypt_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

Methodeme_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

Methodeme_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()

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

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

Methodhash: 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().

Methodhash

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

Methodhotp

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.

Methodmgf1: 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.

Methodopenssl_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()

Methodpbkdf1: 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()

Methodpbkdf2: 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()

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

Methodcreate: __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.

Methodexpand: 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.

Methodextract: 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

Methodclient_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

Methodclient_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

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

Methodserver_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

Methodserver_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

Methodserver_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

InheritMAC: 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.

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

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

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

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

Methodcreate: __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().

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

Methodjwk: 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

Methodset_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

Constantmac_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()

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

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

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

Class __builtin.Nettle.MAC.State

Description: The state for the MAC.

Inheritthis_program: inherit ::this_program : this_program

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

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

Methodjose_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

Methodjose_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

Methodkey_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()

Methodjose_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

Methodjose_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

Methodjwk: 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

Methodjwk_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

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

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

Methodpkcs_algorithm_identifier: Sequencepkcs_algorithm_identifier()
Description: Returns the PKCS-1 AlgorithmIdentifier.

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

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

Methodpkcs_signature_algorithm_id: Sequencepkcs_signature_algorithm_id(.Hashhash)
Description: Returns the PKCS-1 algorithm identifier for the signing algorithm with the provided hash algorithm.

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

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

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

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

Methodname: 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.

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

Methodcreate

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

Methoddigest: 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.

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

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

Methodname: string(8bit)name()
Description: Returns a human readable name for the algorithm.

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

Module __builtin.Sql

Description: Generic base classes for the Sql interfaces.

Variablezero: ZeroWrapper __builtin.Sql.zero
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()

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

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

Variabledata: 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()

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

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

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

Methodget: 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()

InheritPromise: inherit Concurrent.Promise : Promise

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

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

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

25. Implementation internals

Module Builtin

Class Builtin.Future (< ValueType >)

Class Builtin.Null

Class Builtin.Promise (< ValueType >)

Class Builtin.Setter

Class Builtin.__master

Class Builtin.automap_marker

Module __builtin

Class __builtin.Stack

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

25. Implementation internals

Module Builtin

Class Builtin.Future (< ValueType >)

Class Builtin.Null

Class Builtin.Promise (< ValueType >)

Class Builtin.Setter

Class Builtin.__master

Class Builtin.automap_marker

Module __builtin

Class __builtin.Stack

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