Skip to content

Latest commit

 

History

History
1316 lines (1153 loc) · 48.8 KB

migration-guide.adoc

File metadata and controls

1316 lines (1153 loc) · 48.8 KB

1. Migration guide

This chapter covers the most significant changes in DSS code occurred between different versions, requiring review and possible changes from code implementors.

For changes within Diagnostic Data XSD please refer [DiagnosticDataChanges].

For changes within XML Signature Policy please refer [ValidationPolicyChanges].

Table 1. Code changes from version 6.1 to 6.2

Title

v6.1

v6.2

Signature #getFilename

 
import eu.europa.esig.dss.spi.signature.AdvancedSignature;

AdvancedSignature signature = ...
String filename = signature.getSignatureFilename();
...

import eu.europa.esig.dss.diagnostic.SignatureWrapper;

SignatureWrapper signatureWrapper = ...
String filename = signatureWrapper.getSignatureFilename();
 
import eu.europa.esig.dss.spi.signature.AdvancedSignature;

AdvancedSignature signature = ...
String filename = signature.getFilename();
...

import eu.europa.esig.dss.diagnostic.SignatureWrapper;

SignatureWrapper signatureWrapper = ...
String filename = signatureWrapper.getFilename();

PdfBoxUtils#generateScreenshot

 
import eu.europa.esig.dss.pdf.pdfbox.PdfBoxUtils;
import eu.europa.esig.dss.model.DSSDocument;

DSSDocument screenshot = PdfBoxUtils.generateScreenshot(pdfDocument, page);
...

import eu.europa.esig.dss.pdf.pdfbox.PdfBoxUtils;
import eu.europa.esig.dss.model.DSSDocument;

BufferedImage screenshot = PdfBoxUtils.generateBufferedImageScreenshot(pdfDocument, password, page);
 
import eu.europa.esig.dss.pdf.pdfbox.PdfBoxScreenshotBuilder;
import eu.europa.esig.dss.model.DSSDocument;

DSSDocument screenshot = PdfBoxScreenshotBuilder.fromDocument(pdfDocument).generateScreenshot(page);
...

import eu.europa.esig.dss.pdf.pdfbox.PdfBoxScreenshotBuilder;
import eu.europa.esig.dss.model.DSSDocument;

BufferedImage screenshot = PdfBoxScreenshotBuilder.fromDocument(pdfDocument, password).generateBufferedImageScreenshot(page);

PdfBoxUtils#generateSubtractionImage

 
import eu.europa.esig.dss.pdf.pdfbox.PdfBoxUtils;
import eu.europa.esig.dss.model.DSSDocument;

DSSDocument subtractionImage = PdfBoxUtils.generateSubtractionImage(docOne, passwordOne, page, docTwo, passwordTwo, page,
        tempFileResourcesHandlerBuilder.createResourcesHandler());
 
import eu.europa.esig.dss.pdf.pdfbox.PdfBoxUtils;
import eu.europa.esig.dss.pdf.pdfbox.PdfBoxScreenshotBuilder;
import eu.europa.esig.dss.model.DSSDocument;

BufferedImage screenshotOne = PdfBoxScreenshotBuilder.fromDocument(docOne, passwordOne)
        .setDSSResourcesHandlerBuilder(tempFileResourcesHandlerBuilder).generateBufferedImageScreenshot(page);
BufferedImage screenshotTwo = PdfBoxScreenshotBuilder.fromDocument(docTwo, passwordTwo)
        .setDSSResourcesHandlerBuilder(tempFileResourcesHandlerBuilder).generateBufferedImageScreenshot(page);
DSSDocument subtractionImage = PdfBoxUtils.generateSubtractionImage(screenshotOne, screenshotTwo);

Digest encoding for RSA signature

 
import eu.europa.esig.dss.model.Digest;
import eu.europa.esig.dss.spi.DSSUtils;
import eu.europa.esig.dss.token.SignatureTokenConnection;

SignatureTokenConnection token = ...
byte[] digestValue = ...
byte[] encodedDigest = DSSUtils.encodeRSADigest(DigestAlgorithm.SHA256, digestValue));
Digest digest = new Digest(DigestAlgorithm.SHA256, encodedDigest);
SignatureValue signatureValue = token.signDigest(digest, SignatureAlgorithm.RSA_SHA256, getPrivateKeyEntry());
 
import eu.europa.esig.dss.model.Digest;
import eu.europa.esig.dss.token.SignatureTokenConnection;

SignatureTokenConnection token = ...
byte[] digestValue = ...
Digest digest = new Digest(DigestAlgorithm.SHA256, digestValue);
SignatureValue signatureValue = token.signDigest(digest, SignatureAlgorithm.RSA_SHA256, getPrivateKeyEntry());

XML Trusted List signing

 
import eu.europa.esig.dss.xades.TrustedListSignatureParametersBuilder;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

TrustedListSignatureParametersBuilder builder = new TrustedListSignatureParametersBuilder(signingCertificate, xmlTrustedList);
XAdESSignatureParameters parameters = builder.build();
...
 
import eu.europa.esig.dss.xades.tsl.TrustedListV5SignatureParametersBuilder;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

TrustedListV5SignatureParametersBuilder builder = new TrustedListV5SignatureParametersBuilder(signingCertificate, xmlTrustedList);
XAdESSignatureParameters parameters = builder.build();
...

Additional signature validation data is included within AnyValidationData element (XAdES, JAdES) after LTA-level

 
import eu.europa.esig.dss.enumerations.SignatureLevel;
import eu.europa.esig.dss.model.DSSDocument;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;
import eu.europa.esig.dss.xades.signature.XAdESService;

XAdESService service = new XAdESService(certificateVerifier);
XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParameters.setSignatureLevel(SignatureLevel.XAdES_BASELINE_LTA);
...
DSSDocument extendedDocument = service.extendDocument(signedDocument, signatureParameters);

To get back to previous behavior (no AnyValidationData is used):

import eu.europa.esig.dss.enumerations.SignatureLevel;
import eu.europa.esig.dss.enumerations.ValidationDataEncapsulationStrategy;
import eu.europa.esig.dss.model.DSSDocument;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;
import eu.europa.esig.dss.xades.signature.XAdESService;

XAdESService service = new XAdESService(certificateVerifier);
XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParameters.setSignatureLevel(SignatureLevel.XAdES_BASELINE_LTA);
signatureParameters.setValidationDataEncapsulationStrategy(ValidationDataEncapsulationStrategy.CERTIFICATE_REVOCATION_VALUES_AND_TIMESTAMP_VALIDATION_DATA);
...
DSSDocument extendedDocument = service.extendDocument(signedDocument, signatureParameters);

Alert behavior in SignatureValidationContext checks

Only when ValidationContext is used directly.

import eu.europa.esig.dss.alert.ExceptionOnStatusAlert;
import eu.europa.esig.dss.spi.validation.CertificateVerifier;
import eu.europa.esig.dss.spi.validation.CommonCertificateVerifier;
import eu.europa.esig.dss.spi.validation.SignatureValidationContext;
import eu.europa.esig.dss.spi.validation.ValidationContext;

CertificateVerifier certificateVerifier = new CommonCertificateVerifier();
certificateVerifier.setAlertOnExpiredCertificate(new ExceptionOnStatusAlert());
...
ValidationContext validationContext = new SignatureValidationContext();
validationContext.initialize(certificateVerifier);
...
validationContext.validate();

boolean result = validationContext.checkAllSignaturesNotExpired(); // AlertException is thrown in case of FALSE
 
import eu.europa.esig.dss.alert.ExceptionOnStatusAlert;
import eu.europa.esig.dss.spi.validation.CertificateVerifier;
import eu.europa.esig.dss.spi.validation.CommonCertificateVerifier;
import eu.europa.esig.dss.spi.validation.SignatureValidationContext;
import eu.europa.esig.dss.spi.validation.ValidationContext;

CertificateVerifier certificateVerifier = new CommonCertificateVerifier();
certificateVerifier.setAlertOnExpiredCertificate(new ExceptionOnStatusAlert());
...
ValidationContext validationContext = new SignatureValidationContext();
validationContext.initialize(certificateVerifier);
...
validationContext.validate();

boolean result = validationContext.checkAllSignaturesNotExpired(); // no alert execution, only boolean is returned

ValidationAlerter validationAlerter = new SignatureValidationAlerter(validationContext);
validationAlerter.assertAllSignaturesNotExpired(); // AlertException is thrown in case of check failure
Table 2. Code changes from version 6.0 to 6.1

Title

v6.0

v6.1

Include dss-validation module to perform validation
pom.xml
<dependencies>
    ...
    <dependency>
        <groupId>eu.europa.ec.joinup.sd-dss</groupId>
        <artifactId>dss-xades</artifactId>
    </dependency>
    ...
</dependencies>

dss-validation module is required to perform validation for every signature format

pom.xml
<dependencies>
    ...
    <dependency>
        <groupId>eu.europa.ec.joinup.sd-dss</groupId>
        <artifactId>dss-xades</artifactId>
    </dependency>
    <dependency>
        <groupId>eu.europa.ec.joinup.sd-dss</groupId>
        <artifactId>dss-validation</artifactId>
    </dependency>
    ...
</dependencies>

CertificateVerifier package

 
import eu.europa.esig.dss.validation.CommonCertificateVerifier;
import eu.europa.esig.dss.validation.CertificateVerifier;
...
CertificateVerifier certificateVerifier = new CommonCertificateVerifier();
 
import eu.europa.esig.dss.spi.validation.CommonCertificateVerifier;
import eu.europa.esig.dss.spi.validation.CertificateVerifier;
...
CertificateVerifier certificateVerifier = new CommonCertificateVerifier();

UserFriendlyIdentifierProvider package

 
import eu.europa.esig.dss.validation.UserFriendlyIdentifierProvider;
 
import eu.europa.esig.dss.validation.identifier.UserFriendlyIdentifierProvider;

AdvancedSignature package

 
import eu.europa.esig.dss.validation.AdvancedSignature;
 
import eu.europa.esig.dss.spi.signature.AdvancedSignature;

TLValidationJobSummary package

 
import eu.europa.esig.dss.spi.tsl.TLValidationJobSummary;
 
import eu.europa.esig.dss.model.tsl.TLValidationJobSummary;

ValidationLevel package

 
import eu.europa.esig.dss.validation.executor.ValidationLevel;
 
import eu.europa.esig.dss.enumerations.ValidationLevel;

CMS attribute extraction

 
import eu.europa.esig.dss.spi.DSSASN1Utils;
...
ASN1Encodable asn1Encodable = DSSASN1Utils.getAsn1Encodable(attributeTable, oid);
 
import eu.europa.esig.dss.spi.DSSASN1Utils;
...
Attribute[] attributes = DSSASN1Utils.getAsn1Attributes(attributeTable, oid);
ASN1Encodable asn1Encodable = attributes[0].getAttributeValues()[0]; // return value of the first attribute

PDF strict numeric object comparison

Strict comparison enforced by default

 
IPdfObjFactory pdfObjFactory = new ServiceLoaderPdfObjFactory();

DefaultPdfObjectModificationsFinder pdfObjectModificationsFinder = new DefaultPdfObjectModificationsFinder();
pdfObjectModificationsFinder.setLaxNumericComparison(false); // by default is True
pdfObjFactory.setPdfObjectModificationsFinder(pdfObjectModificationsFinder);

PDFDocumentValidator validator = (PDFDocumentValidator) super.getValidator(signedDocument);
validator.setPdfObjFactory(pdfObjFactory);

EvidenceRecord package

 
import eu.europa.esig.dss.validation.evidencerecord.EvidenceRecord;
 
import eu.europa.esig.dss.spi.x509.evidencerecord.EvidenceRecord;

Signing with expired/not yet valid certificate

 
signatureParameters.setSignWithExpiredCertificate(true);
signatureParameters.setSignWithNotYetValidCertificate(true);
 
certificateVerifier.setAlertOnExpiredCertificate(new SilentOnStatusAlert());
certificateVerifier.setAlertOnNotYetValidCertificate(new SilentOnStatusAlert());

Alerting on expired signature augmentation

 
certificateVerifier.setAlertOnExpiredSignature(new ExceptionOnStatusAlert());
 
certificateVerifier.setAlertOnExpiredCertificate(new ExceptionOnStatusAlert());

CommonTrustedCertificateSource#getTrustServices

 
CommonTrustedCertificateSource trustedCertificateSource = ...
List<TrustProperties> trustServices = trustedCertificateSource.getTrustServices(certificate);
 
TrustedListsCertificateSource trustedListCertificateSource = ...
List<TrustProperties> trustServices = trustedListCertificateSource.getTrustServices(certificate);

CacheCleaner#setDataLoader

 
DSSFileLoader dataLoader = new FileCacheDataLoader();
...
CacheCleaner cacheCleaner = ...
cacheCleaner.setDataLoader(dataLoader);
 
DSSCacheFileLoader dataLoader = new FileCacheDataLoader();
...
CacheCleaner cacheCleaner = ...
cacheCleaner.setDataLoader(dataLoader);

Revocation update on validation

No revocation data update forced for time-stamp’s certificates before its lowest POE

To get back to previous behavior:

SignedDocumentValidator validator = ...

CertificateVerifier certificateVerifier = new CommonCertificateVerifier();
...
RevocationDataVerifier revocationDataVerifier = RevocationDataVerifier.createDefaultRevocationDataVerifier();
revocationDataVerifier.setTimestampMaximumRevocationFreshness(null); // disable tst revocation data update
certificateVerifier.setRevocationDataVerifier(revocationDataVerifier);

validator.setCertificateVerifier(certificateVerifier);

DSSDocument#getDigest

 
DSSDocument document = ...
String base64EncodedDigest = document.getDigest(DigestAlgorithm.SHA256);
 
DSSDocument document = ...
byte[] digest = document.getDigestValue(DigestAlgorithm.SHA256);
String base64EncodedDigest = Utils.toBase64(digest);

DSSASN1Utils CMS methods

 
import eu.europa.esig.dss.spi.DSSASN1Utils;

List<ASN1ObjectIdentifier> oids = DSSASN1Utils.getTimestampOids();
boolean result = DSSASN1Utils.isArchiveTimeStampToken(attribute);
...
 
import eu.europa.esig.dss.cades.CMSUtils;

List<ASN1ObjectIdentifier> oids = CMSUtils.getTimestampOids();
boolean result = CMSUtils.isArchiveTimeStampToken(attribute);
...

MaskGenerationFunction deprecation

 
import eu.europa.esig.dss.enumerations.EncryptionAlgorithm;
import eu.europa.esig.dss.enumerations.MaskGenerationFunction;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParmeters.setEncryptionAlgorithm(EncryptionAlgorithm.RSA);
signatureParmeters.setMaskGenerationFunction(MaskGenerationFunction.MGF1);
...

Use EncryptionAlgorithm.RSASSA_PSS instead to distinguish a use of mask generation function.

import eu.europa.esig.dss.enumerations.EncryptionAlgorithm;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParmeters.setEncryptionAlgorithm(EncryptionAlgorithm.RSASSA_PSS);
...

SHA512 as default digest algorithm

SHA256 is default.

import eu.europa.esig.dss.enumerations.DigestAlgorithm;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParmeters.setDigestAlgorithm(DigestAlgorithm.SHA512);
...

SHA512 is default. To get back to SHA256 please use:

import eu.europa.esig.dss.enumerations.DigestAlgorithm;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParmeters.setDigestAlgorithm(DigestAlgorithm.SHA256);
...

RSASSA_PSS as default encryption algorithm

 
import eu.europa.esig.dss.enumerations.EncryptionAlgorithm;
import eu.europa.esig.dss.enumerations.MaskGenerationFunction;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParmeters.setEncryptionAlgorithm(EncryptionAlgorithm.RSA);
signatureParmeters.setMaskGenerationFunction(MaskGenerationFunction.MGF1);
...

DSS will choose encryption algorithm based on the algorithm name in the signing-certificate key (i.e. RSA, RSASSA_PSS or other). When signing without certificate or in order to enforce target encryption algorithm, provide encryption algorithm explicitly.

import eu.europa.esig.dss.enumerations.DigestAlgorithm;
import eu.europa.esig.dss.xades.XAdESSignatureParameters;

XAdESSignatureParameters signatureParameters = new XAdESSignatureParameters();
signatureParmeters.setSigningCertificate(signingCertificate);
...
or
...
signatureParmeters.setEncryptionAlgorithm(EncryptionAlgorithm.RSA);
...

JAdES claimed signing time header

Signature created with sigT (claimed signing time) header

Signature created with iat by default (recommended). To return to the old behavior*, the code below can be used:

import eu.europa.esig.dss.jades.JAdESSignatureParameters;

JAdESSignatureParameters signatureParameters = new JAdESSignatureParameters();
...
signatureParameters.setJadesSigningTimeType(JAdESSigningTimeType.SIG_T);

* sigT is deprecated. The header shall not be used since 2025-05-15T00:00:00Z.

XMLDSig definitions

 
import eu.europa.esig.xmldsig.definition.XMLDSigAttribute;
import eu.europa.esig.xmldsig.definition.XMLDSigElement;
import eu.europa.esig.xmldsig.definition.XMLDSigPath;
...
 
import eu.europa.esig.dss.xml.common.definition.xmldsig.XMLDSigAttribute;
import eu.europa.esig.dss.xml.common.definition.xmldsig.XMLDSigElement;
import eu.europa.esig.dss.xml.common.definition.xmldsig.XMLDSigPath;
...

XAdES definitions

 
import eu.europa.esig.xades.definition.xades132.XAdES132Attribute;
import eu.europa.esig.xades.definition.xades132.XAdES132Element;
import eu.europa.esig.xades.definition.xades132.XAdES132Path;
...
 
import eu.europa.esig.dss.xades.definition.xades132.XAdES132Attribute;
import eu.europa.esig.dss.xades.definition.xades132.XAdES132Element;
import eu.europa.esig.dss.xades.definition.xades132.XAdES132Path;
...

CertificateVerifier#setExtractPOEFromUntrustedChains deprecated

 
import eu.europa.esig.dss.spi.validation.CertificateVerifier;

CertificateVerifier certificateVerifier = new CommonCertificateVerifier();
certificateVerifier.setExtractPOEFromUntrustedChains(true);
 
import eu.europa.esig.dss.spi.validation.TimestampTokenVerifier;
import eu.europa.esig.dss.spi.validation.CertificateVerifier;

CertificateVerifier certificateVerifier = new CommonCertificateVerifier();

TimestampTokenVerifier timestampTokenVerifier = TimestampTokenVerifier.createDefaultTimestampTokenVerifier();
timestampTokenVerifier.setAcceptUntrustedCertificateChains(true);
certificateVerifier.setTimestampTokenVerifier(timestampTokenVerifier);

Skip ValidationContext execution

 
import eu.europa.esig.dss.validation.DocumentValidator;

DocumentValidator documentValidator = ...
documentValidator.setSkipValidationContextExecution(true);
 
import eu.europa.esig.dss.validation.DocumentValidator;
import eu.europa.esig.dss.validation.executor.context.SkipValidationContextExecutor;

DocumentValidator documentValidator = ...
documentValidator.setValidationContextExecutor(SkipValidationContextExecutor.INSTANCE);

ManifestEntry#getName has been deprecated

 
import eu.europa.esig.dss.validation.ManifestEntry;

ManifestEntry manifestEntry = ...
String name = manifestEntry.getName();
 
import eu.europa.esig.dss.model.ManifestEntry;

ManifestEntry manifestEntry = ...
String uri = manifestEntry.getUri();

or use #getDocumentName for identified entries

String documentName = manifestEntry.getDocumentName();
Table 3. Code changes from version 5.13 to 6.0

Title

v5.13

v6.0

Jakarta namespace migration

 
import javax.xml.bind.JAXBElement;
...
 
import jakarta.xml.bind.JAXBElement;
...

Javax version change

 
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>2.*</version>
</dependency>
 
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>3.*</version>
</dependency>
Table 4. Code changes from version 5.12 to 5.13

Title

v5.12

v5.13

KeyStoreCertificateSource password

 
KeyStoreCertificateSource keyStoreCertificateSource = new KeyStoreCertificateSource(file, "PKCS12", "password");
 
KeyStoreCertificateSource keyStoreCertificateSource = new KeyStoreCertificateSource(file, "PKCS12", new char[] { 'p', 'a', 's', 's', 'w', 'o', 'r', 'd' });

Trust Service naming

 
1) List<TrustedServiceWrapper> trustServices = certificateWrapper.getTrustedServices();
2) public abstract class AbstractTrustedServiceFilter implements TrustedServiceFilter {}
...
etc
 
1)
List<TrustServiceWrapper> trustServices = certificateWrapper.getTrustServices();
2)
public abstract class AbstractTrustServiceFilter implements TrustServiceFilter {}
...
etc

Trust Service qualifiers

 
TrustedServiceWrapper trustService = ...
List<String> qualifierUris = trustService.getCapturedQualifiers();
 
TrustServiceWrapper trustService = ...
List<String> qualifierUris = trustService.getCapturedQualifierUris();

OCSP response without nonce (keep failing behavior)

 
OnlineOCSPSource ocspSource = new OnlineOCSPSource();
ocspSource.setNonceSource(new SecureRandomNonceSource());
Exception exception = assertThrows(DSSExternalResourceException.class, () -> ocspSource.getRevocationToken(certificateToken, caToken)); // if OCSP response does not include nonce
 
OnlineOCSPSource ocspSource = new OnlineOCSPSource();
ocspSource.setNonceSource(new SecureRandomNonceSource());
ocspSource.setAlertOnNonexistentNonce(new DSSExternalResourceExceptionAlert());
Exception exception = assertThrows(DSSExternalResourceException.class, () -> ocspSource.getRevocationToken(certificateToken, rootToken)); // if OCSP response does not include nonce

JWS content media type ("cty" header)

 
String mimeType = signature.getContentType();
 
String mimeType = signature.getMimeType();

JWS media type ("typ" header)

 
String jwsType = signature.getMimeType();
 
String jwsType = signature.getSignatureType();

DetailedReport. Timestamp validation

 
Indication indication = detailedReport.getTimestampValidationIndication(tspId);
SubIndication subIndication = detailedReport.getTimestampValidationSubIndication(tspId);
 
Indication indication = detailedReport.getBasicTimestampValidationIndication(tspId);
SubIndication subIndication = detailedReport.getBasicTimestampValidationSubIndication(tspId);

ZipUtils handler

 
SecureContainerHandler secureContainerHandler = new SecureContainerHandler();
secureContainerHandler.setMaxAllowedFilesAmount(1000);
secureContainerHandler.setMaxMalformedFiles(100);
secureContainerHandler.setMaxCompressionRatio(100);
secureContainerHandler.setThreshold(1000000);
secureContainerHandler.setExtractComments(true);
ZipUtils.getInstance().setZipContainerHandler(secureContainerHandler);
 
SecureContainerHandlerBuilder secureContainerHandlerBuilder = new SecureContainerHandlerBuilder();
secureContainerHandlerBuilder.setMaxAllowedFilesAmount(1000);
secureContainerHandlerBuilder.setMaxMalformedFiles(100);
secureContainerHandlerBuilder.setMaxCompressionRatio(100);
secureContainerHandlerBuilder.setThreshold(1000000);
secureContainerHandlerBuilder.setExtractComments(true);
ZipUtils.getInstance().setZipContainerHandlerBuilder(secureContainerHandlerBuilder);

Timestamp processing classes moved to dss-spi module

 
import eu.europa.esig.dss.validation.timestamp.TimestampInclude;
import eu.europa.esig.dss.validation.timestamp.TimestampToken;
import eu.europa.esig.dss.validation.timestamp.TimestampedReference;
import eu.europa.esig.dss.validation.timestamp.TimestampCertificateSource;
import eu.europa.esig.dss.spi.x509.timestamp.TSPSource;
...
 
import eu.europa.esig.dss.spi.x509.tsp.TimestampInclude;
import eu.europa.esig.dss.spi.x509.tsp.TimestampToken;
import eu.europa.esig.dss.spi.x509.tsp.TimestampedReference;
import eu.europa.esig.dss.spi.x509.tsp.TimestampCertificateSource;
import eu.europa.esig.dss.spi.x509.tsp.TSPSource;
...

Common certificate/revocation sources moved to dss-spi module

 
import eu.europa.esig.dss.validation.SignatureCertificateSource;
import eu.europa.esig.dss.validation.ListRevocationSource;
 
import eu.europa.esig.dss.spi.SignatureCertificateSource;
import eu.europa.esig.dss.spi.x509.revocation.ListRevocationSource;

Validation support classes moved to dss-model module

 
import eu.europa.esig.dss.validation.ManifestEntry;
import eu.europa.esig.dss.validation.ManifestFile;
import eu.europa.esig.dss.validation.ReferenceValidation;
import eu.europa.esig.dss.validation.TokenIdentifierProvider;
import eu.europa.esig.dss.validation.scope.SignatureScope;
...
 
import eu.europa.esig.dss.model.ManifestEntry;
import eu.europa.esig.dss.model.ManifestFile;
import eu.europa.esig.dss.model.ReferenceValidation;
import eu.europa.esig.dss.model.identifier.TokenIdentifierProvider;
import eu.europa.esig.dss.model.scope.SignatureScope;
...

XmlDefinerUtils and related classes moved to dss-xml-common module

 
import eu.europa.esig.dss.jaxb.common.XmlDefinerUtils;
import eu.europa.esig.dss.jaxb.common.DocumentBuilderFactoryBuilder;
import eu.europa.esig.dss.jaxb.common.TransformerFactoryBuilder;
import eu.europa.esig.dss.jaxb.common.SchemaFactoryBuilder;
import eu.europa.esig.dss.jaxb.common.ValidatorConfigurator;
 
import eu.europa.esig.dss.xml.common.XmlDefinerUtils;
import eu.europa.esig.dss.xml.common.DocumentBuilderFactoryBuilder;
import eu.europa.esig.dss.xml.common.TransformerFactoryBuilder;
import eu.europa.esig.dss.xml.common.SchemaFactoryBuilder;
import eu.europa.esig.dss.xml.common.ValidatorConfigurator;

XML definitions moved to dss-xml-common module

 
import eu.europa.esig.dss.definition.DSSAttribute;
import eu.europa.esig.dss.definition.DSSElement;
import eu.europa.esig.dss.definition.DSSNamespace;
...
 
import eu.europa.esig.dss.xml.common.definition.DSSAttribute;
import eu.europa.esig.dss.xml.common.definition.DSSElement;
import eu.europa.esig.dss.xml.common.definition.DSSNamespace;
...

DSSErrorHandlerAlert package

 
import eu.europa.esig.dss.jaxb.common.DSSErrorHandlerAlert;
 
import eu.europa.esig.dss.xml.common.alert.DSSErrorHandlerAlert;

DomUtils moved to dss-xml-utils module

 
import eu.europa.esig.dss.DomUtils;
 
import eu.europa.esig.dss.xml.utils.DomUtils;

Canonicalization

 
import eu.europa.esig.dss.xades.DSSXMLUtils;

byte[] canonicalizedBytes = DSSXMLUtils.canonicalize(canonicalizationMethod, bytesToCanonicalize);
 
import eu.europa.esig.dss.xml.utils.XMLCanonicalizer;

byte[] canonicalizedBytes = XMLCanonicalizer.createInstance(canonicalizationMethod).canonicalize(bytesToCanonicalize);

PDF visual signature rotation

 
SignatureImageParameters imageParameters = new SignatureImageParameters();
imageParameters.setRotation(VisualSignatureRotation.AUTOMATIC);
 
SignatureImageParameters imageParameters = new SignatureImageParameters();
SignatureFieldParameters fieldParameters = new SignatureFieldParameters();
fieldParameters.setRotation(VisualSignatureRotation.AUTOMATIC);
imageParameters.setFieldParameters(fieldParameters);

Signature scopes

 
AdvancedSignature advancedSignature = ...
advancedSignature.findSignatureScope(signatureScopeFinder);
List<SignatureScope> signatureScopes = advancedSignature.getSignatureScopes();
 
AdvancedSignature advancedSignature = ...
List<SignatureScope> signatureScopes = advancedSignature.getSignatureScopes();

CMSSignedDataBuilder refactoring

 
import eu.europa.esig.dss.cades.CMSUtils;
import eu.europa.esig.dss.cades.signature.CMSSignedDataBuilder;
import org.bouncycastle.cms.SignerInfoGeneratorBuilder;

CMSSignedDataBuilder cmsSignedDataBuilder = new CMSSignedDataBuilder(certificateVerifier);
SignerInfoGeneratorBuilder signerInfoGeneratorBuilder = cmsSignedDataBuilder.getSignerInfoGeneratorBuilder(dcp, parameters, true, contentToSign);
CMSSignedDataGenerator cmsSignedDataGenerator = cmsSignedDataBuilder.createCMSSignedDataGenerator(parameters, customContentSigner, signerInfoGeneratorBuilder, originalCmsSignedData);
CMSTypedData content = CMSUtils.getContentToBeSigned(contentToSign);
CMSSignedData cmsSignedData = CMSUtils.generateCMSSignedData(cmsSignedDataGenerator, content, encapsulate);
 
import eu.europa.esig.dss.spi.x509.CMSSignedDataBuilder;
import org.bouncycastle.cms.SignerInfoGenerator;

SignerInfoGenerator signerInfoGenerator = new CMSSignerInfoGeneratorBuilder().build(contentToSign, parameters, customContentSigner);
CMSSignedData cmsSignedData = getCMSSignedDataBuilder(parameters).setOriginalCMSSignedData(originalCmsSignedData).createCMSSignedData(signerInfoGenerator, contentToSign);

OfficialJournalSchemeInformationURI URI extraction

 
import eu.europa.esig.dss.tsl.function.OfficialJournalSchemeInformationURI;

OfficialJournalSchemeInformationURI officialJournalSchemeInformationURI = ...
String officialJournalURL = officialJournalSchemeInformationURI.getOfficialJournalURL();
 
import eu.europa.esig.dss.tsl.function.OfficialJournalSchemeInformationURI;

OfficialJournalSchemeInformationURI officialJournalSchemeInformationURI = ...
String officialJournalURL = officialJournalSchemeInformationURI.getUri();
Table 5. Code changes from version 5.11 to 5.12

Title

v5.11

v5.12

PDFSignatureService #digest

 
PDFSignatureService pdfSignatureService = ...
byte[] digest = pdfSignatureService.digest(toSignDocument, parameters);
 
PDFSignatureService pdfSignatureService = ...
MessageDigest messageDigest = pdfSignatureService.messageDigest(toSignDocument, parameters);
byte[] digest = messageDigest.getValue();

PDFSignatureService: permission dictionary alert

 
PDFSignatureService pdfSignatureService = ...
pdfSignatureService.setAlertOnForbiddenSignatureCreation(new ExceptionOnStatusAlert);
 
PAdESService padesService = ...

IPdfObjFactory pdfObjectFactory = new ServiceLoaderPdfObjFactory();
PdfPermissionsChecker pdfPermissionsChecker = new PdfPermissionsChecker();
pdfPermissionsChecker.setAlertOnForbiddenSignatureCreation(new ProtectedDocumentExceptionOnStatusAlert());
pdfObjectFactory.setPdfPermissionsChecker(pdfPermissionsChecker);

service.setPdfObjFactory(pdfObjectFactory);

PDFSignatureService: signature field position alert

 
PDFSignatureService pdfSignatureService = ...
pdfSignatureService.setAlertOnSignatureFieldOutsidePageDimensions(new ExceptionOnStatusAlert);
pdfSignatureService.setAlertOnSignatureFieldOverlap(new ExceptionOnStatusAlert);
 
PAdESService padesService = ...

IPdfObjFactory pdfObjectFactory = new ServiceLoaderPdfObjFactory();
PdfSignatureFieldPositionChecker pdfSignatureFieldPositionChecker = new PdfSignatureFieldPositionChecker();
pdfSignatureFieldPositionChecker.setAlertOnSignatureFieldOutsidePageDimensions(new ExceptionOnStatusAlert());
pdfSignatureFieldPositionChecker.setAlertOnSignatureFieldOverlap(new ExceptionOnStatusAlert());
pdfObjectFactory.setPdfSignatureFieldPositionChecker(pdfSignatureFieldPositionChecker);

service.setPdfObjFactory(pdfObjectFactory);

PAdESSignatureParameters #setIncludeVRIDictionary

VRI dictionary is created by default

 
PAdESSignatureParameters signatureParameters = new PAdESSignatureParameters();
...
signatureParameters.setIncludeVRIDictionary(true);

PdfDocumentReader #checkDocumentPermissions

 
PdfDocumentReader reader = ...
reader.checkDocumentPermissions();
 
PdfDocumentReader reader = ...
SignatureFieldParameters signatureFieldParameters = ...
PdfPermissionsChecker pdfPermissionsChecker = new PdfPermissionsChecker();
pdfPermissionsChecker.checkDocumentPermissions(reader, signatureFieldParameters);

MimeType namespace

 
import eu.europa.esig.dss.model.MimeType;
 
import eu.europa.esig.dss.enumerations.MimeType;

MimeType enumerations

 
import eu.europa.esig.dss.model.MimeType;

MimeType.PDF;
 
import eu.europa.esig.dss.enumerations.MimeTypeEnum;

MimeTypeEnum.PDF;

Password protection variable (replaced to char[] across modules)

 
UserCredentials userCredentials = new UserCredentials("username", "password");
 
UserCredentials userCredentials = new UserCredentials("username", new char[] { 'p', 'a', 's', 's', 'w', 'o', 'r', 'd' });

NativeHTTPDataLoader configuration

 
NativeHTTPDataLoader dataLoader = new NativeHTTPDataLoader();
dataLoader.setTimeout(1000);
 
NativeHTTPDataLoader dataLoader = new NativeHTTPDataLoader();
dataLoader.setConnectTimeout(1000);
dataLoader.setReadTimeout(1000);

CommonsDataLoader set accepted HTTP status

 
commonsDataLoader.setAcceptedHttpStatus(acceptedHttpStatus);
 
CommonsHttpClientResponseHandler httpClientResponseHandler = new CommonsHttpClientResponseHandler();
httpClientResponseHandler.setAcceptedHttpStatuses(acceptedHttpStatus);
commonsDataLoader.setHttpClientResponseHandler(httpClientResponseHandler);

CommonsDataLoader set accepted HTTP status

 
commonsDataLoader.setAcceptedHttpStatus(acceptedHttpStatus);
 
CommonsHttpClientResponseHandler httpClientResponseHandler = new CommonsHttpClientResponseHandler();
httpClientResponseHandler.setAcceptedHttpStatuses(acceptedHttpStatus);
commonsDataLoader.setHttpClientResponseHandler(httpClientResponseHandler);

CommonsDataLoader password implementation

 
commonsDataLoader.setSslKeystorePassword(keyStorePassword);
commonsDataLoader.setSslTruststorePassword(trustStorePassword);
commonsDataLoader.addAuthentication(host, port, scheme, login, password);
 
commonsDataLoader.setSslKeystorePassword(keyStorePassword.toCharArray());
commonsDataLoader.setSslTruststorePassword(trustStorePassword.toCharArray());
commonsDataLoader.addAuthentication(host, port, scheme, login, password.toCharArray());

CommonsDataLoader #get

 
byte[] content = commonsDataLoader.get(url, false);
 
byte[] content = commonsDataLoader.get(url);

TimestampToken #isSignatureValid

 
TimestampToken timestamp = ...
timestamp.isSignatureValid();
 
TimestampToken timestamp = ...
timestamp.isValid();

Certificate extensions extraction

 
CertificateToken certificateToken = ...
List<String> ocspUrls = DSSASN1Utils.getOCSPAccessLocations(certificateToken);
List<String> crlUrls = DSSASN1Utils.getCrlUrls(certificateToken);
 
CertificateToken certificateToken = ...
List<String> ocspUrls = CertificateExtensionsUtils.getOCSPAccessUrls(certificateToken);
List<String> crlUrls = CertificateExtensionsUtils.getCRLAccessUrls(certificateToken);
Table 6. Code changes from version 5.10/5.10.1 to 5.11

Title

v5.10

v5.11

ASiC container: set signature name

 
ASiCWithXAdESSignatureParameters signatureParameters = new ASiCWithXAdESSignatureParameters();
...
signatureParameters.aSiC().setSignatureFileName("signaturesAAA.xml");
 
SimpleASiCWithCAdESFilenameFactory asicFilenameFactory = new SimpleASiCWithCAdESFilenameFactory();
asicFilenameFactory.setSignatureFilename("signaturesAAA.xml");
ASiCWithXAdESService/ASiCWithCAdESService.setAsicFilenameFactory(asicFilenameFactory);

See [asicFilenameFactory] for more details.

Font subset configuration in PDF

 
NativePdfBoxVisibleSignatureDrawer nativePdfBoxDrawer = new NativePdfBoxVisibleSignatureDrawer();
nativePdfBoxDrawer.setEmbedFontSubset(true);
...
 
DSSFileFont font = // create font
font.setEmbedFontSubset(true);
...
SignatureImageTextParameters textParameters = new SignatureImageTextParameters();
textParameters.setFont(font);

RevocationDataLoadingStrategy

 
CertificateVerifier cv = new CommonCertificateVerifier();
cv.setRevocationDataLoadingStrategy(new OCSPFirstRevocationDataLoadingStrategy());
...
 
CertificateVerifier cv = new CommonCertificateVerifier();
cv.setRevocationDataLoadingStrategyFactory(new OCSPFirstRevocationDataLoadingStrategyFactory());
...

Accepted DigestAlgorithms for OnlineOCSPSource

NOTE: list changed from excluding to including

 
OnlineOCSPSource ocspSource = new OnlineOCSPSource();
ocspSource.setDigestAlgorithmsForExclusion(Arrays.asList(DigestAlgorithm.SHA1));

CertificateVerifier cv = new CommonCertificateVerifier();
cv.setOcspSource(ocspSource);
 
RevocationDataVerifier revocationDataVerifier = RevocationDataVerifier.createDefaultRevocationDataVerifier();

List<DigestAlgorithm> digestAlgorithmList = Arrays.asList(DigestAlgorithm.values());
digestAlgorithmList.remove(DigestAlgorithm.SHA1);

revocationDataVerifier.setAcceptableDigestAlgorithms(digestAlgorithmList);

CertificateVerifier cv = new CommonCertificateVerifier();
cv.setRevocationDataVerifier(revocationDataVerifier);

Disable visual comparison

 
AbstractPDFSignatureService pdfSignatureService = ...
pdfSignatureService.setMaximalPagesAmountForVisualComparison(0);
...
class MockPdfObjFactory extends PdfBoxNativeObjectFactory {
@Override
public PDFSignatureService newPAdESSignatureService() {
return pdfSignatureService;
}
...
}
PDFDocumentValidator validator = ...
validator.setPdfObjFactory(new MockPdfObjFactory());
 
IPdfObjFactory pdfObjFactory = new ServiceLoaderPdfObjFactory();
DefaultPdfDifferencesFinder pdfDifferencesFinder = new DefaultPdfDifferencesFinder();
pdfDifferencesFinder.setMaximalPagesAmountForVisualComparison(0);
pdfObjFactory.setPdfDifferencesFinder(pdfDifferencesFinder);
PDFDocumentValidator validator = ...
validator.setPdfObjFactory(pdfObjFactory);
Table 7. Code changes from version 5.9 to 5.10

Title

v5.9

v5.10

ASiC container extraction

 
ASiCExtractResult extractedResult = asicContainerExtractor.extract();
 
ASiCContent extractedResult = asicContainerExtractor.extract();

HttpClient5 transition

 
import org.apache.http.*
 
import org.apache.hc.client5.http.*
import org.apache.hc.core5.http.*

FileCacheDataLoader

 
fileCacheDataLoader.setCacheExpirationTime(Long.MAX_VALUE);
 
fileCacheDataLoader.setCacheExpirationTime(-1); // negative value means cache never expires

DiagnosticData: PDF signature field name

 
List<String> fieldNames = xmlPDFRevision.getSignatureFieldName();
String name = fieldNames.get(i);
 
List<PDFSignatureField> signatureFields = xmlPDFRevision.getPDFSignatureField();
String name = signatureFields.get(i).getName();
Table 8. Code changes from version 5.8 to 5.9

Title

v5.8

v5.9

AIA data loader

 
certificateVerifier.setDataLoader(dataLoader);
 
AIASource aiaSource = new DefaultAIASource(dataLoader);
certificateVerifier.setAIASource(aiaSource);

Signature Policy Provider

 
certificateVerifier.setDataLoader(dataLoader);
 
SignaturePolicyProvider signaturePolicyProvider = new SignaturePolicyProvider();
signaturePolicyProvider.setDataLoader(dataLoader);
documentValidator.setSignaturePolicyProvider(signaturePolicyProvider);

JDBC dataSource

 
JdbcRevocationSource.setDataSource(dataSource);
 
JdbcCacheConnector jdbcCacheConnector = new JdbcCacheConnector(dataSource);
jdbcRevocationSource.setJdbcCacheConnector(jdbcCacheConnector);

DiagnosticData: Signature policy

 
String notice = xmlPolicy.getNotice();
Boolean zeroHash = xmlPolicy.isZeroHash();
XmlDigestAlgoAndValue digestAlgoAndValue = xmlPolicy.getDigestAlgoAndValue();
Boolean status = xmlPolicy.isStatus();
Boolean digestAlgorithmsEqual = xmlPolicy.isDigestAlgorithmsEqual();
 
XmlUserNotice notice = xmlPolicy.getUserNotice();
Boolean zeroHash = xmlPolicy.getDigestAlgoAndValue().isZeroHash();
XmlPolicyDigestAlgoAndValue digestAlgoAndValue = xmlPolicy.getDigestAlgoAndValue();
Boolean status = xmlPolicy.getDigestAlgoAndValue().isMatch();
Boolean digestAlgorithmsEqual = xmlPolicy.getDigestAlgoAndValue().isDigestAlgorithmsEqual();

DiagnosticData: QCStatements

 
XmlPSD2Info psd2Info = xmlCertificate.getPSD2Info();
List<XmlOID> qcStatementIds = xmlCertificate.getQCStatementIds();
List<XmlOID> qcTypes = xmlCertificate.getQCTypes();
QCLimitValue qcLimitValue = xmlCertificate.getQCLimitValue();
OID semanticsIdentifier = xmlCertificate.getSemanticsIdentifier();
 
XmlPSD2Info psd2Info = xmlCertificate.getQcStatements().getPSD2Info();
QcCompliance qcCompliance = xmlCertificate.getQcStatements().getQcCompliance();
BigInteger qcEuRetentionPeriod = xmlCertificate.getQcStatements().getQcEuRetentionPeriod();
QcEuPDS qcEuPDS = xmlCertificate.getQcStatements().getQcEuPDS();
List<XmlOID> qcTypes = xmlCertificate.getQcStatements().getQCTypes();
QcEuLimitValue qcLimitValue = xmlCertificate.getQcStatements().getQcEuLimitValue();
QCLimitValue qcLimitValue = xmlCertificate.getQcStatements().getQCLimitValue();
OID semanticsIdentifier = xmlCertificate.getQcStatements().getSemanticsIdentifier();