License3j Documentation

A license is a collection of features. Each feature consists of a name, a type, and a value.

Predefined Feature Names

• licenseId: Unique ID (UUID)
• licenseSignature: The signature (BINARY)
• signatureDigest: The digest of the license (STRING)
• expiryDate: The expiry date (DATE)

Supported Feature Types

• BINARY: byte[] array
• STRING: java.lang.String
• BYTE: single byte
• SHORT: single short
• INT: integer
• LONG: long
• FLOAT: float
• DOUBLE: double
• BIGINTEGER: java.math.BigInteger
• BIGDECIMAL: java.math.BigDecimal
• DATE: java.util.Date
• UUID: java.util.UUID

License Storage Formats

• BINARY: Most compact, suitable for files, not human-readable.
• BASE64: Binary format encoded in Base64 for printable characters.
• STRING: Human-readable UTF-8 text, suitable for manual editing.

To use License3j in your Java project, add the following dependency to your pom.xml. Check the Sonatype central repository for the latest version.

<dependency>
    <groupId>com.javax0.license3j</groupId>
    <artifactId>license3j</artifactId>
    <version>3.3.0</version>
</dependency>

To manage licenses (create, sign, etc.), use the license3jrepl application. To generate a new RSA key pair, run the following command within the REPL prompt (L3j> $):

generateKeys algorithm=RSA size=1024 format=BINARY public=public.key private=private.key

After generation, you can use the dumpPublicKey command in the REPL to get the Java code required to embed the public key directly into your application.

$ java -jar license3jrepl.jar
L3j> $ generateKeys algorithm=RSA size=1024 format=BINARY public=public.key private=private.key

A license in License3j is a collection of features. Each feature consists of a name, a type, and a value.

Supported feature types include:

• BINARY: Arbitrary byte[] array.
• STRING: java.lang.String.
• BYTE, SHORT, INT, LONG, FLOAT, DOUBLE, BIGINTEGER, BIGDECIMAL, DATE, UUID: Corresponding Java objects or primitives.

Note that there is no automatic conversion between different feature types; you must retrieve the value using the method corresponding to its type.

License3j supports three storage formats:

1. BINARY: The most compact and shortest format. It starts with magic bytes 0xCE, 0x21, 0x5E, 0x4E (LICENSE). It is not human-readable and is best for file storage.
2. BASE64: The binary format encoded in Base64. This ensures the license contains only printable characters, making it suitable for email or web transmission.
3. STRING (Text): A human-readable, UTF-8 encoded format suitable for manual editing.

Text Format Syntax: Each line represents a feature: name:TYPE=value.

• The type (e.g., STRING, INT) is optional for STRING types.
• For multi-line values (like long strings), use the << syntax:

  description:STRING=<<
  This is a multi-line
  description.
  >>

Reading a license file does not automatically verify its authenticity. To ensure the license has not been tampered with, you must verify its digital signature using a public key.

It is highly recommended to hard-code the public key into your application as a byte[] array rather than loading it from an external file. To verify, use the isSigned(byte[] key) method (or similar verification logic provided by the library) which returns true if the signature is valid for the provided key.

// Returns true if the license is signed and the signature is valid for the provided key
if (license.isSigned(publicKeyBytes)) {
    // Proceed with using license features
} else {
    // Handle invalid/tampered license
}

Use SimpleLicense to generate short, fixed-length license keys (four blocks of six characters separated by hyphens, e.g., DCWI3U-6RDTB8-EBMPTJ-TVURQ7). This is ideal for environments where you do not need to store specific features or electronic signatures.

To create a license, use .withSecret(String) to provide a private key that should be hidden in your code, and .forValue(String) to provide a user-specific identifier (like a user ID or license ID).

Note: The license key does not store the value itself; it is a shortened hash of the secret and the value.

final var lic = SimpleLicense
                  .withSecret("abraka dabra")
                  .forValue("my special user");
final var code = lic.toString();

To verify if a license code provided by a user is valid, use the isOK(String) method on a SimpleLicense instance configured with the same secret and value used during generation.

Example using Assertions.assertTrue for validation:

Assertions.assertTrue(lic.isOK(code));

Once a license is verified, you can retrieve specific features by their name using license.get(name). To get the actual value, call the type-specific method (e.g., .getDate(), .getString(), .getInt()) on the returned feature object.

Note that there is no automatic conversion between feature types; you must call the method corresponding to the feature's defined type.

// get a feature and from the feature type-specific data, like date, int, long, String...
Date birthday = license.get("bd").getDate();

Use the javax0.license3j.io.LicenseReader class to read a license file.

By default, the read() method assumes the file is in BINARY format. If the file is in BASE64 or STRING (text) format, you must specify the format using the IOFormat parameter.

If the file is unreadable or the format is incorrect, an IOException or IllegalArgumentException will be thrown.

// Example of reading a binary license
LicenseReader reader = new LicenseReader(new File("license.bin"));
License license = reader.read();

// Example of reading a text license
License license = reader.read(IOFormat.STRING);