| Overview | Package | Class | Use | Tree | Deprecated | Index | Help |
|
|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
| Packages | |
|---|---|
| com.caplin.keymaster | Provides all the classes to verify a token. |
| com.caplin.keymaster.error | Provides all the error classes for key generation. |
| com.caplin.keymaster.keygenerator | Creates a set of public/private keys. |
| com.caplin.keymaster.keyimporter | Utilities that imports a private key into a hardware KeyStore and verify the successful import operation. |
| com.caplin.keymaster.servlet | Provides all the classes used when creating a token for a request. |
| examples.flatfile | Provides an example of a HTTPS servlet as an alternative to BasicAuthenticator. |
| examples.jndi | |
| examples.news | Provides a sample implementation of the ResponseFormatter interface. |
The Caplin KeyMaster allows Liberator to be used within a single sign-on environment. KeyMaster works behind any existing single sign-on system to completely block access to the Liberator to any user who has not been previously authenticated. It generates single-use, expiring, encrypted tokens that are used as the login password for Liberator. Only those clients who have a valid KeyMaster token are able to log in. Only those clients who have authenticated to the single sign-on system are able to retrieve a token from the KeyMaster servlet. The KeyMaster uses a private key to encrypt the token and the Liberator holds the corresponding public key that is used for decryption. This ensures that only the KeyMaster could possibly generate a valid token that is used for login. When the KeyMaster server is protected behind a single sign-on system this allows the Liberator to use the same single sign-on mechanism without the need for direct connection to the sign-on database or back-end system.
KeyMaster also provides several ResponseFormatter classes which specify the format of the response sent back to the client. This allows the users request for a token to be processed in several different ways depending on the type of application that is requesting the token. The current possibilities are:
StreamLinkFormatter - Creates a response that can be used by any of the Caplin StreamLink family
of products, (e.g. StreamLink for Java, StreamLink for C++, StreamLink for Excel).
JavaScriptFormatter - Creates a response that can be used by Caplin's RTML and RTSL products.
Applications such as WebSheet require this type of response.
NewsFormatter - An example response formatter that creates a custom response format. This is an example
ResponseFormatter. It is not used by any applications.
It should be noted that KeyMaster requires Java Virtual Machine (run-time enviroment) version 1.4 or higher
in order to run. This requirement is due to the logging KeyMaster performs as standard. KeyMaster uses
Logger to perform all logging.
The remainder of this document describes the different uses of KeyMaster in more detail. Click the links on the table below for information on a topic:
| Topic |
| KeyGenerator Configuration |
| Servlet Configuration |
| The ResponseFormatter Classes |
| KeyMaster and StreamLink |
| KeyMaster Examples |
| Bouncy Castle Notes |
To generate the public, DER and private keys a properties file must be supplied to the KeyGeneration class
as its first argument. This file must include ALL of the following properties. A sample configuration
file is provided with the KeyMaster installation. This file is located within the examples directory of the
KeyMaster distribution and is
called keygen.props.
| Property | Example | Description |
|---|---|---|
| key.generator.private.key.store.filename | 'privatekey.store' | The name of the file that the private key will be stored in. |
| key.generator.public.key.store.filename | 'publickey.store' | The name of the file that the public key will be stored in. |
| key.generator.public.key.der.filename | 'publickey.der' | The name of the DER formatted public key. The file should end in '.der'. |
| key.generator.key.size | '1024' | The size of the generated key. Both keys use this size. |
| key.generator.security.provider.class.name | 'org.bouncycastle.jce.provider .BouncyCastleProvider' |
The name of the encryption package. Needs to be in the classpath. |
| key.generator.security.provider.name | 'BC' | The name of the security provider that the key will be produced with. |
| key.generator.Level | 'INFO' | Specifies the level of logging required - these are standard Java Logger levels - see java.util.logging.Level for all possible options. |
| key.generator.FilenameAttribute | 'log.txt' | Specifies the name of the file to log messages to. The file is NOT appended to; an existing log file will be overwritten The file is created relative to the users current location. |
key.generator.FilenameAttribute=keygenerationlog.log
key.generator.key.size=1024
The two servlets that ship with KeyMaster (StandardKeyMaster and
FlatFileServlet)
both use the standard servlet deployment descriptor, namely a web.xml file, to set up the servlets properties. A sample web.xml file
is provided with the KeyMaster installation.
The web.xml file
has the following configuration options:
| Parameter | Example | Required | Description |
|---|---|---|---|
| encrypting.generator.key.identifier | 'myIdentifierName' | YES | Name of the identifier the token is generated for. This must be the same as the second parameter passed to
KeyGenerator when the private key was created. |
| encrypting.generator.private.key .store.filename |
Filesystem location: '/usr/local/jakarta-tomcat-5.0.16/ webapps/keymaster/privatekey.store' Classpath:'classpath:com/caplin/keymaster/encrypted/privatekey.store' |
YES | File name and location for the private key. Note that the double '//' is required only for Windows. Or by classpath reference. Note that 'classpath:' is a required prefix of the location. |
| encrypting.generator.security .provider.class.name |
'org.bouncycastle.jce.provider .BouncyCastleProvider' |
YES | The name of the encryption package. Needs to be in the servlet�s classpath. |
| encrypting.generator.security .provider.name |
'BC' | YES | The name of the security provider that the key will be produced with. |
| Parameter | Example | Required | Description |
|---|---|---|---|
| formatter-type-javascript | 'com.caplin.keymaster.servlet .JavaScriptFormatter' |
YES | Name of the class to handle a JavaScript response. This class is provided in keymaster.jar. |
| formatter-type-streamlink | 'com.caplin.keymaster.servlet .StreamLinkFormatter' |
YES | Name of the class to handle a StreamLink response. This class is provided in keymaster.jar. |
| formatter-type-typename | 'com.mycompany.myformatter' | NO | Name of the class to handle a custom response as is requested by the "type" query string parameter passed up to the KeyMaster. This class must implement ResponseFormater. It must be placed in the lib folder within WEB-INF on the application server. |
| Parameter | Example | Required | Description |
|---|---|---|---|
| key.generator.Level | 'ALL' | NO | KeyMaster logging level. In production this should be set to SEVERE or WARNING. See java.util.logging.Level
for all possible level values. |
| key.generator.FilenameAttribute | 'log.txt' | NO | Specifies the name of the file to log messages to. The file is NOT appended to. If an absolute path is not specified then the log file will be created relative to the directory the application server is running from (e.g. in tomcat the log would be tomcat/bin/log.txt). |
| Parameter | Example | Required | Description |
|---|---|---|---|
| http.remote.user | 'enabled' | NO | Specifies the username should be retrieved from the standard HTTP RemoteUser object. |
| user.credential.provider | 'com.caplin.keymaster.servlet.UserCredentialsProvider' | NO | This class will specify how the username is retrieved. If this configuration is left out then the default action will be to use the request parameter "username" if HTTPRemoteUser has not been enabled. If it has been enabled then the HTTPRemoteUser will be got or if this returns null then the request parameter will be used. |
The ResponseFormatter interface allows a developer to create custom response
formats without needing to write a whole servlet. The default servlet,
StandardKeyMaster, uses the "type" query
string parameter to determine which ResponseFormatter should be used to generate the response to the credentials
request.
The default ResponseFormatter is StreamLinkFormatter, which returns the following success message:
credentials=ok
username={username}
token={token/password}
An error response has the following format:
credentials=error
message={error message}
Each type of ResponseFormatter can produce a different response message format.
To create a custom response format, a developer must write a class which implements the ResponseFormatter interface. ResponseFormatter defines two methods:
public String formatResponse(HttpServletRequest request, String token)
public String formatErrorResponse(HttpServletRequest request, String errorMessage)
The HttpServletRequest argument allows a developer maximum flexibility when creating an individual response. Any parameters passed within the query string can be obtained and processed as necessary.
The token represents a password that has just been generated based on the private key specified in the servlet configuration file (web.xml). This key is used to gain access to a Caplin Liberator. This key should be incorporated into the required response format. The servlet that called the class will then return the formatted response to the calling application.
The HttpServletRequest argument allows a developer maximum leeway when creating an individual response. A developer
can add as many request parameters as required and return an error if any are missing.
The request will be passed into a developer's class by the servlet that is calling it. All servlets have this variable
by default as any GET or POST requests made by a user must contain both a HttpServletRequest
and HttpServletResponse object.
The errorMessage is an explanation of what has gone wrong while trying to produce a token for the request. This message should be incorporated into a suitable error response (e.g. the error response for the JavaScriptFormatter is of the form: SigGen_AuthenticationFailed('sourceid', 'Error message'); ). The servlet that called the class will then return the formatted error to the calling application.
When the code compiles successfully, an entry entry must be added to the web.xml file of the servlet that will be calling the new ResponseFormatter class. The entry will take the following form:
<init-param>
<param-name>formatter-type-typename</param-name>
<param-value>package.name.of.new.class</param-value>
<description>Optional description of new ResponseFormatter class</description>
</init-param>StandardKeyMaster uses reflection to load
the new class and it will be automatically added as a valid ResponseFormatter. Now request the
servlet specifying the new type within the query string (e.g. If the new ResponseFormatter has been registered
with the type name test, it will be used whenever a request is made including type=test
in the query string).
You can look at the example NewsFormatter for more information.
When KeyMaster is being used in conjunction with one of the StreamLink API's (e.g. StreamLinkForJava,
StreamLinkForC++ etc.) then the developer will need to use the
com.caplin.credentials.StandardKeyMasterCredentials if a standard KeyMaster request is
required. Otherwise a custom
com.caplin.credentials.CredentialsListener should be implemented on the client side that
can make the required request
and interpret the response correctly. On the KeyMaster side a custom
ResponseFormatter should be
implemented to return a response that the custom CredentialsListener can interpret.
The StandardKeyMasterCredentials class can be found in the StreamLinkForJava documentation at
com.caplin.credentials.StandardKeyMasterCredentials. This class can be used by the developer to
call KeyMaster using either a String or URL object. The class will
then take care of calling KeyMaster and retriving a token from it. The class will provide KeyMaster with
the required attribute (username) and wait for a token or an error to be returned.
com.caplin.credentials.util.RemoteCredentialsEncoder class. This
class allows KeyMaster to to return a response that the StandardKeyMasterCredentials class will understand.
The response is returned to the class via the output stream represented by the HttpServletResponse The classes in the
com.caplin.credentials package will return the response in the correct format.
KeyMaster comes with two examples, the first is a ResponseFormatter implementation, whilst the second is a custom servlet.
This example shows how a developer can implement their own
ResponseFormatter. The example requires an
extra query string parameter called 'wires' that can have a number of values. Each different value corresponds to a particular
user and a piece of news. The class checks the parameters of the URL and will return an error response if there is no value
for wires. If all the required string parameters are present then a piece of news and the token is printed to the screen. If
any of the required parameters are missing then an error message will be printed to the screen instead.
In the web.xml file that ships with KeyMaster, there is a section that deals with the different types of ResponseFormatter that
can be handled. These entries have the following format:
<init-param>
<param-name>formatter-type-news</param-name>
<param-value>examples.news.NewsFormatter</param-value>
<description>Name of the class to handle a NewsFormatter response</description>
</init-param>
This entry in the file tells the servlet when it is loaded by the application server that it can handle requests
for a news response. This response is then requested by specifying news as the type query string parameter
(e.g. http://server/keymaster/servlet/BasicAuthenticator?type=news).
This example demonstrates that KeyMaster will also work over HTTPS using Secure Socket Layer (SSL). The servlet is
configured to only work over HTTPS so that it is much more secure than the StandardKeyMaster
servlet. This allows it to
check user details itself before issuing a token for the request. The servlet uses a standard ASCII file with a list of users
and associated tokens to issue a response. If the user name is present in the file then the servlet will pull out the token for
that user. If the user is not present then an error is returned. Apart from that the servlet runs in the same way as
BasicAuthenticator except that it currently only uses the StreamLinkFormatter to format a response to the user.
The bouncy castle JAR file is used when creating the key files and when generating a token. The accompanying
website can provide the KeyMaster user with the compatible version
of their Java Runtime Enviroment (JRE). KeyMaster ships with Bouncy Castle for JRE version 1.4. If a newer
version of a JRE is being used then the equivalent bouncy castle JAR can be retrieved from the bouncy castle
release page.
The reason for the different bouncy castle JARS is that:
|
|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||