Upgrade Guide

SecureBlackbox 2024 comes with large-scale changes to the API, both in terms of new features and changes to existing features. Every care was taken to minimize the number of painful changes between the versions (those that force the developer to go and change their code to make it compile or work again), but in some cases we still decided to take that step, for the sake of better experience for the long years to come. In this article we summarize the changes that we have introduced in the new version. The baseline for the described changes is SecureBlackbox 2022. There may be other differences with earlier versions. If you are upgrading from SecureBlackbox 16 or older, please see the respective paragraph below.

ArchiveReader and ArchiveWriter

Most of the changes to these components stayed under the bonnet. Among the few visible parts is introduction of the Attributes property in the ArchivedFile class, which offers the capability to provide or read the set of attributes associated with an archived object. Both Windows and Unix attribute models are supported.

AuthenticodeSigner and AuthenticodeVerifier

CustomSignedAttributes and CustomUnsignedAttributes were renamed to SignedAttributes and UnsignedAttributes respectively, and their type changed to SignatureAttribute[] to align better with similar settings in other signing components. The verifier component was also cleaned up to avoid duplication of properties in the component and the subordinate AuthenticodeSignature objects. API of both objects is now aligned more closely to that of other digital signing components.

CertificateManager, Certificate, CertificateRequest

Certificate management objects have undergone a large-scale refurbishment. Certificate and CertificateRequest types have been merged into one (Certificate), with the new CertType property keeping the type of the object content. The Fingerprint and KeyFingerprint properties have become strings, making them easier to integrate with similar settings in external and third-party environments.

CertificateManager has received a CreateNew method that provides for quick creation of certificates from pre-defined templates.

The changes allow for much easier integration of certificate handling tasks both to traditional PKI workflows (generate/issue/revoke) and to more complex systems such as KMIP.

CRLManager and OCSPManager

The components can now be used to generate CRL and OCSP responses (not only to read them).

Certificate stores

Version 2024 introduces a new store type of env://, such as env://?store=trusted. The env stores provide access to process-wide dedicated certificate trust stores that are automatically picked up by all the SBB components working within that process. Three such stores are currently supported: trusted, known, and blocked. Use them instead of having to specify TrustedCertificates, KnownCertificates, and BlockedCertificates lists for every component you are using in the project, or as a process-local alternative to Windows system stores.

Digital signature components

The digital signature creation and validation components, such as CAdESSigner, PDFSigner, XAdESSigner and respective Verifiers, have undergone wide-scale refurbishment to accommodate industry standards and best practices better. The new versions introduces integrated Trusted List support (including EUTL) and automated qualifying policies processing across the board. The chain validation module has also been enhanced to provide better support for complex temporal scenarios and modern PKI environments.

To simplify processing of complex trees of signatures, SelectInfo method was introduced that is a simple way of filtering out information relevant to a particular signature or timestamp. The AdES level management was also simplified through the unified Level property. A number of secondary properties were tucked away to stop them from getting in the way.

SelectInfo relies on a new property of a signature object called EntityLabel. EntityLabel contains a unique identifier of a signature or timestamp within a larger electronic signature structure. The use of SelectInfo with EntityLabel allows to easily filter information associated with a specific signature object, such as the certificate chain that was used to create it or the details of its parent signature (for countersignatures).

EntityLabel works together with the ParentEntity property that references the upper-level container of the current object. For a timestamp, ParentEntity points to the signature the timestamp is made over. For a countersignature, ParentEntity points to the parent signature. ParentEntity set to an empty string indicates that the signature or timestamp object is at the top level of the signature tree - that is, that it covers the actual signed data and not a higher-level signature or timestamp object.

EntityLabel replaces indices in methods such as Upgrade() or Timestamp(). Where in earlier product versions you used to provide the index of the signature to be upgraded, provide the EntityLabel of the respective object. This approach allows to work flexibly with more than one level of signature/timestamp nesting and upgrade signatures and countersignatures at arbitrary nesting level.

Special attention should be paid to revised treatment of timestamps and countersignatures in CAdES components. In version 2024, signatures that are part of the timestamps (those made by the TSA over the TSTInfo block) are now reported explicitly in the Signatures[] collection. That is, a simple CAdES-T message, from SecureBlackbox 2024's viewpoint, consists of the following PKI elements:

  • The primary signature (a signature with EntityLabel=S0 and an empty ParentEntity)
  • The timestamp (a timestamp with EntityLabel=S0:T0 and ParentEntity=S0)
  • The signature over the timestamp (a signature with EntityLabel=S0:T0:S0 and ParentEntity=S0:T0).
The same applies to countersignatures. They are viewed as normal signatures, whose parent entity is another signature. If we countersign the CAdES-T signature considered above, we will get the following structure:
  • The primary signature (a signature with EntityLabel=S0 and an empty ParentEntity)
  • The timestamp (a timestamp with EntityLabel=S0:T0 and ParentEntity=S0)
  • The signature over the timestamp (a signature with EntityLabel=S0:T0:S0 and ParentEntity=S0:T0).
  • The countersignature over the primary signature (a signature with EntityLabel=S0:S0 and ParentEntity=S0).
Version 2024 is capable of reporting nested countersignatures (of levels deeper than 1) - for example, a countersignature made over the above countersignature would get the entity label of S0:S0:S0, and so on.

HTTPClient

The set of Get* methods has been redesigned to align with the remaining HTTP methods: GetBytes(), GetFile(), and GetStream() methods were dropped in favour of OutputBytes, OutputFile, and OutputStream properties. To update an existing GetFile() call, assign the target file path to OutputFile, and then call Get().

Individual authentication type properties (Use*Auth) have been combined into one AuthTypes bitmask.

Mail transport components (IMAP, SMTP, POP)

The API of the mail transport components were refreshed and enhanced following feedback from version 2022 customers. The new version of the components offers smoother authentication flow, detailed session logging, and a variety of integrated OAuth flows. The API itself became simpler and more intuitive.

KMIP components

The KMIP functionality was almost entirely re-approached. The server now supports the virtual mode, allowing to plug in external key management facilities and serve requests on the fly. The client became more flexible and powerful, supporting customization of operations and low-level requests. Both components supports KMIP-over-TCP and KMIP-over-HTTP with optional TLS, and all KMIP encodings (TTLV, XML, JSON).

PKCS#7 Message

MessageEncryptor now supports encryption for multiple recipients.

PGP infrastructure

The new version introduces wide-scale enhancements to the PGP functionality. Version 5 and 6 keys and packets are now fully supported, therefore enabling the use of cutting-edge Argon2 and EdDSA algorithms. The component API has been slightly updated (particularly the PGPKeyManager component), both to cater for the new features and to provide smoother experience.

SAML

The API of the SAML components has been reapproached following industry trends and the feedback we received from customers over the last few years. The API of the Reader and Writer components has been simplified, but at the same time made more flexible to support the most typical scenarios.

The server components now fully support the 'offline' mode, where they can be plugged in to an external web server, such as IIS or Kestrel. The built-in server is still available if required. The servers are also fully virtualizable, with the applications given the opportunity to intervene on every stage of the processing, whether it is to alter the authentication flow or tweak an assertion.

SFTP client and server

SFTPServer now comes with full support for shell, command, and TCP forwarding capabilities.

TSPServer

TSPServer received a Timestamp() method that can be used to generate timestamps locally.

WebSockets

WebSocket components introduce access to key and subprotocol parameters of the websocket session.

Other changes

Apart from technology-specific changes, properties and methods of many components were refreshed to provide uniform and simpler user experience and align better with each other. Below is a summary of such changes:

  • The manager-kind components (CertificateManager, CryptoKeyManager and similar) have introduced a CreateNew() method. The purpose of CreateNew() is to initialize the object managed by the component (such as Certificate in the case of CertificateManager) and prepare it for further setup by the user.
  • The methods that load and save data are now uniformly named as Import* and Export*: for example, what used to be CRLManager.LoadFromFile has become ImportFromFile.
  • The TLS-related properties are now uniformly referenced as TLSsomething, for example, TLSClientChain and TLSServerChain.
  • All components are now publishing a Reset() method that can be used to discard any state kept currently by in the component. The server components additionally introduce a Cleanup() method to purge any accumulated state, such as session cache, without stopping.
  • All defaults have been reviewed and updated to match modern industry expectations.
  • Similar types were merged into one (TLSClientEntry and SSHClientEntry to TLSConnectionInfo and SSHConnectionInfo), SFTPListEntry into FTPListEntry, and a couple others.

Migrating to SecureBlackbox 2024 from earlier versions (16 and older)

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

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