$Id$

CAS requires HTTPS be used for all operations, with the certificate used
having been signed by a certificate in the cacerts files shipped with Java.

If you're using a HTTPS certificate signed by a well known authority
(like Verisign), you can safely ignore the procedure below (although you
might find the troubleshooting section at the end helpful).

The following demonstrates how to create a self-signed certificate and add
it to the cacerts file. If you just want to use the certificate we have
already created and shipped with the Acegi Security System for Spring, you
can skip directly to step 3.


1. keytool -keystore keystore -alias acegisecurity -genkey -keyalg RSA -validity 9999 -storepass password -keypass password

What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  Acegi Security System for Spring
What is the name of your organization?
  [Unknown]:  TEST CERTIFICATE ONLY. DO NOT USE IN PRODUCTION.
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:
Is CN=localhost, OU=Acegi Security System for Spring, O=TEST CERTIFICATE ONLY. D
O NOT USE IN PRODUCTION., L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  yes


2. keytool -export -v -rfc -alias acegisecurity -file acegisecurity.txt -keystore keystore -storepass password

3. copy acegisecurity.txt %JAVA_HOME%\lib\security
   
4. copy keystore %YOUR_WEB_CONTAINER_LOCATION%

   NOTE: You will need to configure your web container as appropriate.
   We recommend you test the certificate works by visiting
   https://localhost:8443. When prompted by your browser, select to
   install the certificate.

5. cd %JAVA_HOME%\lib\security

6. keytool -import -v -file acegisecurity.txt -keypass password -keystore cacerts -storepass changeit -alias acegisecurity

Owner: CN=localhost, OU=Acegi Security System for Spring, O=TEST CERTIFICATE ONL
Y. DO NOT USE IN PRODUCTION., L=Unknown, ST=Unknown, C=Unknown
Issuer: CN=localhost, OU=Acegi Security System for Spring, O=TEST CERTIFICATE ON
LY. DO NOT USE IN PRODUCTION., L=Unknown, ST=Unknown, C=Unknown
Serial number: 4080daf4
Valid from: Sat Apr 17 07:21:24 GMT 2004 until: Tue Sep 02 07:21:24 GMT 2031
Certificate fingerprints:
         MD5:  B4:AC:A8:24:34:99:F1:A9:F8:1D:A5:6C:BF:0A:34:FA
         SHA1: F1:E6:B1:3A:01:39:2D:CF:06:FA:82:AB:86:0D:77:9D:06:93:D6:B0
Trust this certificate? [no]:  yes
Certificate was added to keystore
[Saving cacerts]


7. Finished. You can now run the sample application as if you purchased a
   properly signed certificate. For production applications, of course you should
   use an appropriately signed certificate so your web visitors will trust it
   (such as issued by Thawte, Verisign etc).

TROUBLESHOOTING

* A "sun.security.validator.ValidatorException: No trusted certificate 
  found" indicates the cacerts is not being used or it did not correctly
  import the certificate. To rule out your web container replacing or in
  some way modifying the trust manager, set the
  CasAuthenticationProvider.trustStore property to the full file system
  location to your cacerts file.

* If your web container is ignoring your cacerts file, double-check it
  is stored in $JAVA_HOME\lib\security\cacerts. $JAVA_HOME might be
  pointing to the SDK, not JRE. In that case, copy
  $JAVA_HOME\jre\lib\security\cacerts to $JAVA_HOME\lib\security\cacerts