The latest major release of our development libraries focuses on performance and security. This guide highlights some of the key updates and changes. Please visit the Beta Downloads page to download the latest version.

Contents

• IPWorks and SecureBlackbox Updates
  • New security and API updates in IPWorks
  • New signing and encryption functionality in SecureBlackbox
• Upgrade Guide
  • Class and Namespace Capitalization Changes
  • Exception Class Changes
  • Removal of Deprecated Properties
  • Included .NET Platforms
  • API Changes

IPWorks Updates and SecureBlackbox Updates

IPWorks

Several new security features have been added to IPWorks to round out the supported functionality in the toolkit. TLS-related settings have been updated across the board to increase security, such as enabling TLS session re-use by default in FTP, enabling EMS (Extended Master Secret) by default, and updating the list of ciphers used when the SSLProvider is set to Internal. CertMgr has been updated with new CheckCRL and CheckOCSP methods which add support for additional certificate validation mechanisms. The CalDAV component has been updated with support for listing calendars and more.

SecureBlackbox

Updated support for encryption and authentication make SecureBlackbox 2024 the most complete solution to date. PDF and XML signing has been improved by large scale improvements in the AdES engine for simpler processing of LTA documents. Full support for PGP version 6 is now available which includes EdDSA keys and AEAD encryption. The underlying PRNG is now backed by the industry-standard Fortuna algorithm with an option for transparent fallback to the system PRNG facility. The SAML components have been improved to provide greater flexibility and align with modern SAML solutions. All applicable components have also been updated with support for PKI Proxy.

Upgrade Guide

In most cases upgrading from a previous version is as simple as referencing the updated versions of the library. Every effort has been made to minimize the number of breaking changes to ensure a simple upgrade process. The sections below detail some aspects which may be of help while upgrading your project.

Class and Namespace Capitalization Changes

Class names have been capitalized in a standard way. In many editions no changes are required. Only affected editions have been listed. Please see below for details about the impact to each edition.

.NET

Component class names have been renamed to use a standard capitalization. For instance Http and Htmlmailer have been renamed to HTTP and HTMLMailer. This change also applies to enum types that contain the component name. For instance HttpAuthSchemes has been renamed to HTTPAuthSchemes.

Java

Component class names have been renamed to use a standard capitalization. For instance Http and Htmlmailer classes have been renamed to HTTP and HTMLMailer.

Swift

Enum types that contain the component name have been renamed to use a standard capitalization. For instance HttpAuthSchemes has been renamed to HTTPAuthSchemes.

JavaScript

Enum types that contain the component name have been renamed to use a standard capitalization. For instance HttpAuthSchemes has been renamed to HTTPAuthSchemes.

Exception Class Changes

In editions such as .NET where exception objects are instances of a class defined by the library, the exception classes have been consolidated to a single type. Previously exception classes existed for both individual components and the toolkit as a whole. The individual component exception classes have been removed across the board to simplify exception handling.

In addition, a new Source property has been added to all exception classes which reports the name of the component from which the exception was thrown.

.NET

The component specific exception classes such as IPWorksHttpException have been removed. Update code to use IPWorksException. For instance:

catch (IPWorksException ex) { Console.WriteLine(ex.Message); Console.WriteLine(ex.Code); Console.WriteLine(ex.Source); //Outputs "HTTP" }

Java

Java editions did not previously make use of component specific exceptions. However, the Source property is now available. For instance: catch (ipworks.IPWorksException ex) { System.out.println(ex.getMessage()); System.out.println(ex.getCode()); System.out.println(ex.getSource()); }

Delphi

Component specific exception classes such as EipwHTTP have been removed. Update code to use EIPWorks. For instance: except on E:EIPWorks do begin ShowMessage(E.Message); ShowMessage(E.Code); ShowMessage(E.Source); //Outputs "HTTP" end;

C++ Builder

C++ Builder editions did not previously make use of component specific exceptions. However, the Source property is now available. For instance: catch(EIPWCore &ex){ ShowMessage(ex.Message); ShowMessage(ex.Code); ShowMessage(ex.Source); //Outputs "HTTP" }

Python

Component specific exception classes such as IPWorksHttpError have been removed. Update code to use IPWorksError. For instance: except IPWorksError as e: print(e.message) print(e.code) print(e.source)

PHP

PHP is not affected by this change. Exceptions thrown by the component are of the standard Exception type. For instance: catch (Exception $ex) { echo $ex->getMessage(); }

Swift

Component specific exception classes such as HTTPError have been removed. Update code to use IPWorksError. For instance: catch IPWorksError.Error(let errorCode, let errorMessage, let source) { print(errorCode) print(errorMessage) print(source) //Outputs "HTTP" }

JavaScript

JavaScript did not previously make use of component specific exceptions. However, the Source property is now available. For instance: await http.post(url).catch((err) => { console.log(err.message); console.log(err.code); console.log(err.source); });

C++

C++ does not use exception objects, instead error handling is performed by checking the return code of methods, or by calling the component.GetLastError() and component.GetLastErrorCode() methods.

Removal of Deprecated Properties

Properties which were deprecated in version 2022 have been removed in version 2024. In most cases the deprecated property has been replaced by a corresponding method that performs the same functionality.

Included .NET Platforms

In version 2024 the lib\net40 directory contains a .NET 4.0 library suitable for Windows development and includes design-time support for Visual Studio. The lib\net6.0 directory contains a .NET 6.0 library designed for cross-platform support and includes both the traditional component API as well as a separate nsoftware.async namespace for use with asynchronous programming patterns (async/await). Please refer to the Async Support article for additional details.

The .NET Framework 2.0 and .NET Standard 2.0 libraries are no longer included by default, but are available on demand for legacy projects.

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 articles linked below detail major changes between the previous and latest release.

• IPWorks 2024
• IPWorks EDI 2024
• IPWorks IPC 2024
• IPWorks MQ 2024
• IPWorks SFTP 2024
• IPWorks SMIME 2024
• IPWorks SSL 2024
• SecureBlackbox 2024

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 contact us at support@nsoftware.com with any questions or comments.