| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <!-- 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 https://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>Commons Crypto - User guide</title> |
| <author email="dev@commons.apache.org">Apache Commons Team</author> |
| </properties> |
| <body> |
| <section name="User guide"> |
| <p>Apache Commons Crypto is a cryptographic library optimized with AES-NI |
| (Advanced Encryption |
| Standard New Instructions). It provides Java API for both cipher level and Java stream |
| level. Developers can use it to implement high performance AES encryption/decryption with |
| the minimum code and effort. |
| </p> |
| <p> |
| Please note that Apache Commons Crypto doesn't implement the cryptographic |
| algorithm such as AES directly. It wraps OpenSSL or JCE which implement the algorithms. |
| OpenSSL 1.1.1 is required for building and running. |
| </p> |
| <subsection name="Interfaces Overview"> |
| <p>Interfaces and classes used by the various implementation in the sub-packages.</p> |
| <table> |
| <tr> |
| <td width="150"> |
| <a href="apidocs/index.html">random |
| </a> |
| </td> |
| <td> |
| The interface for CryptoRandom. |
| </td> |
| </tr> |
| <tr> |
| <td width="150"> |
| <a href="apidocs/index.html">cipher |
| </a> |
| </td> |
| <td> |
| The interface of cryptographic cipher for encryption and decryption. |
| </td> |
| </tr> |
| <tr> |
| <td width="150"> |
| <a href="apidocs/index.html">stream |
| </a> |
| </td> |
| <td> |
| The interface wraps the underlying stream, and it automatically encrypts |
| the stream when data is written and decrypts the stream when data is |
| read. |
| </td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name ="Usage"> |
| <h4>Prerequisites</h4> |
| <p> |
| Commons Crypto relies on standard JDK 1.8 (or above) and OpenSSL 1.1.1 for production |
| deployment. |
| If it is installed, the command <code>openssl version</code> can be used to show the version. |
| </p> |
| <p>OpenSSL may already be installed on your system; if not, please visit |
| <a href="https://www.openssl.org/">OpenSSL.org</a> for information on installation. |
| </p> |
| <h4>Using Commons Crypto in your Apache Maven build</h4> |
| <p> |
| To build with Apache Maven, add the dependencies listed below to your pom.xml file. |
| </p> |
| <pre> |
| <dependency><br/> |
| <groupId>org.apache.commons</groupId><br/> |
| <artifactId>commons-crypto</artifactId><br/> |
| <version>1.1.0</version><br/> |
| </dependency><br/> |
| </pre> |
| <h4>Usage of Random API</h4> |
| <p> |
| CryptoRandom provides a cryptographically strong random number generators. |
| The default implementation will use Intel® Digital Random Number Generator (DRNG) |
| for accelerating the random generation. |
| </p> |
| |
| <a href="xref-test/org/apache/commons/crypto/examples/RandomExample.html">RandomExample.java</a> |
| |
| <h4>Usage of Cipher API</h4> |
| <p> |
| Cipher provides a cryptographic interface for encryption and decryption. |
| We provide two kind of implementations: JCE Cipher and OpenSSL Cipher. The |
| JCE implementation uses JCE provider and the OpenSSL implementation uses |
| Intel® AES New Instructions (Intel® AES NI). |
| </p> |
| <h5>Usage of Byte Array Encryption/Decryption</h5> |
| |
| <a href="xref-test/org/apache/commons/crypto/examples/CipherByteArrayExample.html">CipherByteArrayExample.java</a> |
| |
| <h5>Usage of ByteBuffer Encryption/Decryption</h5> |
| |
| <a href="xref-test/org/apache/commons/crypto/examples/CipherByteBufferExample.html">CipherByteBufferExample.java</a> |
| |
| |
| <h4>Usage of Stream API</h4> |
| <p> |
| Stream provides the data encryption and decryption in stream manner. We provide CryptoInputStream, |
| CTRCryptoInputStream, PositionedCryptoInputStream implementations for InputStream and CryptoOutputStream, |
| CTRCryptoOutputStream implementations for OutputStream. |
| </p> |
| <h5>Usage of stream encryption/decryption</h5> |
| |
| <a href="xref-test/org/apache/commons/crypto/examples/StreamExample.html">StreamExample.java</a> |
| |
| </subsection> |
| </section> |
| </body> |
| </document> |
| |
