jfabe

jfabe is a JAVA library for Ciphertext-Policy Attribute-based Encryption (CP-ABE).

Warning

Please read the Security section before considering using the library in any kind of production environment. This library is provided "AS IS", without warranty of any kind.

Context

jfabe is designed for descentralized and distributed systems, such as fully replicated distributed databases. It is primarily used by Byransha, which adopts the following architecture :

• Nodes contain full replicas of the database;
• All sensitive documents are encrypted with ABE;
• A central key manager provisions each node with specific access attributes ;
• Decryption happens offline and locally, meaning there is no interactive "decryption oracle" for attackers to probe. However, in a distributed system, compromised nodes can attempt malicious data injection or ciphertext tampering. For these and other situations, jfabe allows for CCA (Chosen Ciphertext Attack) security using AEAD-backed KEM transforms.

How to Use

Add JitPack and jfabe to pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.alexandreboutrik</groupId>
        <artifactId>jfabe</artifactId>
        <version>v1.0.0</version>
    </dependency>
</dependencies>

API

import io.github.alexandreboutrik.jfabe.api.JfabeClient;
import io.github.alexandreboutrik.jfabe.api.models.*;
import io.github.alexandreboutrik.jfabe.api.enums.*;
import io.github.alexandreboutrik.jfabe.exceptions.*;

JfabeClient abe = JfabeClient.builder()
    .withScheme(Scheme.FABEO)
    .withTransform(Transform.FO_KEM_AEAD)
    // .withFeature(Feature.TRACEABILITY)
    .build();

String[] keyAttrList = {"Team_A", "Team_B"};
String policy = "(Team_A AND Team_B) OR Team_C";
String documentData = "This is the document's data";

JfabeSetup setup = abe.setup();
JfabePublicKey pk = setup.getPublicKey();
JfabeMasterSecretKey msk = setup.getMasterSecretKey();

JfabeSecretKey sk = abe.keygen(pk, msk, keyAttrList);

JfabeCiphertext encryptedDocument = abe.encrypt(pk, documentData, policy);

try {
    JfabePlaintext decryptedDocument = abe.decrypt(pk, sk, encryptedDocument);
    byte[] recoveredDocument = decryptedDocument.getBytes();
} catch (UnsatisfiedPolicyException e) {
    // User's attributes do not satisfy the document's policy.
} catch (CiphertextIntegrityException e) {
    // Ciphertext has been tampered with or corrupted.
}

Limitations

Boolean AND/OR Logic Only. The policy parser and Monotone Span Program (MSP) generation only support boolean logic (AND/OR gates). Threshold gates (e.g., "2 out of 3 attributes") are NOT supported. This restriction allows us to use the Lewko-Waters algorithm to improve encryption/decryption speeds. This optimization bypasses expensive scalar multiplications by assuming MSP matrix coefficients will only ever be -1, 0, or 1.

Attribute Naming Constraints. Attribute names must be alphanumeric and can only contain underscores (_) or hyphens (-). Spaces and other special characters are rejected by the AST parser. Additionally, the null byte (\0) is reserved as an internal delimiter for duplicate attribute handling and will throw an exception if passed to the key generation or encryption engines.

Policy Complexity Limits. To prevent overflows and memory exhaustion, access policies cannot exceed I) A length of 10,000 characters; II) A parenthesis nesting depth of 50; and III) A resulting MSP matrix width of 1,000 columns.

Payload Size Limitations (without Transforms): If the JfabeClient is built using Transform.NONE (pure mathematical CPA security), the encryption payload size is limited at 256 bytes. For encrypting standard documents, JSON, or arbitrary-length data, you MUST configure the client with a transform decorator (e.g., Transform.FO_KEM_AEAD).

Security

Constant-Time Execution. As outlined in the Context section, jfabe is designed mainly for decentralized, offline decryption. To ensure maximum portability across these distributed systems, the decision was made to keep this library in pure Java. Because of that restriction, we CANNOT guarantee any kind of constant-time execution or resilience against side-channel attacks. Please keep this limitation in mind when evaluating the library against your specific threat model.

Post-Quantum Cryptography. Currently, the ABE schemes implemented in jfabe are all classical algorithms. Therefore, this library should not be used in environments that require post-quantum security guarantees. A post-quantum scheme (potentially based on Ring Learning with Errors, or R-LWE) may or may not be implemented in the future to ensure compliance with the ANSSI-FR 2030 deadline.

Author

This library was developed by Alexandre Boutrik during a research internship within the SCALE team at the I3S Laboratory (UMR 7271 Université Côte d'Azur, CNRS).

LICENSE

This project is licensed under the Apache License, Version 2.0. You may use, distribute, and modify this code under the terms of the license. See the LICENSE file for more information.