Ported documentation for the Password tool from old_docs to the operations guide.
Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
3090314206
commit
ad23410e09
|
|
@ -1,128 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// 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
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[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>
|
|
||||||
|
|
||||||
----
|
|
||||||
|
|
@ -37,5 +37,6 @@ include::jndi/chapter.adoc[]
|
||||||
include::jaas/chapter.adoc[]
|
include::jaas/chapter.adoc[]
|
||||||
include::jaspi/chapter.adoc[]
|
include::jaspi/chapter.adoc[]
|
||||||
include::jmx/chapter.adoc[]
|
include::jmx/chapter.adoc[]
|
||||||
|
include::tools/chapter.adoc[]
|
||||||
include::troubleshooting/chapter.adoc[]
|
include::troubleshooting/chapter.adoc[]
|
||||||
include::xml/chapter.adoc[]
|
include::xml/chapter.adoc[]
|
||||||
|
|
|
||||||
|
|
@ -161,8 +161,7 @@ Refer to the link:https://docs.oracle.com/javase/7/docs/api/javax/security/auth/
|
||||||
|
|
||||||
[NOTE]
|
[NOTE]
|
||||||
====
|
====
|
||||||
Passwords can be stored in clear text, obfuscated or checksummed.
|
Passwords can be obfuscated using the xref:og-tools-password[Jetty Password tool].
|
||||||
The class link:{javadoc-url}/org/eclipse/jetty/util/security/Password.html[`org.eclipse.jetty.util.security.Password`] should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables.
|
|
||||||
====
|
====
|
||||||
|
|
||||||
===== JDBCLoginModule
|
===== JDBCLoginModule
|
||||||
|
|
|
||||||
|
|
@ -224,7 +224,7 @@ To configure access to `javax.mail.Session` from within a webapp, declare an `or
|
||||||
----
|
----
|
||||||
<1> Use the `org.eclipse.jetty.jndi.factories.MailSessionReference` class to hold the configuration.
|
<1> Use the `org.eclipse.jetty.jndi.factories.MailSessionReference` class to hold the configuration.
|
||||||
<2> Set the username for the mail instance.
|
<2> Set the username for the mail instance.
|
||||||
<3> Set the password for the mail instance - use Jetty's secure password obfuscation to obscure the password.
|
<3> Set the password for the mail instance -- use the xref:og-tools-password[Jetty Password tool] to obfuscate the password.
|
||||||
<4> Set all other applicable properties.
|
<4> Set all other applicable properties.
|
||||||
|
|
||||||
The webapp performs a lookup for `java:comp/env/mail/Session` at runtime and obtains a `javax.mail.Session` that has the correct configuration to permit it to send email via SMTP.
|
The webapp performs a lookup for `java:comp/env/mail/Session` at runtime and obtains a `javax.mail.Session` that has the correct configuration to permit it to send email via SMTP.
|
||||||
|
|
|
||||||
|
|
@ -16,7 +16,7 @@
|
||||||
|
|
||||||
The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.
|
The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.
|
||||||
|
|
||||||
The `server` module depends on the xref:og-module-threadpool[`threadpool` module], the xref:og-module-bytebufferpool[`bytebufferpool` module] and the xref:og-module-logging[`logging` module].
|
The `server` module depends on the xref:og-module-threadpool[`threadpool` module], the xref:og-module-bytebufferpool[`bytebufferpool` module] and the xref:og-module-logging[`logging` module].
|
||||||
|
|
||||||
[NOTE]
|
[NOTE]
|
||||||
====
|
====
|
||||||
|
|
|
||||||
|
|
@ -53,7 +53,7 @@ Among the configurable properties, the most relevant are:
|
||||||
The KeyStore path on the file system, either an absolute path or a relative path to `$JETTY_BASE` -- defaults to `$JETTY_BASE/etc/keystore.p12`.
|
The KeyStore path on the file system, either an absolute path or a relative path to `$JETTY_BASE` -- defaults to `$JETTY_BASE/etc/keystore.p12`.
|
||||||
`jetty.sslContext.keyStorePassword`::
|
`jetty.sslContext.keyStorePassword`::
|
||||||
The KeyStore password, which you want to explicitly configure.
|
The KeyStore password, which you want to explicitly configure.
|
||||||
The password may be obfuscated with the xref:og-password[Jetty Password Tool].
|
The password may be obfuscated with the xref:og-tools-password[Jetty Password tool].
|
||||||
|
|
||||||
If you need to configure client certificate authentication, you want to configure one of these properties (they are mutually exclusive):
|
If you need to configure client certificate authentication, you want to configure one of these properties (they are mutually exclusive):
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,81 @@
|
||||||
|
//
|
||||||
|
// ========================================================================
|
||||||
|
// 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
|
||||||
|
// ========================================================================
|
||||||
|
//
|
||||||
|
|
||||||
|
[[og-tools]]
|
||||||
|
=== Jetty Tools
|
||||||
|
|
||||||
|
[[og-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`]:
|
||||||
|
|
||||||
|
[source,bash,subs="verbatim,attributes"]
|
||||||
|
----
|
||||||
|
$ java -cp jetty-util-{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:og-protocols-ssl-customize[here].
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.ssl.ini
|
||||||
|
[source,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`:
|
||||||
|
|
||||||
|
[source,xml,subs="verbatim,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.
|
||||||
Loading…
Reference in New Issue