25. Implementation internals

Module Builtin


Method _get_setter

function(mixed_void:void)|zero _get_setter(object o, string varname)

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


Generic ValueType

__generic__ mixed ValueType = mixed


Method delay

Future delay(int|float seconds)


Method filter

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


Method get

ValueType get()


Method get

zero|ValueType get()


Method get_backend

Backend get_backend()


Method map

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


Method map_with

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


Method on_await

Future on_await(function(mixed, function(mixed, __unknown__ ... :void)|void:void) cb)


Method on_failure

Future on_failure(function(mixed, __unknown__ ... :void) cb, mixed ... extra)


Method on_success

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


Method promise_factory

Promise promise_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 recover(function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)


Method recover_with

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


Method set_backend

void set_backend(Backend backend)


Method then

Future then(function(ValueType, __unknown__ ... :mixed)|void onfullfillment, function(mixed, __unknown__ ... :mixed)|void onrejected, mixed ... extra)


Method thencatch

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


Method timeout

Future timeout(int|float seconds)


Method transform

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


Method transform

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


Method wait

Future wait()


Method zip

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


Constant is_sql_null

constant int Builtin.Null.is_sql_null

Description

SQL Null marker.

Deprecated

Replaced by is_val_null.


Constant is_val_null

constant int Builtin.Null.is_val_null

Description

Nonzero recognition constant.


Method encode_json

string encode_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


Generic ValueType

__generic__ mixed ValueType = mixed


Inherit Future

inherit Future(< ValueType >) : Future


Method failure

Promise failure(mixed value, int|void try)


Method future

Future future()


Method success

Promise success(ValueType value, int|void try)


Method try_failure

Promise try_failure(mixed value)


Method try_success

Promise try_success(ValueType value)

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

object cast_to_object(string oname, string current_file)


Method cast_to_program

program cast_to_program(string pname, string current_file, object|void handler)


Method compile_error

void compile_error(string file, int line, string err)


Method compile_warning

void compile_warning(string file, int line, string warn)


Method decode_charset

string decode_charset(string data, string charset)


Method describe_backtrace

string describe_backtrace(object|array trace, int|void line_width)


Method handle_error

void handle_error(array|object trace)


Method handle_import

mixed handle_import(string what, string|void current_file, object|void handler)


Method handle_include

string handle_include(string f, string current_file, bool local_include)


Method handle_inherit

program handle_inherit(string pname, string current_file, object|void handler)


Method read_include

string read_include(string path)


Method resolv

mixed resolv(string identifier, string|void current_file, object|void handler)


Method werror

void werror(string fmt, mixed ... args)


Method write

void write(string fmt, 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_marker Builtin.automap_marker(array arr, int depth)

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

int search(__builtin.Stack from, mixed item)

Description

Return the stack-depth to item.

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


Method _sizeof

int sizeof( __builtin.Stack arg )

Description

sizeof on a stack returns the number of entries in the stack.


Method _values

array values( __builtin.Stack arg )

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.


Method create

__builtin.Stack __builtin.Stack(int|void initial_size)

Description

An initial stack size can be given when a stack is cloned. The default value is 32.


Method pop

mixed pop(void|int val)

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


Method pop_to

void pop_to(int depth)

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


Method push

void push(mixed val)

Description

Push an element on the top of the stack.


Method quick_pop

void quick_pop(void|int val)

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


Method reset

void reset(int|void initial_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


Method set_stack

void set_stack(array stack)

Description

Sets the stacks content to the provided array.


Method top

mixed top()

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


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|void length)

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

string decrypt(string(8bit) key, string(8bit) data)

Description

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


Method encrypt

string encrypt(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_program set_decrypt_key(string(8bit) key, void|int force)

Description

Initializes the object for decryption.

See also

set_encrypt_key, crypt


Method set_encrypt_key

this_program set_encrypt_key(string(8bit) key, void|int force)

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

extern string(7bit) name()

Description

Return the name of the Curve.


Method new_scalar

string(8bit)|Gmp.mpz new_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

extern int size()

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(Point p)
__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|int x, Gmp.mpz|int y)
__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

string encode()

Description

Serialize the Point.

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


Method get_curve

global::this_program get_curve()

Description

Get the Crypto.ECC.Curve that this Point belongs to.


Method get_x
Method get_y

extern Gmp.mpz|string(8bit) get_x()
extern Gmp.mpz|string(8bit) get_y()

Description

Get the coordinates for the curve in the preferred representation.


Method get_x_num

Gmp.mpz get_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.mpz get_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

extern void set(Gmp.mpz|int x, Gmp.mpz|int y)
variant void set(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 constant string __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, int rounds, int bytes)

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, int rounds)

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

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)|zero eme_oaep_decode(string(8bit) message, string(8bit)|void label, function(string(8bit), int(0..):string(8bit))|void mgf)

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)|zero eme_oaep_encode(string(8bit) message, int(1..) bytes, string(8bit) seed, string(8bit)|void label, function(string(8bit), int(0..):string(8bit))|void mgf)

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)|zero emsa_pss_encode(string(8bit) message, int(1..) bits, string(8bit)|void salt, function(string(8bit), int(0..):string(8bit))|void mgf)

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

bool emsa_pss_verify(string(8bit) message, string(8bit) sign, int(1..) bits, int(0..)|void saltlen, function(string(8bit), int(0..):string(8bit))|void mgf)

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

variant string(8bit) hash(Stdio.File|Stdio.Buffer|String.Buffer|System.Memory source, int(0..)|void bytes)

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

int hotp(string(8bit) secret, int factor, int(1..)|void length)

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, int rounds, int bytes)

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, int rounds, int bytes)

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, int rounds, int bytes)

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)|void salt)

Description

Initializes the HKDF object with a RFC 5869 2.2 HKDF-Extract(salt, IKM) call.


Method expand

string(8bit) expand(string(8bit) info, int bytes)

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|string username)

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)|zero client_2(string(8bit) line, string pass)

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

bool client_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|zero server_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, int iters)

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)|zero server_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..)|void b)

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))|zero jwk(bool|void private_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_program set_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 constant string __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(string key)

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))|zero jose_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)|zero jose_sign(string(8bit) message, mapping(string(7bit):string(7bit)|int)|void headers)

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

bool equal(__builtin.Nettle.Sign from, mixed x)

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))|zero jose_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)|zero jose_sign(string(8bit) message, mapping(string(7bit):string(7bit)|int)|void headers, .Hash|void h)

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))|zero jwk(bool|void private_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)|zero jwk_thumbprint(.Hash h)

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

Description

Returns the PKCS-1 AlgorithmIdentifier.


Method pkcs_public_key

Sequence pkcs_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, .Hash h)

Description

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


Method pkcs_signature_algorithm_id

Sequence|zero pkcs_signature_algorithm_id(.Hash hash)

Description

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


Method pkcs_verify

bool pkcs_verify(string(8bit) message, .Hash h, string(8bit) sign)

Description

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


Method public_key_equal

bool public_key_equal(this_program other)

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)|void data)

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|void length)

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_program init(string(8bit)|void data)

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_program update(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

constant string __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

final int __builtin.Sql.FutureResult.affected_rows

Description

The number of affected rows.


Variable bindings

final mapping(string:mixed)|zero __builtin.Sql.FutureResult.bindings

Description

The parameter bindings belonging to the query.


Variable data

final array(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

final array(mapping(string:mixed))|zero __builtin.Sql.FutureResult.fields

Description

The description of the fields in a record.


Variable query

final string|zero __builtin.Sql.FutureResult.query

Description

The SQL query.


Variable status_command_complete

final string|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

final array(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

final this_program discard_records(int(-1..) over)

Parameter over

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


Method max_records

final this_program max_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

final this_program min_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

string sprintf(string format, ... __builtin.Sql.ZeroWrapper arg ... )

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:

Builtin

Gmp

_Stdio

_math

_system

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