Jagged

Java implementation of age encryption

Build Requirements

• Java 21
• Maven 3.9

Runtime Requirements

• Java 25, 21

Java Cryptography Architecture

Jagged uses the Java Cryptography Architecture framework for the following algorithms:

• ChaCha20-Poly1305 with javax.crypto.Cipher
• HmacSHA256 with javax.crypto.Mac
• PBKDF2WithHmacSHA256 with javax.crypto.SecretKeyFactory
• RSA with java.security.KeyFactory
• RSA/ECB/OAEPPadding with javax.crypto.Cipher
• X25519 with javax.crypto.KeyAgreement
• X25519 with java.security.KeyFactory
• X25519 with java.security.KeyPairGenerator

JEP 324 introduced X25519 Key Agreement in Java 11. JEP 329 added ChaCha20-Poly1305 in Java 11.

Jagged does not require additional dependencies when running on Java 21 or higher.

Versioning

Jagged follows the Semantic Versioning Specification 2.0.0.

Features

Jagged supports streaming encryption and decryption using standard recipient types.

• Encryption and decryption of binary age files
• Encryption and decryption of armored age files
• X25519 recipients and identities
• scrypt recipients and identities
• ssh-rsa recipients and identities
• ssh-ed25519 recipients and identities

Specifications

Jagged supports version 1 of the age-encryption.org specification.

The age encryption specification builds on a number of common cryptographic algorithms and encoding standards.

Formatting Standards

Files encrypted using the age specification include a textual header and binary payload.

File headers include a message authentication code computed using HMAC-SHA-256.

• RFC 2104 HMAC: Keyed-Hashing for Message Authentication

File headers include recipient stanza binary body elements encoded using Base64 Canonical Encoding.

• RFC 4648 The Base16, Base32, and Base64 Data Encodings

File payloads use a key derived using HKDF-SHA-256.

• RFC 5869 HMAC-based Extract-and-Expand Key Derivation Function (HKDF)

File payload encryption uses ChaCha20-Poly1305 for as the algorithm for Authenticated Encryption with Additional Data.

• RFC 7539 ChaCha20 and Poly1305 for IETF Protocols

Recipient Standards

Standard recipient types include asymmetric encryption using X25519 and passphrase encryption using scrypt.

The X25519 type uses Curve25519 for Elliptic Curve Diffie-Hellman shared secret key exchanges.

• RFC 7748 Elliptic Curves for Security

The X25519 type uses Bech32 for encoding public keys and private keys.

• BIP 0173 Base32 address format

The X25519 type encrypts a File Key with ChaCha20-Poly1305 using a key derived with HKDF-SHA-256.

The scrypt type uses a passphrase and configurable work factor with other preset values to derive the key for encrypting a File Key.

• RFC 7914 The scrypt Password-Based Key Derivation Function

The scrypt type encrypts a File Key with ChaCha20-Poly1305.

The ssh-ed25519 and ssh-rsa types support reading private key pairs formatted using OpenSSH Private Key Version 1.

• OpenSSH PROTOCOL.key

The ssh-ed25519 type uses Curve25519 for Elliptic Curve Diffie-Hellman shared secret key exchanges based on computing equivalent values from keys described in the Edwards-curve Digital Signature Algorithm edwards25519.

• RFC 8032 Edwards-Curve Digital Signature Algorithm

The ssh-ed25519 type reads SSH public keys encoded according to the SSH protocol.

• RFC 8709 Ed25519 and Ed448 Public Key Algorithms for the Secure Shell (SSH) Protocol

The ssh-ed25519 type encrypts a File Key with ChaCha20-Poly1305.

The ssh-rsa type reads SSH public keys encoded according to the SSH protocol.

• RFC 4253 The Secure Shell (SSH) Transport Layer Protocol

The ssh-rsa type encrypts a File Key with RSA-OAEP.

• RFC 8017 PKCS #1: RSA Cryptography Specifications Version 2.2

Modules

Jagged consists of multiple modules supporting different aspects of the age encryption specification.

• jagged-api
• jagged-bech32
• jagged-framework
• jagged-scrypt
• jagged-ssh
• jagged-test
• jagged-x25519

jagged-api

The jagged-api module contains the core public interfaces for encryption and decryption operations. The module contains interfaces and classes in the com.exceptionfactory.jagged package, which provide integration and extension points for other components.

The FileKey class implements java.crypto.SecretKey and supports the primary contract for age identities and recipients.

The RecipientStanza interface follows the pattern of the age Stanza, providing access to the Type, Arguments, and binary Body elements.

The RecipientStanzaReader interface serves as the age Identity abstraction, responsible for reading RecipientStanza objects and return a decrypted FileKey.

The RecipientStanzaWriter interface follows the age Recipient abstraction, responsible for wrapping a FileKey and returning a collection of RecipientStanza objects.

The EncryptingChannelFactory interface wraps a provided WritableByteChannel and returns a WritableByteChannel that supports streaming encryption to one or more recipients based on supplied RecipientStanzaWriter instances.

The DecryptingChannelFactory interface wraps a provided ReadableByteChannel and returns a ReadableByteChannel that supports streaming decryption for a matched identity based on supplied RecipientStanzaReader instances.

jagged-bech32

The [jagged-bech32](https://javadoc.io/doc/com.exceptionfactory.jagged/jagge