fips.go

     1  // Copyright 2024 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package rsa
     6  
     7  import (
     8  	"crypto"
     9  	"crypto/internal/boring"
    10  	"crypto/internal/fips140/rsa"
    11  	"crypto/internal/fips140hash"
    12  	"crypto/internal/fips140only"
    13  	"crypto/internal/rand"
    14  	"errors"
    15  	"hash"
    16  	"io"
    17  )
    18  
    19  const (
    20  	// PSSSaltLengthAuto causes the salt in a PSS signature to be as large
    21  	// as possible when signing, and to be auto-detected when verifying.
    22  	//
    23  	// When signing in FIPS 140-3 mode, the salt length is capped at the length
    24  	// of the hash function used in the signature.
    25  	PSSSaltLengthAuto = 0
    26  	// PSSSaltLengthEqualsHash causes the salt length to equal the length
    27  	// of the hash used in the signature.
    28  	PSSSaltLengthEqualsHash = -1
    29  )
    30  
    31  // PSSOptions contains options for creating and verifying PSS signatures.
    32  type PSSOptions struct {
    33  	// SaltLength controls the length of the salt used in the PSS signature. It
    34  	// can either be a positive number of bytes, or one of the special
    35  	// PSSSaltLength constants.
    36  	SaltLength int
    37  
    38  	// Hash is the hash function used to generate the message digest. If not
    39  	// zero, it overrides the hash function passed to SignPSS. It's required
    40  	// when using PrivateKey.Sign.
    41  	Hash crypto.Hash
    42  }
    43  
    44  // HashFunc returns opts.Hash so that [PSSOptions] implements [crypto.SignerOpts].
    45  func (opts *PSSOptions) HashFunc() crypto.Hash {
    46  	return opts.Hash
    47  }
    48  
    49  func (opts *PSSOptions) saltLength() int {
    50  	if opts == nil {
    51  		return PSSSaltLengthAuto
    52  	}
    53  	return opts.SaltLength
    54  }
    55  
    56  // SignPSS calculates the signature of digest using PSS.
    57  //
    58  // digest must be the result of hashing the input message using the given hash
    59  // function. The opts argument may be nil, in which case sensible defaults are
    60  // used. If opts.Hash is set, it overrides hash.
    61  //
    62  // The signature is randomized depending on the message, key, and salt size,
    63  // using bytes from random. Most applications should use [crypto/rand.Reader] as
    64  // random.
    65  func SignPSS(random io.Reader, priv *PrivateKey, hash crypto.Hash, digest []byte, opts *PSSOptions) ([]byte, error) {
    66  	if err := checkPublicKeySize(&priv.PublicKey); err != nil {
    67  		return nil, err
    68  	}
    69  
    70  	if opts != nil && opts.Hash != 0 {
    71  		hash = opts.Hash
    72  	}
    73  
    74  	if boring.Enabled && rand.IsDefaultReader(random) && priv.N.BitLen() >= 1024 {
    75  		bkey, err := boringPrivateKey(priv)
    76  		if err != nil {
    77  			return nil, err
    78  		}
    79  		return boring.SignRSAPSS(bkey, hash, digest, opts.saltLength())
    80  	}
    81  	if priv.N.BitLen() >= 1024 {
    82  		boring.UnreachableExceptTests()
    83  	}
    84  
    85  	if !hash.Available() {
    86  		return nil, errors.New("crypto/rsa: requested hash function unavailable: " + hash.String())
    87  	}
    88  	h := fips140hash.Unwrap(hash.New())
    89  
    90  	if err := checkFIPS140OnlyPrivateKey(priv); err != nil {
    91  		return nil, err
    92  	}
    93  	if fips140only.Enforced() && !fips140only.ApprovedHash(h) {
    94  		return nil, errors.New("crypto/rsa: use of hash functions other than SHA-2 or SHA-3 is not allowed in FIPS 140-only mode")
    95  	}
    96  	if fips140only.Enforced() && !fips140only.ApprovedRandomReader(random) {
    97  		return nil, errors.New("crypto/rsa: only crypto/rand.Reader is allowed in FIPS 140-only mode")
    98  	}
    99  
   100  	k, err := fipsPrivateKey(priv)
   101  	if err != nil {
   102  		return nil, err
   103  	}
   104  
   105  	saltLength := opts.saltLength()
   106  	if fips140only.Enforced() && saltLength > h.Size() {
   107  		return nil, errors.New("crypto/rsa: use of PSS salt longer than the hash is not allowed in FIPS 140-only mode")
   108  	}
   109  	switch saltLength {
   110  	case PSSSaltLengthAuto:
   111  		saltLength, err = rsa.PSSMaxSaltLength(k.PublicKey(), h)
   112  		if err != nil {
   113  			return nil, fipsError(err)
   114  		}
   115  	case PSSSaltLengthEqualsHash:
   116  		saltLength = h.Size()
   117  	default:
   118  		// If we get here saltLength is either > 0 or < -1, in the
   119  		// latter case we fail out.
   120  		if saltLength <= 0 {
   121  			return nil, errors.New("crypto/rsa: invalid PSS salt length")
   122  		}
   123  	}
   124  
   125  	return fipsError2(rsa.SignPSS(random, k, h, digest, saltLength))
   126  }
   127  
   128  // VerifyPSS verifies a PSS signature.
   129  //
   130  // A valid signature is indicated by returning a nil error. digest must be the
   131  // result of hashing the input message using the given hash function. The opts
   132  // argument may be nil, in which case sensible defaults are used. opts.Hash is
   133  // ignored.
   134  //
   135  // The inputs are not considered confidential, and may leak through timing side
   136  // channels, or if an attacker has control of part of the inputs.
   137  func VerifyPSS(pub *PublicKey, hash crypto.Hash, digest []byte, sig []byte, opts *PSSOptions) error {
   138  	if err := checkPublicKeySize(pub); err != nil {
   139  		return err
   140  	}
   141  
   142  	if boring.Enabled {
   143  		bkey, err := boringPublicKey(pub)
   144  		if err != nil {
   145  			return err
   146  		}
   147  		if err := boring.VerifyRSAPSS(bkey, hash, digest, sig, opts.saltLength()); err != nil {
   148  			return ErrVerification
   149  		}
   150  		return nil
   151  	}
   152  
   153  	if !hash.Available() {
   154  		return errors.New("crypto/rsa: requested hash function unavailable: " + hash.String())
   155  	}
   156  	h := fips140hash.Unwrap(hash.New())
   157  
   158  	if err := checkFIPS140OnlyPublicKey(pub); err != nil {
   159  		return err
   160  	}
   161  	if fips140only.Enforced() && !fips140only.ApprovedHash(h) {
   162  		return errors.New("crypto/rsa: use of hash functions other than SHA-2 or SHA-3 is not allowed in FIPS 140-only mode")
   163  	}
   164  
   165  	k, err := fipsPublicKey(pub)
   166  	if err != nil {
   167  		return err
   168  	}
   169  
   170  	saltLength := opts.saltLength()
   171  	if fips140only.Enforced() && saltLength > h.Size() {
   172  		return errors.New("crypto/rsa: use of PSS salt longer than the hash is not allowed in FIPS 140-only mode")
   173  	}
   174  	switch saltLength {
   175  	case PSSSaltLengthAuto:
   176  		return fipsError(rsa.VerifyPSS(k, h, digest, sig))
   177  	case PSSSaltLengthEqualsHash:
   178  		return fipsError(rsa.VerifyPSSWithSaltLength(k, h, digest, sig, h.Size()))
   179  	default:
   180  		return fipsError(rsa.VerifyPSSWithSaltLength(k, h, digest, sig, saltLength))
   181  	}
   182  }
   183  
   184  // EncryptOAEP encrypts the given message with RSA-OAEP.
   185  //
   186  // OAEP is parameterised by a hash function that is used as a random oracle.
   187  // Encryption and decryption of a given message must use the same hash function
   188  // and sha256.New() is a reasonable choice.
   189  //
   190  // The random parameter is used as a source of entropy to ensure that
   191  // encrypting the same message twice doesn't result in the same ciphertext.
   192  // Most applications should use [crypto/rand.Reader] as random.
   193  //
   194  // The label parameter may contain arbitrary data that will not be encrypted,
   195  // but which gives important context to the message. For example, if a given
   196  // public key is used to encrypt two types of messages then distinct label
   197  // values could be used to ensure that a ciphertext for one purpose cannot be
   198  // used for another by an attacker. If not required it can be empty.
   199  //
   200  // The message must be no longer than the length of the public modulus minus
   201  // twice the hash length, minus a further 2.
   202  func EncryptOAEP(hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) ([]byte, error) {
   203  	return encryptOAEP(hash, hash, random, pub, msg, label)
   204  }
   205  
   206  // EncryptOAEPWithOptions encrypts the given message with RSA-OAEP using the
   207  // provided options.
   208  //
   209  // This function should only be used over [EncryptOAEP] when there is a need to
   210  // specify the OAEP and MGF1 hashes separately.
   211  //
   212  // See [EncryptOAEP] for additional details.
   213  func EncryptOAEPWithOptions(random io.Reader, pub *PublicKey, msg []byte, opts *OAEPOptions) ([]byte, error) {
   214  	if !opts.Hash.Available() {
   215  		return nil, errors.New("crypto/rsa: requested hash function unavailable: " + opts.Hash.String())
   216  	}
   217  	if opts.MGFHash != 0 && !opts.MGFHash.Available() {
   218  		return nil, errors.New("crypto/rsa: requested hash function unavailable: " + opts.MGFHash.String())
   219  	}
   220  	if opts.MGFHash == 0 {
   221  		return encryptOAEP(opts.Hash.New(), opts.Hash.New(), random, pub, msg, opts.Label)
   222  	}
   223  	return encryptOAEP(opts.Hash.New(), opts.MGFHash.New(), random, pub, msg, opts.Label)
   224  }
   225  
   226  func encryptOAEP(hash hash.Hash, mgfHash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) ([]byte, error) {
   227  	if err := checkPublicKeySize(pub); err != nil {
   228  		return nil, err
   229  	}
   230  
   231  	defer hash.Reset()
   232  	defer mgfHash.Reset()
   233  
   234  	if boring.Enabled && rand.IsDefaultReader(random) {
   235  		k := pub.Size()
   236  		if len(msg) > k-2*hash.Size()-2 {
   237  			return nil, ErrMessageTooLong
   238  		}
   239  		bkey, err := boringPublicKey(pub)
   240  		if err != nil {
   241  			return nil, err
   242  		}
   243  		return boring.EncryptRSAOAEP(hash, mgfHash, bkey, msg, label)
   244  	}
   245  	boring.UnreachableExceptTests()
   246  
   247  	hash = fips140hash.Unwrap(hash)
   248  	mgfHash = fips140hash.Unwrap(mgfHash)
   249  
   250  	if err := checkFIPS140OnlyPublicKey(pub); err != nil {
   251  		return nil, err
   252  	}
   253  	if fips140only.Enforced() {
   254  		if !fips140only.ApprovedHash(hash) || !fips140only.ApprovedHash(mgfHash) {
   255  			return nil, errors.New("crypto/rsa: use of hash functions other than SHA-2 or SHA-3 is not allowed in FIPS 140-only mode")
   256  		}
   257  		if !fips140only.ApprovedRandomReader(random) {
   258  			return nil, errors.New("crypto/rsa: only crypto/rand.Reader is allowed in FIPS 140-only mode")
   259  		}
   260  	}
   261  
   262  	k, err := fipsPublicKey(pub)
   263  	if err != nil {
   264  		return nil, err
   265  	}
   266  	return fipsError2(rsa.EncryptOAEP(hash, mgfHash, random, k, msg, label))
   267  }
   268  
   269  // DecryptOAEP decrypts ciphertext using RSA-OAEP.
   270  //
   271  // OAEP is parameterised by a hash function that is used as a random oracle.
   272  // Encryption and decryption of a given message must use the same hash function
   273  // and sha256.New() is a reasonable choice.
   274  //
   275  // The random parameter is legacy and ignored, and it can be nil.
   276  //
   277  // The label parameter must match the value given when encrypting. See
   278  // [EncryptOAEP] for details.
   279  func DecryptOAEP(hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, label []byte) ([]byte, error) {
   280  	defer hash.Reset()
   281  	return decryptOAEP(hash, hash, priv, ciphertext, label)
   282  }
   283  
   284  func decryptOAEP(hash, mgfHash hash.Hash, priv *PrivateKey, ciphertext []byte, label []byte) ([]byte, error) {
   285  	if err := checkPublicKeySize(&priv.PublicKey); err != nil {
   286  		return nil, err
   287  	}
   288  
   289  	if boring.Enabled && priv.N.BitLen() >= 1024 {
   290  		k := priv.Size()
   291  		if len(ciphertext) > k ||
   292  			k < hash.Size()*2+2 {
   293  			return nil, ErrDecryption
   294  		}
   295  		bkey, err := boringPrivateKey(priv)
   296  		if err != nil {
   297  			return nil, err
   298  		}
   299  		out, err := boring.DecryptRSAOAEP(hash, mgfHash, bkey, ciphertext, label)
   300  		if err != nil {
   301  			return nil, ErrDecryption
   302  		}
   303  		return out, nil
   304  	}
   305  
   306  	hash = fips140hash.Unwrap(hash)
   307  	mgfHash = fips140hash.Unwrap(mgfHash)
   308  
   309  	if err := checkFIPS140OnlyPrivateKey(priv); err != nil {
   310  		return nil, err
   311  	}
   312  	if fips140only.Enforced() {
   313  		if !fips140only.ApprovedHash(hash) || !fips140only.ApprovedHash(mgfHash) {
   314  			return nil, errors.New("crypto/rsa: use of hash functions other than SHA-2 or SHA-3 is not allowed in FIPS 140-only mode")
   315  		}
   316  	}
   317  
   318  	k, err := fipsPrivateKey(priv)
   319  	if err != nil {
   320  		return nil, err
   321  	}
   322  
   323  	return fipsError2(rsa.DecryptOAEP(hash, mgfHash, k, ciphertext, label))
   324  }
   325  
   326  // SignPKCS1v15 calculates the signature of hashed using
   327  // RSASSA-PKCS1-V1_5-SIGN from RSA PKCS #1 v1.5.  Note that hashed must
   328  // be the result of hashing the input message using the given hash
   329  // function. If hash is zero, hashed is signed directly. This isn't
   330  // advisable except for interoperability.
   331  //
   332  // The random parameter is legacy and ignored, and it can be nil.
   333  //
   334  // This function is deterministic. Thus, if the set of possible
   335  // messages is small, an attacker may be able to build a map from
   336  // messages to signatures and identify the signed messages. As ever,
   337  // signatures provide authenticity, not confidentiality.
   338  func SignPKCS1v15(random io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte) ([]byte, error) {
   339  	var hashName string
   340  	if hash != crypto.Hash(0) {
   341  		if len(hashed) != hash.Size() {
   342  			return nil, errors.New("crypto/rsa: input must be hashed message")
   343  		}
   344  		hashName = hash.String()
   345  	}
   346  
   347  	if err := checkPublicKeySize(&priv.PublicKey); err != nil {
   348  		return nil, err
   349  	}
   350  
   351  	if boring.Enabled && priv.N.BitLen() >= 1024 {
   352  		bkey, err := boringPrivateKey(priv)
   353  		if err != nil {
   354  			return nil, err
   355  		}
   356  		return boring.SignRSAPKCS1v15(bkey, hash, hashed)
   357  	}
   358  
   359  	if err := checkFIPS140OnlyPrivateKey(priv); err != nil {
   360  		return nil, err
   361  	}
   362  	if fips140only.Enforced() {
   363  		if !hash.Available() || !fips140only.ApprovedHash(fips140hash.Unwrap(hash.New())) {
   364  			return nil, errors.New("crypto/rsa: use of hash functions other than SHA-2 or SHA-3 is not allowed in FIPS 140-only mode")
   365  		}
   366  	}
   367  
   368  	k, err := fipsPrivateKey(priv)
   369  	if err != nil {
   370  		return nil, err
   371  	}
   372  	return fipsError2(rsa.SignPKCS1v15(k, hashName, hashed))
   373  }
   374  
   375  // VerifyPKCS1v15 verifies an RSA PKCS #1 v1.5 signature.
   376  // hashed is the result of hashing the input message using the given hash
   377  // function and sig is the signature. A valid signature is indicated by
   378  // returning a nil error. If hash is zero then hashed is used directly. This
   379  // isn't advisable except for interoperability.
   380  //
   381  // The inputs are not considered confidential, and may leak through timing side
   382  // channels, or if an attacker has control of part of the inputs.
   383  func VerifyPKCS1v15(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte) error {
   384  	var hashName string
   385  	if hash != crypto.Hash(0) {
   386  		if len(hashed) != hash.Size() {
   387  			return errors.New("crypto/rsa: input must be hashed message")
   388  		}
   389  		hashName = hash.String()
   390  	}
   391  
   392  	if err := checkPublicKeySize(pub); err != nil {
   393  		return err
   394  	}
   395  
   396  	if boring.Enabled {
   397  		bkey, err := boringPublicKey(pub)
   398  		if err != nil {
   399  			return err
   400  		}
   401  		if err := boring.VerifyRSAPKCS1v15(bkey, hash, hashed, sig); err != nil {
   402  			return ErrVerification
   403  		}
   404  		return nil
   405  	}
   406  
   407  	if err := checkFIPS140OnlyPublicKey(pub); err != nil {
   408  		return err
   409  	}
   410  	if fips140only.Enforced() {
   411  		if !hash.Available() || !fips140only.ApprovedHash(fips140hash.Unwrap(hash.New())) {
   412  			return errors.New("crypto/rsa: use of hash functions other than SHA-2 or SHA-3 is not allowed in FIPS 140-only mode")
   413  		}
   414  	}
   415  
   416  	k, err := fipsPublicKey(pub)
   417  	if err != nil {
   418  		return err
   419  	}
   420  	return fipsError(rsa.VerifyPKCS1v15(k, hashName, hashed, sig))
   421  }
   422  
   423  func fipsError(err error) error {
   424  	switch err {
   425  	case rsa.ErrDecryption:
   426  		return ErrDecryption
   427  	case rsa.ErrVerification:
   428  		return ErrVerification
   429  	case rsa.ErrMessageTooLong:
   430  		return ErrMessageTooLong
   431  	}
   432  	return err
   433  }
   434  
   435  func fipsError2[T any](x T, err error) (T, error) {
   436  	return x, fipsError(err)
   437  }
   438  
   439  func checkFIPS140OnlyPublicKey(pub *PublicKey) error {
   440  	if !fips140only.Enforced() {
   441  		return nil
   442  	}
   443  	if pub.N == nil {
   444  		return errors.New("crypto/rsa: public key missing N")
   445  	}
   446  	if pub.N.BitLen() < 2048 {
   447  		return errors.New("crypto/rsa: use of keys smaller than 2048 bits is not allowed in FIPS 140-only mode")
   448  	}
   449  	if pub.N.BitLen()%2 == 1 {
   450  		return errors.New("crypto/rsa: use of keys with odd size is not allowed in FIPS 140-only mode")
   451  	}
   452  	if pub.E <= 1<<16 {
   453  		return errors.New("crypto/rsa: use of public exponent <= 2¹⁶ is not allowed in FIPS 140-only mode")
   454  	}
   455  	if pub.E&1 == 0 {
   456  		return errors.New("crypto/rsa: use of even public exponent is not allowed in FIPS 140-only mode")
   457  	}
   458  	return nil
   459  }
   460  
   461  func checkFIPS140OnlyPrivateKey(priv *PrivateKey) error {
   462  	if !fips140only.Enforced() {
   463  		return nil
   464  	}
   465  	if err := checkFIPS140OnlyPublicKey(&priv.PublicKey); err != nil {
   466  		return err
   467  	}
   468  	if len(priv.Primes) != 2 {
   469  		return errors.New("crypto/rsa: use of multi-prime keys is not allowed in FIPS 140-only mode")
   470  	}
   471  	if priv.Primes[0] == nil || priv.Primes[1] == nil || priv.Primes[0].BitLen() != priv.Primes[1].BitLen() {
   472  		return errors.New("crypto/rsa: use of primes of different sizes is not allowed in FIPS 140-only mode")
   473  	}
   474  	return nil
   475  }
   476
View as plain text