ska package

Subpackages

Submodules

ska.base module

class ska.base.AbstractSignature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: object

Abstract class for signature generation and validation.

Based on symmetric keys.

Parameters:

  • signature –

  • auth_user –

  • valid_until –

auth_user
static datetime_to_timestamp(dtv: datetime) → Optional[str][source]

Human readable datetime according to the format specified.

Format is specified in TIMESTAMP_FORMAT.

Parameters:

dtv –

Returns:

static datetime_to_unix_timestamp(dtv: datetime) → Optional[float][source]

Convert datetime.datetime to Unix timestamp.

Parameters:

dtv –

Returns:

Unix timestamp.

extra
classmethod generate_signature(auth_user: str, secret_key: str, valid_until: Optional[Union[float, str]] = None, lifetime: int = 600, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → AbstractSignature[source]

Generates the signature.

If timestamp is given, the signature is created using the given timestamp. Otherwise current time is used.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • lifetime – Lifetime of the signature in seconds.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

Example:

>>> sig = Signature.generate_signature('user', 'your-secret-key')
EBS6ipiqRLa6TY5vxIvZU30FpnM=
classmethod get_base(auth_user: str, timestamp: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Get base string.

Add something here so that timestamp to signature conversion is not that obvious.

Parameters:

  • auth_user –

  • timestamp –

  • extra –

  • value_dumper –

  • quoter –

is_expired() → bool[source]

Checks if current signature is expired.

Returns True if signature is expired and False otherwise.

Returns:

Example:

>>> # Generating the signature
>>> sig = Signature.generate_signature('user', 'your-secret-key')
>>> sig.is_expired()
False
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

static make_secret_key(secret_key: str) → bytes[source]

The secret key how its’ supposed to be used in generate signature.

Parameters:

secret_key –

Returns:

signature
classmethod timestamp_to_date(timestamp: Union[float, str], fail_silently: bool = True) → Optional[datetime][source]

Converts the given timestamp to date.

If fail_silently is set to False, raises exceptions if timestamp is not valid timestamp (according to the format we have specified in the TIMESTAMP_FORMAT). Mainly used internally.

Parameters:

  • timestamp –

  • fail_silently –

Returns:

classmethod unix_timestamp_to_date(timestamp: Union[float, str], fail_silently: bool = True) → Optional[datetime][source]

Converts the given Unix timestamp to date. If fail_silently is set to False, raises exceptions if timestamp is not valid timestamp.

Parameters:

  • timestamp – UNIX timestamp. Possible to parse to float.

  • fail_silently –

Returns:

valid_until
classmethod validate_signature(signature: Union[str, bytes], auth_user: str, secret_key: str, valid_until: Union[str, float], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, return_object: bool = False, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → Union[SignatureValidationResult, bool][source]

Validates the signature.

Parameters:

  • signature –

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp.

  • extra – Extra arguments to be validated.

  • return_object – If set to True, an instance of SignatureValidationResult is returned.

  • value_dumper –

  • quoter –

Returns:

Example:

>>> Signature.validate_signature(
>>>     'EBS6ipiqRLa6TY5vxIvZU30FpnM=',
>>>     'user',
>>>     'your-secret-key',
>>>     '1377997396.0'
>>> )
False
class ska.base.SignatureValidationResult(result: bool, errors: Optional[List[Union[ErrorCode, Any]]] = None)[source]

Bases: object

Signature validation result container.

If signature validation result is True, things like this would work:

>>> res = SignatureValidationResult(result=True)
>>> print bool(res)
True
>>> res = SignatureValidationResult(
>>>     result=False,
>>>     reason=[error_codes.INVALID_SIGNATURE,]
>>> )
>>> print bool(res)
False
property message: str

Human readable message of all errors.

Returns:

property reason: map

Reason.

For backwards compatibility. Returns list of text messages.

Returns:

ska.defaults module

Application defaults.

  • SIGNATURE_LIFETIME (int): Signature lifetime in seconds. Default value is 600 (seconds).

  • DEFAULT_SIGNATURE_PARAM (str): Default name of the REQUEST param holding the generated signature value. Default value is signature.

  • DEFAULT_AUTH_USER_PARAM (str): Default name of the REQUEST param holding the auth_user value. Default value is auth_user.

  • DEFAULT_VALID_UNTIL_PARAM (str): Default name of the REQUEST param holding the valid_until value. Default value is valid_until.

  • DEFAULT_TIME_ZONE_PARAM (str): Default name of the REQUEST param holding the time_zone value. Default value is time_zone.

  • DEFAULT_EXTRA_PARAM (str): Default name of the REQUEST param holding the extra value. Default value is extra.

  • DEFAULT_PROVIDER_PARAM (str): Default name of the REQUEST param holding the provider value. Default value is provider.

  • DEFAULT_URL_SUFFIX (str): Suffix to add after the endpoint_url and before the appended signature params.

  • DEFAULT_RESERVED_PARAMS (list): List of GET params reserved by default. Users should not be allowed to use them.

ska.error_codes module

class ska.error_codes.ErrorCode(code: int, message: str)[source]

Bases: object

Base error code.

If you have ever used the following code with validation_result:

>>> human_readable_error = ' '.join(validation_result.reason)

…change it as follows:

>>> human_readable_error = validation_result.message
Property int code:

Just an integer code.

Property string message:

Human readable represantation of the error message.

code
message

ska.exceptions module

exception ska.exceptions.BaseSkaException[source]

Bases: Exception

Base exception.

exception ska.exceptions.ImproperlyConfigured[source]

Bases: BaseSkaException

Improperly configured exception.

Raised when developer didn’t configure/write the code properly.

exception ska.exceptions.InvalidData[source]

Bases: BaseSkaException

Invalid data exception.

Raised when invalid data (tampered) is detected.

ska.generate_signed_url module

ska.generate_signed_url.main()[source]

Prints signed URL to console.

Example:

python src/ska/generate_signature.py -u http://example.com -au user -sk test

Example:

ska-sign-url -u http://example.com -au user -sk test

ska.gettext module

ska.helpers module

ska.helpers.default_quoter(value)[source]
ska.helpers.default_value_dumper(value)[source]
ska.helpers.dict_keys(data: Dict[str, Union[bytes, str, float, int]], return_string: bool = False) → Union[str, List[str]][source]

Get sorted keys from dictionary given.

If return_string argument is set to True, returns keys joined by commas.

Parameters:

  • data –

  • return_string –

Returns:

ska.helpers.dict_to_ordered_list(data: Dict[str, Union[bytes, str, float, int]]) → List[Tuple[str, Union[bytes, str, float, int]]][source]

Get extra as ordered list.

Parameters:

data (dict) –

Returns:

ska.helpers.extract_signed_data(data: Dict[str, Union[bytes, str, float, int]], extra: List[str]) → Dict[str, Union[bytes, str, float, int]][source]

Filters out non-whitelisted items from the extra dictionary given.

Parameters:

  • data –

  • extra –

Returns:

ska.helpers.get_callback_func(func: Union[str, Callable], fail_silently: bool = True) → Optional[Callable][source]

Take a string and try to extract a function from it.

Parameters:

  • func – If callable is given, return as is. If str is given, try to extract the function from the string given and return.

  • fail_silently –

Returns:

Returns callable if what’s extracted is callable or None otherwise.

ska.helpers.javascript_quoter(value)[source]
ska.helpers.javascript_value_dumper(value)[source]
ska.helpers.make_valid_until(lifetime: int = 600) → float[source]

Make valid until.

Parameters:

lifetime –

Returns:

ska.helpers.sorted_urlencode(data: ~typing.Dict[str, ~typing.Union[bytes, str, float, int]], quoted: bool = True, value_dumper: ~typing.Optional[~typing.Callable] = <function default_value_dumper>, quoter: ~typing.Optional[~typing.Callable] = <function default_quoter>) → str[source]

Similar to built-in urlencode, but always puts data in a sorted constant way that stays the same between various python versions.

Parameters:

  • data –

  • quoted –

  • value_dumper –

  • quoter –

Returns:

ska.shortcuts module

ska.shortcuts.extract_signed_request_data(data: ~typing.Dict[str, ~typing.Union[bytes, str, float, int]], secret_key: ~typing.Optional[str] = None, signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra_param: str = 'extra', validate: bool = False, fail_silently: bool = False, signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None, quoter: ~typing.Optional[~typing.Callable] = None) → Dict[str, Union[bytes, str, float, int]][source]

Validate the signed request data.

Parameters:

  • data – Dictionary holding the (HTTP) request (for example GET or POST) data.

  • secret_key – The shared secret key.

  • signature_param – Name of the (for example GET or POST) param name which holds the signature value.

  • auth_user_param – Name of the (for example GET or POST) param name which holds the auth_user value.

  • valid_until_param – Name of the (foe example GET or POST) param name which holds the valid_until value.

  • extra_param – Name of the (foe example GET or POST) param name which holds the extra value.

  • validate – If set to True, request data is validated before returning the result.

  • fail_silently – If set to True, exceptions are omitted.

  • signature_cls –

  • value_dumper –

  • quoter –

Returns:

Dictionary with signed request data.

ska.shortcuts.sign_url(auth_user: str, secret_key: str, valid_until: ~typing.Optional[~typing.Union[float, str]] = None, lifetime: int = 600, url: str = '', suffix: str = '?', signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra: ~typing.Optional[~typing.Dict[str, ~typing.Union[bytes, str, float, int]]] = None, extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None) → str[source]

Sign the URL.

Parameters:

  • auth_user – Username of the user making the request.

  • secret_key – The shared secret key.

  • valid_until – Unix timestamp. If not given, generated automatically (now + lifetime).

  • lifetime – Signature lifetime in seconds.

  • url – URL to be signed.

  • suffix – Suffix to add after the endpoint_url and before the appended signature params.

  • signature_param – Name of the GET param name which would hold the generated signature value.

  • auth_user_param – Name of the GET param name which would hold the auth_user value.

  • valid_until_param – Name of the GET param name which would hold the valid_until value.

  • extra – Extra variables to add to the request.

  • extra_param – Name of the GET param name which would hold the extra_keys value.

  • signature_cls –

  • value_dumper –

Returns:

Example:

Required imports.

>>> from ska import sign_url

Producing a signed URL.

>>> signed_url = sign_url(
>>>     auth_user='user', secret_key='your-secret_key', lifetime=120,
>>>     url='http://e.com/api/', signature_param=DEFAULT_SIGNATURE_PARAM,
>>>     auth_user_param=DEFAULT_AUTH_USER_PARAM,
>>>     valid_until_param=DEFAULT_VALID_UNTIL_PARAM,
>>>     extra={
>>>         'provider': 'service1.example.com',
>>>         'email': 'john.doe@mail.example.com'
>>>     },
>>>     extra_param = DEFAULT_EXTRA_PARAM
>>> )
http://e.com/api/?valid_until=1378045287.0&auth_user=user&signature=
YlZpLFsjUKBalL4x5trhkeEgqE8%3D
ska.shortcuts.signature_to_dict(auth_user: str, secret_key: str, valid_until: ~typing.Optional[~typing.Union[float, str]] = None, lifetime: int = 600, signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra: ~typing.Optional[~typing.Dict[str, ~typing.Union[str, int]]] = None, extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None, quoter: ~typing.Optional[~typing.Callable] = None) → Dict[str, Union[bytes, str, float, int]][source]

Return a dictionary containing the signature data params.

Parameters:

  • auth_user – Username of the user making the request.

  • secret_key – The shared secret key.

  • valid_until – Unix timestamp. If not given, generated automatically (now + lifetime).

  • lifetime – Signature lifetime in seconds.

  • signature_param – Name of the (for example POST) param name which would hold the generated signature value.

  • auth_user_param – Name of the (for example POST) param name which would hold the auth_user value.

  • valid_until_param – Name of the (for example POST) param name which would hold the valid_until value.

  • extra – Additional arguments for the signature.

  • extra_param – Name of the (for example POST) param name which would hold the extra keys value.

  • signature_cls –

  • value_dumper –

  • quoter –

Returns:

Example:

Required imports.

>>> from ska import signature_to_dict

Producing a dictionary with signature data.

>>> signature_dict = signature_to_dict(
>>>     auth_user='user', secret_key='your-secret_key', lifetime=120,
>>>     signature_param=DEFAULT_SIGNATURE_PARAM,
>>>     auth_user_param=DEFAULT_AUTH_USER_PARAM,
>>>     valid_until_param=DEFAULT_VALID_UNTIL_PARAM
>>> )
{
    'signature': 'YlZpLFsjUKBalL4x5trhkeEgqE8=',
    'auth_user': 'user',
    'valid_until': '1378045287.0'
}
ska.shortcuts.validate_signed_request_data(data: ~typing.Dict[str, ~typing.Union[bytes, str, float, int]], secret_key: str, signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None, quoter: ~typing.Optional[~typing.Callable] = None) → SignatureValidationResult[source]

Validate the signed request data.

Parameters:

  • data – Dictionary holding the (HTTP) request (for example GET or POST) data.

  • secret_key – The shared secret key.

  • signature_param – Name of the (for example GET or POST) param name which holds the signature value.

  • auth_user_param – Name of the (for example GET or POST) param name which holds the auth_user value.

  • valid_until_param – Name of the (foe example GET or POST) param name which holds the valid_until value.

  • extra_param – Name of the (foe example GET or POST) param name which holds the extra keys value.

  • signature_cls –

  • value_dumper –

  • quoter –

Returns:

A ska.SignatureValidationResult object with the following properties:

  • result (bool): True if data is valid. False otherwise.

  • reason (Iterable): List of strings, indicating validation errors. Empty list in case if result is True.

ska.utils module

class ska.utils.RequestHelper(signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>)[source]

Bases: object

Request helper for easy put/extract of signature params from URLs.

extract_signed_data(data: Dict[str, Union[bytes, str, float, int]], secret_key: Optional[str] = None, validate: bool = False, fail_silently: bool = False, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → Dict[str, str][source]

Extract signed data from the request.

Parameters:

  • data –

  • secret_key –

  • validate –

  • fail_silently –

  • value_dumper –

  • quoter –

Returns:

signature_to_dict(signature: AbstractSignature) → Dict[str, Union[bytes, str, float, int]][source]

Put signature into a dictionary.

Dictionary can be used later on to send requests (for example, a POST request) to the server.

Parameters:

signature – Signature class.

Returns:

Example:

Required imports.

>>> from ska import Signature, RequestHelper

Generate signature.

>>> signature = Signature.generate_signature(
>>>     auth_user='user',
>>>     secret_key='your-secret-key'
>>> )

Create a request helper.

>>> request_helper = RequestHelper(
>>>     signature_param='signature',
>>>     auth_user_param='auth_user',
>>>     valid_until_param='valid_until'
>>> )

Appending signature params to the endpoint URL.

>>> signed_dict = request_helper.signature_to_dict(
>>>     signature=signature
>>> )
{
    'signature': 'YlZpLFsjUKBalL4x5trhkeEgqE8=',
    'auth_user': 'user',
    'valid_until': '1378045287.0'
}
signature_to_url(signature: AbstractSignature, endpoint_url: str = '', suffix: str = '?') → str[source]

URL encodes the signature params.

Parameters:

  • signature – Signature class.

  • endpoint_url –

  • suffix – Suffix to add after the endpoint_url and before the appended signature params.

Returns:

Example:

Required imports.

>>> from ska import Signature, RequestHelper

Generate signature.

>>> signature = Signature.generate_signature(
>>>     auth_user='user',
>>>     secret_key='your-secret-key'
>>> )

Create a request helper.

>>> request_helper = RequestHelper(
>>>     signature_param='signature',
>>>     auth_user_param='auth_user',
>>>     valid_until_param='valid_until'
>>> )

Appending signature params to the endpoint URL.

>>> url = request_helper.signature_to_url(
>>>     signature=signature,
>>>     endpoint_url='http://e.com/api/'
>>> )
http://e.com/api/?valid_until=1378045287.0&auth_user=user&signature=YlZpLFsjUKBalL4x5trhkeEgqE8%3D
validate_request_data(data: Dict[str, Union[bytes, str, float, int]], secret_key: str, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → SignatureValidationResult[source]

Validate the request data.

Parameters:

  • data –

  • secret_key –

  • value_dumper –

  • quoter –

Returns:

Example:

If your imaginary HttpRequest object has GET property (dict), then you would validate the request data as follows.

Create a RequestHelper object with param names expected.

Required imports.

>>> from ska import RequestHelper

Create a request helper.

>>> request_helper = RequestHelper(
>>>     signature_param='signature',
>>>     auth_user_param='auth_user',
>>>     valid_until_param='valid_until'
>>> )

Validate the request data.

>>> validation_result = request_helper.validate_request_data(
>>>     data=request.GET,
>>>     secret_key='your-secret-key'
>>> )

Module contents

class ska.AbstractSignature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: object

Abstract class for signature generation and validation.

Based on symmetric keys.

Parameters:

  • signature –

  • auth_user –

  • valid_until –

auth_user
static datetime_to_timestamp(dtv: datetime) → Optional[str][source]

Human readable datetime according to the format specified.

Format is specified in TIMESTAMP_FORMAT.

Parameters:

dtv –

Returns:

static datetime_to_unix_timestamp(dtv: datetime) → Optional[float][source]

Convert datetime.datetime to Unix timestamp.

Parameters:

dtv –

Returns:

Unix timestamp.

extra
classmethod generate_signature(auth_user: str, secret_key: str, valid_until: Optional[Union[float, str]] = None, lifetime: int = 600, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → AbstractSignature[source]

Generates the signature.

If timestamp is given, the signature is created using the given timestamp. Otherwise current time is used.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • lifetime – Lifetime of the signature in seconds.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

Example:

>>> sig = Signature.generate_signature('user', 'your-secret-key')
EBS6ipiqRLa6TY5vxIvZU30FpnM=
classmethod get_base(auth_user: str, timestamp: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Get base string.

Add something here so that timestamp to signature conversion is not that obvious.

Parameters:

  • auth_user –

  • timestamp –

  • extra –

  • value_dumper –

  • quoter –

is_expired() → bool[source]

Checks if current signature is expired.

Returns True if signature is expired and False otherwise.

Returns:

Example:

>>> # Generating the signature
>>> sig = Signature.generate_signature('user', 'your-secret-key')
>>> sig.is_expired()
False
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

static make_secret_key(secret_key: str) → bytes[source]

The secret key how its’ supposed to be used in generate signature.

Parameters:

secret_key –

Returns:

signature
classmethod timestamp_to_date(timestamp: Union[float, str], fail_silently: bool = True) → Optional[datetime][source]

Converts the given timestamp to date.

If fail_silently is set to False, raises exceptions if timestamp is not valid timestamp (according to the format we have specified in the TIMESTAMP_FORMAT). Mainly used internally.

Parameters:

  • timestamp –

  • fail_silently –

Returns:

classmethod unix_timestamp_to_date(timestamp: Union[float, str], fail_silently: bool = True) → Optional[datetime][source]

Converts the given Unix timestamp to date. If fail_silently is set to False, raises exceptions if timestamp is not valid timestamp.

Parameters:

  • timestamp – UNIX timestamp. Possible to parse to float.

  • fail_silently –

Returns:

valid_until
classmethod validate_signature(signature: Union[str, bytes], auth_user: str, secret_key: str, valid_until: Union[str, float], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, return_object: bool = False, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → Union[SignatureValidationResult, bool][source]

Validates the signature.

Parameters:

  • signature –

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp.

  • extra – Extra arguments to be validated.

  • return_object – If set to True, an instance of SignatureValidationResult is returned.

  • value_dumper –

  • quoter –

Returns:

Example:

>>> Signature.validate_signature(
>>>     'EBS6ipiqRLa6TY5vxIvZU30FpnM=',
>>>     'user',
>>>     'your-secret-key',
>>>     '1377997396.0'
>>> )
False
class ska.HMACMD5Signature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: AbstractSignature

HMAC MD5 signature.

auth_user
extra
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

signature
valid_until
class ska.HMACSHA1Signature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: AbstractSignature

HMAC SHA-1 signature.

auth_user
extra
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

signature
valid_until
class ska.HMACSHA224Signature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: AbstractSignature

HMAC SHA-224 signature.

auth_user
extra
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

signature
valid_until
class ska.HMACSHA256Signature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: AbstractSignature

HMAC SHA-256 signature.

auth_user
extra
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

signature
valid_until
class ska.HMACSHA384Signature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: AbstractSignature

HMAC SHA-384 signature.

auth_user
extra
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

signature
valid_until
class ska.HMACSHA512Signature(signature: bytes, auth_user: str, valid_until: Union[float, str], extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None)[source]

Bases: AbstractSignature

HMAC SHA-512 signature.

auth_user
extra
classmethod make_hash(auth_user: str, secret_key: str, valid_until: Union[str, float] = None, extra: Optional[Dict[str, Union[bytes, str, float, int]]] = None, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → bytes[source]

Make hash.

You should implement this method in your signature class.

Parameters:

  • auth_user –

  • secret_key –

  • valid_until – Unix timestamp, valid until.

  • extra – Additional variables to be added.

  • value_dumper –

  • quoter –

Returns:

signature
valid_until
class ska.RequestHelper(signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>)[source]

Bases: object

Request helper for easy put/extract of signature params from URLs.

extract_signed_data(data: Dict[str, Union[bytes, str, float, int]], secret_key: Optional[str] = None, validate: bool = False, fail_silently: bool = False, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → Dict[str, str][source]

Extract signed data from the request.

Parameters:

  • data –

  • secret_key –

  • validate –

  • fail_silently –

  • value_dumper –

  • quoter –

Returns:

signature_to_dict(signature: AbstractSignature) → Dict[str, Union[bytes, str, float, int]][source]

Put signature into a dictionary.

Dictionary can be used later on to send requests (for example, a POST request) to the server.

Parameters:

signature – Signature class.

Returns:

Example:

Required imports.

>>> from ska import Signature, RequestHelper

Generate signature.

>>> signature = Signature.generate_signature(
>>>     auth_user='user',
>>>     secret_key='your-secret-key'
>>> )

Create a request helper.

>>> request_helper = RequestHelper(
>>>     signature_param='signature',
>>>     auth_user_param='auth_user',
>>>     valid_until_param='valid_until'
>>> )

Appending signature params to the endpoint URL.

>>> signed_dict = request_helper.signature_to_dict(
>>>     signature=signature
>>> )
{
    'signature': 'YlZpLFsjUKBalL4x5trhkeEgqE8=',
    'auth_user': 'user',
    'valid_until': '1378045287.0'
}
signature_to_url(signature: AbstractSignature, endpoint_url: str = '', suffix: str = '?') → str[source]

URL encodes the signature params.

Parameters:

  • signature – Signature class.

  • endpoint_url –

  • suffix – Suffix to add after the endpoint_url and before the appended signature params.

Returns:

Example:

Required imports.

>>> from ska import Signature, RequestHelper

Generate signature.

>>> signature = Signature.generate_signature(
>>>     auth_user='user',
>>>     secret_key='your-secret-key'
>>> )

Create a request helper.

>>> request_helper = RequestHelper(
>>>     signature_param='signature',
>>>     auth_user_param='auth_user',
>>>     valid_until_param='valid_until'
>>> )

Appending signature params to the endpoint URL.

>>> url = request_helper.signature_to_url(
>>>     signature=signature,
>>>     endpoint_url='http://e.com/api/'
>>> )
http://e.com/api/?valid_until=1378045287.0&auth_user=user&signature=YlZpLFsjUKBalL4x5trhkeEgqE8%3D
validate_request_data(data: Dict[str, Union[bytes, str, float, int]], secret_key: str, value_dumper: Optional[Callable] = None, quoter: Optional[Callable] = None) → SignatureValidationResult[source]

Validate the request data.

Parameters:

  • data –

  • secret_key –

  • value_dumper –

  • quoter –

Returns:

Example:

If your imaginary HttpRequest object has GET property (dict), then you would validate the request data as follows.

Create a RequestHelper object with param names expected.

Required imports.

>>> from ska import RequestHelper

Create a request helper.

>>> request_helper = RequestHelper(
>>>     signature_param='signature',
>>>     auth_user_param='auth_user',
>>>     valid_until_param='valid_until'
>>> )

Validate the request data.

>>> validation_result = request_helper.validate_request_data(
>>>     data=request.GET,
>>>     secret_key='your-secret-key'
>>> )
ska.Signature

alias of HMACSHA1Signature

class ska.SignatureValidationResult(result: bool, errors: Optional[List[Union[ErrorCode, Any]]] = None)[source]

Bases: object

Signature validation result container.

If signature validation result is True, things like this would work:

>>> res = SignatureValidationResult(result=True)
>>> print bool(res)
True
>>> res = SignatureValidationResult(
>>>     result=False,
>>>     reason=[error_codes.INVALID_SIGNATURE,]
>>> )
>>> print bool(res)
False
property message: str

Human readable message of all errors.

Returns:

property reason: map

Reason.

For backwards compatibility. Returns list of text messages.

Returns:

ska.extract_signed_request_data(data: ~typing.Dict[str, ~typing.Union[bytes, str, float, int]], secret_key: ~typing.Optional[str] = None, signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra_param: str = 'extra', validate: bool = False, fail_silently: bool = False, signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None, quoter: ~typing.Optional[~typing.Callable] = None) → Dict[str, Union[bytes, str, float, int]][source]

Validate the signed request data.

Parameters:

  • data – Dictionary holding the (HTTP) request (for example GET or POST) data.

  • secret_key – The shared secret key.

  • signature_param – Name of the (for example GET or POST) param name which holds the signature value.

  • auth_user_param – Name of the (for example GET or POST) param name which holds the auth_user value.

  • valid_until_param – Name of the (foe example GET or POST) param name which holds the valid_until value.

  • extra_param – Name of the (foe example GET or POST) param name which holds the extra value.

  • validate – If set to True, request data is validated before returning the result.

  • fail_silently – If set to True, exceptions are omitted.

  • signature_cls –

  • value_dumper –

  • quoter –

Returns:

Dictionary with signed request data.

ska.sign_url(auth_user: str, secret_key: str, valid_until: ~typing.Optional[~typing.Union[float, str]] = None, lifetime: int = 600, url: str = '', suffix: str = '?', signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra: ~typing.Optional[~typing.Dict[str, ~typing.Union[bytes, str, float, int]]] = None, extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None) → str[source]

Sign the URL.

Parameters:

  • auth_user – Username of the user making the request.

  • secret_key – The shared secret key.

  • valid_until – Unix timestamp. If not given, generated automatically (now + lifetime).

  • lifetime – Signature lifetime in seconds.

  • url – URL to be signed.

  • suffix – Suffix to add after the endpoint_url and before the appended signature params.

  • signature_param – Name of the GET param name which would hold the generated signature value.

  • auth_user_param – Name of the GET param name which would hold the auth_user value.

  • valid_until_param – Name of the GET param name which would hold the valid_until value.

  • extra – Extra variables to add to the request.

  • extra_param – Name of the GET param name which would hold the extra_keys value.

  • signature_cls –

  • value_dumper –

Returns:

Example:

Required imports.

>>> from ska import sign_url

Producing a signed URL.

>>> signed_url = sign_url(
>>>     auth_user='user', secret_key='your-secret_key', lifetime=120,
>>>     url='http://e.com/api/', signature_param=DEFAULT_SIGNATURE_PARAM,
>>>     auth_user_param=DEFAULT_AUTH_USER_PARAM,
>>>     valid_until_param=DEFAULT_VALID_UNTIL_PARAM,
>>>     extra={
>>>         'provider': 'service1.example.com',
>>>         'email': 'john.doe@mail.example.com'
>>>     },
>>>     extra_param = DEFAULT_EXTRA_PARAM
>>> )
http://e.com/api/?valid_until=1378045287.0&auth_user=user&signature=
YlZpLFsjUKBalL4x5trhkeEgqE8%3D
ska.signature_to_dict(auth_user: str, secret_key: str, valid_until: ~typing.Optional[~typing.Union[float, str]] = None, lifetime: int = 600, signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra: ~typing.Optional[~typing.Dict[str, ~typing.Union[str, int]]] = None, extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None, quoter: ~typing.Optional[~typing.Callable] = None) → Dict[str, Union[bytes, str, float, int]][source]

Return a dictionary containing the signature data params.

Parameters:

  • auth_user – Username of the user making the request.

  • secret_key – The shared secret key.

  • valid_until – Unix timestamp. If not given, generated automatically (now + lifetime).

  • lifetime – Signature lifetime in seconds.

  • signature_param – Name of the (for example POST) param name which would hold the generated signature value.

  • auth_user_param – Name of the (for example POST) param name which would hold the auth_user value.

  • valid_until_param – Name of the (for example POST) param name which would hold the valid_until value.

  • extra – Additional arguments for the signature.

  • extra_param – Name of the (for example POST) param name which would hold the extra keys value.

  • signature_cls –

  • value_dumper –

  • quoter –

Returns:

Example:

Required imports.

>>> from ska import signature_to_dict

Producing a dictionary with signature data.

>>> signature_dict = signature_to_dict(
>>>     auth_user='user', secret_key='your-secret_key', lifetime=120,
>>>     signature_param=DEFAULT_SIGNATURE_PARAM,
>>>     auth_user_param=DEFAULT_AUTH_USER_PARAM,
>>>     valid_until_param=DEFAULT_VALID_UNTIL_PARAM
>>> )
{
    'signature': 'YlZpLFsjUKBalL4x5trhkeEgqE8=',
    'auth_user': 'user',
    'valid_until': '1378045287.0'
}
ska.validate_signed_request_data(data: ~typing.Dict[str, ~typing.Union[bytes, str, float, int]], secret_key: str, signature_param: str = 'signature', auth_user_param: str = 'auth_user', valid_until_param: str = 'valid_until', extra_param: str = 'extra', signature_cls: ~typing.Type[~ska.base.AbstractSignature] = <class 'ska.signatures.hmac_sha1.HMACSHA1Signature'>, value_dumper: ~typing.Optional[~typing.Callable] = None, quoter: ~typing.Optional[~typing.Callable] = None) → SignatureValidationResult[source]

Validate the signed request data.

Parameters:

  • data – Dictionary holding the (HTTP) request (for example GET or POST) data.

  • secret_key – The shared secret key.

  • signature_param – Name of the (for example GET or POST) param name which holds the signature value.

  • auth_user_param – Name of the (for example GET or POST) param name which holds the auth_user value.

  • valid_until_param – Name of the (foe example GET or POST) param name which holds the valid_until value.

  • extra_param – Name of the (foe example GET or POST) param name which holds the extra keys value.

  • signature_cls –

  • value_dumper –

  • quoter –

Returns:

A ska.SignatureValidationResult object with the following properties:

  • result (bool): True if data is valid. False otherwise.

  • reason (Iterable): List of strings, indicating validation errors. Empty list in case if result is True.