Class EjwsSecureBasicAuth


public class EjwsSecureBasicAuth extends BasicAuthenticator
Implementation of BasicAuthenticator supporting secure basic authentication.

As a protocol, secure basic authentication is identical to basic authentication as described in RFC 7617. The differences are in how passwords are created and compared, and in how realms are named. Generally, a secure-basic-authentication password is a URL-safe, base 64 encoding of a sequence of bytes. The first four bytes is a time stamp of a 32 bit two's complement integer, stored in little-endian byte order, providing the time at which the password was created as the number of seconds since 1970-01-01T00:00:00Z. The next four bytes is a 32-bit CRC of the first 4 bytes of the sequence followed by the password as an array of bytes using the UTF-8 character encoding. The remainder of the sequence is either

  1. a SHA-256 message digest of (1) the first eight bytes of the sequence and (2) a password using the UTF-8 character encoding.
  2. a digital signature of (1) the first eight bytes of the sequence and (2) a password using the UTF-8 character encoding.
  3. a digital signature of (1) the first eight bytes of the sequence, (2) the DER encoding of the public key provided in an SSL certificate, and (3) a password using the UTF-8 character encoding.
In all cases, both sides of the connection must use the same password. When a digital signature is used, the server must store a user's public key and the name of the algorithm used to create the signature. To distinguish these cases, the realm (described in RFC 7616) is prefaced with the following:
  1. [D]. This corresponds to Case 1 above.
  2. [S]. This corresponds to Case 2 above.
  3. [SC]. This corresponds to Case 3 above.
Case 3 is the most secure. When an SSL or TLS connection is established, a server will provide a client with the server's certificate and the SSL or TLS protocol will ensure that the server that provided the certificate has that certificate's private key. This can stop a variety of man-in-the-middle and spoofing attempts, at least to the point of inadvertently disclosing login credentials: in either case the certificate will be different, which means that the password that is generated will not be useful. A CRC is used because this provides a cheap way of rejecting authentication attempts that have the wrong password.

NOTE: For compatibility with openssl, one should use the keytool program, or SecureBasicUtilities.createPEMPair(File,String,String,String,String,char[]), to generate a key pair as a PKCS #12 file will then be created. The openssl equivalent to


 keytool -genkey -keyalg EC -groupname secp256r1 \
         -sigalg SHA256withECDSA -dname CN=nobody@nowhere.com \
         -alias key -keypass password -storepass password \
         -keystore ecstore.pfx
 
is

  openssl ecparam -name prime256v1 -genkey -noout -out eckey.pem
  openssl req -new -x509 -key eckey.pem -out eccert.pem -days 360
  openssl pkcs12 -export -inkey eckey.pem -in eccert.pem \
          -name key -out ecstore.pfx
 
although the choice of a signature algorithm (used to self sign) may be different. To add to the confusion, for the elliptic curve used in this example, keytool prefers the name secp256r1 whereas openssl prefers prime256v1. When openssl is given the name secp256r1, it will indicate that is is using prime256v1, whereas when keytool is given the name prime256v1, it generates an error message. Also keytool must use the same password for the file as for each entry it stores if the file is to be compatible with openssl.
See Also:
  • Constructor Details

  • Method Details

    • setTracer

      public void setTracer(Appendable tracer)
      Set an Appendable for tracing. This method should be used only for debugging.
      Parameters:
      tracer - the Appendable for tracing requests and responses
    • getMode

      public SecureBasicUtilities.Mode getMode()
      Get the mode.
      Returns:
      the mode
    • setTimeLimits

      public void setTimeLimits(int lowerTimeDiffLimit, int upperTimeDiffLimit, int passphraseTimeout) throws IllegalArgumentException
      Set time-offset limits. For the modes SecureBasicUtilities.Mode.DIGEST, SecureBasicUtilities.Mode.SIGNATURE_WITH_CERT, and SecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT, each password that is generated contains a time stamp in units of seconds. The time difference is the difference between the current time and the time stamp associated with a password.

      The first argument will generally be negative to handle the case in which the clock for the client generating the password is ahead of the server's clock. The second argument will generally be positive to handle the case in which the client's clock is behind the server's clock and to additionally account for propagation delay and to limit the number of times a password has to be recomputed. To allow for software that does not implement secure basic authentication, the value should be above the expected maximum length of a user's session.

      Parameters:
      lowerTimeDiffLimit - the lower limit for the time difference in seconds (the default is -10 seconds).
      upperTimeDiffLimit - the upper limit for the time difference in seconds (the default is 150 seconds)
      passphraseTimeout - the time interval in seconds for which a password is valid (the default is 1200)
      Throws:
      IllegalArgumentException - if the first argument is larger than zero, if the second argument is less than zero, or if the third argument is less than the second argument
    • add

      public void add(String username, String password) throws UnsupportedOperationException
      Add a user name and password for this authenticator's HTTP realm.
      Parameters:
      username - the user name
      password - the password
      Throws:
      UnsupportedOperationException - if the map does not allow entries to be added (the default map does not throw this exception)
    • add

      public void add(String username, String password, Set<String> roles) throws UnsupportedOperationException
      Add a user name, the user's password and the user's roles for this authenticator's HTTP realm.
      Parameters:
      username - the user name
      password - the user's password
      roles - the user's roles
      Throws:
      UnsupportedOperationException - if the map does not allow entries to be added (the default map does not throw this exception)
    • add

      public void add(String username, String pem, String password) throws UnsupportedOperationException
      Add a user name, the user's password, the user's public key, and the user's signature algorithm for this authenticator's HTTP realm.
      Parameters:
      username - the user name
      pem - A PEM file providing the signature algorithm and the user's certificate or public key
      password - the user's password
      Throws:
      UnsupportedOperationException - if the map does not allow entries to be added (the default map does not throw this exception)
    • add

      public void add(String username, String pem, String password, Set<String> roles) throws UnsupportedOperationException
      Add a user name, the user's password, the user's public key, the user's signature algorithm and the user's roles for this authenticator's HTTP realm.
      Parameters:
      username - the user name
      pem - A PEM file providing the signature algorithm and the user's certificate or public key
      password - the user's password
      roles - the user's roles
      Throws:
      UnsupportedOperationException - if the map does not allow entries to be added (the default map does not throw this exception)
    • setLoginFunction

      public void setLoginFunction(BiConsumer<EjwsPrincipal,HttpExchange> function)
      Set the login function. This function will be called using the current HttpExchange when a login is (a) successful and (b) the function is not null. It can be used to set headers or perform other operations as required by an application.

      The function will be called when the request URI matches a designated login URI, with the current EjwsPrincipal and HttpExchange as its arguments. In any transaction, at most one of the login, logout, and authorized functions will be called.

      Parameters:
      function - the function; null to disable
      See Also:
    • setAuthorizedFunction

      public void setAuthorizedFunction(BiConsumer<EjwsPrincipal,HttpExchange> function)
      Set the authorized function. This function will be called when a request is authorized. Its arguments are a principal and the HTTP exchange. The later can be used to set cookies or perform other operations. In any transaction, at most one of the login, logout, and authorized functions will be called.
      Parameters:
      function - the 'authorized' function.
    • setLogoutFunction

      public void setLogoutFunction(BiConsumer<EjwsPrincipal,HttpExchange> function)
      Set the logout function. This function will be called using the current HttpExchange when a logout is (a) successful and (b) the function is not null. It can be used to set headers or perform other operations as required by an application.

      The function will be called when the request URI matches a designated logout URI, with the current EjwsPrincipal and HttpExchange as its arguments. The HttpExchange will be null if the login session has timed out. In any transaction, at most one of the login, logout, and authorized functions will be called.

      Parameters:
      function - the function; null to disable
      See Also:
    • authenticate

      public Authenticator.Result authenticate(HttpExchange t)
      Authenticate an HTTP request.
      Overrides:
      authenticate in class BasicAuthenticator
      Parameters:
      t - the HTTP exchange object
      Returns:
      the authentication result
      See Also:
    • prune

      public void prune()
      Remove cached passwords whose timeout has expired. The method can be called periodically to eliminate passwords when a user has not explicitly logged out.
    • checkCredentials

      public boolean checkCredentials(String username, String password)
      Check credentials. This method is called for each incoming request to verify the given name and password in the context of this Authenticator's realm.
      Specified by:
      checkCredentials in class BasicAuthenticator
      Parameters:
      username - the user name
      password - the password