HOWTO: Upgrading to version 8 of Rebex libraries

In most cases, upgrading from versions 6 or 7 of Rebex libraries to version 8.0 is simple and straightforward. However, the new version does introduce some breaking changes, either due to removal of long-deprecated APIs, for security reasons, or to fix compatibility with third-party tools.

Collection API changes

Some collection APIs in Rebex SFTP, FTP or Mail have been updated in order to make them compatible with Linq enumeration intelisense in Visual Studio. For this reason, SftpItemCollection, FtpItemCollection and ZipItemCollection are no longer subclasses of LocalItemCollection, although they can easily be converted to it when neeedd.

ArchiveItemCollection has been removed from Rebex ZIP. Use ZipItemCollection instead.

SHA-256 instead of SHA-1

SHA-256 is now used as a default hashing algorithm instead of SHA-1 thoughout Rebex APIs. This also affects SignedData, EnvelopedData and AsymmetricKeyAlgorithm class.

One particular area to watch out for are the settings-less variants of SignMessage and VerifyMessage low-level methods. When used with an RSA key, these now default to SHA-256 instead of SHA-1. To continue using SHA-1 with these, make sure to specify it using the parameters argument.

Deprecation of 3DES

In S/MIME, default for encryption has been changed from 3DES to AES. This also applies to PFX/P7B certificate saving on recent platforms in FIPS-only mode.

FIPS 140-3 mode instead of FIPS 140-2

Instead of FIPS 140-2, the UseFipsAlgorithmsOnly setting now enables 'FIPS 140-3 mode', which limits usage of cryptographic algorithms, and forces usage of cryptographic modules to those provided by .NET or the operating system.

Cryptography updates

We migrated from the legacy CryptoAPI to the new Windows CNG API wherever possible. Certificate.LoadPfx, CertificateChain.LoadPfx and Certificate.Associate methods now prefer CNG key stores by default instead of legcy CryptoAPI key stores. If you insist on using deprecated CrytoAPI stores on recent editions of Windows, use an overload with options parameter.

Certificate constructor has been updated to only accept X.509 format. To load other formats, use appropriate method.

DiffieHellmanCryptoServiceProvider class has been deprecated beacuse it uses the legacy Windows CryptoAPI. As a replacement, use DiffieHellman.Create to get a new implementation based on Windows CNG API (or a managed implementation on non-Windows platforms).

Custom certificate engines now responsible for server name validation

Previously, our TLS library validated the server name on its own, without passing the responsibility for this to the current certificate engine. However, this prevented custom certificate engines to perform their own validation, and has been changed.

Custom certificate engines are a niche feature, but it you do use a custom engine, it is very important to make sure that it validates server names correctly before upgrading.

Rebex.FileServer dependency change

Rebex.FileServer no longer depends on Rebex.FileSystem. If your project needs Rebex VFS API from Rebex.FileSystem, just add reference to Rebex.FileSystem to your project.

SFTP client no longer ignores file close errors

Previous versions of Rebex SFTP ignored errors by default when closing server-side file handles, potentially masking some unexpected issues. This is no longer the defaulty behavior, but can be enabled again using Sftp.Settings.IgnoreCloseErrors option.

Disallowed unstable SSH key exchange on end-of-life version of Windows

Previous versions of Rebex SSH library made it possible to use Windows CNG providers to implement SSH elliptic-curve key exchange. However, these providers were not quite suitable for SSH on end-of-life versions of Windows, resulting in unexpected negotiation errors in several percent of cases.

Windows 10 or later no longer suffers from this issue, so the usage of non-compliant CNG providers have been disabled. If this affects you, consider using the Rebex.Castle ECDH plugin.

MIME parameters order is preserved when loading and saving a message

This chaneg aims to enhance compatibility by preserving more of the original message structure, in a more predictable way, but it might cause MIME output to be slightly different than before.

SSH updates

The list and order of SSH ciphers has been updated. The original ciphers and order can still be enabled when needed.

TLS updates

When TLS 1.3 is enabled, a new asynchronous TLS 1.2 core is used as well. Should this cause any problems in compatibility or performance, disabling TLS 1.3 will revert to the old TLS 1.2 core as well.

TLS defaults have been updates as well (along with TlsCipherSuite.Secure/Common/Weak.Vulnerable), but all the old ciphers and deprecated TLS/SSL protocol versions can still optionally be enabled. However, it would be better to keep them switched off, as they might not be avalable in version 9.0 any more.

To enable SSL 3.0, use the new SslAllowDeprecatedVersions. Although, of course, upgrading to TLS 1.3 or 1.2 is preferred.

TlsVersion.Any has been changed to only include TLS 1.2 and 1.3 in order to prevent enabling of TLS 1.0 or 1.1 by default. It's recommended to stop using Any and specify desired versions explicitly.

We reviewed and hardened the TLS 1.2 state machine. This should not cause any issues with well-behaved TLS endpoints.

X.509 validation check might return a new result - TlsCertificateAcceptance.BadCertificateStatusResponse.

Removed SmtpDeliveryEngine.System

Rebex SMTP previously had the capability to use .NET's SMTP engine for e-mail delivery, but this stopped working proprly due to changes made in .NET Core runtime. Of course, SmtpDeliveryEngine.Rebex is still supported.

Removed long-deprecated APIs

This version finally removes some very old APIs that have been deprecated since 2012:

• Overloads of Connect method with FtpSecurity, ImapSecurity, SmtpSecurity, Pop3Security arguments. Use SslMode instead.
• PutFiles and GetFiles methods on Ftp and Sftp classes. Use Upload/Download instead.
• Removed Secure methods from Ftp, Imap, Smtp and Pop3 classes. These legacy feature were a leftover from early times of TLS, and no loner have a place in 2026. Instead, just use a secure variant of Connect method.
• Removed Reinitialize method from Ftp class. These legacy feature were a leftover from early times of TLS and has never been properly supported by majority of FTP servers. Instead, use Disconnect followed by another Connect call.