| <?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"> |
| |
| <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> |
| |
| <![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> |
| |
| <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="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> |
| </document> |