21. Cryptography

21.1. Password hashing


Method crypt

string(46..122) crypt(string(1..255) password)
bool crypt(string(1..255) input_password, string(46..122) crypted_password)
string(46..122) crypt()

Description

This function crypts and verifies a short string (only the first 8 characters are significant).

The first syntax crypts the string password into something that is hopefully hard to decrypt.

The second syntax is used to verify typed_password against crypted_password, and returns 1 if they match, and 0 (zero) otherwise.

The third syntax generates a random string and then crypts it, creating a string useful as a password.

Note

Note that strings containing null characters will only be processed up until the null character.

Module Crypto.Password

Description

Password handling.

This module handles generation and verification of password hashes.

See also

verify(), hash(), crypt()


Method hash

string(7bit) hash(string(8bit) password, string(7bit)|void scheme, int(0..)|void rounds)

Description

Generate a hash of password suitable for verify().

Parameter password

Password to hash.

Parameter scheme

Password hashing scheme. If not specified the strongest available will be used.

If an unsupported scheme is specified an error will be thrown.

Supported schemes are:

Crypt(3C)-style:

UNDEFINED

Use the strongest crypt(3C)-style hash that is supported.

"crypt"
"{crypt}"
"6"

SHA512.crypt_hash() with 96 bits of salt and a default of 5000 rounds.

"$6$"
"5"

SHA256.crypt_hash() with 96 bits of salt and a default of 5000 rounds.

"$5$"
"3"

The NTLM MD4 hash.

"NT"
"2"

Nettle.bcrypt() with 128 bits of salt and a default of 1024 rounds.

"2a"
"2b"
"2x"
"2y"
"$2$"
"$2a$"
"$2b$"
"$2x$"
"$2y$"
"1"

MD5.crypt_hash() with 48 bits of salt and 1000 rounds.

"$1$"
"sha1"

SHA1.HMAC.crypt_hash() with 48 bits of salt and a default of 480000 rounds.

"P"

MD5.crypt_php() with 48 bits of salt and a default of 1<<19 rounds. The specified number of rounds will be rounded up to the closest power of 2.

"$P$"
"H"
"$H$"
"U$P$"

Same as "$P$", the supplied password is assumed to have already been passed through MD5.hash() once. Typically used to upgrade unsalted MD5-password databases.

"Q"

Same as "$P$", but with SHA1.crypt_php().

"$Q$"
"S"

Same as "$S$", but with SHA512.crypt_php().

"$S$"
"pbkdf2"

SHA1.pbkdf2().

"$pbkdf2$"
"pbkdf2-sha256"

SHA256.pbkdf2().

"$pbkdf2-sha256$"
"pbkdf2-sha512"

SHA512.pbkdf2().

"$pbkdf2-sha512$"
""

predef::crypt() with 12 bits of salt.

LDAP (RFC 2307)-style. Don't use these if you can avoid it, since they are suspectible to attacks. In particular avoid the unsalted variants at all costs:

"ssha"

SHA1.hash() with 96 bits of salt appended to the password.

"{ssha}"
"smd5"

MD5.hash() with 96 bits of salt appended to the password.

"{smd5}"
"sha"

SHA1.hash() without any salt.

"{sha}"
"md5"

MD5.hash() without any salt.

"{md5}"
Parameter rounds

The number of rounds to use in parameterized schemes. If not specified the scheme specific default will be used.

Returns

Returns a string suitable for verify(). This means that the hashes will be prepended with the suitable markers.

Note

Note that the availability of SHA512 depends on the version of Nettle that Pike has been compiled with.

Note

This function was added in Pike 7.8.755.

See also

verify(), predef::crypt(), Nettle.crypt_md5(), Nettle.Hash()->crypt_hash()


Method verify

int verify(string(8bit) password, string(7bit) hash)

Description

Verify a password against a hash.

This function attempts to support most common password hashing schemes.

Parameter password

Binary password. This is typically is typically a textual string normalized according to string_to_utf8(Unicode.normalize(raw_password, "NFC")), but some operating systems (eg MacOS X) may have other conventions.

Parameter hash

The hash can be on any of the following formats.

LDAP-style (RFC 2307) hashes:

"{SHA}XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The XXX string is taken to be a MIME.encode_base64 SHA1 hash of the password. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/347.html.

"{SSHA}XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The XXX string is taken to be a MIME.encode_base64 string in which the first 20 chars are an SHA1 hash and the remaining chars the salt. The input for the hash is the password concatenated with the salt. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/347.html.

"{MD5}XXXXXXXXXXXXXXXXXXXXXXXX"

The XXX string is taken to be a MIME.encode_base64 MD5 hash of the password. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/418.html.

"{SMD5}XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The XXX string is taken to be a MIME.encode_base64 string in which the first 16 chars are an MD5 hash and the remaining chars the salt. The input for the hash is the password concatenated with the salt. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/418.html.

"{CRYPT}XXXXXXXXXXXXX"

The XX string is taken to be a crypt(3C)-style hash. This is the same thing as passing the XXX string without any preceding method name within {...}. I.e. it's interpreted according to the crypt-style hashes below.

Crypt-style hashes:

"$6$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

The string is interpreted according to the "Unix crypt using SHA-256 and SHA-512" standard Version 0.4 2008-4-3, where SSSSSSSSSSSSSSSS is up to 16 characters of salt, and the string XXX the result of SHA512.crypt_hash() with 5000 rounds. Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt

"$6$rounds=RR$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

This is the same algorithm as the one above, but with the number of rounds specified by RR in decimal. Note that the number of rounds is clamped to be within 1000 and 999999999 (inclusive). Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt

"$5$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

The string is interpreted according to the "Unix crypt using SHA-256 and SHA-512" standard Version 0.4 2008-4-3, where SSSSSSSSSSSSSSSS is up to 16 characters of salt, and the string XXX the result of SHA256.crypt_hash() with 5000 rounds. Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt

"$5$rounds=RR$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

This is the same algorithm as the one above, but with the number of rounds specified by RR in decimal. Note that the number of rounds is clamped to be within 1000 and 999999999 (inclusive). Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt

"$3$$XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

This is interpreted as the NT LANMANAGER (NTLM) password hash. It is a hex representation of MD4 of the password.

"$1$SSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

The string is interpreted according to the GNU libc2 extension of crypt(3C) where SSSSSSSS is up to 8 chars of salt and the XXX string is an MD5-based hash created from the password and the salt. Source: GNU libc http://www.gnu.org/software/libtool/manual/libc/crypt.html.

"$sha1$RRRRR$SSSSSSSS$XXXXXXXXXXXXXXXXXXXX"

The string is interpreted as a NetBSD-style SHA1.HMAC.crypt_hash() (aka crypt_sha1(3C)), where RRRRR is the number of rounds (default 480000), SSSSSSSS is a MIME.crypt64() encoded salt. and the XXX string is an SHA1.HMAC-based hash created from the password and the salt.

"$P$RSSSSSSSSXXXXXXXXXXXXXXXXXXXXXX"

The string is interpreted as a PHPass' Portable Hash password hash, where R is an encoding of the 2-logarithm of the number of rounds, SSSSSSSS is a salt of 8 characters, and XXX is similarily the MIME.encode_crypt64 of running MD5.hash() repeatedly on the password and the salt.

"$H$RSSSSSSSS.XXXXXXXXXXXXXXXXXXXXXX"

Same as "$P$" above. Used by phpBB3.

"U$P$RSSSSSSSSXXXXXXXXXXXXXXXXXXXXXX"

This is handled as a Drupal upgraded PHPass Portable Hash password. The password is run once through MD5.hash(), and then passed along to the "$P$"-handler above.

"$Q$RSSSSSSSSXXXXXXXXXXXXXXXXXXXXXX"

The string is interpreted as a PHPass' Portable Hash password hash, where the base hashing alorithm has been switched to SHA1. This method is apparently used by some versions of Escher CMS.

"$S$RSSSSSSSSXXXXXXXXXXXXXXXXXXXXXX"

The string is interpreted as a PHPass' Portable Hash password hash, where the base hashing alorithm has been switched to SHA256. This method is apparently used by some versions of Drupal.

"$pbkdf2$RRRRR$SSSSS$XXXXXXXXXXXXX"

The string is interpreted as SHA1.crypt_pbkdf2().

"$pbkdf2-sha256$RRRRR$SSSSS$XXXXXXXXXXXXX"

The string is interpreted as SHA256.crypt_pbkdf2().

"$pbkdf2-sha512$RRRRR$SSSSS$XXXXXXXXXXXXX"

The string is interpreted as SHA512.crypt_pbkdf2().

"pbkdf2_sha256$RRRRR$SSSSS$XXXXXXXXXXXXX"

The string is interpreted as the Django variant of SHA256.crypt_pbkdf2(). This differs from the standard variant ("$pbkdf2-sha256$") in that the hash is encoded with plain MIME.encode_base64() (ie including padding ('=') and plus ('+') characters).

"XXXXXXXXXXXXX"

The XXX string (which doesn't begin with "{") is taken to be a password hashed using the classic unix crypt(3C) function. If the string contains only chars from the set [a-zA-Z0-9./] it uses DES and the first two characters as salt, but other alternatives may be possible depending on the crypt(3C) implementation in the operating system.

""

The empty password hash matches all passwords.

Returns

Returns 1 on success, and 0 (zero) otherwise.

Note

This function was added in Pike 7.8.755.

See also

hash(), predef::crypt()

21.2. Kerberos and GSSAPI

Module GSSAPI

Description

This is pike glue for GSS-API ver 2 as specified in RFC 2743.

GSS-API is used to authenticate users and servers, and optionally also to encrypt communication between them. The API is generic and can be used without any knowledge of the actual implementation of these security services, which is typically provided by the operating system.

The most common implementation at the time of writing is Kerberos, which means that the main benefit of this API is to allow clients and servers to authenticate each other using Kerberos, thereby making single sign-on possible in a Kerberized environment.

All functions in this module that wrap GSS-API routines may throw GSSAPI.Error, and by default they do so for all such errors. Only in some special cases do they return when a GSS-API error has happened, and this is then noted in the documentation.


Constant INITIATE
Constant ACCEPT
Constant BOTH

constant int GSSAPI.INITIATE
constant int GSSAPI.ACCEPT
constant int GSSAPI.BOTH

Description

Flags for indicating how a GSSAPI.Cred object may be used:

INITIATE

The credential can only be used to initiate security contexts (i.e. using GSSAPI.InitContext).

ACCEPT

The credential can only be used to accept security contexts (i.e. using GSSAPI.AcceptContext).

BOTH

The credential may be used both to initiate or accept security contexts.


Constant DELEG_FLAG
Constant MUTUAL_FLAG
Constant REPLAY_FLAG
Constant SEQUENCE_FLAG
Constant CONF_FLAG
Constant INTEG_FLAG
Constant ANON_FLAG
Constant PROT_READY_FLAG
Constant TRANS_FLAG

constant int GSSAPI.DELEG_FLAG
constant int GSSAPI.MUTUAL_FLAG
constant int GSSAPI.REPLAY_FLAG
constant int GSSAPI.SEQUENCE_FLAG
constant int GSSAPI.CONF_FLAG
constant int GSSAPI.INTEG_FLAG
constant int GSSAPI.ANON_FLAG
constant int GSSAPI.PROT_READY_FLAG
constant int GSSAPI.TRANS_FLAG

Description

Bitfield flags returned by e.g. GSSAPI.Context.services to denote various services that are available in the context.

Brief descriptions of the flags:

GSSAPI.DELEG_FLAG

Delegation. See RFC 2743 section 1.2.9.

GSSAPI.MUTUAL_FLAG

Mutual authentication (actually, acceptor authentication). See RFC 2743 section 1.1.1.3 and RFC 2743 section 1.2.5.

GSSAPI.REPLAY_FLAG

Per-message replay detection. See RFC 2743 section 1.2.3.

GSSAPI.SEQUENCE_FLAG

Per-message sequencing. See RFC 2743 section 1.2.3.

GSSAPI.CONF_FLAG

Per-message confidentiality. See RFC 2743 section 1.2.2.

GSSAPI.INTEG_FLAG

Per-message integrity. See RFC 2743 section 1.2.2.

GSSAPI.ANON_FLAG

Anonymous authentication. See RFC 2743 section 1.2.5.

GSSAPI.PROT_READY_FLAG

Might be set before the context establishment has finished, to denote that per-message protection already is available. See RFC 2743 section 1.2.7. Is always set in GSSAPI.Context and derived classes when the context is established.

GSSAPI.TRANS_FLAG

The context can be transferred between processes using GSSAPI.Context.export. See RFC 2743 section 1.2.10.


Constant BAD_MECH
Constant BAD_NAME
Constant BAD_NAMETYPE
Constant BAD_BINDINGS
Constant BAD_STATUS
Constant BAD_SIG
Constant NO_CRED
Constant NO_CONTEXT
Constant DEFECTIVE_TOKEN
Constant DEFECTIVE_CREDENTIAL
Constant CREDENTIALS_EXPIRED
Constant CONTEXT_EXPIRED
Constant FAILURE
Constant BAD_QOP
Constant UNAUTHORIZED
Constant UNAVAILABLE
Constant DUPLICATE_ELEMENT
Constant NAME_NOT_MN

constant int GSSAPI.BAD_MECH
constant int GSSAPI.BAD_NAME
constant int GSSAPI.BAD_NAMETYPE
constant int GSSAPI.BAD_BINDINGS
constant int GSSAPI.BAD_STATUS
constant int GSSAPI.BAD_SIG
constant int GSSAPI.NO_CRED
constant int GSSAPI.NO_CONTEXT
constant int GSSAPI.DEFECTIVE_TOKEN
constant int GSSAPI.DEFECTIVE_CREDENTIAL
constant int GSSAPI.CREDENTIALS_EXPIRED
constant int GSSAPI.CONTEXT_EXPIRED
constant int GSSAPI.FAILURE
constant int GSSAPI.BAD_QOP
constant int GSSAPI.UNAUTHORIZED
constant int GSSAPI.UNAVAILABLE
constant int GSSAPI.DUPLICATE_ELEMENT
constant int GSSAPI.NAME_NOT_MN

Description

Constants for routine errors in major status codes like GSSAPI.Error.major_status. See RFC 2743 section 1.2.1.1. Note that major status codes have to be masked with GSSAPI.ERROR_MASK before comparison with these.

Brief descriptions of the flags:

GSSAPI.BAD_BINDINGS

Channel binding mismatch.

GSSAPI.BAD_MECH

Unsupported mechanism requested.

GSSAPI.BAD_NAME

Invalid name provided.

GSSAPI.BAD_NAMETYPE

Name of unsupported type provided.

GSSAPI.BAD_STATUS

Invalid input status selector.

GSSAPI.BAD_MIC

Token had invalid integrity check.

GSSAPI.CONTEXT_EXPIRED

Specified security context expired.

GSSAPI.CREDENTIALS_EXPIRED

Expired credentials detected.

GSSAPI.DEFECTIVE_CREDENTIAL

Defective credential detected.

GSSAPI.DEFECTIVE_TOKEN

Defective token detected.

GSSAPI.FAILURE

Failure, unspecified at GSS-API level. GSSAPI.Error.minor_status should provide further details.

GSSAPI.NO_CONTEXT

No valid security context specified.

GSSAPI.NO_CRED

No valid credentials provided.

GSSAPI.BAD_QOP

Unsupported QOP value.

GSSAPI.UNAUTHORIZED

Operation unauthorized.

GSSAPI.UNAVAILABLE

Operation unavailable.

GSSAPI.DUPLICATE_ELEMENT

Duplicate credential element requested.

GSSAPI.NAME_NOT_MN

Name contains multi-mechanism elements.


Constant CONTINUE_NEEDED
Constant DUPLICATE_TOKEN
Constant OLD_TOKEN
Constant UNSEQ_TOKEN
Constant GAP_TOKEN

constant int GSSAPI.CONTINUE_NEEDED
constant int GSSAPI.DUPLICATE_TOKEN
constant int GSSAPI.OLD_TOKEN
constant int GSSAPI.UNSEQ_TOKEN
constant int GSSAPI.GAP_TOKEN

Description

Bitfield flags for informatory codes in major status codes like GSSAPI.Error.major_status. See RFC 2743 section 1.2.1.1. Any combination of these might optionally be combined with one routine error constant to form a major status code.

Brief descriptions of the flags:

GSSAPI.CONTINUE_NEEDED

Continuation call to routine required.

GSSAPI.DUPLICATE_TOKEN

Duplicate per-message token detected.

GSSAPI.OLD_TOKEN

Timed-out per-message token detected.

GSSAPI.UNSEQ_TOKEN

Reordered (early) per-message token detected.

GSSAPI.GAP_TOKEN

Skipped predecessor token(s) detected.


Constant ERROR_MASK

constant int GSSAPI.ERROR_MASK

Description

Bitfield mask for the routine error part of major status codes like GSSAPI.Error.major_status. After applying this mask, the status values may be compared to any of the routine error constants.


Constant INFO_MASK

constant int GSSAPI.INFO_MASK

Description

Bitfield mask for the informatory part of major status codes like GSSAPI.Error.major_status.


Constant NT_HOSTBASED_SERVICE
Constant NT_USER_NAME
Constant NT_MACHINE_UID_NAME
Constant NT_STRING_UID_NAME
Constant NT_ANONYMOUS
Constant NT_EXPORT_NAME
Constant KRB5_NT_PRINCIPAL_NAME

constant string GSSAPI.NT_HOSTBASED_SERVICE
constant string GSSAPI.NT_USER_NAME
constant string GSSAPI.NT_MACHINE_UID_NAME
constant string GSSAPI.NT_STRING_UID_NAME
constant string GSSAPI.NT_ANONYMOUS
constant string GSSAPI.NT_EXPORT_NAME
constant string GSSAPI.KRB5_NT_PRINCIPAL_NAME

Description

OIDs on dotted-decimal form for the GSS-API mechanism-independent name types, and some selected mechanism-specific ones:

NT_HOSTBASED_SERVICE

Name type for a service associated with a host computer. The syntax is service@hostname where the @hostname part may be omitted for the local host. See RFC 2743 section 4.1.

NT_USER_NAME

Name type for a named user on a local system. The syntax is username. See RFC 2743 section 4.2.

NT_MACHINE_UID_NAME

Name type for a numeric user identifier corresponding to a user on a local system. The string representing a name of this type should contain a locally-significant user ID, represented in host byte order. See RFC 2743 section 4.3.

NT_STRING_UID_NAME

Name type for a string of digits representing the numeric user identifier of a user on a local system. This name type is similar to the Machine UID Form, except that the buffer contains a string representing the user ID. See RFC 2743 section 4.4.

NT_ANONYMOUS

Name type to identify anonymous names. See RFC 2743 section 4.5.

NT_EXPORT_NAME

Name type for the Mechanism-Independent Exported Name Object type, which is the type of the names returned by GSSAPI.Name.export. See RFC 2743 section 4.7.

KRB5_NT_PRINCIPAL_NAME

Name type for a Kerberos principal. See RFC 1964 section 2.1.1.


Method describe_services

string describe_services(int services)

Description

Returns a string that compactly describes the given services, which is taken as a bitfield of GSSAPI.*_FLAG flags.

The returned string contains capitalized names for the flags reminiscent of the GSSAPI.*_FLAG constants, separated by "|".


Method indicate_mechs

multiset(string) indicate_mechs()

Description

Returns the OIDs for the available mechanism in the GSS-API implementation. The OIDs are returned on dotted-decimal form.

This wraps GSS_Indicate_mechs according to RFC 2743 section 2.4.2.


Method major_status_messages

array(string) major_status_messages(int major_status)

Description

Given a major status code like GSSAPI.Error.major_status (or more commonly GSSAPI.Context.last_major_status in this case), returns an array containing messages for all the status values in it. The returned string(s) presumably don't end with linefeeds.

This wraps GSS_Display_status according to RFC 2743 section 2.4.1.


Method minor_status_messages

array(string) minor_status_messages(int minor_status, void|string mech)

Description

Given a mechanism-specific minor status code like GSSAPI.Error.minor_status, returns an array containing messages for all the status values in it. The returned string(s) presumably don't end with linefeeds.

This wraps GSS_Display_status according to RFC 2743 section 2.4.1.

Parameter minor_status

The mechanism-specific minor status.

Parameter mech

The mechanism that produced the status code. If this is zero or left out, a system default mechanism is used.


Method names_for_mech

multiset(string) names_for_mech(string mech)

Description

Returns the OIDs for the name types that the given mech supports. Both mech and the returned OID strings are on dotted-decimal form.

This wraps GSS_Inquire_names_for_mech according to RFC 2743 section 2.4.12.

Class GSSAPI.AcceptContext

Description

Variant of Context which is used on the acceptor side.


Inherit Context

inherit Context : Context


Method accept

string accept(string remote_token)

Description

Accepts a remotely initiated security context.

This wraps GSS_Accept_sec_context according to RFC 2743 section 2.2.2.

The underlying mechanism might require several tokens to be passed back and forth to establish the context. If is_established returns zero after a call to this function then the caller must wait for a token from the remote peer to feed as remote_token in another call to this function.

Parameter remote_token

A token from the remote peer, as returned by a call to GSSAPI.InitContext.init or some other GSS_Init_sec_context wrapper.

Returns

If a string is returned then it must be passed to the remote peer which will feed it to GSSAPI.InitContext.init or some other GSS_Init_sec_context wrapper. An empty string is never returned.

Zero is returned if there is no token to send to the remote peer. Note that is_established might still return zero in that case, meaning more remote tokens are necessary.

Note

This function might block on network connections to remote authentication servers.


Method create

GSSAPI.AcceptContext GSSAPI.AcceptContext(void|Cred cred, void|int required_services)

Description

Creates a context for acceptor use. This function only accepts parameters to be used later during the accept call. If there are semantic problems with them, such as if the credentials are stale, then they will be signalled later by accept.

Parameter cred

Credentials for the identity this context claims. The credentials for the default principal (if any) is used if zero or left out.

Parameter required_services

Bitfield of GSSAPI.*_FLAG flags specifying all services that must be provided in the context. If the context fail to provide any of them then it is closed and a GSSAPI.MissingServicesError is thrown.

GSSAPI.PROT_READY_FLAG is ignored in this parameter. The fact that a user calls a per-message function indicates that this service is required at that point, and a GSSAPI.MissingServicesError is thrown if it isn't.

Note

Channel bindings (RFC 2743 section 1.1.6) are not yet implemented since that feature appear to not be in much active use, and its format is not completely specified (RFC 2744 section 3.11).


Method delegated_cred

Cred delegated_cred()

Description

Returns the delegated credentials from the initiator if the delegation (c.f. GSSAPI.DELEG_FLAG) service is in use.

Class GSSAPI.Context

Description

Class representing a security context; see RFC 2743 section 1.1.3 The user usually instantiates one of the two inheriting classes GSSAPI.InitContext or GSSAPI.AcceptContext, based on whether the context should act as initiator or acceptor for the connection. This class is instantiated directly for imported contexts.

Note

If a Context object for a partly or completely established context is destructed, GSS_Delete_sec_context (RFC 2743 section 2.2.3) is called. That function might do blocking network I/O, which due to pike's object management might occur essentially anytime in any thread if the object isn't explicitly destructed. To avoid that, it's strongly recommended to call delete in contexts that are no longer used.


Method create

GSSAPI.Context GSSAPI.Context(string interprocess_token, void|int required_services)

Description

Creates a context by importing an inter-process token.

This wraps GSS_Import_sec_context according to RFC 2743 section 2.2.9.

Parameter interprocess_token

The inter-process token which has been created by export or some other GSS_Export_sec_context wrapper.

Parameter required_services

Bitfield of GSSAPI.*_FLAG flags specifying all services that must be provided in the context. If the context fail to provide any of them then it is closed and a GSSAPI.MissingServicesError is thrown.

GSSAPI.PROT_READY_FLAG is ignored in this parameter. The fact that a user calls a per-message function indicates that this service is required at that point, and a GSSAPI.MissingServicesError is thrown if it isn't.

Note

It is not possible to retrieve delegated credentials from an imported context. That is a GSS-API limitation.


Method delete

void delete()

Description

Frees the resources for the context, provided it is in use. Does nothing otherwise.

This wraps GSS_Delete_sec_context according to RFC 2743 section 2.2.3.

Note

This function might block on network connections to remote authentication servers.

Note

In compliance with recommendations in GSS-API v2, the optional output token is never used in the call to GSS_Delete_sec_context.


Method export

string export()

Description

Exports this context so that it can be imported in another process, providing the inter-process context transfer service is available (c.f. GSSAPI.TRANS_FLAG).

This wraps GSS_Export_sec_context according to RFC 2743 section 2.2.8.

The returned string is intended to be fed to GSSAPI.Context.create (or some other GSS_Import_sec_context wrapper) in the receiving process.

This operation frees the context in this object.


Method get_mic

string get_mic(string message, void|int qop)

Description

Calculates and returns a MIC (message integrity checksum) for the given message that allows the receiver to verify its origin and integrity through verify_mic or some other GSS_VerifyMIC wrapper.

This wraps GSS_GetMIC according to RFC 2743 section 2.3.1.

This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

Parameter message

The message for which the MIC is to be calculated. It may be of zero length.

Parameter qop

The quality of protection. This is a mechanism-specific value that lets the user direct how the underlying mechanism calculates the MIC. See RFC 2743 section 1.2.4.

Zero or left out means use the default method.


Method is_established
Method services
Method locally_initiated
Method source_name
Method target_name
Method lifetime
Method mech

int is_established()
int services()
int locally_initiated()
Name source_name()
Name target_name()
int(0..) lifetime()
string mech()

Description

Functions to query various properties about the context.

These wrap GSS_Inquire_context according to RFC 2743 section 2.2.6.

is_established()

Returns nonzero as soon as the context has been established. That means no further rounds through GSSAPI.InitContext.init or GSSAPI.AcceptContext.accept, that the remote peer is authenticated as required, and that the set of available services is complete (see services).

services()

Returns a bitfield of GSSAPI.*_FLAG flags for the services that the context (currently) provides. This field is complete only when the context establishment has finished, i.e. when is_established returns nonzero.

See also GSSAPI.describe_services.

locally_initiated()

Returns nonzero if the context is an initiator, zero if it is an acceptor. (This is mainly useful in imported contexts.)

source_name()

Returns the name of the context initiator. The name is always an MN. Returns an anonymous name if used on the acceptor side and the anonymous authentication service (c.f. GSSAPI.ANON_FLAG) was used.

target_name()

Returns the name of the context acceptor. If a name is returned then it is always an MN.

Zero is returned on the initiator side if the initiator didn't specify a target name and the acceptor did not authenticate itself (should never happen if mutual authentication (c.f. GSSAPI.MUTUAL_FLAG) is a required service).

The returned object is not necessarily the same one as was passed to GSSAPI.InitContext.create, even though they are likely to compare as equal (they might not be equal if the passed name wasn't an MN).

lifetime()

Returns the validity lifetime left for the context. Returns zero if the context has expired, or Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

mech()

Returns the mechanism that provides the context. The returned value is its OID on dotted-decimal form.

These functions don't throw errors if the context is missing or not completely established, even though they might not be able to query the proper values then (GSS-API implementations are known to not be completely reliable in handling these queries for partly established contexts). The functions instead return zero.


Method last_confidential

int last_confidential()

Description

Returns nonzero if the last call to wrap or unwrap provided confidentiality for the message, i.e. if wrap encrypted it or if unwrap decrypted it. Zero is returned otherwise.


Method last_major_status
Method last_minor_status

int last_major_status()
int last_minor_status()

Description

Returns the major and minor status codes from the last operation that called a GSS-API routine, with the exception of those that wrap GSS_Inquire_context.


Method last_qop

int last_qop()

Description

Returns the quality of protection provided by the last call to verify_mic or unwrap.


Method process_token

void process_token(string remote_token)

Description

Passes the given remote_token to the mechanism.

This wraps GSS_Process_context_token according to RFC 2743 section 2.2.4.

This is used for tokens that are received outside the handshaking between GSS_Init_sec_context (GSSAPI.InitContext.init) and GSS_Accept_sec_context (GSSAPI.AcceptContext.accept).

An example is when GSSAPI.InitContext.init returns a final token and flags the context as established, but the acceptor context detects an error and sends a failure token back. That token is processed using this function since GSSAPI.InitContext.init doesn't handle any more tokens by then.

Note

This function might change context state.

Note

This function might block on network connections to remote authentication servers. However, if the remote token is the result of GSS_Delete_sec_context on the remote side then it will not block.


Method required_services

int required_services(void|int services)

Description

Gets and optionally sets the set of services that must be provided in the context. The returned and given value is a bitfield of the GSSAPI.*_FLAG constants.

This is mainly useful to change the per-message service flags that verify_mic and unwrap use to decide whether a condition is an error or not.

Parameter services

New set of required services. If this is not given then the set is not changed.

If the context is established and services contain a service which isn't currently provided then the context is closed and a GSSAPI.MissingServicesError is thrown immediately.

GSSAPI.PROT_READY_FLAG is ignored in this parameter.

Returns

Returns the current set of required services (after setting them to services, if provided).

See also

GSSAPI.describe_services


Method unwrap

string unwrap(string message, void|int accept_encrypted_only)

Description

Verifies the origin and integrity of the given message using the MIC included in it, and also decrypts the message if it was encrypted. The message has been calculated by the sender using wrap or some other GSS_Wrap wrapper.

This wraps GSS_Unwrap according to RFC 2743 section 2.3.4.

This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

Parameter message

The message to be unwrapped.

Parameter accept_encrypted_only

If this is nonzero then it is an error if message isn't encrypted, and zero is returned in that case (the status returned by last_major_status will still indicate success, though).

Returns

Zero is returned if the verification fails with GSSAPI.DEFECTIVE_TOKEN or GSSAPI.BAD_MIC.

Zero is also returned if message isn't encrypted and accept_encrypted_only is set.

Otherwise the message is successfully decrypted (provided it was encrypted to begin with), and its origin and integrity checks out, but it might still be considered wrong depending on whether the replay detection or sequencing services are required (see required_services):

If replay detection (c.f. GSSAPI.REPLAY_FLAG) is required then zero is returned if the message is duplicated (GSSAPI.DUPLICATE_TOKEN) or old (GSSAPI.OLD_TOKEN).

If sequencing (c.f. GSSAPI.SEQUENCE_FLAG) is required then in addition to the replay detection conditions, zero is also returned if the message is out of sequence (GSSAPI.UNSEQ_TOKEN or GSSAPI.GAP_TOKEN).

Otherwise the unwrapped message is returned, which is valid according to the currently required services (note however that requiring the confidentiality service does not imply that an error is signalled whenever an unencrypted message is received - see instead accept_encrypted_only above).

Throws

Any GSS-API errors except GSSAPI.DEFECTIVE_TOKEN and GSSAPI.BAD_MIC are thrown.

Note

This function sets the value returned by last_confidential and last_qop.

Note

Even if the message is considered valid by the return value, last_major_status may be called to check for the informatory codes mentioned above.


Method verify_mic

int verify_mic(string message, string mic)

Description

Verifies the origin and integrity of the given message using the given mic, which has been calculated by the sender using get_mic or some other GSS_GetMIC wrapper.

This wraps GSS_VerifyMIC according to RFC 2743 section 2.3.2.

This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

Returns

Zero is returned if the verification fails with GSSAPI.DEFECTIVE_TOKEN or GSSAPI.BAD_MIC.

Otherwise the message origin and integrity checks out, but it might still be considered wrong depending on whether the replay detection or sequencing services are required (see required_services):

If replay detection (c.f. GSSAPI.REPLAY_FLAG) is required then zero is returned if the message is duplicated (GSSAPI.DUPLICATE_TOKEN) or old (GSSAPI.OLD_TOKEN).

If sequencing (c.f. GSSAPI.SEQUENCE_FLAG) is required then in addition to the replay detection conditions, zero is also returned if the message is out of sequence (GSSAPI.UNSEQ_TOKEN or GSSAPI.GAP_TOKEN).

Otherwise nonzero is returned to indicate that the message is valid according to the currently required services.

Throws

Any GSS-API errors except GSSAPI.DEFECTIVE_TOKEN and GSSAPI.BAD_MIC are thrown.

Note

This function sets the value returned by last_qop.

Note

Regardless whether the message is considered valid or not by the return value, last_major_status may be called to check for routine errors or the informatory codes mentioned above.


Method wrap

string wrap(string message, void|int encrypt, void|int qop)

Description

Calculates a MIC (message integrity checksum) for the given message, and returns it together with the message, which is optionally encrypted. The returned value can be verified and (if applicable) decrypted by the receiver using unwrap or some other GSS_Unwrap wrapper.

This wraps GSS_Wrap according to RFC 2743 section 2.3.3.

This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

Parameter message

The message to be wrapped. It may be of zero length.

Parameter encrypt

Set to nonzero to request that the message is encrypted. Otherwise only a MIC is calculated and the returned value contains the unencrypted message.

If this is set and the confidentiality service (c.f. GSSAPI.CONF_FLAG) is required then the returned value is always encrypted. Otherwise it might not be encrypted anyway, and a call to last_confidential will tell if it is or not.

Parameter qop

The quality of protection. This is a mechanism-specific value that lets the user direct how the underlying mechanism calculates the MIC. See RFC 2743 section 1.2.4.

Zero or left out means use the default method.

Note

This function sets the value returned by last_confidential.

See also

wrap_size_limit


Method wrap_size_limit

int(0..) wrap_size_limit(int(0..) output_size, int encrypt, void|int qop)

Description

Returns the maximum size of an input string to wrap that would produce no more than output_size bytes in the resulting output.

This wraps GSS_Wrap_size_limit according to RFC 2743 section 2.2.7.

with_confidentiality and qop are the same as in the call to wrap.

Class GSSAPI.Cred

Description

Objects of this class hold one or more credentials that the current process can use to assert identities; see RFC 2743 section 1.1.1.

Note

If a Cred object is destructed, GSS_Release_cred (RFC 2743 section 2.1.2) is called. The RFC doesn't preclude that that function might do blocking network I/O, which due to pike's object management might occur essentially anytime in any thread if the object isn't explicitly destructed. To avoid that, it's recommended to call release in credential objects that are no longer used.


Method name
Method cred_usage
Method mechs
Method lifetime
Method init_lifetime
Method accept_lifetime

GSSAPI.Name name(void|string mech)
int cred_usage(void|string mech)
multiset(string) mechs()
int(0..)|Int.inf lifetime()
int(0..)|Int.inf init_lifetime(string mech)
int(0..)|Int.inf accept_lifetime(string mech)

Description

Functions to query various properties about the credentials.

These wrap GSS_Inquire_cred according to RFC 2743 section 2.1.3 if mech is not given, and GSS_Inquire_cred_by_mech according to RFC 2743 section 2.1.5 otherwise.

Parameter mech

If this is given then the credential for that specific mechanism is queried. mech contains the OID of the mechanism on dotted-decimal form.

Some of the query functions can only be used for a specific mechanism, in which case mech is required. Some can only be used on the credentials in general, and the mech argument is not applicable. Some can be used both ways, and then mech is optional.

name (void|string mech) Returns the name of the identity that the credential(s) assert. If mech is given then the returned name is a Mechanism Name (MN).

The returned GSSAPI.Name object is always a newly created one, even though it typically compares as equal with the ones given to acquire or add.

cred_usage (void|string mech) Returns how the credential(s) may be used, one of GSSAPI.INITIATE, GSSAPI.ACCEPT or GSSAPI.BOTH.

If mech is not given then the returned usage value reflects the union of the capabilities in all credentials.

mechs() Returns the set of mechanisms supported by the credential. The returned value is a multiset of strings with OIDs on dotted-decimal form.

lifetime() Returns the shortest validity lifetime left in any of the mechanisms that are part of the credentials, for either initiator or acceptor use.

Returns zero if some part of the credentials has expired.

Returns Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

init_lifetime (string mech) Returns the validity lifetime left for initiator use.

Returns zero if the credential has expired for this use or if its usage is GSSAPI.ACCEPT.

Returns Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

accept_lifetime (string mech) Returns the validity lifetime left for acceptor use.

Returns zero if the credential has expired for this use or if its usage is GSSAPI.INITIATE.

Returns Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

Note

RFC 2743 doesn't preclude that these functions might block on network connections to remote authentication servers.


Method acquire

void acquire(Name|string name, int cred_usage, void|multiset(string) desired_mechs, void|int(0..) desired_time)

Description

Acquire initial credentials for this object. It is an error if it already has some credentials.

This wraps GSS_Acquire_cred according to RFC 2743 section 2.1.1.

Parameter name

The name of the identity for which credentials should be acquired. It is up to the GSS-API implementation to check whether the running process is authorized to act on behalf of this identity.

This can be either a GSSAPI.Name object or a string. In the latter case, the string is converted to a GSS-API name according to a mechanism-specific default printable syntax, i.e. just like if it would be given as the sole argument to GSSAPI.Name.create.

If this is zero then credentials for the default principal (if any) are retrieved.

Parameter cred_usage

Specifies how the credential will be used. One of GSSAPI.INITIATE, GSSAPI.ACCEPT or GSSAPI.BOTH.

Parameter desired_mechs

The mechanisms that the credentials should cover, as a multiset containing their OIDs on dotted-decimal form. If zero or left out then a default set provided by the GSS-API implementation is used.

It is an error to pass an empty multiset.

Parameter desired_time

Number of seconds the credentials should remain valid. The GSS-API implementation may return credentials that are valid both longer and shorter than this. Zero or left out means use the maximum permitted time.

Note

This function might block on network connections to remote authentication servers.


Method add

void add(Name|string name, int cred_usage, string desired_mech, void|int(0..)|array(int(0..)) desired_time)

Description

Adds another credential element to this object. If this object has no credentials already then it will get the default credentials in addition to this specified one.

This wraps GSS_Add_cred according to RFC 2743 section 2.1.4.

Parameter name

The name of the identity for which a credential should be acquired. It is up to the GSS-API implementation to check whether the running process has sufficient privileges to act on behalf of this identity.

This can be either a GSSAPI.Name object or a string. In the latter case, the string is converted to a GSS-API name according to a mechanism-specific default printable syntax, i.e. just like if it would be given as the sole argument to GSSAPI.Name.create.

If this is zero then a credential for the default principal (if any) are retrieved.

Parameter cred_usage

Specifies how the credential will be used. One of GSSAPI.INITIATE, GSSAPI.ACCEPT or GSSAPI.BOTH.

Parameter desired_mech

The mechanism that the credential should cover, as an OID on dotted-decimal form.

Parameter desired_time

Number of seconds the credential should remain valid. The GSS-API implementation may return a credential that is valid both longer and shorter than this. Zero or left out means use the maximum permitted time.

This can also be an array containing two elements. In that case the first element applies to the credential when it is used to initiate contexts, and the second element applies to use for acceptor contexts.

Note

This function might block on network connections to remote authentication servers.


Method release

void release()

Description

Frees the resources for the credential.

This wraps GSS_Release_cred according to RFC 2743 section 2.1.2.

Note

This function might block on network connections to remote authentication servers.

Class GSSAPI.Error

Description

Error object used for GSS-API errors.


Inherit Generic

inherit Error.Generic : Generic


Constant is_gssapi_error
Constant error_type

constant int GSSAPI.Error.is_gssapi_error
constant string GSSAPI.Error.error_type

Description

Object recognition constants.


Variable major_status

int GSSAPI.Error.major_status

Description

The major status code. This is a bitwise OR of one routine error code and zero or more supplementary error info bits.

See RFC 2743 section 1.2.1.1 and RFC 2744 section 3.9.1. Note that the calling errors mentioned in RFC 2744 are never thrown.

See also

major_status_messages


Variable minor_status

int GSSAPI.Error.minor_status

Description

The minor status code specific for the mechanism.

See also

minor_status_messages, minor_status_mech


Method create

GSSAPI.Error GSSAPI.Error(void|int major, void|int minor, void|string mech, void|string message, void|array backtrace)

Parameter major

Initial value for major_status.

Parameter minor

Initial value for minor_status.

Parameter mech

Object identifier on dotted-decimal form for the mechanism that minor applies to.

Parameter message

Error message. This is prepended to the message generated from major_status and/or minor_status. ": " is inserted in between.

Parameter backtrace

Backtrace. The current backtrace for the calling function is used if left out.


Method major_status_messages

array(string) major_status_messages()

Description

Returns an array containing messages for all the status values in major_status. See GSSAPI.major_status_messages for further details.


Method minor_status_mech

string|zero minor_status_mech()

Description

Returns the OID for the mechanism that is used to interpret the minor status, or zero if no mechanism has been set. It is returned on dotted-decimal form.


Method minor_status_messages

array(string) minor_status_messages()

Description

Returns an array containing messages for all the status values in minor_status. See GSSAPI.minor_status_messages for further details.

Class GSSAPI.InitContext

Description

Variant of Context which is used on the initiator side.


Inherit Context

inherit Context : Context


Method create

GSSAPI.InitContext GSSAPI.InitContext(void|Cred cred, void|Name|string target_name, void|string mech, void|int required_services, void|int desired_services, void|int(0..) desired_time)

Description

Creates a context for initiator use. This function only accepts parameters to be used later during the init call. If there are semantic problems with them, such as if the credentials are stale or the mechanism isn't supported, then they will be signalled later by init.

Parameter cred

Credentials for the identity this context claims. The credentials for the default principal (if any) is used if zero or left out.

Parameter target_name

The name of the target.

This can be either a GSSAPI.Name object or a string. In the latter case, the string is converted to a GSS-API name according to a mechanism-specific default printable syntax, i.e. just like if it would be given as the sole argument to GSSAPI.Name.create.

Some mechanisms support unnamed targets (as allowed in GSS-API v2, update 1) and in such cases this may be zero or left out.

Parameter mech

The mechanism to use. It is given as an OID on dotted-decimal form. The GSS-API implementation chooses this using system settings if it's zero or left out, which is the recommended way.

Parameter required_services

Bitfield of GSSAPI.*_FLAG flags specifying all services that must be provided in the context. If the context fail to provide any of them then it is closed and a GSSAPI.MissingServicesError is thrown.

GSSAPI.PROT_READY_FLAG is ignored in this parameter. The fact that a user calls a per-message function indicates that this service is required at that point, and a GSSAPI.MissingServicesError is thrown if it isn't.

Parameter desired_services

Bitfield of GSSAPI.*_FLAG flags specifying the context services that are wanted but not required. I.e. errors won't be thrown if any of these aren't provided. The services specified in required_services are implicit, so they need not be repeated here.

GSSAPI.PROT_READY_FLAG is ignored in this parameter.

Parameter desired_time

The desired context validity time in seconds. Zero or left out means use the default.

Note

Channel bindings (RFC 2743 section 1.1.6) are not yet implemented since that feature appear to not be in much active use, and its format is not completely specified (RFC 2744 section 3.11).


Method init

string init(void|string remote_token)

Description

Initiates a security context to send to a remote peer.

This wraps GSS_Init_sec_context according to RFC 2743 section 2.2.1.

The underlying mechanism might require several tokens to be passed back and forth to establish the context. If is_established returns zero after a call to this function then the caller must wait for a token from the remote peer to feed as remote_token in another call to this function.

Parameter remote_token

A token from the remote peer, as returned by a call to GSSAPI.AcceptContext.accept (or some other GSS_Accept_sec_context wrapper) in it. This is zero or left out on the initial call, but used later if the remote peer sends back tokens to process as part of the context establishment.

Returns

If a string is returned then it must be passed to the remote peer which will feed it to GSSAPI.AcceptContext.accept or some other GSS_Accept_sec_context wrapper. An empty string is never returned.

Zero is returned if there is no token to send to the remote peer. Note that is_established might still return zero in that case, meaning more remote tokens are necessary.

Note

This function might block on network connections to remote authentication servers.

Class GSSAPI.MissingServicesError

Description

Error object used when one or more required services are missing in a GSSAPI.Context object.


Inherit Generic

inherit Error.Generic : Generic


Constant is_gssapi_missing_services_error
Constant error_type

constant int GSSAPI.MissingServicesError.is_gssapi_missing_services_error
constant string GSSAPI.MissingServicesError.error_type

Description

Object recognition constants.


Variable services

int GSSAPI.MissingServicesError.services

Description

Bitfield of GSSAPI.*_FLAG flags for the missing services that caused the error.

See also

GSSAPI.describe_services


Method create

GSSAPI.MissingServicesError GSSAPI.MissingServicesError(void|int missing_services)

Parameter missing_services

Initial value for services.

Class GSSAPI.Name

Description

An object of this class contains a name on the internal form which is required by the GSS-API functions. See RFC 2743 section 1.1.5.


Method __hash

int hash_value( GSSAPI.Name arg )

Description

Tries to export the name (see export) and if that succeeds returns a hash made from the exported name string. Otherwise a normal hash based on this object is returned.

This means that mechanism names (MNs) can be used as indices in mappings without getting duplicate entries for the same identity.


Method `==

int res = GSSAPI.Name() == other

Description

Returns true if other is a GSSAPI.Name which contains a name that refers to the same identity as this one.

This wraps GSS_Compare_name according to RFC 2743 section 2.4.3.

If either GSSAPI.Name object is uninitialized or contains an anonymous identity then they are considered different, unless it is the very same GSSAPI.Name object (that is an inherent pike behavior).

Throws

An error is thrown if the names are incomparable, or if either of them are ill-formed.


Method canonicalize

Name canonicalize(string mech)

Description

Returns a GSSAPI.Name containing the canonical mechanism name (MN) of this name. The mechanism is given as a dotted-decimal OID in mech.

This wraps GSS_Canonicalize_name according to RFC 2743 section 2.4.14.

Note

This function might block on network connections to remote authentication servers.


Method create

GSSAPI.Name GSSAPI.Name(string name, void|string name_type)

Description

This wraps GSS_Import_name according to RFC 2743 section 2.4.5.

Parameter name

A name on string form (a contiguous string name in GSS-API parlance).

Parameter name_type

The OID on dotted-decimal form for the type of the name in name. If left out, name is parsed according to a mechanism-specific default printable syntax.

Note

If name is the result of export or a similar function then name_type should be GSSAPI.NT_EXPORT_NAME.


Method display_name
Method display_name_type

string display_name()
string display_name_type()

Description

display_name returns a representation of the name for display purposes, and display_name_type returns an OID on dotted-decimal form for the type of that name.

If no type was given to create then display_name_type might return zero.

This wraps GSS_Display_name according to RFC 2743 section 2.4.4.

See also

The GSSAPI.NT_* constants.


Method export

string export(void|string mech)

Description

Returns the name on the exported format. If mech isn't given then the name has to be a mechanism name (MN). If mech is given then the name is canonicalized according to that mechanism before being exported (see canonicalize).

This wraps GSS_Export_name according to RFC 2743 section 2.4.15.

Note

This function might block on network connections to remote authentication servers if mech is specified.


Method mechs

multiset(string) mechs()

Description

Returns the OIDs for the mechanisms that might be able to process this name. The returned OID strings are on dotted-decimal form.

This wraps GSS_Inquire_mechs_for_name according to RFC 2743 section 2.4.13.

Note

Some older GSS-API v2 implementations lack this funcion.

21.3. Cryptographic primitives

Module Crypto

Description

Various cryptographic classes and functions.

Hash modules

These are based on the Nettle.Hash API. Examples include MD5, SHA1, SHA256 and SHA3_256.

Cipher modules

These are based on the Nettle.Cipher API. Examples include AES, Arcfour, DES, DES3, CAMELLIA.

The Substitution program is compatible with Cipher.State.

Also conforming to the API are several helper modules such as predef::Nettle.BufferedCipher.Buffer, predef::Nettle.BlockCipher.CBC, predef::Nettle.BlockCipher16.GCM and Pipe.

Message Authentication Code modules (MACs)

MAC algorithms are provided as sub-modules to their corresponding Hash or Cipher module. Examples include SHA1.HMAC and AES.UMAC32.

Authenticated Encryption with Associated Data modules (AEADs)

AEADs combine ciphers with authentication codes, and may optionally also take into account some associated data that is provided out of band. This API is compatible with both Cipher and Hash. AEADs are provided as sub-modules to their corresponding ciphers. Examples include AES.CCM, AES.GCM and CAMELLIA.EAX.

As the cryptographic services offered from this module aren't necessarily used for security applications, none of the strings input or output are marked as secure. That is up to the caller.

Note

Most of the APIs in this module work on 8 bit binary strings unless otherwise noted. For conversions to and from hexadecimal notation String.string2hex() and String.hex2string() may be of interest.

Note

This module is only available if Pike has been compiled with Nettle enabled (this is the default).


Method make_crypt_md5

string(8bit) make_crypt_md5(string(8bit) password, string(8bit)|void salt)

Description

Hashes a password together with a salt with the crypt_md5 algorithm and returns the result.

See also

verify_crypt_md5


Method rot13

string(8bit) rot13(string(8bit) data)

Description

Convenience function that accesses the crypt function of a substitution object keyed to perform standard ROT13 (de)ciphering.


Method siphash24

int siphash24(string data, void|int key)

Description

Hashes a string, with an optional key, to a 64 bit integer using the siphash-2-4 algorithm. Currently the 64 bit key parameter is used both for the high and low part of the 128 bit key.


Method verify_crypt_md5

bool verify_crypt_md5(string(8bit) password, string(7bit) hash)

Description

Verifies the password against the crypt_md5 hash.

Throws

May throw an exception if the hash value is bad.

See also

make_crypt_md5

Class Crypto.AE

Description

Abstract class for AE algorithms.


Inherit AE

inherit __builtin.Nettle.AE : AE

Class Crypto.AEAD

Description

Abstract class for AEAD algorithms.


Inherit AEAD

inherit Nettle.AEAD : AEAD

Class Crypto.BlockCipher

Description

Abstract class for block cipher algorithms. Contains some tools useful for all block ciphers.

Contains the CBC submodule.


Inherit BlockCipher

inherit Nettle.BlockCipher : BlockCipher

Class Crypto.BlockCipher16

Description

Abstract class for block cipher algorithms with a 16 byte block size. Contains some tools useful for all such block ciphers.

Contains the GCM submodule.


Inherit BlockCipher16

inherit Nettle.BlockCipher16 : BlockCipher16

Class Crypto.BufferedCipher

Description

Abstract class for block cipher meta algorithms.

Contains the Buffer submodule.


Inherit BufferedCipher

inherit Nettle.BufferedCipher : BufferedCipher

Class Crypto.Cipher

Description

Abstract class for crypto algorithms. Contains some tools useful for all ciphers.

Note

Typically only inherited directly by stream ciphers.

Note

It is however convenient for typing as it contains the minimum base level API for a cipher.

See also

BufferedCipher, BlockCipher, BlockCipher16


Inherit Cipher

inherit Nettle.Cipher : Cipher

Class Crypto.HMAC

Description

HMAC, defined by RFC 2104.

Backward-compatibility implementation. New code should use Crypto.Hash.HMAC.


Method `()

Crypto.MAC.State res = Crypto.HMAC()()

Description

Calling the HMAC object with a password returns a new object that can perform the actual HMAC hashing. E.g. doing a HMAC hash with MD5 and the password "bar" of the string "foo" would require the code Crypto.HMAC(Crypto.MD5)("bar")("foo").


Method create

Crypto.HMAC Crypto.HMAC(.Hash h, int(1..)|void b)

Parameter h

The hash object on which the HMAC object should base its operations. Typical input is Crypto.MD5.

Parameter b

The block size of one compression block, in octets. Defaults to block_size() of h.


Method pkcs_digest

string(8bit) pkcs_digest(string(8bit) s)

Description

Makes a PKCS-1 digestinfo block with the message s.

See also

Standards.PKCS.Signature.build_digestinfo


Method raw_hash

string(8bit) raw_hash(string(8bit) s)

Description

Calls the hash function given to create and returns the hash value of s.

Class Crypto.Hash

Description

Abstract class for hash algorithms. Contains some tools useful for all hashes.


Inherit Hash

inherit Nettle.Hash : Hash

Class Crypto.MAC

Description

Abstract class for Message Authentication Code (MAC) algorithms. Contains some tools useful for all MACs.


Inherit MAC

inherit Nettle.MAC : MAC

Class Crypto.Pipe

Description

A wrapper class that connects several cipher algorithms into one algorithm. E.g. triple DES can be emulated with Crypto.Pipe(Crypto.DES, Crypto.DES, Crypto.DES).

Class Crypto.Sign

Description

Abstract class for signature algorithms. Contains some tools useful for all signatures.


Method `()

State res = Crypto.Sign()()

Description

Calling `() will return a State object.


Method name

string(7bit) name()

Description

Returns the printable name of the signing algorithm.

Class Crypto.Sign.State


Inherit Sign

inherit __builtin.Nettle.Sign : Sign

Class Crypto.Substitution

Description

Implements a simple substitution crypto, ie. one of the first crypto systems ever invented and thus one of the least secure ones available.


Method decrypt

string(8bit) decrypt(string(8bit) c)

Description

Decrypts the cryptogram c.


Method encrypt

string(8bit) encrypt(string(8bit) m)

Description

Encrypts the message m.


Method filter

string filter(string m, multiset(int)|void save)

Description

Removes characters not in the encryption key or in the save multiset from the message m.


Method set_ACA_K1_key

this_program set_ACA_K1_key(string key, void|int offset, array(string)|void alphabet)

Description

Sets the key according to ACA K1 key generation. The plaintext alphabet is prepended with a keyword key that shifts the alphabet positions compared to the cryptogram alphabet. The plaintext alphabet is then reduced with the characters in the keyword. It is also optionally rotated offset number of steps.


Method set_ACA_K2_key

this_program set_ACA_K2_key(string key, void|int offset, array(string)|void alphabet)

Description

Sets the key according to ACA K2 key generation. The cryptogram alphabet is prepended with a keyword key that shifts the alphabet positions compared to the plaintext alphabet. The cryptogram alphabet is then reduced with the characters in the keyword. It is als optionally reotated offset number of steps.


Method set_ACA_K3_key

this_program set_ACA_K3_key(string key, int offset, array(string)|void alphabet)

Description

Sets the key according to ACA K3 key generation. Both the plaintext and the cryptogram alphabets are prepended with a keyword key, which characters are removed from the rest of the alphabet. The plaintext alphabet is then rotated offset number of steps.


Method set_ACA_K4_key

this_program set_ACA_K4_key(string key1, string key2, void|int offset, array(string)|void alphabet)

Description

Sets the key according to ACA K4 key generation. Both the plaintext and the cryptogram alphabets are prepended with the keywords key1 and key2. The plaintext alphabet is then rotated offset number of steps.


Method set_key

this_program set_key(mapping(string:string|array(string)) key)

Description

Sets the encryption and decryption key. The decryption key is derived from the encryption key by reversing the mapping. If one index maps to an array of strings, one element from the array will be chosen at random in such substitution.

Throws

An error is thrown if the encryption key can not be made reversible.


Method set_null_chars

this_program set_null_chars(int|float p, array(string) chars)

Description

Set null characters (fillers). Characters from chars will be inserted into the output stream with a probability p.

Parameter p

A float between 0.0 and 1.0 or an integer between 0 and 100.

Parameter chars

An array of one character strings.


Method set_rot_key

this_program set_rot_key(int(1..)|void steps, void|array(string) alphabet)

Description

Sets the key to a ROT substitution system. steps defaults to 13 and alphabet defaults to A-Z, i.e. this function defaults to set the substitution crypto to be ROT13. If no alphabet is given the key will be case insensitive, e.g. the key will really be two ROT13 alphabets, one a-z and one A-Z, used simultaneously.

Module Crypto.AES

Description

AES (American Encryption Standard) is a quite new block cipher, specified by NIST as a replacement for the older DES standard. The standard is the result of a competition between cipher designers. The winning design, also known as RIJNDAEL, was constructed by Joan Daemen and Vincent Rijnmen.

Like all the AES candidates, the winning design uses a block size of 128 bits, or 16 octets, and variable key-size, 128, 192 and 256 bits (16, 24 and 32 octets) being the allowed key sizes. It does not have any weak keys.


Inherit AES

inherit Nettle.AES : AES

Module Crypto.AES.POLY1305


Inherit POLY1305_AES

inherit Nettle.POLY1305_AES : POLY1305_AES


Method `()

protected State `()(string(8bit) password)

Description

Get a POLY1305 State object initialized with a password.

Module Crypto.AES.UMAC128

Description

UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

UMAC128 outputs a digest of 128 bits or 16 octets.

See also

UMAC32, UMAC64, UMAC96


Inherit UMAC128_AES

inherit Nettle.UMAC128_AES : UMAC128_AES


Method `()

protected State `()(string(8bit) password)

Description

Get a UMAC128 State object initialized with a password.

Module Crypto.AES.UMAC32

Description

UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

UMAC32 outputs a digest of 32 bits or 4 octets.

See also

UMAC64, UMAC96, UMAC128


Inherit UMAC32_AES

inherit Nettle.UMAC32_AES : UMAC32_AES


Method `()

protected State `()(string(8bit) password)

Description

Get a UMAC32 State object initialized with a password.

Module Crypto.AES.UMAC64

Description

UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

UMAC64 outputs a digest of 64 bits or 8 octets.

See also

UMAC32, UMAC96, UMAC128


Inherit UMAC64_AES

inherit Nettle.UMAC64_AES : UMAC64_AES


Method `()

protected State `()(string(8bit) password)

Description

Get a UMAC64 State object initialized with a password.

Module Crypto.AES.UMAC96

Description

UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

UMAC96 outputs a digest of 96 bits or 12 octets.

See also

UMAC32, UMAC64, UMAC128


Inherit UMAC96_AES

inherit Nettle.UMAC96_AES : UMAC96_AES


Method `()

protected State `()(string(8bit) password)

Description

Get a UMAC96 State object initialized with a password.

Module Crypto.Arcfour

Description

Arcfour is a stream cipher, also known under the trade marked name RC4, and it is one of the fastest ciphers around. A problem is that the key setup of Arcfour is quite weak, you should never use keys with structure, keys that are ordinary passwords, or sequences of keys like "secret:1", "secret:2", ..... If you have keys that don't look like random bit strings, and you want to use Arcfour, always hash the key before feeding it to Arcfour.


Inherit ARCFOUR

inherit Nettle.ARCFOUR : ARCFOUR

Module Crypto.Arctwo

Description

Arctwo is a block cipher, also known under the trade marked name RC2.

The cipher is quite weak, and should not be used for new software.


Inherit ARCTWO

inherit Nettle.ARCTWO : ARCTWO

Module Crypto.Blowfish

Description

BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block size of 64 bits (8 octets), and a variable key size, up to 448 bits. It has some weak keys.


Inherit BLOWFISH

inherit Nettle.BLOWFISH : BLOWFISH

Module Crypto.CAST

Description

CAST-128 is a block cipher, specified in RFC 2144. It uses a 64 bit (8 octets) block size, and a variable key size of up to 128 bits.


Inherit CAST128

inherit Nettle.CAST128 : CAST128

Module Crypto.Camellia

Description

The Camellia 128-bit block cipher.


Inherit CAMELLIA

inherit Nettle.CAMELLIA : CAMELLIA

Module Crypto.ChaCha20

Description

ChaCha20 is a stream cipher by D. J. Bernstein.

Note

This module is not available in all versions of Nettle.


Inherit CHACHA

inherit Nettle.CHACHA : CHACHA

Module Crypto.ChaCha20.POLY1305

Description

This is an AEAD cipher consisting of the CHACHA cipher and a MAC based on the POLY1305 algorithm.

Note

Note that this is an AEAD cipher, while AES.POLY1305 (aka POLY1305-AES) is a MAC.

Note

Note also that the POLY1305 algorithm used here is NOT identical to the one in the AES.POLY1305 MAC. The iv/nonce handling differs.

Note

This module is not available in all versions of Nettle.


Inherit CHACHA_POLY1305

inherit Nettle.CHACHA_POLY1305 : CHACHA_POLY1305

Module Crypto.Checksum

Description

Some non-cryptographic checksums.


Method adler32

int(0..) adler32(string(8bit) data, void|int(0..) seed)

Description

This function calculates the Adler-32 Cyclic Redundancy Check.

Parameter seed

Can be fed with the result of the previous invocation to chain on new data. Defaults to zero on virgin runs.


Method crc32

int(0..) crc32(string(8bit) data, void|int(0..) seed)

Description

This function calculates the standard ISO3309 Cyclic Redundancy Check.

Parameter seed

Can be fed with the result of the previous invocation to chain on new data. Defaults to zero on virgin runs.


Method crc32c

int(0..) crc32c(string(8bit) data, void|int(0..) seed)

Description

This function calculates the Castagnoli CRC, CRC32C. Hardware optimized on Intel CPUs with SSE 4.2.

Parameter seed

Can be fed with the result of the previous invocation to chain on new data. Defaults to zero on virgin runs.

Module Crypto.DES

Description

DES is the old Data Encryption Standard, specified by NIST. It uses a block size of 64 bits (8 octets), and a key size of 56 bits. However, the key bits are distributed over 8 octets, where the least significant bit of each octet is used for parity. A common way to use DES is to generate 8 random octets in some way, then set the least significant bit of each octet to get odd parity, and initialize DES with the resulting key.

The key size of DES is so small that keys can be found by brute force, using specialized hardware or lots of ordinary work stations in parallel. One shouldn't be using plain DES at all today, if one uses DES at all one should be using DES3 or "triple DES".

DES also has some weak keys.


Inherit DES

inherit Nettle.DES : DES

Module Crypto.DES3

Description

The inadequate key size of DES has already been mentioned. One way to increase the key size is to pipe together several DES boxes with independent keys. It turns out that using two DES ciphers is not as secure as one might think, even if the key size of the combination is a respectable 112 bits.

The standard way to increase DES's key size is to use three DES boxes. The mode of operation is a little peculiar: the middle DES box is wired in the reverse direction. To encrypt a block with DES3, you encrypt it using the first 56 bits of the key, then decrypt it using the middle 56 bits of the key, and finally encrypt it again using the last 56 bits of the key. This is known as "ede" triple-DES, for "encrypt-decrypt-encrypt".

The "ede" construction provides some backward compatibility, as you get plain single DES simply by feeding the same key to all three boxes. That should help keeping down the gate count, and the price, of hardware circuits implementing both plain DES and DES3.

DES3 has a key size of 168 bits, but just like plain DES, useless parity bits are inserted, so that keys are represented as 24 octets (192 bits). As a 112 bit key is large enough to make brute force attacks impractical, some applications uses a "two-key" variant of triple-DES. In this mode, the same key bits are used for the first and the last DES box in the pipe, while the middle box is keyed independently. The two-key variant is believed to be secure, i.e. there are no known attacks significantly better than brute force.


Inherit DES3

inherit Nettle.DES3 : DES3

Module Crypto.DH

Description

Diffie-Hellman key-exchange related stuff.


Variable FFDHE2048

Parameters Crypto.DH.FFDHE2048

Description

Finite Field Diffie-Hellman 2048

From RFC 7919 appendix A.1.


Variable FFDHE2432

Parameters Crypto.DH.FFDHE2432

Description

Finite Field Diffie-Hellman 2432

Mentioned in Negotiated FF-DHE for TLS draft 06, March 2015, Section 2.


Variable FFDHE3072

Parameters Crypto.DH.FFDHE3072

Description

Finite Field Diffie-Hellman 3072

From RFC 7919 appendix A.2.


Variable FFDHE4096

Parameters Crypto.DH.FFDHE4096

Description

Finite Field Diffie-Hellman 4096

From RFC 7919 appendix A.3.


Variable FFDHE6144

Parameters Crypto.DH.FFDHE6144

Description

Finite Field Diffie-Hellman 6144

From RFC 7919 appendix A.4.


Variable FFDHE8192

Parameters Crypto.DH.FFDHE8192

Description

Finite Field Diffie-Hellman 8192

From RFC 7919 appendix A.5.


Variable MODPGroup1

Parameters Crypto.DH.MODPGroup1

Description

MODP Group 1 (768 bit) (aka First Oakley Group (aka ORM96 group 1)).

RFC 2409 section 6.1

Note

Not allowed for use with FIPS 140.


Variable MODPGroup14

Parameters Crypto.DH.MODPGroup14

Description

MODP Group 14 (2048 bit).

RFC 3526 section 3


Variable MODPGroup15

Parameters Crypto.DH.MODPGroup15

Description

MODP Group 15 (3072 bit).

RFC 3526 section 4


Variable MODPGroup16

Parameters Crypto.DH.MODPGroup16

Description

MODP Group 16 (4096 bit).

RFC 3526 section 5


Variable MODPGroup17

Parameters Crypto.DH.MODPGroup17

Description

MODP Group 17 (6144 bit).

RFC 3526 section 6


Variable MODPGroup18

Parameters Crypto.DH.MODPGroup18

Description

MODP Group 18 (8192 bit).

RFC 3526 section 7


Variable MODPGroup2

Parameters Crypto.DH.MODPGroup2

Description

MODP Group 2 (1024 bit) (aka Second Oakley Group (aka ORM96 group 2)).

RFC 2409 section 6.2

Note

Not allowed for use with FIPS 140.


Variable MODPGroup22

Parameters Crypto.DH.MODPGroup22

Description

MODP Group 22 (1024-bit with 160-bit Subgroup).

RFC 5114 section 2.1


Variable MODPGroup23

Parameters Crypto.DH.MODPGroup23

Description

MODP Group 23 (2048-bit with 224-bit Subgroup).

RFC 5114 section 2.2


Variable MODPGroup24

Parameters Crypto.DH.MODPGroup24

Description

MODP Group 24 (2048-bit with 256-bit Subgroup).

RFC 5114 section 2.3


Variable MODPGroup5

Parameters Crypto.DH.MODPGroup5

Description

MODP Group 5 (1536 bit).

RFC 3526 section 2

Note

Not allowed for use with FIPS 140.

Class Crypto.DH.Parameters

Description

Diffie-Hellman parameters.


Inherit DH_Params

inherit Nettle.DH_Params : DH_Params


Variable g

Gmp.mpz|zero Crypto.DH.Parameters.g

Description

Generator.


Variable p

Gmp.mpz|zero Crypto.DH.Parameters.p

Description

Prime.


Variable q

Gmp.mpz|zero Crypto.DH.Parameters.q

Description

Subgroup size.


Method create

Crypto.DH.Parameters Crypto.DH.Parameters(this_program other)

Description

Initialize the set of Diffie-Hellman parameters.

Parameter other

Copy the parameters from this object.


Method create

Crypto.DH.Parameters Crypto.DH.Parameters(DSA_State dsa)

Description

Initialize the set of Diffie-Hellman parameters.

Parameter dsa

Copy the parameters from this object.


Method create

Crypto.DH.Parameters Crypto.DH.Parameters(Gmp.mpz|int p, Gmp.mpz|int|void g, Gmp.mpz|int|void q)

Description

Initialize the set of Diffie-Hellman parameters.

Parameter p

The prime for the group.

Parameter g

The generator for the group. Defaults to 2.

Parameter q

The order of the group. Defaults to (p-1)/2.


Method generate_keypair

array(Gmp.mpz) generate_keypair(function(int(0..):string(8bit)) rnd)

Description

Generate a Diffie-Hellman key pair.

Returns

Returns the following array:

Array
Gmp.mpz 0

The generated public key.

Gmp.mpz 1

The corresponding private key.


Method validate

bool validate(int(0..) effort)

Description

Validate that the DH Parameters doesn't have obvious security weaknesses. It will first attempt to verify the prime p using Donald Knuth's probabilistic primality test with provided effort. This has a chance of pow(0.25,effort) to produce a false positive. An effort of 0 skipps this step. The second test verifies that g is of high order.

Module Crypto.DSA

Description

The Digital Signature Algorithm DSA is part of the NIST Digital Signature Standard DSS, FIPS-186 (1993).


Inherit Sign

inherit Crypto.Sign : Sign


Method `()

protected State `()()

Description

Calling `() will return a State object.


Method name

string(8bit) name()

Description

Returns the string "DSA".

Class Crypto.DSA.State


Inherit this_program

inherit ::this_program : this_program


Method _equal

bool equal(Crypto.DSA.State from, mixed other)

Description

Compares the keys of this DSA object with something other.


Method generate_key

variant this_program generate_key()

Description

Generates a public/private key pair. Needs the public parameters p, q and g set, through one of set_public_key, generate_key(int,int) or generate_key(params).


Method generate_key

variant this_program generate_key(int p_bits, int q_bits)

Description

Generates DSA parameters (p, q, g) and key (x, y). Depending on Nettle version q_bits can be 160, 224 and 256 bits. 160 works for all versions.


Method generate_key

variant this_program generate_key(.DH.Parameters params)

Description

Generates a public/private key pair with the specified finite field diffie-hellman parameters.


Method get_g

Gmp.mpz|zero get_g()

Description

Returns the DSA generator (g).


Method get_p

Gmp.mpz|zero get_p()

Description

Returns the DSA modulo (p).


Method get_q

Gmp.mpz|zero get_q()

Description

Returns the DSA group order (q).


Method get_x

Gmp.mpz|zero get_x()

Description

Returns the DSA private key (x).


Method get_y

Gmp.mpz|zero get_y()

Description

Returns the DSA public key (y).


Method hash

Gmp.mpz hash(string(8bit) msg, .Hash h)

Description

Makes a DSA hash of the message msg.


Method name

string(8bit) name()

Description

Returns the string "DSA".


Method pkcs_algorithm_identifier

Sequence pkcs_algorithm_identifier()

Description

Returns the AlgorithmIdentifier as defined in RFC 5280 section 4.1.1.2 including the DSA parameters.


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 DSA and the provided hash algorithm. Only SHA1 supported.


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

Description

Compares the public key in this object with that in the provided DSA object.


Method raw_sign

array(Gmp.mpz) raw_sign(Gmp.mpz h, Gmp.mpz|void k)

Description

Sign the message h. Returns the signature as two Gmp.mpz objects.


Method raw_verify

bool raw_verify(Gmp.mpz h, Gmp.mpz r, Gmp.mpz s)

Description

Verify the signature r,s against the message h.


Method set_private_key

this_program set_private_key(Gmp.mpz secret)

Description

Sets the private key, the x parameter, in this DSA object.


Method set_public_key

this_program set_public_key(Gmp.mpz modulo, Gmp.mpz order, Gmp.mpz generator, Gmp.mpz key)

Description

Sets the public key in this DSA object.

Parameter modulo

This is the p parameter.

Parameter order

This is the group order q parameter.

Parameter generator

This is the g parameter.

Parameter kye

This is the public key y parameter.


Method set_public_key

variant this_program set_public_key(.DH.Parameters params, Gmp.mpz key)

Description

Sets the public key in this DSA object.

Parameter params

The finite-field diffie-hellman group parameters.

Parameter key

The public key y parameter.


Method set_random

this_program set_random(function(int(0..):string(8bit)) r)

Description

Sets the random function, used to generate keys and parameters, to the function r. Default is random_string.

Module Crypto.ECC

Description

Elliptic Curve Cipher Constants.

This module contains constants used with elliptic curve algorithms.

Class Crypto.ECC.Curve

Description

The definition of an elliptic curve.

Objects of this class are typically not created by the user.

See also

SECP_192R1, SECP_224R1, SECP_256R1, SECP_384R1, SECP_521R1


Inherit ECC_Curve

inherit Nettle.ECC_Curve : ECC_Curve


Method pkcs_algorithm_identifier

Sequence pkcs_algorithm_identifier()

Description

Returns the AlgorithmIdentifier as defined in RFC 5480 section 2.


Method pkcs_ec_parameters

Identifier pkcs_ec_parameters()

Description

Returns the PKCS-1 elliptic curve parameters for the curve. cf RFC 5480 section 2.1.1.


Method pkcs_named_curve_id

Identifier|zero pkcs_named_curve_id()

Description

Returns the PKCS-1 elliptic curve identifier for the curve. cf RFC 5480 section 2.1.1.

Class Crypto.ECC.Curve.ECDSA

Description

Elliptic Curve Digital Signing Algorithm


Inherit ECDSA

inherit ECC_Curve::ECDSA : ECDSA


Method _equal

bool equal(Crypto.ECC.Curve.ECDSA from, mixed other)

Description

Compares the keys of this ECDSA object with something other.


Method generate_key

this_program generate_key()

Description

Generate a new set of private and public keys on the current curve.


Method get_curve

Curve get_curve()

Description

Return the curve.


Method get_point

Point get_point()

Description

Get the public key curve point.


Method get_public_key

string(8bit) get_public_key()

Description

Get the ANSI x9.62 4.3.6 encoded uncompressed public key.


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

See also

pkcs_verify(), RFC 7515 section 3.5


Method jose_sign

string(7bit)|zero jose_sign(string(8bit) message, .Hash|void h, mapping(string(7bit):string(7bit)|int)|void headers)

Description

Signs the message with a JOSE JWS ECDSA signature using hash algorithm h.

Parameter message

Message to sign.

Parameter h

Hash algorithm to use.

Returns

Returns the signature on success, and 0 (zero) on failure.

See also

pkcs_verify(), salt_size(), RFC 7515


Method jwa

string(7bit)|zero jwa(.Hash hash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


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

If true, include the private key in the result.

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


Method key_size

int(0..) key_size()

Description

Return the size of the private key in bits.


Method pkcs_algorithm_identifier

Sequence pkcs_algorithm_identifier()

Description

Returns the AlgorithmIdentifier as defined in RFC 5480 section 2.1.1 including the ECDSA parameters.


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 and RFC 5480 section 2.2.


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 ECDSA and the provided hash algorithm. Only SHA-1 and SHA-2 based hashes are supported currently.


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

Description

Compares the public key in this object with that in the provided ECDSA object.


Method set_private_key

this_program set_private_key(Gmp.mpz|int k)

Description

Set the private key.

Note

Throws errors if the key isn't valid for the curve.


Method set_private_key

variant this_program set_private_key(string(8bit) k)

Description

Set the private key.

Note

Throws errors if the key isn't valid for the curve.


Method set_public_key

this_program set_public_key(Gmp.mpz|int x, Gmp.mpz|int y)

Description

Change to the selected point on the curve as public key.

Note

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


Method set_public_key

variant this_program set_public_key(string(8bit) key)

Description

Change to the selected point on the curve as public key.

Parameter key

The public key encoded according to ANSI x9.62 4.3.6.

Note

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


Method set_random

this_program set_random(function(int:string(8bit)) r)

Description

Set the random function, used to generate keys and parameters, to the function r.


Method size

int size()

Description

Return the curve size in bits.

Module Crypto.ECC.Curve25519

Description

The definition of the elliptic curve X25519.

See also

Curve, Curve448


Inherit Curve25519

inherit Nettle.Curve25519 : Curve25519


Method pkcs_algorithm_identifier

Sequence pkcs_algorithm_identifier()

Description

Returns the AlgorithmIdentifier for the curve as defined in RFC 8410 section 3.


Method pkcs_eddsa_id

Identifier pkcs_eddsa_id()

Description

Returns the EdDSA AlgorithmIdentifier as defined in RFC 8410 section 3.


Method pkcs_named_curve_id

Identifier pkcs_named_curve_id()

Description

Returns the PKCS-1 elliptic curve identifier for the curve. cf RFC 8410 section 3.

Class Crypto.ECC.Curve25519.EdDSA

Description

Edwards Curve Digital Signing Algorithm


Inherit EdDSA

inherit Curve25519::EdDSA : EdDSA


Method _equal

bool equal(Crypto.ECC.Curve25519.EdDSA from, mixed other)

Description

Compares the keys of this ECDSA object with something other.


Method generate_key

this_program generate_key()

Description

Generate a new set of private and public keys on the current curve.


Method get_curve

_Curve25519 get_curve()

Description

Return the curve.


Method get_point

Point get_point()

Description

Get the public key curve point.


Method get_public_key

string(8bit) get_public_key()

Description

Get the ANSI x9.62 4.3.6 encoded uncompressed public key.


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

See also

pkcs_verify(), RFC 7515 section 3.5


Method jose_sign

string(7bit)|zero jose_sign(string(8bit) message, .Hash|void h, mapping(string(7bit):string(7bit)|int)|void headers)

Description

Signs the message with a JOSE JWS EdDSA signature.

Parameter message

Message to sign.

Parameter h

Hash algorithm to use; ignored for Ed25519.

Returns

Returns the signature on success, and 0 (zero) on failure.

See also

pkcs_verify(), salt_size(), RFC 7515


Method jwa

string(7bit) jwa(.Hash|void hash)

Description

Get the JWS algorithm identifier for a hash.

Parameter hash

Hash algorithm; ignored for Ed25519.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


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

If true, include the private key in the result.

Returns

Returns a JWK-style mapping on success, and 0 (zero) on failure.

See also

create(), Web.encode_jwk(), RFC 8037


Method key_size

int(0..) key_size()

Description

Return the size of the private key in bits.


Method pkcs_algorithm_identifier

Sequence pkcs_algorithm_identifier()

Description

Returns the AlgorithmIdentifier as defined in RFC 5480 section 2.1.1 including the EdDSA parameters.


Method pkcs_named_curve_id

Identifier pkcs_named_curve_id()

Description

Returns the EdDSA identifier for the curve.


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

Description

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

Parameter h

Hash algorithm; ignored for Curve25519.


Method pkcs_signature_algorithm_id

Sequence pkcs_signature_algorithm_id(.Hash|void hash)

Description

Returns the PKCS-1 algorithm identifier for EdDSA and the provided hash algorithm.

Parameter hash

Hash algorithm; ignored for Curve25519.


Method pkcs_verify

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

Description

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

Parameter h

Hash algorithm; ignored for Ed25519.


Method public_key_equal

bool public_key_equal(this_program eddsa)

Description

Compares the public key in this object with that in the provided ECDSA object.


Method set_private_key

this_program set_private_key(string(8bit) k)

Description

Set the private key.

Note

Throws errors if the key isn't valid for the curve.


Method set_public_key

this_program set_public_key(string(8bit) key)


Method set_public_key

variant this_program set_public_key(Point p)


Method set_random

this_program set_random(function(int:string(8bit)) r)

Description

Set the random function, used to generate keys and parameters, to the function r.


Method size

int size()

Description

Return the curve size in bits.

Module Crypto.ECC.GOST_GC256B


Inherit Curve

inherit Curve : Curve

Module Crypto.ECC.GOST_GC512A


Inherit Curve

inherit Curve : Curve

Module Crypto.ECC.SECP_192R1


Inherit Curve

inherit Curve : Curve

Module Crypto.ECC.SECP_224R1


Inherit Curve

inherit Curve : Curve

Module Crypto.ECC.SECP_256R1


Inherit Curve

inherit Curve : Curve

Module Crypto.ECC.SECP_384R1


Inherit Curve

inherit Curve : Curve

Module Crypto.ECC.SECP_521R1


Inherit Curve

inherit Curve : Curve

Module Crypto.GOST94

Description

The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm used in Russian government standards, defined in RFC 4357.


Inherit GOST94

inherit Nettle.GOST94 : GOST94

Module Crypto.GOST94CP

Description

The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm used in Russian government standards. This is the "CryptoPro" variant.

See also

GOST94


Inherit GOST94CP

inherit Nettle.GOST94CP : GOST94CP

Module Crypto.IDEA

Description

The IDEA(tm) block cipher is covered by patents held by ETH and a Swiss company called Ascom-Tech AG. The Swiss patent number is PCT/CH91/00117, the European patent number is EP 0 482 154 B1, and the U.S. patent number is US005214703. IDEA(tm) is a trademark of Ascom-Tech AG. There is no license fee required for noncommercial use.


Inherit IDEA

inherit Nettle.IDEA : IDEA

Module Crypto.Koremutake

Description

Quote from Koremutake home page http://shorl.com/koremutake:

In an attempt to temporarily solve the fact that human beings seem to be inable to remember important things (such as their names, car keys and seemingly random numbers with fourteen digits in 'em), we invented Koremutake.

It is, in plain language, a way to express any large number as a sequence of syllables. The general idea is that word-sounding pieces of information are a lot easier to remember than a sequence of digits.


Method decrypt

int decrypt(string c)

Description

Decode a koremutake string into an integer.


Method encrypt

string encrypt(int m)

Description

Encode an integer as a koremutake string.

Module Crypto.MD2

Description

MD2 is a message digest function constructed by Burton Kaliski, and is described in RFC 1319. It outputs message digests of 128 bits, or 16 octets.


Inherit MD2

inherit Nettle.MD2 : MD2

Module Crypto.MD4

Description

MD4 is a message digest function constructed by Ronald Rivest, and is described in RFC 1320. It outputs message digests of 128 bits, or 16 octets.


Inherit MD4

inherit Nettle.MD4 : MD4

Module Crypto.MD5

Description

MD5 is a message digest function constructed by Ronald Rivest, and is described in RFC 1321. It outputs message digests of 128 bits, or 16 octets.


Inherit MD5

inherit Nettle.MD5 : MD5


Method crypt_hash

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

Description

This is a convenience alias for Nettle.crypt_md5(), that uses the same API as the other hashes.

Note

The rounds parameter is currently ignored. For forward compatibility, either leave out, or specify as 1000.

See also

Nettle.Hash()->crypt_hash(), crypt_md5()

Module Crypto.NT

Class Crypto.NT.CryptContext

Description

Class representing an HCRYPTPROV handle.


Method create

Crypto.NT.CryptContext Crypto.NT.CryptContext(string(8bit) name, string(8bit) csp, int type, int flags)

Parameter name

Key container name. When flags is set to CRYPT_VERIFYCONTEXT the name must be 0.

Parameter csp

The name of the Crypto Service Provider to use. If set to 0 the user default CSP will be used.


Method read

string(8bit) read(int size, string(8bit)|void init)

Description

Retreive some random data. Calls CryptGenRandom in the NT API.

Module Crypto.NTLM

Description

NT Lan Manager authentication protocol primitives.

Note

These functions use obsolete crypto primitives in weak and questionable ways, and should be avoided if possible. They are only intended to be used for interop with old code.

See also

[MS-NLMP]:http://download.microsoft.com/download/9/5/e/95ef66af-9026-4bb0-a41d-a4f81802d92c/[ms-nlmp].pdf


Method LMOWFv1

string(8bit) LMOWFv1(string Passwd, string User, string UserDom)

Description

Lan-Manager One-Way Function version 1.

This function is also known as LM hash.


Method LMOWFv2

string(8bit) LMOWFv2(string Passwd, string User, string UserDom)

Description

Lan-Manager One-Way Function version 2.

This function is identical to NTOWFv2().


Method NTOWFv1

string(8bit) NTOWFv1(string Passwd, string User, string UserDom)

Description

NT One-Way Function version 1.


Method NTOWFv2

string(8bit) NTOWFv2(string Passwd, string User, string UserDom)

Description

NT One-Way Function version 2.


Method SBKv1

string(8bit) SBKv1(string Passwd, string User, string UserDom)

Description

Session Base Key for NTLMv1.

Module Crypto.None

Description

The plaintext algorithm.

This modules implements several of the crypto APIs, but without any crypto. It is intended to be used for testing of higher level algorithms.


Inherit AE

inherit .AE : AE

Description

Implements the empty AE algorithm.


Inherit MAC

inherit .MAC : MAC

Description

Implements the empty MAC algorithm.


Constant mac_jwa_id

protected constant string Crypto.None.mac_jwa_id

Description

Implements the "none" JWS algorithm.

Module Crypto.PGP

Description

PGP stuff. See RFC 4880.


Method decode

mapping(string:string|mapping|array) decode(string s)

Description

Decodes PGP data.


Method decode_radix64

mapping(string:mixed) decode_radix64(string data)

Description

Decode ASCII armour.


Method encode_radix64

string encode_radix64(string data, string type, mapping(string:string)|void extra)

Description

Encode PGP data with ASCII armour.


Method verify_signature

int verify_signature(string text, string sig, string pubkey)

Description

Verify text against signature sig with the public key pubkey.

Module Crypto.RC4

Description

RC4 is a stream cipher, sometimes refered to as Arcfour, and while very fast isn't considered secure anymore.

Note

The key setup of RC4 is quite weak, so you should never use keys with structure, such as ordinary passwords. If you have keys that don't look like random bit strings, and you want to use RC4, always hash the key before feeding it to RC4.

The first few thousand bits have a slight bias, so it is not uncommon for applications to encrypt a few kilobytes of dummy data before actual encryption.


Inherit pre

inherit Nettle.ARCFOUR : pre

Module Crypto.RIPEMD160

Description

RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD (which, like MD4 and MD5, fails the collision-resistance requirement). It produces message digests of 160 bits, or 20 octets.


Inherit RIPEMD160

inherit Nettle.RIPEMD160 : RIPEMD160

Module Crypto.RSA


Inherit Sign

inherit Crypto.Sign : Sign


Method `()

protected State `()(mapping(string(8bit):Gmp.mpz|int|string(7bit))|void params)

Description

Calling `() will return a State object with the given params.

See also

State()


Method name

string(8bit) name()

Description

Returns the string "RSA".

Class Crypto.RSA.LowState


Inherit State

inherit Sign::State : State


Method _equal

bool equal(Crypto.RSA.LowState from, mixed other)

Description

Compares the keys of this RSA object with something other.


Method create

Crypto.RSA.LowState Crypto.RSA.LowState(mapping(string(8bit):Gmp.mpz|int|string(7bit))|void params)

Description

Can be initialized with a mapping with the elements n, e, d, p and q.

The mapping can either contain integer values, or be an RFC 7517 JWK-style mapping with kty set to "RSA" and contain MIME.encode_base64url()-encoded values.

See also

jwk()


Method generate_key

this_program generate_key(int(89..) bits, int(1..)|Gmp.mpz|void e)

Description

Generate a valid RSA key pair with the size bits using the random function set with set_random(). The public exponent e will be used, which defaults to 65537. Keys must be at least 89 bits.


Method get_d

Gmp.mpz|zero get_d()

Description

Returns the RSA private exponent (d), if known.


Method get_e

Gmp.mpz|zero get_e()

Description

Returns the RSA public exponent (e).


Method get_n

Gmp.mpz|zero get_n()

Description

Returns the RSA modulo (n).


Method get_p

Gmp.mpz|zero get_p()

Description

Returns the first RSA prime (p), if known.


Method get_q

Gmp.mpz|zero get_q()

Description

Returns the second RSA prime (q), if known.


Method jwa

string(7bit) jwa(.Hash hash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


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

If true, include the private key in the result. Note that if the private key isn't known, the function will fail (and return 0).

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


Method key_size

int(0..) key_size()

Description

Returns the size of the key in terms of number of bits.


Method name

string(8bit) name()

Description

Returns the string "RSA".


Method public_key_equal

bool public_key_equal(this_program rsa)

Description

Compares the public key of this RSA object with another RSA object.


Method set_decrypt_key

this_program set_decrypt_key(array(Gmp.mpz) key)

Description

Sets the public key to keyand the mod to decryption.

See also

set_encrypt_key, crypt


Method set_encrypt_key

this_program set_encrypt_key(array(Gmp.mpz) key)

Description

Sets the public key to key and the mode to encryption.

See also

set_decrypt_key, crypt


Method set_private_key

this_program set_private_key(Gmp.mpz|int priv, array(Gmp.mpz|int)|void extra)

Description

Sets the private key.

Parameter priv

The private RSA exponent, often called d.

Parameter extra
Array
Gmp.mpz|int 0

The first prime, often called p.

Gmp.mpz|int 1

The second prime, often called q.


Method set_public_key

this_program set_public_key(Gmp.mpz|int modulo, Gmp.mpz|int pub)

Description

Sets the public key.

Parameter modulo

The RSA modulo, often called n. This value needs to be >=12.

Parameter pub

The public RSA exponent, often called e.


Method set_random

this_program set_random(function(int(0..):string(8bit)) r)

Description

Sets the random function, used to generate keys and parameters, to the function r. Default is random_string.

Class Crypto.RSA.OAEPState

Description

Implementation of RSAES-OAEP (Optimal Asymmetric Encryption Padding).

See also

RFC 3447 section 7.1


Inherit LowState

inherit LowState : LowState


Variable OAEP

this_program Crypto.RSA.OAEPState.OAEP

Description

Get the OAEP encryption state.

Note

Read only


Method block_size

local int block_size()

Description

Returns the crypto block size, in bytes, or zero if not yet set.


Method crypt

local string(8bit) crypt(string(8bit) s, string(8bit)|void label)

Description

Encrypt or decrypt depending on set mode.

See also

set_encrypt_key, set_decrypt_key

Class Crypto.RSA.PKCS1_5State

Description

PKCS#1 1.5 encryption (RFC 3447 section 7.2) and signatures (RFC 3447 section 8.2).

See also

PSSState


Inherit PSSState

inherit PSSState : PSSState


Variable PKCS1_5

this_program Crypto.RSA.PKCS1_5State.PKCS1_5

Description

Get the PKCS#1 1.5 state.

Note

Read only


Method block_size

int block_size()

Description

Returns the crypto block size, in bytes, or zero if not yet set.


Method crypt

string(8bit)|zero crypt(string(8bit) s)

Description

Encrypt or decrypt depending on set mode.

See also

set_encrypt_key, set_decrypt_key


Method decrypt

string(8bit)|zero decrypt(string(8bit) s)

Description

Decrypt a message encrypted with encrypt.


Method encrypt

string(8bit) encrypt(string(8bit) s, function(int:string(8bit))|void r)

Description

Pads the message s with rsa_pad type 2, signs it and returns the signature as a byte string.

Parameter r

Optional random function to be passed down to rsa_pad.


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 RSASSA-PKCS-v1.5 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

pkcs_verify(), RFC 7515 section 3.5


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 RSASSA-PKCS-v1.5 signature using hash algorithm h.

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. Currently defaults to SHA256.

Returns

Returns the signature on success, and 0 (zero) on failure (typically that the hash + salt combo is too large for the RSA modulo).

See also

pkcs_verify(), salt_size(), RFC 7515


Method jwa

string(7bit)|zero jwa(.Hash hash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


Method name

string(8bit) name()

Description

Returns the string "RSA".


Method pkcs_public_key

Sequence pkcs_public_key()

Description

Calls Standards.PKCS.RSA.build_public_key with this object as argument.


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. This is equivalent to I2OSP(RSASP1(OS2IP(RSAES-PKCS1-V1_5-ENCODE(message)))) in PKCS#1 v2.2.


Method pkcs_signature_algorithm_id

Sequence pkcs_signature_algorithm_id(.Hash hash)

Description

Calls Standards.PKCS.RSA.signature_algorithm_id with the provided hash.


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 raw_sign

Gmp.mpz raw_sign(string(8bit) digest)

Description

Pads the digest with rsa_pad type 1 and signs it. This is equivalent to RSASP1(OS2IP(RSAES-PKCS1-V1_5-ENCODE(message))) in PKCS#1 v2.2.


Method raw_verify

bool raw_verify(string(8bit) digest, Gmp.mpz s)

Description

Verifies the digest against the signature s, assuming pad type 1.

See also

rsa_pad, raw_sign


Method rsa_pad

Gmp.mpz rsa_pad(string(8bit) message, int(1..2) type, function(int(0..):string(8bit))|void random)

Description

Pads the message to the current block size with method type and returns the result as an integer. This is equivalent to OS2IP(RSAES-PKCS1-V1_5-ENCODE(message)) in PKCS#1 v2.2.

Parameter type
1

The message is padded with 0xff bytes.

2

The message is padded with random data, using the random function if provided. Otherwise the default random function set in the object will be used.


Method rsa_unpad

string(8bit)|zero rsa_unpad(Gmp.mpz block, int type)

Description

Reverse the effect of rsa_pad.

Class Crypto.RSA.PSSState

Description

RSA PSS signatures (RFC 3447 section 8.1).

See also

PKCS1_5State


Inherit OAEPState

inherit OAEPState : OAEPState


Variable PSS

this_program Crypto.RSA.PSSState.PSS

Description

Get the PSS signature state.

Note

Read only


Method jose_decode

local array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zero jose_decode(string(7bit) jws)

Description

Verify and decode a JOSE JWS RSASSA-PSS 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.

See also

pkcs_verify(), RFC 7515 section 3.5


Method jose_sign

local 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 RSASSA-PSS signature using hash algorithm h.

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. Currently defaults to SHA256.

Returns

Returns the signature on success, and 0 (zero) on failure (typically that the hash + salt combo is too large for the RSA modulo).

See also

pkcs_sign(), salt_size(), RFC 7515 section 3.5


Method jwa

local string(7bit)|zero jwa(.Hash hash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


Method pkcs_sign

local string(8bit) pkcs_sign(string(8bit) message, .Hash h, string(8bit)|int(0..)|void salt)

Description

Signs the message with a RSASSA-PSS signature using hash algorithm h.

Parameter message

Message to sign.

Parameter h

Hash algorithm to use.

Parameter salt

Either of

int(0..)

Use a random salt of this length for the signature.

zero|void

Use a random salt of length salt_size().

string(8bit)

Use this specific salt.

Returns

Returns the signature on success, and 0 (zero) on failure (typically that the hash + salt combo is too large for the RSA modulo).

See also

pkcs_verify(), salt_size(), RFC 3447 section 8.1.1


Method pkcs_signature_algorithm_id

local Sequence pkcs_signature_algorithm_id(.Hash hash, int(0..)|void saltlen)

Description

Calls Standards.PKCS.RSA.pss_signature_algorithm_id with the provided hash and saltlen.

Parameter hash

Hash algorithm for the signature.

Parameter saltlen

Length of the salt for the signature. Defaults to the value returned by salt_size().


Method pkcs_verify

local bool pkcs_verify(string(8bit) message, .Hash h, string(8bit) sign, int(0..)|void saltlen)

Description

Verify RSASSA-PSS signature sign of message message using hash algorithm h.

See also

RFC 3447 section 8.1.2

Class Crypto.RSA.State


Inherit PKCS1_5State

inherit PKCS1_5State : PKCS1_5State

Module Crypto.Random

Description

This module contains a pseudo random number generator (PRNG) designed to give you the best possible random number generation. The current design is based on the Fortuna PRNG, but uses the system random source as input.


Inherit Fast

inherit Random.Fast : Fast


Method add_entropy

void add_entropy(string(8bit) data)

Description

Inject additional entropy into the random generator. One possible use is to persist random data between executions of an application. The internal state is approximately 256 bits, so storing 32 bytes from random_string() at shutdown and injecting them through add_entropy() again at startup should carry over the entropy. Note that this doesn't affect the independent initialization that happens in the generator at startup, so the output sequence will be different than if the application had continued uninterrupted.

Parameter data

The random string.


Method random_string

string(8bit) random_string(int(0..) len)

Description

Returns a string of length len with random content. The content is generated by a Fortuna random generator that is updated with output from /dev/urandom on UNIX and CryptGenRandom on NT.

Module Crypto.SALSA20

Description

The SALSA20 stream cipher.


Inherit SALSA20

inherit Nettle.SALSA20 : SALSA20

Module Crypto.SALSA20R12

Description

The SALSA20 stream cipher reduced to just 12 rounds.


Inherit SALSA20R12

inherit Nettle.SALSA20R12 : SALSA20R12

Module Crypto.SHA1

Description

SHA1 is a hash function specified by NIST (The U.S. National Institute for Standards and Technology). It outputs hash values of 160 bits, or 20 octets.


Inherit SHA1

inherit Nettle.SHA1 : SHA1

Module Crypto.SHA1.HMAC


Inherit this_program

inherit ::this_program : this_program


Method crypt_hash

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

Description

crypt_sha1() from NetBSD.

Module Crypto.SHA224

Description

SHA224 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 224 bits, or 28 octets.


Inherit SHA224

inherit Nettle.SHA224 : SHA224

Module Crypto.SHA256

Description

SHA256 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 256 bits, or 32 octets.


Inherit SHA256

inherit Nettle.SHA256 : SHA256

Module Crypto.SHA384

Description

SHA384 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 384 bits, or 48 octets.


Inherit SHA384

inherit Nettle.SHA384 : SHA384

Module Crypto.SHA3_224

Description

SHA-3-224 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 224 bits, or 28 octets.


Inherit SHA3_224

inherit Nettle.SHA3_224 : SHA3_224

Module Crypto.SHA3_256

Description

SHA-3-256 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 256 bits, or 32 octets.


Inherit SHA3_256

inherit Nettle.SHA3_256 : SHA3_256

Module Crypto.SHA3_384

Description

SHA-3-386 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 256 bits, or 48 octets.


Inherit SHA3_384

inherit Nettle.SHA3_384 : SHA3_384

Module Crypto.SHA3_512

Description

SHA-3-512 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 512 bits, or 64 octets.


Inherit SHA3_512

inherit Nettle.SHA3_512 : SHA3_512

Module Crypto.SHA512

Description

SHA512 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 512 bits, or 64 octets.


Inherit SHA512

inherit Nettle.SHA512 : SHA512

Module Crypto.SHA512_224

Description

SHA512/224 is another hash function specified by NIST. It is similar to SHA512 except it uses a different initialization and the output is truncated to 224 bits, or 28 octets.


Inherit SHA512_224

inherit Nettle.SHA512_224 : SHA512_224

Module Crypto.SHA512_256

Description

SHA512/256 is another hash function specified by NIST. It is similar to SHA512 except it uses a different initialization and the output is truncated to 256 bits, or 32 octets.


Inherit SHA512_256

inherit Nettle.SHA512_256 : SHA512_256

Module Crypto.SHAKE_256

Description

SHAKE-256 is an extendable output function (XOF) based on SHA3_256. It can provide an output digest of any length.

See also

SHA3_256.shake()


Inherit SHA3_256

inherit Crypto.SHA3_256 : SHA3_256

Module Crypto.SM3

Description

SM3 is a cryptographic hash function standard adopted by the government of the People's Republic of China. It outputs hash values of 256 bits, or 32 octets.


Inherit SM3

inherit Nettle.SM3 : SM3

Module Crypto.SM4

Description

The SM4 block cipher.


Inherit SM4

inherit Nettle.SM4 : SM4

Module Crypto.STREEBOG256

Description

The STREEBOG256 algorithm is a member of the Streebog (GOST R 34.11-2012) family of hash algorithms, and is used in Russian government standards.

See also

STREEBOG512


Inherit STREEBOG256

inherit Nettle.STREEBOG256 : STREEBOG256

Module Crypto.STREEBOG512

Description

The STREEBOG512 algorithm is a member of the Streebog (GOST R 34.11-2012) family of hash algorithms, and is used in Russian government standards.

See also

STREEBOG256


Inherit STREEBOG512

inherit Nettle.STREEBOG512 : STREEBOG512

Module Crypto.Serpent

Description

SERPENT is one of the AES finalists, designed by Ross Anderson, Eli Biham and Lars Knudsen. Thus, the interface and properties are similar to AES'. One peculiarity is that it is quite pointless to use it with anything but the maximum key size, smaller keys are just padded to larger ones.


Inherit SERPENT

inherit Nettle.SERPENT : SERPENT

Module Crypto.Twofish

Description

Another AES finalist, this one designed by Bruce Schneier and others.


Inherit Twofish

inherit Nettle.Twofish : Twofish

Module Nettle

Description

Low level crypto functions used by the Crypto module. Unless you are doing something very special, you would want to use the Crypto module instead.


Method bcrypt_hash

string(7bit) bcrypt_hash(string(8bit) password, string(7bit) scheme, string(8bit)|void salt, int|void log2rounds)

Description

Low level implementation of the bcrypt password-hashing algorithm.

Parameter password

The cleartext password. Only accepts 8-bit strings. Typically passwords are encoded in UTF-8 NFC, but some platforms may have other conventions.

Parameter scheme

Specifies the scheme to be used to generate the hash. The settings either cleanly specify the scheme of either "2a", "2b", "2x" or "2y", or they contain the (or part of the prefix of) normal hashed password string, so an existing hashed password string may be passed unmodified.

When generating a new hash from scratch, the following minimum needs to be specified, e.g. "$2y$10$1b2lPgo4XumibnJGN3r3sO". In this "$" is the separator, "2y" specifies the used hash-algorithm, "10" specifies 2^10 encryption rounds and "1b2lPgo4XumibnJGN3r3sO" is the salt (16 bytes, base64 encoded). The minimal value for settings would be "$2y$".

Parameter salt

The salt can be supplied as part of settings, or separately as a 16-byte binary string.

Parameter log2rounds

The log2 number of encryption rounds. If unspecified it is taken from the settings string, and if not specified there it defaults to 10 which equals 1024 encryption rounds.

Returns

Returns the (according to the specified algorithm, encryption rounds, and salt) hashed and encoded version of the supplied password. Throws an error on invalid input.

Note

You should normally use Crypto.Password instead.

See also

Crypto.Password, Crypto.BLOWFISH


Method bcrypt_verify

int bcrypt_verify(string(8bit) password, string(7bit) hashedpassword)

Description

Low level implementation of the bcrypt password-verifying algorithm.

Parameter password

The cleartext password. Only accepts 8-bit strings.

Parameter hashedpassword

This is the full hashed password string.

Returns

Returns 1 if the cleartext password matches the hashed password and zero otherwise.

Note

You should normally use Crypto.Password instead.

See also

Crypto.Password, Crypto.BLOWFISH


Method crc32c

int(0..) crc32c(string(8bit) data, void|int(0..) seed)

Description

Implements the Castagnoli CRC, CRC32C. Hardware optimized on Intel CPUs with SSE 4.2.

Parameter seed

Can be fed with the result of the previous invocation to chain on new data. Defaults to zero on virgin runs.


Method crypt_md5

string(7bit) crypt_md5(string(8bit) password, string(8bit) salt, void|string(8bit) magic)

Description

Does the crypt_md5 abrakadabra (MD5 + snakeoil). It is assumed that salt does not contain "$".

The password memory will be cleared before released.


Method dsa_generate_keypair

array(Gmp.mpz) dsa_generate_keypair(int p_bits, int q_bits, function(int(0..):string(8bit)) rnd)

Description

Generates a DSA key pair with p_bits number of bits (sometimes referred to as L) for p, and q_bits number of bits (sometimes referred to as N) for q, using the random function rnd.

Valid combinations as per FIPS 186-3 are

   p_bits  q_bits
   1024    160
   2048    224 (rejected by some versions of Hogweed)
   2048    256
   3072    256
 

Returns
Array
Gmp.mpz 0

The value p, the modulo.

Gmp.mpz 1

The value q, the group order.

Gmp.mpz 2

The value g, the generator.

Gmp.mpz 3

The value y, the public value.

Gmp.mpz 4

The value x, the private value.


Method rsa_generate_keypair

array(Gmp.mpz) rsa_generate_keypair(int bits, int e, function(int(0..):string(8bit)) rnd)

Description

Generates an RSA key pair with a bits sized modulus (n), using the provided value for e and random function rnd.

Returns
Array
Gmp.mpz 0

The value n, the modulo.

Gmp.mpz 1

The value d, the private exponent.

Gmp.mpz 2

The value p, a prime.

Gmp.mpz 3

The value q, a prime.


Method rsa_unpad

int(0..) rsa_unpad(string(8bit) data, int(1..2) type)

Description

Unpads a message that has been padded according to RSAES-PKCS1-V1_5-ENCODE(message) in PKCS#1 v2.2, but without the null byte prefix. The padding method used on the original message must be provided in the type parameter. All content dependent processing is done in constant time for the same padding type and data length.

Returns

Returns the position in the string where the first non-padding character is, or 0.


Method version

string version()

Description

Returns the version of the Nettle library, e.g. "3.1". 0 is returned when runtime version is unknown.

Class Nettle.AEAD

Description

Represents information about an Authenticated Encryption with Associated Data (AEAD) algorithm, such as name, key size, digest size, and block size.


Inherit AEAD

inherit __builtin.Nettle.AEAD : AEAD


Method block_size

int(0..) block_size()

Returns

The block size of the AEAD algorithm.

Note

Note that AEAD algorithms often support automatic padding, so that the last block does not need to be complete.


Method digest_size

int(0..) digest_size()

Description

Returns the size of a MAC digest.


Method iv_size

int(0..) iv_size()

Description

Returns the size of the iv/nonce of the AEAD algorithm (if any).

Returns 0 (zero) if there is no configurable iv/nonce.


Method key_size

int(0..) key_size()

Returns

The recommended key size for the cipher.


Method name

string(8bit) name()

Returns

A human readable name for the algorithm.

Class Nettle.AEAD.State

Description

Base class for AEAD contexts.


Inherit State

inherit AEAD::State : State


Method block_size

int(0..) block_size()

Returns

The block size for this cipher.

Note

The default implementation just calls Cipher::block_size() in the parent.


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

Data must be an integral number of blocks, except for the last segment.

Returns

The encrypted or decrypted data.


Method digest

string(8bit) digest(int|void length)

Description

Generates a digest, and resets the AEAD contents.

Also updates the iv/nonce (if any).

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


Method iv_size

int(0..) iv_size()

Description

Returns the size of the iv/nonce of the AEAD algorithm (if any).

Returns 0 (zero) if there is no configurable iv/nonce.


Method key_size

int(0..) key_size()

Returns

The actual key size for this cipher.


Method make_key

string(8bit) make_key()

Description

Generate a key by calling random_string and initialize this object for encryption with that key.

Returns

The generated key. The key memory will be cleared before released.

See also

set_encrypt_key


Method name

string(8bit) name()

Returns

A human readable name for the algorithm.

Note

The default implementation just calls Cipher::name() in the parent.


Method set_decrypt_key

State set_decrypt_key(string(8bit) key)

Description

Initializes the object for decryption. The key memory will be cleared before released.

See also

set_encrypt_key, crypt


Method set_encrypt_key

State set_encrypt_key(string(8bit) key)

Description

Initializes the object for encryption. The key memory will be cleared before released.

See also

set_decrypt_key, crypt


Method set_iv

State set_iv(string(8bit) iv)

Description

Set the iv/nonce (if supported) for the AEAD.

Returns

Returns this in order to simplify chaining of function calls.


Method update

State update(string(8bit) data)

Description

Add some more associated data.

All associated data typically needs to be added before any data to actually encrypt.

Returns

Returns this in order to simplify chaining of function calls.

Class Nettle.AES

Description

Implementation of the AES cipher.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES.State

Description

State for AES encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.AES128

Description

Implementation of the AES128 cipher.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES128.State

Description

State for AES128 encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.AES128_CTR_DRBG

Description

Minimal implementation of NIST SP800-90Ar1 pseudo random number generator CTR_DRBG using AES-128. No personalization, nounces or additional data are supported.

See also

Random.AES128_CTR_DRBG


Variable reseed_interval

int(1..281474976710656) Nettle.AES128_CTR_DRBG.reseed_interval

Description

The number of times random_string can be called before a reseeding is forced. The number needs to be in the range of 1..1<<48.

See also

entropy_underflow


Variable reseed_interval

int(1..281474976710656) Nettle.AES128_CTR_DRBG.reseed_interval

Description

The number of times random_string can be called before a reseeding is forced. The number needs to be in the range of 1..1<<48.

See also

entropy_underflow


Method entropy_underflow

void entropy_underflow()

Description

Called when random_string has been called more than reseed_interval times.


Method random_string

string(8bit) random_string(int(0..) len)

Description

Generates len amount of pseudo random data. Does not allow for additional input data in the call.


Method reseed

void reseed(string(8bit) data)

Description

Updated the internal key with the provided additional entropy.

Class Nettle.AES192

Description

Implementation of the AES192 cipher.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES192.State

Description

State for AES192 encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.AES256

Description

Implementation of the AES256 cipher.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES256.State

Description

State for AES256 encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.ARCFOUR

Description

Implementation of the ARCFOUR cipher.


Inherit Cipher

inherit Cipher : Cipher

Class Nettle.ARCFOUR.State

Description

State for ARCFOUR encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.ARCTWO

Description

Implementation of the ARCTWO cipher.


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.ARCTWO.State

Description

State for PIKE_NAME encyption.


Inherit State

inherit Cipher::State : State


Method set_decrypt_key

State set_decrypt_key(string(8bit) key, void|int ekb)

Description

Initializes the object for decryption. The key memory will be cleared before released.

Parameter ekb

The effective number of bits in the key.

UNDEFINED

Derive from the key size (ie 8 * sizeof(key)).

0

Convenience alias for max (ie 1024).

(1..1024)

Reduce the effective key size to the specified number of bits.

See also

set_encrypt_key, crypt


Method set_encrypt_key

State set_encrypt_key(string(8bit) key, int|void ekb)

Description

Initializes the object for encryption. The key memory will be cleared before released.

Parameter ekb

The effective number of bits in the key.

UNDEFINED

Derive from the key size (ie 8 * sizeof(key)).

0

Convenience alias for max (ie 1024).

(1..1024)

Reduce the effective key size to the specified number of bits.

See also

set_decrypt_key, crypt

Class Nettle.BLOWFISH

Description

Implementation of the BLOWFISH cipher.


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.BLOWFISH.State

Description

State for BLOWFISH encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.BlockCipher

Description

Base class for all block ciphers.

Extends the BufferedCipher class with various operating modes.


Inherit BlockCipher

inherit __builtin.Nettle.BlockCipher : BlockCipher


Inherit BufferedCipher

inherit BufferedCipher : BufferedCipher

Module Nettle.BlockCipher.ABC

Description

Implementation of the Accumulated Block Chaining mode (ABC).

This is a mode of operation similar to IGE, but where the plaintext is mixed with both initialization vectors. It was suggested as a mode of operation for AES by Lars R. Knudsen.

See also

CBC, GCM, CFB, IGE


Inherit BufferedCipher

inherit BufferedCipher : BufferedCipher

Class Nettle.BlockCipher.ABC.State


Inherit State

inherit Cipher::State : State


Method block_size

int(1..) block_size()

Description

Returns the block size of the encapsulated cipher.


Method create

Nettle.BlockCipher.ABC.State Nettle.BlockCipher.ABC.State()

Description

Initialize the ABC state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.


Method iv_size

int(1..) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "ABC(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

Note

ABC semantically has two initialization vectors of size block_size(); x0 (previous plaintext) and y0 (previous ciphertext). They are here concatenated to a single initialization vector of double the block size.


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher.CBC

Description

Implementation of the Cipher Block Chaining mode (CBC).

Works as a wrapper for the cipher implemented by overloading the parent class (Cipher).

See also

Crypto.CBC, GCM


Inherit BufferedCipher

inherit BufferedCipher : BufferedCipher

Class Nettle.BlockCipher.CBC.State


Inherit State

inherit Cipher::State : State


Method block_size

int(1..) block_size()

Description

Returns the block size of the encapsulated cipher.


Method create

Nettle.BlockCipher.CBC.State Nettle.BlockCipher.CBC.State()

Description

Initialize the CBC state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.


Method iv_size

int(1..) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "CBC(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher.CFB

Description

Implementation of the Cipher Feed-Back mode (CFB).

See also

CBC, GCM


Inherit BufferedCipher

inherit BufferedCipher : BufferedCipher


Method `()

State res = Nettle.BlockCipher()()

Returns

Returns a new State object.


Method name

string(8bit) name()

Description

Returns the base cipher name appended with the string ".CFB".

Class Nettle.BlockCipher.CFB.State

Description

The state for a CFB instance.


Inherit State

inherit BufferedCipher::State : State


Variable obj

object Nettle.BlockCipher.CFB.State.obj

Note

Read only


Method block_size

int(1..) block_size()

Description

Returns the block size of the encapsulated cipher.


Method create

Nettle.BlockCipher.CFB.State Nettle.BlockCipher.CFB.State()

Description

Initialize the CFB state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

The length of data MUST be a multiple of the block size for all calls except the last.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

See also

update(), digest()


Method iv_size

int(1..) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "CFB(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_encrypt_key(), set_iv()


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_decrypt_key(), set_iv()


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

Note

iv must have the length reported by iv_size().

See also

set_encrypt_key(), set_decrypt_key().


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher.CTR

Description

Implementation of the Counter mode (CTR).

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

CBC, GCM, Buffer


Inherit Cipher

inherit __builtin.Nettle.Cipher : Cipher


Method `()

State res = Nettle.BlockCipher()()

Returns

Returns a new State object.


Method name

string(8bit) name()

Description

Returns the base cipher name appended with the string ".CTR".

Class Nettle.BlockCipher.CTR.State

Description

The state for a CTR instance.


Inherit State

inherit Cipher::State : State


Variable obj

object Nettle.BlockCipher.CTR.State.obj

Note

Read only


Method block_size

int(1..) block_size()

Description

Returns the block size of the encapsulated cipher.


Method create

Nettle.BlockCipher.CTR.State Nettle.BlockCipher.CTR.State()

Description

Initialize the CTR state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

The length of data MUST be a multiple of the block size for all calls except the last.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

See also

update(), digest()


Method iv_size

int(1..) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "CTR(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_encrypt_key(), set_iv()


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_decrypt_key(), set_iv()


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

Note

iv must have the length reported by iv_size().

See also

set_encrypt_key(), set_decrypt_key().


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher.IGE

Description

Implementation of the Infinite Garble Extension mode (IGE).

This is a mode of operation suggested in 1977 by C. Cambell.

See also

CBC, GCM, CFB


Inherit BufferedCipher

inherit BufferedCipher : BufferedCipher

Class Nettle.BlockCipher.IGE.State


Inherit State

inherit Cipher::State : State


Method block_size

int(1..) block_size()

Description

Returns the block size of the encapsulated cipher.


Method create

Nettle.BlockCipher.IGE.State Nettle.BlockCipher.IGE.State()

Description

Initialize the IGE state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.


Method iv_size

int(1..) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "IGE(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

Note

IGE semantically has two initialization vectors of size block_size(); x0 (previous plaintext) and y0 (previous ciphertext). They are here concatenated to a single initialization vector of double the block size.


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher.OFB

Description

Implementation of the Output Feed-Back mode (OFB).

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

CFB, CBC, CTR, GCM


Inherit BufferedCipher

inherit BufferedCipher : BufferedCipher


Method `()

State res = Nettle.BlockCipher()()

Returns

Returns a new State object.


Method name

string(8bit) name()

Description

Returns the base cipher name appended with the string ".OFB".

Class Nettle.BlockCipher.OFB.State

Description

The state for a OFB instance.


Inherit State

inherit BufferedCipher::State : State


Variable obj

object Nettle.BlockCipher.OFB.State.obj

Note

Read only


Method block_size

int(1..) block_size()

Description

Returns the block size of the encapsulated cipher.


Method create

Nettle.BlockCipher.OFB.State Nettle.BlockCipher.OFB.State()

Description

Initialize the OFB state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

The length of data MUST be a multiple of the block size for all calls except the last.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

See also

update(), digest()


Method iv_size

int(1..) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "OFB(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_encrypt_key(), set_iv()


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_decrypt_key(), set_iv()


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

Note

iv must have the length reported by iv_size().

See also

set_encrypt_key(), set_decrypt_key().


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher.PCBC

Description

Implementation of the Propagating Cipher Block Chaining mode (PCBC).

This mode is also known as plaintext cipher block chaining (from Kerberos v4).

Works as a wrapper for the cipher implemented by overloading the parent class (Cipher).

See also

CBC, GCM


Inherit CBC

inherit CBC : CBC

Class Nettle.BlockCipher.PCBC.State


Inherit State

inherit CBC::State : State


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

Neither the input nor the output data is automatically memory scrubbed, unless String.secure has been called on the data.


Method name

string(8bit) name()

Description

Returns the string "PCBC(x)" where x is the encapsulated algorithm.

Class Nettle.BlockCipher16

Description

This is the BlockCipher class extended with algorithms that require a block size of 16 bytes.

See also

Cipher, BlockCipher, BufferedCipher, GCM


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Module Nettle.BlockCipher16.CCM

Description

Implementation of the Counter with Cipher Block Chaining Message Authentication Code mode (CCM).

Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

This is a so-called authenticated encryption with associated data (AEAD) algorithm, and in addition to encryption also provides message digests.

The operation of CCM is specified in NIST Special Publication 800-38C.

Note

This mode of operation is not suited for streaming operation, as the sizes of the associated data and payload data need to be known for the CBC-MAC operation to start. Currently this means that the associated data and payload data are buffered until State()->digest() is called.

See also

CCM8, CBC, GCM, CTR


Inherit AEAD

inherit __builtin.Nettle.AEAD : AEAD


Inherit CTR

inherit BlockCipher::CTR : CTR


Method digest_size

int(4..16) digest_size()

Description

Default digest size.

Returns

Returns 16, but overloading via inherit is supported, and may return any even number in the range [4..16].

Note

Note that the digest length is folded into the digest, so it doesn't simply imply a truncation.


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".CCM" appended.

Class Nettle.BlockCipher16.CCM.State


Inherit State

inherit CTR::State : State


Method create

Nettle.BlockCipher16.CCM.State Nettle.BlockCipher16.CCM.State()


Method digest

string(8bit) digest(int(4..16)|void bytes)

Description

Returns the CBC-MAC digest of the specified size.

Parameter bytes

Size in bytes for the desired digest. Any even number in the range [4..16]. If not specified the value from calling digest_size() will be used.

Note

Note that the digest length is folded into the digest, so it doesn't simply imply a truncation.

See also

digest_size(), global::digest_size()


Method digest_size

int(4..16) digest_size()

Description

Default digest size.

This function is used by digest() to determine the digest size if no argument was given.

Returns

The default implementation returns the result from calling global::digest_size(), but overloading via inherit is supported, and may return any even number in the range [4..16].

Note

Note that the digest length is folded into the digest, so it doesn't simply imply a truncation.

See also

digest(), CCM::digest_size()

Module Nettle.BlockCipher16.CCM8

Description

Special case of CCM where the default digest size has been truncated to 8 bytes.

See also

CCM, CBC, GCM, CTR


Inherit CCM

inherit CCM : CCM


Method digest_size

int(4..16) digest_size()

Description

Default digest size.

Returns

Returns 8, but overloading via inherit is supported, and may return any even number in the range [4..16].


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".CCM8" appended.

Module Nettle.BlockCipher16.CMAC

Description

CMAC - Cipher-based Message Authentication Code

This module implements the CMAC algorithm from RFC 4493.


Inherit MAC

inherit __builtin.Nettle.MAC : MAC


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".CMAC" appended.

Class Nettle.BlockCipher16.CMAC.State


Inherit State

inherit Cipher::State : State


Method create

Nettle.BlockCipher16.CMAC.State Nettle.BlockCipher16.CMAC.State()


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher16.EAX

Description

Implementation of the EAX mode.

Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

This is a so-called authenticated encryption with associated data (AEAD) algorithm, and in addition to encryption also provides message digests.

Note

This mode of operation was specified as a reaction to the limitiations of the BlockCipher16.CCM mode.

Note

Note that this module is not available in all versions of Nettle.

See also

CBC, CTR, BlockCipher16.CCM, BlockCipher16.GCM


Inherit AEAD

inherit __builtin.Nettle.AEAD : AEAD


Method digest_size

int(1..) digest_size()

Description

Default digest size.

Returns

Returns BlockCipher::block_size(), but overloading via inherit is supported, and may return any positive number <= BlockCipher::block_size().


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".EAX" appended.

Class Nettle.BlockCipher16.EAX.State


Inherit State

inherit AEAD::State : State


Method block_size

int(16) block_size()

Description

Returns the block size of the encapsulated cipher, which is always 16 for EAX.


Method create

Nettle.BlockCipher16.EAX.State Nettle.BlockCipher16.EAX.State()


Method digest

string(8bit) digest(int(1..16)|void bytes)

Description

Returns the OMAC digest of the specified size.

Parameter bytes

Size in bytes for the desired digest. Any number in the range [1..16]. If not specified the value from calling digest_size() will be used.

See also

digest_size(), global::digest_size()


Method digest_size

int(1..16) digest_size()

Description

Default digest size.

This function is used by digest() to determine the digest size if no argument was given.

Returns

The default implementation returns the result from calling EAX::digest_size(), but overloading via inherit is supported, and may return any even number in the range [1..16].

See also

digest(), EAX::digest_size()


Method iv_size

int(16) iv_size()

Description

Returns the recommended size for the initialization vector (ie 16).

Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "x.EAX" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_encrypt_key(), set_iv()


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_decrypt_key(), set_iv()


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher16.GCM

Description

Implementation of the Galois Counter Mode (GCM).

Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

This is a so-called authenticated encryption with associated data (AEAD) algorithm, which in addition to encryption also provides message digests.

The operation of GCM is specified in NIST Special Publication 800-38D.

Typically accessed as Crypto.AES.GCM or Crypto.Camellia.GCM

Note

Note that this module is not available in all versions of Nettle.

See also

CBC


Inherit AEAD

inherit __builtin.Nettle.AEAD : AEAD


Method block_size

int(16) block_size()

Description

Returns the block size of the encapsulated cipher, which is always 16 for GCM.


Method digest_size

int(16) digest_size()

Description

Returns the size of the generated digest, which is always 16 for GCM.


Method iv_size

int(12) iv_size()

Description

Returns the recommended size for the initialization vector (ie 12).

Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".GCM" appended.

Class Nettle.BlockCipher16.GCM.State

Description

The state for a GCM instance.


Inherit State

inherit AEAD::State : State


Method block_size

int(16) block_size()

Description

Returns the block size of the encapsulated cipher, which is always 16 for GCM.


Method create

Nettle.BlockCipher16.GCM.State Nettle.BlockCipher16.GCM.State()

Description

Initialize the GCM state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

The length of data MUST be a multiple of the block size (ie 16) for all calls except the last.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

See also

update(), digest()


Method digest

string(8bit) digest()

Description

Generate a message digest for the data accumulated so far.

Note

set_iv() needs to be called to start the next message.

See also

update(), digest()


Method digest_size

int(16) digest_size()

Description

Returns the size of the generated digest, which is always 16 for GCM.


Method iv_size

int(12) iv_size()

Description

Returns the recommended size for the initialization vector (ie 12).

Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "x.GCM" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_encrypt_key(), set_iv()


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_decrypt_key(), set_iv()


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

Also resets all state needed to start a new message.

Note

For ivs of length other than 12, an encryption or decryption key must have been set first.

See also

set_encrypt_key(), set_decrypt_key().


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.


Method update

void update(string(8bit) public_data)

Description

Add public_data to be authenticated.

The length of public_data MUST be a multiple of the block size (ie 16) for all calls except the last.

All calls of update() need to be performed before any calls of crypt().

Module Nettle.BlockCipher16.KW

Description

The AES Key Wrapping algorithm from RFC 3394.

This algorithm is intended to be used to encode encryption keys which are a multiple of 8 bytes and at least 16 bytes long.

Note

RFC 6931 section 2.6.3 indicates that this algorithm is also appropriate for Camellia.


Inherit AE

inherit __builtin.Nettle.AE : AE


Constant DEFAULT_IV

constant Nettle.BlockCipher16.KW.DEFAULT_IV

Description

This is the default initialization vector specified by RFC 3394 section 2.2.3.1.


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".KW" appended.

Class Nettle.BlockCipher16.KW.State


Inherit State

inherit Cipher::State : State


Method block_size

int(8) block_size()

Description

Returns the block size for this AEAD mode.


Method create

Nettle.BlockCipher16.KW.State Nettle.BlockCipher16.KW.State()

Description

Initialize the KW state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt/decrypt data and return the result. data must be an integral number of blocks. It must also be at least two blocks long.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.


Method digest

string(8bit) digest()

Description

Returns the data integrity value.

When decoding this value should be compared to the original IV used when encoding.

When encoding the convention is to prepend this value to the encoded data returned by crypt().

Note

The above convention is the reverse of the convention for most AEADs (where the digest typically comes last).

See also

set_iv(), DEFAULT_IV


Method iv_size

int(8) iv_size()

Description

Returns the size for the initialization vector


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "KW(x)" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv. The iv memory will be cleared before released.

The default iv if this function hasn't been called is "\246\246\246\246\246\246\246\246" (cf RFC 3394 section 2.2.3.1.

See also

digest(), DEFAULT_IV


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Module Nettle.BlockCipher16.OCB

Description

Implementation of the OCB mode (RFC 7253).

Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

OCB was initially an acronym for Offset CodeBook.

This is a so-called authenticated encryption with associated data (AEAD) algorithm, and in addition to encryption also provides message digests.

Note

This module requires Nettle 3.9 or later.

See also

CBC, CTR, BlockCipher16.CCM, BlockCipher16.GCM


Inherit AEAD

inherit __builtin.Nettle.AEAD : AEAD


Method digest_size

int(16) digest_size()

Description

Default digest size (16).


Method name

string(8bit) name()

Description

Returns the name of the base cipher with ".OCB" appended.

Class Nettle.BlockCipher16.OCB.State


Inherit State

inherit AEAD::State : State


Method block_size

int(16) block_size()

Description

Returns the block size of the encapsulated cipher, which is always 16 for OCB.


Method create

Nettle.BlockCipher16.OCB.State Nettle.BlockCipher16.OCB.State()


Method digest

string(8bit) digest()

Description

Returns the OCB authentication tag.

Note

The size of the digest is specified in the call to set_iv().

See also

set_iv(), digest_size(), global::digest_size()


Method digest_size

int(1..16) digest_size()

Description

Digest size as set by set_iv().

See also

digest(), OCB::digest_size()


Method iv_size

int(15) iv_size()

Description

Returns the recommended size for the initialization vector (ie 15).

Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.


Method key_size

int(1..) key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string(8bit) name()

Description

Returns the string "x.OCB" where x is the encapsulated algorithm.


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, int|void flags)

Description

Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_encrypt_key(), set_iv()


Method set_encrypt_key

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

Description

Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

Note

Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

See also

set_decrypt_key(), set_iv()


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.

Class Nettle.BufferedCipher

Description

Extends the Cipher class with the Buffer meta cipher. This is in turn inherited by the BlockCipher class, which is the base class for all block ciphers.


Inherit Cipher

inherit Cipher : Cipher

Module Nettle.BufferedCipher.Buffer

Description

Acts as a buffer so that data can be fed to the cipher in blocks that don't correspond to cipher block sizes.

Example

class Encrypter { protected Crypto.Cipher buffer;

void create(string key) { buffer = Crypto.AES.CBC.Buffer(); buffer->set_encrypt_key(key); }

string feed(string data) { return buffer->crypt(data); }

string drain() { return buffer->pad(Crypto.PAD_PKCS7); } }

See also

BlockCipher.CBC, BlockCipher16.GCM


Inherit Cipher

inherit __builtin.Nettle.Cipher : Cipher


Method `()

State res = Nettle.BufferedCipher()()

Returns

Returns a new State object.

Class Nettle.BufferedCipher.Buffer.State

Description

Acts as a buffer so that data can be fed to the cipher in blocks that don't correspond to cipher block sizes.

Example

class Encrypter { protected Crypto.Cipher buffer;

void create(string key) { buffer = Crypto.AES.CBC.Buffer(); buffer->set_encrypt_key(key); }

string feed(string data) { return buffer->crypt(data); }

string drain() { return buffer->pad(Crypto.PAD_PKCS7); } }

See also

BlockCipher.CBC, BlockCipher16.GCM


Method block_size

int(1..) block_size()

Description

Get the block size of the contained block crypto.


Method create

Nettle.BufferedCipher.Buffer.State Nettle.BufferedCipher.Buffer.State()

Description

Initialize the buffer with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.


Method crypt

string(8bit) crypt(string(8bit) data)

Description

Encrypt or decrypt some data.

Adds data to be en/decrypted to the buffer. If there's enough data to en/decrypt a block, that will be done, and the result returned. Any unprocessed data will be left in the buffer.

Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.


Method iv_size

int(0..) iv_size()

Description

Get the iv size of the contained block crypto.


Method key_size

int(1..) key_size()

Description

Get the key size of the contained block crypto.


Method name

string(8bit) name()

Description

Returns the name of the wrapped cipher with ".Buffer" appended.


Method pad

string(8bit) pad(void|int method)

Description

Pad and encrypt any data left in the buffer. The output data is not automatically memory scrubbed, unless String.secure is called on the data.

Parameter method

The type of padding to apply to the buffer.

Crypto.PAD_ISO_10126

Pads according to ISO 10126, which means filling all extra space with random data and putting the size of the non-payload data last.

Crypto.PAD_TLS

Pads according to RFC 5246 section 6.2.3.2, meaning that all extra space is filled with the size of the padding. Note that this size has an off by one difference to the other schemas, so 0 means 1 byte of padding.

Crypto.PAD_SSL
Crypto.PAD_ANSI_X923

Pads according to ANSI X.923, which means filling all extra space with zero and putting the size of the non-payload data last.

Crypto.PAD_PKCS7

Pads according to PKCS7 / RFC 3852, which means filling all extra space with the size of the extra space.

Crypto.PAD_ZERO

Fills the extra space with null bytes. To correctly remove the padding the clear text data must not end with a null byte. In that case the data would have to be manually padded/unpadded before/after calling crypt().

Defaults to Crypto.PAD_SSL for compatibility reasons.

See also

unpad()


Method set_decrypt_key

this_program set_decrypt_key(string(8bit) key, void|int flags)

Description

Set the decryption key. The key memory will be cleared before released.

Note

As a side-effect any buffered data will be cleared.


Method set_encrypt_key

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

Description

Set the encryption key. The key memory will be cleared before released.

Note

As a side-effect any buffered data will be cleared.


Method set_iv

this_program set_iv(string(8bit) iv)

Description

Set the initialization vector to iv.


Method substate_factory

Cipher::State substate_factory()

Description

Returns the Cipher::State object that this object is to operate on.

Defaults to creating the State for the cipher implemented in the parent module.


Method unpad

string(8bit) unpad(string(8bit) data, void|int method)

Description

Decrypt and unpad a block of data. Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

This performs the reverse operation of pad(). The padding will be verified to be correct, if possible. If not, zero is returned.

Parameter method

The type of padding that was applied to the original buffer.

Crypto.PAD_SSL
Crypto.PAD_TLS
Crypto.PAD_ISO_10126
Crypto.PAD_ANSI_X923
Crypto.PAD_PKCS7
Crypto.PAD_ZERO

Defaults to Crypto.PAD_SSL for compatibility reasons.

See also

pad()

Class Nettle.CAMELLIA

Description

Implementation of the CAMELLIA cipher.

Note

Requires Nettle 2.1 or later.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.CAMELLIA.State

Description

State for CAMELLIA encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.CAST128

Description

Implementation of the CAST128 cipher.


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.CAST128.State

Description

State for CAST128 encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.CHACHA

Description

Implementation of the CHACHA stream cipher.

Note

Note that this class is not available in all versions of Nettle.


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.CHACHA.State

Description

State for CHACHA encyption.


Inherit State

inherit Cipher::State : State


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

Usually an integral number of blocks, except for the last segement in a run. The decoder must get partial blocks at the same places as the encoder, otherwise they will get out of sync.

Returns

The encrypted or decrypted data.


Method set_iv

object set_iv(string(8bit) iv)

Description

Set the initialization vector (aka nonce) and reset the block counter to zero.

Parameter iv

An 8-byte long string which is only to be used once for every key.

Note

This function MUST be called in addition to set_encrypt_key() or set_decrypt_key().

Note

The same iv should NEVER be reused with the same key!

Class Nettle.CHACHA_POLY1305

Description

Implementation of the CHACHA_POLY1305 AEAD algorithm.


Inherit AEAD

inherit AEAD : AEAD

Class Nettle.CHACHA_POLY1305.State

Description

State for CHACHA_POLY1305 encyption.


Inherit State

inherit AEAD::State : State

Class Nettle.Cipher

Description

Represents information about a cipher algorithm, such as name, key size, and block size.


Inherit Cipher

inherit __builtin.Nettle.Cipher : Cipher


Method block_size

int(1..) block_size()

Returns

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


Method key_size

int(1..) key_size()

Returns

The recommended key size for the cipher.


Method name

string(8bit) name()

Returns

A human readable name for the algorithm.

Class Nettle.Cipher.State

Description

Base class for cipher contexts.


Inherit State

inherit Cipher::State : State


Method block_size

int(1..) block_size()

Returns

The block size for this cipher.

Note

The default implementation just calls Cipher::block_size() in the parent.


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(1..) key_size()

Returns

The actual key size for this cipher.


Method make_key

string(8bit) make_key()

Description

Generate a key by calling random_string and initialize this object for encryption with that key.

Returns

The generated key. The key memory will be cleared before being released.

See also

set_encrypt_key


Method name

string(8bit) name()

Returns

A human readable name for the algorithm.

Note

The default implementation just calls Cipher::name() in the parent.


Method set_decrypt_key

State set_decrypt_key(string(8bit) key, void|int flags)

Description

Initializes the object for decryption. The key memory will be cleared before released.

See also

set_encrypt_key, crypt


Method set_encrypt_key

State set_encrypt_key(string(8bit) key, void|int flags)

Description

Initializes the object for encryption. The key memory will be cleared before released.

See also

set_decrypt_key, crypt

Class Nettle.Curve25519

Description

Elliptic Curve Definition for the curve y^2 = x^3 + 486662 x^2 + x (mod 2^255 - 19).

This curve is standardized in RFC 7748.

Note

The API for this curve differs somewhat from the API used by the other Curves.

See also

Curve, Curve448, RFC 7748


Inherit ECC_Curve

inherit __builtin.Nettle.ECC_Curve : ECC_Curve


Method `*

Point res = Nettle.Curve25519() * scalar

Description

Multiply the curve by a scalar.

This can be used to get the public key from a private key.

Returns

Returns a new point on the curve.


Method jose_name

string(7bit) jose_name()

Description

Returns the name of the curve according to JOSE (RFC 8037 section 3.1).

Returns

Returns the string "X25519".

See also

name()


Method name

string(7bit) name()

Description

Returns the name of the curve.


Method new_scalar

Gmp.mpz new_scalar(function(int(0..):string(8bit)) rnd)

Parameter rnd

Randomness function to use as source.

Returns

Returns a random scalar suitable to use as an ECDSA private key or as an ECDH exponent.


Method point_mul

string(8bit) point_mul(string(8bit) x, string(8bit) scalar)

Description

Multiply a point on the curve by a scalar.

A typical use is for Elliptic Curve Diffie Hellman (ECDH) key exchange.

Returns

Returns the new point on the curve.


Method size

int size()

Returns

Returns the size in bits for a single coordinate on the curve.

Class Nettle.Curve25519.EdDSA

Description

Edwards Curve Digital Signing Algorithm


Inherit Point

inherit Point : Point

Description

This point represents the public key.


Inherit Sign

inherit __builtin.Nettle.Sign : Sign


Method generate_key

void generate_key()

Description

Generate a new set of private and public keys on the current curve.


Method get_curve

Curve25519 get_curve()

Description

Get the elliptic curve that is in use.


Method get_private_key

string(8bit) get_private_key()

Description

Get the private key.


Method get_x

string(8bit) get_x()

Description

Get the x coordinate of the public key.


Method jose_name

string(7bit) jose_name()

Description

Returns the string "Ed25519".


Method name

string(7bit) name()

Description

Returns the string "EdDSA".


Method raw_sign

string(8bit) raw_sign(string(8bit) message)

Description

Sign the message.


Method raw_verify

bool raw_verify(string(8bit) message, string(8bit) signature)

Description

Verify the signature against the message.


Method set_private_key

void set_private_key(string(8bit) k)

Description

Set the private key (and corresponding public key).

Note

Throws errors if the key isn't valid for the curve.


Method set_public_key

void set_public_key(string(8bit) x)

Description

Change to the selected point on the curve as public key.

Note

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


Method set_random

void set_random(function(int(0..):string(8bit)) r)

Description

Set the random function, used to generate keys and parameters, to the function r.

Class Nettle.Curve25519.Point

Description

A point on an elliptic curve.


Inherit Point

inherit ECC_Curve::Point : Point

Class Nettle.Curve448

Description

Elliptic Curve Definition for the curve y^2 = x^3 + 156326 x^2 + x (mod 2^448 - 2^224 - 1).

This curve is standardized in RFC 7748.

Note

The API for this curve differs somewhat from the API used by the other Curves.

See also

Curve, Curve25519, RFC 7748


Inherit ECC_Curve

inherit __builtin.Nettle.ECC_Curve : ECC_Curve


Method `*

Point res = Nettle.Curve448() * scalar

Description

Multiply the curve by a scalar.

This can be used to get the public key from a private key.

Returns

Returns a new point on the curve.


Method jose_name

string(7bit) jose_name()

Description

Returns the name of the curve according to JOSE (RFC 8037 section 3.1).

Returns

Returns the string "X448".

See also

name()


Method name

string(7bit) name()

Description

Returns the name of the curve.


Method new_scalar

Gmp.mpz new_scalar(function(int(0..):string(8bit)) rnd)

Parameter rnd

Randomness function to use as source.

Returns

Returns a random scalar suitable to use as an ECDSA private key or as an ECDH exponent.


Method point_mul

string(8bit) point_mul(string(8bit) x, string(8bit) scalar)

Description

Multiply a point on the curve by a scalar.

A typical use is for Elliptic Curve Diffie Hellman (ECDH) key exchange.

Returns

Returns the new point on the curve.


Method size

int size()

Returns

Returns the size in bits for a single coordinate on the curve.

Class Nettle.Curve448.EdDSA

Description

Edwards Curve Digital Signing Algorithm


Inherit Point

inherit Point : Point

Description

This point represents the public key.


Inherit Sign

inherit __builtin.Nettle.Sign : Sign


Method generate_key

void generate_key()

Description

Generate a new set of private and public keys on the current curve.


Method get_curve

Curve448 get_curve()

Description

Get the elliptic curve that is in use.


Method get_private_key

string(8bit) get_private_key()

Description

Get the private key.


Method get_x

string(8bit) get_x()

Description

Get the x coordinate of the public key.


Method jose_name

string(7bit) jose_name()

Description

Returns the string "Ed448".


Method name

string(7bit) name()

Description

Returns the string "EdDSA".


Method raw_sign

string(8bit) raw_sign(string(8bit) message)

Description

Sign the message.


Method raw_verify

bool raw_verify(string(8bit) message, string(8bit) signature)

Description

Verify the signature against the message.


Method set_private_key

void set_private_key(string(8bit) k)

Description

Set the private key (and corresponding public key).

Note

Throws errors if the key isn't valid for the curve.


Method set_public_key

void set_public_key(string(8bit) x)

Description

Change to the selected point on the curve as public key.

Note

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


Method set_random

void set_random(function(int(0..):string(8bit)) r)

Description

Set the random function, used to generate keys and parameters, to the function r.

Class Nettle.Curve448.Point

Description

A point on an elliptic curve.


Inherit Point

inherit ECC_Curve::Point : Point

Class Nettle.DES

Description

Implementation of the Data Encryption Standard (DES) crypto algorithm.


Inherit BlockCipher

inherit BlockCipher : BlockCipher


Method fix_parity

string(8bit) fix_parity(string(8bit) key)

Description

Sets the last bit in every byte in key to reflect the parity. If a seven byte key is used, it will be expanded into eight bytes. If a key longer than eight characters is used, it will be truncated to eight characters.

Class Nettle.DES.State

Description

State for DES encyption


Inherit State

inherit Cipher::State : State


Method fix_parity

string(8bit) fix_parity(string(8bit) key)

Description

Sets the last bit in every byte in key to reflect the parity. If a seven byte key is used, it will be expanded into eight bytes. If a key longer than eight characters is used, it will be truncated to eight characters.

Class Nettle.DES3

Description

Implementation of the DES3 cipher algorithm.


Inherit BlockCipher

inherit BlockCipher : BlockCipher


Method fix_parity

string(8bit) fix_parity(string(8bit) key)

Description

Sets the last bit in every byte in key to reflect the parity. If a 21 byte key is used, it will be expanded into 24 bytes. If a key longer than 24 characters is used, it will be truncated to 24 characters.

Class Nettle.DES3.State

Description

State for DES3 encyption


Inherit State

inherit Cipher::State : State

Class Nettle.DH_Params

Description

Diffie-Hellman Parameters.


Variable g

Gmp.mpz Nettle.DH_Params.g

Description

Generator.


Variable p

Gmp.mpz Nettle.DH_Params.p

Description

Prime.


Variable q

Gmp.mpz Nettle.DH_Params.q

Description

Order.


Method generate

void generate(int p_bits, int q_bits, function(int(0..):string(8bit)) rnd)

Description

Generate a new set of Diffie-Hellman parameters.

Note

Throws errors for unsupported parameters.

Note

This function is not available in all installations of Pike.


Method generate_keypair

array(Gmp.mpz) generate_keypair(function(int(0..):string(8bit)) rnd)

Description

Generate a Diffie-Hellman key pair.

Returns

Returns the following array:

Array
Gmp.mpz 0

The generated public key.

Gmp.mpz 1

The corresponding private key.

Class Nettle.ECC_Curve

Description

Elliptic Curve Definition


Inherit ECC_Curve

inherit __builtin.Nettle.ECC_Curve : ECC_Curve


Inherit ECDSA

inherit ECDSA : ECDSA

Description

This point represents the public key.


Method `*

Point res = Nettle.ECC_Curve() * scalar

Description

Multiply the curve by a scalar.

This can be used to get the public key from a private key.

Returns

Returns a new Point on the curve.


Method `==

bool res = Nettle.ECC_Curve() == x

Returns

Returns 1 if x is the same Curve, and 0 (zero) otherwise.


Method create

Nettle.ECC_Curve Nettle.ECC_Curve(int(0..) curve)

Description

Initialize the curve.

Parameter curve

The curve type the object should be initialized as.

Nettle.SECP192R1
Nettle.SECP224R1
Nettle.SECP256R1
Nettle.SECP384R1
Nettle.SECP521R1
Nettle.GOST_GC256B
Nettle.GOST_GC512A

Method jose_name

string(7bit) jose_name()

Description

Returns the name of the curve according to JOSE (RFC 7518 section 6.2.1.1).

Returns

Returns the JOSE name for supported curves, and UNDEFINED otherwise.

See also

name()


Method name

string(7bit) name()

Description

Returns the name of the curve.

See also

jose_name()


Method new_scalar

Gmp.mpz new_scalar(function(int(0..):string(8bit)) rnd)

Parameter rnd

Randomness function to use as source.

Returns

Returns a random scalar suitable to use as an ECDSA private key or as an ECDH secret factor.


Method point_mul

Point point_mul(Gmp.mpz|int x, Gmp.mpz|int y, Gmp.mpz|int scalar)

Description

Multiply a point on the curve by a scalar.

A typical use is for Elliptic Curve Diffie Hellman (ECDH) key exchange.

This is equivalent to (Point(x, y) * scalar).

Returns

Returns the new Point on the curve.

Throws

Throws an error if the point (x, y) isn't on the curve.


Method raw_sign

array(Gmp.mpz) raw_sign(string(8bit) digest)

Description

Sign the message digest digest. Returns the signature as two Gmp.mpz objects.


Method raw_verify

bool raw_verify(string(8bit) digest, Gmp.mpz r, Gmp.mpz s)

Description

Verify the signature r, s against the message digest digest.


Method size

int size()

Returns

Returns the size in bits for a single coordinate on the curve.

Class Nettle.ECC_Curve.ECDSA

Description

Elliptic Curve Digital Signing Algorithm


Inherit Point

inherit Point : Point

Description

This point represents the public key.


Inherit Sign

inherit __builtin.Nettle.Sign : Sign


Method generate_key

void generate_key()

Description

Generate a new set of private and public keys on the current curve.


Method get_curve

ECC_Curve get_curve()

Description

Get the elliptic curve that is in use.


Method get_private_key

Gmp.mpz get_private_key()

Description

Get the private key.


Method get_x

Gmp.mpz get_x()

Description

Get the x coordinate of the public key.

See also

get_y()


Method get_y

Gmp.mpz get_y()

Description

Get the y coordinate of the public key.

See also

get_x()


Method name

string(7bit) name()

Description

Returns the string "ECDSA" followed by the parenthesized name of the curve.


Method raw_sign

array(Gmp.mpz) raw_sign(string(8bit) digest)

Description

Sign the message digest digest. Returns the signature as two Gmp.mpz objects.


Method raw_verify

bool raw_verify(string(8bit) digest, Gmp.mpz r, Gmp.mpz s)

Description

Verify the signature r, s against the message digest digest.


Method set_private_key

void set_private_key(Gmp.mpz|int k)

Description

Set the private key (and corresponding public key).

Note

Throws errors if the key isn't valid for the curve.


Method set_public_key

void set_public_key(Gmp.mpz|int x, Gmp.mpz|int y)

Description

Change to the selected point on the curve as public key.

Note

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


Method set_random

void set_random(function(int(0..):string(8bit)) r)

Description

Set the random function, used to generate keys and parameters, to the function r.

Class Nettle.ECC_Curve.Point

Description

A point on an elliptic curve.


Inherit Point

inherit ECC_Curve::Point : Point


Method _equal

bool equal(Nettle.ECC_Curve.Point from, mixed x)

Returns

Returns 1 if x is a Point on the same Curve and has the same coordinates, and otherwise returns 0 (zero).


Method `*

Point res = Nettle.ECC_Curve.Point() * scalar

Description

Multiply the point on the curve by a scalar.

A typical use is for Elliptic Curve Diffie Hellman (ECDH) key exchange.

Returns

Returns the new point on the curve.


Method get_curve

ECC_Curve get_curve()

Description

Get the elliptic curve that is in use.


Method get_x

Gmp.mpz get_x()

Description

Get the x coordinate of the point.

See also

get_y()


Method get_y

Gmp.mpz get_y()

Description

Get the y coordinate of the point.

See also

get_x()


Method name

string(7bit) name()

Description

Returns the string "Point" followed by the parenthesized name of the curve.


Method set

void set(Gmp.mpz|int x, Gmp.mpz|int y)

Description

Change to the selected point on the curve.

Note

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

Class Nettle.Fortuna

Description

Implements the Fortuna PRNG generator, designed by Niels Ferguson and Bruce Schneier and described in Practical Cryptography. Web published exerpt at https://www.schneier.com:443/fortuna.pdf

This implementation uses AES256 to generate output and SHA256 to generate keys.

To use this class an entropy accumulator needs to be implemented and supply the reseed() method with new entopy.


Method random_string

string(8bit) random_string(int(0..) len)

Description

Generates len amount of pseudo random data. In contrast with the Fortuna PseudoRandomData function, which only allows 2^20 bytes of random data per call, the necessary rekey operations are here performed internally, so no such restrictions apply.


Method reseed

void reseed(string(8bit) data)

Description

Updated the internal key with the provided additional entropy.

Class Nettle.GOST94

Description

Implementation of the GOST94 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for GOST94.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.GOST94.State

Description

State for GOST94 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), GOST94.shake()

Module Nettle.GOST94.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the GOST94 hash algorithm.

See also

Crypto.HMAC

Class Nettle.GOST94.HMAC.GOST94

Description

The HMAC hash state.


Method create

Nettle.GOST94.HMAC.GOST94 Nettle.GOST94.HMAC.GOST94(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.GOST94CP

Description

Implementation of the GOST94CP hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for GOST94CP.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.GOST94CP.State

Description

State for GOST94CP hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), GOST94CP.shake()

Module Nettle.GOST94CP.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the GOST94CP hash algorithm.

See also

Crypto.HMAC

Class Nettle.GOST94CP.HMAC.GOST94CP

Description

The HMAC hash state.


Method create

Nettle.GOST94CP.HMAC.GOST94CP Nettle.GOST94CP.HMAC.GOST94CP(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.Hash

Description

Represents information about a hash algorithm, such as name, digest size, and internal block size.


Inherit Hash

inherit __builtin.Nettle.Hash : Hash


Method balloon

string(7bit) balloon(string(8bit) password, string(8bit) salt, int(1..) s_cost, int(1..) rounds)

Description

Password hashing function in crypt_hash()-style.

Implements the algorithm described in https://eprint.iacr.org/2016/027.pdf.

Parameter password

Password to hash.

Parameter salt

Salt for the password.

Parameter s_cost

Memory cost.

Parameter rounds

Number of rounds (also known as t_cost).

Returns

Returns the balloon hash of the password.

Note

The password memory will be cleared before released.

Note

This function is only available with Nettle 3.9 and later.

See also

crypt_hash()


Method block_size

int(1..) block_size()

Description

Returns the internal block size of the hash algorithm.


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

The password memory will be cleared before released.

Rounds will never be set to less than 1000. If rounds is 0 it will be set to 5000.

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

The password memory will be cleared before released.

Rounds will never be set to less than 1000. If rounds is 0 it will be set to 5000.

Note

Do not use unless you know what you are doing!

See also

crypt_md5(), crypt_hash()


Method digest_size

int(0..) digest_size()

Description

Returns the size of a hash digest.


Method hash

string(8bit) hash(string(8bit) data)

Description

Works as a (faster) shortcut for State()->update(data)->digest(), where State is the hash state class corresponding to this Hash.

See also

State()->update() and State()->digest().


Method hash

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

Description

Works as a (faster) shortcut for e.g. State()->update(Stdio.read_file(file))->digest(), where State is the hash state class corresponding to this Hash.

Parameter bytes

The number of bytes of the file object file that should be hashed. Zero and negative numbers are ignored and the whole file is hashed. Support for negative numbers is deprecated.

See also

Stdio.File, State()->update() and State()->digest().


Method name

string(8bit) name()

Description

Returns a human readable name for the algorithm.

Class Nettle.Hash.State

Description

Base class for hashing contexts.


Inherit State

inherit Hash::State : State


Method digest

string(8bit) digest(int(0..)|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 update

State update(string(8bit) data)

Description

Hashes more data.

Returns

Returns this in order to simplify chaining of function calls.

Class Nettle.IDEA

Description

Implementation of the IDEA cipher.


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.IDEA.State

Description

State for IDEA encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.MAC

Description

Represents information about a MAC algorithm, such as name, key size, digest size, and internal block size.


Inherit MAC

inherit __builtin.Nettle.MAC : MAC


Method block_size

int(0..) block_size()

Description

Returns the internal block size of the MAC algorithm.


Method digest_size

int(0..) digest_size()

Description

Returns the size of a MAC digest.


Method iv_size

int(0..) iv_size()

Description

Returns the size of the iv/nonce of the MAC algorithm (if any).

Returns 0 (zero) if there is no configurable iv/nonce.


Method key_size

int(0..) key_size()

Description

Returns the recommended size for the secret key for the MAC algorithm.


Method name

string(8bit) name()

Description

Returns a human readable name for the algorithm.

Class Nettle.MAC.State

Description

Base class for MAC contexts.


Inherit State

inherit MAC::State : State


Method `()

string(8bit) res = Nettle.MAC.State()()

Description

Acts as the combination of update() followed by digest().

Note

Also updates the iv/nonce (if any).


Method create

Nettle.MAC.State Nettle.MAC.State(string(8bit) key)

Description

Initialize the MAC with a password.

It also resets any iv/nonce to it's default.


Method digest

string(8bit) digest(int|void length)

Description

Generates a digest, and resets the MAC contents.

Also updates the iv/nonce (if any).

Parameter length

If the length argument is provided, the digest is truncated to the given length.

Returns

The digest.


Method set_iv

State set_iv(string(8bit) iv)

Description

Set the iv/nonce (if supported) for the MAC.

Returns

Returns this in order to simplify chaining of function calls.


Method update

State update(string(8bit) data)

Description

Hashes more data.

Returns

Returns this in order to simplify chaining of function calls.

Class Nettle.MD2

Description

Implementation of the MD2 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for MD2.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.MD2.State

Description

State for MD2 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), MD2.shake()

Module Nettle.MD2.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the MD2 hash algorithm.

See also

Crypto.HMAC

Class Nettle.MD2.HMAC.MD2

Description

The HMAC hash state.


Method create

Nettle.MD2.HMAC.MD2 Nettle.MD2.HMAC.MD2(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.MD4

Description

Implementation of the MD4 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for MD4.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.MD4.State

Description

State for MD4 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), MD4.shake()

Module Nettle.MD4.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the MD4 hash algorithm.

See also

Crypto.HMAC

Class Nettle.MD4.HMAC.MD4

Description

The HMAC hash state.


Method create

Nettle.MD4.HMAC.MD4 Nettle.MD4.HMAC.MD4(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.MD5

Description

Implementation of the MD5 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for MD5.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.MD5.State

Description

State for MD5 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), MD5.shake()

Module Nettle.MD5.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the MD5 hash algorithm.

See also

Crypto.HMAC

Class Nettle.MD5.HMAC.MD5

Description

The HMAC hash state.


Method create

Nettle.MD5.HMAC.MD5 Nettle.MD5.HMAC.MD5(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.POLY1305_AES

Description

Implementation of the POLY1305_AES MAC algorithm.


Inherit MAC

inherit MAC : MAC

Class Nettle.POLY1305_AES.State

Description

State for POLY1305_AES macing.


Inherit State

inherit MAC::State : State

Class Nettle.RIPEMD160

Description

Implementation of the RIPEMD160 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for RIPEMD160.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.RIPEMD160.State

Description

State for RIPEMD160 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), RIPEMD160.shake()

Module Nettle.RIPEMD160.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the RIPEMD160 hash algorithm.

See also

Crypto.HMAC

Class Nettle.RIPEMD160.HMAC.RIPEMD160

Description

The HMAC hash state.


Method create

Nettle.RIPEMD160.HMAC.RIPEMD160 Nettle.RIPEMD160.HMAC.RIPEMD160(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SALSA20

Description

Implementation of the SALSA20 cipher.


Inherit BlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.SALSA20.State

Description

State for SALSA20 encyption.


Inherit State

inherit Cipher::State : State


Method set_iv

object set_iv(string(8bit) iv)

Description

Set the initialization vector (aka nonce) and reset the block counter to zero.

Parameter iv

An 8-byte long string which is only to be used once for every key.

Note

This function MUST be called in addition to set_encrypt_key() or set_decrypt_key().

Note

The same iv should NEVER be reused with the same key!

Class Nettle.SALSA20R12

Description

Implementation of the SALSA20 cipher reduced to 12 rounds.


Inherit SALSA20

inherit SALSA20 : SALSA20

Class Nettle.SERPENT

Description

Implementation of the SERPENT cipher.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.SERPENT.State

Description

State for SERPENT encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.SHA1

Description

Implementation of the SHA1 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA1.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA1.State

Description

State for SHA1 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA1.shake()

Module Nettle.SHA1.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA1 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA1.HMAC.SHA1

Description

The HMAC hash state.


Method create

Nettle.SHA1.HMAC.SHA1 Nettle.SHA1.HMAC.SHA1(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA224

Description

Implementation of the SHA224 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA224.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA224.State

Description

State for SHA224 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA224.shake()

Module Nettle.SHA224.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA224 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA224.HMAC.SHA224

Description

The HMAC hash state.


Method create

Nettle.SHA224.HMAC.SHA224 Nettle.SHA224.HMAC.SHA224(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA256

Description

Implementation of the SHA256 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA256.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA256.State

Description

State for SHA256 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA256.shake()

Module Nettle.SHA256.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA256 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA256.HMAC.SHA256

Description

The HMAC hash state.


Method create

Nettle.SHA256.HMAC.SHA256 Nettle.SHA256.HMAC.SHA256(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA384

Description

Implementation of the SHA384 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA384.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA384.State

Description

State for SHA384 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA384.shake()

Module Nettle.SHA384.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA384 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA384.HMAC.SHA384

Description

The HMAC hash state.


Method create

Nettle.SHA384.HMAC.SHA384 Nettle.SHA384.HMAC.SHA384(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA3_224

Description

Implementation of the SHA3_224 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA3_224.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA3_224.State

Description

State for SHA3_224 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA3_224.shake()

Module Nettle.SHA3_224.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA3_224 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA3_224.HMAC.SHA3_224

Description

The HMAC hash state.


Method create

Nettle.SHA3_224.HMAC.SHA3_224 Nettle.SHA3_224.HMAC.SHA3_224(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA3_256

Description

Implementation of the SHA3_256 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA3_256.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA3_256.State

Description

State for SHA3_256 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA3_256.shake()

Module Nettle.SHA3_256.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA3_256 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA3_256.HMAC.SHA3_256

Description

The HMAC hash state.


Method create

Nettle.SHA3_256.HMAC.SHA3_256 Nettle.SHA3_256.HMAC.SHA3_256(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA3_384

Description

Implementation of the SHA3_384 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA3_384.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA3_384.State

Description

State for SHA3_384 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA3_384.shake()

Module Nettle.SHA3_384.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA3_384 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA3_384.HMAC.SHA3_384

Description

The HMAC hash state.


Method create

Nettle.SHA3_384.HMAC.SHA3_384 Nettle.SHA3_384.HMAC.SHA3_384(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA3_512

Description

Implementation of the SHA3_512 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA3_512.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA3_512.State

Description

State for SHA3_512 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA3_512.shake()

Module Nettle.SHA3_512.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA3_512 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA3_512.HMAC.SHA3_512

Description

The HMAC hash state.


Method create

Nettle.SHA3_512.HMAC.SHA3_512 Nettle.SHA3_512.HMAC.SHA3_512(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA512

Description

Implementation of the SHA512 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA512.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA512.State

Description

State for SHA512 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA512.shake()

Module Nettle.SHA512.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA512 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA512.HMAC.SHA512

Description

The HMAC hash state.


Method create

Nettle.SHA512.HMAC.SHA512 Nettle.SHA512.HMAC.SHA512(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA512_224

Description

Implementation of the SHA512_224 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA512_224.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA512_224.State

Description

State for SHA512_224 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA512_224.shake()

Module Nettle.SHA512_224.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA512_224 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA512_224.HMAC.SHA512_224

Description

The HMAC hash state.


Method create

Nettle.SHA512_224.HMAC.SHA512_224 Nettle.SHA512_224.HMAC.SHA512_224(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SHA512_256

Description

Implementation of the SHA512_256 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SHA512_256.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SHA512_256.State

Description

State for SHA512_256 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SHA512_256.shake()

Module Nettle.SHA512_256.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SHA512_256 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SHA512_256.HMAC.SHA512_256

Description

The HMAC hash state.


Method create

Nettle.SHA512_256.HMAC.SHA512_256 Nettle.SHA512_256.HMAC.SHA512_256(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SM3

Description

Implementation of the SM3 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for SM3.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.SM3.State

Description

State for SM3 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), SM3.shake()

Module Nettle.SM3.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the SM3 hash algorithm.

See also

Crypto.HMAC

Class Nettle.SM3.HMAC.SM3

Description

The HMAC hash state.


Method create

Nettle.SM3.HMAC.SM3 Nettle.SM3.HMAC.SM3(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.SM4

Description

Implementation of the SM4 cipher.

Note

Requires Nettle 3.9 or later.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.SM4.State

Description

State for SM4 encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.STREEBOG256

Description

Implementation of the STREEBOG256 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for STREEBOG256.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.STREEBOG256.State

Description

State for STREEBOG256 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), STREEBOG256.shake()

Module Nettle.STREEBOG256.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the STREEBOG256 hash algorithm.

See also

Crypto.HMAC

Class Nettle.STREEBOG256.HMAC.STREEBOG256

Description

The HMAC hash state.


Method create

Nettle.STREEBOG256.HMAC.STREEBOG256 Nettle.STREEBOG256.HMAC.STREEBOG256(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.STREEBOG512

Description

Implementation of the STREEBOG512 hash algorithm.


Inherit Hash

inherit Hash : Hash


Method shake

string(8bit) shake(string(8bit) in, int(0..) bytes)

Description

SHAKE-256 hash. Works as a (faster) shortcut for STREEBOG512.State()->update(in)->shake(bytes).

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update() and State()->shake().

Class Nettle.STREEBOG512.State

Description

State for STREEBOG512 hashing.


Inherit State

inherit Hash::State : State


Method shake

string(8bit) shake(int(0..) bytes)

Description

SHAKE-256 hash.

This function is similar to hash(), but can return an arbitrary number of bytes. When bytes is digest_size (or more) the security is equivalent to that of hash(), albeit the output is different.

See also

hash(), State()->update(), STREEBOG512.shake()

Module Nettle.STREEBOG512.HMAC

Description

Accellerated implementation of HMAC (Hashing for Message Authenticity Control) with the STREEBOG512 hash algorithm.

See also

Crypto.HMAC

Class Nettle.STREEBOG512.HMAC.STREEBOG512

Description

The HMAC hash state.


Method create

Nettle.STREEBOG512.HMAC.STREEBOG512 Nettle.STREEBOG512.HMAC.STREEBOG512(string(8bit) passwd, void|int b)

Parameter passwd

The secret password (K).

Parameter b

Block size. Must 0 (zero) or equal to the block_size().

Class Nettle.Twofish

Description

Implementation of the Twofish cipher.


Inherit BlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.Twofish.State

Description

State for Twofish encyption.


Inherit State

inherit Cipher::State : State

Class Nettle.UMAC128_AES

Description

Implementation of the UMAC128_AES MAC algorithm.


Inherit MAC

inherit MAC : MAC

Class Nettle.UMAC128_AES.State

Description

State for UMAC128_AES macing.


Inherit State

inherit MAC::State : State

Class Nettle.UMAC32_AES

Description

Implementation of the UMAC32_AES MAC algorithm.


Inherit MAC

inherit MAC : MAC

Class Nettle.UMAC32_AES.State

Description

State for UMAC32_AES macing.


Inherit State

inherit MAC::State : State

Class Nettle.UMAC64_AES

Description

Implementation of the UMAC64_AES MAC algorithm.


Inherit MAC

inherit MAC : MAC

Class Nettle.UMAC64_AES.State

Description

State for UMAC64_AES macing.


Inherit State

inherit MAC::State : State

Class Nettle.UMAC96_AES

Description

Implementation of the UMAC96_AES MAC algorithm.


Inherit MAC

inherit MAC : MAC

Class Nettle.UMAC96_AES.State

Description

State for UMAC96_AES macing.


Inherit State

inherit MAC::State : State

Class Nettle.Yarrow

Description

Yarrow is a family of pseudo-randomness generators, designed for cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson. Yarrow-160 is described in a paper at http://www.schneier.com/paper-yarrow.html, and it uses SHA1 and triple-DES, and has a 160-bit internal state. Nettle implements Yarrow-256, which is similar, but uses SHA256 and AES to get an internal state of 256 bits.


Method create

Nettle.Yarrow Nettle.Yarrow(void|int(0..) sources)

Description

The number of entropy sources that will feed entropy to the random number generator is given as an argument to Yarrow during instantiation.

See also

update


Method force_reseed

void force_reseed()

Description

By calling this function entropy is moved from the slow pool to the fast pool. Read more about Yarrow before using this.


Method get_seed

string(8bit) get_seed()

Description

Returns part of the internal state so that it can be saved for later seeding. This method is deprecated. Instead read the min_seed_size number of bytes from the random_string method.

See also

seed(), random_string()


Method is_seeded

bool is_seeded()

Description

Returns 1 if the random generator is seeded and ready to generator output. 0 otherwise.

See also

seed


Method min_seed_size

int(0..) min_seed_size()

Description

Returns the minimal number of characters that the seed needs to properly seed the random number generator.

See also

seed


Method needed_sources

int(0..) needed_sources()

Description

The number of sources that must reach the threshold before a slow reseed will happen.


Method random_string

string(8bit) random_string(int(0..) length)

Description

Returns a pseudo-random string of the requested length.


Method seed

Yarrow seed(string(8bit) data)

Description

The random generator needs to be seeded before it can be used. The seed must be at least 32 characters long. The seed could be stored from a previous run by inserting the value returned from previous random_string call.

Returns

Returns the called object.

See also

min_seed_size, is_seeded


Method update

bool update(string(8bit) data, int source, int entropy)

Description

Inject additional entropy into the random number generator.

See also

create