The Go programming language has always shipped with “batteries included,” so to speak. The Go standard library is comprehensive, containing most of what a developer needs to be productive out-of-the-box. Included in this standard library are several cryptographic routines, as part of the crypto standard library package. For most Go programmers and operators, these routines are all you really need.
However, the standard library does not contain an implementation for every known cryptographic algorithm. For example, the popular bcrypt password hashing algorithm is not included in the standard library, but instead provided by the x/crypto package x/crypto/bcrypt.
Go x/crypto package
As a Go programmer, you are likely familiar with the x packages; according to its own documentation, these are repositories that are part of the Go project but outside the main Go tree. They are developed under looser compatibility requirements than the Go core standard library packages. These packages bridge the gap between what is available in the standard library and other common libraries that are useful to the Go community. They are developed and maintained by the Go team, but do not ship with the standard Go toolchain distribution.
Go FIPS enhancements in RHEL
The Go toolchain that is shipped in Red Hat Enterprise Linux (RHEL) via the Go Toolset package contains a few modifications to enable the Go standard library cryptography APIs to be FIPS compliant. This is achieved by linking against the OpenSSL cryptography library that is also shipped as part of the Red Hat Enterprise Linux distribution. The OpenSSL cryptography library is FIPS certified, with the usage from within our Go toolchain engineered in a way that makes the Go standard library call into a FIPS certified cryptography library.
Our downstream work to have Go crypto APIs call into OpenSSL is based on preexisting upstream work which similarly modified the Go standard library crypto APIs to call into BoringSSL for similar reasons. We’ve built upon that work and modified it to instead call into OpenSSL, which is already packaged and certified on RHEL.
Within RHEL the FIPS enhancements are limited to the standard library. We do not ship FIPS compliant versions of any x/crypto algorithms. This means that any program using any code from x/crypto within a FIPS environment may be inadvertently breaking compliance. Typically this isn’t an issue as most of the widely used crypto algorithms are already included in the standard library.
However, periodically we receive requests from customers to support non standard library implementations found with the x/crypto package. We do not take on anything from outside the standard library because replacing an x/crypto (or any other non-standard library package) is significantly easier. The rest of this post will focus on how you can implement your own OpenSSL backed crypto APIs outside of the standard library.
Implementing other crypto algorithms
For any non-standard library cryptographic routine you would like to implement and incorporate into your program, you can create your own CGO bindings and leverage our Go OpenSSL binding library for a few helpers. Using the helpers provided by that library will ensure that your modifications behave correctly on RHEL systems, in alignment with the modified standard library cryptography, meaning that the library will only use the OpenSSL backed version when FIPS is required.
Starting with a program like the following:
package main
import (
"fmt"
"github.com/golang-fips/openssl/v2"
"golang.org/x/crypto/argon2"
)
func init() {
openssl.Init("")
}
func main() {
var (
threads = uint8(2)
iter = uint32(3)
memcost = uint32(65536)
keylen = uint32(128)
password = []byte("1234567890")
salt = []byte("saltsalt")
)
fmt.Println(argon2.IDKey(password, salt, iter, memcost, threads, keylen))
}If you wanted to roll your own version of the argon2 algorithm, you could download (or fork and publish) golang.org/x/crypto and modify the go.mod file of your local program to use your fork, like so:
…
replace golang.org/x/crypto => your/fork/of/x/crypto
…This step is really only necessary if you want to modify a program you may not have full control over in the least invasive way possible. Then, we apply the following modifications to our copy of x/crypto to call into OpenSSL in FIPS mode when using the argon2.IDKey algorithm:
diff --git a/argon2/argon2.go b/argon2/argon2.go
index 29f0a2d..8ce7b2b 100644
--- a/argon2/argon2.go
+++ b/argon2/argon2.go
@@ -34,10 +34,71 @@
// [2] https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-9.3
package argon2
+/*
+#cgo LDFLAGS: -lcrypto
+#include <string.h> // strlen
+#include <openssl/core_names.h> // OSSL_KDF_*
+#include <openssl/params.h> // OSSL_PARAM_*
+#include <openssl/thread.h> // OSSL_set_max_threads
+#include <openssl/kdf.h> // EVP_KDF_*
+
+// argon2 params, please refer to RFC9106 for recommended defaults
+int argon2_id_key(char *pwd, char *salt, uint32_t iter, uint32_t threads, uint32_t memcost, size_t outlen, unsigned char *result)
+{
+ int retval = 1;
+
+ EVP_KDF *kdf = NULL;
+ EVP_KDF_CTX *kctx = NULL;
+ OSSL_PARAM params[7], *p = params;
+
+ // derive result
+ if (outlen > 3096)
+ return retval;
+
+ // required if threads > 1
+ if (OSSL_set_max_threads(NULL, threads) != 1)
+ goto fail;
+
+ p = params;
+ *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &threads);
+ *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES,
+ &threads);
+ *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST,
+ &memcost);
+ *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ITER,
+ &iter);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
+ salt,
+ strlen((const char *)salt));
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
+ pwd,
+ strlen((const char *)pwd));
+ *p++ = OSSL_PARAM_construct_end();
+
+ if ((kdf = EVP_KDF_fetch(NULL, "ARGON2D", NULL)) == NULL)
+ goto fail;
+ if ((kctx = EVP_KDF_CTX_new(kdf)) == NULL)
+ goto fail;
+ if (EVP_KDF_derive(kctx, &result[0], outlen, params) != 1)
+ goto fail;
+
+ // printf("Output = %s\n", OPENSSL_buf2hexstr(result, outlen));
+ retval = 0;
+
+fail:
+ EVP_KDF_free(kdf);
+ EVP_KDF_CTX_free(kctx);
+ OSSL_set_max_threads(NULL, 0);
+
+ return retval;
+}
+*/
+import "C"
import (
"encoding/binary"
"sync"
+ "github.com/golang-fips/openssl/v2"
"golang.org/x/crypto/blake2b"
)
@@ -94,6 +155,12 @@ func Key(password, salt []byte, time, memory uint32, threads uint8, keyLen uint3
// increased as memory latency and CPU parallelism increases. Remember to get a
// good random salt.
func IDKey(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte {
+ if openssl.FIPS() {
+ println("using cgo")
+ result := make([]byte, keyLen)
+ C.argon2_id_key(C.CString(string(password)), C.CString(string(salt)), C.uint32_t(time), C.uint32_t(threads), C.uint32_t(memory), C.size_t(keyLen), (*C.uchar)(&result[0]))
+ return result
+ }
return deriveKey(argon2id, password, salt, nil, nil, time, memory, threads, keyLen)
}
diff --git a/go.mod b/go.mod
index d3527d4..e8298bd 100644
--- a/go.mod
+++ b/go.mod
@@ -8,4 +8,6 @@ require (
golang.org/x/term v0.24.0
)
+require github.com/golang-fips/openssl/v2 v2.0.3
+
require golang.org/x/text v0.18.0 // indirect
diff --git a/go.sum b/go.sum
index b347167..16b1ac8 100644
--- a/go.sum
+++ b/go.sum
@@ -1,3 +1,5 @@
+github.com/golang-fips/openssl/v2 v2.0.3 h1:9+J2R0BQio6Jz8+dPZf/0ylISByl0gZWjTEKm+J+y7Y=
+github.com/golang-fips/openssl/v2 v2.0.3/go.mod h1:7tuBqX2Zov8Yq5mJ2yzlKhpnxOnWyEzi38AzeWRuQdg=
golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
golang.org/x/sys v0.25.0 h1:r+8e+loiHxRqhXVl6ML1nO3l1+oFoWbnlu2Ehimmi34=(Note that while this specific example uses argon2, this algorithm is not actually FIPS certified as of FIPS 140-3; it is just shown as an example.)
Summary
In this post I’ve shared an example of modifying a non-standard library cryptography operation to call into OpenSSL conditionally based on system FIPS requirements. These types of modifications can integrate nicely with programs compiled using the RHEL toolchain, which already applies these types of changes in the standard library cryptography implementation.
Finally, we are always willing to accept community contributions to the golang-fips/openssl repository implementing more FIPS algorithms from the x/crypto back end, which can then be easily integrated into user code in the same way.
