21. Cryptography

21.1. Password hashing


Methodcrypt

string(46..122)crypt(string(1..255)password)
boolcrypt(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()


Methodhash

string(7bit)hash(string(8bit)password, string(7bit)|voidscheme, int(0..)|voidrounds)

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


Methodverify

intverify(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_base64SHA1 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_base64MD5 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.


ConstantINITIATE
ConstantACCEPT
ConstantBOTH

constantint GSSAPI.INITIATE
constantint GSSAPI.ACCEPT
constantint 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.


ConstantDELEG_FLAG
ConstantMUTUAL_FLAG
ConstantREPLAY_FLAG
ConstantSEQUENCE_FLAG
ConstantCONF_FLAG
ConstantINTEG_FLAG
ConstantANON_FLAG
ConstantPROT_READY_FLAG
ConstantTRANS_FLAG

constantint GSSAPI.DELEG_FLAG
constantint GSSAPI.MUTUAL_FLAG
constantint GSSAPI.REPLAY_FLAG
constantint GSSAPI.SEQUENCE_FLAG
constantint GSSAPI.CONF_FLAG
constantint GSSAPI.INTEG_FLAG
constantint GSSAPI.ANON_FLAG
constantint GSSAPI.PROT_READY_FLAG
constantint 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.


ConstantBAD_MECH
ConstantBAD_NAME
ConstantBAD_NAMETYPE
ConstantBAD_BINDINGS
ConstantBAD_STATUS
ConstantBAD_SIG
ConstantNO_CRED
ConstantNO_CONTEXT
ConstantDEFECTIVE_TOKEN
ConstantDEFECTIVE_CREDENTIAL
ConstantCREDENTIALS_EXPIRED
ConstantCONTEXT_EXPIRED
ConstantFAILURE
ConstantBAD_QOP
ConstantUNAUTHORIZED
ConstantUNAVAILABLE
ConstantDUPLICATE_ELEMENT
ConstantNAME_NOT_MN

constantint GSSAPI.BAD_MECH
constantint GSSAPI.BAD_NAME
constantint GSSAPI.BAD_NAMETYPE
constantint GSSAPI.BAD_BINDINGS
constantint GSSAPI.BAD_STATUS
constantint GSSAPI.BAD_SIG
constantint GSSAPI.NO_CRED
constantint GSSAPI.NO_CONTEXT
constantint GSSAPI.DEFECTIVE_TOKEN
constantint GSSAPI.DEFECTIVE_CREDENTIAL
constantint GSSAPI.CREDENTIALS_EXPIRED
constantint GSSAPI.CONTEXT_EXPIRED
constantint GSSAPI.FAILURE
constantint GSSAPI.BAD_QOP
constantint GSSAPI.UNAUTHORIZED
constantint GSSAPI.UNAVAILABLE
constantint GSSAPI.DUPLICATE_ELEMENT
constantint 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.


ConstantCONTINUE_NEEDED
ConstantDUPLICATE_TOKEN
ConstantOLD_TOKEN
ConstantUNSEQ_TOKEN
ConstantGAP_TOKEN

constantint GSSAPI.CONTINUE_NEEDED
constantint GSSAPI.DUPLICATE_TOKEN
constantint GSSAPI.OLD_TOKEN
constantint GSSAPI.UNSEQ_TOKEN
constantint 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.


ConstantERROR_MASK

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


ConstantINFO_MASK

constantint GSSAPI.INFO_MASK

Description

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


ConstantNT_HOSTBASED_SERVICE
ConstantNT_USER_NAME
ConstantNT_MACHINE_UID_NAME
ConstantNT_STRING_UID_NAME
ConstantNT_ANONYMOUS
ConstantNT_EXPORT_NAME
ConstantKRB5_NT_PRINCIPAL_NAME

constantstring GSSAPI.NT_HOSTBASED_SERVICE
constantstring GSSAPI.NT_USER_NAME
constantstring GSSAPI.NT_MACHINE_UID_NAME
constantstring GSSAPI.NT_STRING_UID_NAME
constantstring GSSAPI.NT_ANONYMOUS
constantstring GSSAPI.NT_EXPORT_NAME
constantstring 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.


Methoddescribe_services

stringdescribe_services(intservices)

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


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


Methodmajor_status_messages

array(string) major_status_messages(intmajor_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.


Methodminor_status_messages

array(string) minor_status_messages(intminor_status, void|stringmech)

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.


Methodnames_for_mech

multiset(string) names_for_mech(stringmech)

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.


InheritContext

inherit Context : Context


Methodaccept

stringaccept(stringremote_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.


Methodcreate

GSSAPI.AcceptContextGSSAPI.AcceptContext(void|Credcred, void|intrequired_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).


Methoddelegated_cred

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


Methodcreate

GSSAPI.ContextGSSAPI.Context(stringinterprocess_token, void|intrequired_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.


Methoddelete

voiddelete()

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.


Methodexport

stringexport()

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.


Methodget_mic

stringget_mic(stringmessage, void|intqop)

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.


Methodis_established
Methodservices
Methodlocally_initiated
Methodsource_name
Methodtarget_name
Methodlifetime
Methodmech

intis_established()
intservices()
intlocally_initiated()
Namesource_name()
Nametarget_name()
int(0..)lifetime()
stringmech()

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.


Methodlast_confidential

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


Methodlast_major_status
Methodlast_minor_status

intlast_major_status()
intlast_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.


Methodlast_qop

intlast_qop()

Description

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


Methodprocess_token

voidprocess_token(stringremote_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.


Methodrequired_services

intrequired_services(void|intservices)

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


Methodunwrap

stringunwrap(stringmessage, void|intaccept_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.


Methodverify_mic

intverify_mic(stringmessage, stringmic)

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.


Methodwrap

stringwrap(stringmessage, void|intencrypt, void|intqop)

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


Methodwrap_size_limit

int(0..)wrap_size_limit(int(0..)output_size, intencrypt, void|intqop)

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.


Methodname
Methodcred_usage
Methodmechs
Methodlifetime
Methodinit_lifetime
Methodaccept_lifetime

GSSAPI.Namename(void|stringmech)
intcred_usage(void|stringmech)
multiset(string) mechs()
int(0..)|Int.inflifetime()
int(0..)|Int.infinit_lifetime(stringmech)
int(0..)|Int.infaccept_lifetime(stringmech)

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.


Methodacquire

voidacquire(Name|stringname, intcred_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.


Methodadd

voidadd(Name|stringname, intcred_usage, stringdesired_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.


Methodrelease

voidrelease()

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.


InheritGeneric

inherit Error.Generic : Generic


Constantis_gssapi_error
Constanterror_type

constantint GSSAPI.Error.is_gssapi_error
constantstring GSSAPI.Error.error_type

Description

Object recognition constants.


Variablemajor_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


Variableminor_status

int GSSAPI.Error.minor_status

Description

The minor status code specific for the mechanism.

See also

minor_status_messages, minor_status_mech


Methodcreate

GSSAPI.ErrorGSSAPI.Error(void|intmajor, void|intminor, void|stringmech, void|stringmessage, void|arraybacktrace)

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.


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


Methodminor_status_mech

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


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


InheritContext

inherit Context : Context


Methodcreate

GSSAPI.InitContextGSSAPI.InitContext(void|Credcred, void|Name|stringtarget_name, void|stringmech, void|intrequired_services, void|intdesired_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).


Methodinit

stringinit(void|stringremote_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.


InheritGeneric

inherit Error.Generic : Generic


Constantis_gssapi_missing_services_error
Constanterror_type

constantint GSSAPI.MissingServicesError.is_gssapi_missing_services_error
constantstring GSSAPI.MissingServicesError.error_type

Description

Object recognition constants.


Variableservices

int GSSAPI.MissingServicesError.services

Description

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

See also

GSSAPI.describe_services


Methodcreate

GSSAPI.MissingServicesErrorGSSAPI.MissingServicesError(void|intmissing_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

inthash_value(GSSAPI.Namearg)

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.


Methodcanonicalize

Namecanonicalize(stringmech)

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.


Methodcreate

GSSAPI.NameGSSAPI.Name(stringname, void|stringname_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.


Methoddisplay_name
Methoddisplay_name_type

stringdisplay_name()
stringdisplay_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.


Methodexport

stringexport(void|stringmech)

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.


Methodmechs

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


Methodmake_crypt_md5

string(8bit)make_crypt_md5(string(8bit)password, string(8bit)|voidsalt)

Description

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

See also

verify_crypt_md5


Methodrot13

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.


Methodsiphash24

intsiphash24(stringdata, void|intkey)

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.


Methodverify_crypt_md5

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


InheritAE

inherit __builtin.Nettle.AE : AE

Class Crypto.AEAD

Description

Abstract class for AEAD algorithms.


InheritAEAD

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.


InheritBlockCipher

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.


InheritBlockCipher16

inherit Nettle.BlockCipher16 : BlockCipher16

Class Crypto.BufferedCipher

Description

Abstract class for block cipher meta algorithms.

Contains the Buffer submodule.


InheritBufferedCipher

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


InheritCipher

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


Methodcreate

Crypto.HMACCrypto.HMAC(.Hashh, int(1..)|voidb)

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.


Methodpkcs_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


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


InheritHash

inherit Nettle.Hash : Hash

Class Crypto.MAC

Description

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


InheritMAC

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.


Methodname

string(7bit)name()

Description

Returns the printable name of the signing algorithm.

Class Crypto.Sign.State


InheritSign

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.


Methoddecrypt

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

Description

Decrypts the cryptogram c.


Methodencrypt

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

Description

Encrypts the message m.


Methodfilter

stringfilter(stringm, multiset(int)|voidsave)

Description

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


Methodset_ACA_K1_key

this_programset_ACA_K1_key(stringkey, void|intoffset, array(string)|voidalphabet)

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.


Methodset_ACA_K2_key

this_programset_ACA_K2_key(stringkey, void|intoffset, array(string)|voidalphabet)

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.


Methodset_ACA_K3_key

this_programset_ACA_K3_key(stringkey, intoffset, array(string)|voidalphabet)

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.


Methodset_ACA_K4_key

this_programset_ACA_K4_key(stringkey1, stringkey2, void|intoffset, array(string)|voidalphabet)

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.


Methodset_key

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


Methodset_null_chars

this_programset_null_chars(int|floatp, 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.


Methodset_rot_key

this_programset_rot_key(int(1..)|voidsteps, 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.


InheritAES

inherit Nettle.AES : AES

Module Crypto.AES.POLY1305


InheritPOLY1305_AES

inherit Nettle.POLY1305_AES : POLY1305_AES


Method`()

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


InheritUMAC128_AES

inherit Nettle.UMAC128_AES : UMAC128_AES


Method`()

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


InheritUMAC32_AES

inherit Nettle.UMAC32_AES : UMAC32_AES


Method`()

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


InheritUMAC64_AES

inherit Nettle.UMAC64_AES : UMAC64_AES


Method`()

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


InheritUMAC96_AES

inherit Nettle.UMAC96_AES : UMAC96_AES


Method`()

protectedState`()(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.


InheritARCFOUR

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.


InheritARCTWO

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.


InheritBLOWFISH

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.


InheritCAST128

inherit Nettle.CAST128 : CAST128

Module Crypto.Camellia

Description

The Camellia 128-bit block cipher.


InheritCAMELLIA

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.


InheritCHACHA

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.POLY1305MAC. The iv/nonce handling differs.

Note

This module is not available in all versions of Nettle.


InheritCHACHA_POLY1305

inherit Nettle.CHACHA_POLY1305 : CHACHA_POLY1305

Module Crypto.Checksum

Description

Some non-cryptographic checksums.


Methodadler32

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.


Methodcrc32

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.


Methodcrc32c

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.


InheritDES

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.


InheritDES3

inherit Nettle.DES3 : DES3

Module Crypto.DH

Description

Diffie-Hellman key-exchange related stuff.


VariableFFDHE2048

Parameters Crypto.DH.FFDHE2048

Description

Finite Field Diffie-Hellman 2048

From RFC 7919 appendix A.1.


VariableFFDHE2432

Parameters Crypto.DH.FFDHE2432

Description

Finite Field Diffie-Hellman 2432

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


VariableFFDHE3072

Parameters Crypto.DH.FFDHE3072

Description

Finite Field Diffie-Hellman 3072

From RFC 7919 appendix A.2.


VariableFFDHE4096

Parameters Crypto.DH.FFDHE4096

Description

Finite Field Diffie-Hellman 4096

From RFC 7919 appendix A.3.


VariableFFDHE6144

Parameters Crypto.DH.FFDHE6144

Description

Finite Field Diffie-Hellman 6144

From RFC 7919 appendix A.4.


VariableFFDHE8192

Parameters Crypto.DH.FFDHE8192

Description

Finite Field Diffie-Hellman 8192

From RFC 7919 appendix A.5.


VariableMODPGroup1

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.


VariableMODPGroup14

Parameters Crypto.DH.MODPGroup14

Description

MODP Group 14 (2048 bit).

RFC 3526 section 3


VariableMODPGroup15

Parameters Crypto.DH.MODPGroup15

Description

MODP Group 15 (3072 bit).

RFC 3526 section 4


VariableMODPGroup16

Parameters Crypto.DH.MODPGroup16

Description

MODP Group 16 (4096 bit).

RFC 3526 section 5


VariableMODPGroup17

Parameters Crypto.DH.MODPGroup17

Description

MODP Group 17 (6144 bit).

RFC 3526 section 6


VariableMODPGroup18

Parameters Crypto.DH.MODPGroup18

Description

MODP Group 18 (8192 bit).

RFC 3526 section 7


VariableMODPGroup2

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.


VariableMODPGroup22

Parameters Crypto.DH.MODPGroup22

Description

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

RFC 5114 section 2.1


VariableMODPGroup23

Parameters Crypto.DH.MODPGroup23

Description

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

RFC 5114 section 2.2


VariableMODPGroup24

Parameters Crypto.DH.MODPGroup24

Description

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

RFC 5114 section 2.3


VariableMODPGroup5

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.


InheritDH_Params

inherit Nettle.DH_Params : DH_Params


Variableg

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

Description

Generator.


Variablep

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

Description

Prime.


Variableq

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

Description

Subgroup size.


Methodcreate

Crypto.DH.ParametersCrypto.DH.Parameters(this_programother)

Description

Initialize the set of Diffie-Hellman parameters.

Parameter other

Copy the parameters from this object.


Methodcreate

Crypto.DH.ParametersCrypto.DH.Parameters(DSA_Statedsa)

Description

Initialize the set of Diffie-Hellman parameters.

Parameter dsa

Copy the parameters from this object.


Methodcreate

Crypto.DH.ParametersCrypto.DH.Parameters(Gmp.mpz|intp, Gmp.mpz|int|voidg, Gmp.mpz|int|voidq)

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.


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

The generated public key.

Gmp.mpz1

The corresponding private key.


Methodvalidate

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


InheritSign

inherit Crypto.Sign : Sign


Method`()

protectedState`()()

Description

Calling `() will return a State object.


Methodname

string(8bit)name()

Description

Returns the string "DSA".

Class Crypto.DSA.State


Inheritthis_program

inherit ::this_program : this_program


Method_equal

boolequal(Crypto.DSA.Statefrom, mixedother)

Description

Compares the keys of this DSA object with something other.


Methodgenerate_key

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


Methodgenerate_key

variantthis_programgenerate_key(intp_bits, intq_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.


Methodgenerate_key

variantthis_programgenerate_key(.DH.Parametersparams)

Description

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


Methodget_g

Gmp.mpz|zeroget_g()

Description

Returns the DSA generator (g).


Methodget_p

Gmp.mpz|zeroget_p()

Description

Returns the DSA modulo (p).


Methodget_q

Gmp.mpz|zeroget_q()

Description

Returns the DSA group order (q).


Methodget_x

Gmp.mpz|zeroget_x()

Description

Returns the DSA private key (x).


Methodget_y

Gmp.mpz|zeroget_y()

Description

Returns the DSA public key (y).


Methodhash

Gmp.mpzhash(string(8bit)msg, .Hashh)

Description

Makes a DSA hash of the message msg.


Methodname

string(8bit)name()

Description

Returns the string "DSA".


Methodpkcs_algorithm_identifier

Sequencepkcs_algorithm_identifier()

Description

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


Methodpkcs_public_key

Sequencepkcs_public_key()

Description

Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.


Methodpkcs_sign

string(8bit)pkcs_sign(string(8bit)message, .Hashh)

Description

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


Methodpkcs_signature_algorithm_id

Sequence|zeropkcs_signature_algorithm_id(.Hashhash)

Description

Returns the PKCS-1 algorithm identifier for DSA and the provided hash algorithm. Only SHA1 supported.


Methodpkcs_verify

boolpkcs_verify(string(8bit)message, .Hashh, string(8bit)sign)

Description

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


Methodpublic_key_equal

boolpublic_key_equal(this_programdsa)

Description

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


Methodraw_sign

array(Gmp.mpz) raw_sign(Gmp.mpzh, Gmp.mpz|voidk)

Description

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


Methodraw_verify

boolraw_verify(Gmp.mpzh, Gmp.mpzr, Gmp.mpzs)

Description

Verify the signature r,s against the message h.


Methodset_private_key

this_programset_private_key(Gmp.mpzsecret)

Description

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


Methodset_public_key

this_programset_public_key(Gmp.mpzmodulo, Gmp.mpzorder, Gmp.mpzgenerator, Gmp.mpzkey)

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.


Methodset_public_key

variantthis_programset_public_key(.DH.Parametersparams, Gmp.mpzkey)

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.


Methodset_random

this_programset_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


InheritECC_Curve

inherit Nettle.ECC_Curve : ECC_Curve


Methodpkcs_algorithm_identifier

Sequencepkcs_algorithm_identifier()

Description

Returns the AlgorithmIdentifier as defined in RFC 5480 section 2.


Methodpkcs_ec_parameters

Identifierpkcs_ec_parameters()

Description

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


Methodpkcs_named_curve_id

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


InheritECDSA

inherit ECC_Curve::ECDSA : ECDSA


Method_equal

boolequal(Crypto.ECC.Curve.ECDSAfrom, mixedother)

Description

Compares the keys of this ECDSA object with something other.


Methodgenerate_key

this_programgenerate_key()

Description

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


Methodget_curve

Curveget_curve()

Description

Return the curve.


Methodget_point

Pointget_point()

Description

Get the public key curve point.


Methodget_public_key

string(8bit)get_public_key()

Description

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


Methodjose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_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


Methodjose_sign

string(7bit)|zerojose_sign(string(8bit)message, .Hash|voidh, mapping(string(7bit):string(7bit)|int)|voidheaders)

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


Methodjwa

string(7bit)|zerojwa(.Hashhash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


Methodjwk

mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_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


Methodkey_size

int(0..)key_size()

Description

Return the size of the private key in bits.


Methodpkcs_algorithm_identifier

Sequencepkcs_algorithm_identifier()

Description

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


Methodpkcs_public_key

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


Methodpkcs_sign

string(8bit)pkcs_sign(string(8bit)message, .Hashh)

Description

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


Methodpkcs_signature_algorithm_id

Sequence|zeropkcs_signature_algorithm_id(.Hashhash)

Description

Returns the PKCS-1 algorithm identifier for ECDSA and the provided hash algorithm. Only SHA-1 and SHA-2 based hashes are supported currently.


Methodpkcs_verify

boolpkcs_verify(string(8bit)message, .Hashh, string(8bit)sign)

Description

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


Methodpublic_key_equal

boolpublic_key_equal(this_programecdsa)

Description

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


Methodset_private_key

this_programset_private_key(Gmp.mpz|intk)

Description

Set the private key.

Note

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


Methodset_private_key

variantthis_programset_private_key(string(8bit)k)

Description

Set the private key.

Note

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


Methodset_public_key

this_programset_public_key(Gmp.mpz|intx, Gmp.mpz|inty)

Description

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

Note

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


Methodset_public_key

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


Methodset_random

this_programset_random(function(int:string(8bit)) r)

Description

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


Methodsize

intsize()

Description

Return the curve size in bits.

Module Crypto.ECC.Curve25519

Description

The definition of the elliptic curve X25519.

See also

Curve, Curve448


InheritCurve25519

inherit Nettle.Curve25519 : Curve25519


Methodpkcs_algorithm_identifier

Sequencepkcs_algorithm_identifier()

Description

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


Methodpkcs_eddsa_id

Identifierpkcs_eddsa_id()

Description

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


Methodpkcs_named_curve_id

Identifierpkcs_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


InheritEdDSA

inherit Curve25519::EdDSA : EdDSA


Method_equal

boolequal(Crypto.ECC.Curve25519.EdDSAfrom, mixedother)

Description

Compares the keys of this ECDSA object with something other.


Methodgenerate_key

this_programgenerate_key()

Description

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


Methodget_curve

_Curve25519get_curve()

Description

Return the curve.


Methodget_point

Pointget_point()

Description

Get the public key curve point.


Methodget_public_key

string(8bit)get_public_key()

Description

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


Methodjose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_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


Methodjose_sign

string(7bit)|zerojose_sign(string(8bit)message, .Hash|voidh, mapping(string(7bit):string(7bit)|int)|voidheaders)

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


Methodjwa

string(7bit)jwa(.Hash|voidhash)

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


Methodjwk

mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_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


Methodkey_size

int(0..)key_size()

Description

Return the size of the private key in bits.


Methodpkcs_algorithm_identifier

Sequencepkcs_algorithm_identifier()

Description

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


Methodpkcs_named_curve_id

Identifierpkcs_named_curve_id()

Description

Returns the EdDSA identifier for the curve.


Methodpkcs_public_key

Sequencepkcs_public_key()

Description

Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.


Methodpkcs_sign

string(8bit)pkcs_sign(string(8bit)message, .Hash|voidh)

Description

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

Parameter h

Hash algorithm; ignored for Curve25519.


Methodpkcs_signature_algorithm_id

Sequencepkcs_signature_algorithm_id(.Hash|voidhash)

Description

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

Parameter hash

Hash algorithm; ignored for Curve25519.


Methodpkcs_verify

boolpkcs_verify(string(8bit)message, .Hash|voidh, string(8bit)sign)

Description

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

Parameter h

Hash algorithm; ignored for Ed25519.


Methodpublic_key_equal

boolpublic_key_equal(this_programeddsa)

Description

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


Methodset_private_key

this_programset_private_key(string(8bit)k)

Description

Set the private key.

Note

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


Methodset_public_key

this_programset_public_key(string(8bit)key)


Methodset_public_key

variantthis_programset_public_key(Pointp)


Methodset_random

this_programset_random(function(int:string(8bit)) r)

Description

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


Methodsize

intsize()

Description

Return the curve size in bits.

Module Crypto.ECC.GOST_GC256B


InheritCurve

inherit Curve : Curve

Module Crypto.ECC.GOST_GC512A


InheritCurve

inherit Curve : Curve

Module Crypto.ECC.SECP_192R1


InheritCurve

inherit Curve : Curve

Module Crypto.ECC.SECP_224R1


InheritCurve

inherit Curve : Curve

Module Crypto.ECC.SECP_256R1


InheritCurve

inherit Curve : Curve

Module Crypto.ECC.SECP_384R1


InheritCurve

inherit Curve : Curve

Module Crypto.ECC.SECP_521R1


InheritCurve

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.


InheritGOST94

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


InheritGOST94CP

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.


InheritIDEA

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.


Methoddecrypt

intdecrypt(stringc)

Description

Decode a koremutake string into an integer.


Methodencrypt

stringencrypt(intm)

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.


InheritMD2

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.


InheritMD4

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.


InheritMD5

inherit Nettle.MD5 : MD5


Methodcrypt_hash

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

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.


Methodcreate

Crypto.NT.CryptContextCrypto.NT.CryptContext(string(8bit)name, string(8bit)csp, inttype, intflags)

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.


Methodread

string(8bit)read(intsize, string(8bit)|voidinit)

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


MethodLMOWFv1

string(8bit)LMOWFv1(stringPasswd, stringUser, stringUserDom)

Description

Lan-Manager One-Way Function version 1.

This function is also known as LM hash.


MethodLMOWFv2

string(8bit)LMOWFv2(stringPasswd, stringUser, stringUserDom)

Description

Lan-Manager One-Way Function version 2.

This function is identical to NTOWFv2().


MethodNTOWFv1

string(8bit)NTOWFv1(stringPasswd, stringUser, stringUserDom)

Description

NT One-Way Function version 1.


MethodNTOWFv2

string(8bit)NTOWFv2(stringPasswd, stringUser, stringUserDom)

Description

NT One-Way Function version 2.


MethodSBKv1

string(8bit)SBKv1(stringPasswd, stringUser, stringUserDom)

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.


InheritAE

inherit .AE : AE

Description

Implements the empty AE algorithm.


InheritMAC

inherit .MAC : MAC

Description

Implements the empty MAC algorithm.


Constantmac_jwa_id

protected constantstring Crypto.None.mac_jwa_id

Description

Implements the "none" JWS algorithm.

Module Crypto.PGP

Description

PGP stuff. See RFC 4880.


Methoddecode

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

Description

Decodes PGP data.


Methoddecode_radix64

mapping(string:mixed) decode_radix64(stringdata)

Description

Decode ASCII armour.


Methodencode_radix64

stringencode_radix64(stringdata, stringtype, mapping(string:string)|voidextra)

Description

Encode PGP data with ASCII armour.


Methodverify_signature

intverify_signature(stringtext, stringsig, stringpubkey)

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.


Inheritpre

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.


InheritRIPEMD160

inherit Nettle.RIPEMD160 : RIPEMD160

Module Crypto.RSA


InheritSign

inherit Crypto.Sign : Sign


Method`()

protectedState`()(mapping(string(8bit):Gmp.mpz|int|string(7bit))|voidparams)

Description

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

See also

State()


Methodname

string(8bit)name()

Description

Returns the string "RSA".

Class Crypto.RSA.LowState


InheritState

inherit Sign::State : State


Method_equal

boolequal(Crypto.RSA.LowStatefrom, mixedother)

Description

Compares the keys of this RSA object with something other.


Methodcreate

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

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


Methodgenerate_key

this_programgenerate_key(int(89..)bits, int(1..)|Gmp.mpz|voide)

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.


Methodget_d

Gmp.mpz|zeroget_d()

Description

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


Methodget_e

Gmp.mpz|zeroget_e()

Description

Returns the RSA public exponent (e).


Methodget_n

Gmp.mpz|zeroget_n()

Description

Returns the RSA modulo (n).


Methodget_p

Gmp.mpz|zeroget_p()

Description

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


Methodget_q

Gmp.mpz|zeroget_q()

Description

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


Methodjwa

string(7bit)jwa(.Hashhash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


Methodjwk

mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_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


Methodkey_size

int(0..)key_size()

Description

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


Methodname

string(8bit)name()

Description

Returns the string "RSA".


Methodpublic_key_equal

boolpublic_key_equal(this_programrsa)

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(array(Gmp.mpz) key)

Description

Sets the public key to keyand the mod to decryption.

See also

set_encrypt_key, crypt


Methodset_encrypt_key

this_programset_encrypt_key(array(Gmp.mpz) key)

Description

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

See also

set_decrypt_key, crypt


Methodset_private_key

this_programset_private_key(Gmp.mpz|intpriv, array(Gmp.mpz|int)|voidextra)

Description

Sets the private key.

Parameter priv

The private RSA exponent, often called d.

Parameter extra
Array
Gmp.mpz|int0

The first prime, often called p.

Gmp.mpz|int1

The second prime, often called q.


Methodset_public_key

this_programset_public_key(Gmp.mpz|intmodulo, Gmp.mpz|intpub)

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.


Methodset_random

this_programset_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


InheritLowState

inherit LowState : LowState


VariableOAEP

this_program Crypto.RSA.OAEPState.OAEP

Description

Get the OAEP encryption state.

Note

Read only


Methodblock_size

localintblock_size()

Description

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


Methodcrypt

localstring(8bit)crypt(string(8bit)s, string(8bit)|voidlabel)

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


InheritPSSState

inherit PSSState : PSSState


VariablePKCS1_5

this_program Crypto.RSA.PKCS1_5State.PKCS1_5

Description

Get the PKCS#1 1.5 state.

Note

Read only


Methodblock_size

intblock_size()

Description

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


Methodcrypt

string(8bit)|zerocrypt(string(8bit)s)

Description

Encrypt or decrypt depending on set mode.

See also

set_encrypt_key, set_decrypt_key


Methoddecrypt

string(8bit)|zerodecrypt(string(8bit)s)

Description

Decrypt a message encrypted with encrypt.


Methodencrypt

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

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.


Methodjose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_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


Methodjose_sign

string(7bit)|zerojose_sign(string(8bit)message, mapping(string(7bit):string(7bit)|int)|voidheaders, .Hash|voidh)

Description

Signs the message with a JOSE JWS 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


Methodjwa

string(7bit)|zerojwa(.Hashhash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


Methodname

string(8bit)name()

Description

Returns the string "RSA".


Methodpkcs_public_key

Sequencepkcs_public_key()

Description

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


Methodpkcs_sign

string(8bit)pkcs_sign(string(8bit)message, .Hashh)

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.


Methodpkcs_signature_algorithm_id

Sequencepkcs_signature_algorithm_id(.Hashhash)

Description

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


Methodpkcs_verify

boolpkcs_verify(string(8bit)message, .Hashh, string(8bit)sign)

Description

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


Methodraw_sign

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


Methodraw_verify

boolraw_verify(string(8bit)digest, Gmp.mpzs)

Description

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

See also

rsa_pad, raw_sign


Methodrsa_pad

Gmp.mpzrsa_pad(string(8bit)message, int(1..2)type, function(int(0..):string(8bit))|voidrandom)

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.


Methodrsa_unpad

string(8bit)|zerorsa_unpad(Gmp.mpzblock, inttype)

Description

Reverse the effect of rsa_pad.

Class Crypto.RSA.PSSState

Description

RSA PSS signatures (RFC 3447 section 8.1).

See also

PKCS1_5State


InheritOAEPState

inherit OAEPState : OAEPState


VariablePSS

this_program Crypto.RSA.PSSState.PSS

Description

Get the PSS signature state.

Note

Read only


Methodjose_decode

localarray(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_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


Methodjose_sign

localstring(7bit)|zerojose_sign(string(8bit)message, mapping(string(7bit):string(7bit)|int)|voidheaders, .Hash|voidh)

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


Methodjwa

localstring(7bit)|zerojwa(.Hashhash)

Description

Get the JWS algorithm identifier for a hash.

Returns

Returns 0 (zero) on failure.

See also

RFC 7518 section 3.1


Methodpkcs_sign

localstring(8bit)pkcs_sign(string(8bit)message, .Hashh, string(8bit)|int(0..)|voidsalt)

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


Methodpkcs_signature_algorithm_id

localSequencepkcs_signature_algorithm_id(.Hashhash, int(0..)|voidsaltlen)

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


Methodpkcs_verify

localboolpkcs_verify(string(8bit)message, .Hashh, string(8bit)sign, int(0..)|voidsaltlen)

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


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


InheritFast

inherit Random.Fast : Fast


Methodadd_entropy

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


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


InheritSALSA20

inherit Nettle.SALSA20 : SALSA20

Module Crypto.SALSA20R12

Description

The SALSA20 stream cipher reduced to just 12 rounds.


InheritSALSA20R12

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.


InheritSHA1

inherit Nettle.SHA1 : SHA1

Module Crypto.SHA1.HMAC


Inheritthis_program

inherit ::this_program : this_program


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


InheritSHA224

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.


InheritSHA256

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.


InheritSHA384

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.


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


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


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


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


InheritSHA512

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.


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


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


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


InheritSM3

inherit Nettle.SM3 : SM3

Module Crypto.SM4

Description

The SM4 block cipher.


InheritSM4

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


InheritSTREEBOG256

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


InheritSTREEBOG512

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.


InheritSERPENT

inherit Nettle.SERPENT : SERPENT

Module Crypto.Twofish

Description

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


InheritTwofish

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.


Methodbcrypt_hash

string(7bit)bcrypt_hash(string(8bit)password, string(7bit)scheme, string(8bit)|voidsalt, int|voidlog2rounds)

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


Methodbcrypt_verify

intbcrypt_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


Methodcrc32c

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.


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


Methoddsa_generate_keypair

array(Gmp.mpz) dsa_generate_keypair(intp_bits, intq_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.mpz0

The value p, the modulo.

Gmp.mpz1

The value q, the group order.

Gmp.mpz2

The value g, the generator.

Gmp.mpz3

The value y, the public value.

Gmp.mpz4

The value x, the private value.


Methodrsa_generate_keypair

array(Gmp.mpz) rsa_generate_keypair(intbits, inte, 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.mpz0

The value n, the modulo.

Gmp.mpz1

The value d, the private exponent.

Gmp.mpz2

The value p, a prime.

Gmp.mpz3

The value q, a prime.


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


Methodversion

stringversion()

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.


InheritAEAD

inherit __builtin.Nettle.AEAD : AEAD


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


Methoddigest_size

int(0..)digest_size()

Description

Returns the size of a MAC digest.


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


Methodkey_size

int(0..)key_size()

Returns

The recommended key size for the cipher.


Methodname

string(8bit)name()

Returns

A human readable name for the algorithm.

Class Nettle.AEAD.State

Description

Base class for AEAD contexts.


InheritState

inherit AEAD::State : State


Methodblock_size

int(0..)block_size()

Returns

The block size for this cipher.

Note

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


Methodcrypt

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

Description

Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

Parameter data

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

Returns

The encrypted or decrypted data.


Methoddigest

string(8bit)digest(int|voidlength)

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.


Methoddigest_size

int(0..)digest_size()

Description

Returns the size of a MAC digest.


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


Methodkey_size

int(0..)key_size()

Returns

The actual key size for this cipher.


Methodmake_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


Methodname

string(8bit)name()

Returns

A human readable name for the algorithm.

Note

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


Methodset_decrypt_key

Stateset_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


Methodset_encrypt_key

Stateset_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


Methodset_iv

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


Methodupdate

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


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES.State

Description

State for AES encyption.


InheritState

inherit Cipher::State : State

Class Nettle.AES128

Description

Implementation of the AES128 cipher.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES128.State

Description

State for AES128 encyption.


InheritState

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


Variablereseed_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


Variablereseed_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


Methodentropy_underflow

voidentropy_underflow()

Description

Called when random_string has been called more than reseed_interval times.


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


Methodreseed

voidreseed(string(8bit)data)

Description

Updated the internal key with the provided additional entropy.

Class Nettle.AES192

Description

Implementation of the AES192 cipher.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES192.State

Description

State for AES192 encyption.


InheritState

inherit Cipher::State : State

Class Nettle.AES256

Description

Implementation of the AES256 cipher.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.AES256.State

Description

State for AES256 encyption.


InheritState

inherit Cipher::State : State

Class Nettle.ARCFOUR

Description

Implementation of the ARCFOUR cipher.


InheritCipher

inherit Cipher : Cipher

Class Nettle.ARCFOUR.State

Description

State for ARCFOUR encyption.


InheritState

inherit Cipher::State : State

Class Nettle.ARCTWO

Description

Implementation of the ARCTWO cipher.


InheritBlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.ARCTWO.State

Description

State for PIKE_NAME encyption.


InheritState

inherit Cipher::State : State


Methodset_decrypt_key

Stateset_decrypt_key(string(8bit)key, void|intekb)

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


Methodset_encrypt_key

Stateset_encrypt_key(string(8bit)key, int|voidekb)

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.


InheritBlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.BLOWFISH.State

Description

State for BLOWFISH encyption.


InheritState

inherit Cipher::State : State

Class Nettle.BlockCipher

Description

Base class for all block ciphers.

Extends the BufferedCipher class with various operating modes.


InheritBlockCipher

inherit __builtin.Nettle.BlockCipher : BlockCipher


InheritBufferedCipher

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


InheritBufferedCipher

inherit BufferedCipher : BufferedCipher

Class Nettle.BlockCipher.ABC.State


InheritState

inherit Cipher::State : State


Methodblock_size

int(1..)block_size()

Description

Returns the block size of the encapsulated cipher.


Methodcreate

Nettle.BlockCipher.ABC.StateNettle.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.


Methodcrypt

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.


Methodiv_size

int(1..)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_iv

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritBufferedCipher

inherit BufferedCipher : BufferedCipher

Class Nettle.BlockCipher.CBC.State


InheritState

inherit Cipher::State : State


Methodblock_size

int(1..)block_size()

Description

Returns the block size of the encapsulated cipher.


Methodcreate

Nettle.BlockCipher.CBC.StateNettle.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.


Methodcrypt

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.


Methodiv_size

int(1..)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_iv

this_programset_iv(string(8bit)iv)

Description

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritBufferedCipher

inherit BufferedCipher : BufferedCipher


Method`()

State res = Nettle.BlockCipher()()

Returns

Returns a new State object.


Methodname

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.


InheritState

inherit BufferedCipher::State : State


Variableobj

object Nettle.BlockCipher.CFB.State.obj

Note

Read only


Methodblock_size

int(1..)block_size()

Description

Returns the block size of the encapsulated cipher.


Methodcreate

Nettle.BlockCipher.CFB.StateNettle.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.


Methodcrypt

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


Methodiv_size

int(1..)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

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


Methodset_iv

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritCipher

inherit __builtin.Nettle.Cipher : Cipher


Method`()

State res = Nettle.BlockCipher()()

Returns

Returns a new State object.


Methodname

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.


InheritState

inherit Cipher::State : State


Variableobj

object Nettle.BlockCipher.CTR.State.obj

Note

Read only


Methodblock_size

int(1..)block_size()

Description

Returns the block size of the encapsulated cipher.


Methodcreate

Nettle.BlockCipher.CTR.StateNettle.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.


Methodcrypt

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


Methodiv_size

int(1..)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

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


Methodset_iv

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritBufferedCipher

inherit BufferedCipher : BufferedCipher

Class Nettle.BlockCipher.IGE.State


InheritState

inherit Cipher::State : State


Methodblock_size

int(1..)block_size()

Description

Returns the block size of the encapsulated cipher.


Methodcreate

Nettle.BlockCipher.IGE.StateNettle.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.


Methodcrypt

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.


Methodiv_size

int(1..)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_iv

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritBufferedCipher

inherit BufferedCipher : BufferedCipher


Method`()

State res = Nettle.BlockCipher()()

Returns

Returns a new State object.


Methodname

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.


InheritState

inherit BufferedCipher::State : State


Variableobj

object Nettle.BlockCipher.OFB.State.obj

Note

Read only


Methodblock_size

int(1..)block_size()

Description

Returns the block size of the encapsulated cipher.


Methodcreate

Nettle.BlockCipher.OFB.StateNettle.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.


Methodcrypt

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


Methodiv_size

int(1..)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

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


Methodset_iv

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritCBC

inherit CBC : CBC

Class Nettle.BlockCipher.PCBC.State


InheritState

inherit CBC::State : State


Methodcrypt

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.


Methodname

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


InheritBlockCipher

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


InheritAEAD

inherit __builtin.Nettle.AEAD : AEAD


InheritCTR

inherit BlockCipher::CTR : CTR


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


Methodname

string(8bit)name()

Description

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

Class Nettle.BlockCipher16.CCM.State


InheritState

inherit CTR::State : State


Methodcreate

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


Methoddigest

string(8bit)digest(int(4..16)|voidbytes)

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


Methoddigest_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


InheritCCM

inherit CCM : CCM


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


Methodname

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.


InheritMAC

inherit __builtin.Nettle.MAC : MAC


Methodname

string(8bit)name()

Description

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

Class Nettle.BlockCipher16.CMAC.State


InheritState

inherit Cipher::State : State


Methodcreate

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritAEAD

inherit __builtin.Nettle.AEAD : AEAD


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


Methodname

string(8bit)name()

Description

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

Class Nettle.BlockCipher16.EAX.State


InheritState

inherit AEAD::State : State


Methodblock_size

int(16)block_size()

Description

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


Methodcreate

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


Methoddigest

string(8bit)digest(int(1..16)|voidbytes)

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


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


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


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritAEAD

inherit __builtin.Nettle.AEAD : AEAD


Methodblock_size

int(16)block_size()

Description

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


Methoddigest_size

int(16)digest_size()

Description

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


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


Methodname

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.


InheritState

inherit AEAD::State : State


Methodblock_size

int(16)block_size()

Description

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


Methodcreate

Nettle.BlockCipher16.GCM.StateNettle.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.


Methodcrypt

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


Methoddigest

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


Methoddigest_size

int(16)digest_size()

Description

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


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


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

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


Methodset_iv

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


Methodsubstate_factory

Cipher::Statesubstate_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.


Methodupdate

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


InheritAE

inherit __builtin.Nettle.AE : AE


ConstantDEFAULT_IV

constant Nettle.BlockCipher16.KW.DEFAULT_IV

Description

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


Methodname

string(8bit)name()

Description

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

Class Nettle.BlockCipher16.KW.State


InheritState

inherit Cipher::State : State


Methodblock_size

int(8)block_size()

Description

Returns the block size for this AEAD mode.


Methodcreate

Nettle.BlockCipher16.KW.StateNettle.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.


Methodcrypt

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.


Methoddigest

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


Methodiv_size

int(8)iv_size()

Description

Returns the size for the initialization vector


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

Description

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


Methodset_iv

this_programset_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


Methodsubstate_factory

Cipher::Statesubstate_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


InheritAEAD

inherit __builtin.Nettle.AEAD : AEAD


Methoddigest_size

int(16)digest_size()

Description

Default digest size (16).


Methodname

string(8bit)name()

Description

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

Class Nettle.BlockCipher16.OCB.State


InheritState

inherit AEAD::State : State


Methodblock_size

int(16)block_size()

Description

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


Methodcreate

Nettle.BlockCipher16.OCB.StateNettle.BlockCipher16.OCB.State()


Methoddigest

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


Methoddigest_size

int(1..16)digest_size()

Description

Digest size as set by set_iv().

See also

digest(), OCB::digest_size()


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


Methodkey_size

int(1..)key_size()

Description

Returns the key size of the encapsulated cipher.


Methodname

string(8bit)name()

Description

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, int|voidflags)

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


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, int|voidflags)

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


Methodsubstate_factory

Cipher::Statesubstate_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.


InheritCipher

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


InheritCipher

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


Methodblock_size

int(1..)block_size()

Description

Get the block size of the contained block crypto.


Methodcreate

Nettle.BufferedCipher.Buffer.StateNettle.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.


Methodcrypt

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.


Methodiv_size

int(0..)iv_size()

Description

Get the iv size of the contained block crypto.


Methodkey_size

int(1..)key_size()

Description

Get the key size of the contained block crypto.


Methodname

string(8bit)name()

Description

Returns the name of the wrapped cipher with ".Buffer" appended.


Methodpad

string(8bit)pad(void|intmethod)

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


Methodset_decrypt_key

this_programset_decrypt_key(string(8bit)key, void|intflags)

Description

Set the decryption key. The key memory will be cleared before released.

Note

As a side-effect any buffered data will be cleared.


Methodset_encrypt_key

this_programset_encrypt_key(string(8bit)key, void|intflags)

Description

Set the encryption key. The key memory will be cleared before released.

Note

As a side-effect any buffered data will be cleared.


Methodset_iv

this_programset_iv(string(8bit)iv)

Description

Set the initialization vector to iv.


Methodsubstate_factory

Cipher::Statesubstate_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.


Methodunpad

string(8bit)unpad(string(8bit)data, void|intmethod)

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.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.CAMELLIA.State

Description

State for CAMELLIA encyption.


InheritState

inherit Cipher::State : State

Class Nettle.CAST128

Description

Implementation of the CAST128 cipher.


InheritBlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.CAST128.State

Description

State for CAST128 encyption.


InheritState

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.


InheritBlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.CHACHA.State

Description

State for CHACHA encyption.


InheritState

inherit Cipher::State : State


Methodcrypt

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

Description

Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

Parameter data

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.


Methodset_iv

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


InheritAEAD

inherit AEAD : AEAD

Class Nettle.CHACHA_POLY1305.State

Description

State for CHACHA_POLY1305 encyption.


InheritState

inherit AEAD::State : State

Class Nettle.Cipher

Description

Represents information about a cipher algorithm, such as name, key size, and block size.


InheritCipher

inherit __builtin.Nettle.Cipher : Cipher


Methodblock_size

int(1..)block_size()

Returns

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


Methodkey_size

int(1..)key_size()

Returns

The recommended key size for the cipher.


Methodname

string(8bit)name()

Returns

A human readable name for the algorithm.

Class Nettle.Cipher.State

Description

Base class for cipher contexts.


InheritState

inherit Cipher::State : State


Methodblock_size

int(1..)block_size()

Returns

The block size for this cipher.

Note

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


Methodcrypt

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

Description

Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

Parameter data

For block ciphers, data must be an integral number of blocks.

Returns

The encrypted or decrypted data.


Methodkey_size

int(1..)key_size()

Returns

The actual key size for this cipher.


Methodmake_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


Methodname

string(8bit)name()

Returns

A human readable name for the algorithm.

Note

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


Methodset_decrypt_key

Stateset_decrypt_key(string(8bit)key, void|intflags)

Description

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

See also

set_encrypt_key, crypt


Methodset_encrypt_key

Stateset_encrypt_key(string(8bit)key, void|intflags)

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


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


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


Methodname

string(7bit)name()

Description

Returns the name of the curve.


Methodnew_scalar

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


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


Methodsize

intsize()

Returns

Returns the size in bits for a single coordinate on the curve.

Class Nettle.Curve25519.EdDSA

Description

Edwards Curve Digital Signing Algorithm


InheritPoint

inherit Point : Point

Description

This point represents the public key.


InheritSign

inherit __builtin.Nettle.Sign : Sign


Methodgenerate_key

voidgenerate_key()

Description

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


Methodget_curve

Curve25519get_curve()

Description

Get the elliptic curve that is in use.


Methodget_private_key

string(8bit)get_private_key()

Description

Get the private key.


Methodget_x

string(8bit)get_x()

Description

Get the x coordinate of the public key.


Methodjose_name

string(7bit)jose_name()

Description

Returns the string "Ed25519".


Methodname

string(7bit)name()

Description

Returns the string "EdDSA".


Methodraw_sign

string(8bit)raw_sign(string(8bit)message)

Description

Sign the message.


Methodraw_verify

boolraw_verify(string(8bit)message, string(8bit)signature)

Description

Verify the signature against the message.


Methodset_private_key

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


Methodset_public_key

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


Methodset_random

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


InheritPoint

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


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


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


Methodname

string(7bit)name()

Description

Returns the name of the curve.


Methodnew_scalar

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


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


Methodsize

intsize()

Returns

Returns the size in bits for a single coordinate on the curve.

Class Nettle.Curve448.EdDSA

Description

Edwards Curve Digital Signing Algorithm


InheritPoint

inherit Point : Point

Description

This point represents the public key.


InheritSign

inherit __builtin.Nettle.Sign : Sign


Methodgenerate_key

voidgenerate_key()

Description

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


Methodget_curve

Curve448get_curve()

Description

Get the elliptic curve that is in use.


Methodget_private_key

string(8bit)get_private_key()

Description

Get the private key.


Methodget_x

string(8bit)get_x()

Description

Get the x coordinate of the public key.


Methodjose_name

string(7bit)jose_name()

Description

Returns the string "Ed448".


Methodname

string(7bit)name()

Description

Returns the string "EdDSA".


Methodraw_sign

string(8bit)raw_sign(string(8bit)message)

Description

Sign the message.


Methodraw_verify

boolraw_verify(string(8bit)message, string(8bit)signature)

Description

Verify the signature against the message.


Methodset_private_key

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


Methodset_public_key

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


Methodset_random

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


InheritPoint

inherit ECC_Curve::Point : Point

Class Nettle.DES

Description

Implementation of the Data Encryption Standard (DES) crypto algorithm.


InheritBlockCipher

inherit BlockCipher : BlockCipher


Methodfix_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


InheritState

inherit Cipher::State : State


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


InheritBlockCipher

inherit BlockCipher : BlockCipher


Methodfix_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


InheritState

inherit Cipher::State : State

Class Nettle.DH_Params

Description

Diffie-Hellman Parameters.


Variableg

Gmp.mpz Nettle.DH_Params.g

Description

Generator.


Variablep

Gmp.mpz Nettle.DH_Params.p

Description

Prime.


Variableq

Gmp.mpz Nettle.DH_Params.q

Description

Order.


Methodgenerate

voidgenerate(intp_bits, intq_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.


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

The generated public key.

Gmp.mpz1

The corresponding private key.

Class Nettle.ECC_Curve

Description

Elliptic Curve Definition


InheritECC_Curve

inherit __builtin.Nettle.ECC_Curve : ECC_Curve


InheritECDSA

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.


Methodcreate

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

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


Methodname

string(7bit)name()

Description

Returns the name of the curve.

See also

jose_name()


Methodnew_scalar

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


Methodpoint_mul

Pointpoint_mul(Gmp.mpz|intx, Gmp.mpz|inty, Gmp.mpz|intscalar)

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.


Methodraw_sign

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

Description

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


Methodraw_verify

boolraw_verify(string(8bit)digest, Gmp.mpzr, Gmp.mpzs)

Description

Verify the signature r, s against the message digest digest.


Methodsize

intsize()

Returns

Returns the size in bits for a single coordinate on the curve.

Class Nettle.ECC_Curve.ECDSA

Description

Elliptic Curve Digital Signing Algorithm


InheritPoint

inherit Point : Point

Description

This point represents the public key.


InheritSign

inherit __builtin.Nettle.Sign : Sign


Methodgenerate_key

voidgenerate_key()

Description

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


Methodget_curve

ECC_Curveget_curve()

Description

Get the elliptic curve that is in use.


Methodget_private_key

Gmp.mpzget_private_key()

Description

Get the private key.


Methodget_x

Gmp.mpzget_x()

Description

Get the x coordinate of the public key.

See also

get_y()


Methodget_y

Gmp.mpzget_y()

Description

Get the y coordinate of the public key.

See also

get_x()


Methodname

string(7bit)name()

Description

Returns the string "ECDSA" followed by the parenthesized name of the curve.


Methodraw_sign

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

Description

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


Methodraw_verify

boolraw_verify(string(8bit)digest, Gmp.mpzr, Gmp.mpzs)

Description

Verify the signature r, s against the message digest digest.


Methodset_private_key

voidset_private_key(Gmp.mpz|intk)

Description

Set the private key (and corresponding public key).

Note

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


Methodset_public_key

voidset_public_key(Gmp.mpz|intx, Gmp.mpz|inty)

Description

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

Note

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


Methodset_random

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


InheritPoint

inherit ECC_Curve::Point : Point


Method_equal

boolequal(Nettle.ECC_Curve.Pointfrom, mixedx)

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.


Methodget_curve

ECC_Curveget_curve()

Description

Get the elliptic curve that is in use.


Methodget_x

Gmp.mpzget_x()

Description

Get the x coordinate of the point.

See also

get_y()


Methodget_y

Gmp.mpzget_y()

Description

Get the y coordinate of the point.

See also

get_x()


Methodname

string(7bit)name()

Description

Returns the string "Point" followed by the parenthesized name of the curve.


Methodset

voidset(Gmp.mpz|intx, Gmp.mpz|inty)

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.


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


Methodreseed

voidreseed(string(8bit)data)

Description

Updated the internal key with the provided additional entropy.

Class Nettle.GOST94

Description

Implementation of the GOST94 hash algorithm.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.GOST94.HMAC.GOST94Nettle.GOST94.HMAC.GOST94(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.GOST94CP.HMAC.GOST94CPNettle.GOST94CP.HMAC.GOST94CP(string(8bit)passwd, void|intb)

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.


InheritHash

inherit __builtin.Nettle.Hash : Hash


Methodballoon

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


Methodblock_size

int(1..)block_size()

Description

Returns the internal block size of the hash algorithm.


Methodcrypt_hash

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

Description

Password hashing function in crypt_md5()-style.

Implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

This is the algorithm used by crypt(2) in methods $5$ (SHA256) and $6$ (SHA512).

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


Methodcrypt_hash_pike

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

Description

Password hashing function in crypt_md5()-style.

Almost implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

This function is provided for compatibility with hashes generated by Pike 8.0.1876 and earlier.

It differs from crypt_hash() for passwords that have a length that is a power of 2 (phase 11).

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


Methoddigest_size

int(0..)digest_size()

Description

Returns the size of a hash digest.


Methodhash

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


Methodhash

string(8bit)hash(Stdio.File|Stdio.Buffer|String.Buffer|System.Memorysource, 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().


Methodname

string(8bit)name()

Description

Returns a human readable name for the algorithm.

Class Nettle.Hash.State

Description

Base class for hashing contexts.


InheritState

inherit Hash::State : State


Methoddigest

string(8bit)digest(int(0..)|voidlength)

Description

Generates a digest, and resets the hashing contents.

Parameter length

If the length argument is provided, the digest is truncated to the given length.

Returns

The digest.


Methodupdate

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


InheritBlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.IDEA.State

Description

State for IDEA encyption.


InheritState

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.


InheritMAC

inherit __builtin.Nettle.MAC : MAC


Methodblock_size

int(0..)block_size()

Description

Returns the internal block size of the MAC algorithm.


Methoddigest_size

int(0..)digest_size()

Description

Returns the size of a MAC digest.


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


Methodkey_size

int(0..)key_size()

Description

Returns the recommended size for the secret key for the MAC algorithm.


Methodname

string(8bit)name()

Description

Returns a human readable name for the algorithm.

Class Nettle.MAC.State

Description

Base class for MAC contexts.


InheritState

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


Methodcreate

Nettle.MAC.StateNettle.MAC.State(string(8bit)key)

Description

Initialize the MAC with a password.

It also resets any iv/nonce to it's default.


Methoddigest

string(8bit)digest(int|voidlength)

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.


Methodset_iv

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


Methodupdate

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


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.MD2.HMAC.MD2Nettle.MD2.HMAC.MD2(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.MD4.HMAC.MD4Nettle.MD4.HMAC.MD4(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.MD5.HMAC.MD5Nettle.MD5.HMAC.MD5(string(8bit)passwd, void|intb)

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.


InheritMAC

inherit MAC : MAC

Class Nettle.POLY1305_AES.State

Description

State for POLY1305_AES macing.


InheritState

inherit MAC::State : State

Class Nettle.RIPEMD160

Description

Implementation of the RIPEMD160 hash algorithm.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.RIPEMD160.HMAC.RIPEMD160Nettle.RIPEMD160.HMAC.RIPEMD160(string(8bit)passwd, void|intb)

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.


InheritBlockCipher

inherit BlockCipher : BlockCipher

Class Nettle.SALSA20.State

Description

State for SALSA20 encyption.


InheritState

inherit Cipher::State : State


Methodset_iv

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


InheritSALSA20

inherit SALSA20 : SALSA20

Class Nettle.SERPENT

Description

Implementation of the SERPENT cipher.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.SERPENT.State

Description

State for SERPENT encyption.


InheritState

inherit Cipher::State : State

Class Nettle.SHA1

Description

Implementation of the SHA1 hash algorithm.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA1.HMAC.SHA1Nettle.SHA1.HMAC.SHA1(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA224.HMAC.SHA224Nettle.SHA224.HMAC.SHA224(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA256.HMAC.SHA256Nettle.SHA256.HMAC.SHA256(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA384.HMAC.SHA384Nettle.SHA384.HMAC.SHA384(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA3_224.HMAC.SHA3_224Nettle.SHA3_224.HMAC.SHA3_224(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA3_256.HMAC.SHA3_256Nettle.SHA3_256.HMAC.SHA3_256(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA3_384.HMAC.SHA3_384Nettle.SHA3_384.HMAC.SHA3_384(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA3_512.HMAC.SHA3_512Nettle.SHA3_512.HMAC.SHA3_512(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA512.HMAC.SHA512Nettle.SHA512.HMAC.SHA512(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA512_224.HMAC.SHA512_224Nettle.SHA512_224.HMAC.SHA512_224(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SHA512_256.HMAC.SHA512_256Nettle.SHA512_256.HMAC.SHA512_256(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.SM3.HMAC.SM3Nettle.SM3.HMAC.SM3(string(8bit)passwd, void|intb)

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.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.SM4.State

Description

State for SM4 encyption.


InheritState

inherit Cipher::State : State

Class Nettle.STREEBOG256

Description

Implementation of the STREEBOG256 hash algorithm.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.STREEBOG256.HMAC.STREEBOG256Nettle.STREEBOG256.HMAC.STREEBOG256(string(8bit)passwd, void|intb)

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.


InheritHash

inherit Hash : Hash


Methodshake

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.


InheritState

inherit Hash::State : State


Methodshake

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.


Methodcreate

Nettle.STREEBOG512.HMAC.STREEBOG512Nettle.STREEBOG512.HMAC.STREEBOG512(string(8bit)passwd, void|intb)

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.


InheritBlockCipher16

inherit BlockCipher16 : BlockCipher16

Class Nettle.Twofish.State

Description

State for Twofish encyption.


InheritState

inherit Cipher::State : State

Class Nettle.UMAC128_AES

Description

Implementation of the UMAC128_AES MAC algorithm.


InheritMAC

inherit MAC : MAC

Class Nettle.UMAC128_AES.State

Description

State for UMAC128_AES macing.


InheritState

inherit MAC::State : State

Class Nettle.UMAC32_AES

Description

Implementation of the UMAC32_AES MAC algorithm.


InheritMAC

inherit MAC : MAC

Class Nettle.UMAC32_AES.State

Description

State for UMAC32_AES macing.


InheritState

inherit MAC::State : State

Class Nettle.UMAC64_AES

Description

Implementation of the UMAC64_AES MAC algorithm.


InheritMAC

inherit MAC : MAC

Class Nettle.UMAC64_AES.State

Description

State for UMAC64_AES macing.


InheritState

inherit MAC::State : State

Class Nettle.UMAC96_AES

Description

Implementation of the UMAC96_AES MAC algorithm.


InheritMAC

inherit MAC : MAC

Class Nettle.UMAC96_AES.State

Description

State for UMAC96_AES macing.


InheritState

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.


Methodcreate

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


Methodforce_reseed

voidforce_reseed()

Description

By calling this function entropy is moved from the slow pool to the fast pool. Read more about Yarrow before using this.


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


Methodis_seeded

boolis_seeded()

Description

Returns 1 if the random generator is seeded and ready to generator output. 0 otherwise.

See also

seed


Methodmin_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


Methodneeded_sources

int(0..)needed_sources()

Description

The number of sources that must reach the threshold before a slow reseed will happen.


Methodrandom_string

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

Description

Returns a pseudo-random string of the requested length.


Methodseed

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


Methodupdate

boolupdate(string(8bit)data, intsource, intentropy)

Description

Inject additional entropy into the random number generator.

See also

create