baseplate.crypto

Utilities for common cryptographic operations.

message = "Hello, world!"

secret = secrets.get_versioned("some_signing_key")
signature = make_signature(
    secret, message, max_age=datetime.timedelta(days=1))

try:
    validate_signature(secret, message, signature)
except SignatureError:
    print("Oh no, it was invalid!")
else:
    print("Message was valid!")
Message was valid!

Message Signing

baseplate.crypto.make_signature(secret, message, max_age)

Return a signature for the given message.

To ensure that key rotation works automatically, always fetch the secret token from the secret store immediately before use and do not cache / save the token anywhere. The current version of the secret will be used to sign the token.

Parameters:
Returns:

An encoded signature.

baseplate.crypto.validate_signature(secret, message, signature)

Validate and assert a message’s signature is correct.

If the signature is valid, the function will return normally with a SignatureInfo with some details about the signature. Otherwise, an exception will be raised.

To ensure that key rotation works automatically, always fetch the secret token from the secret store immediately before use and do not cache / save the token anywhere. All active versions of the secret will be checked when validating the signature.

Parameters:
  • secret (baseplate.secrets.VersionedSecret) – The secret signing key from the secret store.
  • message (str) – The message payload to validate.
  • signature (str) – The signature supplied with the message.
Raises:

UnreadableSignatureError The signature is corrupt.

Raises:

IncorrectSignatureError The digest is incorrect.

Raises:

ExpiredSignatureError The signature expired.

Return type:

SignatureInfo

class baseplate.crypto.SignatureInfo

Information about a valid signature.

Variables:
  • version (int) – The version of the packed signature format.
  • expiration (int) – The time, in seconds since the UNIX epoch, at which the signature will expire.

Exceptions

exception baseplate.crypto.SignatureError

Base class for all message signing related errors.

exception baseplate.crypto.UnreadableSignatureError

Raised when the signature is corrupt or wrongly formatted.

exception baseplate.crypto.IncorrectSignatureError

Raised when the signature is readable but does not match the message.

exception baseplate.crypto.ExpiredSignatureError(expiration)

Raised when the signature is valid but has expired.

The expiration attribute is the time (as seconds since the UNIX epoch) at which the signature expired.

Utilities

baseplate.crypto.constant_time_compare()

compare_digest(a, b) -> bool

Return ‘a == b’. This function uses an approach designed to prevent timing analysis, making it appropriate for cryptography. a and b must both be of the same type: either str (ASCII only), or any type that supports the buffer protocol (e.g. bytes).

Note: If a and b are of different lengths, or if an error occurs, a timing attack could theoretically reveal information about the types and lengths of a and b–but not their values.