update docs

crypto/s2n_fips.c

@@ -26,23 +26,23 @@
 
 static bool s2n_fips_mode_enabled = false;
 
-/* FIPS mode can be checked if OpenSSL was configured and built for FIPS which
- * then defines OPENSSL_FIPS.
+/* Check if the linked libcrypto has FIPS mode enabled.
  *
- * AWS-LC always defines FIPS_mode() that you can call and check what the
- * library was built with. It does not define a public OPENSSL_FIPS/AWSLC_FIPS
- * macro that we can (or need to) check here
+ * This method indicates the state of the libcrypto, NOT the state
+ * of s2n-tls and should ONLY be called during library initialization (i.e.
+ * s2n_init()). For example, if s2n-tls is using Openssl and FIPS_mode_set(1)
+ * is called after s2n_init() is called, then this method will return true
+ * while s2n_is_in_fips_mode() will return false and s2n-tls will not operate
+ * in FIPS mode.
  *
- * Safeguard with macro's, for example because Libressl doesn't define
- * FIPS_mode() by default.
+ * For AWS-LC, the FIPS_mode() method is always defined. If AWS-LC was built to
+ * support FIPS, FIPS_mode() always returns 1.
  *
- * Note: FIPS_mode() does not change the FIPS state of libcrypto. This only
- * returns the current state. Applications using s2n must call FIPS_mode_set(1)
- * prior to s2n_init.
- *
- * Note: Developers should use `s2n_is_in_fips_mode()` instead of calling this
- * directly. `s2n_is_in_fips_mode()` returns libcrypto FIPS status at library
- * initialization, ie. s2n_init().
+ * For OpenSSL, OPENSSL_FIPS is defined if the libcrypto was built to support
+ * FIPS. The FIPS_mode() method is only present if OPENSSL_FIPS is defined, and
+ * only returns 1 if FIPS_mode_set(1) was used to enable FIPS mode.
+ * Applications wanting to enable FIPS mode with OpenSSL must call
+ * FIPS_mode_set(1) prior to calling s2n_init().
  */
 bool s2n_libcrypto_is_fips(void)
 {