# `passlib.utils.binary` - Binary Helper Functions

Warning

This module is primarily used as an internal support module. Its 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.

## Constants

passlib.utils.binary.BASE64_CHARS

  Character map used by standard MIME-compatible Base64 encoding scheme.

passlib.utils.binary.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.

passlib.utils.binary.BCRYPT_CHARS

  Base64 character map used by `bcrypt`. The ordering is wildly different from both the standard base64 character map, and the common hash64 character map.

## 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.binary.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 its 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.

  #### Informational Attributes

  charmap

    unicode string containing list of characters used in encoding; position in string matches 6bit value of character.

  bytemap

    bytes version of `charmap`

  big

    boolean flag indicating this using big-endian encoding.

### Predefined Instances

passlib.utils.binary.h64

  Predefined instance of `Base64Engine` which uses the `HASH64_CHARS` character map and little-endian encoding. (see `HASH64_CHARS` for more details).

passlib.utils.binary.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.binary.ab64_encode(data)

  encode using shortened base64 format which omits padding & whitespace. uses custom `./` altchars.

  it is primarily used by Passlib’s custom pbkdf2 hashes.

passlib.utils.binary.ab64_decode(data)

  decode from shortened base64 format which omits padding & whitespace. uses custom `./` altchars, but supports decoding normal `+/` altchars as well.

  it is primarily used by Passlib’s custom pbkdf2 hashes.

passlib.utils.binary.b64s_encode(data)

  encode using shortened base64 format which omits padding & whitespace. uses default `+/` altchars.

passlib.utils.binary.b64s_decode(data)

  decode from shortened base64 format which omits padding & whitespace. uses default `+/` altchars.

passlib.utils.binary.b32encode(source)

  wrapper around `base64.b32encode()` which strips padding, and returns a native string.

passlib.utils.binary.b32decode(source)

  wrapper around `base64.b32decode()` which handles common mistyped chars. padding optional, ignored if present.