nbi.xmlsec
Class PEPClient

java.lang.Object
  nbi.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:

• URL of the provider's PEP (e.g.https://localhost/biocase/pywrapper.cgi)
• Database name (i.e. the dsa parameter of the Http request to the PyWrapper)
• Debug flag (i.e. the debug parameter of the Http request to the PyWrapper)
• KeyStore
• TrustStore

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:

• Initialise the PEPClient
• Send the BioCase request using one of the send methods
• Retrieve the BioCase response using one of the getResponse methods

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:

• javax.net.ssl.keyStore
• javax.net.ssl.keyStoreType
• javax.net.ssl.keyStorePassword

The system properties for truststores are:

• javax.net.ssl.trustStore
• javax.net.ssl.trustStoreType
• javax.net.ssl.trustStorePassword

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)