nbi.xmlsec
Class PEPClient

java.lang.Object
  extended bynbi.xmlsec.PEPClient

public class PEPClient
extends Object

The PEPClient manages communication with a BioCASE provider's Policy Enforcement Point(PEP).

The PEP protects the provider combining SSL based client authentication and role based access control on the provider resources. The PEPClient API may be used from clients as well as web interface providers. The former authenticates the client to the PEP directly using his private key. The PEP evaluates the roles assigned to this client and handles the related request according to the access control policies defined for these roles. The latter must be recognised by the provider PEP as a trusted communication partner. For this purpose, the PEP implements a fixed role named trustedClient . Clients having assigned this role by the provider's access control policies, may pass the identity of any client authenticated by themselves to the PEP. Therefore, the PEPClient sends the X.509 certificate of such authenticated clients to the PEP. This is done through the addition of an additional parameter clientCert to the Http request. Following the initial authentication of the trusted client , the PEP uses the X.509 certificate of the client certificates to determine the access rights of the included BioCASE request. It is on the trusted client to present or deliver the response to the real client respectively.

The PEPClient needs the following parameters to provide the functionality described above:

The Keystore specifies a Java KeyStore file holding the private key and certificate of the client sending requests to the PEP (e.g. PKCS12-file (.p12) delivered from the CA). The Truststore also specifies a Java KeyStore file including the certificates from all entities trusted by the client, especially the certificates of the provider PEPs to be contacted.

The basic usage of this class consists of three steps:

The initialisation of the PEPClient may also be read from a XML-Configuration file, according to the Apache Jakarta Commons Configuration API.

If the BioCASE response returned from the PEP includes any XML-Signature, the PEPClient validates these signature and adds the validation results to the diagnostic part of the BioCASE response. Finally, the PEPClient removes the corresponding XML Signature elements and delivers the core BioCASE response only. Note: Currently, this feature is not implemented.

Since:
Version:
$Revision: 1.15 $
Author:
Lutz Suhrbier

Field Summary
(package private) static Logger logger
           
private  HttpURLConnection pepConnection
          The connection to the PEP
private  URL pepURL
          The URL of the PEP protected PyWrapper
private  Diagnostics validationDiagnostics
           
 
Constructor Summary
PEPClient(Configuration config)
          Initialises the PEP client using a configuration.
PEPClient(String pepURL, String keystore, String keystoreType, String keystorePass, String truststore, String truststoreType, String truststorePass)
          Initialises the PEPClient.
 
Method Summary
 URL getPepURL()
          Gets the pepURL
 Response getResponse()
          Retrieves the BioCASE response from the PEP.
protected  InputStream getResponseAsInputStream()
          Retrieves the BioCASE response stream from the PEP.
protected static void logCertificates(URLConnection conn)
          Logs the local and server certificates of the current connection.
static void logDefaultStores()
          Logs the current System properties of keystore and truststore.
private  void openHostConnection()
          Opens and preconfigures the Https-connection the PEP.
 void send(InputStream requestIn, String dataBase, boolean debug, X509Certificate clientCert)
          Sends a BioCASE request to the provider PEP.
 void send(Request request, String dataBase, boolean debug, X509Certificate clientCert)
          Sends a BioCASE request to the provider PEP.
private  void setKeyStoreProperties(String store, String type, String password, boolean truststore)
          Store the Keystore parameters into the corresponding system properties.
protected  void setPepURL(String pepURL)
          Sets pepURL
protected  InputStream validateSignature(InputStream in)
          Validates any signature of the incoming InputStream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

static Logger logger

pepURL

private URL pepURL
The URL of the PEP protected PyWrapper


pepConnection

private HttpURLConnection pepConnection
The connection to the PEP


validationDiagnostics

private Diagnostics validationDiagnostics
Constructor Detail

PEPClient

public PEPClient(Configuration config)
          throws MalformedURLException
Initialises the PEP client using a configuration.

Parameters:
config - Configuration of the PEPClient class.
Throws:
MalformedURLException

PEPClient

public PEPClient(String pepURL,
                 String keystore,
                 String keystoreType,
                 String keystorePass,
                 String truststore,
                 String truststoreType,
                 String truststorePass)
          throws MalformedURLException
Initialises the PEPClient.

Parameters:
pepURL - URL of the PyWrapper.
keystore - Path to a JKS-Keystore including the client's private Key.
keystoreType - Type of the keystore (e.g. PKCS12)
keystorePass - Password of the keystore
truststore - Path to a JKS-Keystore including certificates of all trusted (provider) entities.
truststoreType - Type of the truststore (e.g. PKCS12)
truststorePass - Password of the truststore.
Throws:
MalformedURLException
Method Detail

setKeyStoreProperties

private void setKeyStoreProperties(String store,
                                   String type,
                                   String password,
                                   boolean truststore)
Store the Keystore parameters into the corresponding system properties. The system properties are the only way to configure a HttpsURLConnection. The system properties for keystores are: The system properties for truststores are:

Parameters:
store - Path to a JKS-Keystore.
type - Type of the keystore.
password - Password of the keystore.
truststore -

openHostConnection

private void openHostConnection()
                         throws IOException
Opens and preconfigures the Https-connection the PEP.

Throws:
IOException

logDefaultStores

public static void logDefaultStores()
Logs the current System properties of keystore and truststore.


logCertificates

protected static void logCertificates(URLConnection conn)
Logs the local and server certificates of the current connection.

Parameters:
conn - The cuurent connection.

send

public void send(Request request,
                 String dataBase,
                 boolean debug,
                 X509Certificate clientCert)
          throws SAXException,
                 CertificateEncodingException,
                 IOException
Sends a BioCASE request to the provider PEP.

Parameters:
request - The BioCASE request.
dataBase - The database to be queried (dsa request parameter)
debug - The debug flag (debug request parameter)
clientCert - The client certificate (trusted client mode) or null.
Throws:
SAXException
CertificateEncodingException
IOException

send

public void send(InputStream requestIn,
                 String dataBase,
                 boolean debug,
                 X509Certificate clientCert)
          throws CertificateEncodingException,
                 IOException
Sends a BioCASE request to the provider PEP.

Parameters:
requestIn - The BioCASE request stream.
dataBase - The database to be queried (dsa request parameter)
debug - The debug flag (debug request parameter)
clientCert - The client certificate (trusted client mode) or null.
Throws:
CertificateEncodingException
IOException

validateSignature

protected InputStream validateSignature(InputStream in)
                                 throws SAXException,
                                        IOException,
                                        ParserConfigurationException,
                                        InstantiationException,
                                        IllegalAccessException,
                                        ClassNotFoundException,
                                        MarshalException,
                                        XMLSignatureException,
                                        TransformerException
Validates any signature of the incoming InputStream. The validation result is reported in the validationDiagnostics, which will be added later within getResponse() to the final response. The key validation is done using the PEPClientKeySelector. Unfortunately, the validation process needs a transformation of the XML-Document into the DOM-model.

Parameters:
in - InputStream with the XML-document.
Returns:
InputStream with the original XML-Document without signature element. Any validation error throws an exception.
Throws:
SAXException
IOException
ParserConfigurationException
InstantiationException
IllegalAccessException
ClassNotFoundException
MarshalException
XMLSignatureException
TransformerException

getResponseAsInputStream

protected InputStream getResponseAsInputStream()
                                        throws SAXException,
                                               IOException,
                                               ParserConfigurationException,
                                               InstantiationException,
                                               IllegalAccessException,
                                               ClassNotFoundException,
                                               MarshalException,
                                               XMLSignatureException,
                                               TransformerException
Retrieves the BioCASE response stream from the PEP. Errors are documented within the diagnostics part of the response. XML-Signature evaluation results are not added to the diagnostics part of the response here!

Returns:
The BioCASE response as InputStream without XML-Signature validation results in the diagnostics.
Throws:
IOException
TransformerException
XMLSignatureException
MarshalException
ClassNotFoundException
IllegalAccessException
InstantiationException
ParserConfigurationException
SAXException

getResponse

public Response getResponse()
                     throws UnsupportedEncodingException,
                            IOException,
                            SAXException,
                            Exception
Retrieves the BioCASE response from the PEP. Errors are documented within the diagnostics part of the response. XML-Signature evaluation are added to the diagnostics part of the response.

Returns:
The BioCASE response including signature evalution report.
Throws:
UnsupportedEncodingException
IOException
SAXException
Exception

getPepURL

public URL getPepURL()
Gets the pepURL

Returns:
Returns the pepURL.

setPepURL

protected void setPepURL(String pepURL)
                  throws MalformedURLException
Sets pepURL

Parameters:
pepURL - The pepURL to set.
Throws:
MalformedURLException - URL(String)


Copyright © 2006 Lutz Suhrbier, Freie Universitšt Berlin. All Rights Reserved.