From 68a9d2e8978ef6f50d6ace86da47c59e027c2ecd Mon Sep 17 00:00:00 2001 From: Tom Cocagne Date: Tue, 7 Dec 2010 16:33:07 -0500 Subject: greatly enhanced documentation --- doc/srp.rst | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 104 insertions(+), 12 deletions(-) (limited to 'doc/srp.rst') diff --git a/doc/srp.rst b/doc/srp.rst index 3ae2022..f566763 100644 --- a/doc/srp.rst +++ b/doc/srp.rst @@ -10,24 +10,38 @@ This module provides an implementation of the Secure Remote Password -Protocol (SRP). SRP is a secure, password-based authentication -and key-exhange protocol. It solves the problem of securely -authenticating clients to servers that store a salted verification -key derived from the user's password. Successful authentication proves -that the client knows user's password and that the server knows the -verification key. +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. -The SRP protocol has a number of advantageous properties -* It provides strong authentication +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 does not require a trusted third party (unlike Kerberos & SSL) * It is resists both passive and active network attacks * Compromised verification keys do not allow the attacker to impersonate the client. -See http://srp.stanford.edu/ for a full description of the SRP protocol. + Usage ----- @@ -220,8 +234,13 @@ Simple Usage Example:: # 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!") + # Server => Client: HAMK usr.verify_session( HAMK ) @@ -242,3 +261,76 @@ 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. + + + +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. + +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. + +========= ================================================================= +Variables Description +========= ================================================================= +N A large, safe prime (N = 2q+1, where q is a Sophie Germain prime) + All arithmetic is performed in the field of integers modulo N +g A generator modulo N +s Small salt for the verification key +I Username +p Cleartext password +H() One-way hash function +a,b Secret, random values +K Session key +========= ================================================================= + +============================ ==================================== +Derived Values Description +============================ ==================================== +k = H(N,g) Multiplier Parameter +A = g^a Public ephemeral value +B = kv + g^b Public ephemeral value +x = H( s, H( I | ':' | p ) ) Private key (as defined by RFC 5054) +v = g^x Password verifier +u = H(A,B) Random scrambling parameter +M = H(H(N) xor H(g), H(I), s, A, B, K) Session key verifier +====================================== ==================================== + +The server stores the password verifier *v*. Authentication begins with a +message from the client:: + + client -> server: I, A = g^a + +The server replies with the verifier salt and challenge:: + + server -> client: s, B = kv + g^b + +At this point, both the client and server calculate the shared session key:: + + client & server: u = H(A,B) + +:: + + server: K = H( (Av^u) ^ b ) +:: + + client: x = H( s, H( I + ':' + p ) ) + client: K = H( (B - kg^x) ^ (a + ux) ) + +Now both parties have a shared, strong session key *K*. To complete +authentication they need to prove to each other that their keys match:: + + client -> server: M = H(H(N) xor H(g), H(I), s, A, B, K) + server -> client: H(A, M, K) + +SRP 6a requires the two parties to use the following safeguards: +1) The client will abort if it recieves B == 0 (mod N) or u == 0 +1) The server will abort if it detects A == 0 (mod N) +1) The client must show its proof of K first. If the server detects that this + proof is incorrect it must abort without showing its own proof of K \ No newline at end of file -- cgit v1.2.3