boring

README

We have been working inside Google on a fork of Go that uses BoringCrypto (the core of BoringSSL) for various crypto primitives, in furtherance of some work related to FIPS 140. We have heard that some external users of Go would be interested in this code as well, so we have published this code here in the main Go repository behind the setting GOEXPERIMENT=boringcrypto.

Use of GOEXPERIMENT=boringcrypto outside Google is unsupported. This mode is not part of the Go 1 compatibility rules, and it may change incompatibly or break in other ways at any time.

To be clear, we are not making any statements or representations about the suitability of this code in relation to the FIPS 140 standard. Interested users will have to evaluate for themselves whether the code is useful for their own purposes.

---

This directory holds the core of the BoringCrypto implementation as well as the build scripts for the module itself: syso/*.syso.

syso/goboringcrypto_linux_amd64.syso is built with:

GOARCH=amd64 ./build.sh

syso/goboringcrypto_linux_arm64.syso is built with:

GOARCH=arm64 ./build.sh

Both run on an x86 Debian Linux system using Docker. For the arm64 build to run on an x86 system, you need

apt-get install qemu-user-static qemu-binfmt-support

to allow the x86 kernel to run arm64 binaries via QEMU.

See build.sh for more details about the build.

Documentation

Overview

Package boring provides access to BoringCrypto implementation functions. Check the constant Enabled to find out whether BoringCrypto is available. If BoringCrypto is not available, the functions in this package all panic.

Index

• Constants
• 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(*PrivateKeyECDH, *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 NewAESCipher(key []byte) (cipher.Block, error)
• func NewGCMTLS(cipher.Block) (cipher.AEAD, error)
• func NewHMAC(h func() hash.Hash, key []byte) hash.Hash
• func NewSHA1() hash.Hash
• func NewSHA224() hash.Hash
• func NewSHA256() hash.Hash
• func NewSHA384() hash.Hash
• func NewSHA512() hash.Hash
• func SHA1([]byte) [20]byte
• func SHA224([]byte) [28]byte
• func SHA256([]byte) [32]byte
• func SHA384([]byte) [48]byte
• func SHA512([]byte) [64]byte
• 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 Unreachable()
• func UnreachableExceptTests()
• func VerifyECDSA(pub *PublicKeyECDSA, hash []byte, sig []byte) bool
• func VerifyRSAPKCS1v15(pub *PublicKeyRSA, h crypto.Hash, hashed, sig []byte) error
• func VerifyRSAPSS(pub *PublicKeyRSA, h crypto.Hash, hashed, sig []byte, saltLen int) error
• type BigInt
  • func GenerateKeyECDSA(curve string) (X, Y, D BigInt, err error)
  • func GenerateKeyRSA(bits int) (N, E, D, P, Q, Dp, Dq, Qinv BigInt, err error)
• type PrivateKeyECDH
  • func GenerateKeyECDH(string) (*PrivateKeyECDH, []byte, error)
  • func NewPrivateKeyECDH(string, []byte) (*PrivateKeyECDH, error)
  • func (*PrivateKeyECDH) PublicKey() (*PublicKeyECDH, error)
• type PrivateKeyECDSA
  • func NewPrivateKeyECDSA(curve string, X, Y, D BigInt) (*PrivateKeyECDSA, error)
• type PrivateKeyRSA
  • func NewPrivateKeyRSA(N, E, D, P, Q, Dp, Dq, Qinv BigInt) (*PrivateKeyRSA, error)
• type PublicKeyECDH
  • func NewPublicKeyECDH(string, []byte) (*PublicKeyECDH, error)
  • func (*PublicKeyECDH) Bytes() []byte
• type PublicKeyECDSA
  • func NewPublicKeyECDSA(curve string, X, Y BigInt) (*PublicKeyECDSA, error)
• type PublicKeyRSA
  • func NewPublicKeyRSA(N, E BigInt) (*PublicKeyRSA, error)

Constants

const Enabled = available

Enabled reports whether BoringCrypto is available. When enabled is false, all functions in this package panic.

BoringCrypto is only available on linux/amd64 systems.

const RandReader = randReader(0)

Functions

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(*PrivateKeyECDH, *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 NewAESCipher

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

func NewGCMTLS

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

func NewHMAC

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

func NewSHA1

func NewSHA1() hash.Hash

func NewSHA224

func NewSHA224() hash.Hash

func NewSHA256

func NewSHA256() hash.Hash

func NewSHA384

func NewSHA384() hash.Hash

func NewSHA512

func NewSHA512() hash.Hash

func SHA1

func SHA1([]byte) [20]byte

func SHA224

func SHA224([]byte) [28]byte

func SHA256

func SHA256([]byte) [32]byte

func SHA384

func SHA384([]byte) [48]byte

func SHA512

func SHA512([]byte) [64]byte

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 Unreachable

func Unreachable()

Unreachable marks code that should be unreachable when BoringCrypto is in use. It is a no-op without BoringCrypto.

func UnreachableExceptTests

func UnreachableExceptTests()

UnreachableExceptTests marks code that should be unreachable when BoringCrypto is in use. It is a no-op without BoringCrypto.

func VerifyECDSA

func VerifyECDSA(pub *PublicKeyECDSA, hash []byte, sig []byte) bool

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

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 crypto/internal/boring/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{}

func GenerateKeyECDH

func GenerateKeyECDH(string) (*PrivateKeyECDH, []byte, error)

func NewPrivateKeyECDH

func NewPrivateKeyECDH(string, []byte) (*PrivateKeyECDH, error)

func (*PrivateKeyECDH) PublicKey

func (*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 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{}

func NewPublicKeyECDH

func NewPublicKeyECDH(string, []byte) (*PublicKeyECDH, error)

func (*PublicKeyECDH) Bytes

func (*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 PublicKeyRSA

type PublicKeyRSA struct {
	// contains filtered or unexported fields
}

func NewPublicKeyRSA

func NewPublicKeyRSA(N, E BigInt) (*PublicKeyRSA, error)