The reference manual discusses the Cryptacular library from the perspective of a developer trying to get work done,
and as such we rely heavily on examples to demonstrate usage. We discuss some design matters where relevant,
but the reference manual is first and foremost a developer usage guide. The best reference on library design is the
There are some notable conventions used in the following examples:
All unqualified class names are either well-known classes in the JSE or Cryptacular components.
We make copious use of comments to clarify operations and the purpose of method parameters.
One of the most common pitfalls in cryptographic code is inattention to thread safety issues. In many cases problems
arise from poor documentation around whether components and their dependencies are thread safe. Cryptacular provides
a straightforward convention that identifies whether a component is safe.
A Cryptacular component is thread safe if any of the following is true:
Otherwise the component should be considered not thread safe unless explicity noted in the JavaDocs.
The remainder of the reference is organized by broad categories of either cryptographic operation or component type.
We cover only the most common components, component classes, and usage scenarios, but that ought to be a complete
introduction to library usage. The JavaDocs and source are intended to complement and complete the reference guide.
Cryptacular provides a number of components for common hashing operations such as hashing with output encoding
(e.g. hex) and salted hash comparison (e.g. password comparison). The following examples demonstrate common operations.
A common password authentication routine follows.
Encryption and decryption
Cryptacular provides a novel feature in its encryption routines that addresses a common pitfall in cryptographic coding, failing to provide a unique initialization vector (IV, nonce) on every encryption. Cryptography standards such as
NIST 800-38d are clear that unique nonces are required for every encryption under the same key
in order to provide any meaningful security. Cryptacular cipher routines force adherence to this practice by requiring
a Nonce object, a kind of generator,
that produces a unique nonce for every encryption. The nonce and an optional symbolic key name are
prepended to the beginning of the output where they become effectively a cleartext superblock containing information
about the following ciphertext. The superblock is subsequently used in decryption routines; since the nonce is stored
with the ciphertext, it is not needed for decryption. The symbolic key name is intended to support key rollover
processes where a hint is provided through the symbolic name about which of several possible keys was used to encrypt
The following example demonstrates a complete encryption and decryption process. AEAD-mode ciphers are demonstrated here
and recommended for new software.
The beans package provides thread safe components for common cryptographic operations: hashing, encryption, and key
management. Beans are configuration containers that allow reproducible operations with a particular configuration set;
for example, encryption under a particular key or hashing under a particular number of rounds.
In the following sections we provide examples of notable beans used in common scenarios. We provide Spring XML configuration along with each Java source excerpt to underscore component wiring, which is a
primary consideration when using beans.
The following example demonstrates how to perform encryption and decryption of data under a key that is
handled securely. All ciphertext data is base64 encoded to allow for more convenient handling.
The following example demonstrates how to generate a salted, hex encoded SHA-256 hash digest from a user-supplied
password and salt.
Cryptacular is an open source project developed and supported by
at Virginia Tech