21. Cryptography

21.1. Password hashing


Method crypt

string crypt(string password)
bool crypt(string typed_password, string crypted_password)

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.

Note

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

Module Crypto.Password

Description

Password handling.

This module handles generation and verification of password hashes.

See also

verify(), hash(), crypt()


Method hash

string hash(string password, string|void scheme, int|void rounds)

Description

Generate a hash of password suitable for verify().

Parameter password

Password to hash.

Parameter scheme

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

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

Supported schemes are:

Crypt(3C)-style:

UNDEFINED

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

"crypt"
"{crypt}"
"6"

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

"$6$"
"5"

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

"$5$"
"1"

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

"$1$"
""

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

LDAP (RFC2307)-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.HashInfo()->crypt_hash()


Method verify

int verify(string password, string hash)

Description

Verify a password against a hash.

This function attempts to support most common password hashing schemes. The hash can be on any of the following formats.

LDAP-style (RFC2307) hashes:

"{SHA}XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

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

"{SSHA}XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

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

"{MD5}XXXXXXXXXXXXXXXXXXXXXXXX"

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

"{SMD5}XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

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

"{CRYPT}XXXXXXXXXXXXX"

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

Crypt-style hashes:

"$6$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

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

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

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

"$5$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"

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

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

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

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

"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 might 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 wraps GSS-API routines might throw GSSAPI.Error, and by default they do for all such errors. Only in some special cases do they return when a GSS-API error has happened, and that is noted in the documentation.


Constant INITIATE
Constant ACCEPT
Constant BOTH

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

Description

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

INITIATE

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

ACCEPT

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

BOTH

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


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

constant GSSAPI.DELEG_FLAG
constant GSSAPI.MUTUAL_FLAG
constant GSSAPI.REPLAY_FLAG
constant GSSAPI.SEQUENCE_FLAG
constant GSSAPI.CONF_FLAG
constant GSSAPI.INTEG_FLAG
constant GSSAPI.ANON_FLAG
constant GSSAPI.PROT_READY_FLAG
constant 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 sections 1.1.1.3 and 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 and GSSAPI.Context.import. See RFC 2743 section 1.2.10.


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

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

Description

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

Brief descriptions of the flags:

GSSAPI.BAD_BINDINGS

Channel binding mismatch.

GSSAPI.BAD_MECH

Unsupported mechanism requested.

GSSAPI.BAD_NAME

Invalid name provided.

GSSAPI.BAD_NAMETYPE

Name of unsupported type provided.

GSSAPI.BAD_STATUS

Invalid input status selector.

GSSAPI.BAD_MIC

Token had invalid integrity check.

GSSAPI.CONTEXT_EXPIRED

Specified security context expired.

GSSAPI.CREDENTIALS_EXPIRED

Expired credentials detected.

GSSAPI.DEFECTIVE_CREDENTIAL

Defective credential detected.

GSSAPI.DEFECTIVE_TOKEN

Defective token detected.

GSSAPI.FAILURE

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

GSSAPI.NO_CONTEXT

No valid security context specified.

GSSAPI.NO_CRED

No valid credentials provided.

GSSAPI.BAD_QOP

Unsupported QOP value.

GSSAPI.UNAUTHORIZED

Operation unauthorized.

GSSAPI.UNAVAILABLE

Operation unavailable.

GSSAPI.DUPLICATE_ELEMENT

Duplicate credential element requested.

GSSAPI.NAME_NOT_MN

Name contains multi-mechanism elements.


Constant CONTINUE_NEEDED
Constant DUPLICATE_TOKEN
Constant OLD_TOKEN
Constant UNSEQ_TOKEN
Constant GAP_TOKEN

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

Description

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

Brief descriptions of the flags:

GSSAPI.CONTINUE_NEEDED

Continuation call to routine required.

GSSAPI.DUPLICATE_TOKEN

Duplicate per-message token detected.

GSSAPI.OLD_TOKEN

Timed-out per-message token detected.

GSSAPI.UNSEQ_TOKEN

Reordered (early) per-message token detected.

GSSAPI.GAP_TOKEN

Skipped predecessor token(s) detected.


Constant ERROR_MASK

constant GSSAPI.ERROR_MASK

Description

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


Constant INFO_MASK

constant GSSAPI.INFO_MASK

Description

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


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

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

Description

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

NT_HOSTBASED_SERVICE

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

NT_USER_NAME

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

NT_MACHINE_UID_NAME

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

NT_STRING_UID_NAME

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

NT_ANONYMOUS

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

NT_EXPORT_NAME

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

KRB5_NT_PRINCIPAL_NAME

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


Method describe_services

string describe_services(int services)

Description

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

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


Method indicate_mechs

multiset(string) indicate_mechs()

Description

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

This wraps GSS_Indicate_mechs according to RFC 2743 section 2.4.2.


Method major_status_messages

array(string) major_status_messages(int major_status)

Description

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

This wraps GSS_Display_status according to RFC 2743 section 2.4.1.


Method minor_status_messages

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

Description

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

This wraps GSS_Display_status according to RFC 2743 section 2.4.1.

Parameter minor_status

The mechanism-specific minor status.

Parameter mech

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


Method names_for_mech

multiset(string) names_for_mech(string mech)

Description

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

This wraps GSS_Inquire_names_for_mech according to RFC 2743 section 2.4.12.

Class GSSAPI.AcceptContext

Description

Variant of Context which is used on the acceptor side.


Inherit Context

inherit Context : Context


Method accept

string accept(string remote_token)

Description

Accepts a remotely initiated security context.

This wraps GSS_Accept_sec_context according to RFC 2743 section 2.2.2.

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

Parameter remote_token

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

Returns

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

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

Note

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


Method create

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

Description

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

Parameter cred

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

Parameter required_services

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

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

Note

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


Method delegated_cred

Cred delegated_cred()

Description

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

Class GSSAPI.Context

Description

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

Note

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


Method create

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

Description

Creates a context by importing an inter-process token.

This wraps GSS_Import_sec_context according to RFC 2743 section 2.2.9.

Parameter interprocess_token

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

Parameter required_services

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

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

Note

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


Method delete

void delete()

Description

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

This wraps GSS_Delete_sec_context according to RFC 2743 section 2.2.3.

Note

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

Note

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


Method export

string export()

Description

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

This wraps GSS_Export_sec_context according to RFC 2743 section 2.2.8.

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

This operation frees the context in this object.


Method get_mic

string get_mic(string message, void|int qop)

Description

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

This wraps GSS_GetMIC according to RFC 2743 section 2.3.1.

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

Parameter message

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

Parameter qop

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

Zero or left out means use the default method.


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

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

Description

Functions to query various properties about the context.

These wrap GSS_Inquire_context according to RFC 2743 section 2.2.6.

is_established()

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

services()

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

See also GSSAPI.describe_services.

locally_initiated()

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

source_name()

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

target_name()

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

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

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

lifetime()

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

mech()

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

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


Method last_confidential

int last_confidential()

Description

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


Method last_major_status
Method last_minor_status

int last_major_status()
int last_minor_status()

Description

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


Method last_qop

int last_qop()

Description

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


Method process_token

void process_token(string remote_token)

Description

Passes the given remote_token to the mechanism.

This wraps GSS_Process_context_token according to RFC 2743 section 2.2.4.

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

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

Note

This function might change context state.

Note

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


Method required_services

int required_services(void|int services)

Description

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

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

Parameter services

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

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

GSSAPI.PROT_READY_FLAG is ignored in this parameter.

Returns

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

See also

GSSAPI.describe_services


Method unwrap

string unwrap(string message, void|int accept_encrypted_only)

Description

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

This wraps GSS_Unwrap according to RFC 2743 section 2.3.4.

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

Parameter message

The message to be unwrapped.

Parameter accept_encrypted_only

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

Returns

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

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

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

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

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

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

Throws

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

Note

This function sets the value returned by last_confidential and last_qop.

Note

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


Method verify_mic

int verify_mic(string message, string mic)

Description

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

This wraps GSS_VerifyMIC according to RFC 2743 section 2.3.2.

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

Returns

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

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

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

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

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

Throws

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

Note

This function sets the value returned by last_qop.

Note

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


Method wrap

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

Description

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

This wraps GSS_Wrap according to RFC 2743 section 2.3.3.

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

Parameter message

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

Parameter encrypt

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

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

Parameter qop

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

Zero or left out means use the default method.

Note

This function sets the value returned by last_confidential.

See also

wrap_size_limit


Method wrap_size_limit

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

Description

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

This wraps GSS_Wrap_size_limit according to RFC 2743 section 2.2.7.

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

Class GSSAPI.Cred

Description

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

Note

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


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

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

Description

Functions to query various properties about the credentials.

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

Parameter mech

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

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

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

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

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

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

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

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

Returns zero if some part of the credentials has expired.

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

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

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

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

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

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

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

Note

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


Method acquire

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

Description

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

This wraps GSS_Acquire_cred according to RFC 2743 section 2.1.1.

Parameter name

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

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

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

Parameter cred_usage

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

Parameter desired_mechs

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

It is an error to pass an empty multiset.

Parameter desired_time

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

Note

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


Method add

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

Description

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

This wraps GSS_Add_cred according to RFC 2743 section 2.1.4.

Parameter name

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

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

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

Parameter cred_usage

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

Parameter desired_mech

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

Parameter desired_time

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

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

Note

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


Method release

void release()

Description

Frees the resources for the credential.

This wraps GSS_Release_cred according to RFC 2743 section 2.1.2.

Note

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

Class GSSAPI.Error

Description

Error object used for GSS-API errors.


Inherit Error.Generic

inherit Error.Generic : Error.Generic


Constant is_gssapi_error
Constant error_type

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

Description

Object recognition constants.


Variable major_status

int GSSAPI.Error.major_status

Description

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

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

See also

major_status_messages


Variable minor_status

int GSSAPI.Error.minor_status

Description

The minor status code specific for the mechanism.

See also

minor_status_messages, minor_status_mech


Method create

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

Parameter major

Initial value for major_status.

Parameter minor

Initial value for minor_status.

Parameter mech

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

Parameter message

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

Parameter backtrace

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


Method major_status_messages

array(string) major_status_messages()

Description

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


Method minor_status_mech

string minor_status_mech()

Description

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


Method minor_status_messages

array(string) minor_status_messages()

Description

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

Class GSSAPI.InitContext

Description

Variant of Context which is used on the initiator side.


Inherit Context

inherit Context : Context


Method create

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

Description

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

Parameter cred

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

Parameter target_name

The name of the target.

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

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

Parameter mech

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

Parameter required_services

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

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

Parameter desired_services

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

GSSAPI.PROT_READY_FLAG is ignored in this parameter.

Parameter desired_time

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

Note

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


Method init

string init(void|string remote_token)

Description

Initiates a security context to send to a remote peer.

This wraps GSS_Init_sec_context according to RFC 2743 section 2.2.1.

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

Parameter remote_token

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

Returns

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

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

Note

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

Class GSSAPI.MissingServicesError

Description

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


Inherit Error.Generic

inherit Error.Generic : Error.Generic


Constant is_gssapi_missing_services_error
Constant error_type

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

Description

Object recognition constants.


Variable services

int GSSAPI.MissingServicesError.services

Description

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

See also

GSSAPI.describe_services


Method create

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

Parameter missing_services

Initial value for services.

Class GSSAPI.Name

Description

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


Method __hash

int hash_value( GSSAPI.Name arg )

Description

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

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


Method `==

int res = GSSAPI.Name() == other

Description

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

This wraps GSS_Compare_name according to RFC 2743 section 2.4.3.

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

Throws

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


Method canonicalize

Name canonicalize(string mech)

Description

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

This wraps GSS_Canonicalize_name according to RFC 2743 section 2.4.14.

Note

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


Method create

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

Description

This wraps GSS_Import_name according to RFC 2743 section 2.4.5.

Parameter name

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

Parameter name_type

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

Note

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


Method display_name
Method display_name_type

string display_name()
string display_name_type()

Description

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

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

This wraps GSS_Display_name according to RFC 2743 section 2.4.4.

See also

The GSSAPI.NT_* constants.


Method export

string export(void|string mech)

Description

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

This wraps GSS_Export_name according to RFC 2743 section 2.4.15.

Note

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


Method mechs

multiset(string) mechs()

Description

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

This wraps GSS_Inquire_mechs_for_name according to RFC 2743 section 2.4.13.

Note

Some older GSS-API v2 implementations lack this funcion.

21.3. Cryptographic primitives

Module Crypto

Description

Various cryptographic classes and functions.

Hash functions These are based on the Hash API; MD2, MD4, MD5, SHA1, SHA256.

Stream cipher functions These are based on the Cipher API; AES, Arcfour, Blowfish, CAST, DES, DES3, IDEA, Serpent, Twofish. The Substitution program is compatible with the CipherState. Also conforming to the API are the helper programs Buffer, CBC and Pipe.

As the cryptographic services offered from this module isn't necessarily used for security applications, none of the strings inputted or outputted are marked as secure. This is up to the caller.

Note

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


Method make_crypt_md5

string make_crypt_md5(string password, void|string salt)

Description

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

See also

verify_crypt_md5


Method rot13

string rot13(string data)

Description

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


Method verify_crypt_md5

bool verify_crypt_md5(string password, string 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.Buffer

Description

Acts as a buffer so that data can be fed to a cipher in blocks that don't correspond to cipher block sizes.

Acts as a buffer so that data can be fed to a cipher in blocks that don't correspond to cipher block sizes.

Example

class Encrypter { protected Crypto.Buffer buffer;

void create(string key) { buffer = Crypto.Buffer(Crypto.CBC(Crypto.AES)); buffer->set_encrypt_key(key); }

string feed(string data) { return buffer->crypt(data); }

string drain() { return buffer->pad(Crypto.PAD_PKCS7); } }


Inherit Cipher

inherit Cipher : Cipher


Inherit Proxy

inherit Nettle.Proxy : Proxy


Method block_size

int block_size()

Description

Get the block size of the contained block crypto.


Method create

Crypto.Buffer Crypto.Buffer(program|object|function(:void) cipher, mixed ... args)

Description

Initialize the Proxy wrapper with a cipher algorithm. If it is a program, an object will be instantiated with args as arguments. If it is an object that doesn't conform to the cipher API, but has an LFUN::`(), that LFUN will be called. If it is a function, that function will be called with args as arguments.


Method crypt

string crypt(string data)

Description

Encrypt some data.

Adds data to be encrypted to the buffer. If there's enough data to en/decrypt a block, that will be done, and the result returned. Any uncrypted data will be left in the buffer.


Method key_size

int key_size()

Description

Get the key size of the contained block crypto.


Method name

string name()

Description

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


Method pad

string pad(void|int method)

Description

Pad and encrypt any data left in the buffer.

Parameter method

The type of padding to apply to the buffer.

Crypto.PAD_SSL
Crypto.PAD_ISO_10126
Crypto.PAD_ANSI_X923
Crypto.PAD_PKCS7
Crypto.PAD_ZERO

Defaults to Crypto.PAD_SSL for compatibility reasons.

See also

unpad()


Method set_decrypt_key

this_program set_decrypt_key(string key)

Description

Set the decryption key.

Note

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


Method set_encrypt_key

this_program set_encrypt_key(string key)

Description

Set the encryption key.

Note

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


Method set_iv

this_program set_iv(string iv)

Description

Set the initialization vector to iv.


Method unpad

string unpad(string data, void|int method)

Description

Decrypt and unpad a block of data.

This performs the reverse operation of pad().

Parameter method

The type of padding that was applied to the original buffer.

Crypto.PAD_SSL
Crypto.PAD_ISO_10126
Crypto.PAD_ANSI_X923
Crypto.PAD_PKCS7
Crypto.PAD_ZERO

Defaults to Crypto.PAD_SSL for compatibility reasons.

See also

pad()

Class Crypto.CBC

Description

Implementation of the cipher block chaining mode (CBC). Works as a wrapper for the cipher algorithm put in create.


Inherit CBC

inherit Nettle.CBC : CBC


Inherit Cipher

inherit Cipher : Cipher


Method block_size

int block_size()

Description

Reurns the block size of the encapsulated cipher.


Method create

Crypto.CBC Crypto.CBC(program|object|function(:void) cipher, mixed ... args)

Description

Initialize the CBC wrapper with a cipher algorithm. If it is a program, an object will be instantiated with args as arguments. If it is an object that doesn't conform to the cipher API, but has an LFUN::`(), that LFUN will be called. If it is a function, that function will be called with args as arguments.


Method crypt

string crypt(string data)

Description

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


Method key_size

int key_size()

Description

Returns the key size of the encapsulated cipher.


Method name

string name()

Description

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


Method set_decrypt_key

this_program set_decrypt_key(string key)

Description

Prepare the cipher and the wrapper for decrypting with the given key.


Method set_encrypt_key

this_program set_encrypt_key(string key)

Description

Prepare the cipher and the wrapper for encrypting with the given key.


Method set_iv

this_program set_iv(string iv)

Description

Set the initialization vector to iv.

Class Crypto.Cipher

Description

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


Inherit CipherInfo

inherit Nettle.CipherInfo : CipherInfo


Method `()

CipherState res = Crypto.Cipher()()

Description

Calling `() will return a Nettle.CipherState object.


Method decrypt

string decrypt(string key, string data)

Description

Works as a shortcut for obj->set_decrypt_key(key)->crypt(data)


Method encrypt

string encrypt(string key, string data)

Description

Works as a shortcut for obj->set_encrypt_key(key)->crypt(data)

Class Crypto.DSA

Description

The Digital Signature Algorithm (aka DSS, Digital Signature Standard).


Method generate_key

this_program generate_key()

Description

Generates a public/private key pair. Needs the public parameters p, q and g set, either through set_public_key or generate_parameters.


Method generate_parameters

this_program generate_parameters(int bits)

Description

Generate key parameters using nist_primes.


Method get_g

Gmp.mpz get_g()

Description

Returns the generator.


Method get_p

Gmp.mpz get_p()

Description

Returns the modulo.


Method get_q

Gmp.mpz get_q()

Description

Returns the group order.


Method get_x

Gmp.mpz get_x()

Description

Returns the private key.


Method get_y

Gmp.mpz get_y()

Description

Returns the public key.


Method hash

Gmp.mpz hash(string msg, .Hash|void h)

Description

Makes a DSA hash of the messge msg.


Method name

string name()

Description

Returns the string "DSA".


Method nist_primes

array(Gmp.mpz) nist_primes(int l)

Description

The (slow) NIST method of generating a DSA prime pair. Algorithm 4.56 of Handbook of Applied Cryptography.


Method pkcs_sign

string pkcs_sign(string msg, .Hash h)

Description

Make an SSL signatrue of message msg.


Method pkcs_verify

bool pkcs_verify(string msg, .Hash h, string s)

Description

Verify an SSL signature s of message msg.


Method public_key_equal

bool public_key_equal(.DSA dsa)

Description

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


Method raw_sign

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

Description

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


Method raw_verify

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

Description

Verify the signature r,s against the message h.


Method set_private_key

this_program set_private_key(Gmp.mpz secret)

Description

Sets the private key in this DSA object.


Method set_public_key

this_program set_public_key(Gmp.mpz p_, Gmp.mpz q_, Gmp.mpz g_, Gmp.mpz y_)

Description

Sets the public key in this DSA object.


Method set_random

this_program set_random(function(int:string) r)

Description

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


Method sign_rsaref

string sign_rsaref(string msg)

Description

Make a RSA ref signature of message msg.


Method sign_ssl

string sign_ssl(string msg)

Description

Make an SSL signatrue of message msg.


Method verify_rsaref

bool verify_rsaref(string msg, string s)

Description

Verify a RSA ref signature s of message msg.


Method verify_ssl

bool verify_ssl(string msg, string s)

Description

Verify an SSL signature s of message msg.

Class Crypto.GCMState

Description

Implementation of the Galois Counter Mode (GCM). Works as a wrapper for the cipher algorithm put in create.

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

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

Note

Wrapped ciphers MUST have a block size of 16.

Note

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

See also

CBC


Inherit GCMState

inherit Nettle.GCMState : GCMState

Class Crypto.HMAC

Description

HMAC, defined by RFC-2104


Method create

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

Parameter h

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

Parameter b

The block size of one compression block, in octets. Defaults to 64.


Method pkcs_digest

string pkcs_digest(string s)

Description

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

See also

Standards.PKCS.Signature.build_digestinfo


Method raw_hash

string raw_hash(string s)

Description

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

Class Crypto.HMAC.`()

Description

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


Method `()

string res = Crypto.HMAC.`()()()

Description

Hashes the text according to the HMAC algorithm and returns the hash value.


Method create

Crypto.HMAC.`() Crypto.HMAC.`()(string passwd)

Parameter passwd

The secret password (K).


Method digest_info

string digest_info(string text)

Description

Hashes the text according to the HMAC algorithm and returns the hash value as a PKCS-1 digestinfo block.

Class Crypto.Hash

Description

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


Inherit HashInfo

inherit Nettle.HashInfo : HashInfo


Method `()

HashState res = Crypto.Hash()()

Description

Calling `() will return a Nettle.HashState object.

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


Method cooked_get_d

string cooked_get_d()

Description

Returns the RSA private exponent (d) as a binary string, if known.


Method cooked_get_e

string cooked_get_e()

Description

Returns the RSA public exponent (e) as a binary string.


Method cooked_get_n

string cooked_get_n()

Description

Returns the RSA modulo (n) as a binary string.


Method cooked_get_p

string cooked_get_p()

Description

Returns the first RSA prime (p) as a binary string, if known.


Method cooked_get_q

string cooked_get_q()

Description

Returns the second RSA prime (q) as a binary string, if known.


Method cooked_sign

string cooked_sign(string digest)

Description

Signs digest as raw_sign and returns the signature as a byte string.


Method crypt

string crypt(string s)

Description

Encrypt or decrypt depending on set mode.

See also

set_encrypt_key, set_decrypt_key


Method decrypt

string decrypt(string s)

Description

Decrypt a message encrypted with encrypt.


Method encrypt

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

Description

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

Parameter r

Optional random function to be passed down to rsa_pad.


Method generate_key

this_program generate_key(int(128..) bits, function(int:string)|void r)

Description

Generate a valid RSA key pair with the size bits. A random function may be provided as arguemnt r, otherwise Crypto.Random.random_string will be used. Keys must be at least 128 bits.


Method get_d

Gmp.mpz get_d()

Description

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


Method get_e

Gmp.mpz get_e()

Description

Returns the RSA public exponent (e).


Method get_n

Gmp.mpz get_n()

Description

Returns the RSA modulo (n).


Method get_p

Gmp.mpz get_p()

Description

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


Method get_prime

Gmp.mpz get_prime(int bits, function(int:string) r)

Description

Generate a prime with bits number of bits using random function r.


Method get_q

Gmp.mpz get_q()

Description

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


Method name

string name()

Description

Returns the string "RSA".


Method pkcs_sign

string pkcs_sign(string message, .Hash h)

Description

Signs the message with a PKCS-1 signature using hash algorithm h. This is equivalent to I2OSP(RSASP1(OS2IP(RSAES-PKCS1-V1_5-ENCODE(message)))) in PKCS#1 v2.2.


Method pkcs_verify

bool pkcs_verify(string msg, .Hash h, string sign)

Description

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


Method public_key_equal

bool public_key_equal(this_program rsa)

Description

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


Method query_blocksize

int query_blocksize()

Description

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


Method raw_sign

Gmp.mpz raw_sign(string digest)

Description

Pads the digest with rsa_pad type 1 and signs it.


Method raw_verify

bool raw_verify(string digest, Gmp.mpz s)

Description

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

See also

rsa_pad, raw_sign


Method rsa_pad

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

Description

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

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 Crypto.Random.random_string will be used.


Method rsa_size

int(0..) rsa_size()

Description

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


Method rsa_unpad

string rsa_unpad(Gmp.mpz block, int type)

Description

Reverse the effect of rsa_pad.


Method set_decrypt_key

this_program set_decrypt_key(array(Gmp.mpz) key)

Description

Sets the public key to keyand the mod to decryption.

See also

set_encrypt_key, crypt


Method set_encrypt_key

this_program set_encrypt_key(array(Gmp.mpz) key)

Description

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

See also

set_decrypt_key, crypt


Method set_private_key

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

Description

Sets the private key.

Parameter priv

The private RSA exponent, often called d.

Parameter extra
Array
Gmp.mpz|int 0

The first prime, often called p.

Gmp.mpz|int 1

The second prime, often called q.


Method set_public_key

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

Description

Sets the public key.

Parameter modulo

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

Parameter pub

The public RSA exponent, often called e.


Method sha_sign

string sha_sign(string message, mixed|void r)

FIXME

Document this function.


Method sha_verify

int sha_verify(string message, string signature)

FIXME

Document this function.


Method sign

Gmp.mpz sign(string message, .Hash h)

Description

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


Method verify

bool verify(string msg, .Hash h, Gmp.mpz sign)

Description

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

Class Crypto.Substitution

Description

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


Method decrypt

string decrypt(string c)

Description

Decrypts the cryptogram c.


Method encrypt

string encrypt(string m)

Description

Encrypts the message m.


Method filter

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

Description

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


Method set_ACA_K1_key

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

Description

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


Method set_ACA_K2_key

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

Description

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


Method set_ACA_K3_key

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

Description

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


Method set_ACA_K4_key

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

Description

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


Method set_key

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

Description

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

Throws

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


Method set_null_chars

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

Description

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

Parameter p

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

Parameter chars

An array of one character strings.


Method set_rot_key

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

Description

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

Module Crypto.AES

Description

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

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


Inherit AES_Info

inherit Nettle.AES_Info : AES_Info


Inherit Cipher

inherit .Cipher : Cipher

Module Crypto.Arcfour

Description

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


Inherit ARCFOUR_Info

inherit Nettle.ARCFOUR_Info : ARCFOUR_Info


Inherit Cipher

inherit .Cipher : Cipher

Module Crypto.Blowfish

Description

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


Inherit BLOWFISH_Info

inherit Nettle.BLOWFISH_Info : BLOWFISH_Info


Inherit Cipher

inherit .Cipher : Cipher

Module Crypto.CAST

Description

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


Inherit CAST128_Info

inherit Nettle.CAST128_Info : CAST128_Info


Inherit Cipher

inherit .Cipher : Cipher

Module Crypto.Camellia

Description

The Camellia 128-bit block cipher.


Inherit CAMELLIA

inherit Nettle.CAMELLIA : CAMELLIA

Module Crypto.DES

Description

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

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

DES also has some weak keys.


Inherit Cipher

inherit .Cipher : Cipher


Inherit DES_Info

inherit Nettle.DES_Info : DES_Info

Module Crypto.DES3

Description

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

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

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

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


Inherit Cipher

inherit .Cipher : Cipher


Inherit DES3_Info

inherit Nettle.DES3_Info : DES3_Info

Module Crypto.DH

Description

Diffie-Hellman key-exchange related stuff.


Variable MODPGroup

Parameters Crypto.DH.MODPGroup

Description

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

RFC 5114 2.2


Variable MODPGroup1

Parameters Crypto.DH.MODPGroup1

Description

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

RFC 2409 6.1

Note

Not allowed for use with FIPS 140.


Variable MODPGroup14

Parameters Crypto.DH.MODPGroup14

Description

MODP Group 14 (2048 bit).

RFC 3526 3


Variable MODPGroup15

Parameters Crypto.DH.MODPGroup15

Description

MODP Group 15 (3072 bit).

RFC 3526 3


Variable MODPGroup16

Parameters Crypto.DH.MODPGroup16

Description

MODP Group 16 (4096 bit).

RFC 3526 5


Variable MODPGroup17

Parameters Crypto.DH.MODPGroup17

Description

MODP Group 17 (6144 bit).

RFC 3526 6


Variable MODPGroup18

Parameters Crypto.DH.MODPGroup18

Description

MODP Group 18 (8192 bit).

RFC 3526 7


Variable MODPGroup2

Parameters Crypto.DH.MODPGroup2

Description

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

RFC 2409 6.2

Note

Not allowed for use with FIPS 140.


Variable MODPGroup22

Parameters Crypto.DH.MODPGroup22

Description

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

RFC 5114 2.1


Variable MODPGroup24

Parameters Crypto.DH.MODPGroup24

Description

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

RFC 5114 2.3


Variable MODPGroup5

Parameters Crypto.DH.MODPGroup5

Description

MODP Group 5 (1536 bit).

RFC 3526 2

Note

Not allowed for use with FIPS 140.

Class Crypto.DH.Parameters

Description

Diffie-Hellman parameters.


Inherit DH_Params

inherit Nettle.DH_Params : DH_Params


Variable g

Gmp.mpz Crypto.DH.Parameters.g

Description

Generator.


Variable order

__deprecated__ Gmp.mpz Crypto.DH.Parameters.order

Description

Alias for q.

Deprecated

Replaced by q.


Variable p

Gmp.mpz Crypto.DH.Parameters.p

Description

Prime.


Variable q

Gmp.mpz Crypto.DH.Parameters.q

Description

Subgroup size.


Method create

Crypto.DH.Parameters Crypto.DH.Parameters(this_program|Crypto.DSA|Gmp.mpz|int other, Gmp.mpz|int|void g, Gmp.mpz|int|void q)

Description

Initialize the set of Diffie-Hellman parameters.

Parameter other
Parameters|Crypto.DSA

Copy the parameters from this object.

Gmp.mpz|int

The prime for the group.

Parameter g

The generator for the group. Defaults to 2.

Parameter q

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


Method generate_keypair

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

Description

Generate a Diffie-Hellman key pair.

Returns

Returns the following array:

Array
Gmp.mpz 0

The generated public key.

The corresponding private key.

Module Crypto.IDEA

Description

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


Inherit Cipher

inherit .Cipher : Cipher


Inherit IDEA_Info

inherit Nettle.IDEA_Info : IDEA_Info

Module Crypto.Koremutake

Description

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

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

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


Method decrypt

int decrypt(string c)

Description

Decode a koremutake string into an integer.


Method encrypt

string encrypt(int m)

Description

Encode an integer as a koremutake string.

Module Crypto.MD2

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit MD2_Info

inherit Nettle.MD2_Info : MD2_Info

Module Crypto.MD4

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit MD4_Info

inherit Nettle.MD4_Info : MD4_Info

Module Crypto.MD5

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit MD5_Info

inherit Nettle.MD5_Info : MD5_Info


Method crypt_hash

string crypt_hash(string password, string salt, int|void rounds)

Description

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

Note

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

See also

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

Module Crypto.NT

Class Crypto.NT.CryptContext

Description

Class representing an HCRYPTPROV handle.


Method create

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

Parameter name

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

Parameter csp

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


Method read

string read(int size, string|void init)

Description

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

Module Crypto.PGP

Description

PGP stuff. See RFC 2440.


Method decode

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

Description

Decodes PGP data.


Method decode_radix64

mapping(string:mixed) decode_radix64(string data)

Description

Decode ASCII armour.


Method encode_radix64

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

Description

Encode PGP data with ASCII armour.


Method verify_signature

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

Description

Verify text against signature sig with the public key pubkey.

Module Crypto.Random

Description

This module contains stuff to that tries to give you the best possible random generation.


Method add_entropy

void add_entropy(string data, int entropy)

Description

Inject additional entropy into the random generator.

Parameter data

The random string.

Parameter entropy

The number of bits in the random string that is truely random.


Method blocking_random_string

string blocking_random_string(int len)

Description

Works as random_string, but may block in order to gather enough entropy to make a truely random output. Using this function is probably overkill for about all applications.


Method random

Gmp.mpz random(int top)

Description

Returns a Gmp.mpz object with a random value between 0 and top. Uses random_string.


Method random_string

string random_string(int len)

Description

Returns a string of length len with random content. The content is generated by a Yarrow random generator that is constantly updated with output from /dev/random on UNIX and CryptGenRandom on NT. The Yarrow random generator is fed at least the amount of random data from its sources as it outputs, thus doing its best to give at least good pseudo- random data on operating systems with bad /dev/random.

Module Crypto.SHA1

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit SHA1_Info

inherit Nettle.SHA1_Info : SHA1_Info

Module Crypto.SHA224

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit SHA224_Info

inherit Nettle.SHA224_Info : SHA224_Info

Module Crypto.SHA256

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit SHA256_Info

inherit Nettle.SHA256_Info : SHA256_Info

Module Crypto.SHA384

Description

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


Inherit Hash

inherit .Hash : Hash


Inherit SHA384_Info

inherit Nettle.SHA384_Info : SHA384_Info

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


Inherit Hash

inherit .Hash : Hash


Inherit SHA512_Info

inherit Nettle.SHA512_Info : SHA512_Info

Module Crypto.Serpent

Description

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


Inherit Cipher

inherit .Cipher : Cipher


Inherit Serpent_Info

inherit Nettle.Serpent_Info : Serpent_Info

Module Crypto.Twofish

Description

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


Inherit Cipher

inherit .Cipher : Cipher


Inherit Twofish_Info

inherit Nettle.Twofish_Info : Twofish_Info

Module Nettle

Description

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


Method crypt

string(8bit) crypt(string data)

Description

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

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

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

See also

update(), digest()


Method crypt_md5

string crypt_md5(string password, string salt)

Description

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


Method digest

string(8bit) digest()

Description

Generate a message digest for the data accumulated so far, and reset to handle the next message.

See also

update(), digest()


Method set_decrypt_key

CipherState set_decrypt_key(string key, void|int force)

Description

Initializes the object for decryption.

See also

set_encrypt_key, crypt


Method set_encrypt_key

CipherState set_encrypt_key(string key, void|int force)

Description

Initializes the object for encryption.

See also

set_decrypt_key, crypt


Method set_iv

this_program set_iv(string iv)

Description

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


Method update

void update(string public_data)

Description

Add public_data to be authenticated.

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

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

Class Nettle.AES_GCM_State

Description

State for AES/GCM encryption.

Implementation mixin of the Galois Counter Mode (GCM) with AES.

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

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

Note

Use Crypto.AES.GCM instead.

Note

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

See also

Crypto.AES.GCM

Class Nettle.AES_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.AES_State

Description

State for AES encyption

Class Nettle.ARCFOUR_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.ARCFOUR_State

Description

State for ARCFOUR encyption

Class Nettle.BLOWFISH_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.BLOWFISH_State

Description

State for Blowfish encyption

Class Nettle.CAST128_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.CAST128_State

Description

State for CAST128 encyption

Class Nettle.CipherInfo

Description

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


Method block_size

string block_size()

Returns

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


Method key_size

string key_size()

Returns

The recommended key size for the cipher.


Method name

string name()

Returns

A human readable name for the algorithm.

Class Nettle.CipherState

Description

Base class for hashing contexts.


Method crypt

string crypt(string data)

Description

Encrypts or decrypts data, using the current key.

Parameter data

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

Returns

The encrypted or decrypted data.


Method key_size

string key_size()

Returns

The actual key size for this cipher.


Method make_key

string make_key()

Description

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

Returns

The generated key.

See also

set_encrypt_key


Method set_decrypt_key

CipherState set_decrypt_key(string key, void|int force)

Description

Initializes the object for decryption.

See also

set_encrypt_key, crypt


Method set_encrypt_key

CipherState set_encrypt_key(string key, void|int force)

Description

Initializes the object for encryption.

See also

set_decrypt_key, crypt

Class Nettle.DES3_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.


Method fix_parity

string fix_parity(string key)

Description

Sets the last bit in every byte in key to reflect the parity. If a 21 byte key is used, it will be expanded into 24 bytes. If a key longer than 24 characters is used, it will be truncated to 24 characters.

Class Nettle.DES3_State

Description

State for DES3 encyption

Class Nettle.DES_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.


Method fix_parity

string fix_parity(string key)

Description

Sets the last bit in every byte in key to reflect the parity. If a seven byte key is used, it will be expanded into eight bytes. If a key longer than eight characters is used, it will be truncated to eight characters.

Class Nettle.DES_State

Description

State for DES encyption

Class Nettle.HashInfo

Description

Represents information about a hash algorithm, such as name, digest size, and internal block size.


Method block_size

string block_size()

Description

Returns the internal block size of the hash algorithm.


Method crypt_hash

string crypt_hash(string password, string salt, int rounds)

Description

Password hashing function in crypt_md5()-style.

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

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

See also

crypt_md5()


Method digest_size

string digest_size()

Description

Returns the size of a hash digests.


Method hash

string hash(string data)

Description

Works as a (faster) shortcut for HashState()->update(data)->digest(), where HashState is the hash state class corresponding to this HashInfo.

See also

HashState()->update() and HashState()->digest().


Method hash

string hash(Stdio.File file, void|int bytes)

Description

Works as a (faster) shortcut for HashState()->update(Stdio.read_file(file))->digest(), where HashState is the hash state class corresponding to this HashInfo.

Parameter bytes

The number of bytes of the file object file that should be hashed. Negative numbers are ignored and the whole file is hashed.

See also

Stdio.File, HashState()->update() and HashState()->digest().


Method name

string name()

Description

Returns a human readable name for the algorithm.

Class Nettle.HashState

Description

Base class for hashing contexts.


Method digest

string digest(int|void length)

Description

Generates a digests, and resets the hashing contents.

Parameter length

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

Returns

The digest.


Method update

HashState update(string data)

Description

Hashes more data.

Class Nettle.IDEA_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.IDEA_State

Description

State for IDEA encyption

Class Nettle.MD2_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.MD2_State

Description

State for MD2 hashing.

Class Nettle.MD4_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.MD4_State

Description

State for MD4 hashing.

Class Nettle.MD5_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.MD5_State

Description

State for MD5 hashing.

Class Nettle.SHA1_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.SHA1_State

Description

State for SHA1 hashing.

Class Nettle.SHA224_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.SHA224_State

Description

State for SHA224 hashing.

Class Nettle.SHA256_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.SHA256_State

Description

State for SHA256 hashing.

Class Nettle.SHA384_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.SHA384_State

Description

State for SHA384 hashing.

Class Nettle.SHA512_Info

Description

Internal mixin class, intended to be multiply inherited together with HashInfo.

Class Nettle.SHA512_State

Description

State for SHA512 hashing.

Class Nettle.Serpent_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.Serpent_State

Description

State for Serpent encyption

Class Nettle.Twofish_Info

Description

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Class Nettle.Twofish_State

Description

State for Twofish encyption

Class Nettle.Yarrow

Description

Yarrow is a family of pseudo-randomness generators, designed for cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson. Yarrow-160 is described in a paper at http://www.counterpane.com/yarrow.html, and it uses SHA1 and triple-DES, and has a 160-bit internal state. Nettle implements Yarrow-256, which is similar, but uses SHA256 and AES to get an internal state of 256 bits.


Method create

Nettle.Yarrow Nettle.Yarrow(void|int sources)

Description

The number of entropy sources that will feed entropy to the random number generator is given as an argument to Yarrow during instantiation.

See also

update


Method force_reseed

void force_reseed()

Description

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


Method get_seed

string(8bit) get_seed()

Description

Returns part of the internal state so that it can be saved for later seeding.

See also

seed(), random_string()


Method is_seeded

bool is_seeded()

Description

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

See also

seed


Method min_seed_size

int(0..) min_seed_size()

Description

Returns the minimal number of characters that the seed needs to properly seed the random number generator.

See also

seed


Method needed_sources

int(0..) needed_sources()

Description

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


Method random_string

string random_string(int length)

Description

Returns a pseudo-random string of the requested length.


Method seed

Yarrow seed(string data)

Description

The random generator needs to be seeded before it can be used. The seed must be at least 32 characters long. The seed could be stored from a previous run by inserting the value returned from get_seed.

Returns

Returns the called object.

See also

min_seed_size, get_seed, is_seeded


Method update

bool update(string data, int source, int entropy)

Description

Inject additional entropy into the random number generator.

See also

create