//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[configuring-security-secure-passwords]]
=== Secure Password Obfuscation

There are many places where you might want to use and store a password, for example for the SSL connectors and user passwords in realms.

Passwords can be stored in clear text, obfuscated, checksummed or encrypted in order of increasing security.
The choice of method to secure a password depends on where you are using the password.
In some cases, such as keystore passwords and `DIGEST` authentication, the system must retrieve the original password, which requires the obfuscation method.
The drawback of the obfuscation algorithm is that it protects passwords *from casual viewing only.*

When the stored password is compared to one a user enters, the handling code can apply the same algorithm that secures the stored password to the user input and compare results, making password authentication more secure.

The class `org.eclipse.jetty.util.security.Password` can be used to generate all varieties of passwords.

Run it without arguments to see usage instructions:

[source, screen, subs="{sub-order}"]
....
$ java -cp lib/jetty-util-{VERSION}.jar org.eclipse.jetty.util.security.Password

Usage - java org.eclipse.jetty.util.security.Password [<user>] <password>
If the password is ?, the user will be prompted for the password
....

For example, to generate a secured version of the password `password` for the user `username`:

[source, screen, subs="{sub-order}"]
....
$ java -cp ../lib/jetty-util-{VERSION}.jar org.eclipse.jetty.util.security.Password username password
2017-12-13 11:19:27.928:INFO::main: Logging initialized @95ms to org.eclipse.jetty.util.log.StdErrLog
password
OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
MD5:5f4dcc3b5aa765d61d8327deb882cf99
CRYPT:usjRS48E8ZADM
....

If using a external tool to create/verify the MD5 hash (such as `md5sum` or `md5`), be sure to verify a carriage return (CR) or new line is not added.
For example:

[source, screen, subs="{sub-order}"]
....
//With a CR included
$ echo password | md5sum
286755fad04869ca523320acce0dc6a4 *-

//Using the `-n` option to exclude a new line from being added.
$ echo -n password | md5sum
5f4dcc3b5aa765d61d8327deb882cf99 *-
....

____
[IMPORTANT]
When using the `DIGEST` method in tandem with an MD5 hash, you must hash the entire `user:realm:password` string or you will encounter issues with authenticating.
____

[source, screen, subs="{sub-order}"]
....
$ java -cp ../lib/jetty-util-{VERSION}.jar org.eclipse.jetty.util.security.Password username username:realm:password
2017-12-13 11:34:33.263:INFO::main: Logging initialized @97ms to org.eclipse.jetty.util.log.StdErrLog
username:realm:password
OBF:1w281yf41v1x1z7e1xmi1v1p1tvv1v901c3j1x8k1ugo1ri71uh21x8a1c3j1v9m1tv71v2p1xms1z7o1v2h1yf21w1a
MD5:66999343281b2624585fd58cc9d36dfc
CRYPT:usulxZfApLefk

$ echo -n username:realm:password | md5sum
66999343281b2624585fd58cc9d36dfc *-
....

You can now cut and paste whichever secure version you choose into your configuration file or Java code.

For example, the last line below shows how you would implement the encrypted password generated above into the properties file for a `LoginService`:

[source,bash]
----

admin: CRYPT:ad1ks..kc.1Ug,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq
guest: guest,read-only
me:CRYPT:me/ks90E221EY

----

____
[TIP]
Don't forget to also copy the OBF:, MD5: or CRYPT: prefix on the generated password. It will not be usable by Jetty without it.
____

You can also use obfuscated passwords in Jetty xml files where a plain text password is required.
Here's an example setting the password for a JDBC Datasource with obfuscation:

[source, xml, subs="{sub-order}"]
----

  <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
     <Arg></Arg>
     <Arg>jdbc/DSTest</Arg>
     <Arg>
       <New class="com.jolbox.bonecp.BoneCPDataSource">
         <Set name="driverClass">com.mysql.jdbc.Driver</Set>
         <Set name="jdbcUrl">jdbc:mysql://localhost:3306/foo</Set>
         <Set name="username">dbuser</Set>
         <Set name="password">
            <Call class="org.eclipse.jetty.util.security.Password" name="deobfuscate">
                  <Arg>OBF:1ri71v1r1v2n1ri71shq1ri71shs1ri71v1r1v2n1ri7</Arg>
            </Call>
         </Set>
         <Set name="minConnectionsPerPartition">5</Set>
         <Set name="maxConnectionsPerPartition">50</Set>
         <Set name="acquireIncrement">5</Set>
         <Set name="idleConnectionTestPeriod">30</Set>
      </New>
    </Arg>
  </New>

----
