diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/srp.rst | 149 |
1 files changed, 87 insertions, 62 deletions
diff --git a/doc/srp.rst b/doc/srp.rst index 5c4c7bd..5900e4c 100644 --- a/doc/srp.rst +++ b/doc/srp.rst @@ -11,49 +11,55 @@ The Secure Remote Password Protocol (SRP) is a simple and secure protocol for password-based, mutual authentication over an insecure network -connection. Successful SRP authentication proves to the server that the client -has the user's password and proves to the client that the server has the -verification key associated with the user's password. Additionally, successful -SRP authentication results in a cryptographically strong shared key that can be -used to protect network traffic via symmetric key encryption. - -Unlike many other commonly used authentication protocols such as Kerberos & SSL, -SRP does not require a trusted third party. Instead, SRP server applications -store small, salted verification keys that are derived from each user's -password. These keys are then used during the authentication process to verify -the correctness of the remote user's password. - -An advantage of the SRP protocol is that even if the verification keys are -compromized, they are of little value to a potential attacker. Possesion of a -verification key does not allow an attacker to impersonate the user and cannot -be used to obtai the users password except by way of a computationally +connection. Successful SRP authentication proves that both sides of the +connection have knowledge of the user's password. The client side must know the +raw user's password and the server side must have a verification key that is +derived from the user's password. Additionally, successful SRP authentication +results in a cryptographically strong shared key that can be used to protect +network traffic via symmetric key encryption. + +An advantage of SRP over other authentication protocols such as Kerberos and +SSL is that SRP does not require a trusted third party. Instead, SRP server +applications store small, salted verification keys that are derived from each +user's password. These keys are then used during the authentication process to +verify the correctness of the remote user's password. + +A favorable aspect of the SRP protocol is that even if the verification keys +are compromized, they are of little value to a potential attacker. Possesion of +a verification key does not allow an attacker to impersonate the user and +cannot be used to obtain the users password except by way of a computationally infeasible dictionary attack. A compromized key would, however, allow an attacker to impersonate the server side of an SRP authenticated -connection. Consequently, care should be taken to prevent unauthorized access to -verification keys for applications in which the client side requires assurance -of the server's identity. +connection. Consequently, care should be taken to prevent unauthorized access +to verification keys for applications in which the client side requires +assurance of the server's identity. Usage ----- -Use of SRP begins by using the create_salted_verification_key() function to -create a salted verification key from the user's password. The salt and key are -stored on the server and will be used during the authentication process. +Use of SRP begins by using the *create_salted_verification_key()* function to +create a salted verification key from the user's password. The resulting salt +and key are then stored on the server and will be used during the +authentication process. -The rest of the authentication process occurs as an exchange of messages between -the clent and the server. The :ref:`example` below provides a simple -demonstration of the protocol. A comprehensive description of the SRP protocol -is contained in the :ref:`protocol-description` section. +The authentication process occurs as an exchange of messages between the clent +and the server. The :ref:`example` below provides a simple demonstration of the +protocol. A comprehensive description of the SRP protocol is contained in the +:ref:`protocol-description` section. -The User & Verifier construtors, as well as the create_salted_verification_key() -function, take optional hashing algorithm and prime number arguments. Generally -speaking, more bits means more security but comes at the cost of increased -computation time. The hashing and prime number parameters passed to the User and -Verifier constructors must match those used to create the verification key. +The *User* & *Verifier* constructors, as well as the *create_salted_verification_key()* +function, accept optional arguments to specify which hashing algorithm and +prime number arguments should be used during the authentication process. These +options may be used to tune the security/performance tradeoff for an application. +Generally speaking, specifying arguments with a higher number of bits will result +in a greater level of security. However, it will come at the cost of increased +computation time. The parameters passed to the *User* and *Verifier* constructors +must exactly match those passed to *create_salted_verification_key()* +.. _constants: Constants --------- @@ -70,7 +76,9 @@ Constants SHA512 512 ============== ============== -Larger hashing algorithms will result in larger session keys. +.. note:: + + Larger hashing algorithms will result in larger session keys. .. table:: Prime Number Constants @@ -83,19 +91,27 @@ Larger hashing algorithms will result in larger session keys. NG_CUSTOM User Supplied ================= ============== -If NG_CUSTOM is used, the 'n_hex' and 'g_hex' parameters are required. -These parameters must be ASCII text containing hexidecimal notation of the -prime number 'n_hex' and the corresponding generator number 'g_hex'. Appendix -A of RFC 5054 contains several large prime number, generator pairs that may -be used with NG_CUSTOM. +.. note:: + + If NG_CUSTOM is used, the 'n_hex' and 'g_hex' parameters are required. + These parameters must be ASCII text containing hexidecimal notation of the + prime number 'n_hex' and the corresponding generator number 'g_hex'. Appendix + A of RFC 5054 contains several large prime number, generator pairs that may + be used with NG_CUSTOM. Functions --------- .. function:: create_salted_verification_key ( username, password[, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None] ) - Generates a salt and verifier for the given username and password. - Returns (salt_bytes, verifier_bytes) + *username* Name of the user + + *password* Plaintext user password + + *hash_alg*, *ng_type*, *n_hex*, *g_hex* Refer to the :ref:`constants` section. + + Generate a salted verification key for the given username and password and return the tuple: + (salt_bytes, verification_key_bytes) :class:`Verifier` Objects @@ -115,33 +131,35 @@ user. *bytes_s* Salt generated by :func:`create_salted_verification_key`. - *bytes_v* Verifier generated by :func:`create_salted_verification_key`. + *bytes_v* Verification Key generated by :func:`create_salted_verification_key`. *bytes_A* Challenge from the remote user. Generated by :meth:`User.start_authentication` + + *hash_alg*, *ng_type*, *n_hex*, *g_hex* Refer to the :ref:`constants` section. .. method:: Verifier.authenticated() - Returns True if the authentication succeeded. False + Return True if the authentication succeeded. False otherwise. .. method:: Verifier.get_username() - Returns the name of the user this :class:`Verifier` object is for. + Return the name of the user this :class:`Verifier` object is for. .. method:: Verifier.get_session_key() - Returns the session key for an authenticated user or None if the + Return the session key for an authenticated user or None if the authentication failed or has not yet completed. .. method:: Verifier.get_challenge() - Returns (bytes_s, bytes_B) on success or (None, None) if + Return (bytes_s, bytes_B) on success or (None, None) if authentication has failed. .. method:: Verifier.verify_session( user_M ) - Completes the :class:`Verifier` side of the authentication + Complete the :class:`Verifier` side of the authentication process. If the authentication succeded the return result, bytes_H_AMK should be returned to the remote user. On failure, this method returns None. @@ -150,39 +168,40 @@ user. :class:`User` Objects ------------------------- -A :class:`User` object is used to perform mutual authentication with a remote -:class:`Verifier`. Successful authentication requires not only that the -:class:`User` be provided with a valid username/password but also that the -remote :class:`Verifier` have a salt & verifier for that username/password pair. +A :class:`User` object is used to prove a user's identity to a remote :class:`Verifier` and +verifiy that the remote :class:`Verifier` knows the verification key associated with +the user's password. .. class:: User( username, password[, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None] ) *username* Name of the user being authenticated. *password* Password for the user. + + *hash_alg*, *ng_type*, *n_hex*, *g_hex* Refer to the :ref:`constants` section. .. method:: User.authenticated() - Returns True if authentication succeeded. False + Return True if authentication succeeded. False otherwise. .. method:: User.get_username() - Returns the username passed to the constructor. + Return the username passed to the constructor. .. method:: User.get_session_key() - Returns the session key if authentication succeeded or None if the + Return the session key if authentication succeeded or None if the authentication failed or has not yet completed. .. method:: User.start_authentication() - Returns (username, bytes_A). These should be passed to the + Return (username, bytes_A). These should be passed to the constructor of the remote :class:`Verifer` .. method:: User.process_challenge( bytes_s, bytes_B ) - Processes the challenge returned + Processe the challenge returned by :meth:`Verifier.get_challenge` on success this method returns bytes_M that should be sent to :meth:`Verifier.verify_session` if authentication failed, @@ -190,7 +209,7 @@ remote :class:`Verifier` have a salt & verifier for that username/password pair. .. method:: User.verify_session( bytes_H_AMK ) - Completes the :class:`User` side of the authentication + Complete the :class:`User` side of the authentication process. If the authentication succeded :meth:`authenticated` will return True @@ -205,7 +224,10 @@ Simple Usage Example:: # The salt and verifier returned from srp.create_salted_verification_key() should be # stored on the server. - salt, verifier = srp.create_salted_verification_key( 'testuser', 'testpassword' ) + salt, vkey = srp.create_salted_verification_key( 'testuser', 'testpassword' ) + + class AuthenticationFailed (Exception): + pass # ~~~ Begin Authentication ~~~ @@ -217,20 +239,23 @@ Simple Usage Example:: # process should be aborted on the first failure. # Client => Server: username, A - svr = srp.Verifier( uname, salt, verifier, A ) + svr = srp.Verifier( uname, salt, vkey, A ) s,B = svr.get_challenge() + + if s is None or B is None: + raise AuthenticationFailed() # Server => Client: s, B M = usr.process_challenge( s, B ) + + if M is None: + raise AuthenticationFailed() # Client => Server: M HAMK = svr.verify_session( M ) - # SRP 6a requies the server to abort authentication and to specifically - # NOT send the HAMK message to the client if detects failed authentication - # at this point: - if not svr.authenticated(): - raise Exception("authentication failed!") + if HAMK is None: + raise AuthenticationFailed() # Server => Client: HAMK usr.verify_session( HAMK ) |