### Example: Create and Sign ASiC-E in Test Environment

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

A complete example demonstrating the creation and signing of an ASiC-E container in a testing environment using PKCS#11.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "test.asice" -add "test.pdf" "application/pdf" -pkcs11 "/usr/local/lib/opensc-pkcs11.so" "12345" "1"
```

--------------------------------

### Example with TEST Mode and PKCS11

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

An example demonstrating the use of the TEST mode for digidoc4j and signing a PDF document using a PKCS11 module with a specified slot index.

```bash
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in test.bdoc -add dds_acrobat.pdf application/pdf -pkcs11 /usr/local/lib/opensc-pkcs11.so 22975 1
```

--------------------------------

### Run digidoc4j Utility

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Execute the digidoc4j utility jar to display available commands. This is the basic command to start the tool.

```shell
java -jar digidoc4j-util.jar
```

--------------------------------

### Example: Using Custom Container and Signature Builder

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Demonstrates the end-to-end process of creating a container with a custom implementation, preparing data for signing, signing it, and adding the signature back to the container.

```java
// Set TestContainer class to be used for TEST-FORMAT container types
ContainerBuilder.setContainerImplementation("TEST-FORMAT", TestContainer.class);
Container container = ContainerBuilder
		.aContainer("TEST-FORMAT")
		.withDataFile("testFiles/legal_contract_1.txt", "text/plain")
		.build();

//Get the certificate (with a browser plugin, for example)
X509Certificate signingCert = getSignerCertSomewhere();

// Set TestSignatureBuilder class to be used for TEST-FORMAT container types
SignatureBuilder.setSignatureBuilderForContainerType("TEST-FORMAT", TestSignatureBuilder.class);
//Get the data to be signed by the user
DataToSign dataToSign = SignatureBuilder
		.aSignature(container)
		.withSigningCertificate(signingCert)
		.withSignatureDigestAlgorithm(DigestAlgorithm.SHA256)
		.buildDataToSign();

//Data to sign contains the signature dataset (including digest of file(s) that should be signed)
byte[] signableData = dataToSign.getDataToSign();
byte[] signatureValue = signDataSomewhereRemotely(signableData, DigestAlgorithm.SHA256);

//Finalize the signature
Signature signature = dataToSign.finalize(signatureValue);

//Add signature to the container
container.addSignature(signature);
```

--------------------------------

### External Signing Example (Web)

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Demonstrates a two-step external signing process suitable for web applications. Requires implementing methods to fetch signing certificates and remotely sign data.

```java
//Create a container with a text file to be signed
Container container = ContainerBuilder
		.aContainer()
		.withDataFile("testFiles/legal_contract_1.txt", "text/plain")
		.build();

//Get the certificate (with a browser plugin, for example)
X509Certificate signingCert = getSignerCertSomewhere();

//Get the data to be signed by the user
DataToSign dataToSign = SignatureBuilder
		.aSignature(container)
		.withSigningCertificate(signingCert)
		.withSignatureDigestAlgorithm(DigestAlgorithm.SHA256)
		.buildDataToSign();

//Data to sign contains the signature dataset including the digest of the file(s) that should be signed
byte[] signableData = dataToSign.getDataToSign();

//Sign the signature dataset
byte[] signatureValue = signDataSomewhereRemotely(signableData, DigestAlgorithm.SHA256);

//Finalize the signature with OCSP response and timestamp
Signature signature = dataToSign.finalize(signatureValue);

//Add signature to the container
container.addSignature(signature);

//Save the container as a .asice file
container.saveAsFile("test-container.asice");
```

--------------------------------

### JavaScript Example for Signing with hwcrypto.js

Source: https://github.com/open-eid/digidoc4j/wiki/Questions-&-Answers

This JavaScript code demonstrates how to initiate a signing process using the hwcrypto.js library. It's crucial to ensure that the signing process is not re-initiated before completion to prevent synchronization issues.

```javascript
function sign(dataToSign) {
    return hwcrypto.sign(
        new hwcrypto.DataFormat(dataToSign, "hex"),
        new hwcrypto.BinaryFormat(null, "hex"),
        "SHA-512"
    );
}
```

--------------------------------

### Signing Example with Local Private Key

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Signs two text files using a private key stored in a PKCS12 file. Ensure the private key file path and password are correct.

```java
//Create a container with two text files to be signed
Container container = ContainerBuilder
		.aContainer()
		.withDataFile("testFiles/legal_contract_1.txt", "text/plain")
		.withDataFile("testFiles/legal_contract_2.txt", "text/plain")
		.build();

//Using the private key stored in the "signout.p12" file with password "test"
String privateKeyPath = "testFiles/signout.p12";
char[] password = "test".toCharArray();
PKCS12SignatureToken signatureToken = new PKCS12SignatureToken(privateKeyPath, password);

//Create a signature
Signature signature = SignatureBuilder
		.aSignature(container)
		.withSignatureToken(signatureToken)
		.invokeSigning();

//Add the signature to the container
container.addSignature(signature);

//Save the container as a .asice file
container.saveAsFile("test-container.asice");
```

--------------------------------

### Configure DigiDoc4j via YAML

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Declare DigiDoc4j settings in a YAML file for declarative configuration. This example shows all optional settings.

```yaml
# digidoc4j.yaml — full optional settings example
LOTL_LOCATION: "https://ec.europa.eu/tools/lotl/eu-lotl.xml"
LOTL_TRUSTSTORE_PATH: "classpath:truststores/lotl-truststore.p12"
LOTL_TRUSTSTORE_PASSWORD: "digidoc4j-password"
LOTL_TRUSTSTORE_TYPE: "PKCS12"

TRUSTED_TERRITORIES: EE, LV, LT

OCSP_SOURCE: "http://ocsp.sk.ee/"
PREFER_AIA_OCSP: true

TSP_SOURCE: "http://tsa.sk.ee"
TSP_SOURCE_FOR_ARCHIVE_TIMESTAMPS: "http://tsa.sk.ee"
ARCHIVE_TIMESTAMP_DIGEST_ALGORITHM: SHA512

HTTP_PROXY_HOST: proxy.example.com
HTTP_PROXY_PORT: 8080
HTTPS_PROXY_HOST: proxy.example.com
HTTPS_PROXY_PORT: 8080

SSL_TRUSTSTORE_PATH: "path/to/ssl/truststore.p12"
SSL_TRUSTSTORE_PASSWORD: "changeit"
SSL_TRUSTSTORE_TYPE: PKCS12

MAX_ALLOWED_ZIP_COMPRESSION_RATIO: 100
ZIP_COMPRESSION_RATIO_CHECK_THRESHOLD_IN_BYTES: 1048576

ALLOWED_TS_AND_OCSP_RESPONSE_DELTA_IN_MINUTES: 15
```

--------------------------------

### Create Timestamped ASiC-S Container with Options

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Example of creating a timestamped ASiC-S container with specific options for timestamp digest algorithm, reference digest algorithm, and TSP source URL for archive timestamps.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -tst -datst SHA384 -refdatst SHA512 -tspsourcearchive http://tsa.demo.sk.ee/tsarsa
```

--------------------------------

### Create Detached XAdES Signature from Scratch

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

This example demonstrates creating a detached XAdES signature using a signature token. It requires pre-calculating the data digest.

```java
byte[] digest = MessageDigest.getInstance("SHA-256").digest("test".getBytes());
DigestDataFile digestDataFile = new DigestDataFile("test.txt", DigestAlgorithm.SHA256, digest, "text/plain");

Configuration configuration = Configuration.of(Configuration.Mode.TEST);

Signature signature = DetachedXadesSignatureBuilder
    .withConfiguration(configuration)
    .withDataFile(digestDataFile)
    .withSignatureProfile(SignatureProfile.LT)
    .withSignatureToken(pkcs12EccSignatureToken)
    .invokeSigning();
```

--------------------------------

### Wrap a Serialized Container Stream in a Timestamped ASiC-S Container

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

This example shows how to wrap a container from an input stream into a timestamped ASiC-S container with a given configuration. This method is also recommended for preserving byte-wise equivalence.

```java
CompositeContainer nestingContainer = CompositeContainerBuilder
		.fromContainerStream(containerInputStream, "container-name.asice")
		.withConfiguration(configuration)
		.buildTimestamped(timestampBuilder -> {});
```

--------------------------------

### Get AdES Signature XML Bytes

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Retrieve the XML representation of the generated AdES signature.

```java
byte[] signatureXmlBytes = signature.getAdESSignature();
```

--------------------------------

### Get Signing Certificate

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

Retrieve the signer's certificate, which is necessary for external signing processes. This certificate is obtained through a separate method.

```java
X509Certificate signingCert = getSignerCertSomewhere();
```

--------------------------------

### ASiC-S Container Timestamping Example

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Adds a timestamp token to an ASiC-S container. This can be done multiple times, with each timestamp covering previous assertions.

```java
// Create or load an ASiC-S container
Container container = ...;

// Create a timestamp token
Timestamp timestamp = TimestampBuilder
		.aTimestamp(container)
		.invokeTimestamping();

// Add the timestamp token to the container
container.addTimestamp(timestamp);

// Save the container as a .asics file
container.saveAsFile("test-container.asics");
```

--------------------------------

### Create and Sign ASiC-E Container with PKCS#12

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Add a datafile to a container and sign it using a PKCS#12 keystore. A new container is created if it doesn't exist.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>"
```

--------------------------------

### Get Default Singleton Configuration

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

Access the default singleton configuration object, which is used by all containers unless overridden. This is efficient as it allows caching, such as for TSL.

```java
Configuration configuration = Configuration.getInstance();
```

--------------------------------

### Clone and Build DigiDoc4j with Maven

Source: https://github.com/open-eid/digidoc4j/wiki/Development

Use these commands to clone the repository and build the project using the Maven wrapper.

```bash
git clone https://github.com/open-eid/digidoc4j.git

cd digidoc4j
./mvnw clean package
```

--------------------------------

### Get Default Configuration Instance in Java

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Retrieve the singleton instance of the default configuration object. This configuration is used by all containers and is beneficial for performance as it caches resources like TSL.

```java
// Getting the singleton configuration object
// This is the default configuration object used in all containers
Configuration configuration = Configuration.getInstance();
```

--------------------------------

### Initialize Configuration in TEST Mode

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Configure DigiDoc4j for testing using demo endpoints. Pre-load TSL for faster initial requests and set trusted territories.

```java
import org.digidoc4j.Configuration;

// Singleton (mode derived from digidoc4j.mode system property; defaults to PROD)
Configuration configuration = Configuration.getInstance();

// Explicit TEST mode (uses demo OCSP/TSA/TSL endpoints)
Configuration testConfig = Configuration.of(Configuration.Mode.TEST);

// Pre-load TSL at application startup to avoid first-request latency (5–15 s)
testConfig.getTSL().refresh();

// Restrict to specific trusted territories (skips downloading others)
testConfig.setTrustedTerritories("EE", "LV", "FR");

// Override OCSP responder fallback
testConfig.setOcspSource("http://custom.ocsp/");

// Configure HTTP/HTTPS proxy
testConfig.setHttpProxyHost("proxy.example.com");
testConfig.setHttpProxyPort(8080);
testConfig.setHttpsProxyHost("proxy.example.com");
testConfig.setHttpsProxyPort(8080);

// Custom LOTL truststore (required after EU LOTL signer certificate rotation)
testConfig.setLotlTruststorePath("classpath:truststores/lotl-truststore.p12");
testConfig.setLotlTruststorePassword("digidoc4j-password");
testConfig.setLotlTruststoreType("PKCS12");
```

--------------------------------

### Create and Sign ASiC-E Container with PKCS#11

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Add a datafile to a container and sign it using a PKCS#11 token (like an ID-card). A new container is created if it doesn't exist.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"
```

--------------------------------

### Create Production Configuration Directly in Java

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Instantiate a production configuration object directly. This is the default mode and is used for live operations.

```java
// Production configuration
Configuration configuration = Configuration.of(Configuration.Mode.PROD);
```

--------------------------------

### Initialize PKCS12 Signature Token

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

Create a PKCS12SignatureToken instance by providing the path to the private key file (e.g., a .p12 file) and the password for the private key.

```java
String privateKeyPath = "testFiles/signout.p12";
char[] password = "test".toCharArray();
PKCS12SignatureToken signatureToken = new PKCS12SignatureToken(privateKeyPath, password);
```

--------------------------------

### Get Timestamp Token Details in Java

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Extract information from timestamp tokens within a container, such as creation time, digest algorithm, and the signing certificate. This is useful for verifying the integrity and timeliness of timestamps.

```java
// Obtain the timestamp token of your choice from a container
Timestamp timestamp = container.getTimestamps().get(0);

// Timestamp creation time
Date creationTime = timestamp.getCreationTime();
// Timestamp digest algorithm
DigestAlgorithm digestAlgorithm = timestamp.getDigestAlgorithm();
// The signing certificate of the timestamp, if available
X509Cert certificate = timestamp.getCertificate();
// TimeStampToken object encapsulating the CMS signed data of the timestamp token
TimeStampToken timeStampToken = timestamp.getTimeStampToken();
```

--------------------------------

### Configure HTTP and HTTPS Proxies via YAML

Source: https://github.com/open-eid/digidoc4j/wiki/Questions-&-Answers

Set up HTTP and HTTPS proxy servers using environment variables in a YAML configuration file. Ensure both are configured if both connection types are required.

```yaml
HTTP_PROXY_HOST: proxy.host
HTTP_PROXY_PORT: 1234
HTTPS_PROXY_HOST: proxy.host
HTTPS_PROXY_PORT: 1234
```

--------------------------------

### Configure Digidoc4j for Test Environment

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

Instantiate the Configuration class with TEST mode to use test servers for OCSP and Timestamping. Alternatively, set the 'digidoc4j.mode' system property to 'TEST'.

```java
Configuration configuration = new Configuration(Configuration.Mode.TEST);
```

--------------------------------

### Open and Read Existing Detached XAdES Signature

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

This example shows how to load an existing detached XAdES signature from its XML representation. It requires reconstructing the DigestDataFile object with the original file's details.

```java
// Get the existing detached XAdES signature
byte[] xadesSignature = getSignatureXmlFromSomeWhere();

// Construct the digest-based data file object from original file that was signed with the above-mentioned signature
DigestDataFile digestDataFile = new DigestDataFile(getFileName(), DigestAlgorithm.SHA256, getFileDigest(), "text/plain");

Configuration configuration = Configuration.of(Configuration.Mode.TEST);

Signature signature = DetachedXadesSignatureBuilder
    .withConfiguration(configuration)
    .withDataFile(digestDataFile)
    .openAdESSignature(xadesSignature);
```

--------------------------------

### Get Signer Certificate Country Code

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Retrieve the country code from a signer's X.509 certificate. This can be used to dynamically select the appropriate Digidoc4j configuration object when supporting multiple OCSP responders.

```java
//Get the country code of the signer
X509Certificate signerCert;
X509Cert cert = new X509Cert(signerCert);
String countryCode = cert.getSubjectName(X509Cert.SubjectName.C);
```

--------------------------------

### Run DigiDoc4j Tests with Maven

Source: https://github.com/open-eid/digidoc4j/wiki/Development

Execute the project's test suite using the Maven wrapper.

```bash
./mvnw test
```

--------------------------------

### Open Digital Containers with ContainerOpener

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Demonstrates opening digital containers from various sources like file paths and InputStreams. Supports explicit configuration and big files.

```java
import org.digidoc4j.*;
import org.apache.commons.io.FileUtils;
import java.io.File;
import java.io.InputStream;

Configuration configuration = Configuration.of(Configuration.Mode.PROD);

// Open from file path
Container fromFile = ContainerOpener.open("signed-contract.asice");

// Open from file path with explicit configuration
Container fromFileWithConfig = ContainerOpener.open("signed-contract.bdoc", configuration);

// Open from InputStream (big files support enabled)
InputStream inputStream = FileUtils.openInputStream(new File("signed-contract.asice"));
Container fromStream = ContainerOpener.open(inputStream, true);

// Open via ContainerBuilder (preserves byte-wise serialization for composite wrapping)
Container fromBuilder = ContainerBuilder
        .aContainer()
        .fromExistingFile("signed-container.asice")
        .withConfiguration(configuration)
        .build();

System.out.println("Signatures: " + fromFile.getSignatures().size());
System.out.println("Container type: " + fromFile.getType());
```

--------------------------------

### Add Timestamp Token to ASiC-S Container

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Timestamp an ASiC-S container to prove its integrity. This example shows how to create a container, add a timestamp token with specified algorithms and TSA source, and then inspect the created timestamp.

```java
import org.digidoc4j.*;

Configuration configuration = Configuration.of(Configuration.Mode.TEST);

// Create or load an ASiC-S container
Container container = ContainerBuilder
        .aContainer(Container.DocumentType.ASICS)
        .withConfiguration(configuration)
        .withDataFile("archive.bdoc", "application/vnd.etsi.asic-e+zip")
        .build();

// Create and add first timestamp token
Timestamp ts = TimestampBuilder
        .aTimestamp(container)
        .withTimestampDigestAlgorithm(DigestAlgorithm.SHA256)
        .withReferenceDigestAlgorithm(DigestAlgorithm.SHA384)
        .withTspSource("http://tsa.demo.sk.ee/tsa")
        .invokeTimestamping();

container.addTimestamp(ts);

// Inspect timestamp
System.out.println("Created at: " + ts.getCreationTime());
System.out.println("Algorithm: " + ts.getDigestAlgorithm());

container.saveAsFile("archive.asics");
```

--------------------------------

### Sign a file with PKCS#12 using digidoc4j-util.jar

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Use the digidoc4j-util.jar to sign a file with a PKCS#12 certificate in TEST mode. This command creates a test.asice file.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar \
  -in "test.asice" \
  -add "document.pdf" "application/pdf" \
  -pkcs12 "signer.p12" "test"

```

--------------------------------

### Create Multiple Signed Containers

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Use this command to create signed containers for all data files within a specified input directory. The output containers will be saved to the specified output directory. PKCS#11 module path, token PIN, and slot index are required for signing.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -inputDir "<input_directory_path>" -mimeType "<mime_type (optional)>" -outputDir "<output_directory_path>" -pkcs11 "<pkcs11_module_path>" "<pkcs11_token_pin_password>" "<pkcs11_slot_index>"
```

--------------------------------

### Get Signature Details in Java

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Retrieve various details about a digital signature, including signing times, signer information, signature profile, and the signer's certificate. Use this to inspect and verify signature attributes.

```java
// Signature creation time confirmed by OCSP or TimeStamp authority.
Date trustedSigningTime = signature.getTrustedSigningTime();

// Signature creation time in the signer's computer (unofficial signing time)
Date claimedSigningTime = signature.getClaimedSigningTime();

// Signer info: city, state, postal code, country and signer roles
String city = signature.getCity();
String stateOrProvince = signature.getStateOrProvince();
String postalCode = signature.getPostalCode();
String country = signature.getCountryName();
List<String> signerRoles = signature.getSignerRoles();

// Signature profile: LT, LTA etc.
SignatureProfile signatureProfile = signature.getProfile();

// The full (XAdES) signature in bytes containing OCSP, TimeStamp etc
byte[] adESSignature = signature.getAdESSignature();

// Signer's certificate information: ID Code, first name, last name, country code etc.
X509Cert certificate = signature.getSigningCertificate();
String signerIdCode = certificate.getSubjectName(SERIALNUMBER);
String signerFirstName = certificate.getSubjectName(GIVENNAME);
String signerLastName = certificate.getSubjectName(SURNAME);
String signerCountryCode = certificate.getSubjectName(C);
```

--------------------------------

### Wrap an Existing Container in a Timestamped ASiC-S Container

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

This example demonstrates how to use CompositeContainerBuilder to wrap an existing container object into a new ASiC-S container and timestamp it. An empty lambda is provided for buildTimestamped if no additional timestamping parameters are needed.

```java
CompositeContainer nestingContainer = CompositeContainerBuilder
		.fromContainer(containerToBeNested, "container-name.asice")
		.buildTimestamped(timestampBuilder -> {});
```

--------------------------------

### Open an Existing Container from a File

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Opens an existing container from a specified file path.

```java
Container container = ContainerOpener
		.open("testFiles/test-container.asice");
```

--------------------------------

### Create Multiple Signed Containers from Directory

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

Process all files in an input directory to create signed containers, saving them to an output directory. Supports optional MIME type specification and PKCS11 authentication.

```bash
java -jar digidoc4j-util.jar -inputDir "<input_directory_path>" -mimeType "<mime_type (optional)>" -outputDir "<output_directory_path>" -pkcs11 "<pkcs11_module_path>" "<pkcs11_token_pin_password>" "<pkcs11_slot_index>"
```

--------------------------------

### Extend Signatures to LTA Profile

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Extend signatures to a higher profile for long-term archival integrity. It's crucial to check extendability first to avoid unnecessary TSA requests. This example demonstrates checking for errors and then extending valid signatures.

```java
import org.digidoc4j.*;
import org.digidoc4j.impl.asic.AsicContainer;
import java.util.*;

Container container = ContainerOpener.open("signed-contract.asice");
List<Signature> signatures = container.getSignatures();

// Check extendability before making paid TSA requests
Map<String, DigiDoc4jException> errors = 
        ((AsicContainer) container).getExtensionValidationErrors(SignatureProfile.LTA, signatures);

List<Signature> extendable = new ArrayList<>();
for (Signature s : signatures) {
    if (errors.containsKey(s.getUniqueId())) {
        System.out.println("Cannot extend " + s.getUniqueId() + ": " + errors.get(s.getUniqueId()).getMessage());
    } else {
        extendable.add(s);
    }
}

if (extendable.isEmpty()) {
    throw new RuntimeException("No signatures can be extended");
}

// Extend valid signatures to LTA (adds archive timestamp)
container.extendSignatureProfile(SignatureProfile.LTA, extendable);
container.saveAsFile("signed-contract-lta.asice");
System.out.println("Extended " + extendable.size() + " signature(s) to LTA");
```

--------------------------------

### Sign with PKCS#12

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Sign a file using a PKCS#12 token. Requires the token file path and password.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>" -sigOutputPath "<signature_file_path>"
```

--------------------------------

### Run digidoc4j Utility in Test Mode

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Invoke the utility in test mode using the -Ddigidoc4j.mode=TEST system property. This enables demo services and certificates for testing purposes.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar
```

--------------------------------

### Create Test Configuration Directly in Java

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Instantiate a testing configuration object directly. This approach allows for explicit control over the configuration mode without relying on environment variables.

```java
// Testing configuration
Configuration configuration = Configuration.of(Configuration.Mode.TEST);
```

--------------------------------

### Add Signature to Existing Container with PKCS#12

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Add a signature to an existing ASiC-E container using a PKCS#12 keystore without adding new datafiles.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>"
```

--------------------------------

### Configure LOTL Truststore Path (YAML)

Source: https://github.com/open-eid/digidoc4j/wiki/Questions-&-Answers

Set the LOTL truststore path via digidoc4j.yaml configuration. Use LOTL_TRUSTSTORE_PATH for classpath resources.

```yaml
LOTL_TRUSTSTORE_PATH: "classpath:truststores/lotl-truststore.p12"
```

--------------------------------

### Pre-load TSL in Digidoc4j

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Call this method during application startup to download TSL separately. Subsequent operations will not need to download TSL, improving performance. TSL is downloaded once a day by default and stored in the Configuration object.

```java
configuration.getTSL().refresh();
```

--------------------------------

### Create a timestamped ASiC-S container with digidoc4j-util.jar

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Create a timestamped ASiC-S container using digidoc4j-util.jar. This command adds a file to an existing archive, applies timestamping, and specifies digest algorithms for data and reference data.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar \
  -in "archive.asics" \
  -add "old-signed.bdoc" "application/vnd.etsi.asic-e+zip" \
  -tst -datst SHA256 -refdatst SHA384 -tspsourcearchive http://tsa.demo.sk.ee/tsa

```

--------------------------------

### Create a BDOC Container

Source: https://github.com/open-eid/digidoc4j/blob/master/digidoc4j/src/main/doc/overview.html

Create a BDOC container with at least one document and sign it. Specify the output file, input document, its MIME type, and the PKCS12 token details.

```bash
java -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>"
```

--------------------------------

### Build Container with Custom Configuration in Java

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Create a container using a custom configuration object, such as a test configuration. Passing a pre-configured object to the ContainerBuilder ensures consistent settings for all operations.

```java
// Test configuration. Use only a single configuration object for all the containers so operation times would be faster.
Configuration configuration = Configuration.of(Configuration.Mode.TEST);

// Creating an ASiC-E container with the test configuration
Container container = ContainerBuilder
		.aContainer()
		.withConfiguration(configuration)  // Using our configuration
		.build();
```

--------------------------------

### Configure HTTP and HTTPS Proxies Programmatically

Source: https://github.com/open-eid/digidoc4j/wiki/Questions-&-Answers

Configure HTTP and HTTPS proxy servers programmatically using the Configuration object. Overload specific connection types like TSL, OCSP, and TSP using `set*ProxyFor()` methods.

```java
configuration.setHttpProxyHost("proxy.host");
configuration.setHttpProxyPort(1234);
configuration.setHttpsProxyHost("proxy.host");
configuration.setHttpsProxyPost(1234);
```

--------------------------------

### Create ASiC-E Container with ContainerBuilder

Source: https://context7.com/open-eid/digidoc4j/llms.txt

Use the fluent `ContainerBuilder` API to create a new ASiC-E container, adding files from disk and input streams. Ensure file names do not contain invalid characters.

```java
import org.digidoc4j.*;
import java.io.FileInputStream;
import java.io.InputStream;

Configuration configuration = Configuration.of(Configuration.Mode.TEST);

// Add files from disk and from stream; default container type is ASiC-E
InputStream stream = new FileInputStream("contract2.pdf");
Container container = ContainerBuilder
        .aContainer(Container.DocumentType.ASICE)
        .withConfiguration(configuration)
        .withDataFile("contract1.pdf", "application/pdf")
        .withDataFile(stream, "contract2.pdf", "application/pdf")
        .build();

// File names cannot contain: \ < > : " / | ? *
System.out.println("Data files: " + container.getDataFiles().size()); // 2
```

--------------------------------

### List PKCS#11 Slots with pkcs11-tool

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Use the pkcs11-tool to list available slots and objects on a PKCS#11 token. This is useful for determining the correct slot number.

```shell
pkcs11-tool -L --module /usr/local/lib/opensc-pkcs11.so
```

--------------------------------

### Sign with PKCS#11

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Sign a file using a PKCS#11 token. Requires the driver file, PIN code, and slot number.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>" -sigOutputPath "<signature_file_path>"
```

--------------------------------

### Configure Test LOTL Truststore in digidoc4j.yaml

Source: https://github.com/open-eid/digidoc4j/wiki/Using-test-TSL-lists

Configure the trust-store for the test LOTL signing certificate in `digidoc4j.yaml`. Use `LOTL_TRUSTSTORE_PATH`, `LOTL_TRUSTSTORE_PASSWORD`, and `LOTL_TRUSTSTORE_TYPE` for versions 5.0.0 and later; `TSL_` prefixed parameters are deprecated.

```yaml
# pre-5.0.0 DigiDoc4J (deprecated since 5.0.0)
TSL_KEYSTORE_LOCATION: keystore/test-keystore.jks
TSL_KEYSTORE_PASSWORD: digidoc4j-password
# since DigiDoc4J version 5.0.0
LOTL_TRUSTSTORE_PATH: classpath:truststores/test-lotl-truststore.p12
LOTL_TRUSTSTORE_PASSWORD: digidoc4j-password
LOTL_TRUSTSTORE_TYPE: PKCS12
```

--------------------------------

### Create a New ASiC-E Container with Data Files

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Creates a new ASiC-E container using ContainerBuilder. It demonstrates adding data files from both a file path and an input stream. Ensure file names do not contain forbidden characters like `\ <> : " / | ? *`.

```java
// We can provide configuration. "Configuration.Mode.TEST" should be used for testing.
// Use only a single configuration object for all the containers so operation times would be faster.
Configuration configuration = Configuration.of(Configuration.Mode.TEST);

// Creating an ASiC-E container
Container container = ContainerBuilder
		.aContainer(Container.DocumentType.ASICE)  // Specifying container type. Default is ASICE.
		.withConfiguration(configuration)  // Using our configuration
		.withDataFile("testFiles/legal_contract_1.txt", "text/plain")  // Adding a document from a hard drive
		.withDataFile(inputStream, "legal_contract_2.txt", "text/plain")  // Adding a document from a stream
		.build();
```

--------------------------------

### Wrap an Existing Container File in a Timestamped ASiC-S Container

Source: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

Use this snippet to wrap an existing container from a file into a timestamped ASiC-S container, applying a specific configuration. This method is recommended for preserving byte-wise equivalence.

```java
CompositeContainer nestingContainer = CompositeContainerBuilder
		.fromContainerFile("testFiles/container-name.asice")
		.withConfiguration(configuration)
		.buildTimestamped(timestampBuilder -> {});
```

--------------------------------

### Configure Logback Dependencies for digidoc4j

Source: https://github.com/open-eid/digidoc4j/wiki/Questions-&-Answers

Include these Maven dependencies to enable Logback logging with digidoc4j. Ensure a logback.xml configuration file is present in the classpath.

```xml
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.3</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-core</artifactId>
    <version>1.2.3</version>
</dependency>
```

--------------------------------

### Enable AIA OCSP for Signature Creation (Deprecated)

Source: https://github.com/open-eid/digidoc4j/wiki/Command-line-utility-tool

Prior to version 5.3.0, this command explicitly enabled AIA OCSP preference for signature creation. This option is deprecated and will be removed in future versions. Requires PKCS#11 driver, PIN, and slot number.

```shell
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -aiaocsp -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"
```