API reference

All operations are static methods on io.github.aniketc068.atick.Atick. Every method takes raw byte[] for PDFs and certificates, and an options JSON string where applicable. On any failure a method throws Atick.AtickException — a public static class extending RuntimeException. The error text is available from e.getMessage().

import io.github.aniketc068.atick.Atick;

Signing

static byte[] signPfx(byte[] pdf, byte[] pfx, String optionsJson)

Sign pdf with a .pfx/.p12/.pem credential (the format is auto-detected). For a PEM file pass the password as the empty string "" inside the options. Returns the signed PDF bytes.

• pdf — the PDF to sign.
• pfx — the credential bytes (.pfx, .p12, or .pem).
• optionsJson — the options JSON (see the Options table). Pass the credential password as the password key; use "" for PEM.
• returns — the signed PDF as byte[].

import io.github.aniketc068.atick.Atick;

byte[] pdf = Files.readAllBytes(Path.of("in.pdf"));
byte[] pfx = Files.readAllBytes(Path.of("signer.pfx"));

String options = """
    {
      "password": "secret",
      "cn": "Axonate Tech",
      "reason": "Approval",
      "page": 1,
      "rect": [40, 40, 240, 140],
      "pades": true,
      "timestamp": true,
      "tsa_url": "http://timestamp.example/tsa"
    }
    """;

try {
    byte[] signed = Atick.signPfx(pdf, pfx, options);
    Files.write(Path.of("signed.pdf"), signed);
} catch (Atick.AtickException e) {
    System.err.println("signing failed: " + e.getMessage());
}

static byte[] signField(byte[] pdf, byte[] pfx, String optionsJson)

Sign an existing empty signature field. Use the field_name option to select the field. Returns the signed PDF bytes.

• pdf — a PDF containing an empty signature field (see prepareFields).
• pfx — the credential bytes.
• optionsJson — must include field_name; same credential and signing keys as signPfx.
• returns — the signed PDF as byte[].

Deferred / remote-key signing

These three methods cover the deferred (eSign / HSM / remote-key) flow: prepare the PDF, sign the returned bytes elsewhere, then embed the resulting CMS.

static byte[][] prepare(byte[] pdf, String optionsJson)

Step 1 of deferred signing. Adds an empty signature field, the appearance, and the signature container, then returns the exact bytes that must be signed. Returns a byte[][] of length 2:

• index 0 — the prepared PDF (byte[]).
• index 1 — the bytes to sign (byte[]); hash and sign these with the remote key.

• pdf — the PDF to prepare.
• optionsJson — appearance and signing options (see the Options table).
• returns — byte[][]{ prepared, bytesToSign }.

static byte[] cmsPfx(byte[] data, byte[] pfx, String optionsJson)

Produce a detached PKCS#7 / CMS signature over data using a PFX. Useful for producing the CMS that embed expects when the signing credential is a local PFX.

• data — the bytes to sign (typically index 1 from prepare).
• pfx — the credential bytes.
• optionsJson — password, hash_algo, pades, timestamp, tsa_url, tsa_auth, ltv, revocation.
• returns — the detached CMS as byte[].

Pass "revocation":true to embed the RevocationInfoArchivalattribute (the signer's CRL / OCSP responses) inside the produced CMS, so the signature carries its own revocation evidence.

static byte[] embed(byte[] prepared, byte[] cms)

Embed a detached CMS / PKCS#7 into a prepared PDF. Returns the signed PDF bytes.

• prepared — the prepared PDF (index 0 from prepare).
• cms — the detached CMS (from cmsPfx, an eSign reply, or an HSM).
• returns — the signed PDF as byte[].

import io.github.aniketc068.atick.Atick;

byte[][] step = Atick.prepare(pdf, options);
byte[] prepared    = step[0];
byte[] bytesToSign = step[1];

byte[] cms    = Atick.cmsPfx(bytesToSign, pfx, "{\"password\":\"secret\"}");
byte[] signed = Atick.embed(prepared, cms);

Field templates

static byte[] prepareFields(byte[] pdf, String optionsJson)

Create an empty signature field as a template: the appearance is drawn, but the signature is left empty so it can be signed later with signField. Returns the PDF bytes.

• pdf — the PDF to add the field to.
• optionsJson — appearance options plus field_name, page, rect / placements.
• returns — the PDF with an empty field as byte[].

Long-term validation & timestamps

static byte[] addDocTimestamp(byte[] pdf, String optionsJson)

Add an archive DocTimeStamp (and the DSS validation material) to an already-signed PDF, producing a PAdES-B-LTA document. Returns the timestamped PDF bytes.

• pdf — an already-signed PDF.
• optionsJson — tsa_url, tsa_auth, ltv, contents_size.
• returns — the timestamped PDF as byte[].

addDocTimestamp also adds the DSS validation material for the timestamp certificate chain, so the archive timestamp is itself long-term verifiable.

Documents & utilities

static byte[] setMetadata(byte[] pdf, String optionsJson)

Set the document information (/Info) metadata on a PDF. Returns the updated PDF bytes.

• pdf — the PDF to update.
• optionsJson — title, author, subject, keywords, application, created, modified (see the Metadata options table).
• returns — the updated PDF as byte[].

static byte[] decrypt(byte[] pdf, String password)

Decrypt a password-protected PDF. Returns the plaintext PDF bytes.

• pdf — the encrypted PDF.
• password — the open (user) password.
• returns — the decrypted PDF as byte[].

static void setFastSigning(boolean on)

Enable or disable the in-memory revocation cache (used to speed up repeated CRL/OCSP lookups). Passing false disables it.

• on — true to enable the cache, false to disable it.

static String version()

Return the library version string.

• returns — the version as a String.

System.out.println("ATick " + Atick.version());

Options JSON

The optionsJson argument is a JSON object string. All keys are optional unless a method note says otherwise. Keys are grouped below by purpose.

Identity & appearance text

Verified mark

Layout & styling

Appearance fine-tuning

Placement

Cryptography & PAdES

Certification & locking

Verification

Each check runs before signing; if it fails, no output is produced and the method throws Atick.AtickException. Use verify to run all checks at once, or enable the granular keys individually.

String options =
    "{\"password\":\"secret\"," +
    "\"verify_expiry\":true," +     // refuse if expired / not yet valid
    "\"verify_crl\":true," +        // pre-sign CRL check
    "\"verify_ocsp\":true," +       // pre-sign OCSP check
    "\"trusted_roots\":[\"<base64 DER root>\"]}";

Document security

Metadata options

These keys apply to setMetadata.

Exceptions

public static class AtickException extends RuntimeException

Thrown by every Atick operation on failure — bad password, malformed PDF, network error, invalid options, and so on. The error text is available from getMessage().

try {
    byte[] signed = Atick.signPfx(pdf, pfx, options);
} catch (Atick.AtickException e) {
    System.err.println("ATick error: " + e.getMessage());
}