RSA BSAFE® Micro Edition Suite 4.
Copyright and Trademark Notice and Trademarks Copyright © 2019 Dell Inc. or its subsidiaries. All rights reserved. Dell believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS”. DELL INC.
Migration Guide Contents Preface .................................................................................................................................... 1 Document Organization ...................................................................................................... 2 Related Documentation....................................................................................................... 3 Support and Service .....................................................................
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Chapter 3: Changes in MES 4.3 ................................................................................. 17 Library Files...................................................................................................................... 18 Cryptographic API Changes ............................................................................................. 19 Improved ASN.1 AlgorithmIdentifier Handling ............................................
Migration Guide Preface This document describes changes made in the RSA BSAFE Micro Edition Suite (MES) toolkit, and the changes required when migrating applications between MES 4.0.1 and MES 4.4. Important: The migration requirements listed for each release are cumulative. Please read this guide completely before starting the migration process. This guide is intended for use by software developers already familiar with their version of MES, and who intend to migrate their applications to MES 4.4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Document Organization This guide is organized into the following chapters: 2 • Chapter 1 Changes Between MES 4.0.1 and 4.1.n.n, which describes the changes implemented in the releases from MES 4.0.1 up to, but not including MES 4.2. • Chapter 2 Changes in MES 4.2, which describes the changes implemented in release MES 4.2. • Chapter 3 Changes in MES 4.3, which describes the changes implemented in release MES 4.3. • Chapter 4 Changes Between MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Related Documentation The MES documentation suite includes: • This document, the RSA BSAFE Micro Edition Suite Migration Guide, in Portable Document Format (PDF), which describes the changes required to migrate existing applications between MES 4.0.1 and MES 4.4. • RSA BSAFE Micro Edition Suite Release Notes, in PDF, with the latest information on MES.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Support and Service Access community and support information for your RSA BSAFE products on RSA Link at https://community.rsa.com/community/products/bsafe. RSA Link offers a knowledge base containing answers to common questions and solutions to known problems, product documentation, community discussions, and case management. Customers can also open support cases by sending an email to support@rsa.com. RSA Ready at https://community.rsa.
Migration Guide 1 Changes Between MES 4.0.1 and 4.1.n.n The chapters covered the changes made between release 4.0.1 and 4.1.n.n that must be considered. Topics: • Library Files • Resource Management • Cryptographic API Changes • Library Files • TLS Changes Chapter 1: Changes Between MES 4.0.1 and 4.1.n.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Library Files In MES 4.1, the ccme_core static library file was renamed to mes_core. The mes and mes_core libraries provide the standard MES functionality and must always be linked with the application. Any combination of the other libraries (ccme_swprov, ccme_fipsprov, and mes_p11prov) can be linked into the application as required.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Resource Management Common Resources Resources that provide core MES functionality, required to use resources from any of the providers, are available from the mes_core library file. These common resources can be accessed individually for custom resource lists, or as a list using R_PROV_MES_get_default_resource_list().
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Cryptographic API Changes Default PRNG MES 4.1 adds the CTR DRBG as a self-seeding PRNG to the existing HMAC DRBG implementations. The HMAC DRBG implementations are extended to include HMAC SHA512/224 and HMAC 512/256 DRBGs. The PRNG created using the identifier, R_CR_ID_RANDOM_DEFAULT, chooses the CTR DRBG in preference to all HMAC DRBGs when the default resources are used by an application. Elliptic Curve Private Asymmetric Key Write Format MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Cryptographic Message Syntax MES 4.0.2 included a redeveloped implementation of the Cryptographic Message Syntax (CMS). This section describes the functionality available if implementing CMS into your applications.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide TLS Changes PRNG Security Enhancements MES 4.1 introduced the following PRNG-related security enhancements: • Random cryptographic objects are reseeded with a small amount of entropy after a specified period of time to prevent attacks involving the cloning of virtual machines. • Enhanced seed generation for DRBGs by adding a default personalization string, based on the current time, process ID, and thread ID, to the random cryptographic object.
Migration Guide 2 Changes in MES 4.2 The chapters covered the changes made in MES 4.2 that must be considered. Topics: • Library Files • Cryptographic API Changes • TLS Changes Chapter 2: Changes in MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Library Files The ccme_swprov static library file was renamed to mes_swprov. The mes_swprov library provides cryptographic implementations that are not FIPS 140-2 compliant. Migrate Non-FIPS 140-2 Applications Applications using standard or software cryptographic functionality, which previously linked against the ccme_swprov library file, now link against the mes_swprov library file. Header File and Namespace Changes MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Migrate Shared Libraries Shared libraries using MES 4.2 must be recompiled with the new public header files. If the shared library exposes a transitioned MES function, to make the shared library a drop in replacement, bridging functions must be written. These bridging functions implement the old function by calling the new namespace version and are compiled into the shared library.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Cryptographic API Changes Symmetric Key Encryption Cryptographic Objects Creation of cryptographic objects for symmetric key encryption now expects one or both of the R_CR_SUB_DECRYPT and R_CR_SUB_ENCRYPT sub-identifiers to be specified explicitly to identify the type of operations to be performed. During creation of the cryptographic object, all requested operations are checked for availability in the resource list.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Create a Symmetric Key Encryption Object - MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide TLS Changes Protocol Changes SSLv3 Support The SSLv3 protocol has known vulnerabilities and is not secure. In MES 4.2 it was disabled by default. It should not be used. RSA strongly recommends using the TLS 1.2, 1.1, or 1.0 protocols instead. For more information, see RFC 7568 Deprecating Secure Sockets Layer Version 3.0. 16 Chapter 2: Changes in MES 4.
Migration Guide 3 Changes in MES 4.3 The chapters covered the changes made in MES 4.3 that must be considered. Topics: • Library Files • Cryptographic API Changes • Cryptographic Message Syntax • TLS Changes Chapter 3: Changes in MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Library Files In MES 4.3.1, the mes_iosprov static library file was included. On systems running an iOS operating system, FIPS 140-2-compliant applications must link against the mes_core, mes_iosprov, and mes static libraries. The mes_iosprov library accesses FIPS 140-2-validated cryptographic functionality through the iOS common cryptographic library. 18 Chapter 3: Changes in MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Cryptographic API Changes Improved ASN.1 AlgorithmIdentifier Handling MES 4.3 introduces improved support for ASN.1 AlgorithmIdentifier handling, including: – A new algorithm parameters object (R_ALG_PARAMS) to represent the configurable aspects of cryptographic algorithms, and to allow encoding and decoding of AlgorithmIdentifier data.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Cryptographic Message Syntax MES 4.3 added to the redeveloped implementation of the Cryptographic Message Syntax (CMS). This section describes the functionality available if implementing CMS into your applications.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide TLS Changes SSLv3 Deprecated The SSLv3 protocol has known vulnerabilities and is not secure. In MES 4.3 it is deprecated. It will be removed in the next release of MES. It should not be used. RSA strongly recommends using the TLS 1.2, 1.1, or 1.0 protocols instead. For more information, see RFC 7568 Deprecating Secure Sockets Layer Version 3.0.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide 22 Chapter 3: Changes in MES 4.
Migration Guide 4 Changes Between MES 4.3.1 and 4.4 The chapters covered the changes made between MES 4.3.1 and MES 4.4 that must be considered. Topics: • Library Files • Cryptographic API Changes • TLS Changes Chapter 4: Changes Between MES 4.3.1 and 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Library Files MES 4.4 introduces the FIPS 140-2 provider for the iOS environment, in the ccme_fipsprov file. For applications that previously linked against mes_iosprov, developers can now choose to continue to link against mes_iosprov or to link to ccme_fipsprov. RSA recommends linking to ccme_fipsprov for broader support of cryptographic algorithms.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Memory Management For MES 4.4 the definition for the realloc() method of the custom memory allocator has changed and the application must update its implementation accordingly. For more information about memory management functionality, see Memory Management in the RSA BSAFE Micro Edition Suite Developers Guide. Chapter 4: Changes Between MES 4.3.1 and 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Cryptographic API Changes Asymmetric Key Operations Asymmetric Key Assurance The proper management and use of cryptographic keys is essential to the use of cryptography for security. NIST provides a wealth of guidance for the management of keys, and this is included in the FIPS 140-2 standard. Even when FIPS 140-2 compliance is not required for an application, following the NIST guidance is recommended.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide FIPS 186-2 DSA The following table lists details about the FIPS 186-2 DSA key parameter generation information identifiers for MES 4.4. Table 2 FIPS 186-2 DSA Key Parameter Generation Information Identifiers Prior to MES 4.4 MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Key Wrapping Key wrapping is a method of encrypting key data for protection on untrusted storage devices or during transmission over insecure channels. Previous versions of MES provided wrapping of key data using specific key wrap algorithms (using AES symmetric key encryption), or applications could also use asymmetric key encryption and wrap key data using a recipient’s public key.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide The following table lists the algorithm subtypes to specify when creating a cryptographic object for key wrapping, for MES 3.1 through 4.3.1 and MES 4.4. Table 5 Key Wrapping Algorithm Subtypes MES 4.3.1 MES 4.4 R_CR_SUB_NONE If wrapping with a symmetric key, R_CR_SUB_SYMMETRIC_KEY, plus the type of key you are wrapping. One of: • R_CR_SUB_WRAP_SKEY • R_CR_SUB_WRAP_PKEY • R_CR_SUB_WRAP_RAW.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide Wrap the Key Data The following table lists the functions used to wrap the key data in MES 4.4. Table 7 Key Wrapping Functions MES 4.3.1 MES 4.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide TLS Changes SSLv23 Methods Removed Originally to allow maximum flexibility for clients and servers negotiating the protocol version to use, all SSLv23 method functions are now removed. Cipher Suite Updates The R_SSL_DEFAULT_CIPHER_LIST is updated to remove all cipher suites that use RSA key exchange, except for TLS_RSA_WITH_AES_128_CBC_SHA. For more information, see TLS Operations > Cipher Suites in the RSA BSAFE Micro Edition Suite Developers Guide.
RSA BSAFE Micro Edition Suite 4.4 Migration Guide 32 Chapter 4: Changes Between MES 4.3.1 and 4.
