doc/config: Add notes about recommended usage to sample configs and man pages

Add notes about not trying to accelerate algorithms that are already
accelerated by OpenSSL itself using CPACF.

Also add a note about disabling FIPS mode because the provider is not FIPS
certified.

Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>

Author: ifranzki

src/engine/doc/ibmca.man

@@ -47,10 +47,16 @@ If ALL is not used, the default_algorithms consists of a comma separated list
 of
 .I mechanisms
 :
-.B CIPHERS | DIGESTS | RSA | DH | DSA.
+.B CIPHERS | DIGESTS | RSA | DH | DSA | EC | PKEY_CRYPTO | RAND
 .PP
 Only all CIPHERS and/or DIGESTS can be
 de/activated. Algorithms like AES can not be de/activated independently.
+.PP
+.B Note: 
+Algorithms denoted by CIPHERS, DIGESTS, EC (since IBM z15 for certain curves),
+and PKEY are already accelerated by OpenSSL itself using CPACF.
+Therefore, do not accelerate them using the IBMCA engine. This would actually
+make them slower.
 .SS Control Command
 IBMCA does support one optional control command:
 .PP

src/engine/ibmca-engine-opensslconfig.in

@@ -95,6 +95,16 @@ init = 1
 # with "ALL" denoting the same as all of them in a comma separated
 # list.
 #
+# Note: Algorithms denoted by CIPHERS, DIGESTS, EC (since IBM z15 for certain
+# curves), and PKEY are already accelerated by OpenSSL itself using CPACF.
+# Therefore, do not accelerate them using the IBMCA engine. This would actually
+# make them slower.
+#
+# Moreover, ibmca's CIPHER and DIGEST implementations do not
+# support the processing of messages in arbitrary chunk sizes.
+# All chunks, except the final one, are required to be a multiple
+# of the primitive's block size.
+#
 # RSA
 # - RSA encrypt, decrypt, sign and verify, key lengths 512-4096
 #
@@ -128,8 +138,8 @@ init = 1
 #
 # PKEY_CRYPTO
 # - X25519, X448, ED25519, ED448
-#default_algorithms = ALL
-default_algorithms = PKEY_CRYPTO,RAND,RSA,DH,DSA,EC
+
+default_algorithms = RSA,DH,DSA,RAND
 |;
     close($ih);
     close($oh);

src/engine/openssl.cnf.sample

@@ -30,10 +30,10 @@ init = 1
 # with "ALL" denoting the same as all of them in a comma separated
 # list.
 #
-# Note that IBM Z hardware support for the symmetric crypto
-# primitives (CIPHERS, DIGESTS) most likely comes natively with your
-# OpenSSL version. Therefore, this sample configuration excludes them
-# from the default_algorithms list below.
+# Note: Algorithms denoted by CIPHERS, DIGESTS, EC (since IBM z15 for certain
+# curves), and PKEY are already accelerated by OpenSSL itself using CPACF.
+# Therefore, do not accelerate them using the IBMCA engine. This would actually
+# make them slower.
 #
 # Moreover, ibmca's CIPHER and DIGEST implementations do not
 # support the processing of messages in arbitrary chunk sizes.

src/provider/doc/ibmca-provider.man

@@ -84,6 +84,11 @@ of
 .I mechanisms
 : \fBRSA\fP | \fBEC\fP | \fBDH\fP.
 If this option is not specified, \fBALL\fP is the default.
+.PP
+.B Note:
+Depending on the hardware level (IBM z15), EC is already accelerated implicitly
+by OpenSSL for certain curves. Therefore, do not accelerate EC using the IBMCA
+provider if you are on an IBM z15 or later. This would actually make it slower.
 .RE
 .PP
 .IP "debug = yes | no | stderr"

src/provider/ibmca-provider-opensslconfig

@@ -120,10 +120,18 @@ activate = 1
 identity = ibmca
 module = ibmca-provider.so
 activate = 1
-#debug = yes
-#fips = yes
-#algorithms = RSA,EC,DH
-algorithms = ALL
+# Note: Disable the FIPS mode of the IBMCA provider by setting fips=no in the 
+# provider configuration. The IBMCA provider is currently not FIPS-certified.
+# It does not perform any FIPS self-tests itself nor an integrity check which
+# would be required to be FIPS-certified. It is only checked whether libica
+# library has successfully performed its self-tests and integrity checks when
+# FIPS mode is enabled.
+fips = no
+# Note: Depending on the hardware level (IBM z15), EC is already accelerated
+# implicitly by OpenSSL for certain curves. Therefore, do not accelerate EC 
+# using the IBMCA provider if you are on an IBM z15 or later. This would 
+# actually make it slower.
+algorithms = RSA,EC,DH
 #fallback-properties = provider=default
 |;
 

src/provider/openssl.cnf.provider.sample

@@ -24,10 +24,18 @@ activate = 1
 identity = ibmca
 module = ibmca-provider.so
 activate = 1
-#debug = yes
-#fips = yes
-#algorithms = RSA,EC,DH
-algorithms = ALL
+# Note: Disable the FIPS mode of the IBMCA provider by setting fips=no in the 
+# provider configuration. The IBMCA provider is currently not FIPS-certified.
+# It does not perform any FIPS self-tests itself nor an integrity check which
+# would be required to be FIPS-certified. It is only checked whether libica
+# library has successfully performed its self-tests and integrity checks when
+# FIPS mode is enabled.
+fips = no
+# Note: Depending on the hardware level (IBM z15), EC is already accelerated
+# implicitly by OpenSSL for certain curves. Therefore, do not accelerate EC 
+# using the IBMCA provider if you are on an IBM z15 or later. This would 
+# actually make it slower.
+algorithms = RSA,EC,DH
 #fallback-properties = provider=default
 
 [evp_properties]