= Scramp
:toc: preamble
:toclevels: 2

A Python implementation of the SCRAM authentication protocol defined by
https://tools.ietf.org/html/rfc5802[RFC 5802] and
https://www.rfc-editor.org/rfc/rfc7677.txt[RFC 7677]. Scramp supports the
following mechanisms:

* SCRAM-SHA-256
* SCRAM-SHA-1


== Installation

* Create a virtual environment: `python3 -m venv venv`
* Activate the virtual environment: `source venv/bin/activate`
* Install: `pip install scramp`


== Examples

=== Client and Server

Here's an example using both the client and the server. It's a bit contrived as
normally you'd be using either the client or server on its own.

```
>>> from scramp import ScramClient, ScramMechanism
>>>
>>> USERNAME = 'user'
>>> PASSWORD = 'pencil'
>>> MECHANISMS = ['SCRAM-SHA-256']
>>>
>>>
>>> # Choose a mechanism for our server
>>> m = ScramMechanism()  # Default is SCRAM-SHA-256
>>>
>>> # On the server side we create the authentication information for each user
>>> # and store it in an authentication database. We'll use a dict:
>>> db = {}
>>>
>>> salt, stored_key, server_key, iteration_count = m.make_auth_info(PASSWORD)
>>>
>>> db[USERNAME] = salt, stored_key, server_key, iteration_count
>>>
>>> # Define your own function for retrieving the authentication information
>>> # from the database given a username
>>>
>>> def auth_fn(username):
...     return db[username]
>>>
>>> # Make the SCRAM server
>>> s = m.make_server(auth_fn)
>>>
>>> # Now set up the client and carry out authentication with the server
>>> c = ScramClient(MECHANISMS, USERNAME, PASSWORD)
>>> cfirst = c.get_client_first()
>>>
>>> s.set_client_first(cfirst)
>>> sfirst = s.get_server_first()
>>>
>>> c.set_server_first(sfirst)
>>> cfinal = c.get_client_final()
>>>
>>> s.set_client_final(cfinal)
>>> sfinal = s.get_server_final()
>>>
>>> c.set_server_final(sfinal)
>>>
>>> # If it all runs through without raising an exception, the authentication
>>> # has succeeded
```


=== Client only

Here's an example using just the client. The client nonce is specified in order
to give a reproducible example, but in production you'd omit the `c_nonce`
parameter and let `ScramClient` generate a client nonce:

```
>>> from scramp import ScramClient
>>>
>>> USERNAME = 'user'
>>> PASSWORD = 'pencil'
>>> C_NONCE = 'rOprNGfwEbeRWgbNEkqO'
>>> MECHANISMS = ['SCRAM-SHA-256']
>>>
>>> # Normally the c_nonce would be omitted, in which case ScramClient will
>>> # generate the nonce itself.
>>>
>>> c = ScramClient(MECHANISMS, USERNAME, PASSWORD, c_nonce=C_NONCE)
>>>
>>> # Get the client first message and send it to the server
>>> cfirst = c.get_client_first()
>>> print(cfirst)
n,,n=user,r=rOprNGfwEbeRWgbNEkqO
>>>
>>> # Set the first message from the server
>>> c.set_server_first(
...     'r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,'
...     's=W22ZaJ0SNY7soEsUEjb6gQ==,i=4096')
>>>
>>> # Get the client final message and send it to the server
>>> cfinal = c.get_client_final()
>>> print(cfinal)
c=biws,r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,p=dHzbZapWIk4jUhN+Ute9ytag9zjfMHgsqmmiz7AndVQ=
>>>
>>> # Set the final message from the server
>>> c.set_server_final('v=6rriTRBi23WpRR/wtup+mMhUZUn/dB5nLTJRsjl95G4=')
>>>
>>> # If it all runs through without raising an exception, the authentication
>>> # has succeeded
```

=== Server only

Here's an example using just the server. The server nonce and salt is specified
in order to give a reproducible example, but in production you'd omit the
`s_nonce` and `salt` parameters and let Scramp generate them:

```
>>> from scramp import ScramMechanism
>>>
>>> USERNAME = 'user'
>>> PASSWORD = 'pencil'
>>> S_NONCE = '%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0'
>>> SALT = b'[m\x99h\x9d\x125\x8e\xec\xa0K\x14\x126\xfa\x81'
>>>
>>> db = {}
>>>
>>> m = ScramMechanism()
>>>
>>> salt, stored_key, server_key, iteration_count = m.make_auth_info(
...     PASSWORD, salt=SALT)
>>>
>>> db[USERNAME] = salt, stored_key, server_key, iteration_count
>>>
>>> # Define your own function for getting a password given a username
>>> def auth_fn(username):
...     return db[username]
>>>
>>> # Normally the s_nonce parameter would be omitted, in which case the
>>> # server will generate the nonce itself.
>>>
>>> s = m.make_server(auth_fn, s_nonce=S_NONCE)
>>>
>>> # Set the first message from the client
>>> s.set_client_first('n,,n=user,r=rOprNGfwEbeRWgbNEkqO')
>>>
>>> # Get the first server message, and send it to the client
>>> sfirst = s.get_server_first()
>>> print(sfirst)
r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,s=W22ZaJ0SNY7soEsUEjb6gQ==,i=4096
>>>
>>> # Set the final message from the client
>>> s.set_client_final(
...     'c=biws,r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,'
...     'p=dHzbZapWIk4jUhN+Ute9ytag9zjfMHgsqmmiz7AndVQ=')
>>>
>>> # Get the final server message and send it to the client
>>> sfinal = s.get_server_final()
>>> print(sfinal)
v=6rriTRBi23WpRR/wtup+mMhUZUn/dB5nLTJRsjl95G4=
>>>
>>> # If it all runs through without raising an exception, the authentication
>>> # has succeeded
```

=== Server only with passlib

Here's an example using just the server and using the
https://passlib.readthedocs.io/en/stable/index.html[passlib hashing library].
The server nonce and salt is specified in order to give a reproducible example,
but in production you'd omit the `s_nonce` and `salt` parameters and let Scramp
generate them:

```
>>> from scramp import ScramMechanism
>>> from passlib.hash import scram
>>>
>>> USERNAME = 'user'
>>> PASSWORD = 'pencil'
>>> S_NONCE = '%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0'
>>> SALT = b'[m\x99h\x9d\x125\x8e\xec\xa0K\x14\x126\xfa\x81'
>>> ITERATION_COUNT = 4096
>>>
>>> db = {}
>>> hash = scram.using(salt=SALT, rounds=ITERATION_COUNT).hash(PASSWORD)
>>>
>>> salt, iteration_count, digest = scram.extract_digest_info(hash, 'sha-256')
>>> 
>>> stored_key, server_key = m.make_stored_server_keys(digest)
>>>
>>> db[USERNAME] = salt, stored_key, server_key, iteration_count
>>>
>>> # Define your own function for getting a password given a username
>>> def auth_fn(username):
...     return db[username]
>>>
>>> # Normally the s_nonce parameter would be omitted, in which case the
>>> # server will generate the nonce itself.
>>>
>>> m = ScramMechanism()
>>> s = m.make_server(auth_fn, s_nonce=S_NONCE)
>>>
>>> # Set the first message from the client
>>> s.set_client_first('n,,n=user,r=rOprNGfwEbeRWgbNEkqO')
>>>
>>> # Get the first server message, and send it to the client
>>> sfirst = s.get_server_first()
>>> print(sfirst)
r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,s=W22ZaJ0SNY7soEsUEjb6gQ==,i=4096
>>>
>>> # Set the final message from the client
>>> s.set_client_final(
...     'c=biws,r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,'
...     'p=dHzbZapWIk4jUhN+Ute9ytag9zjfMHgsqmmiz7AndVQ=')
>>>
>>> # Get the final server message and send it to the client
>>> sfinal = s.get_server_final()
>>> print(sfinal)
v=6rriTRBi23WpRR/wtup+mMhUZUn/dB5nLTJRsjl95G4=
>>>
>>> # If it all runs through without raising an exception, the authentication
>>> # has succeeded
```



== API Docs


=== scramp.MECHANISMS

A tuple of the supported mechanisms.


=== scramp.ScramClient

`ScramClient(mechanisms, username, password, c_nonce=None)`::
  Constructor of the `ScramClient` class, with the following parameters:
  `mechanisms`:::
    Sequence of mechanism names given by the server. ScramClient will choose
    the most secure one that it supports.
  `username`:::
  `password`:::
  `c_nonce`:::
    The client nonce. It's sometimes useful to set this when testing /
    debugging, but in production this should be omitted, in which case
    `ScramClient` will generate a client nonce.

The `ScramClient` object has the following methods:

`get_client_first()`::
  Get the client first message.
`set_server_first(message)`::
    Set the first message from the server.
`get_client_final()`::
  Get the final client message.
`set_server_final(message)`::
  Set the final message from the server.


=== scramp.ScramMechanism

`ScramMechanism(mechanism='SCRAM-SHA-256')`::
  Constructor of the `ScramMechanism` class, with the following parameter:
  `mechanism`:::
    The SCRAM mechanism to use.

The `ScramMechanism` object has the following methods:

`make_auth_info(password, iteration_count=4096, salt=None)`::
  returns the tuple `(salt, stored_key, server_key, iteration_count)` which is
  stored in the authentication database on the server side. It has the
  following parameters:
  `password`:::
    The user's password as a `str`.
  `iteration_count`:::
    The rounds as an `int`.
  `salt`:::
    It's sometimes useful to set this binary parameter when testing /
    debugging, but in production this should be omitted, in which case a salt
    will be generated.

`make_server(auth_fn, s_nonce=None)`::
    returns a `ScramServer` object. It takes the following parameters:

  `auth_fn`:::
    This is a function provided by the programmer that has one parameter, a
    username of type `str` and returns returns the tuple
    `(salt, stored_key, server_key, iteration_count)`. Where `salt`,
    `stored_key` and `server_key` are of a binary type, and `iteration_count`
    is an `int`.

  `s_nonce`:::
    The server nonce as a `str`. It's sometimes useful to set this when testing
    / debugging, but in production this should be omitted, in which case
    `ScramServer` will generate a server nonce.

`make_stored_server_keys(salted_password)`::
    returns `(stored_key, server_key)` tuple of `bytes` objects given a salted
    password. This is useful if you want to use a separate hashing
    implementation from the one provided by Scramp. It takes the following
    parameter:

  `salted_password`:::
    A binary object representing the hashed password.


=== scramp.ScramServer

The `ScramServer` object has the following methods:

`set_client_first(message)`::
  Set the first message from the client.
`get_server_first()`::
  Get the server first message.
`set_client_final(message)`::
  Set the final client message.
`get_server_final()`::
  Get the server final message.


== Testing

* Activate the virtual environment: `source venv/bin/activate`
* Install `tox`: `pip install tox`
* Run `tox`: `tox`


== Doing A Release Of Scramp

Run `tox` to make sure all tests pass, then update the release notes, then do:

```
git tag -a x.y.z -m "version x.y.z"
rm -r dist
python setup.py sdist bdist_wheel --python-tag py3
for f in dist/*; do gpg --detach-sign -a $f; done
twine upload dist/*
```


== Release Notes

=== Version 1.2.0, 2020-05-30

* This is a backwardly incompatible change on the server side, the client side
  will work as before. The idea of this change is to make it possible to have
  an authentication database. That is, the authentication information can be
  stored, and then retrieved when needed to authenticate the user.

* In addition, it's now possible on the server side to use a third party
  hashing library such as passlib as the hashing implementation.


=== Version 1.1.1, 2020-03-28

* Add the README and LICENCE to the distribution.


=== Version 1.1.0, 2019-02-24

* Add support for the SCRAM-SHA-1 mechanism.


=== Version 1.0.0, 2019-02-17

* Implement the server side as well as the client side.


=== Version 0.0.0, 2019-02-10

* Copied SCRAM implementation from https://github.com/tlocke/pg8000[pg8000].
  The idea is to make it a general SCRAM implemtation. Credit to the
  https://github.com/cagdass/scrampy[Scrampy] project which I read through to
  help with this project. Also credit to the
  https://github.com/efficks/passlib[passlib] project from which I copied the
  `saslprep` function.
