src/site/xdoc/developer-guide.xml - axis-axis2-java-rampart - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
     <title></title>
 </head>
   <body >
 <h1>Apache Rampart Developer Guide</h1>
 <h2>Getting Involved in Rampart</h2>

 <h3>Introduction</h3>

 Components of Rampart
 <ul>
   <li>Rampart Core</li>
   <li>Rampart Policy</li>
   <li>Rampart Trust</li>
 </ul>

 <p></p>
 <img alt="Rampart Components and WS-Security Stack"
 title="Rampart Components and WS-Security Stack" src="images/security-stack.jpg" align="middle" />

 <p><strong><em>Figure 1 : Rampart Components and WS-Security
 Stack</em></strong></p>

 <h3>Building Rampart</h3>
 <ol>
   <li>Install maven3. Refer to the <a
     href="http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html">Installation
     guide</a>.</li>
   <li>Download the source code.
     <ul>
       <li>Checkout <a href="https://github.com/apache/axis-axis2-java-rampart">https://github.com/apache/axis-axis2-java-rampart/</a></li>
     </ul>
   </li>
   <li>The Rampart project has 8 modules under it. They are:
     <ul>
       <li>rampart-policy contains security policy assertions.</li>
       <li>rampart-core has core components that process and enforce
       security.</li>
       <li>rampart-trust contains trust components.</li>
       <li>rampart-mar builds the rampart.mar that is deployed in the
         "modules" directory of the Axis2 repository.</li>
       <li>rampart-trust-mar builds the rahas.mar that adds WS-Trust into
         Axis2.</li>
       <li>rampart-test has a set of unit test cases.</li>
       <li>integration-test has functional tests.</li>
       <li>rampart-samples consist of samples provided with the
       distribution.</li>
     </ul>
   </li>
   <li>Build by typing <code>$mvn clean install</code></li>
 </ol>

 <p>When deploying rampart.mar and rampart-trust.mar in the Axis2 repository,
 you may notice that they do not contain any dependencies. Therefore all the
 dependencies must be in the classpath.</p>

 <h3>Rampart in Axis2</h3>

 <p>Rampart is deployed as a module in Axis2, in the security phase. The
 security phase is right after the transport phase. The Rampart module
 introduces a couple of handlers -
 "org.apache.rampart.handler.RampartReciever" and
 "org.apache.rampart.handler.RampartSender" to the security phase.</p>

 <p></p>
 <img alt="DOOM" title="Rampart in Axis2" src="images/rampart-handlers.jpg"
 align="middle" />

 <p><strong><em>Figure 2 : Rampart in Axis2</em></strong></p>

 <p>The "RampartReceiver" handler intercepts the incoming message. Then Rampart
 validates the security of the incoming message, and checks whether it is
 in-line with the specified security policy. All security actions such as
 decryption of the message, validating the digital signature, validating the
 timestamp, and authenticating the user happens inside the Rampart module.</p>

 <p>"RampartSender" is the last handler in the outflow. The outgoing message
 is intercepted by this handler and Rampart takes the security actions. For
 example SOAP message can be encrypted, digitally signed, and security tokens
 are included according to the security policy.</p>

 <h3>Rampart, WSS4J, and DOOM</h3>

 <p>Rampart uses WSS4J for securing SOAP messages. WSS4J is an Apache project
 which implements the WS-Security specification. SOAP messages are signed and
 encrypted according to the <a href="http://www.w3.org/TR/xmlenc-core/">XML
 Encryption</a> and <a href="http://www.w3.org/TR/xmldsig-core/">XML Digital
 Signature</a> specifications, but the WS-Security specification introduces an
 additional set of rules. Therefore WSS4J ensures that SOAP messages are
 singed according to all the rules defined in the specifications. WSS4J uses
 Apache's <a href="http://santuario.apache.org/Java/index.html">xmlsec
 libraries</a> for XML Encryption and XML Digital Signature.</p>

 <p>Rather than re-inventing the wheel, it was decided to use WSS4J for SOAP
 message security in Rampart but there was a fundamental problem. WSS4J and
 all the incorporating XML security libraries use "DOM" for parsing and
 generating XML, while Axis2 uses "AXIOM" as the object model. This was
 resolved by using a new object model named "DOOM". DOOM is both AXIOM and DOM
 implementations. Therefore you can manipulate/access a DOOM object structure
 through DOM interfaces and AXIOM interfaces.</p>

 <p>When Rampart is engaged and configured, the incoming SOAP messages are
 converted to DOOM. Since DOOM implements the DOM interface it is possible for
 WSS4J to process messages. After performing the security validations, before
 flushing the message down the message inflow, the DOOM SOAP message is
 converted back to OM. At the outgoing flow, the message is converted to DOOM
 and then the security functions are performed using WSS4J.</p>

 <h3>Rampart Core</h3>

 <p>Rampart core drives security enforcement and validation on SOAP messages.
 It binds all components together to create the final product. The important
 components of Rampart core are,</p>
 <ul>
   <li>org.apache.rampart.RampartEngine</li>
   <li>org.apache.rampart.MessageBuilder</li>
 </ul>

 <p><strong>SOAP Message Inflow</strong></p>

 <p>Incoming messages are intercepted by RampartReciver and handed over to the
 RampartEngine. RampartEngine is responsible for handling validation of
 security in the incoming SOAP message.</p>
 <img alt="Rampart Engine" title="Rampart Engine"
 src="images/rampart-engine.jpg" align="middle" />

 <p><strong><em>Figure 3: Control flow in RampartEngine</em></strong></p>

 <p><strong>Note</strong>: RampartMessageData stores
 "org.apache.rampart.policy.RampartPolicyData", which contains security policy
 in the manner required by "RampartEngine" and "MessageBuilder".</p>

 <p><strong>SOAP Message Outflow</strong></p>

 <p>Outgoing messages are intercepted by RampartSender and handed over to
 org.apache.rampart.RampartMessageBuilder. It is responsible for enforcing
 security on an outgoing SOAP message.</p>
 <img alt="Message Builder" title="Message Builder"
 src="images/message-builder.jpg" align="middle" />

 <p><strong><em>Figure 4: Control flow in MessageBuilder</em></strong></p>

 <h3>Rampart Policy</h3>

 <p>WS - Security Policy is an extension of WS-Policy specification.
 Corresponding to this, the implementation of the security policy in Rampart
 is based on "Neethi", which is the Apache implementation of WS Policy
 specification. For each policy assertion introduced in the WS-Security
 Policy, there is an "Assertion Builder" and an "Assertion Model" defined in
 Rampart-policy.</p>

 <p>Apache Neethi is a highly extensible framework. When reading a security
 policy file, these builders and models in Rampart Policy are picked up by the
 Neethi framework using the "Jar file Service Provider Mechanism". All Rampart
 builders are listed in the
 META-INF/services/org.apache.neethi.builders.AssertionBuilder file. When
 adding a new Policy assertion it requires only a builder, assertion model,
 and an entry in the file.</p>

 <p>The RampartPolicyBuilder creates a RampartPolicyData given a "Policy"
 object created using the Rampart-policy and Neethi frameworks.</p>

 <h3>Rampart Trust</h3>

 <p>Rampart Trust implements the WS-Trust specification, which can be used
 in-conjunction with the Rampart Core and Rampart Policy modules. Rampart
 Trust defines a framework that can be used to issue, cancel, renew, and
 validate tokens, i.e., it defines a set of interfaces that must be
 implemented by different token issuing parties. Basically, Rampart Trust
 provides the functionality needed to host a STS - Security Token Service.</p>
 <img alt="Rampart Trust" title="Rampart Trust" src="images/rampart-trust.jpg"
 align="middle" />

 <p><strong><em>Figure 5: Control flow in Rampart Trust</em></strong></p>

 <p></p>

 <p></p>

 <p></p>

 <h3>Release process and release preparation</h3>
 <p>Check that all dependencies and plugins are available from standard repositories. To do this, clean the local repository and execute 'mvn clean install followed by 'mvn site'</p>

 <p>Check that the set of license files in the legal directory is complete and accurate (by checking that in the binary distribution for every third party JAR in the lib directory. </p>

 <p>Check that the apache-release profile (see the 'parent' reference in the top level pom.xml, and https://maven.apache.org/pom/asf/) can be executed properly. To do this, issue the following command: mvn clean install -Papache-release -DskipTests=true</p>

 <p>You may also execute a dry run of the release process: mvn release:prepare -DdryRun=true. In a dry run, the generated zip files will still be labled as SNAPSHOT. After this, you need to clean up using the following command: mvn release:clean</p>

 <p>Check that the Maven site can be generated and deployed successfully, and that it has the expected content.</p>

 <p>To generate the entire documentation in one place, complete with working inter-module links, execute the site-deploy phase (and check the files under target/staging). A quick and reliable way of doing that is to use the following command: mvn -Dmaven.test.skip=true clean package site-deploy</p>

 <p>Complete the release notes in the new src/site/markdown/release-notes .md file, i.e. 2.0.0.md.  It should include a description of the major changes in the release as well as a list of resolved JIRA issues.</p>

 <h3>Prerequisites</h3>

 <p>The following things are required to perform the actual release:</p>

 <p>A PGP key that conforms to the <a href="http://specs.xmlsoap.org/ws/2005/02/trust/WS-Trust.pdf"> requirement for Apache release signing</a></p>

 <p>To make the release process easier, the passphrase for the code signing key should be configured in ~/.m2/settings.xml</p>

 <code><![CDATA[<settings>
   ...
   <profiles>
     <profile>
       <id>apache-release</id>
       <properties>
         <gpg.passphrase><!-- KEY PASSPHRASE --></gpg.passphrase>
       </properties>
     </profile>
   </profiles>
   ...
 </settings>]]>

 </code>

 <p>The release process uses a Nexus staging repository. Every committer should have access to the corresponding staging profile in Nexus. To validate this, login to repository.apache.org and check that you can see the org.apache.axis staging profile. The credentials used to deploy to Nexus should be added to settings.xml</p>

 <h3>Release</h3>

 <p>In order to prepare the release artifacts for vote, execute the following steps:</p>

 <p>If not yet done, export your public key and <a href="https://dist.apache.org/repos/dist/release/axis/axis2/java/rampart/KEYS"> append it there. </a></p>

 <p>If not yet done, also export your public key to the dev area and <a href="https://dist.apache.org/repos/dist/release/axis/axis2/java/rampart/KEYS"> append it there. </a></p>

 <p>The command to export a public key is as follows:</p>

 <code>gpg --armor --export key_id</code>

 <p>If you have multiple keys, you can define a ~/.gnupg/gpg.conf file for a default. Note that while 'gpg --list-keys' will show your public keys, using maven-release-plugin with the command 'release:perform' below requires 'gpg --list-secret-keys' to have a valid entry that matches your public key, in order to create 'asc' files that are used to verify the release artifcats. 'release:prepare' creates the sha512 checksum files.</p>

 <p>The created artifacts i.e. zip files can be checked with, for example, sha512sum 'rampart-dist-1.8.0-bin.zip' which should match the generated sha512 files. In that example, use 'gpg --verify rampart-dist-1.8.0-bin.zip.asc rampart-dist-1.8.0-bin.zip' to verify the artifacts were signed correctly</p>

 <p>If necessary, update the copyright date in the top level NOTICE file.</p>

 <p>Start the release process with the following command - use 'mvn release:rollback' to undo and be aware that in the main pom.xml there is an apache parent that defines some plugin versions<a href="https://maven.apache.org/pom/asf/"> documented here. </a></p>

 <code>mvn release:prepare</code>

 <p>When asked for the "SCM release tag or label", keep the default value (x.y.z) </p>

 <p>The above command will create a tag in Git and increment the version number of the trunk to the next development version. It will also create a release.properties file that will be used in the next step.</p>

 <p>Perform the release using the following command: </p>

 <code>mvn release:perform</code>

 <p>This will upload the release artifacts to the Nexus staging repository.</p>

 <p>Close the staging repository. The name of the staging profile is org.apache.axis. See <a href="https://maven.apache.org/developers/release/maven-project-release-procedure.html"> for a more thorough description of this step. </a></p>

 <p>Execute the target/checkout/etc/dist.py script to upload the source and binary distributions to the development area of the <a href="https://dist.apache.org/repos/dist/"> repository. </a></p>

 https://dist.apache.org/repos/dist/dev/axis/axis2/java/rampart/

 <p>Create a new staging area for the site, clone from https://github.com/apache/axis-site and commit a copy of the dir axis2/java/rampart to axis2/java/rampart-staging.</p>

 <p>Change to the target/checkout directory and prepare the site using the following commands:</p>

 <code>mvn site-deploy ; mvn scm-publish:publish-scm -Dscmpublish.skipCheckin=true</code>

 <p>The staging area will be checked out to target/scmpublish-checkout (relative to target/checkout). Do a sanity check on the changes and then commit them.</p>

 <p>The root dir of axis-site has a .asf.yaml file, referenced here at target/scmpublish-checkout/.asf.yaml, that is  <a href="https://github.com/apache/infrastructure-asfyaml/blob/main/README.md"> documented here. </a></p>

 <p>Start the release vote by sending a mail to java-dev@axis.apache.org . The mail should mention the list of issues solved in the release (by linking to the relevant JIRA view).</p>

 <p>Include a link to the location of the Nexus staging repository, and a link to the <a href="https://dist.apache.org/repos/dist/dev/axis/axis2/java/rampart/"> source and binary distributions. </a></p>

 <p>A link to the preview of the <a href="https://axis.apache.org/axis2/java/rampart-staging/"> Maven site. </a></p>

 <p>If the vote passes, execute the following steps:</p>

 <p>Promote the artifacts in the staging repository. See<a href="https://central.sonatype.org/publish/release/#close-and-drop-or-release-your-staging-repository"> for detailed instructions for this step.</a></p>

 <p>Publish the distributions:</p>

 <code>svn mv https://dist.apache.org/repos/dist/dev/axis/axis2/java/rampart/x.x.x https://dist.apache.org/repos/dist/release/axis/axis2/java/rampart</code>

 <p>Publish the site:</p>

 <code>git clone https://github.com/apache/axis-site ; cd axis-site ; git rm -r rampart ; git mv rampart-staging rampart ; git commit -am "Release Rampart x.x.x"</code>

 <p>It may take several hours before all the updates have been synchronized to the relevant ASF systems. Before proceeding, check that the Maven artifacts for the release are available from the Maven central repository, and the <a href="https://axis.apache.org/axis2/java/rampart/"> Rampart Maven site has been synchronized.</a></p>

 <p>Verify the binary and source distributions can be downloaded from the<a href="https://axis.apache.org/axis2/java/rampart/download.html"> Rampart download page.</a></p>

 <p>Once everything is in place, send announcements to java-dev@axis.apache.org and announce@apache.org. Since the two lists have different conventions, audiences and moderation policies, to send the announcement separately to the two lists.</p>

 <p>Sample announcement:</p>

 <p>Apache Rampart Team is pleased to announce the release of Rampart x.y.z. The release is available for download at:</p>

 <p>https://axis.apache.org/axis2/java/rampart/download.html</p>

 <p>Apache Rampart provides implementations of the WS-Sec* specifications for Apache Axis2, based on Apache WSS4J and the Apache Axiom DOOM implementation.</p>

 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title></title>
	</head>
	<body >
	<h1>Apache Rampart Developer Guide</h1>
	<h2>Getting Involved in Rampart</h2>

	<h3>Introduction</h3>

	Components of Rampart
	<ul>
	<li>Rampart Core</li>
	<li>Rampart Policy</li>
	<li>Rampart Trust</li>
	</ul>

	<p></p>
	<img alt="Rampart Components and WS-Security Stack"
	title="Rampart Components and WS-Security Stack" src="images/security-stack.jpg" align="middle" />

	<p><strong><em>Figure 1 : Rampart Components and WS-Security
	Stack</em></strong></p>

	<h3>Building Rampart</h3>
	<ol>
	<li>Install maven3. Refer to the <a
	href="http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html">Installation
	guide</a>.</li>
	<li>Download the source code.
	<ul>
	<li>Checkout <a href="https://github.com/apache/axis-axis2-java-rampart">https://github.com/apache/axis-axis2-java-rampart/</a></li>
	</ul>
	</li>
	<li>The Rampart project has 8 modules under it. They are:
	<ul>
	<li>rampart-policy contains security policy assertions.</li>
	<li>rampart-core has core components that process and enforce
	security.</li>
	<li>rampart-trust contains trust components.</li>
	<li>rampart-mar builds the rampart.mar that is deployed in the
	"modules" directory of the Axis2 repository.</li>
	<li>rampart-trust-mar builds the rahas.mar that adds WS-Trust into
	Axis2.</li>
	<li>rampart-test has a set of unit test cases.</li>
	<li>integration-test has functional tests.</li>
	<li>rampart-samples consist of samples provided with the
	distribution.</li>
	</ul>
	</li>
	<li>Build by typing <code>$mvn clean install</code></li>
	</ol>

	<p>When deploying rampart.mar and rampart-trust.mar in the Axis2 repository,
	you may notice that they do not contain any dependencies. Therefore all the
	dependencies must be in the classpath.</p>

	<h3>Rampart in Axis2</h3>

	<p>Rampart is deployed as a module in Axis2, in the security phase. The
	security phase is right after the transport phase. The Rampart module
	introduces a couple of handlers -
	"org.apache.rampart.handler.RampartReciever" and
	"org.apache.rampart.handler.RampartSender" to the security phase.</p>

	<p></p>
	<img alt="DOOM" title="Rampart in Axis2" src="images/rampart-handlers.jpg"
	align="middle" />

	<p><strong><em>Figure 2 : Rampart in Axis2</em></strong></p>

	<p>The "RampartReceiver" handler intercepts the incoming message. Then Rampart
	validates the security of the incoming message, and checks whether it is
	in-line with the specified security policy. All security actions such as
	decryption of the message, validating the digital signature, validating the
	timestamp, and authenticating the user happens inside the Rampart module.</p>

	<p>"RampartSender" is the last handler in the outflow. The outgoing message
	is intercepted by this handler and Rampart takes the security actions. For
	example SOAP message can be encrypted, digitally signed, and security tokens
	are included according to the security policy.</p>

	<h3>Rampart, WSS4J, and DOOM</h3>

	<p>Rampart uses WSS4J for securing SOAP messages. WSS4J is an Apache project
	which implements the WS-Security specification. SOAP messages are signed and
	encrypted according to the <a href="http://www.w3.org/TR/xmlenc-core/">XML
	Encryption</a> and <a href="http://www.w3.org/TR/xmldsig-core/">XML Digital
	Signature</a> specifications, but the WS-Security specification introduces an
	additional set of rules. Therefore WSS4J ensures that SOAP messages are
	singed according to all the rules defined in the specifications. WSS4J uses
	Apache's <a href="http://santuario.apache.org/Java/index.html">xmlsec
	libraries</a> for XML Encryption and XML Digital Signature.</p>

	<p>Rather than re-inventing the wheel, it was decided to use WSS4J for SOAP
	message security in Rampart but there was a fundamental problem. WSS4J and
	all the incorporating XML security libraries use "DOM" for parsing and
	generating XML, while Axis2 uses "AXIOM" as the object model. This was
	resolved by using a new object model named "DOOM". DOOM is both AXIOM and DOM
	implementations. Therefore you can manipulate/access a DOOM object structure
	through DOM interfaces and AXIOM interfaces.</p>

	<p>When Rampart is engaged and configured, the incoming SOAP messages are
	converted to DOOM. Since DOOM implements the DOM interface it is possible for
	WSS4J to process messages. After performing the security validations, before
	flushing the message down the message inflow, the DOOM SOAP message is
	converted back to OM. At the outgoing flow, the message is converted to DOOM
	and then the security functions are performed using WSS4J.</p>

	<h3>Rampart Core</h3>

	<p>Rampart core drives security enforcement and validation on SOAP messages.
	It binds all components together to create the final product. The important
	components of Rampart core are,</p>
	<ul>
	<li>org.apache.rampart.RampartEngine</li>
	<li>org.apache.rampart.MessageBuilder</li>
	</ul>

	<p><strong>SOAP Message Inflow</strong></p>

	<p>Incoming messages are intercepted by RampartReciver and handed over to the
	RampartEngine. RampartEngine is responsible for handling validation of
	security in the incoming SOAP message.</p>
	<img alt="Rampart Engine" title="Rampart Engine"
	src="images/rampart-engine.jpg" align="middle" />

	<p><strong><em>Figure 3: Control flow in RampartEngine</em></strong></p>

	<p><strong>Note</strong>: RampartMessageData stores
	"org.apache.rampart.policy.RampartPolicyData", which contains security policy
	in the manner required by "RampartEngine" and "MessageBuilder".</p>

	<p><strong>SOAP Message Outflow</strong></p>

	<p>Outgoing messages are intercepted by RampartSender and handed over to
	org.apache.rampart.RampartMessageBuilder. It is responsible for enforcing
	security on an outgoing SOAP message.</p>
	<img alt="Message Builder" title="Message Builder"
	src="images/message-builder.jpg" align="middle" />

	<p><strong><em>Figure 4: Control flow in MessageBuilder</em></strong></p>

	<h3>Rampart Policy</h3>

	<p>WS - Security Policy is an extension of WS-Policy specification.
	Corresponding to this, the implementation of the security policy in Rampart
	is based on "Neethi", which is the Apache implementation of WS Policy
	specification. For each policy assertion introduced in the WS-Security
	Policy, there is an "Assertion Builder" and an "Assertion Model" defined in
	Rampart-policy.</p>

	<p>Apache Neethi is a highly extensible framework. When reading a security
	policy file, these builders and models in Rampart Policy are picked up by the
	Neethi framework using the "Jar file Service Provider Mechanism". All Rampart
	builders are listed in the
	META-INF/services/org.apache.neethi.builders.AssertionBuilder file. When
	adding a new Policy assertion it requires only a builder, assertion model,
	and an entry in the file.</p>

	<p>The RampartPolicyBuilder creates a RampartPolicyData given a "Policy"
	object created using the Rampart-policy and Neethi frameworks.</p>

	<h3>Rampart Trust</h3>

	<p>Rampart Trust implements the WS-Trust specification, which can be used
	in-conjunction with the Rampart Core and Rampart Policy modules. Rampart
	Trust defines a framework that can be used to issue, cancel, renew, and
	validate tokens, i.e., it defines a set of interfaces that must be
	implemented by different token issuing parties. Basically, Rampart Trust
	provides the functionality needed to host a STS - Security Token Service.</p>
	<img alt="Rampart Trust" title="Rampart Trust" src="images/rampart-trust.jpg"
	align="middle" />

	<p><strong><em>Figure 5: Control flow in Rampart Trust</em></strong></p>

	<p></p>

	<p></p>

	<p></p>

	<h3>Release process and release preparation</h3>
	<p>Check that all dependencies and plugins are available from standard repositories. To do this, clean the local repository and execute 'mvn clean install followed by 'mvn site'</p>

	<p>Check that the set of license files in the legal directory is complete and accurate (by checking that in the binary distribution for every third party JAR in the lib directory. </p>

	<p>Check that the apache-release profile (see the 'parent' reference in the top level pom.xml, and https://maven.apache.org/pom/asf/) can be executed properly. To do this, issue the following command: mvn clean install -Papache-release -DskipTests=true</p>

	<p>You may also execute a dry run of the release process: mvn release:prepare -DdryRun=true. In a dry run, the generated zip files will still be labled as SNAPSHOT. After this, you need to clean up using the following command: mvn release:clean</p>

	<p>Check that the Maven site can be generated and deployed successfully, and that it has the expected content.</p>

	<p>To generate the entire documentation in one place, complete with working inter-module links, execute the site-deploy phase (and check the files under target/staging). A quick and reliable way of doing that is to use the following command: mvn -Dmaven.test.skip=true clean package site-deploy</p>

	<p>Complete the release notes in the new src/site/markdown/release-notes .md file, i.e. 2.0.0.md. It should include a description of the major changes in the release as well as a list of resolved JIRA issues.</p>

	<h3>Prerequisites</h3>

	<p>The following things are required to perform the actual release:</p>

	<p>A PGP key that conforms to the <a href="http://specs.xmlsoap.org/ws/2005/02/trust/WS-Trust.pdf"> requirement for Apache release signing</a></p>

	<p>To make the release process easier, the passphrase for the code signing key should be configured in ~/.m2/settings.xml</p>

	<code><![CDATA[<settings>
	...
	<profiles>
	<profile>
	<id>apache-release</id>
	<properties>
	<gpg.passphrase><!-- KEY PASSPHRASE --></gpg.passphrase>
	</properties>
	</profile>
	</profiles>
	...
	</settings>]]>

	</code>

	<p>The release process uses a Nexus staging repository. Every committer should have access to the corresponding staging profile in Nexus. To validate this, login to repository.apache.org and check that you can see the org.apache.axis staging profile. The credentials used to deploy to Nexus should be added to settings.xml</p>

	<h3>Release</h3>

	<p>In order to prepare the release artifacts for vote, execute the following steps:</p>

	<p>If not yet done, export your public key and <a href="https://dist.apache.org/repos/dist/release/axis/axis2/java/rampart/KEYS"> append it there. </a></p>

	<p>If not yet done, also export your public key to the dev area and <a href="https://dist.apache.org/repos/dist/release/axis/axis2/java/rampart/KEYS"> append it there. </a></p>

	<p>The command to export a public key is as follows:</p>

	<code>gpg --armor --export key_id</code>

	<p>If you have multiple keys, you can define a ~/.gnupg/gpg.conf file for a default. Note that while 'gpg --list-keys' will show your public keys, using maven-release-plugin with the command 'release:perform' below requires 'gpg --list-secret-keys' to have a valid entry that matches your public key, in order to create 'asc' files that are used to verify the release artifcats. 'release:prepare' creates the sha512 checksum files.</p>

	<p>The created artifacts i.e. zip files can be checked with, for example, sha512sum 'rampart-dist-1.8.0-bin.zip' which should match the generated sha512 files. In that example, use 'gpg --verify rampart-dist-1.8.0-bin.zip.asc rampart-dist-1.8.0-bin.zip' to verify the artifacts were signed correctly</p>

	<p>If necessary, update the copyright date in the top level NOTICE file.</p>

	<p>Start the release process with the following command - use 'mvn release:rollback' to undo and be aware that in the main pom.xml there is an apache parent that defines some plugin versions<a href="https://maven.apache.org/pom/asf/"> documented here. </a></p>

	<code>mvn release:prepare</code>

	<p>When asked for the "SCM release tag or label", keep the default value (x.y.z) </p>

	<p>The above command will create a tag in Git and increment the version number of the trunk to the next development version. It will also create a release.properties file that will be used in the next step.</p>

	<p>Perform the release using the following command: </p>

	<code>mvn release:perform</code>

	<p>This will upload the release artifacts to the Nexus staging repository.</p>

	<p>Close the staging repository. The name of the staging profile is org.apache.axis. See <a href="https://maven.apache.org/developers/release/maven-project-release-procedure.html"> for a more thorough description of this step. </a></p>

	<p>Execute the target/checkout/etc/dist.py script to upload the source and binary distributions to the development area of the <a href="https://dist.apache.org/repos/dist/"> repository. </a></p>

	https://dist.apache.org/repos/dist/dev/axis/axis2/java/rampart/

	<p>Create a new staging area for the site, clone from https://github.com/apache/axis-site and commit a copy of the dir axis2/java/rampart to axis2/java/rampart-staging.</p>

	<p>Change to the target/checkout directory and prepare the site using the following commands:</p>

	<code>mvn site-deploy ; mvn scm-publish:publish-scm -Dscmpublish.skipCheckin=true</code>

	<p>The staging area will be checked out to target/scmpublish-checkout (relative to target/checkout). Do a sanity check on the changes and then commit them.</p>

	<p>The root dir of axis-site has a .asf.yaml file, referenced here at target/scmpublish-checkout/.asf.yaml, that is <a href="https://github.com/apache/infrastructure-asfyaml/blob/main/README.md"> documented here. </a></p>

	<p>Start the release vote by sending a mail to java-dev@axis.apache.org . The mail should mention the list of issues solved in the release (by linking to the relevant JIRA view).</p>

	<p>Include a link to the location of the Nexus staging repository, and a link to the <a href="https://dist.apache.org/repos/dist/dev/axis/axis2/java/rampart/"> source and binary distributions. </a></p>

	<p>A link to the preview of the <a href="https://axis.apache.org/axis2/java/rampart-staging/"> Maven site. </a></p>

	<p>If the vote passes, execute the following steps:</p>

	<p>Promote the artifacts in the staging repository. See<a href="https://central.sonatype.org/publish/release/#close-and-drop-or-release-your-staging-repository"> for detailed instructions for this step.</a></p>

	<p>Publish the distributions:</p>

	<code>svn mv https://dist.apache.org/repos/dist/dev/axis/axis2/java/rampart/x.x.x https://dist.apache.org/repos/dist/release/axis/axis2/java/rampart</code>

	<p>Publish the site:</p>

	<code>git clone https://github.com/apache/axis-site ; cd axis-site ; git rm -r rampart ; git mv rampart-staging rampart ; git commit -am "Release Rampart x.x.x"</code>

	<p>It may take several hours before all the updates have been synchronized to the relevant ASF systems. Before proceeding, check that the Maven artifacts for the release are available from the Maven central repository, and the <a href="https://axis.apache.org/axis2/java/rampart/"> Rampart Maven site has been synchronized.</a></p>

	<p>Verify the binary and source distributions can be downloaded from the<a href="https://axis.apache.org/axis2/java/rampart/download.html"> Rampart download page.</a></p>

	<p>Once everything is in place, send announcements to java-dev@axis.apache.org and announce@apache.org. Since the two lists have different conventions, audiences and moderation policies, to send the announcement separately to the two lists.</p>

	<p>Sample announcement:</p>

	<p>Apache Rampart Team is pleased to announce the release of Rampart x.y.z. The release is available for download at:</p>

	<p>https://axis.apache.org/axis2/java/rampart/download.html</p>

	<p>Apache Rampart provides implementations of the WS-Sec* specifications for Apache Axis2, based on Apache WSS4J and the Apache Axiom DOOM implementation.</p>

	</body>
	</html>