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
- a SHA-256 message digest of (1) the first eight bytes of the sequence and (2) a password using the UTF-8 character encoding.
- a digital signature of (1) the first eight bytes of the sequence and (2) a password using the UTF-8 character encoding.
- 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.
- [D]. This corresponds to Case 1 above.
- [S]. This corresponds to Case 2 above.
- [SC]. This corresponds to Case 3 above.
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
iskeytool -genkey -keyalg EC -groupname secp256r1 \ -sigalg SHA256withECDSA -dname CN=nobody@nowhere.com \ -alias key -keypass password -storepass password \ -keystore 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.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
- See Also:
-
Nested Class Summary
Nested ClassesNested classes/interfaces inherited from class com.sun.net.httpserver.Authenticator
Authenticator.Failure, Authenticator.Result, Authenticator.Retry, Authenticator.Success
-
Field Summary
Fields inherited from class com.sun.net.httpserver.BasicAuthenticator
realm
-
Constructor Summary
ConstructorsConstructorDescriptionEjwsSecureBasicAuth
(String realm) Constructor forSecureBasicUtilities.Mode.DIGEST
mode.EjwsSecureBasicAuth
(String realm, Certificate[] certs) Constructor forSecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT
mode andSecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
mode given multiple certificates.EjwsSecureBasicAuth
(String realm, Certificate[] certs, Map<String, EjwsSecureBasicAuth.Entry> map) Constructor forSecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT
mode andSecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
mode given multiple certificates, specifying a map.EjwsSecureBasicAuth
(String realm, Map<String, EjwsSecureBasicAuth.Entry> map) Constructor forSecureBasicUtilities.Mode.DIGEST
mode, specifying a map. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Add a user name and password for this authenticator's HTTP realm.void
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.void
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.void
Add a user name, the user's password and the user's roles for this authenticator's HTTP realm.Authenticate an HTTP request.boolean
checkCredentials
(String username, String password) Check credentials.getMode()
Get the mode.void
prune()
Remove cached passwords whose timeout has expired.void
setAuthorizedFunction
(BiConsumer<EjwsPrincipal, HttpExchange> function) Set the authorized function.void
setLoginFunction
(BiConsumer<EjwsPrincipal, HttpExchange> function) Set the login function.void
setLogoutFunction
(BiConsumer<EjwsPrincipal, HttpExchange> function) Set the logout function.void
setTimeLimits
(int lowerTimeDiffLimit, int upperTimeDiffLimit, int passphraseTimeout) Set time-offset limits.void
setTracer
(Appendable tracer) Set an Appendable for tracing.Methods inherited from class com.sun.net.httpserver.BasicAuthenticator
getRealm
-
Constructor Details
-
EjwsSecureBasicAuth
Constructor forSecureBasicUtilities.Mode.DIGEST
mode.- Parameters:
realm
- the HTTP realm
-
EjwsSecureBasicAuth
Constructor forSecureBasicUtilities.Mode.DIGEST
mode, specifying a map.A user-supplied map can be implemented so as to allow one to obtain passwords and roles from a database or some other form of persistent storage. If entries can be added while a server using this authenticator is running, the map should have a thread-safe implementation.
- Parameters:
realm
- the HTTP realmmap
- a map associating user names with entries containing a password, roles, and optionally a public key and related data
-
EjwsSecureBasicAuth
Constructor forSecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT
mode andSecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
mode given multiple certificates.If the second argument is null or does not contain any certificates, the mode is
SecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT
; otherwise the mode isSecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
- Parameters:
certs
- the server certificates.realm
- the HTTP realm
-
EjwsSecureBasicAuth
public EjwsSecureBasicAuth(String realm, Certificate[] certs, Map<String, EjwsSecureBasicAuth.Entry> map) Constructor forSecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT
mode andSecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
mode given multiple certificates, specifying a map.If the second argument is null or does not contain any certificates, the mode is
SecureBasicUtilities.Mode.SIGNATURE_WITHOUT_CERT
; otherwise the mode isSecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
A user-supplied map can be implemented so as to allow one to obtain passwords and roles from a database or some other form of persistent storage. If entries can be added while a server using this authenticator is running, the map should have a thread-safe implementation.
- Parameters:
certs
- the server certificates.realm
- the HTTP realmmap
- a map associating user names with entries containing a password, roles, and optionally a public key and related data
-
-
Method Details
-
setTracer
Set an Appendable for tracing. This method should be used only for debugging.- Parameters:
tracer
- the Appendable for tracing requests and responses
-
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 modesSecureBasicUtilities.Mode.DIGEST
,SecureBasicUtilities.Mode.SIGNATURE_WITH_CERT
, andSecureBasicUtilities.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
Add a user name and password for this authenticator's HTTP realm.- Parameters:
username
- the user namepassword
- 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 namepassword
- the user's passwordroles
- 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
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 namepem
- A PEM file providing the signature algorithm and the user's certificate or public keypassword
- 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 namepem
- A PEM file providing the signature algorithm and the user's certificate or public keypassword
- the user's passwordroles
- 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
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
andHttpExchange
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
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
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
andHttpExchange
as its arguments. TheHttpExchange
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
Authenticate an HTTP request.- Overrides:
authenticate
in classBasicAuthenticator
- 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
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 classBasicAuthenticator
- Parameters:
username
- the user namepassword
- the password
-