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 objecto
.- Returns
Returns a
Setter()->`()()
for the variable if it exists, andUNDEFINED
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 callingCompilationHandler->get_predefines()
to retrieve the set of predefined macros.- See also
[cpp()],
CompilationHandler->get_predefines()
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 withVal.Null
.- Deprecated
Replaced by
Val.Null
.- See also
Val.Null
,Val.null
- Methodencode_json
string
encode_json()- Description
Defined for use with
Standards.JSON.encode
, so that it formats NULL asnull
.
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
object
cast_to_object(string
oname
,string
current_file
)
- Methodcast_to_program
program
cast_to_program(string
pname
,string
current_file
,object
|void
handler
)
- Methodcompile_error
void
compile_error(string
file
,int
line
,string
err
)
- Methodcompile_warning
void
compile_warning(string
file
,int
line
,string
warn
)
- Methoddecode_charset
string
decode_charset(string
data
,string
charset
)
- Methoddescribe_backtrace
string
describe_backtrace(object
|array
trace
,int
|void
line_width
)
- Methodhandle_error
void
handle_error(array
|object
trace
)
- Methodhandle_import
mixed
handle_import(string
what
,string
|void
current_file
,object
|void
handler
)
- Methodhandle_include
string
handle_include(string
f
,string
current_file
,bool
local_include
)
- Methodhandle_inherit
program
handle_inherit(string
pname
,string
current_file
,object
|void
handler
)
- Methodread_include
string
read_include(string
path
)
- Methodresolv
mixed
resolv(string
identifier
,string
|void
current_file
,object
|void
handler
)
- Methodwerror
void
werror(string
fmt
,mixed
...args
)
- Methodwrite
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()
- Methodcreate
Builtin.automap_markerBuiltin.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.Stackfrom,mixed
item
)- Description
Return the stack-depth to
item
.This function makes it possible to use eg
search()
andhas_value()
on the stack.
- Method_sizeof
int
sizeof(__builtin.Stackarg)- Description
sizeof
on a stack returns the number of entries in the stack.
- Method_values
array
values(__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
|void
initial_size
)- Description
An initial stack size can be given when a stack is cloned. The default value is 32.
- Methodpop
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()
- Methodpop_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()
- Methodpush
void
push(mixed
val
)- Description
Push an element on the top of the stack.
- Methodquick_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()
- Methodreset
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
- Methodset_stack
void
set_stack(array
stack
)- Description
Sets the stacks content to the provided array.
- Methodtop
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
- 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.
- InheritCipher
inherit __builtin.Nettle.Cipher : Cipher
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.
- Methoddigest
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.
- Methoddigest_size
int(0..)
digest_size()- Description
Returns the size of a hash digest.
- InheritState
inherit Cipher::State : State
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
- Method`()
State
res =__builtin.Nettle.AEAD()
()- Description
Calling `() will return a
State
object.
- InheritAE
inherit __builtin.Nettle.AE : AE
- Inherit__Hash
inherit __builtin.Nettle.__Hash : __Hash
Class __builtin.Nettle.AEAD.State
- Description
This is the context for a single incrementally updated AEAD cipher.
Most of the functions here are only prototypes, and need to be overrided via inherit.
- InheritState
inherit Cipher::State : State
- InheritState
inherit __Hash::State : State
Class __builtin.Nettle.BlockCipher
- Description
Base class for block cipher algorithms.
Implements some common convenience functions, and prototypes.
It also implements operating modes other than ECB.
Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit this class.
- InheritCipher
inherit .Cipher : Cipher
Module __builtin.Nettle.BlockCipher.CTR
- Description
Implementation of Counter Mode (CTR). Works as a wrapper for the cipher algorithm in the parent module.
This cipher mode works like a stream cipher with a block size >= 1. This means that the same key and initialization vector (aka counter) should never be reused, since a simple xor would reveal information about the plain text. It also means that it should never be used without a suiteable Message Authentication Code (MAC).
- See also
predef::Nettle.BlockCipher.CBC
,predef::Nettle.BlockCipher.CCM
,predef::Nettle.BlockCipher.GCM
,MAC
- InheritCipher
inherit .Cipher : Cipher
- Methodname
string(7bit)
name()- Description
Returns the name of the base cipher extended with
".CTR"
.
Class __builtin.Nettle.BlockCipher.CTR.State
- Description
The state for the embedded algorithm
- Inheritthis_program
inherit ::this_program : this_program
Class __builtin.Nettle.Cipher
- Description
Base class for cipher algorithms.
Implements some common convenience functions, and prototypes.
Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit (usually via
predef::Nettle.Cipher
) this class.- See also
predef::Nettle.Cipher
,Crypto.Cipher
- Method`()
State
res =__builtin.Nettle.Cipher()
()- Description
Calling `() will return a
State
object.
- Methodblock_size
int(0..)
block_size()- Returns
The block size of the cipher (
1
for stream ciphers).
- Methoddecrypt
string
decrypt(string(8bit)
key
,string(8bit)
data
)- Description
Works as a shortcut for
obj->set_decrypt_key(key)->crypt(data)
- Methodencrypt
string
encrypt(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_program
set_decrypt_key(string(8bit)
key
,void
|int
force
)- Description
Initializes the object for decryption.
- See also
set_encrypt_key
,crypt
- Methodset_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
- Methodjose_name
string(7bit)
jose_name()- Description
Return the JOSE name of the Curve (if any).
- Returns
The default implementation returns
UNDEFINED
.
- Methodname
extern
string(7bit)
name()- Description
Return the name of the Curve.
- Methodnew_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.
- Methodsize
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.
- Methodcreate
__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 sameCurve
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 sameCurve
.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
. Cfencode()
.- Note
Throws errors if the point isn't on the
Curve
.
- Methodencode
string
encode()- Description
Serialize the
Point
.The default implementation serializes according to ANSI x9.62 encoding #4 (uncompressed point format).
- Methodget_curve
global::this_program
get_curve()- Description
Get the
Crypto.ECC.Curve
that thisPoint
belongs to.
- Methodget_x
Methodget_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.
- Methodget_x_num
Gmp.mpz
get_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.mpz
get_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
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 thePoint
.- 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.
- MethodP_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.
- 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 also
crypt_md5()
- Methodcrypt_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()
- Methodcrypt_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
is0
.- Parameter
rounds
Number of rounds. Defaults to taking the value from the
salt
if thesalt
has length9
, otherwise defaults to1<<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)
|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
- Methodeme_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()
- Methodemsa_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()
.
- Methodemsa_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 and0
(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()
, whereState
is the hash state class corresponding to thisHash
.- Parameter
data
String to hash.
- See also
Stdio.File
,State()->update()
andState()->digest()
.
- Methodhash
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()
, whereState
is the hash state class corresponding to thisHash
.- 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
- 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.
- Methodhotp
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 isCrypto.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.
- Inherit__Hash
inherit .__Hash : __Hash
- 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
,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 encryptStandards.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
,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()
- Methodpbkdf2
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()
- 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)
|void
salt
)- Description
Initializes the HKDF object with a RFC 5869 2.2 HKDF-Extract(salt, IKM) call.
- Methodexpand
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.
- 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 theserver_*
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
|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
- Methodclient_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
- Methodclient_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.
- Methodserver_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
- Methodserver_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
- Methodserver_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)
orCrypto.SHA256.HMAC(key)->update(data)->update(more_data)->digest()
.- See also
Crypto.HMAC
- Method`()
State
res =__builtin.Nettle.Hash()
()- Description
Returns a new
State
object initialized with apassword
, and optionally block sizeb
. Block size defaults to the hash function block size.
- InheritMAC
inherit .MAC : MAC
- 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
- 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.
- 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()
anddigest()
.
- Methodcreate
__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 theblock_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.
- Inheritthis_program
inherit ::this_program : this_program
- Methodjwk
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
- Methodset_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
- 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 return0
.
- Methodjwa
string(7bit)
jwa()- Description
JWS algorithm identifier (if any, otherwise
0
).- See also
- Methodkey_size
int(0..)
key_size()- Description
Returns the recomended size of the key.
- 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()
Class __builtin.Nettle.MAC.State
- Description
The state for the MAC.
- Methodcreate
__builtin.Nettle.MAC.State__builtin.Nettle.MAC.State(
string
key
)- Parameter
key
The secret key for the hash.
- Inheritthis_program
inherit ::this_program : this_program
- 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 return0
.
- Methodjose_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 arrayArray 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)
|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
- 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
andCrypto.ECC.Curve.ECDSA
.
- Method_equal
bool
equal(__builtin.Nettle.Signfrom,mixed
x
)- 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)
)|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 arrayArray 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 (egCrypto.DSA
).- See also
jose_sign()
,pkcs_verify()
, RFC 7515
- Methodjose_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 algorithmh
and JOSE headersheaders
.- 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 (egCrypto.DSA
).- See also
jose_decode()
,pkcs_sign()
, RFC 7515
- Methodjwk
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
- Methodjwk_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
- 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
pkcs_algorithm_identifier()- Description
Returns the PKCS-1 AlgorithmIdentifier.
- Methodpkcs_public_key
Sequence
pkcs_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
,.Hash
h
)- Description
Signs the
message
with a PKCS-1 signature using hash algorithmh
.
- Methodpkcs_signature_algorithm_id
Sequence
pkcs_signature_algorithm_id(.Hash
hash
)- Description
Returns the PKCS-1 algorithm identifier for the signing algorithm with the provided hash algorithm.
- Methodpkcs_verify
bool
pkcs_verify(string(8bit)
message
,.Hash
h
,string(8bit)
sign
)- Description
Verify PKCS-1 signature
sign
of messagemessage
using hash algorithmh
.
- Methodpublic_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 implementingCrypto.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)
|void
data
)- Description
Create the new context, and optionally add some initial data to hash.
The default implementation calls
update()
withdata
if any, so there's usually no reason to override this function, since overridingupdate()
should be sufficient.
- Methoddigest
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.
- Methoddigest_size
int(0..)
digest_size()- Description
Returns the size of a hash digest.
- Methodinit
this_program
init(string(8bit)
|void
data
)- Description
Reset the context, and optionally add some initial data to the hash.
- Methodname
string(8bit)
name()- Description
Returns a human readable name for the algorithm.
- Methodupdate
this_program
update(string(8bit)
data
)- Description
Add some more data to hash.
Module __builtin.Sql
- Description
Generic base classes for the Sql interfaces.
- Variablezero
ZeroWrapper
__builtin.Sql.zero- Description
Instance of
ZeroWrapper
used byConnection()->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
final
int
__builtin.Sql.FutureResult.affected_rows- Description
The number of affected rows.
- Variablebindings
final
mapping
(string
:mixed
)|zero
__builtin.Sql.FutureResult.bindings- Description
The parameter bindings belonging to the query.
- Variabledata
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()
- Variablefields
final
array
(mapping
(string
:mixed
))|zero
__builtin.Sql.FutureResult.fields- Description
The description of the fields in a record.
- Methodget
final
array
(mapping
(string
:mixed
)) get()- Returns
The returned labeled records, all typed data.
- See also
Sql.Connection->query()
,data
- Variablequery
final
string
|zero
__builtin.Sql.FutureResult.query- Description
The SQL query.
- Variablestatus_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.
Class __builtin.Sql.Promise
- Description
This class is the base class for promise based SQL queries.
future()
will return a future which carriesFutureResult
objects to contain the result of the query.- See also
FutureResult
,Connection.promise_query()
- Methoddiscard_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).
- InheritPromise
inherit Concurrent.Promise : Promise
- Methodmax_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).
- Methodmin_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
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.