From d6d2c59a9c4bf8d2407fb3f1d1d6a8d7b396dddf Mon Sep 17 00:00:00 2001 From: Tom Cocagne Date: Thu, 13 Jan 2011 00:23:38 -0500 Subject: reworded introduction --- doc/srp.rst | 115 +++++++++++++++++++++++++++--------------------------------- 1 file changed, 51 insertions(+), 64 deletions(-) (limited to 'doc/srp.rst') diff --git a/doc/srp.rst b/doc/srp.rst index 4a593c4..5c4c7bd 100644 --- a/doc/srp.rst +++ b/doc/srp.rst @@ -9,58 +9,49 @@ .. sectionauthor:: Tom Cocagne -This module provides an implementation of the Secure Remote Password -Protocol (SRP). SRP is a simple and secure protocol for password-based, mutual -authentication. Successful SRP authentication proves that the client knows -the user's password and proves that the server knows the verification key -that was derived from the user's password at the time it was set. An -additional benefit of SRP is that successful authentication results in a -cryptographically strong shared key that can be used for symmetric key -encryption. - -Unlike Kerberos & SSL, SRP does not require a trusted third party. The -server simply needs to store a salted verification key that is derived -from the user's password. This verification key should be protected as it's -compromise would allow an attacker to impersonate the server. - -An advantage of the SRP protocol is that, even in the event that the -verification key is compromised, the protocol remains reasonably secure. While -an attacker would be able to impersonate the server side of a connection, he or -she would not be able to directly impersonate a user or discover the user's -password. It would require a computationally infeasible dictionary attack to -obtain the user's password from the verification key. - - -Briefly stated, the advantages of SRP are: - -* It does not require a trusted third party (unlike Kerberos & SSL) -* It provides strong, mutual authentication -* Successful authentication results in a cryptographically strong shared key - that may be used for subsequent symmetric-key encryption. -* It is resists both passive and active network attacks -* Compromised verification keys do not allow the attacker to impersonate the - client. +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 +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. 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 salt and key are +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 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 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. +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. @@ -159,11 +150,10 @@ 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 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. .. class:: User( username, password[, hash_alg=SHA1, ng_type=NG_1024, n_hex=None, g_hex=None] ) @@ -230,11 +220,9 @@ Simple Usage Example:: svr = srp.Verifier( uname, salt, verifier, A ) s,B = svr.get_challenge() - # Server => Client: s, B M = usr.process_challenge( s, B ) - # Client => Server: M HAMK = svr.verify_session( M ) @@ -256,14 +244,14 @@ Simple Usage Example:: Implementation Notes -------------------- -This implementation of SRP consists of both a pure-python module and -a C-based implementation that is approximately 10x faster. By default, -the C-implementation will be used if it is available. An additional -benefit of the C implementation is that it can take advantage of -of multiple CPUs. For cases in which the number of connections per -second is an issue, using a small pool of threads to perform the -authentication steps on multi-core systems will yield a substantial -performance increase. + +This implementation of SRP consists of both a pure-python module and a C-based +implementation that is approximately 10x faster. By default, the +C-implementation will be used if it is available. An additional benefit of the C +implementation is that it can take advantage of of multiple CPUs. For cases in +which the number of connections per second is an issue, using a small pool of +threads to perform the authentication steps on multi-core systems will yield a +substantial performance increase. .. _protocol-description: @@ -271,14 +259,13 @@ performance increase. SRP 6a Protocol Description --------------------------- -For the original, authoritative definition of SRP-6a please -refer to http://srp.stanford.edu. RFC 5054 also contains SRP related -information and is the source of the predefined N and g constants used -in this implementation. +For the original, authoritative definition of SRP-6a please refer to +http://srp.stanford.edu. RFC 5054 also contains SRP related information and is +the source of the predefined N and g constants used in this implementation. -The following is a complete description of the SRP-6a protocol as implemented -by this library. Note that the ^ symbol indicates exponentiaion and the | -symbol indicates concatenation. +The following is a complete description of the SRP-6a protocol as implemented by +this library. Note that the ^ symbol indicates exponentiaion and the | symbol +indicates concatenation. .. rubric:: Primary Variables used in SRP 6a -- cgit v1.2.3