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

Description

Returns the string "DSA".

Class Crypto.DSA.State

Annotations

@Pike.Annotations.Implements(Crypto.Sign.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, __builtin.Nettle.Hashh)

Description

Makes a DSA hash of the message msg.

---

Methodname

string(7bit)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, __builtin.Nettle.Hashh)

Description

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

---

Methodpkcs_signature_algorithm_id

Sequence|zeropkcs_signature_algorithm_id(__builtin.Nettle.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, __builtin.Nettle.Hashh, string(8bit)sign)

Description

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

---

Methodpublic_key_equal

boolpublic_key_equal(objectother)

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.

Note

Note this encoding is NOT suitable for encoding numeric quantities where initial zeroes are significant (ie it is NOT suitable for eg PIN-numbers).

Note

This module implements an API that is similar to (but NOT compatible with) the generic Crypto.Cipher API.

---

Methoddecrypt

int(0..)decrypt(string(7bit)c)

Description

Decode a koremutake string into an integer.

Note

Returns an integer. This is not compatible with the Crypto.Cipher API.

---

Methodencrypt

string(7bit)encrypt(int(0..)m)

Description

Encode an integer as a koremutake string.

Note

Encrypts an integer. This is not compatible with the Crypto.Cipher API.

Class Crypto.Koremutake.`()

---

Methodcrypt

int(0..)|string(7bit)crypt(int(0..)|string(7bit)x)

Note

Encrypts or returns an integer. This is not compatible with the Crypto.Cipher API.

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