Skip to content
Permalink
Browse files
JUDDI-912 updating documentation for the replication bits, more clari…
…fication on key stores
  • Loading branch information
spyhunter99 committed Feb 16, 2015
1 parent 02c3b6d commit 4477b4cbdc949945fce55d56f7e8b3931d5c82d2
Showing 1 changed file with 58 additions and 5 deletions.
@@ -31,7 +31,7 @@ The specification defines a mechanism that is similar to a two step commit (for
Prerequisites:

1. Each node must have a unique ID associated with it.
2. Each node must have the UDDI v3 Replication service deployed and configured for CLIENT-CERT authentication using SSL/TLS.
2. Each node must have the UDDI v3 Replication service (juddiv3replication.war) deployed and configured for CLIENT-CERT authentication using SSL/TLS.
3. Each node must have a configured JKS key store and trust store.

==== Changing the Node ID
@@ -42,6 +42,54 @@ Forgot to change the Node ID before starting jUDDI for the first time? No proble

Since a registry can be corrupted via the replication endpoint, it is important to provide adequate security. The UDDI spec recommends using mutual certificate authentication. This is somtimes returned to as "CLIENT-CERT", certificate based authentication, or two-way SSL. All of these terms really refer to the same thing. jUDDI comes prebundled with Apache Tomcat that is configured for mutal certificate authentication out of the box (with self signed certificates). To setup CLIENT-CERT authentication, please see the documentation for your web application server.

===== Special notes on key stores and trust stores

jUDDI's use of key stores and trust stores for replication purposes using the standard system properties
- -Djavax.net.ssl.keyStore
- -Djavax.net.ssl.keyPassword
- -Djavax.net.ssl.trustStore
- -Djavax.net.ssl.trustStorePassword

These are used for transport layer security (node to node). On a side node, jUDDI (server) can also use the trust store to verify signed entities (configured though _juddiv3.xml_) and finally, the application server itself needs access to the key store and trust store for providing a certificate for SSL/TLS communication with clients for validating users (or another jUDDI replication node) that provide a client certificate.

For Tomcat, all you need is a connector with "clientAuth=want". Here's an example:

----
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
clientAuth="want" sslProtocol="TLS"
truststoreFile="truststore.jks" truststorePass="password"
keystoreFile="conf/keystore.jks" keystorePass="password"/>
----

===== Mapping certificates to roles

For each certificate that is used by a jUDDI node to authenticate to another, you'll have to map the Subject DN of the certificate to a user with the role "replication". In our example, we'll use tomcat's _tomcat-users.xml_ file.

----
<user username="CN=localhost, OU=jUDDI Test, O=Apache Software Foundation, L=Anytown, ST=MD, C=US" password="null" roles="replication"/>
----

In this example, we've added our test certificate's subject DN to the role of "replication".

TIP: If you run into issues getting things working, try adding the following to the startup parameters for tomcat: -Djavax.net.debug=all

IMPORTANT: Besides mapping the certificates to the replication role, either the certificate itself or the issuer of the certificate must be in the trust store used by the application server.

Since dealing with certificates can be confusing, consider the following configuration.

- Node 1 sends updates to Node 2
- Node 2 sends updates to Node 1

Then the certificates must be setup as follows (assuming that each node's SSL cert is used for authentication to the other node(s))

- Node 1's public key must be trusted by Node 2 (in Node 2 app server's trust store)
- Node 2's public key must be trusted by Node 1 (in Node 1 app server's trust store)
- Node 1 must have Node 2's certificate's Subject DN mapped to the 'replication' role
- Node 2 must have Node 1's certificate's Subject DN mapped to the 'replication' role
- Node 1's public and private keys must be in a keystore on Node 1 (and the Java -D properties set)
- Node 2's public and private keys must be in a keystore on Node 2 (and the Java -D properties set)

==== Setting the Replication Configuration

To set the replication configuration, you'll need to go to http://localhost:8080/juddiv3/admin then click on "Admin" in the top navigation bar and login. Once logged in, select "set_ReplicationNodes" from the drop down menu. The text entry field is actually resizable, so you'll probably want to make it bigger. This text box should be pre-populated with an example replication configuration. Edit the replication as needed, then click the "Go!" button to save it.
@@ -185,6 +233,7 @@ In this example, we have a directed graph where Node 1 sends to Node2, Node 2 to
</replicationConfiguration>
----

One last point of interest, Edge's can have a list of alternate message receivers and it is supported by jUDDI.

==== Performing Custody Transfer between nodes

@@ -193,13 +242,17 @@ Custody transfer (from a user's perspective) happens exacty the same way as it w

==== What's Supported and What's Not

Supported Configurations
- Directed graph replication with retransmit
- Non-directed
Here's a quick summary of what is and isn't supported for jUDDI replication capabilities. Want more support? Open a ticket and contribute.

Supported:

- Directed graph replication with retransmit (primary and alternate message receivers)
- Non-directed graphic replication (no edges defined)
- All UDDI data is replicated (Business, Binding, Serivce, tModels and Publisher Assertions)
- Custody transfer from Node to Node within the replication graph.

Functions not supported
Functions not supported:

- Conditional Data Updates
- Configuration Settings:
- maximumTimeToSyncRegistry

0 comments on commit 4477b4c

Please sign in to comment.