From a6cb2aa4f7a524e48cf3cbdd9bcdc2b73ce40c7f Mon Sep 17 00:00:00 2001 From: qmuntal Date: Tue, 14 Jan 2025 09:07:20 +0100 Subject: [PATCH] improve func docs --- openssl.go | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/openssl.go b/openssl.go index 7330261..ec39bf1 100644 --- a/openssl.go +++ b/openssl.go @@ -135,10 +135,19 @@ func FIPS() bool { } // FIPSCapable returns true if the provider used by default matches the `fips=yes` query. -// Note that this function can return true even if [FIPS] returns false, because [FIPS] also -// checks whether the default properties contain `fips=yes`. -// It will always return true for OpenSSL 3 if [FIPS] returns true. -// When using OpenSSL 1, this function always returns the same value as [FIPS]. +// It is useful for checking whether OpenSSL is capable of running in FIPS mode regardless +// of whether FIPS mode is explicitly enabled. For example, Azure Linux 3 doesn't set the +// `fips=yes` query in the default properties, but sets the default provider to be SCOSSL, +// which is FIPS-capable. +// +// Considerations: +// - Multiple calls to FIPSCapable can return different values if [SetFIPS] is called in between. +// - Can return true even if [FIPS] returns false, because [FIPS] also checks whether +// the default properties contain `fips=yes`. +// - When using OpenSSL 3, will always return true if [FIPS] returns true. +// - When using OpenSSL 1, Will always return the same value as [FIPS]. +// - OpenSSL 3 doesn't provide a way to know if a provider is FIPS-capable. This function uses +// some heuristics that should be treated as an implementation detail that may change in the future. func FIPSCapable() bool { if FIPS() { return true