openssl

package module
v2.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 24, 2024 License: MIT Imports: 14 Imported by: 1

README

Go OpenSSL bindings for FIPS compliance

Go Reference

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.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

View Source 
const RandReader = randReader(0)

Variables

This section is empty.

Functions

func CheckLeaks 

func CheckLeaks()

func CheckVersion 

func CheckVersion(version string) (exists, fips bool)

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 DecryptRSAOAEP(h, mgfHash hash.Hash, priv *PrivateKeyRSA, ciphertext, label []byte) ([]byte, error)

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 EncryptRSAOAEP(h, mgfHash hash.Hash, pub *PublicKeyRSA, msg, label []byte) ([]byte, error)

func EncryptRSAPKCS1 

func EncryptRSAPKCS1(pub *PublicKeyRSA, msg []byte) ([]byte, error)

func ExpandHKDF 

func ExpandHKDF(h func() hash.Hash, pseudorandomKey, info []byte) (io.Reader, error)

func ExtractHKDF 

func ExtractHKDF(h func() hash.Hash, secret, salt []byte) ([]byte, error)

func FIPS 

func FIPS() bool

FIPS returns true if OpenSSL is running in FIPS mode, else returns false.

func HashSignECDSA 

func HashSignECDSA(priv *PrivateKeyECDSA, h crypto.Hash, msg []byte) ([]byte, error)

func HashSignRSAPKCS1v15 

func HashSignRSAPKCS1v15(priv *PrivateKeyRSA, h crypto.Hash, msg []byte) ([]byte, error)

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 

func Init(file string) error

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 MD4 

func MD4(p []byte) (sum [16]byte)

func MD5 

func MD5(p []byte) (sum [16]byte)

func NewAESCipher 

func NewAESCipher(key []byte) (cipher.Block, error)

func NewDESCipher 

func NewDESCipher(key []byte) (cipher.Block, error)

func NewGCMTLS 

func NewGCMTLS(c cipher.Block) (cipher.AEAD, error)

NewGCMTLS returns a GCM cipher specific to TLS and should not be used for non-TLS purposes.

func NewGCMTLS13 

func NewGCMTLS13(c cipher.Block) (cipher.AEAD, error)

NewGCMTLS13 returns a GCM cipher specific to TLS 1.3 and should not be used for non-TLS purposes.

func NewHMAC 

func NewHMAC(h func() hash.Hash, key []byte) hash.Hash

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 

func NewMD4() hash.Hash

NewMD4 returns a new MD4 hash. The returned hash doesn't implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler.

func NewMD5 

func NewMD5() hash.Hash

NewMD5 returns a new MD5 hash.

func NewSHA1 

func NewSHA1() hash.Hash

NewSHA1 returns a new SHA1 hash.

func NewSHA224 

func NewSHA224() hash.Hash

NewSHA224 returns a new SHA224 hash.

func NewSHA256 

func NewSHA256() hash.Hash

NewSHA256 returns a new SHA256 hash.

func NewSHA384 

func NewSHA384() hash.Hash

NewSHA384 returns a new SHA384 hash.

func NewSHA3_224 

func NewSHA3_224() hash.Hash

NewSHA3_224 returns a new SHA3-224 hash.

func NewSHA3_256 

func NewSHA3_256() hash.Hash

NewSHA3_256 returns a new SHA3-256 hash.

func NewSHA3_384 

func NewSHA3_384() hash.Hash

NewSHA3_384 returns a new SHA3-384 hash.

func NewSHA3_512 

func NewSHA3_512() hash.Hash

NewSHA3_512 returns a new SHA3-512 hash.

func NewSHA512 

func NewSHA512() hash.Hash

NewSHA512 returns a new SHA512 hash.

func NewTripleDESCipher 

func NewTripleDESCipher(key []byte) (cipher.Block, error)

func PBKDF2 

func PBKDF2(password, salt []byte, iter, keyLen int, h func() hash.Hash) ([]byte, error)

func SHA1 

func SHA1(p []byte) (sum [20]byte)

func SHA224 

func SHA224(p []byte) (sum [28]byte)

func SHA256 

func SHA256(p []byte) (sum [32]byte)

func SHA384 

func SHA384(p []byte) (sum [48]byte)

func SHA3_224 

func SHA3_224(p []byte) (sum [28]byte)

func SHA3_256 

func SHA3_256(p []byte) (sum [32]byte)

func SHA3_384 

func SHA3_384(p []byte) (sum [48]byte)

func SHA3_512 

func SHA3_512(p []byte) (sum [64]byte)

func SHA512 

func SHA512(p []byte) (sum [64]byte)

func SetFIPS 

func SetFIPS(enabled bool) error

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 SignRSAPKCS1v15(priv *PrivateKeyRSA, h crypto.Hash, hashed []byte) ([]byte, error)

func SignRSAPSS 

func SignRSAPSS(priv *PrivateKeyRSA, h crypto.Hash, hashed []byte, saltLen int) ([]byte, error)

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 

func SupportsHash(h crypto.Hash) bool

SupportsHash returns true if a hash.Hash implementation is supported for h.

func SupportsRC4 

func SupportsRC4() bool

SupportsRC4 returns true if NewRC4Cipher is supported.

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 

func TLS1PRF(result, secret, label, seed []byte, h func() hash.Hash) error

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 VerifyRSAPSS(pub *PublicKeyRSA, h crypto.Hash, hashed, sig []byte, saltLen int) error

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 GenerateKeyECDSA(curve string) (X, Y, D BigInt, err error)

func GenerateKeyRSA 

func GenerateKeyRSA(bits int) (N, E, D, P, Q, Dp, Dq, Qinv BigInt, err error)

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 

func NewRC4Cipher(key []byte) (*RC4Cipher, error)

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 

func (c *RC4Cipher) XORKeyStream(dst, src []byte)

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

View all Source files

Directories

Path Synopsis
cmd
checkheader
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.