GT-2658 JAAS tweaks, javadoc, docs.

This commit is contained in:
dev747368
2019-09-05 12:59:49 -04:00
parent 220c3ff8d2
commit eff84e30d6
20 changed files with 412 additions and 305 deletions

View File

@@ -0,0 +1,76 @@
//
// JAAS config file for GhidraServer when operating in -a4 mode.
// Only the one section that you wish to enable should be called "auth".
// All other sections will be ignored.
//**********************************************************************************
// Active Directory via LDAP
//**********************************************************************************
// The special string "{USERNAME}" in the authIdentity and userFilter parameters is replaced with the Ghidra user's name
// at runtime by the LdapLoginModule, and should not be modified.
//
// The ldap DNS hostname for your Active Directory server needs to be fixed-up in the userProvider parameter,
// and the domain name portion of your user's identity (ie. user@domain.tld) needs to be fixed up in the
// authIdentity parameter, possibly the port number also (3269).
//
// In this mode, GhidraServer will bind to the LDAP server using the Ghidra user's name and password. It will
// then query for that same user (sAMAccountName={USERNAME}) to confirm that user's DN.
//
// See https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/LdapLoginModule.html
// for more information about the LdapLoginModule and its configuration.
//
// Do not use a plain "ldap" URI to connect to your LDAP server unless you want your user's
// credentials to be visible as plaintext network traffic.
//
example_ad_ldap_auth {
com.sun.security.auth.module.LdapLoginModule REQUIRED
userProvider="ldaps://<your_active_directory_ldap_server_hostname>:3269"
authIdentity="{USERNAME}@<your_active_directory_domain_name.tld>"
userFilter="(sAMAccountName={USERNAME})"
debug=true;
};
//**********************************************************************************
// JPAM
//**********************************************************************************
// JPAM is not included in the Ghidra distro. See http://jpam.sourceforge.net/.
//
// Additionally:
// the libjpam.so native library needs to be copied to your <ghidra>/server/os/[linux|linux64] directory.
// the JPAM-x.y.jar java library needs to be copied to your <ghidra>/server/lib directory.
example_jpam_auth {
net.sf.jpam.jaas.JpamLoginModule REQUIRED
// The serviceName parameter controls which PAM service Ghidra will try to authenticate against.
// This typically corresponds to a file called /etc/pam.d/<serviceName>
serviceName="system-auth"
;
};
//**********************************************************************************
// External program (ie. mod_authnz_external)
//**********************************************************************************
// Launches an external program to perform authentication.
//
// You may need to adjust the PROGRAM="" to include the full path to the example script
example_external_auth {
ghidra.server.security.loginmodule.ExternalProgramLoginModule REQUIRED
// Path to the external program. An absolute path is preferable.
PROGRAM="server/jaas/jaas_external_program.example.sh"
// Time to wait for external program to finish before killing it, in milliseconds.
TIMEOUT="1000"
// Any arguments that the external program needs. Do not include sensitive values as an
// argument because they can be seen by other users on the system.
ARG_00="arg1" ARG_01="test arg2"
;
};

View File

@@ -1,19 +0,0 @@
// Example JAAS config file for Ghidra server when operating in -a4 authmode.
// Ghidra only uses the "auth" section from the JAAS configuration.
// You may need to adjust the PROGRAM="" to include the full path to the example script
auth {
ghidra.server.security.loginmodule.ExternalProgramLoginModule required
// Path to the external program. An absolute path is preferable.
PROGRAM="server/jaas/jaas_external_program.example.sh"
// Time to wait for external program to finish before killing it, in milliseconds.
TIMEOUT="1000"
// any arguments that the external program needs. Do not include sensitive values as an
// argument as they can be seen by other users on the system.
ARG_00="arg1" ARG_01="test arg2"
;
};

View File

@@ -1,14 +0,0 @@
// Example JAAS config file to use the local Linux PAM system when operating in -a4 authmode.
// JPAM is not included in the Ghidra distro.
// Additionally:
// the libjpam.so native library needs to be copied to your ${JAVA_HOME}/lib directory.
// the JPAM-x.y.jar java library needs to be inserted into the GhidraServer's classpath.
auth {
net.sf.jpam.jaas.JpamLoginModule required
// The serviceName parameter controls which PAM service Ghidra will try to authenticate against.
// This corresponds to a file called /etc/pam.d/<serviceName>
serviceName="system-auth"
;
};

View File

@@ -1,22 +0,0 @@
// Example JAAS config file to use an Active Directory LDAP server to authenticate users when operating in -a4 authmode.
//
// The special string "{USERNAME}" in the authIdentity and userFilter parameters is replaced with the Ghidra user's name
// at runtime by the LdapLoginModule, and should not be modified.
//
// The ldap DNS hostname for your Active Directory server needs to be fixed-up in the userProvider parameter,
// and the domain name portion of your user's identity (ie. user@domain.tld) needs to be fixed up in the
// authIdentity parameter.
//
// In this mode, the Ghidra Server will bind to the LDAP server using the Ghidra user's name and password. It will
// then query for that same user (sAMAccountName={USERNAME}) to confirm that user's DN.
//
// See https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/LdapLoginModule.html
// for more information about the LdapLoginModule and its configuration.
//
auth {
com.sun.security.auth.module.LdapLoginModule REQUIRED
userProvider="ldaps://<your_active_directory_ldap_server_hostname>:3269"
authIdentity="{USERNAME}@<your_active_directory_domain_name.tld>"
userFilter="(sAMAccountName={USERNAME})"
debug=true;
};

View File

@@ -106,26 +106,52 @@ ghidra.repositories.dir=./repositories
# Ghidra server startup parameters.
#
# Command line parameters: (Add command line parameters as needed and renumber each starting from .1)
# [-ip <hostname>] [-i ###.###.###.###] [-p#] [-a#] [-anonymous] [-ssh] [-d<ntDomain>] [-e<days>] [-u] [-jaas <config_file>] [-autoProvision] [-n] <repositories_path>
# [-ip <hostname>] [-i #.#.#.#] [-p#] [-n]
# [-a#] [-d<ad_domain>] [-e<days>] [-jaas <config_file>] [-u] [-autoProvision] [-anonymous] [-ssh]
# <repository_path>
#
# -ip <hostname> : remote access hostname or IPv4 address to be used by clients
# -i #.#.#.# : interface IPv4 address to accept connections on (default all interfaces)
# -p# : base TCP port to be used (default: 13100)
# -a# : an optional authentication mode where # is a value of 0, 2, 4 or 5
# 0 - Private user password
# 2 - PKI Authentication
# 4 - JAAS Authentication
# 5 - Active Directory via Kerberos. Requires -d<active_directory_domainname.tld>
# -anonymous : enables anonymous repository access (see svrREADME.html for details)
# -ssh : enables SSH authentication for headless clients
# -e<days> : specifies default password expiration time in days (-a0 mode only, default is 1-day)
# -u : enable users to be prompted for user ID (does not apply to -a2 PKI mode)
# -jaas <path_to_config_file> : specifies JAAS config file.
# -autoProvision : enable the auto-creation of Ghidra users when the authenticator module
# (ie. OS or other authentication method specified by JAAS) authenticates
# a new unknown user.
# -ip <hostname> : identifies the remote access IPv4 address or hostname (FQDN) which should be
# used by remote clients to access the server.
#
# -i #.#.#.# : server interface IPv4 address to listen on (default will listen on all interfaces).
#
# -p# : base TCP port to be used (default: 13100) [see Note 1]
#
# -n : enable reverse name lookup for IP addresses when logging (requires proper configuration
# of reverse lookup by your DNS server)
#
# -a# : an optional authentication mode where # is a value of 0, 1, 2, or 4
# 0 - Private user password
# 1 - Active Directory via Kerberos. Requires -d<your.ad_domainname.tld>
# 2 - PKI Authentication
# 4 - JAAS Authentication. See also -jaas <config_file>
#
# -d<ad_domain> : the Active Directory domain name. Example: "-dmydomain.com"
#
# -e<days> : specifies default password expiration time in days (-a0 mode only, default is 1-day)
#
# -jaas <config_file> : specifies the path to the JAAS config file (when using -a4), relative
# to the ghidra/server directory (if not absolute).
# See jaas/jaas.conf for examples and suggestions.
# It is the system administrator's responsibility to craft their own
# JAAS configuration directive when using the -a4 mode.
#
# -u : enable users to be prompted for user ID (does not apply to -a2 PKI mode)
#
# -autoProvision : enable the auto-creation of Ghidra users when the authenticator module
# (ie. OS or other authentication method specified by JAAS) authenticates
# a new unknown user.
# Users deleted in the OS or other source system will need to be
# deleted manually from the Ghidra system.
#
# -anonymous : enables anonymous repository access (see svrREADME.html for details)
#
# -ssh : enables SSH authentication for headless clients
#
# <repository_path> : Required. Directory used to store repositories. This directory must be dedicated to this
# Ghidra Server instance and may not contain files or folders not produced
# by the Ghidra Server or its administrative scripts.
# Relative paths originate from the installation directory
# ${ghidra.repositories.dir} : config variable (defined above) which identifies the directory
# used to store repositories. Use of this variable to define the
# repositories directory must be retained.

View File

@@ -219,7 +219,7 @@ the <a href="#serverOptions">Server Options</a> section for more details.
<P>
The Ghidra Server has been designed to support many possible user authentication modes:
<OL>
<UL>
<LI><u>No authentication</u> - any user which has been added to the server may connect without
password or credentials.</LI>
<br>
@@ -230,29 +230,77 @@ The Ghidra Server has been designed to support many possible user authenticatio
first added or when the user is reset (see <a href="#serverAdministration">Server
Administration</a>). This default password must be changed by the user to avoid its expiration.</LI>
<br>
<LI><u>Active Directory via Kerberos (<typewriter>-a1</typewriter>)</u> - user authentication is
performed against your local Active Directory system using Kerberos to do so. The -d&lt;ad_domain&gt;
argument is required to specify the domain name of your Active Directory system.
<p>
It is also possible to authenticate against your Active Directory system using LDAP. See the
LDAP example when using JAAS -a4 mode.
</LI>
<br>
<LI><u>PKI authentication (<typewriter>-a2</typewriter>)</u> - user authentication is performed
using PKI user certificates. When using this mode, the distinguished name (DN) for each user
must be associated with each server User ID (see <a href="#serverAdministration">Server
Administration</a>). In addition, each user must configure Ghidra with the location of their
signing key/certificate keystore file (see <a href="#pkiCertificates">PKI Certificates</a>
for more information).
</LI>
<br>
<p>
Please note that each user&apos;s certificate must be issued by a trusted certificate authority
which has been properly added to the Ghidra Server&apos;s <typewriter>cacerts</typewriter> file. See
<a href="#pkiCertificateAuthorities">Managing PKI Certificate Authorities</a> for more information.
<br><br>
<p>
In an attempt to simplify the determination of user DN&apos;s, a log file
(<typewriter>UnknownDN.log</typewriter>) records user DNs which are unknown. After adding a
user to the server, ask the user to attempt a login using their PKCS certificate. This should
result in their DN being recorded to this log file. The server administrator may now copy the
appropriate DN from this log file when assigning the DN for a user.
</LI>
<br>
<LI><u>JAAS - Java Authentication and Authorization Service (<typewriter>-a4</typewriter>)</u> -
user authentication is delegated to the JAAS subsystem. The -jaas &lt;config_file&gt; argument
is required to specify the JAAS config file. There is an example config file in the GhidraServer
directory called jaas/jaas.conf.
<p>
JAAS is architected similar to Linux/Unix PAM, where a named authentication configuration is possibly
composed of several different modules. Ghidra's support of JAAS only handles single simple
JAAS modules that requests the name and password from the user.
<p>
Some known JAAS login modules:
<ul>
<li><u>com.sun.security.auth.module.LdapLoginModule</u> - allows authentication to an LDAP server. There
is an example of using this module to authenticate against an Active Directory system in the
jaas.conf file.
</li>
<li><u>net.sf.jpam.jaas.JpamLoginModule</u> - (Linux/Unix server only) allows authentication against
the local PAM configuration. You will need to download JPAM from SourceForce and install the
libraries in the necessary locations. See the example in the jaas.conf file.
</li>
<li><u>ghidra.server.security.loginmodule.ExternalProgramLoginModule</u> - spawns an external
program for each authentication request, and uses the external program's exit code as the indicator
of successful authentication.
<p>
There is an example (and non-useful) implementation of an external authenticator in the GhidraServer
directory called jaas/jaas_external_program.example.sh.
<p>
This login module strives to be compatible with Apache's mod_authnz_external API, and you should
be able to use any mod_authnz_external authenticator with Ghidra.
<p>
The external program is fed the username\n and password\n on its STDIN (ie. two text lines).
The external authenticator needs to exit with 0 (zero) error level
if the authentication was successful, or a non-zero error level if not successful.
</li>
<li><u>com.sun.security.auth.module.Krb5LoginModule</u> - not recommended - this login module
is used in the -a1 Active Directory via Kerberos authentication mode, and as such you should use it that way.
</li>
</ul>
</LI>
<br>
<LI><u>Use of an SSH pre-shared key (<typewriter>-ssh</typewriter>)</u> is supported as an
alternate form of authentication when using Local Ghidra password (<typewriter>-a0</typewriter>).
This SSH authentication is currently supported by the Headless Analyzer only. See
<a href="#sshAuthentication">SSH User Authentication</a> for configuration details.</LI>
</OL>
</UL>
</P>
(<a href="#top">Back to Top</a>)
@@ -277,46 +325,69 @@ public key files may be made without restarting the Ghidra Server.
<h2><a name="serverOptions">Server Options</a></h2>
<UL>
<LI><typewriter>-a#</typewriter><br>Allows a user authentication mode to be specified (see
<a href=#userAuthentication>User Authentication</a>)</LI>
<br>
<LI><typewriter>-anonymous</typewriter><br>Enable anonymous access support for Ghidra Server
and its repositories. Only those repositories which specifically enable anonymous access will be
accessible as read-only to an anonymous user.</LI>
<br>
<LI><typewriter>-ssh</typewriter><br>Enable SSH as an alternate form of authentication when
using <typewriter>-a0</typewriter> authentication mode.</LI>
<br>
<LI><typewriter>-u</typewriter><br>Allows the server login user ID to be specified at time of
login for <typewriter>-a0</typewriter> authentication mode. Without this option, the users
client-side login ID will be assumed.</LI>
<br>
<LI><typewriter>-ip &lt;hostname&gt;</typewriter><br>Identifies the remote access hostname (FQDN)
or IPv4 address which should be used by remote clients to access the server. By default the
host name reported by the operating system is resolved to an IPv4 address, if this fails the
local loopback address is used. The server log will indicate the remote access hostname
at startup. This option may be required when a server has multiple IP interfaces, relies on
a dynamic DNS or other network address translation for incoming connections.
This option establishes the property value for <i>java.rmi.server.hostname</i>.
<LI>Networking options
<UL>
<LI><typewriter>-ip &lt;hostname&gt;</typewriter><br>Identifies the remote access hostname (FQDN)
or IPv4 address which should be used by remote clients to access the server. By default the
host name reported by the operating system is resolved to an IPv4 address, if this fails the
local loopback address is used. The server log will indicate the remote access hostname
at startup. This option may be required when a server has multiple IP interfaces, relies on
a dynamic DNS or other network address translation for incoming connections.
This option establishes the property value for <i>java.rmi.server.hostname</i>.
</LI>
<br>
<LI><typewriter>-i &lt;#.#.#.#&gt;</typewriter><br>Forces the server to be bound to a specific
IPv4 interface on the server. If specified and the <typewriter>-ip</typewriter> option is not,
the address specified by <typewriter>-i</typewriter> will establish the remote access IP
address as well as restrict the listening interface. If this option is not specified connections
will be accepted on any interface.</LI>
<br>
<LI><typewriter>-p#</typewriter><br>Allows the base TCP port to be specified (default: 13100). The
server utilizes three (3) TCP ports starting with the specified base port (e.g., 13100,13101 and 13102).
The ports utilized are logged by the server during startup.</LI>
<br>
<LI><typewriter>-n</typewriter><br>Enables reverse name lookup for IP addresses when logging
(requires proper configuration of reverse lookup by your DNS server). Please note that logging
of host names is now disabled by default due to the slow-down which occurs when reverse DNS is
not properly configured on the network.</LI>
</UL>
</LI>
<br>
<LI><typewriter>-i &lt;#.#.#.#&gt;</typewriter><br>Forces the server to be bound to a specific
IPv4 interface on the server. If specified and the <typewriter>-ip</typewriter> option is not,
the address specified by <typewriter>-i</typewriter> will establish the remote access IP
address as well as restrict the listening interface. If this option is not specified connections
will be accepted on any interface.</LI>
<br>
<LI><typewriter>-p#</typewriter><br>Allows the base TCP port to be specified (default: 13100). The
server utilizes three (3) TCP ports starting with the specified base port (e.g., 13100,13101 and 13102).
The ports utilized are logged by the server during startup.</LI>
<br>
<LI><typewriter>-e#</typewriter><br>Allows the reset password expiration to be set to a
specified number of days (default is 1-day).</LI>
<br>
<LI><typewriter>-n</typewriter><br>Enables reverse name lookup for IP addresses when logging
(requires proper configuration of reverse lookup by your DNS server). Please note that logging
of host names is now disabled by default due to the slow-down which occurs when reverse DNS is
not properly configured on the network.</LI>
<LI>Authentication options
<UL>
<LI><typewriter>-a#</typewriter><br>Allows a user authentication mode to be specified (see
<a href=#userAuthentication>User Authentication</a>)</LI>
<br>
<LI><typewriter>-d&lt;ad_domain&gt;</typewriter><br>Sets the Active Directory domain name.
Example: "-dmydomain.com"</LI>
<br>
<LI><typewriter>-e#</typewriter><br>Allows the reset password expiration to be set to a
specified number of days (default is 1-day).</LI>
<br>
<LI><typewriter>-jaas &lt;config_file&gt;</typewriter><br>Specifies the path to the JAAS
config file (when using -a4), relative to the ghidra/server directory (if not absolute).
<p>
See jaas/jaas.conf for examples and suggestions. It is the system administrator's
responsibility to craft their own JAAS configuration directive when using the -a4 mode.</LI>
<br>
<LI><typewriter>-u</typewriter><br>Allows the server login user ID to be specified at time of
login for <typewriter>-a0</typewriter> authentication mode. Without this option, the users
client-side login ID will be assumed.</LI>
<br>
<LI><typewriter>-autoProvision</typewriter><br>Enable the auto-creation of Ghidra users when
the authenticator module (ie. OS or other authentication method specified by JAAS) authenticates
a new unknown user. Users deleted in the OS or other source system will need to be deleted
manually from the Ghidra system.</LI>
<br>
<LI><typewriter>-anonymous</typewriter><br>Enable anonymous access support for Ghidra Server
and its repositories. Only those repositories which specifically enable anonymous access will be
accessible as read-only to an anonymous user.</LI>
<br>
<LI><typewriter>-ssh</typewriter><br>Enable SSH as an alternate form of authentication when
using <typewriter>-a0</typewriter> authentication mode.</LI>
<br>
</UL>
</LI>
</UL>
(<a href="#top">Back to Top</a>)

View File

@@ -1,9 +1,7 @@
##VERSION: 2.0
##MODULE IP: Copyright Distribution Permitted
Common/server/jaas/jaas_external_program.example.conf||GHIDRA||||END|
Common/server/jaas/jaas.conf||GHIDRA||||END|
Common/server/jaas/jaas_external_program.example.sh||GHIDRA||||END|
Common/server/jaas/jaas_jpam.example.conf||GHIDRA||||END|
Common/server/jaas/jaas_ldap_ad.example.conf||GHIDRA||||END|
Common/server/server.conf||GHIDRA||||END|
Common/server/svrREADME.html||GHIDRA||||END|
Common/support/analyzeHeadlessREADME.html||GHIDRA||||END|