25. Implementation internals

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


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 crypt_hash_pike() for details.

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

Sequence|zeropkcs_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

Sequence|zeropkcs_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(7bit)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.


ConstantQUERY_OPTION_CHARSET

constantstring __builtin.Sql.QUERY_OPTION_CHARSET

Description

Field to set in the query bindings mapping to set a character set for just the current query. Only supported by some databases.


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


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:

Builtin

Gmp

_Stdio

_math

_system

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