README
¶
Go OpenSSL bindings for FIPS compliance
The openssl package implements Go crypto primitives using OpenSSL shared libraries and cgo. When configured correctly, OpenSSL can be executed in FIPS mode, making the openssl package FIPS compliant.
The openssl package is designed to be used as a drop-in replacement for the boring package in order to facilitate integrating openssl inside a forked Go toolchain.
Disclaimer
A program directly or indirectly using this package in FIPS mode can claim it is using a FIPS-certified cryptographic module (OpenSSL), but it can't claim the program as a whole is FIPS certified without passing the certification process, nor claim it is FIPS compliant without ensuring all crypto APIs and workflows are implemented in a FIPS-compliant manner.
Background
FIPS 140-2 is a U.S. government computer security standard used to approve cryptographic modules. FIPS compliance may come up when working with U.S. government and other regulated industries.
Go FIPS compliance
The Go crypto package is not FIPS certified, and the Go team has stated that it won't be, e.g. in golang/go/issues/21734 Adam Langley says:
The status of FIPS 140 for Go itself remains "no plans, basically zero chance".
On the other hand, Google maintains a branch that uses cgo and BoringSSL to implement various crypto primitives: https://github.com/golang/go/blob/dev.boringcrypto/README.boringcrypto.md. As BoringSSL is FIPS 140-2 certified, an application using that branch is more likely to be FIPS 140-2 compliant, yet Google does not provide any liability about the suitability of this code in relation to the FIPS 140-2 standard.
Features
Multiple OpenSSL versions supported
The openssl package has support for multiple OpenSSL versions, namely 1.0.2, 1.1.0, 1.1.1 and 3.0.x.
All supported OpenSSL versions pass a small set of automatic tests that ensure they can be built and that there are no major regressions.
These tests do not validate the cryptographic correctness of the openssl package.
On top of that, the golang-fips Go fork -maintained by Red Hat- and the Microsoft Go fork, tests a subset of the supported OpenSSL versions when integrated with the Go crypto package.
These tests are much more exhaustive and validate a specific OpenSSL version can produce working applications.
Building without OpenSSL headers
The openssl package does not use any symbol from the OpenSSL headers. There is no need that have them installed to build an application which imports this library.
The CI tests in this repository verify that all the functions and constants defined in our headers match the ones in the OpenSSL headers for every supported OpenSSL version.
Portable OpenSSL
The OpenSSL bindings are implemented in such a way that the OpenSSL version available when building a program does not have to match with the OpenSSL version used when running it.
In fact, OpenSSL doesn't need to be present on the builder.
For example, using the openssl package and go build . on a Windows host with GOOS=linux can produce a program that successfully runs on Linux and uses OpenSSL.
This feature does not require any additional configuration, but it only works with OpenSSL versions known and supported by the Go toolchain that integrates the openssl package.
Limitations
- Only Unix, Unix-like and Windows platforms are supported.
- The build must set
CGO_ENABLED=1.
Acknowledgements
The work done to support FIPS compatibility mode leverages code and ideas from other open-source projects:
- All crypto stubs are a mirror of Google's dev.boringcrypto branch and the release branch ports of that branch.
- The mapping between BoringSSL and OpenSSL APIs is taken from the former Red Hat Go fork.
- The portable OpenSSL implementation is ported from Microsoft's .NET runtime cryptography module.
Code of Conduct
This project adopts the Go code of conduct: https://go.dev/conduct.
Documentation
¶
Overview ¶
Package openssl provides access to OpenSSL cryptographic functions.
Index ¶
- Constants
- func CheckLeaks()
- func CheckVersion(version string) (exists, fips bool)
- func DecryptRSANoPadding(priv *PrivateKeyRSA, ciphertext []byte) ([]byte, error)
- func DecryptRSAOAEP(h, mgfHash hash.Hash, priv *PrivateKeyRSA, ciphertext, label []byte) ([]byte, error)
- func DecryptRSAPKCS1(priv *PrivateKeyRSA, ciphertext []byte) ([]byte, error)
- func ECDH(priv *PrivateKeyECDH, pub *PublicKeyECDH) ([]byte, error)
- func EncryptRSANoPadding(pub *PublicKeyRSA, msg []byte) ([]byte, error)
- func EncryptRSAOAEP(h, mgfHash hash.Hash, pub *PublicKeyRSA, msg, label []byte) ([]byte, error)
- func EncryptRSAPKCS1(pub *PublicKeyRSA, msg []byte) ([]byte, error)
- func ExpandHKDF(h func() hash.Hash, pseudorandomKey, info []byte) (io.Reader, error)
- func ExtractHKDF(h func() hash.Hash, secret, salt []byte) ([]byte, error)
- func FIPS() bool
- func HashSignECDSA(priv *PrivateKeyECDSA, h crypto.Hash, msg []byte) ([]byte, error)
- func HashSignRSAPKCS1v15(priv *PrivateKeyRSA, h crypto.Hash, msg []byte) ([]byte, error)
- func HashVerifyECDSA(pub *PublicKeyECDSA, h crypto.Hash, msg, sig []byte) bool
- func HashVerifyRSAPKCS1v15(pub *PublicKeyRSA, h crypto.Hash, msg, sig []byte) error
- func Init(file string) error
- func MD4(p []byte) (sum [16]byte)
- func MD5(p []byte) (sum [16]byte)
- func NewAESCipher(key []byte) (cipher.Block, error)
- func NewDESCipher(key []byte) (cipher.Block, error)
- func NewGCMTLS(c cipher.Block) (cipher.AEAD, error)
- func NewGCMTLS13(c cipher.Block) (cipher.AEAD, error)
- func NewHMAC(h func() hash.Hash, key []byte) hash.Hash
- func NewMD4() hash.Hash
- func NewMD5() hash.Hash
- func NewSHA1() hash.Hash
- func NewSHA224() hash.Hash
- func NewSHA256() hash.Hash
- func NewSHA384() hash.Hash
- func NewSHA3_224() hash.Hash
- func NewSHA3_256() hash.Hash
- func NewSHA3_384() hash.Hash
- func NewSHA3_512() hash.Hash
- func NewSHA512() hash.Hash
- func NewTripleDESCipher(key []byte) (cipher.Block, error)
- func PBKDF2(password, salt []byte, iter, keyLen int, h func() hash.Hash) ([]byte, error)
- func SHA1(p []byte) (sum [20]byte)
- func SHA224(p []byte) (sum [28]byte)
- func SHA256(p []byte) (sum [32]byte)
- func SHA384(p []byte) (sum [48]byte)
- func SHA3_224(p []byte) (sum [28]byte)
- func SHA3_256(p []byte) (sum [32]byte)
- func SHA3_384(p []byte) (sum [48]byte)
- func SHA3_512(p []byte) (sum [64]byte)
- func SHA512(p []byte) (sum [64]byte)
- func SetFIPS(enabled bool) error
- func SignEd25519(priv *PrivateKeyEd25519, message []byte) (sig []byte, err error)
- func SignMarshalECDSA(priv *PrivateKeyECDSA, hash []byte) ([]byte, error)
- func SignRSAPKCS1v15(priv *PrivateKeyRSA, h crypto.Hash, hashed []byte) ([]byte, error)
- func SignRSAPSS(priv *PrivateKeyRSA, h crypto.Hash, hashed []byte, saltLen int) ([]byte, error)
- func SupportsDESCipher() bool
- func SupportsEd25519() bool
- func SupportsHKDF() bool
- func SupportsHash(h crypto.Hash) bool
- func SupportsRC4() bool
- func SupportsTLS1PRF() bool
- func SupportsTripleDESCipher() bool
- func TLS1PRF(result, secret, label, seed []byte, h func() hash.Hash) error
- func VerifyECDSA(pub *PublicKeyECDSA, hash []byte, sig []byte) bool
- func VerifyEd25519(pub *PublicKeyEd25519, message, sig []byte) error
- func VerifyRSAPKCS1v15(pub *PublicKeyRSA, h crypto.Hash, hashed, sig []byte) error
- func VerifyRSAPSS(pub *PublicKeyRSA, h crypto.Hash, hashed, sig []byte, saltLen int) error
- func VersionText() string
- type BigInt
- type PrivateKeyECDH
- type PrivateKeyECDSA
- type PrivateKeyEd25519
- type PrivateKeyRSA
- type PublicKeyECDH
- type PublicKeyECDSA
- type PublicKeyEd25519
- type PublicKeyRSA
- type RC4Cipher
Constants ¶
const RandReader = randReader(0)
Variables ¶
This section is empty.
Functions ¶
func CheckLeaks ¶
func CheckLeaks()
func CheckVersion ¶
CheckVersion checks if the OpenSSL version can be loaded and if the FIPS mode is enabled. This function can be called before Init.
func DecryptRSANoPadding ¶
func DecryptRSANoPadding(priv *PrivateKeyRSA, ciphertext []byte) ([]byte, error)
func DecryptRSAOAEP ¶
func DecryptRSAPKCS1 ¶
func DecryptRSAPKCS1(priv *PrivateKeyRSA, ciphertext []byte) ([]byte, error)
func ECDH ¶
func ECDH(priv *PrivateKeyECDH, pub *PublicKeyECDH) ([]byte, error)
func EncryptRSANoPadding ¶
func EncryptRSANoPadding(pub *PublicKeyRSA, msg []byte) ([]byte, error)
func EncryptRSAOAEP ¶
func EncryptRSAPKCS1 ¶
func EncryptRSAPKCS1(pub *PublicKeyRSA, msg []byte) ([]byte, error)
func ExpandHKDF ¶
func FIPS ¶
func FIPS() bool
FIPS returns true if OpenSSL is running in FIPS mode, else returns false.
func HashSignECDSA ¶
func HashSignRSAPKCS1v15 ¶
func HashVerifyECDSA ¶
func HashVerifyECDSA(pub *PublicKeyECDSA, h crypto.Hash, msg, sig []byte) bool
func HashVerifyRSAPKCS1v15 ¶
func HashVerifyRSAPKCS1v15(pub *PublicKeyRSA, h crypto.Hash, msg, sig []byte) error
func Init ¶
Init loads and initializes OpenSSL from the shared library at path. It must be called before any other OpenSSL call, except CheckVersion.
Only the first call to Init is effective. Subsequent calls will return the same error result as the one from the first call.
The file is passed to dlopen() verbatim to load the OpenSSL shared library. For example, `file=libcrypto.so.1.1.1k-fips` makes Init look for the shared library libcrypto.so.1.1.1k-fips.
func NewGCMTLS ¶
NewGCMTLS returns a GCM cipher specific to TLS and should not be used for non-TLS purposes.
func NewGCMTLS13 ¶
NewGCMTLS13 returns a GCM cipher specific to TLS 1.3 and should not be used for non-TLS purposes.
func NewHMAC ¶
NewHMAC returns a new HMAC using OpenSSL. The function h must return a hash implemented by OpenSSL (for example, h could be openssl.NewSHA256). If h is not recognized, NewHMAC returns nil.
func NewMD4 ¶
NewMD4 returns a new MD4 hash. The returned hash doesn't implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler.
func SetFIPS ¶
SetFIPS enables or disables FIPS mode.
For OpenSSL 3, the `fips` provider is loaded if enabled is true, else the `default` provider is loaded.
func SignEd25519 ¶
func SignEd25519(priv *PrivateKeyEd25519, message []byte) (sig []byte, err error)
SignEd25519 signs the message with priv and returns a signature.
func SignMarshalECDSA ¶
func SignMarshalECDSA(priv *PrivateKeyECDSA, hash []byte) ([]byte, error)
func SignRSAPKCS1v15 ¶
func SignRSAPSS ¶
func SupportsDESCipher ¶
func SupportsDESCipher() bool
SupportsDESCipher returns true if NewDESCipher is supported, which uses ECB mode. If CBC is also supported, then the returned cipher.Block will also implement NewCBCEncrypter and NewCBCDecrypter.
func SupportsEd25519 ¶
func SupportsEd25519() bool
SupportsEd25519 returns true if the current OpenSSL version supports GenerateKeyEd25519, NewKeyFromSeedEd25519, SignEd25519 and VerifyEd25519.
func SupportsHKDF ¶
func SupportsHKDF() bool
func SupportsHash ¶
SupportsHash returns true if a hash.Hash implementation is supported for h.
func SupportsTLS1PRF ¶
func SupportsTLS1PRF() bool
func SupportsTripleDESCipher ¶
func SupportsTripleDESCipher() bool
SupportsTripleDESCipher returns true if NewTripleDESCipher is supported, which uses ECB mode. If CBC is also supported, then the returned cipher.Block will also implement NewCBCEncrypter and NewCBCDecrypter.
func TLS1PRF ¶
TLS1PRF implements the TLS 1.0/1.1 pseudo-random function if h is nil, else it implements the TLS 1.2 pseudo-random function. The pseudo-random number will be written to result and will be of length len(result).
func VerifyECDSA ¶
func VerifyECDSA(pub *PublicKeyECDSA, hash []byte, sig []byte) bool
func VerifyEd25519 ¶
func VerifyEd25519(pub *PublicKeyEd25519, message, sig []byte) error
VerifyEd25519 reports whether sig is a valid signature of message by pub.
func VerifyRSAPKCS1v15 ¶
func VerifyRSAPKCS1v15(pub *PublicKeyRSA, h crypto.Hash, hashed, sig []byte) error
func VerifyRSAPSS ¶
func VersionText ¶
func VersionText() string
VersionText returns the version text of the OpenSSL currently loaded.
Types ¶
type BigInt ¶
type BigInt []uint
A BigInt is the raw words from a BigInt. This definition allows us to avoid importing math/big. Conversion between BigInt and *big.Int is in openssl/bbig.
func GenerateKeyECDSA ¶
func GenerateKeyRSA ¶
type PrivateKeyECDH ¶
type PrivateKeyECDH struct {
// contains filtered or unexported fields
}
func GenerateKeyECDH ¶
func GenerateKeyECDH(curve string) (*PrivateKeyECDH, []byte, error)
func NewPrivateKeyECDH ¶
func NewPrivateKeyECDH(curve string, bytes []byte) (*PrivateKeyECDH, error)
func (*PrivateKeyECDH) PublicKey ¶
func (k *PrivateKeyECDH) PublicKey() (*PublicKeyECDH, error)
type PrivateKeyECDSA ¶
type PrivateKeyECDSA struct {
// contains filtered or unexported fields
}
func NewPrivateKeyECDSA ¶
func NewPrivateKeyECDSA(curve string, X, Y, D BigInt) (*PrivateKeyECDSA, error)
type PrivateKeyEd25519 ¶
type PrivateKeyEd25519 struct {
// contains filtered or unexported fields
}
func GenerateKeyEd25519 ¶
func GenerateKeyEd25519() (*PrivateKeyEd25519, error)
GenerateKeyEd25519 generates a private key.
func NewPrivateKeyEd25119 ¶
func NewPrivateKeyEd25119(priv []byte) (*PrivateKeyEd25519, error)
func NewPrivateKeyEd25519FromSeed ¶
func NewPrivateKeyEd25519FromSeed(seed []byte) (*PrivateKeyEd25519, error)
NewPrivateKeyEd25519FromSeed calculates a private key from a seed. It will panic if len(seed) is not [SeedSize]. RFC 8032's private keys correspond to seeds in this package.
func (*PrivateKeyEd25519) Bytes ¶
func (k *PrivateKeyEd25519) Bytes() ([]byte, error)
func (*PrivateKeyEd25519) Public ¶
func (k *PrivateKeyEd25519) Public() (*PublicKeyEd25519, error)
type PrivateKeyRSA ¶
type PrivateKeyRSA struct {
// contains filtered or unexported fields
}
func NewPrivateKeyRSA ¶
func NewPrivateKeyRSA(N, E, D, P, Q, Dp, Dq, Qinv BigInt) (*PrivateKeyRSA, error)
type PublicKeyECDH ¶
type PublicKeyECDH struct {
// contains filtered or unexported fields
}
func NewPublicKeyECDH ¶
func NewPublicKeyECDH(curve string, bytes []byte) (*PublicKeyECDH, error)
func (*PublicKeyECDH) Bytes ¶
func (k *PublicKeyECDH) Bytes() []byte
type PublicKeyECDSA ¶
type PublicKeyECDSA struct {
// contains filtered or unexported fields
}
func NewPublicKeyECDSA ¶
func NewPublicKeyECDSA(curve string, X, Y BigInt) (*PublicKeyECDSA, error)
type PublicKeyEd25519 ¶
type PublicKeyEd25519 struct {
// contains filtered or unexported fields
}
func NewPublicKeyEd25119 ¶
func NewPublicKeyEd25119(pub []byte) (*PublicKeyEd25519, error)
func (*PublicKeyEd25519) Bytes ¶
func (k *PublicKeyEd25519) Bytes() ([]byte, error)
type PublicKeyRSA ¶
type PublicKeyRSA struct {
// contains filtered or unexported fields
}
func NewPublicKeyRSA ¶
func NewPublicKeyRSA(N, E BigInt) (*PublicKeyRSA, error)
type RC4Cipher ¶
type RC4Cipher struct {
// contains filtered or unexported fields
}
A RC4Cipher is an instance of RC4 using a particular key.
func NewRC4Cipher ¶
NewRC4Cipher creates and returns a new Cipher.
func (*RC4Cipher) Reset ¶
func (c *RC4Cipher) Reset()
Reset zeros the key data and makes the Cipher unusable.
func (*RC4Cipher) XORKeyStream ¶
XORKeyStream sets dst to the result of XORing src with the key stream. Dst and src must overlap entirely or not at all.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gentestvectors
gentestvectors emits cryptographic test vectors using the Go standard library cryptographic routines to test the OpenSSL bindings.
|
gentestvectors emits cryptographic test vectors using the Go standard library cryptographic routines to test the OpenSSL bindings. |