xdocs/index.xml (67 lines of code) (raw):
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or
more contributor license agreements. See the NOTICE file
distributed with this work for additional information regarding
copyright ownership. The ASF licenses this file to you under the
Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by
applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions
and limitations under the License.
-->
<document>
<properties>
<title>Crypto Component</title>
<author email="epugh@upstate.com">Eric PUgh</author>
</properties>
<body>
<section name="Overview">
<p>
The Crypto Service allows an application to request various encryption
algorithms.
</p>
<p>
It is written for use in Turbine but it can be used in any container
compatible with Avalon's ECM container.
</p>
</section>
<section name="Configuration">
<subsection name="Role Configuration">
<source><![CDATA[
<role
name="org.apache.fulcrum.crypto.CryptoService"
shorthand="crypto"
default-class="org.apache.fulcrum.crypto.DefaultCryptoService"/>
]]></source>
</subsection>
<subsection name="Component Configuration">
<table>
<tr>
<th>Item</th>
<th>Datatype</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
<tr>
<td>algorithm</td>
<td>Complex</td>
<td>[0|1]</td>
<td>
This element controls the various encryption providers. All sub-elements
of this element define the name of the provider as the element name and
the class that implements the provider as its value. See the configuration
example. The algorithm <code>default</code> can be used to override the
default which is JavaCrypt.
</td>
</tr>
</table>
</subsection>
<subsection name="Component Configuration Example">
<source><![CDATA[
<crypto>
<algorithm>
<unix>org.apache.fulcrum.crypto.provider.UnixCrypt</unix>
<clear>org.apache.fulcrum.crypto.provider.ClearCrypt</clear>
<java>org.apache.fulcrum.crypto.provider.JavaCrypt</java>
<oldjava>org.apache.fulcrum.crypto.provider.OldJavaCrypt</oldjava>
</algorithm>
</crypto>
]]></source>
</subsection>
</section>
<section name="Usage">
<p>
If you want to encrypt a clear text with a MessageDigest Cipher, you
can do it like this:
</p>
<source><![CDATA[
import org.apache.fulcrum.crypto.CryptoAlgorithm;
import org.apache.fulcrum.crypto.CryptoService;
public class CryptoExample
{
public String doMD5Encryption(String input)
{
CryptoService cs = (CryptoService) avalonComponentService.lookup(CryptoService.ROLE);
CryptoAlgorithm ca = CryptoService.getCryptoAlgorithm("default");
ca.setCipher("MD5");
return ca.encrypt(input);
}
}
]]></source>
<p>
To see an example, look at the test case
<a href="xref-test/org/apache/fulcrum/crypto/CryptoServiceTest.html">CryptoServiceTest</a>.
</p>
</section>
<section name="Default Provider">
<p>
In the source code and the example above, there is talk
about a "default" provider which is used if no encryption algorithm is
specifically requested. The reason for this comes from the first user
of the crypto service, the
<a href="http://turbine.apache.org/turbine/turbine-2.3.3/services/security-service.html">Turbine Security Service</a>.
It gives you the
ability to select an encryption algorithm like MD5 or SHA1 which is in
turn used with the normal java crypto providers. As we just wanted to
"add" new algorithms and still be able to use the old java.security
names like MD5 and SHA1, we decided to add a "catchall" algorithm to
the crypto service.
</p>
<p>
If you don't set the default provider explicitly, the
org.apache.fulcrum.crypto.provider.JavaCrypt class is
used. If you don't set the Cipher of this class explicitly, then SHA
is used.
</p>
</section>
<section name="Included Providers">
<p>The following algorithm providers are included in the
Cryptoservice:</p>
<p>
<ol>
<li>
<b>ClearCrypt</b>
(org.apache.fulcrum.crypto.provider.ClearCrypt).
This is the simplest algorithm which does nothing. It is still
useful because you can use the Crypto Service all the time even
if you don't want to actually encrypt something. Just request
the "clear" algorithm.
</li>
<li>
<b>UnixCrypt</b>
(org.apache.fulcrum.crypto.provider.UnixCrypt).
This is an implementation of the Unix crypt(3) algorithm. Its
main use is when you need to access legacy information or
databases which already contain crypted passwords.
</li>
<li>
<b>JavaCrypt</b>
(org.apache.fulcrum.crypto.provider.JavaCrypt).
This is the default crypto provider. It implements the normal
Java MessageDigest ciphers You don't need to have this, it is
the default if no algorithms are given. The default
provider gives you all the Java MessageDigest Ciphers including
MD5, and SHA1.
</li>
<li>
<b>OldJavaCrypt</b>
(org.apache.fulcrum.crypto.provider.OldJavaCrypt).
Accessing the MessageDigest functions from java.security was
buggy in Turbine 2.1, because the Security Service didn't pad
the base64 values correctly but simply cut them
off after 20 bytes. If you're stuck with an old database full of
passwords and can't upgrade, please use this provider to keep
going. DO NOT USE THIS PROVIDER FOR NEW APPLICATIONS!.
</li>
</ol>
</p>
</section>
</body>
</document>