sirp 2.0.0.pre → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 09ad55f348720fdef0cd77d90bc9f166db80cc59
-  data.tar.gz: 0b664333742d32311c3e6a8b3269cdd482fa395f
+  metadata.gz: 5c52dff2045e6a63899115731fa0b6b47c211e83
+  data.tar.gz: b39d228ae76c0afb76e228203025ef9c3ebfd33d
 SHA512:
-  metadata.gz: d89cecbbf3761e596eba3953adcb22af3ca25507068d0186728a6febb3fc72e6549885b04fa202d25eef736eab066eed22cdc59b4f2dfc59193bbd4a29a513c4
-  data.tar.gz: 9e0b5e09f86ec07eb5db4ad2c61509749ae7e38c36645b39101fa21ce2dd0ddb6692a984e9a6896ba61e6cbe376172ba0a14beaa698b7c268954d7e82e13c1b4
+  metadata.gz: e13201e91458fd8f6d69e70482038a37007bd8faff54ca83c2b4ffa87be1f4906a49480ef3256152dde8b18fd1955566dbfc4b733ad1257fe159077aa8456f06
+  data.tar.gz: 2f129346aa66933aecbdb7ed76d26e32ac67a423a03ae291e3d995c9e8c1de6a3786bfa1c7975556f3d0d648da5097a88635aa2eff8dae544df1c2c121a58fe0

data/.gitignore

@@ -9,3 +9,5 @@
 /tmp/
 /examples/.bundle/
 /examples/Gemfile.lock
+.DS_Store
+

data/.rubocop.yml

@@ -30,3 +30,7 @@ Style/FormatString:
 
 Style/MethodName:
   Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+  

data/.yardopts

@@ -0,0 +1 @@
+--no-private  lib/**/*.rb - README.md LICENSE.txt CODE_OF_CONDUCT.md

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v2.0.0 (9/20/2016)
+
+Initial release after shake-down in a real app.
+
 ## v2.0.0.pre (5/13/2016)
 
 This is the initial pre-release of the sirp gem.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at glenn@rempe.us. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/README.md

@@ -9,29 +9,47 @@
 
 Ruby Docs : [http://www.rubydoc.info/gems/sirp](http://www.rubydoc.info/gems/sirp)
 
-
 This is a pure Ruby implementation of the
 [Secure Remote Password](http://srp.stanford.edu/) protocol (SRP-6a),
 which is a 'zero-knowledge' mutual authentication system.
 
-SiRP is an authentication method that allows the use of user names and passwords
-over an insecure network connection without revealing the password. If either the
-client lacks the user's password or the server lacks the proper verification
-key, the authentication will fail. This approach is much more secure than the
-vast majority of authentication systems in daily use since the password is
-***never*** sent over the wire, and is therefore impossible to intercept, and
-impossible to be revealed in a breach unless the verifier can be reversed. This
-attack would be of similar difficulty as deriving a private encryption key from
-its public key.
+SRP is an protocol that allows for mutual authentication of a client and
+server over an insecure network connection without revealing the password to the
+server or an eavesdropper. If the client lacks the user's password, or the server
+lacks the proper verification key, the authentication will fail. This approach
+is much more secure than the vast majority of authentication systems in common use
+since the password is never sent over the wire. The password is impossible to
+intercept, or to be revealed in a server breach, unless the verifier can be
+reversed. Since the verifier is derived from the password + salt through
+cryptographic one-way hash functions and Modular Exponentiation. Attacking the
+verifier to retrieve a password would be of similar difficulty
+as deriving a private encryption key from its public key. Extremely difficult, if
+not impossible.
 
 Unlike other common challenge-response authentication protocols, such as
-Kerberos and SSL, SiRP does not rely on an external infrastructure of trusted
+Kerberos and SSL, SRP does not rely on an external infrastructure of trusted
 key servers or complex certificate management.
 
+At the end of the authentication process both the client and the server will have
+negotiated a shared strong encryption key suitable for encrypted session
+communications. This key is negotiated through a modified Diffie-Hellman
+key exchange and the key is never sent over the wire.
+
+SiRP is designed to be interoperable with a Ruby client and server, or
+with Ruby on the server side, and the [JSRP](https://github.com/alax/jsrp)
+Javascript client running in a browser.
+
+## Live Demo
+
+You can try out an interactive demo at
+[https://sirp-demo.herokuapp.com/index.html](https://sirp-demo.herokuapp.com/index.html).
+
+[Demo Source Code @ grempe/sirp-demo](https://github.com/grempe/sirp-demo)
+
 ## Documentation
 
 There is pretty extensive inline documentation. You can view the latest
-auto-generated docs at [http://www.rubydoc.info/gems/sirp](http://www.rubydoc.info/gems/sirp)
+API docs at [http://www.rubydoc.info/gems/sirp](http://www.rubydoc.info/gems/sirp)
 
 You can check my documentation quality score at
 [http://inch-ci.org/github/grempe/sirp](http://inch-ci.org/github/grempe/sirp?branch=master)
@@ -40,9 +58,11 @@ You can check my documentation quality score at
 
 SiRP is continuously integration tested on the following Ruby VMs:
 
-* MRI 2.1, 2.2, 2.3
+* MRI 2.1
+* MRI 2.2
+* MRI 2.3
 
-It may work on others as well.
+Ruby versions < 2.1 are not supported.
 
 ## Installation
 
@@ -119,11 +139,83 @@ compliant third-party libraries:
 
 [JSRP / JavaScript](https://github.com/alax/jsrp)
 
+## SRP-6a Protocol Design
+
+Extracted from [http://srp.stanford.edu/design.html](http://srp.stanford.edu/design.html)
+
+```
+SRP is the newest addition to a new class of strong authentication protocols
+that resist all the well-known passive and active attacks over the network.
+SRP borrows some elements from other key-exchange and identification protcols
+and adds some subtle modifications and refinements. The result is a protocol
+that preserves the strength and efficiency of the EKE family protocols while
+fixing some of their shortcomings.
+
+The following is a description of SRP-6 and 6a, the latest versions of SRP:
+
+  N    A large safe prime (N = 2q+1, where q is prime)
+       All arithmetic is done modulo N.
+  g    A generator modulo N
+  k    Multiplier parameter (k = H(N, g) in SRP-6a, k = 3 for legacy SRP-6)
+  s    User's salt
+  I    Username
+  p    Cleartext Password
+  H()  One-way hash function
+  ^    (Modular) Exponentiation
+  u    Random scrambling parameter
+  a,b  Secret ephemeral values
+  A,B  Public ephemeral values
+  x    Private key (derived from p and s)
+  v    Password verifier
+
+The host stores passwords using the following formula:
+
+  x = H(s, p)               (s is chosen randomly)
+  v = g^x                   (computes password verifier)
+
+The host then keeps {I, s, v} in its password database. The authentication
+protocol itself goes as follows:
+
+User -> Host:  I, A = g^a                  (identifies self, a = random number)
+Host -> User:  s, B = kv + g^b             (sends salt, b = random number)
+
+        Both:  u = H(A, B)
+
+        User:  x = H(s, p)                 (user enters password)
+        User:  S = (B - kg^x) ^ (a + ux)   (computes session key)
+        User:  K = H(S)
+
+        Host:  S = (Av^u) ^ b              (computes session key)
+        Host:  K = H(S)
+
+Now the two parties have a shared, strong session key K. To complete
+authentication, they need to prove to each other that their keys match.
+One possible way:
+
+User -> Host:  M = H(H(N) xor H(g), H(I), s, A, B, K)
+Host -> User:  H(A, M, K)
+
+The two parties also employ the following safeguards:
+
+* The user will abort if he receives B == 0 (mod N) or u == 0.
+* The host will abort if it detects that A == 0 (mod N).
+* The user must show his proof of K first. If the server detects that the
+user's proof is incorrect, it must abort without showing its own proof of K.
+```
+
 ## Usage Example
 
 In this example the client and server steps are interleaved for demonstration
-purposes. See the `examples` dir for simple working client and server
-implementations.
+purposes. See the [grempe/sirp-demo](https://github.com/grempe/sirp-demo)
+repository for working sample code and a live demo. The phases of authentication
+in this example are delineated by the HTTPS request/response between client and
+server. The concept of 'phases' is something noted here for convenience. The
+specification makes no mention of phases since it is implementation specific.
+
+This example is useful for showing the ordering and arguments in the public
+API and is not intended to be a 'copy & paste' code sample since the
+client and server interaction is something left up to the implementer and likely
+different in every case.
 
 ``` ruby
 require 'sirp'
@@ -132,22 +224,42 @@ username     = 'user'
 password     = 'password'
 prime_length = 2048
 
-# The salt and verifier should be stored on the server database.
+# ~~~ Phase 0 : User Registration ~~~
+
+# One time only! SRP is a form of TOFU (Trust On First Use) authentication
+# where all is predicated on the client being able to register a verifier
+# with the server upon initial registration. The server promises in turn to
+# keep this verifier secret and never reveal it. If this first interaction
+# is compromised then all is lost. If the verifier is revealed then there
+# is a theoretical attack on the verifier which could reveal information
+# about the password. It is likely cryptographically difficult though.
+# It is important that the username and password combination be of
+# high entropy.
+
+# The salt and verifier should be persisted server-side, accessible by
+# looking up via the username. The server must protect the verifier but
+# will return the salt to any party requesting authentication who knows
+# the username.
+
 @auth = SIRP::Verifier.new(prime_length).generate_userauth(username, password)
-# @auth is a hash containing :username, :verifier and :salt
+# => {username: '...', verifier: '...', salt: '...'}
 
-# ~~~ Begin Authentication ~~~
+# ~~~ Phase 1 : Challenge/Response ~~~
 
 client = SIRP::Client.new(prime_length)
 A = client.start_authentication
 
-# Client => Server: username, A
+# HTTPS POST Client => Server: request includes 'username' and  'A'
 
-# Server retrieves user's verifier and salt from the database.
+# Server retrieves user's verifier and salt from the database by
+# looking up these values indexed by 'username'. Here simulated
+# by using the @auth hash directly.
 v    = @auth[:verifier]
 salt = @auth[:salt]
 
-# Server generates challenge for the client.
+# Server generates a challenge for the client and a proof it will require
+# in Phase 2 of the auth process. The challenge is given to the client, the
+# proof is temporarily persisted.
 verifier = SIRP::Verifier.new(prime_length)
 session = verifier.get_challenge_and_proof(username, v, salt, A)
 
@@ -157,29 +269,49 @@ session = verifier.get_challenge_and_proof(username, v, salt, A)
 # Server sends the challenge containing salt and B to client.
 response = session[:challenge]
 
-# Server => Client: salt, B
+# HTTPS Server => Client: response includes 'salt', and 'B'
 
-# Client calculates M as a response to the challenge.
+# ~~~ Phase 2 : Continue Authentication ~~~
+
+# Client calculates M as a response to the challenge using the
+# username and password and the server provided 'salt' and 'B'.
 client_M = client.process_challenge(username, password, salt, B)
 
-# Client => Server: username, M
+# HTTPS POST Client => Server: request includes 'username', and 'M'
 
 # Instantiate a new verifier on the server.
 verifier = SIRP::Verifier.new(prime_length)
 
-# Verify challenge response M.
-# The Verifier state is passed in @proof.
+# Verify challenge response M against the Verifier proof stored earlier.
+# server_H_AMK returned will be 'false' if verification failed.
 server_H_AMK = verifier.verify_session(@proof, client_M)
-# Is false if authentication failed.
-
-# At this point, the client and server should have a common session key
-# that is secure (i.e. not known to an outside party).  To finish
-# authentication, they must prove to each other that their keys are
-# identical.
 
-# Server => Client: H(AMK)
-
-client.verify(server_H_AMK) == true
+# At this point, the client and server should have a common session key (K)
+# that is secure and unknown to any outside party. Before they can safely use
+# it though they must prove to each other that their keys are identical by
+# exchanging a hash H(A,M,K). This step allows both client and server to be
+# certain they arrived at the same values independently.
+
+# The server sends a response based on the results of verify_session.
+
+if server_H_AMK
+  # HTTPS Server => Client: response includes server_H_AMK
+else
+  # Do NOT include the server_H_AMK in the response.
+  # HTTPS Server => Client: 401 Unauthorized
+end
+
+# The client compares server_H_AMK response to its own calculated H(A,M,K).
+
+if client.verify(server_H_AMK)
+  ####  SUCCESS ####
+  # Client and server have mutually authenticated.
+  # Optional : Use this secret key to derive shared encryption keys for some
+  # other application specific use.
+  secret_key = client.K
+else
+  # FAIL, THROW IT ALL AWAY AND START OVER!
+end
 
 ```
 
@@ -200,6 +332,8 @@ interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+The formal release process can be found in [RELEASE.md](https://github.com/grempe/sirp/blob/master/RELEASE.md)
+
 ### Contributing
 
 Bug reports and pull requests are welcome on GitHub

data/lib/sirp.rb

@@ -1,8 +1,10 @@
 require 'openssl'
 require 'digest'
 require 'rbnacl/libsodium'
-require 'securer_randomer'
+require 'sysrandom/securerandom'
+require 'hashie'
 require 'sirp/sirp'
+require 'sirp/parameters'
 require 'sirp/client'
 require 'sirp/verifier'
 require 'sirp/version'

data/lib/sirp/client.rb

@@ -1,50 +1,96 @@
 module SIRP
   class Client
+    include SIRP
     attr_reader :N, :g, :k, :a, :A, :S, :K, :M, :H_AMK, :hash
 
+    # Select modulus (N), generator (g), and one-way hash function (SHA1 or SHA256)
+    #
+    # @param group [Integer] the group size in bits
     def initialize(group = 2048)
-      # select modulus (N) and generator (g)
-      @N, @g, @hash = SIRP.Ng(group)
-      @k = SIRP.calc_k(@N, @g, hash)
+      raise ArgumentError, 'must be an Integer' unless group.is_a?(Integer)
+      raise ArgumentError, 'must be a known group size' unless [1024, 1536, 2048, 3072, 4096, 6144, 8192].include?(group)
+
+      @N, @g, @hash = Ng(group)
+      @k = calc_k(@N, @g, hash)
     end
 
+    # Phase 1 : Step 1 : Start the authentication process by generating the
+    # client 'a' and 'A' values. Public 'A' should later be sent along with
+    # the username, to the server verifier to continue the auth process. The
+    # internal secret 'a' value should remain private.
+    #
+    # @return [String] the value of 'A' in hex
     def start_authentication
-      # Generate a/A private and public components
       @a ||= SecureRandom.hex(32).hex
-      @A = SIRP.num_to_hex(SIRP.calc_A(@a, @N, @g))
+      @A = num_to_hex(calc_A(@a, @N, @g))
     end
 
-    # Process initiated authentication challenge.
-    # Returns M if authentication is successful, false otherwise.
-    # Salt and B should be given in hex.
+    #
+    # Phase 1 : Step 2 : See Verifier#get_challenge_and_proof(username, xverifier, xsalt, xaa)
+    #
+
+    # Phase 2 : Step 1 : Process the salt and B values provided by the server.
+    #
+    # @param username [String] the client provided authentication username
+    # @param password [String] the client provided authentication password
+    # @param xsalt [String] the server provided salt for the username in hex
+    # @param xbb [String] the server verifier 'B' value in hex
+    # @return [String] the client 'M' value in hex
     def process_challenge(username, password, xsalt, xbb)
+      raise ArgumentError, 'username must be a string' unless username.is_a?(String) && !username.empty?
+      raise ArgumentError, 'password must be a string' unless password.is_a?(String) && !password.empty?
+      raise ArgumentError, 'xsalt must be a string' unless xsalt.is_a?(String)
+      raise ArgumentError, 'xsalt must be a hex string' unless xsalt =~ /^[a-fA-F0-9]+$/
+      raise ArgumentError, 'xbb must be a string' unless xbb.is_a?(String)
+      raise ArgumentError, 'xbb must be a hex string' unless xbb =~ /^[a-fA-F0-9]+$/
+
+      # Convert the 'B' hex value to an Integer
       bb = xbb.to_i(16)
 
       # SRP-6a safety check
-      return false if (bb % @N) == 0
+      return false if (bb % @N).zero?
 
-      x = SIRP.calc_x(username, password, xsalt, hash)
-      u = SIRP.calc_u(@A, xbb, @N, hash)
+      x = calc_x(username, password, xsalt, hash)
+      u = calc_u(@A, xbb, @N, hash)
 
       # SRP-6a safety check
-      return false if u == 0
+      return false if u.zero?
 
-      # calculate session key
-      @S = SIRP.num_to_hex(SIRP.calc_client_S(bb, @a, @k, x, u, @N, @g))
-      @K = SIRP.sha_hex(@S, hash)
+      # Calculate session key 'S' and secret key 'K'
+      @S = num_to_hex(calc_client_S(bb, @a, @k, x, u, @N, @g))
+      @K = sha_hex(@S, hash)
 
-      # calculate match
-      @M = SIRP.calc_M(@A, xbb, @K, hash)
+      # Calculate the 'M' matcher
+      @M = calc_M(@A, xbb, @K, hash)
 
-      # calculate verifier
-      @H_AMK = SIRP.num_to_hex(SIRP.calc_H_AMK(@A, @M, @K, hash))
+      # Calculate the H(A,M,K) verifier
+      @H_AMK = num_to_hex(calc_H_AMK(@A, @M, @K, hash))
 
+      # Return the 'M' matcher to be sent to the server
       @M
     end
 
+    #
+    # Phase 2 : Step 2 : See Verifier#verify_session(proof, client_M)
+    #
+
+    # Phase 2 : Step 3 : Verify that the server provided H(A,M,K) value
+    # matches the client generated version. This is the last step of mutual
+    # authentication and confirms that the client and server have
+    # completed the auth process. The comparison of local and server
+    # H_AMK values is done using a secure constant-time comparison
+    # method so as not to leak information.
+    #
+    # @param server_HAMK [String] the server provided H_AMK in hex
+    # @return [true,false] returns true if the server and client agree on the H_AMK value, false if not
     def verify(server_HAMK)
-      return false unless @H_AMK
-      @H_AMK == server_HAMK
+      return false unless @H_AMK && server_HAMK
+      return false unless server_HAMK.is_a?(String)
+      return false unless server_HAMK =~ /^[a-fA-F0-9]+$/
+
+      # Hash the comparison params to ensure that both strings
+      # being compared are equal length 32 Byte strings.
+      secure_compare(Digest::SHA256.hexdigest(@H_AMK), Digest::SHA256.hexdigest(server_HAMK))
     end
   end
 end