SecureBlackbox 2022 Upgrade Guide

In the latest version of SecureBlackbox we continued with our primary strategy of packaging complex security technologies into simple and easy-to-use components. The simple design is balanced with flexibility and power, making the components applicable to a variety of business tasks. The new version puts extra focus on novel usage scenarios, such as long-term signatures, and better supporting emerging technologies, such as SAML.

Overview
Usage Notes
API Changes
SecureBlackbox 16 Style API Notes

Overview

The new version mostly keeps the same collection of components as version 2020. However, many components have been refreshed, extended with new features, or re-designed to offer a better development experience.

Among the highlights of version 2022 are "edit mode" in PDF, ASiC, and other digital signing components, extended virtualization capabilities in the Internet servers, and better integration of the DCAuth components to the SecureBlackbox ecosystem. Individual technologies, such as SAML, TLS, SSH, AdES, or mailing protocols, have been updated to match the most recent developments in the industry.

Customers that still rely on the v16-compatible API in their older projects will also benefit from the improvements in the respective API layer. Every new technology added to SecureBlackbox always goes to both sets of APIs.

Usage Notes

Below we will discuss the most important changes in the components. Some of them may affect your existing projects, and in some cases you will need to make changes to your code. We tried to keep such changes to a minimum. Please read on to find out more about them.

PDFSigner and PDFVerifier

The PDF components were extended with support for "edit mode", as opposed to "one-pass mode" offered in SecureBlackbox 2020. What this means is that you can split the signing or verifying operation into smaller logical steps, by replacing


signer.Sign();

with the following multi-step code:


signer.Open();
signer.Sign();
signer.Close();

Our customers have long demanded this functionality to be able to adjust the appearance and position of the signature widget basing on the contents of a particular document. Edit mode provides a convenient way of doing that. This is complemented by a handy mechanism of retrieving the page and signature information and adjusting the look of the widget.

We have organized the classes to make the API more logical. The PDFSignature class was split into two classes, PDFSignature and PDFWidget, with the latter encapsulating the widget look parameters. The old PDFSigner.Signature property was renamed to NewSignature, which reflects its purpose better, and also avoids clashing with new Signatures[] property.

The PDFSigner class has received a large share of the old PDFVerifier functionality. This is to simplify our offerings for the use cases which require processing and creation of signatures at the same time. You can also re-validate signatures without reopening a PDF document.

Note: The old one-pass signer.Sign() and verifier.Verify() syntax still works as well.

ASiCSigner and ASiCVerifier

The ASiC components are another pair of components to introduce "edit mode", allowing for much more flexible operations on archived files. As with our PDF components, the ASiC components allow you to re-validate signatures without re-opening the documents. This may be handy if you need to provide extra validation material between the validations.

ASiCSigner has also incorporated much of the ASiCVerifier functionality - meaning you can use the ASiCSigner class for both signing and basic verification purposes.

The API changes in PDF and ASiC components, while large-scale, have little effect on existing code. In many cases it will only take a few minutes to update your code to work with the updated version of the components. At the same time, you can start exploring the new edit mode functionality for projects that demand it.

CAdESVerifier

The CAdESVerifier component was significantly reworked to allow for a variety of new validation scenarios. The new CAdESVerifier is capable of processing signatures of infinite depth (such as a countersignature made over a countersignature made over a countersignature made over a signature). If you are using CAdESVerifier in your existing project, please take care when updating, as the behaviour of the new component differs from that of the previous version. Depending on your usage scenario, the changes in the component behaviour may require your code to be updated.

Internet Clients

All the client components have been updated to support the latest revisions of the underlying protocols. TLS-capable components had their TLS event reporting updated, with five TLS events (TLSHandshake, TLSCertValidate, TLSCertNeeded, TLSEstablished, and TLSShutdown) introduced across the board.

Individual components saw new smaller but still valuable features added, such as plain second channel support in DTLS (for SRTP protocol alike), exporters in TLS and DTLS, and multipart body support in HTTP.

Internet Servers

The server components now include enhanced virtualization capabilities through new events and the ProcessGenericRequest method. The events let you intercept specific operations - such as file uploads in FTP server - and redirect the data to external, possibly non-file locations. The ProcessGenericRequest method lets you use the components "offline", without physically binding them to a network interface. One example of using that method is where you would like to attach the functionality of a SAML service provider to an existing HTTP engine, such as IIS.

Remote and Async Signing

The async signing components are now fully integrated into the primary SecureBlackbox ecosystem. This means that you can pass the Certificate object directly to the DCAuth object, wherever you obtained it from (PKCS#11 device, Windows system store, or a database). You can now also timestamp PKCS7/CMS signatures on the DCAuth side.

Certificates and Certificate Stores

The certificates engine has seen a few changes. We added Login and Logout methods to CertificateStorage class, which should make it simpler to work with PKCS#11 devices. We also moved the Qualified Certificates functionality to CertificateValidator, which is now its single point of access.

The components that encapsulate chain validation also received a uniform set of chain-related events (ChainValidationProgress, ChainValidated, ChainElementDownload), which makes tracking or altering the chain validation process simpler.

The Utils Class

Last but not least, we've added the Utils class that contains a few useful auxiliary methods. From string encoding, to DNS resolving, to multipart message formatting and list management, this little helper may be of good use in a variety of developmental situations.

Additional Features

Among other changes that are worth mentioning are:

The .NET Standard assembly is now called nsoftware.secureblackbox.dll.
Delphi edition supports dynamic loading (GetProcAddress) of the SecureBlackbox dll.
Java and Android editions were merged together.
C++ edition fully supports streams.

API Changes

In most cases upgrading is seamless and requires no code changes, as efforts have been made to maintain backwards compatibility. However, the latest release includes several API changes that may require code changes. The Secure Blackbox 2022 API Changes page details major changes between the previous and latest release.

Upgrading to the latest version is designed to be a quick process and involve only minimal code changes while offering additional functionality and options for new and existing users.

Please be aware that the installation location in version 2022 defaults to the %UserProfile%\Documents location on the system. In previous versions the installation defaults to the Program Files folder. This change makes compiling and running the sample projects easier, as they no longer need elevated permissions to run.

SecureBlackbox 16 Style API Notes

The SecureBlackbox version 16 API is still included in .NET, Java, and Delphi editions, so your older projects that rely on it are safe. Driven by design of SecureBlackbox classes, the v16-style API gets all the improvements and security updates as the new-style API does.

.NET

If you are upgrading from version 2020 to version 2022 (and using the v16-style API in your project) there will be no major changes for you. The directory structure of the product, the file and component names, the licensing model have all inherited the version 2020 styling.

If you are upgrading from version 16 (or earlier) to version 2022, please read on. There have been important changes between version 16 and version 2022.

The first change you will notice after upgrading to SecureBlackbox 2022 is the absence of a bunch of SecureBlackbox.*.dll assemblies. To make the things simpler there is now there is only one assembly. The SecureBlackbox 2022 distribution therefore only contains the following few assemblies:

lib\nsoftware.SecureBlackbox.dll - a SecureBlackbox assembly targeting CLR 2.0
lib\net40\nsoftware.SecureBlackbox.dll - a SecureBlackbox assembly targeting CLR 4.0
lib\netstandard20\nsoftware.SecureBlackbox.dll - a SecureBlackbox assembly targeting .NET Standard 2.0.

Each assembly contains the same set of components, representing both the new and the old APIs. All the components from the new API are provided in nsoftware.SecureBlackbox namespace. The components from the old API are available in their original namespaces (SBHTTPSClient, SBCAdES etc.)

Replace all the references to SecureBlackbox assemblies with a single reference to appropriate nsoftware.SecureBlackbox.dll assembly when migrating your existing projects. This should bring any old-API SecureBlackbox components back into scope with no further actions needed.

Note: Please see the Licensing Instructions section of the help file for details on licensing the components when using the SecureBlackbox 16 Style API.

Java and Android

If you are upgrading from version 16 (or earlier) to version 2022, please read on. There have been important changes between version 16 and version 2022.

The first change you will notice after upgrading to SecureBlackbox 2022 is the absence of a bunch of secureblackbox.*.jar packages. To make the things simpler there is now there is only one jar file. The SecureBlackbox 2022 distribution therefore only contains the following few jar files:

secureblackbox.jar - the development version of SecureBlackbox jar (includes help files)
deploy.jar - the deployment version of a SecureBlackbox jar (smaller size and no help files)

Both jars contain the same set of components, representing both the new and the old APIs. All the components from the new API are provided in secureblackbox namespace. The components from the old API are available in their original namespaces (secureblackbox.HTTPClient, secureblackbox.XML etc.). There is one important change here: the first part of the original namespace became all-lowercase, so what used to be SecureBlackbox.XML became secureblackbox.XML.

When migrating your existing SecureBlackbox-powered projects, replace all the references to SecureBlackbox jars with a single reference to the new secureblackbox.jar or deploy.jar. Update import directives in your Java files, and you should be good to go - any old-API SecureBlackbox components should be back in scope with no further actions needed.

Delphi and C++ Builder

If you are upgrading from version 16 (or earlier) to version 2022, please read on. There have been important changes between version 16 and version 2022.

If you have already tried installing SecureBlackbox 2022 Delphi edition you will have noticed that the product has undergone large-scale changes. What used to be packaged in .dcu units has been replaced with .dru and .pas files. The old-API components are also no longer present.

For backward compatibility reasons we also provide the new and old API components in .dcu form. These are available as SecureBlackbox Delphi Backwards Compatibility Packs which are available as a separate set of downloads when selecting the Delphi Edition. If you are evaluating migrating an existing SecureBlackbox-driven project to SecureBlackbox 2022, please download the setup file that matches your version of Delphi/C++ Builder to get the familiar .dcu files.

The SecureBlackbox Backwards Compatibility Pack does not register paths to the units in the IDE. You can add them manually by going to Project -> Options -> Delphi Compiler and adding the following directory to your search path: C:\Program Files\nsoftware\SecureBlackbox 2022 Delphi Edition - Backwards Compatibility Pack\code\<Delphi Version>\<OS>.

Note: Please see the Licensing Instructions section of the help file for details on licensing the components in the Backwards Compatibility Pack.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.