WL#8102: Make sure MySQL compiles and runs with the OpenSSL FIPS Object Module

Test if the server, the openssl udf and the client compile and work with the OpenSSL FIPS object module.

https://www.openssl.org/docs/fips/UserGuide-2.0.pdf

Functional Requirements

• FR 1: prerequisite:

We need to build and install openssl library and openssl fips object module in system installation path for testing purpose. MySQL should use installed system openssl fips libraries as dynamic libraries and should work as expected. Currently supported OS is EL7 because of testing efforts. But user can build openssl library and openssl fips object module in any OS and use with MySQL.

• FR 2: Server shall support restricting OpenSSL library to use FIPS 140-2 compliant algorithms

New global variable named ssl_fips_mode will be added.

• • FR 2.1: A new dynamic system variable shall be added to restrict usage of cryptography algorithms to FIPS 140-2 compliant versions

ssl_fips_mode variable possible values will be (enumeration values): OFF (0): ssl_fips mode is disabled and all the encryption/security algorithms will be allowed.
ON (1): ssl_fips mode is on and only mandated encryption/security algorithm will be allowed (as per fips-140-2 specifications)
STRICT (2): This ssl_fips mode will restrict usage of suite B encryption algorithms as per fips-140-2 specifications. (as mentioned in the openssl fips user guide)
Kindly Note that fips mode ON and STRICT both enforces the fips mode to ON.
fips mode ON is recommended usage and main requirement for this work-log. fips mode STRICT is futuristic in nature. It has been added to allow if some users want to do so.
Exact behavior of FIPS mode ON/STRICT depends on openssl version used. Please refer respective openssl fips user guide for more details..

• FR 3: ssl_fips_mode usages:
  • FR 3.1: Default value of ssl_fips_mode will OFF and MySQL server functionality should not be impacted in any way.
  • FR 3.2: ssl_fips_mode will be set in the server start-up. Setting ssl_fips_mode variable will call openssl method FIPS_mode_set.
  • FR 3.3: If ssl_fips_mode is ON/STRICT, FIPS_mode_set method will check the integrity of fips object module and perform some specific fips tests. FIPS_mode_set method will return error in-case of something wrong and in turn MySQL server will exit with the proper error.
  • FR 3.4: If ssl_fips_mode is ON/STRICT, NON fips complaint usage of openssl functions will be failed with error code, We will be reporting such detailed errors to the end interface.
  • FR 3.5: ssl_fips_mode variable can be modified any time and current value will be returned to the user.
  • FR 3.6: ssl_fips_mode only can be set by the user having SYSTEM_VARIABLES_ADMIN or super user privilege .
• FR 4: All the non FIPS mode openssl api static usage like MD5 will be identified and not be allowed to call.

As per fips object module user guide error code will be return in-case of not fips mode openssl methods call/usage but not calling the API's where possible is recommended.
All these methods will be mentioned in the HLS section.

• FR 5: If any of the MySQL functionality is non FIPS complaint and not possible to fix. These functionalities will be documented.
• FR 6: This feature will be only tested and supported on EL7.
• FR 7: We need to support ssl_fips_mode for the MySQL client library.
• FR 8: We need to support ssl_fips_mode for the MySQL clients.
  

Some major functionality when fips mode is set in the clients, and that will set fips mode to openssl library.

• • FR 8.1: During client process initialization/ Before connection phase / During ssl initialization: When fips mode is ON/STRICT openssl library used should be build with openssl fips object module. There is code hash checked for openssl, so there cant be any local code changes in the openssl library code.This ensures tempered openssl library usage. Clients / Server process will exit if fips mode is ON/ STRICT and openssl fips library is not used.
    
  • FR 8.2: In Server/clients process complete life cycle once fips mode is set: In the server/clients weak encryption algorithm like MD5 will not be allowed. And calling such function with abort the server/client process. Such calls should not be made if FIPS mode is ON/STRICT
    
  • FR 8.3: During connection phase: Server and client ssl connection will not allow weak ciphers like RC4/MD5.
    
• FR 9: Server and client connection behavior:
  • FR 9.1: Server and client will be able to connect successfully with any server/ client combination of OFF/ON/STRICT.
    

Server and clients connection status with various fips mode

• • FR 9.2: Server and client will be able to connect successfully with any combination even when one of them don't support FIPS mode (Different versions).
    
  • FR 9.3: Server and client will failed to connect if weak cipher based on MD5/RC4 is used and FIPS mode is ON/STRICT in clients/ server.
    
• FR 10: We need to support ssl_fips_mode for the plug-ins which uses openssl library.
  

Following plug-in uses openssl and should support ssl_fips_mode
OKV
openssl udf
keyrings

• FR 11.1: wolf/yssl builds (Non openssl builds): fips mode is supported only on
  openssl. For wolfssl/yssl (non openssl builds) only fips mode OFF will be allowed.
  
• FR 11.2: If user sets ssl fips mode ON/STRICT when openssl is not fips enabled, operation will fail.

Non-Functional Requirements

• NFR 1: We need to build fips object module for EL7 without any change in build steps or change in the source code.

./config no-asm
make
make install

• • NFR 1.1: Installed location of fips object module can not be changed. Files can be copied manually to other locations.
• NFR 2: Build openssl library using following commands:

export CFLAGS=-fPIC
./config fips --prefix=/path_installed/openssl_ins no-asm shared
make depend
make
make install

• NFR 3: library used will be:
  • openssl-fips-2.0.16
  • openssl-1.0.2l

https://www.openssl.org/source/

• NFR 4: Platform supported and tested will be: EL7
• NFR 5: Some plug-in/MySQL code may be used third party software like openldap, cyrus sasl etc. FIPS usage of such library is out of scope for this work log.
• NFR 6: replication channels, slave, group replication plugin and x server doesn't require separate ssl fips mode as they run inside MySQLD process.
• NFR 7: When ssl_fips_mode is ON weak algorithms are not allowed. Please note that ssl_fips_mode ON cant enforce usage of ssl connection or encryption of data or password.
• NFR 8 : openssl library can be build with fips object module as a shared and static library.

  • If we do a shared build of OpenSSL (./config fips shared), then the libcrypto.so that is produced contains the FIPS Object Module, and fipsld will have embedded the digest in that library.

  • If we do a static build of OpenSSL (./config fips), then the libcrypto.a that is produced does not contain the FIPS Object Module.

Later linking to an MySQL server/plug-in/clients will require fipscanister.o, -Llcrypto, and the use of fipsld to embed the digest in the MySQL server/plug-in/clients.
this is the reason we will be supporting openssl build as shared library and not as static library.

Reference links

• openssl source code @

https://www.openssl.org/source/

• openssl fips object module user guide @

https://www.openssl.org/docs/fips/UserGuide-2.0.pdf

• SecurityPolicy-2.0.16.pdf @

https://www.openssl.org/docs/fips/

• fips-140-2 document @

https://doi.org/10.6028/NIST.FIPS.140-2

Definitions
FIPS Object Module
OpenSSL itself is not validated,and never will be. Instead a carefully defined software component called the OpenSSL FIPS Object Module has been created. The Module is designed for compatibility with the OpenSSL library so products using the OpenSSL library and API can be converted to use FIPS 140-2 validated cryptography with minimal effort.

FIPS Capable openssl Library
The capable library is a standard OpenSSL distribution that is “FIPS Aware”. The “aware” library handles all the details of operation while in FIPS mode after you successfully call FIPS_mode_set(). If you don't call FIPS_mode_set(), the library will still operate as expected; but it will not be using validated cryptography

FIPS_mode_set
FIPS_mode_set() enables the FIPS mode of operation for applications that have complied with all the provisions of the OpenSSL FIPS 140-2 Security Policy. Successful execution of this function call with non-zero (ON(1)/STIRCT(2)) is the only way to enable FIPS mode. After verifying the integrity of the executable object code using the stored digest FIPS_mode_set() performs the power-up self-test. When invoked with OFF(0) FIPS_mode_set() exits FIPS mode. If the power-up self-test fails subsequent cryptographic operations are disabled.

FIPS approved encryption algorithms lists
Triple DES, AES, CMAC, CCM, RSA (for digital signatures)
, DH, DSA/DSA2, ECDSA/ECDSA2, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, and HMAC-SHA-1, HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, HMACSHA- 512.
The FIPS Object Module supports SP 800-90 and ANSI X9.31 compliant pseudorandom number generators.

Non FIPS approved encryption algorithms including
Blowfish, MD5, IDEA, RC4

FIPS mode strict, additional restriction of suite B encryption algorithms
As mentioned in the FR's main scope of the work-log is to make FIPS mode ON. ssl_fips_mode value ON and STRICT both makes fips mode to ON.
Exact behavior and allowed strict encryption algorithms are depends on openssl version used.
STRICT mode usage is futuristic in nature.
We can see more stricter behavior in openssl version openssl-1.0.2l and above.
Advanced Encryption Standard (AES) with key sizes of 128 and 256 bits. For traffic flow, AES should be used with either the Counter Mode (CTR) for low bandwidth traffic or the Galois/Counter Mode (GCM) mode of operation for high bandwidth traffic (see Block cipher modes of operation) – symmetric encryption
Elliptic Curve Digital Signature Algorithm (ECDSA) – digital signatures
Elliptic Curve Diffie–Hellman (ECDH) – key agreement
Secure Hash Algorithm 2 (SHA-256 and SHA-384) – message digest

Some sample FIPS specific errors.
FIPS_R_KEY_TOO_SHORT
FIPS_R_NON_FIPS_METHOD
MySQL server will convert error code to strings using openssl calls and return to the user.

Compiling with non fips capable openssl library
We will not compile MySQL with fips methods if openssl library doesn't support it.
fips functionality was introduced in openssl version 0.9.7.

Non fips specific openssl functions will not be called
Idea is to not call the known non fips methods wherever it is possible. Please not that not calling the non fips openssl methods are preferable as few function may not return the proper code. (as per fips module object code user guide)
Example:
in method static void my_md5_hash(unsigned char* digest, unsigned const char *buf, int len)
if (ssl_fips_mode == SSL_FIPS_MODE_OFF))
{

 MD5_Init();

} else
{

 my_message_local(ERROR_INFORMATION_LEVEL, "SSL error: FIPS mode is ON, MD5 algorithms will not be allowed");

 return;

}

Error handling for non FIPS mode openssl usage when ssl_fips_mode is ON/STRICT.
In some cases it is not possible to know the non fips mode usage statically and it is dynamic in nature.
For example TLS protocol, Resulted TLS protocol will be negotiation between MySQL server and clients.
TLS 1.0 and 1.1 uses MD5 as a PRF during key agreement.

Impacted functionalities/codes New system variable ssl_fips_mode is added for the server.
New variable ssl_fips_mode will be added for MySQL client library and clients.
Performance schema digest will now based on sha256.
New ssl parameter ssl_fips_mode in the x-plugin client.
openssl udf, key ring, AWS, oracle key vault, MySQL str function like (MD5()), LDAP uses openssl library. And when we set fips mode ON there functionality might be impacted. Like MySQL str function MD5 will return NULL string when fips mode is ON.
Openssl usage of low level API's like SHA256_Init is not allowed when FIPS mode is ON. All such calls are replaced with EVP_DigestInit_ex(ctx, EVP_sha256(), NULL);

Plugin build suggestion All the plug-ins should be using same shared system openssl library, static openssl is usage is not allowed. If static openssl library is used, fips mode will not be applicable to them.