Package: scramp
A Python implementation of theSCRAM authentication protocol.
Scramp supports the following mechanisms:SCRAM-SHA-1SCRAM-SHA-1-PLUSSCRAM-SHA-256SCRAM-SHA-256-PLUSSCRAM-SHA-512SCRAM-SHA-512-PLUSSCRAM-SHA3-512SCRAM-SHA3-512-PLUSTable of ContentsInstallationExamplesClient and ServerClient onlyServer onlyServer only with passlibServer ErrorStandardsAPI Docsscramp.MECHANISMSscramp.ScramClientscramp.ScramMechanismscramp.ScramServerscramp.make_channel_binding()README.rstTestingDoing A Release Of ScrampRelease NotesVersion 1.4.4, 2022-11-01Version 1.4.3, 2022-10-26Version 1.4.2, 2022-10-22Version 1.4.1, 2021-08-25Version 1.4.0, 2021-03-28Version 1.3.0, 2021-03-28Version 1.2.2, 2021-02-13Version 1.2.1, 2021-02-07Version 1.2.0, 2020-05-30Version 1.1.1, 2020-03-28Version 1.1.0, 2019-02-24Version 1.0.0, 2019-02-17Version 0.0.0, 2019-02-10InstallationCreate a virtual environment:python3-mvenv venvActivate the virtual environment:source venv/bin/activateInstall:pip install scrampExamplesClient and ServerHere’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 succeededClient onlyHere’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 thec_nonceparameter and letScramClientgenerate 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 succeededServer onlyHere’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 thes_nonceandsaltparameters 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 succeededServer only with passlibHere’s an example using just the server and using thepasslib hashing library. The server nonce and salt is
specified in order to give a reproducible example, but in production you’d omit thes_nonceandsaltparameters 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 succeededServer ErrorHere’s an example of when setting a message from the client causes an error. The server
nonce and salt is specified in order to give a reproducible example, but in production
you’d omit thes_nonceandsaltparameters and let Scramp generate them:>>> from scramp import ScramException, 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)
>>>
>>> try:
...     # Set the first message from the client
...     s.set_client_first('p=tls-unique,,n=user,r=rOprNGfwEbeRWgbNEkqO')
... except ScramException as e:
...     print(e)
...     # Get the final server message and send it to the client
...     sfinal = s.get_server_final()
...     print(sfinal)
Received GS2 flag 'p' which indicates that the client requires channel binding, but the server does not: channel-binding-not-supported
e=channel-binding-not-supportedStandardsRFC 5802Describes SCRAM.RFC 7677Registers SCRAM-SHA-256 and SCRAM-SHA-256-PLUS.draft-melnikov-scram-sha-512-02Registers SCRAM-SHA-512 and SCRAM-SHA-512-PLUS.draft-melnikov-scram-sha3-512Registers SCRAM-SHA3-512 and SCRAM-SHA3-512-PLUS.RFC 5929Channel Bindings for TLS.draft-ietf-kitten-tls-channel-bindings-for-tls13Defines thetls-exporterchannel binding, which isnot yet supported by Scramp.API Docsscramp.MECHANISMSA tuple of the supported mechanism names.scramp.ScramClientScramClient(mechanisms, username, password, channel_binding=None, c_nonce=None)Constructor of theScramClientclass, with the following parameters:mechanismsA list or tuple of mechanism names. ScramClient will choose the most secure. Ifcbind_dataisNone, the ‘-PLUS’ variants will be filtered out first. The
chosen mechanism is available as the propertymechanism_name.usernamepasswordchannel_bindingProviding a value for this parameter allows channel binding to be used (ie. it lets
you use mechanisms ending in ‘-PLUS’). The value forchannel_bindingis a tuple
consisting of the channel binding name and the channel binding data. For example, if
the channel binding name istls-unique, thechannel_bindingparameter would
be('tls-unique',data), wheredatais obtained by callingSSLSocket.get_channel_binding().
The convenience functionscramp.make_channel_binding()can be used to create a
channel binding tuple.c_nonceThe client nonce. It’s sometimes useful to set this when testing / debugging, but in
production this should be omitted, in which caseScramClientwill generate a
client nonce.TheScramClientobject has the following methods and properties: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.mechanism_nameThe mechanism chosen from the list given in the constructor.scramp.ScramMechanismScramMechanism(mechanism='SCRAM-SHA-256')Constructor of theScramMechanismclass, with the following parameter:mechanismThe SCRAM mechanism to use.TheScramMechanismobject has the following methods and properties:make_auth_info(password, iteration_count=None, 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:passwordThe user’s password as astr.iteration_countThe rounds as anint. IfNonethen use the minimum associated with the
mechanism.saltIt’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, channel_binding=None, s_nonce=None)returns aScramServerobject. It takes the following parameters:auth_fnThis is a function provided by the programmer that has one parameter, a username of
typestrand returns returns the tuple(salt, stored_key, server_key, iteration_count). Wheresalt,stored_keyandserver_keyare of a
binary type, anditeration_countis anint.channel_bindingProviding a value for this parameter allows channel binding to be used (ie.  it lets
you use mechanisms ending in-PLUS). The value forchannel_bindingis a
tuple consisting of the channel binding name and the channel binding data. For
example, if the channel binding name is ‘tls-unique’, thechannel_bindingparameter would be('tls-unique',data), wheredatais obtained by callingSSLSocket.get_channel_binding().
The convenience functionscramp.make_channel_binding()can be used to create a
channel binding tuple. Ifchannel_bindingis provided and the mechanism isn’t a-PLUSvariant, then the server will negotiate with the client to use the-PLUSvariant if the client supports it, or otherwise to use the mechanism
without channel binding.s_nonceThe server nonce as astr. It’s sometimes useful to set this when testing /
debugging, but in production this should be omitted, in which caseScramServerwill generate a server nonce.make_stored_server_keys(salted_password)returns(stored_key, server_key)tuple ofbytesobjects 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_passwordA binary object representing the hashed password.iteration_countThe minimum iteration count recommended for this mechanism.scramp.ScramServerTheScramServerobject 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.scramp.make_channel_binding()make_channel_binding(name, ssl_socket)A helper function that makes achannel_bindingtuple when given a channel binding
name and an SSL socket. The parameters are:nameA channel binding name such as ‘tls-unique’ or ‘tls-server-end-point’.ssl_socketAn instance ofssl.SSLSocket.README.rstThis file is written in thereStructuredTextformat. To generate an
HTML page from it, do:Activate the virtual environment:source venv/bin/activateInstallSphinx:pip install SphinxRunrst2html.py:rst2html.py README.rst README.htmlTestingActivate the virtual environment:source venv/bin/activateInstalltox:pip install toxRuntox:toxDoing A Release Of ScrampRuntoxto 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 -m build
twine upload --sign dist/*Release NotesVersion 1.4.4, 2022-11-01Tighten up parsing of messages to make sure that aScramExceptionis raised if a
message is malformed.Version 1.4.3, 2022-10-26The client now sends a gs2-cbind-flag of ‘y’ if the client supports channel
binding, but thinks the server does not.Version 1.4.2, 2022-10-22Switch to using the MIT-0 licencehttps://choosealicense.com/licenses/mit-0/When creating a ScramClient, allow non-PLUSvariants, even if achannel_bindingparameter is provided. Previously this would raise and
exception.Version 1.4.1, 2021-08-25When usingmake_channel_binding()to create a tls-server-end-point channel
binding, support certificates with hash algorithm of sha512.Version 1.4.0, 2021-03-28Raise an exception if the client receives an error from the server.Version 1.3.0, 2021-03-28As the specification allows, server errors are now sent to the client in theserver_finalmessage, an exception is still thrown as before.Version 1.2.2, 2021-02-13Fix bug in generating the AuthMessage. It was incorrect when channel binding
was used. So now Scramp supports channel binding.Version 1.2.1, 2021-02-07Add support for channel binding.Add support for SCRAM-SHA-512 and SCRAM-SHA3-512 and their channel binding
variants.Version 1.2.0, 2020-05-30This 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-28Add the README and LICENCE to the distribution.Version 1.1.0, 2019-02-24Add support for the SCRAM-SHA-1 mechanism.Version 1.0.0, 2019-02-17Implement the server side as well as the client side.Version 0.0.0, 2019-02-10Copied SCRAM implementation frompg8000. The
idea is to make it a general SCRAM implemtation. Credit to theScrampyproject which I read through to help with this
project. Also credit to thepasslibproject
from which I copied thesaslprepfunction.