passlib.utils - Helper Functions¶
Warning
This module is primarily used as an internal support module. It’s interface has not been finalized yet, and may be changed somewhat between major releases of Passlib, as the internal code is cleaned up and simplified.
This module primarily contains utility functions used interally by Passlib. However, end-user applications may find some of the functions useful, in particular:
Constants¶
- passlib.utils.unix_crypt_schemes¶
List of the names of all the hashes in passlib.hash which are natively supported by crypt() on at least one operating system.
For all hashes in this list, the expression passlib.hash.alg.has_backend("os_crypt") will return True if the host OS natively supports the hash. This list is used by host_context and ldap_context to determine which hashes are supported by the host.
See also
Identifiers & Platform Support for a table of which OSes are known to support which hashes.
Unicode Helpers¶
- passlib.utils.consteq(left, right)¶
Check two strings/bytes for equality. This is functionally equivalent to left == right, but attempts to take constant time relative to the size of the righthand input.
The purpose of this function is to help prevent timing attacks during digest comparisons: the standard == operator aborts after the first mismatched character, causing it’s runtime to be proportional to the longest prefix shared by the two inputs. If an attacker is able to predict and control one of the two inputs, repeated queries can be leveraged to reveal information about the content of the second argument. To minimize this risk, consteq() is designed to take THETA(len(right)) time, regardless of the contents of the two strings. It is recommended that the attacker-controlled input be passed in as the left-hand value.
Warning
This function is not perfect. Various VM-dependant issues (e.g. the VM’s integer object instantiation algorithm, internal unicode representation, etc), may still cause the function’s run time to be affected by the inputs, though in a less predictable manner. To minimize such risks, this function should not be passed unicode inputs that might contain non- ASCII characters.
New in version 1.6.
- passlib.utils.saslprep(source, param='value')¶
Normalizes unicode strings using SASLPrep stringprep profile.
The SASLPrep profile is defined in RFC 4013. It provides a uniform scheme for normalizing unicode usernames and passwords before performing byte-value sensitive operations such as hashing. Among other things, it normalizes diacritic representations, removes non-printing characters, and forbids invalid characters such as \n. Properly internationalized applications should run user passwords through this function before hashing.
Parameters: - source – unicode string to normalize & validate
- param – Optional noun used to refer to identify source parameter in error messages (Defaults to the string "value"). This is mainly useful to make the caller’s error messages make more sense.
Raises ValueError: if any characters forbidden by the SASLPrep profile are encountered.
Returns: normalized unicode string
Note
This function is not available under Jython, as the Jython stdlib is missing the stringprep module (Jython issue 1758320).
New in version 1.6.
Bytes Helpers¶
- passlib.utils.xor_bytes(left, right)¶
Perform bitwise-xor of two byte strings (must be same size)
- passlib.utils.render_bytes(source, *args)¶
Peform % formating using bytes in a uniform manner across Python 2/3.
This function is motivated by the fact that bytes instances do not support % or {} formatting under Python 3. This function is an attempt to provide a replacement: it converts everything to unicode (decoding bytes instances as latin-1), performs the required formatting, then encodes the result to latin-1.
Calling render_bytes(source, *args) should function roughly the same as source % args under Python 2.
- passlib.utils.int_to_bytes(value, count)¶
encode integer as single big-endian byte string
- passlib.utils.bytes_to_int(value)¶
decode byte string as single big-endian integer
Encoding Helpers¶
- passlib.utils.is_same_codec(left, right)¶
Check if two codec names are aliases for same codec
- passlib.utils.is_ascii_codec(codec)¶
Test if codec is compatible with 7-bit ascii (e.g. latin-1, utf-8; but not utf-16)
- passlib.utils.is_ascii_safe(source)¶
Check if string (bytes or unicode) contains only 7-bit ascii
- passlib.utils.to_bytes(source, encoding='utf-8', param='value', source_encoding=None)¶
Helper to normalize input to bytes.
Parameters: - source – Source bytes/unicode to process.
- encoding – Target encoding (defaults to "utf-8").
- param – Optional name of variable/noun to reference when raising errors
- source_encoding – If this is specified, and the source is bytes, the source will be transcoded from source_encoding to encoding (via unicode).
Raises TypeError: if source is not unicode or bytes.
Returns: - unicode strings will be encoded using encoding, and returned.
- if source_encoding is not specified, byte strings will be returned unchanged.
- if source_encoding is specified, byte strings will be transcoded to encoding.
- passlib.utils.to_unicode(source, encoding='utf-8', param='value')¶
Helper to normalize input to unicode.
Parameters: - source – source bytes/unicode to process.
- encoding – encoding to use when decoding bytes instances.
- param – optional name of variable/noun to reference when raising errors.
Raises TypeError: if source is not unicode or bytes.
Returns: - returns unicode strings unchanged.
- returns bytes strings decoded using encoding
- passlib.utils.to_native_str(source, encoding='utf-8', param='value')¶
Take in unicode or bytes, return native string.
Python 2: encodes unicode using specified encoding, leaves bytes alone. Python 3: leaves unicode alone, decodes bytes using specified encoding.
Raises TypeError: if source is not unicode or bytes.
Parameters: - source – source unicode or bytes string.
- encoding – encoding to use when encoding unicode or decoding bytes. this defaults to "utf-8".
- param – optional name of variable/noun to reference when raising errors.
Returns: str instance
Base64 Encoding¶
Base64Engine Class¶
Passlib has to deal with a number of different Base64 encodings, with varying endianness, as well as wildly different character <-> value mappings. This is all encapsulated in the Base64Engine class, which provides common encoding actions for an arbitrary base64-style encoding scheme. There are also a couple of predefined instances which are commonly used by the hashes in Passlib.
- class passlib.utils.Base64Engine(charmap, big=False)¶
Provides routines for encoding/decoding base64 data using arbitrary character mappings, selectable endianness, etc.
Parameters: - charmap – A string of 64 unique characters, which will be used to encode successive 6-bit chunks of data. A character’s position within the string should correspond to it’s 6-bit value.
- big – Whether the encoding should be big-endian (default False).
Note
This class does not currently handle base64’s padding characters in any way what so ever.
- Raw Bytes <-> Encoded Bytes
The following methods convert between raw bytes, and strings encoded using the engine’s specific base64 variant:
- encode_bytes(source)¶
encode bytes to base64 string.
Parameters: source – byte string to encode. Returns: byte string containing encoded data.
- decode_bytes(source)¶
decode bytes from base64 string.
Parameters: source – byte string to decode. Returns: byte string containing decoded data.
- encode_transposed_bytes(source, offsets)¶
encode byte string, first transposing source using offset list
- decode_transposed_bytes(source, offsets)¶
decode byte string, then reverse transposition described by offset list
- Integers <-> Encoded Bytes
The following methods allow encoding and decoding unsigned integers to and from the engine’s specific base64 variant. Endianess is determined by the engine’s big constructor keyword.
- encode_int6(value)¶
encodes 6-bit integer -> single hash64 character
- decode_int6(source)¶
decode single character -> 6 bit integer
- encode_int12(value)¶
encodes 12-bit integer -> 2 char string
- decode_int12(source)¶
decodes 2 char string -> 12-bit integer
- encode_int24(value)¶
encodes 24-bit integer -> 4 char string
- decode_int24(source)¶
decodes 4 char string -> 24-bit integer
- encode_int64(value)¶
encode 64-bit integer -> 11 char hash64 string
this format is used primarily by des-crypt & variants to encode the DES output value used as a checksum.
- decode_int64(source)¶
decode 11 char base64 string -> 64-bit integer
this format is used primarily by des-crypt & variants to encode the DES output value used as a checksum.
Common Character Maps¶
- passlib.utils.BASE64_CHARS¶
Character map used by standard MIME-compatible Base64 encoding scheme.
- passlib.utils.HASH64_CHARS¶
Base64 character map used by a number of hash formats; the ordering is wildly different from the standard base64 character map.
This encoding system appears to have originated with des_crypt, but is used by md5_crypt, sha256_crypt, and others. Within Passlib, this encoding is referred as the “hash64” encoding, to distinguish it from normal base64 and others.
Predefined Instances¶
- passlib.utils.h64¶
Predefined instance of Base64Engine which uses the HASH64_CHARS character map and little-endian encoding. (see HASH64_CHARS for more details).
- passlib.utils.h64big¶
Predefined variant of h64 which uses big-endian encoding. This is mainly used by des_crypt.
Changed in version 1.6: Previous versions of Passlib contained a module named passlib.utils.h64; As of Passlib 1.6 this was replaced by the the h64 and h64big instances of the Base64Engine class; the interface remains mostly unchanged.
Other¶
- passlib.utils.ab64_encode(data)¶
encode using variant of base64
the output of this function is identical to stdlib’s b64_encode, except that it uses . instead of +, and omits trailing padding = and whitepsace.
it is primarily used by Passlib’s custom pbkdf2 hashes.
- passlib.utils.ab64_decode(data)¶
decode using variant of base64
the input of this function is identical to stdlib’s b64_decode, except that it uses . instead of +, and should not include trailing padding = or whitespace.
it is primarily used by Passlib’s custom pbkdf2 hashes.
Randomness¶
- passlib.utils.rng¶
The random number generator used by Passlib to generate salt strings and other things which don’t require a cryptographically strong source of randomness.
If os.urandom() support is available, this will be an instance of random.SystemRandom, otherwise it will use the default python PRNG class, seeded from various sources at startup.
- passlib.utils.getrandbytes(rng, count)¶
return byte-string containing count number of randomly generated bytes, using specified rng
- passlib.utils.getrandstr(rng, charset, count)¶
return string containing count number of chars/bytes, whose elements are drawn from specified charset, using specified rng
- passlib.utils.generate_password(size=10, charset=<default charset>)¶
generate random password using given length & charset
Parameters: - size – size of password.
- charset –
optional string specified set of characters to draw from.
the default charset contains all normal alphanumeric characters, except for the characters 1IiLl0OoS5, which were omitted due to their visual similarity.
Returns: str containing randomly generated password.
Note
Using the default character set, on a OS with SystemRandom support, this function should generate passwords with 5.7 bits of entropy per character.
Interface Tests¶
- passlib.utils.is_crypt_handler(obj)¶
check if object follows the Password Hash Interface
- passlib.utils.is_crypt_context(obj)¶
check if object appears to be a CryptContext instance
- passlib.utils.has_rounds_info(handler)¶
check if handler provides the optional rounds information attributes
- passlib.utils.has_salt_info(handler)¶
check if handler provides the optional salt information attributes
Submodules¶
There are also a few sub modules which provide additional utility functions:
Previous topic
passlib.registry - Password Handler Registry
Next topic
passlib.utils.handlers - Framework for writing password hashes