Repository: juddi Updated Branches: refs/heads/master 02c3b6d02 -> 4477b4cbd
JUDDI-912 updating documentation for the replication bits, more clarification on key stores Project: http://git-wip-us.apache.org/repos/asf/juddi/repo Commit: http://git-wip-us.apache.org/repos/asf/juddi/commit/4477b4cb Tree: http://git-wip-us.apache.org/repos/asf/juddi/tree/4477b4cb Diff: http://git-wip-us.apache.org/repos/asf/juddi/diff/4477b4cb Branch: refs/heads/master Commit: 4477b4cbdc949945fce55d56f7e8b3931d5c82d2 Parents: 02c3b6d Author: Alex <[email protected]> Authored: Mon Feb 16 15:50:14 2015 -0500 Committer: Alex <[email protected]> Committed: Mon Feb 16 15:50:14 2015 -0500 ---------------------------------------------------------------------- .../Guide/en-US/GuideReplication.asciidoc | 63 ++++++++++++++++++-- 1 file changed, 58 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/juddi/blob/4477b4cb/docs/asciidoc/Guide/en-US/GuideReplication.asciidoc ---------------------------------------------------------------------- diff --git a/docs/asciidoc/Guide/en-US/GuideReplication.asciidoc b/docs/asciidoc/Guide/en-US/GuideReplication.asciidoc index 02b2c9f..a088f67 100644 --- a/docs/asciidoc/Guide/en-US/GuideReplication.asciidoc +++ b/docs/asciidoc/Guide/en-US/GuideReplication.asciidoc @@ -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 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
