//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Jetty Tools

[[password]]
== Password Obfuscation

There are many cases where you might need to provide credentials such as usernames and passwords to authenticate your access to certain services, for example KeyStore and TrustStore passwords, JDBC credentials, Basic or Digest authentication credentials, etc.

Passwords are typically stored in clear-text in configuration files, because a program such as Jetty reading the configuration file must be able to retrieve the original password to authenticate with the service.

You can protect clear-text stored passwords from _casual view_ by obfuscating them using class link:{javadoc-url}/org/eclipse/jetty/util/security/Password.html[`org.eclipse.jetty.util.security.Password`]:

[,bash,subs=attributes+]
----
$ java -cp jetty-util-{jetty-version}.jar org.eclipse.jetty.util.security.Password --prompt
Username: <1>
Password: secret <2>
OBF:1yta1t331v8w1v9q1t331ytc <3>
MD5:5eBe2294EcD0E0F08eAb7690D2A6Ee69 <4>
----
<1> Hit kbd:[Enter] to specify a blank user.
<2> Enter the password you want to obfuscate.
<3> The obfuscated password.
<4> The MD5 checksum of the password.

The `Password` tool produced an obfuscated string for the password `secret`, namely `OBF:1yta1t331v8w1v9q1t331ytc` (the prefix `OBF:` must be retained).
The obfuscated string can be de-obfuscated to obtain the original password.

Now you can use the obfuscated password in Jetty configuration files, for example to specify the KeyStore password in `ssl.ini` when configuring secure connectors, as explained xref:protocols/index.adoc#ssl-customize[here].
For example:

.ssl.ini
[,properties]
----
jetty.sslContext.keyStorePassword=OBF:1yta1t331v8w1v9q1t331ytc
----

CAUTION: Remember that password obfuscation only protects from _casual view_ -- it can be de-obfuscated to obtain the original password.

TIP: You can also use the obfuscated password in your Java source code.

You can also use obfuscated passwords in Jetty XML files where a clear-text password is usually required.
Here is an example, setting an obfuscated password for a JDBC `DataSource`:

[,xml,subs=attributes+]
----
<New id="myDS" class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg></Arg>
  <Arg>jdbc/myDS</Arg>
  <Arg>
    <New class="com.zaxxer.hikari.HikariDataSource">
      <Arg>
        <New class="com.zaxxer.hikari.HikariConfig">
          <Set name="dataSourceClassName">org.postgresql.ds.PGSimpleDataSource</Set>
          <Set name="username">dbuser</Set>
          <Set name="password">
            <Call class="org.eclipse.jetty.util.security.Password" name="deobfuscate"> <!--1-->
              <Arg>OBF:1yta1t331v8w1v9q1t331ytc</Arg>
            </Call>
          </Set>
          ...
        </New>
      </Arg>
    </New>
  </Arg>
</New>
----
<1> Note the usage of `Password.deobfuscate(\...)` to avoid storing the clear-text password in the XML file.
