develop

JAVA做的J2EE下CA认证系统 基于EJB开发

Eclipse
=======
To build succesfully using Eclipse, there are .classpath and .project files in the package and in cvs. 
Simply check out EJBCA as a project and you're almost set. 
You must define the variable JBOSS_HOME in Window->Preferences->Java->Build Path->Classpath Variables.
Many classes are generated by XDoclet, so you must also do an 'ant' for Eclipse to find all classes needed
to build the project. After checking out the project, defining JBOSS_HOME and running 'ant', you should simply 
refresh the project in Eclipse and voila!

You can build javadoc on all APIs used with 'ant javadoc'.

Debugging
=========
You might notice that there is a j2ee:debug target, it will start JBoss in debug mode. 
Just fire up your debugger to the default transport and address display on your console and 
you're set. You can now debug your application. 

Database connections and statements
===================================
It is very important to close connections and prepared statments when doing direct
JDBC queries. There is a utility class se.anatom.ejbca.util.JDBCUtil that helps minimize 
code for this. All direct JDBC queries must be encapsulated in in a try/finally clause 
as shown below:

Connection con = null;
PreparedStatement ps = null;
try {
    // Do stuff,,,
} catch (Exception e) {
	// handle error
} finally {
    JDBCUtil.close(con);
    JDBCUtil.close(ps);
}            
        
BouncyCastle provider
=====================
EJBCA uses the BouncyCastle (BC) jce provider. 
To handle redeploy you must use the static method:

CertTools.installBCProvier()

to install the provider if needed.

Subject and Issuer DNs
======================
Handling of subject and issuer DNs must be done in an extremely predictable way,
and in the same way everywhere. Issue are ordering of DN elements, handling of
localized strings (UTF8) etc. Because of this, there are a few methods in
se.anatom.ejbca.util.CertTools that MUST be used when handling DNs:

stringToBCDNString() - when handling user input of a DN string to store od
match.
getSubjectDN(cert) - extracts subject DN from a certificate
getIssuerDN(cert) - extracts issuer DN from a certificate
getIssuerDN(crl) - - extracts issuer DN from a CRL

Logging
=======

Straight console output (System.out) MUST not be used in EJBCA except in
cases of console admin utilities.

There are two types of logging in EJBCA:

1. CA logs, defining important events. These logs end up in the database and can
be searched through the administration Web-GUI.

2. Error and debug logs. These logs use Log4j and end up in a log file defined
in JBoss.

CA logs
-------

There are three important classes:
Admin     : Defines the administrator that performed the action.
LogEntry  : Represents a line in the log database. Only the contants defined
here are used.
ILogSessionRemote/Local : The log functionality itself.

To perform logging, one must first aquire the remote interface to the log
session:
ILogSessionLocalHome logsessionhome = (ILogSessionLocalHome) getLocator().getLocalHome(ILogSessionLocalHome.COMP_NAME);
logsession = logsessionhome.create();

Next step is to log trough the function 'log', it's as easy as can be.

Parameters to the log function are:
admin : is of the class Admin and is created according to the following
criteria:
    1. In case a client certificate exists, new Admin(certificate)
    2. In other cases one of the types defined in Admin.TYPE_...
       ex: new Admin(Admin.TYPE_RACOMMANDLINE_USER, ip-adress).
       If possible, the ip-adress should be passed.
module : is one of the LogEntry.MODULE_ constants and defines in which module
the event occured.
    ex : LogEntry.MODULE_CA.
time : the time of the event.
username : describes which user (endentity) that is involved in the event.
null in case no user can be considered to be involved.
certificate : defines which certificate is involved in the event. null in case
no certificate can be considered to be involved.
event : is one of the LogEntry.EVENT_ constants and defines which type of event
occured.
comment : a comment to the event.

If there are events that are not defined it is easy to add new ones, just follow
these steps:
1. Add an EVENT_INFO/ERROR constant to LogEntry
2. Add corresponting text in the constant LogEntry.EVENTNAMES_INFO/ERROR
3. Open the file src/ra/web/raadmin/languages/languagefile.en.properies i a text
editor.
Go through the contants until you come to the EVENT_INFO/ERROR... constants and
add the english translation. Try to keep the list sorted in alphabetical order.

If the three steps are followed the Web-GUI will be automagicaly updated and no
changes need to be done to it.

Error and debug logs
--------------------

EJBCA uses the Apache Log4J package for debug-logging. This means that any class
that wants to do logging or console output MUST define:

/** Log4j instance */
private static Logger log = Logger.getLogger(<class>.class);

Logging is then done with:

    log.error("message");
    log.info("message");
    log.debug("message");

There is also a version of the command that takes an additional Exception as
argument, were the exception stack will be printed to the log.

Where the log ends up is defined in 'log4j.properties'.

Some classes have special pre-prepared logging constructs. They are:

    BaseSessionBean.java
    BaseAdminCommand.java

This means that classes inheriting from one of these classes does not have to
define their own logger, but can simply use:

    error("message");
    info("message");
    debug("message");

Debugging output for entrance and exit in methods can be added in the following
way:

public int myMethod(int arg) {
  log.debug(">myMethod("+arg+")");

  int ret = 0;
  ...

  log.debug("<meMethod: return "+ret);
  return ret;
}

Making session beans
====================

All session beans should extend the class se.anatom.ejbca.BaseSessionBean.

Making entity beans
===================

All entity beans should extend the class se.anatom.ejbca.BaseEntityBean.
When doing this, the standard methods like setting the context are already in
there. They can however always be overriden.


CVS
===

All files should have the below part in the initial class comment:

@version $Id: DEVELOP,v 1.2 2005/05/27 12:56:36 anatom Exp $

Example:

/**
 * The main bean for the web interface, it contains all basic functions.
 *
 * @version $Id: DEVELOP,v 1.2 2005/05/27 12:56:36 anatom Exp $
 */

All java files should include the following header as the first lines in the file:
/*************************************************************************
 *                                                                       *
 *  EJBCA: The OpenSource Certificate Authority                          *
 *                                                                       *
 *  This software is free software; you can redistribute it and/or       *
 *  modify it under the terms of the GNU Lesser General Public           *
 *  License as published by the Free Software Foundation; either         *
 *  version 2.1 of the License, or any later version.                    *
 *                                                                       *
 *  See terms of license at gnu.org.                                     *
 *                                                                       *
 *************************************************************************/
 
 
CA KeyStore architecture/creating a custom CA Keystore
======================================================

The CA Keystore, where the CAs private key is stored and used is
defined by the interface se.anatom.ejbca.ca.sign.ISigningDevice.

By creating a new custom class and simply editing the property
'signingDeviceFactory' to point at the custom factory class that creates an
instance of the custom SigningDevice class in a thread-safe way.
It is recommended, but not required, that the Signing device implements a
Singleton.

The SigningDeviceFactory class MUST contain the method:

   /** Creates (if needed) the signing device and returns the object.
    * @prop Arguments needed fo?r the eventual creation of the object
    * @return An instance of the Signing device.
    */
    public synchronized ISigningDevice makeInstance(Properties prop) throws
    Exception {
        return PKCS12SigningDevice.instance(prop);
    }

Clear or hashed passwords
=========================

Passwords for users are normally stored SHA1-hashed in the database.

You can retrieve and use the password IF it is stored in clear text.

Use something like this to get the password (snip from BatchMakeP12.java):

IUserAdminSessionRemote admin = adminhome.create();
UserAdminData data = admin.findUser(administrator, username);
if ((data.getPassword() != null) && (data.getPassword().length() > 0) {
...
}

When creating the user, you must specify that the password should be in clear text, 
otherwise it will be stored in hashed form, which will obvoiusly be of no use to you.

If using the Web-GUI there is a checkbox for storing the password in clear format.

If using the command line gui there is a command 'ra setclearpwd'

If using programatically:
In IUserAdminSession there is a flag 'clearpwd' to the method addUser, or you can use 
the method setOpenPassword on the UserDataBean object returned from findUser.