srslib

srslib is a modern Python implementation of the Sender Rewriting Scheme (SRS).

For an overview of this library and example usage, please refer to the GitHub repository at

Module Documentation

class srslib.SRS(secret, prev_secrets=[], validity_days=21, hash_length=4)[source]

A Sender Rewriting Scheme (SRS) instance.

This class implements the Guarded scheme described in the original SRS paper at http://www.libsrs2.org/srs/srs.pdf, with sensible defaults derived from the the canonical libsrs2 C implementation.

Example usage:

srs = SRS('secret_key')
# Rewrites an email from alice@A.com to B.com
rewritten_addr = srs.forward('alice@A.com', 'B.com')
# Reverse it to get the address to bounce to.
bounce_addr = srs.reverse(rewritten_addr)
__init__(secret, prev_secrets=[], validity_days=21, hash_length=4)[source]

Creates a new SRS configuration instance.

Parameters:
  • secret (str|bytes) – Cryptographic secret for creating / rwversing rewritten addresses.
  • prev_secrets (list(str|bytes)) – Previously used secrets that are still considered valid for reversing rewritten addresses.
  • validity_days (int) – Number of days after which rewritten addresses cannot be reversed.
  • hash_length (int) – Length to truncate hash digest to.
forward(from_addr, alias_host)[source]

Rewrites sender address from_addr to alias_host.

As described in the SRS specification, the algorithm is:

  • If the envelope sender address (from_addr) is an SRS1 address rewritten by 1stHop.com to SRS0 and later by nthHop.com to SRS1, rewrite to a new SRS1 address such that bounces will go to us then 1stHop.com.
  • If from_addr is an SRS0 address rewritten by 1stHop.com, rewrite to an SRS1 address such that bounces will go to us then back to 1stHop.com.
  • If from_addr is neither an SRS0 address nor an SRS1 address, rewrite to an SRS0 address such that bounces will go to us then back to from_addr.
Parameters:
  • from_addr (str) – The original envelope sender address.
  • alias_host (str) – The host to rewrite to (current host).
Returns:

The envelope sender address rewritten to alias_host.
Return type:

str
Raises:

srslib.InvalidAddressError – from_addr is not a valid email address.
reverse(srs_addr)[source]

Reverses a rewritten address.

As described in the SRS specification, the algorithm is:

  • If srs_addr is an SRS0 address rewritten by us, bounce to the original envelope sender address.
  • If srs_addr is an SRS1 address rewritten by 1stHop.com and then us, bounce to the SRS0 address rewritten by 1stHop.com.
Parameters:

srs_addr (str) – An SRS0 or SRS1 address.
Returns:

The address to bounce to.
Return type:

str
Raises:
classmethod is_srs_address(addr, strict=True)[source]

Checks if an address is a valid SRS address.

If strict is True, this function will only consider SRS0 addresses formatted according to the Guarded scheme as valid. If strict is False, any address with an SRS0 prefix and separator is considered valid.

Parameters:
  • addr (str) – An email address, e.g. foo@example.com.
  • strict (bool) – Whether to check SRS0 addresses in strict mode.
Raises:

srslib.InvalidAddressError – addr is not a valid email address.
generate_srs0_address(orig_host, orig_local_part, alias_host)[source]

Produces an SRS0 address.

Parameters:
  • orig_host (str) – Host part of the original envelope sender address.
  • orig_local_part (str) – Local part of the original envelope sender address.
  • alias_host (str) – The host to rewrite to (current host).
Returns:

The rewritten SRS0 address.
Return type:

str
generate_srs1_address(first_hop_host, first_hop_local_part, alias_host)[source]

Produces an SRS1 address.

Parameters:
  • first_hop_host (str) – Address of the 1st hop (SRS0) host.
  • first_hop_local_part (str) – Local part generated by 1st hop host (w/o the “SRS0” prefix)
  • alias_host (str) – The host to rewrite to (current host).
Returns:

The rewritten SRS1 address.
Return type:

str
generate_hash(s, secret, hash_length)[source]

Produces a hash string for use in an SRS address.

As recommended in the specification, this function yields a base64-encoded hash of the provided string in lower case using the HMAC-SHA1 algorithm, and truncates it to hash_length characters.

Parameters:
  • s (str) – Input string to hash.
  • secret (bytes) – The cryptographic secret to use.
  • hash_length (int) – Length to truncate the generated hash digest to.
Returns:

SRS hash string, truncated to hash_length.
Return type:

str
check_hash(h, s, addr)[source]

Checks a hash (h) against an input string (s).

Following the canonical implementation (libsrs2), hashes are compared case-insensively.

Parameters:
  • h (str) – A hash string possibly generated by the algorithm described in generate_hash.
  • s (str) – Original hashed string.
  • addr (str) – The full address being reversed.
Raises:

srslib.InvalidHashError – Hash is invalid.
generate_ts(t=None)[source]

Produces a timestamp for use in an SRS0 address.

Following the algorithm in the original paper, this function yields the UNIX timestamp of the current date modded by 2^10, encoded in base32.

Parameters:t (float) – If not None, specifies the UNIX timestamp to use instead of the current time.
check_ts(ts, addr)[source]

Checks an encoded timestamp string against current time.

Parameters:
  • ts (str) – A timestamp possibly generated by the algorithm described in generate_ts.
  • addr (str) – The full address being reversed.
Raises:

srslib.InvalidTimestampError – timestamp is invalid.

Exceptions

class srslib.Error[source]

Base class for SRS errors.

class srslib.InvalidAddressError[source]

Invalid email address.

class srslib.InvalidHashError[source]

Invalid hash in an SRS address.

class srslib.InvalidTimestampError[source]

Invalid timestamp in an SRS address.