xdocs/ElementSerializers.xml (62 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>Element Serializers</title>
<author email="tv@apache.org">Thomas Vandahl</author>
</properties>
<body>
<section name="Serializing and De-serializing Cache Objects">
<p> When using auxiliary caches, cache elements need to be serialized
into a byte stream in order to be stored on disk or transported
through a network. For reading from these caches, bytes must be
de-serialized into objects. By default, JCS uses the standard JDK
methods for serializing and de-serializing objects. However, all
of the auxiliaries also support setting a custom serializer to
have finer control of the behavior.</p>
<p> This document describes the built-in serializers and their
configuration.</p>
</section>
<section name="Compressing Serializer">
<p> The <code>CompressingSerializer</code> gzips the bytes
after serializing the cache object the default way. For reading,
the bytes will be de-compressed first and then de-serialized into
a Java object. The class can also be used as a wrapper around an
arbitrary class implementing <code>IElementSerializer</code>.</p>
<p> The configuration for a typical application looks like this:</p>
<source>
<![CDATA[
# Block Disk Cache
jcs.auxiliary.blockDiskCache=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheFactory
jcs.auxiliary.blockDiskCache.attributes=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheAttributes
jcs.auxiliary.blockDiskCache.attributes.DiskPath=target/test-sandbox/block-disk-cache
jcs.auxiliary.blockDiskCache.serializer=org.apache.commons.jcs3.utils.serialization.CompressingSerializer
]]>
</source>
</section>
<section name="Encrypting Serializer">
<p> The <code>EncryptingSerializer</code> uses AES to encrypt the bytes
after serializing the cache object the default way. For reading,
the bytes will be decrypted first and then de-serialized into
a Java object. The class can also be used as a wrapper around an
arbitrary class implementing <code>IElementSerializer</code>.</p>
<p> The implementation uses a symmetrical pre-shared key phrase for
encrypting and decrypting the data. The key is salted separately
for each object and the salt is stored together with the serialized
data.</p>
<p> The configuration for a typical application looks like this:</p>
<source>
<![CDATA[
# Block Disk Cache
jcs.auxiliary.blockDiskCache2=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheFactory
jcs.auxiliary.blockDiskCache2.attributes=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheAttributes
jcs.auxiliary.blockDiskCache2.attributes.DiskPath=target/test-sandbox/block-disk-cache2
jcs.auxiliary.blockDiskCache2.serializer=org.apache.commons.jcs3.utils.serialization.EncryptingSerializer
jcs.auxiliary.blockDiskCache2.serializer.attributes.preSharedKey=my_secret
]]>
</source>
<p> The AES cipher transformation default is AES/ECB/PKCS5Padding as this
algorithm must be supported by every JDK 8, according to the
<a href="https://docs.oracle.com/javase/8/docs/api/javax/crypto/Cipher.html">docs</a>.
Special handling is provided for the AES/GCM/NoPadding algorithm which
can be activated like this:</p>
<source>
<![CDATA[
jcs.auxiliary.blockDiskCache2.serializer.attributes.aesCipherTransformation=AES/GCM/NoPadding
]]>
</source>
<p> The encryption code uses the default constructor of SecureRandom() to create
a random number generator. Depending on your security requirements, you should
configure a SecureRandom that works for your environment, giving preference to
the ones with good randomness (given that your environment generates entropy fast
enough, we saw problems with Linux).</p>
</section>
</body>
</document>