Upgrade Guide

The latest version of SecureBlackbox has been carefully redesigned and extensively improved. This guide is intended to help answer common questions existing users may have when upgrading to the new version. For users which do not wish to upgrade immediately, we also offer a backwards-compatible API in the .NET, Java, and Delphi editions. More details about the availability and use of the backwards-compatible API are included below.

Migrating to SecureBlackbox 2022

The most significant change is the redesigned API introduced in version 2020. The new API is simpler than previous versions, and is more consistent with existing /n software products. The API principles that have made /n software the leading Internet tools vendor have been applied to SecureBlackbox 2022 in order to enrich and streamline the development experience. The new API reflects our vision of the future of IT security, and aims to make it easier and safer for our customers to use security technologies in their projects.

The simplified interface reduces complexity and thereby reduces potential errors and security issues. By default the components will use best practices for all security-related functionality, removing the burden on the developer to make a choice. For advanced users, the components can still be configured as needed through the use of the Config method.

Upgrading to the new API will require code changes, however in most cases this can be done without a large time investment. Our support team is available at support@nsoftware.com to discuss what might need to change for your particular use case.

The below sections provide information about common use cases and recommended upgrade paths.

General Notes

Considering the above, most of your code involving SecureBlackbox is likely to become much simpler after the migration. You will use fewer components and settings. Most of the auxiliary tasks that you used to perform in your code will now be undertaken by the new components.

The new components rely on improved SecureBlackbox 16-style components internally, which ensures compatibility and inheritance between the new and the old API.

Certificate Validation

All TLS-capable components now validate certificates internally in accordance with the local trust settings. On Windows, the standard system stores (ROOT, CA) are used as a source of trust. This is different from the behavior used in the SecureBlackbox 16-style versions where the ultimate decision about the trust was up to the user's code (and was typically requested via the OnCertificateValidate event).

You can alter the trust settings (for example, on Linux, where there are no system-wide trusted certificate lists) by providing your own trusted and known certificates via the TrustedCertificates and KnownCertificates properties. Every component that may need to validate certificates publishes those properties.

In exceptional circumstances you can override the validation behavior by setting component.TLSSettings.AutoValidateCertificates to false and subscribing to the OnTLSCertValidate event. This will bring the component's behavior back to the SecureBlackbox 16 style.

Accessing Certificate Stores

The diversity of SecureBlackbox 16-style TElXXXCertStorage classes have been replaced with a single CertificateStorage component. This component encapsulates work with certificate storages of different kinds, including PKCS#11 and Windows system stores.

Tell the component what kind of storage to open by providing a specially crafted URI-like storage Id. For instance:

Storage.Open("C:\Certs\certs.pem"); // opening a file storage
Storage.Open("system://currentuser@localhost/?store=MY"); // opening a Windows storage
Storage.Open("pkcs11://user:1234@/c:/windows/system32/asepkcs.dll?slot=0"); // opening a PKCS#11 storage

Please note that your storage component must remain open for as long as you need to use certificates originating from there. When a storage is closed, any links between the certificate objects originating from it and their keys are lost. If the storage is closed prematurely, any attempts to use such certificates (for signing or encryption) will fail.

CAdES, PAdES, XAdES, and ASiC

The advanced signature features are among those that have been significantly redesigned and simplified. SecureBlackbox 2022 offers CAdESSigner, PDFSigner, and XAdESSigner components that are capable of creating the respective advanced signatures in just over a few lines of code. The chain validation functionality, including CRL/OCSP retrieval and management, is now performed by the components internally with no special actions needed from your code.

While migrating this part may be slightly challenging, most of it is likely to be about removing the existing code rather than modifying it.

E-mail and MIME

The MIME class infrastructure has been replaced with a much simpler MailMessage class and a pair of MailReader and MailWriter classes for email processing and serialization.

ZIP and Archives

The ArchiveReader and ArchiveWriter classes provide simpler access to the compression technologies. They work with all supported archive types (ZIP, bzip2, gzip, tar), and provide uniform access to the underlying compression mechanisms.

DC (Distributed Crypto)

DC has long been set to change, dictated by efforts from browser vendors to retire the in-browser technologies capable of circumventing the sandbox. The change in DC is one of the biggest in SecureBlackbox 2022.

The new approach to in-browser signing involves two principal pieces on the workstation side: a system service that relies on the DCAuth component (ex-TElDCStandardServer) to sign incoming DC requests, and in-browser JavaScript that is capable of forwarding the DC requests from the browser to the service via Ajax. This eliminates the use of "now-illegitimate" technologies like Java applets altogether, making the scheme fair, cross-platform, and usable in the long term.

The workstation-side application eliminates the need to implement the desktop-side solution for most common usage scenarios.

The application-level components, such as PDFSigner, support DC via their SignAsyncBegin and SignAsyncEnd methods. These are equivalents of the InitiateAsyncSign and CompleteAsyncSign methods.

Network Protocol Clients

The APIs of FTP, HTTP, SFTP, and mail clients have been simplified, but the general usage approaches have largely been kept unchanged.

Network Protocol Servers

All server components now come with built-in networking capabilities, so you don't need to bother with sockets and threads.

Licensing Notes

In previous versions of the product you used a SetLicenseKey() call to pass your license key to the components. This is no longer the case: you will receive a new shorter product key from our licensing team used during installation. For instructions on how to license the components for distribution please see the Licensing Instructions page.

Using the SecureBlackbox 16-Style API

We understand that in many cases migrating a project to a brand new set of components, however close in technology, may not be a preferred course of action. One example is where your current code was formally tested or certified and the migration will require recertification. For such scenarios, and for backward compatibility reasons, we continue to offer the SecureBlackbox 16-style API. This is available by default in the .NET and Java editions, and as a separate Backwards Compatiblity Pack download for the Delphi edition.

The documentation for the v16-style API is available here.

Upgrade Notes

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.