design-docs/kernel-authentication/kernelauthentication.txt

Establishing a remote client's trust in Virgo
=============================================
 
KeyStore
--------

The start processing of dmk.sh specifies JVM parameters:

    -Djavax.net.ssl.keyStore=<keystore file path> (default config/keystore)
    -Djavax.net.ssl.keyStorePassword=<keystore password> (default "changeit")

The JSSE Reference Guide (http://download.oracle.com/javase/1,5.0/docs/guide/security/jsse/JSSERefGuide.html#X509TrustManager) says
that setting the system property javax.net.ssl.keyStore to the filename of a keystore file (and javax.net.ssl.keyStorePassword
to the keystore password) creates an X509KeyManager which is used by SSL to establish a client's trust in the Virgo server.

TrustStore
----------

Both jconsole.sh and the stop processing of dmk.sh specify JVM parameters:

    -Djavax.net.ssl.trustStore=<keystore file path> (default config/keystore)
    -Djavax.net.ssl.trustStorePassword=<keystore password> (default "changeit")

These are used in establishing trust in the Virgo server using SSL.

The test keystore supplied with Virgo was generated by following the instructions at
http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html#Prepare_the_Certificate_Keystore
and may be examined as follows:

$ keytool -list -v -keystore keystore -storepass changeit

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: s2dmk
Creation date: Nov 12, 2009
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=SpringSource dm Kernel, OU=dm Server Team, O=SpringSource
Issuer: CN=SpringSource dm Kernel, OU=dm Server Team, O=SpringSource
Serial number: 4afbddd5
Valid from: Thu Nov 12 10:05:09 GMT 2009 until: Sat Oct 19 11:05:09 BST 2109
Certificate fingerprints:
	 MD5:  2F:C3:9E:4A:B5:75:B1:4C:5D:C0:69:83:D9:38:C7:5A
	 SHA1: AC:B8:0C:86:7E:7B:A5:67:3E:B9:13:95:CF:33:0F:BA:7C:DB:5D:D6
	 Signature algorithm name: SHA1withDSA
	 Version: 3


*******************************************
*******************************************


User Authentication
===================

The start processing of dmk.sh sets the following system properties:

		-Djava.security.auth.login.config=$CONFIG_DIR/org.eclipse.virgo.kernel.authentication.config
		-Dorg.eclipse.virgo.kernel.authentication.file=$CONFIG_DIR/org.eclipse.virgo.kernel.users.properties
			
org.eclipse.virgo.kernel.authentication.config contains the following:

virgo-kernel {
	org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
};
...

"JAAS Login Configuration File" http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html
describes how an application can authenticate a user and password by constructing a LoginContext passing the name of an entry
in the JAAS login configuration file, such as "virgo-kernel", and a callback handler which is used to supply the user name and
password to JAAS.

KernelLoginModule looks for the system property org.eclipse.virgo.kernel.authentication.file, typically set to point at the file
org.eclipse.virgo.kernel.users.properties, and uses it to create a CredentialStore which it uses to authenticate users and passwords.

The shipped version of org.eclipse.virgo.kernel.users.properties contains:

##################
# User definitions
##################
user.admin=springsource


##################
# Role definitions
##################
role.admin=admin


Remote JMX Configuration 
========================

dmk.sh sets the following system properties:

    -Dcom.sun.management.jmxremote.port=$JMX_PORT (default 9875)
    -Dcom.sun.management.jmxremote.authenticate=true
    -Dcom.sun.management.jmxremote.login.config=virgo-kernel
    -Dcom.sun.management.jmxremote.access.file=$CONFIG_DIR/org.eclipse.virgo.kernel.jmxremote.access.properties	
    -Dcom.sun.management.jmxremote.ssl=true
    -Dcom.sun.management.jmxremote.ssl.need.client.auth=false

config/org.eclipse.virgo.kernel.jmxremote.access.properties configures the access rights of the admin user:

admin=readwrite

Console Authentication
======================

See http://www.eclipse.org/equinox/incubator/console/user-doc.php for documentation.

org.eclipse.virgo.kernel.authentication.config contains the following:

...
equinox_console {
	org.eclipse.equinox.console.jaas.SecureStorageLoginModule REQUIRED;
};

dmk.sh sets the following system properties:

    -Dorg.eclipse.equinox.console.jaas.file="$CONFIG_DIR/store"
    -Dssh.server.keystore="$CONFIG_DIR/hostkey.ser"

Bug 361663 will replace equinox_console {} with one which points at the kernel login module.

We are considering raising a bug which will make the console ssh daemon use config/keystore.