Author: tv
Date: Thu Sep 10 06:32:27 2009
New Revision: 813252
URL: http://svn.apache.org/viewvc?rev=813252&view=rev
Log:
Updated documentation
Modified:
turbine/fulcrum/trunk/crypto/xdocs/index.xml
Modified: turbine/fulcrum/trunk/crypto/xdocs/index.xml
URL:
http://svn.apache.org/viewvc/turbine/fulcrum/trunk/crypto/xdocs/index.xml?rev=813252&r1=813251&r2=813252&view=diff
==============================================================================
--- turbine/fulcrum/trunk/crypto/xdocs/index.xml (original)
+++ turbine/fulcrum/trunk/crypto/xdocs/index.xml Thu Sep 10 06:32:27 2009
@@ -1,88 +1,94 @@
<?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.
+ 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="[email protected]">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">
-
- <p>
- First, here is the role configuration.
- </p>
-
-<source>
-<![CDATA[
- <role
- name="org.apache.fulcrum.crypto.CryptoService"
- shorthand="crypto"
- default-class="org.apache.fulcrum.crypto.DefaultCryptoService"/>
-]]>
-</source>
-
- <p>
- Now comes the basic configuration of the component. Here will will
- configure the various encryption providers
- </p>
-<source>
+ <properties>
+ <title>Crypto Component</title>
+ <author email="[email protected]">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>
-<![CDATA[
+ <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>
-
- </section>
+ ]]></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>
-<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[
+ <source><![CDATA[
import org.apache.fulcrum.crypto.CryptoAlgorithm;
import org.apache.fulcrum.crypto.CryptoService;
@@ -100,68 +106,76 @@
}
]]></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="security-service.html">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 "cleartext" 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 need not 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>
+ <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>
