SecureBlackbox 2020 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.

Contents

Overview

The most significant change is the redesigned API. The new API is simpler than previous versions, and is more consistent with existing /n software products. The new API allows us to offer SecureBlackbox on more platforms than ever, increasing the overall number of deployments, which directly relates to quality and viability. The API principles that have made /n software the leading Internet tools vendor have been applied to SecureBlackbox 2020 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.

Usage 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 SecureBlackbox 16 style 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 OnCertificateValidate 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 the 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 Windows storage
Storage.Open("pkcs11://user:1234@/c:/windows/system32/asepkcs.dll?slot=0"); // opening 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 2020 offers CAdESSigner, PAdESSigner, 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

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 2020.

The new approach to the in-browser signing involves two principal pieces on the workstation side: a system service that relies on 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 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.

SecureBlackbox 16 Style API Notes

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 .NET and Java editions, and as a separate Backwards Compatiblity Pack download for the Delphi edition.

.NET

The first change you will notice after upgrading to SecureBlackbox 2020 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 2020 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.NetStd.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

The first change you will notice after upgrading to SecureBlackbox 2020 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 2020 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 have already tried installing SecureBlackbox 2020 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 2020, please download the setup file that matches your version of Delphi/C++ Builder to get the familiar .dcu files.

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.