grpc 1.66.0 → 1.67.0.pre1

data/third_party/boringssl-with-bazel/src/crypto/cpu_intel.c

@@ -173,20 +173,21 @@ void OPENSSL_cpuid_setup(void) {
 
   OPENSSL_cpuid(&eax, &ebx, &ecx, &edx, 1);
 
-  if (is_amd) {
-    // See https://www.amd.com/system/files/TechDocs/25481.pdf, page 10.
-    const uint32_t base_family = (eax >> 8) & 15;
-    const uint32_t base_model = (eax >> 4) & 15;
+  const uint32_t base_family = (eax >> 8) & 15;
+  const uint32_t base_model = (eax >> 4) & 15;
 
-    uint32_t family = base_family;
-    uint32_t model = base_model;
-    if (base_family == 0xf) {
-      const uint32_t ext_family = (eax >> 20) & 255;
-      family += ext_family;
-      const uint32_t ext_model = (eax >> 16) & 15;
-      model |= ext_model << 4;
-    }
+  uint32_t family = base_family;
+  uint32_t model = base_model;
+  if (base_family == 15) {
+    const uint32_t ext_family = (eax >> 20) & 255;
+    family += ext_family;
+  }
+  if (base_family == 6 || base_family == 15) {
+    const uint32_t ext_model = (eax >> 16) & 15;
+    model |= ext_model << 4;
+  }
 
+  if (is_amd) {
     if (family < 0x17 || (family == 0x17 && 0x70 <= model && model <= 0x7f)) {
       // Disable RDRAND on AMD families before 0x17 (Zen) due to reported
       // failures after suspend.
@@ -227,19 +228,67 @@ void OPENSSL_cpuid_setup(void) {
     ecx &= ~(1u << 28);  // AVX
     ecx &= ~(1u << 12);  // FMA
     ecx &= ~(1u << 11);  // AMD XOP
-    // Clear AVX2 and AVX512* bits.
-    //
-    // TODO(davidben): Should bits 17 and 26-28 also be cleared? Upstream
-    // doesn't clear those. See the comments in
-    // |CRYPTO_hardware_supports_XSAVE|.
-    extended_features[0] &=
-        ~((1u << 5) | (1u << 16) | (1u << 21) | (1u << 30) | (1u << 31));
+    extended_features[0] &= ~(1u << 5);   // AVX2
+    extended_features[1] &= ~(1u << 9);   // VAES
+    extended_features[1] &= ~(1u << 10);  // VPCLMULQDQ
   }
-  // See Intel manual, volume 1, section 15.2.
+  // See Intel manual, volume 1, sections 15.2 ("Detection of AVX-512 Foundation
+  // Instructions") through 15.4 ("Detection of Intel AVX-512 Instruction Groups
+  // Operating at 256 and 128-bit Vector Lengths").
   if ((xcr0 & 0xe6) != 0xe6) {
-    // Clear AVX512F. Note we don't touch other AVX512 extensions because they
-    // can be used with YMM.
-    extended_features[0] &= ~(1u << 16);
+    // Without XCR0.111xx11x, no AVX512 feature can be used. This includes ZMM
+    // registers, masking, SIMD registers 16-31 (even if accessed as YMM or
+    // XMM), and EVEX-coded instructions (even on YMM or XMM). Even if only
+    // XCR0.ZMM_Hi256 is missing, it isn't valid to use AVX512 features on
+    // shorter vectors, since AVX512 ties everything to the availability of
+    // 512-bit vectors. See the above-mentioned sections of the Intel manual,
+    // which say that *all* these XCR0 bits must be checked even when just using
+    // 128-bit or 256-bit vectors, and also volume 2a section 2.7.11 ("#UD
+    // Equations for EVEX") which says that all EVEX-coded instructions raise an
+    // undefined-instruction exception if any of these XCR0 bits is zero.
+    //
+    // AVX10 fixes this by reorganizing the features that used to be part of
+    // "AVX512" and allowing them to be used independently of 512-bit support.
+    // TODO: add AVX10 detection.
+    extended_features[0] &= ~(1u << 16);  // AVX512F
+    extended_features[0] &= ~(1u << 17);  // AVX512DQ
+    extended_features[0] &= ~(1u << 21);  // AVX512IFMA
+    extended_features[0] &= ~(1u << 26);  // AVX512PF
+    extended_features[0] &= ~(1u << 27);  // AVX512ER
+    extended_features[0] &= ~(1u << 28);  // AVX512CD
+    extended_features[0] &= ~(1u << 30);  // AVX512BW
+    extended_features[0] &= ~(1u << 31);  // AVX512VL
+    extended_features[1] &= ~(1u << 1);   // AVX512VBMI
+    extended_features[1] &= ~(1u << 6);   // AVX512VBMI2
+    extended_features[1] &= ~(1u << 11);  // AVX512VNNI
+    extended_features[1] &= ~(1u << 12);  // AVX512BITALG
+    extended_features[1] &= ~(1u << 14);  // AVX512VPOPCNTDQ
+  }
+
+  // Repurpose the bit for the removed MPX feature to indicate when using zmm
+  // registers should be avoided even when they are supported. (When set, AVX512
+  // features can still be used, but only using ymm or xmm registers.) Skylake
+  // suffered from severe downclocking when zmm registers were used, which
+  // affected unrelated code running on the system, making zmm registers not too
+  // useful outside of benchmarks. The situation improved significantly by Ice
+  // Lake, but a small amount of downclocking remained. (See
+  // https://lore.kernel.org/linux-crypto/e8ce1146-3952-6977-1d0e-a22758e58914@intel.com/)
+  // We take a conservative approach of not allowing zmm registers until after
+  // Ice Lake and Tiger Lake, i.e. until Sapphire Rapids on the server side.
+  //
+  // AMD CPUs, which support AVX512 starting with Zen 4, have not been reported
+  // to have any downclocking problem when zmm registers are used.
+  if (is_intel && family == 6 &&
+      (model == 85 ||    // Skylake, Cascade Lake, Cooper Lake (server)
+       model == 106 ||   // Ice Lake (server)
+       model == 108 ||   // Ice Lake (micro server)
+       model == 125 ||   // Ice Lake (client)
+       model == 126 ||   // Ice Lake (mobile)
+       model == 140 ||   // Tiger Lake (mobile)
+       model == 141)) {  // Tiger Lake (client)
+    extended_features[0] |= 1u << 14;
+  } else {
+    extended_features[0] &= ~(1u << 14);
   }
 
   OPENSSL_ia32cap_P[0] = edx;

data/third_party/boringssl-with-bazel/src/crypto/crypto.c

@@ -16,8 +16,8 @@
 
 #include <assert.h>
 
-#include "fipsmodule/rand/fork_detect.h"
 #include "fipsmodule/rand/internal.h"
+#include "bcm_support.h"
 #include "internal.h"
 
 

data/third_party/boringssl-with-bazel/src/crypto/ecdsa_extra/ecdsa_asn1.c

@@ -62,34 +62,87 @@
 #include <openssl/mem.h>
 
 #include "../bytestring/internal.h"
-#include "../fipsmodule/ec/internal.h"
+#include "../fipsmodule/ecdsa/internal.h"
 #include "../internal.h"
 
 
+static ECDSA_SIG *ecdsa_sig_from_fixed(const EC_KEY *key, const uint8_t *in,
+                                       size_t len) {
+  const EC_GROUP *group = EC_KEY_get0_group(key);
+  if (group == NULL) {
+    OPENSSL_PUT_ERROR(ECDSA, ERR_R_PASSED_NULL_PARAMETER);
+    return NULL;
+  }
+  size_t scalar_len = BN_num_bytes(EC_GROUP_get0_order(group));
+  if (len != 2 * scalar_len) {
+    OPENSSL_PUT_ERROR(ECDSA, ECDSA_R_BAD_SIGNATURE);
+    return NULL;
+  }
+  ECDSA_SIG *ret = ECDSA_SIG_new();
+  if (ret == NULL ||
+      !BN_bin2bn(in, scalar_len, ret->r) ||
+      !BN_bin2bn(in + scalar_len, scalar_len, ret->s)) {
+    ECDSA_SIG_free(ret);
+    return NULL;
+  }
+  return ret;
+}
+
+static int ecdsa_sig_to_fixed(const EC_KEY *key, uint8_t *out, size_t *out_len,
+                              size_t max_out, const ECDSA_SIG *sig) {
+  const EC_GROUP *group = EC_KEY_get0_group(key);
+  if (group == NULL) {
+    OPENSSL_PUT_ERROR(ECDSA, ERR_R_PASSED_NULL_PARAMETER);
+    return 0;
+  }
+  size_t scalar_len = BN_num_bytes(EC_GROUP_get0_order(group));
+  if (max_out < 2 * scalar_len) {
+    OPENSSL_PUT_ERROR(EC, EC_R_BUFFER_TOO_SMALL);
+    return 0;
+  }
+  if (BN_is_negative(sig->r) ||
+      !BN_bn2bin_padded(out, scalar_len, sig->r) ||
+      BN_is_negative(sig->s) ||
+      !BN_bn2bin_padded(out + scalar_len, scalar_len, sig->s)) {
+    OPENSSL_PUT_ERROR(ECDSA, ECDSA_R_BAD_SIGNATURE);
+    return 0;
+  }
+  *out_len = 2 * scalar_len;
+  return 1;
+}
+
 int ECDSA_sign(int type, const uint8_t *digest, size_t digest_len, uint8_t *sig,
-               unsigned int *sig_len, const EC_KEY *eckey) {
+               unsigned int *out_sig_len, const EC_KEY *eckey) {
   if (eckey->ecdsa_meth && eckey->ecdsa_meth->sign) {
-    return eckey->ecdsa_meth->sign(digest, digest_len, sig, sig_len,
+    return eckey->ecdsa_meth->sign(digest, digest_len, sig, out_sig_len,
                                    (EC_KEY*) eckey /* cast away const */);
   }
 
-  int ret = 0;
-  ECDSA_SIG *s = ECDSA_do_sign(digest, digest_len, eckey);
+  *out_sig_len = 0;
+  uint8_t fixed[ECDSA_MAX_FIXED_LEN];
+  size_t fixed_len;
+  if (!ecdsa_sign_fixed(digest, digest_len, fixed, &fixed_len, sizeof(fixed),
+                        eckey)) {
+    return 0;
+  }
+
+  // TODO(davidben): We can actually do better and go straight from the DER
+  // format to the fixed-width format without a malloc.
+  ECDSA_SIG *s = ecdsa_sig_from_fixed(eckey, fixed, fixed_len);
   if (s == NULL) {
-    *sig_len = 0;
-    goto err;
+    return 0;
   }
 
+  int ret = 0;
   CBB cbb;
   CBB_init_fixed(&cbb, sig, ECDSA_size(eckey));
   size_t len;
   if (!ECDSA_SIG_marshal(&cbb, s) ||
       !CBB_finish(&cbb, NULL, &len)) {
     OPENSSL_PUT_ERROR(ECDSA, ECDSA_R_ENCODE_ERROR);
-    *sig_len = 0;
     goto err;
   }
-  *sig_len = (unsigned)len;
+  *out_sig_len = (unsigned)len;
   ret = 1;
 
 err:
@@ -99,12 +152,13 @@ err:
 
 int ECDSA_verify(int type, const uint8_t *digest, size_t digest_len,
                  const uint8_t *sig, size_t sig_len, const EC_KEY *eckey) {
-  ECDSA_SIG *s;
+  // Decode the ECDSA signature.
+  //
+  // TODO(davidben): We can actually do better and go straight from the DER
+  // format to the fixed-width format without a malloc.
   int ret = 0;
   uint8_t *der = NULL;
-
-  // Decode the ECDSA signature.
-  s = ECDSA_SIG_from_bytes(sig, sig_len);
+  ECDSA_SIG *s = ECDSA_SIG_from_bytes(sig, sig_len);
   if (s == NULL) {
     goto err;
   }
@@ -118,7 +172,10 @@ int ECDSA_verify(int type, const uint8_t *digest, size_t digest_len,
     goto err;
   }
 
-  ret = ECDSA_do_verify(digest, digest_len, s, eckey);
+  uint8_t fixed[ECDSA_MAX_FIXED_LEN];
+  size_t fixed_len;
+  ret = ecdsa_sig_to_fixed(eckey, fixed, &fixed_len, sizeof(fixed), s) &&
+        ecdsa_verify_fixed(digest, digest_len, fixed, fixed_len, eckey);
 
 err:
   OPENSSL_free(der);
@@ -147,6 +204,95 @@ size_t ECDSA_size(const EC_KEY *key) {
   return ECDSA_SIG_max_len(group_order_size);
 }
 
+ECDSA_SIG *ECDSA_SIG_new(void) {
+  ECDSA_SIG *sig = OPENSSL_malloc(sizeof(ECDSA_SIG));
+  if (sig == NULL) {
+    return NULL;
+  }
+  sig->r = BN_new();
+  sig->s = BN_new();
+  if (sig->r == NULL || sig->s == NULL) {
+    ECDSA_SIG_free(sig);
+    return NULL;
+  }
+  return sig;
+}
+
+void ECDSA_SIG_free(ECDSA_SIG *sig) {
+  if (sig == NULL) {
+    return;
+  }
+
+  BN_free(sig->r);
+  BN_free(sig->s);
+  OPENSSL_free(sig);
+}
+
+const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig) {
+  return sig->r;
+}
+
+const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig) {
+  return sig->s;
+}
+
+void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **out_r,
+                    const BIGNUM **out_s) {
+  if (out_r != NULL) {
+    *out_r = sig->r;
+  }
+  if (out_s != NULL) {
+    *out_s = sig->s;
+  }
+}
+
+int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s) {
+  if (r == NULL || s == NULL) {
+    return 0;
+  }
+  BN_free(sig->r);
+  BN_free(sig->s);
+  sig->r = r;
+  sig->s = s;
+  return 1;
+}
+
+int ECDSA_do_verify(const uint8_t *digest, size_t digest_len,
+                    const ECDSA_SIG *sig, const EC_KEY *eckey) {
+  uint8_t fixed[ECDSA_MAX_FIXED_LEN];
+  size_t fixed_len;
+  return ecdsa_sig_to_fixed(eckey, fixed, &fixed_len, sizeof(fixed), sig) &&
+         ecdsa_verify_fixed(digest, digest_len, fixed, fixed_len, eckey);
+}
+
+// This function is only exported for testing and is not called in production
+// code.
+ECDSA_SIG *ECDSA_sign_with_nonce_and_leak_private_key_for_testing(
+    const uint8_t *digest, size_t digest_len, const EC_KEY *eckey,
+    const uint8_t *nonce, size_t nonce_len) {
+  uint8_t sig[ECDSA_MAX_FIXED_LEN];
+  size_t sig_len;
+  if (!ecdsa_sign_fixed_with_nonce_for_known_answer_test(
+          digest, digest_len, sig, &sig_len, sizeof(sig), eckey, nonce,
+          nonce_len)) {
+    return NULL;
+  }
+
+  return ecdsa_sig_from_fixed(eckey, sig, sig_len);
+}
+
+ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest, size_t digest_len,
+                         const EC_KEY *eckey) {
+  uint8_t sig[ECDSA_MAX_FIXED_LEN];
+  size_t sig_len;
+  if (!ecdsa_sign_fixed(digest, digest_len, sig, &sig_len, sizeof(sig),
+                        eckey)) {
+    return NULL;
+  }
+
+  return ecdsa_sig_from_fixed(eckey, sig, sig_len);
+}
+
 ECDSA_SIG *ECDSA_SIG_parse(CBS *cbs) {
   ECDSA_SIG *ret = ECDSA_SIG_new();
   if (ret == NULL) {

data/third_party/boringssl-with-bazel/src/crypto/fipsmodule/aes/internal.h

@@ -17,6 +17,8 @@
 
 #include <stdlib.h>
 
+#include <openssl/aes.h>
+
 #include "../../internal.h"
 
 #if defined(__cplusplus)

data/third_party/boringssl-with-bazel/src/crypto/fipsmodule/bcm.c

@@ -28,84 +28,85 @@
 #include <openssl/hmac.h>
 #include <openssl/sha.h>
 
+#include "bcm_interface.h"
 #include "../internal.h"
 
-#include "aes/aes.c"
-#include "aes/aes_nohw.c"
-#include "aes/key_wrap.c"
-#include "aes/mode_wrappers.c"
-#include "bn/add.c"
-#include "bn/asm/x86_64-gcc.c"
-#include "bn/bn.c"
-#include "bn/bytes.c"
-#include "bn/cmp.c"
-#include "bn/ctx.c"
-#include "bn/div.c"
-#include "bn/div_extra.c"
-#include "bn/exponentiation.c"
-#include "bn/gcd.c"
-#include "bn/gcd_extra.c"
-#include "bn/generic.c"
-#include "bn/jacobi.c"
-#include "bn/montgomery.c"
-#include "bn/montgomery_inv.c"
-#include "bn/mul.c"
-#include "bn/prime.c"
-#include "bn/random.c"
-#include "bn/rsaz_exp.c"
-#include "bn/shift.c"
-#include "bn/sqrt.c"
-#include "cipher/aead.c"
-#include "cipher/cipher.c"
-#include "cipher/e_aes.c"
-#include "cipher/e_aesccm.c"
-#include "cmac/cmac.c"
-#include "dh/check.c"
-#include "dh/dh.c"
-#include "digest/digest.c"
-#include "digest/digests.c"
-#include "digestsign/digestsign.c"
-#include "ecdh/ecdh.c"
-#include "ecdsa/ecdsa.c"
-#include "ec/ec.c"
-#include "ec/ec_key.c"
-#include "ec/ec_montgomery.c"
-#include "ec/felem.c"
-#include "ec/oct.c"
-#include "ec/p224-64.c"
-#include "ec/p256.c"
-#include "ec/p256-nistz.c"
-#include "ec/scalar.c"
-#include "ec/simple.c"
-#include "ec/simple_mul.c"
-#include "ec/util.c"
-#include "ec/wnaf.c"
-#include "hkdf/hkdf.c"
-#include "hmac/hmac.c"
-#include "md4/md4.c"
-#include "md5/md5.c"
-#include "modes/cbc.c"
-#include "modes/cfb.c"
-#include "modes/ctr.c"
-#include "modes/gcm.c"
-#include "modes/gcm_nohw.c"
-#include "modes/ofb.c"
-#include "modes/polyval.c"
-#include "rand/ctrdrbg.c"
-#include "rand/fork_detect.c"
-#include "rand/rand.c"
-#include "rand/urandom.c"
-#include "rsa/blinding.c"
-#include "rsa/padding.c"
-#include "rsa/rsa.c"
-#include "rsa/rsa_impl.c"
-#include "self_check/fips.c"
-#include "self_check/self_check.c"
-#include "service_indicator/service_indicator.c"
-#include "sha/sha1.c"
-#include "sha/sha256.c"
-#include "sha/sha512.c"
-#include "tls/kdf.c"
+// TODO(crbug.com/362530616): When delocate is removed, build these files as
+// separate compilation units again.
+#include "aes/aes.c.inc"
+#include "aes/aes_nohw.c.inc"
+#include "aes/key_wrap.c.inc"
+#include "aes/mode_wrappers.c.inc"
+#include "bn/add.c.inc"
+#include "bn/asm/x86_64-gcc.c.inc"
+#include "bn/bn.c.inc"
+#include "bn/bytes.c.inc"
+#include "bn/cmp.c.inc"
+#include "bn/ctx.c.inc"
+#include "bn/div.c.inc"
+#include "bn/div_extra.c.inc"
+#include "bn/exponentiation.c.inc"
+#include "bn/gcd.c.inc"
+#include "bn/gcd_extra.c.inc"
+#include "bn/generic.c.inc"
+#include "bn/jacobi.c.inc"
+#include "bn/montgomery.c.inc"
+#include "bn/montgomery_inv.c.inc"
+#include "bn/mul.c.inc"
+#include "bn/prime.c.inc"
+#include "bn/random.c.inc"
+#include "bn/rsaz_exp.c.inc"
+#include "bn/shift.c.inc"
+#include "bn/sqrt.c.inc"
+#include "cipher/aead.c.inc"
+#include "cipher/cipher.c.inc"
+#include "cipher/e_aes.c.inc"
+#include "cipher/e_aesccm.c.inc"
+#include "cmac/cmac.c.inc"
+#include "dh/check.c.inc"
+#include "dh/dh.c.inc"
+#include "digest/digest.c.inc"
+#include "digest/digests.c.inc"
+#include "digestsign/digestsign.c.inc"
+#include "ecdh/ecdh.c.inc"
+#include "ecdsa/ecdsa.c.inc"
+#include "ec/ec.c.inc"
+#include "ec/ec_key.c.inc"
+#include "ec/ec_montgomery.c.inc"
+#include "ec/felem.c.inc"
+#include "ec/oct.c.inc"
+#include "ec/p224-64.c.inc"
+#include "ec/p256.c.inc"
+#include "ec/p256-nistz.c.inc"
+#include "ec/scalar.c.inc"
+#include "ec/simple.c.inc"
+#include "ec/simple_mul.c.inc"
+#include "ec/util.c.inc"
+#include "ec/wnaf.c.inc"
+#include "hkdf/hkdf.c.inc"
+#include "hmac/hmac.c.inc"
+#include "md4/md4.c.inc"
+#include "md5/md5.c.inc"
+#include "modes/cbc.c.inc"
+#include "modes/cfb.c.inc"
+#include "modes/ctr.c.inc"
+#include "modes/gcm.c.inc"
+#include "modes/gcm_nohw.c.inc"
+#include "modes/ofb.c.inc"
+#include "modes/polyval.c.inc"
+#include "rand/ctrdrbg.c.inc"
+#include "rand/rand.c.inc"
+#include "rsa/blinding.c.inc"
+#include "rsa/padding.c.inc"
+#include "rsa/rsa.c.inc"
+#include "rsa/rsa_impl.c.inc"
+#include "self_check/fips.c.inc"
+#include "self_check/self_check.c.inc"
+#include "service_indicator/service_indicator.c.inc"
+#include "sha/sha1.c.inc"
+#include "sha/sha256.c.inc"
+#include "sha/sha512.c.inc"
+#include "tls/kdf.c.inc"
 
 
 #if defined(BORINGSSL_FIPS)
@@ -193,10 +194,10 @@ int BORINGSSL_integrity_test(void) {
 
   assert_within(start, AES_encrypt, end);
   assert_within(start, RSA_sign, end);
-  assert_within(start, RAND_bytes, end);
+  assert_within(start, BCM_rand_bytes, end);
   assert_within(start, EC_GROUP_cmp, end);
   assert_within(start, SHA256_Update, end);
-  assert_within(start, ECDSA_do_verify, end);
+  assert_within(start, ecdsa_verify_fixed, end);
   assert_within(start, EVP_AEAD_CTX_seal, end);
 
 #if defined(BORINGSSL_SHARED_LIBRARY)

data/third_party/boringssl-with-bazel/src/crypto/fipsmodule/bcm_interface.h

@@ -0,0 +1,89 @@
+/* Copyright (c) 2024, Google Inc.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+ * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
+
+#ifndef OPENSSL_HEADER_CRYPTO_BCM_INTERFACE_H
+#define OPENSSL_HEADER_CRYPTO_BCM_INTERFACE_H
+
+// This header will eventually become the interface between BCM and the
+// rest of libcrypto. More cleanly separating the two is still a work in
+// progress (see https://crbug.com/boringssl/722) so, at the moment, we
+// consider this no different from any other header in BCM.
+//
+// Over time, calls from libcrypto to BCM will all move to this header
+// and the separation will become more meaningful.
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+// Enumerated types for return values from bcm functions, both infallible
+// and fallible functions. Two success values are used to correspond to the
+// FIPS service indicator. For the moment, the official service indicator
+// remains the counter, not these values. Once we fully transition to
+// these return values from bcm we will change that.
+enum bcm_infallible_t {
+  bcm_infallible_approved,
+  bcm_infallible_not_approved,
+};
+
+enum bcm_status_t {
+  bcm_status_approved,
+  bcm_status_not_approved,
+
+  // Failure codes, which must all be negative.
+  bcm_status_failure,
+};
+typedef enum bcm_status_t bcm_status;
+typedef enum bcm_infallible_t bcm_infallible;
+
+OPENSSL_INLINE int bcm_success(bcm_status status) {
+  return status == bcm_status_approved || status == bcm_status_not_approved;
+}
+
+#if defined(BORINGSSL_FIPS)
+
+// We overread from /dev/urandom or RDRAND by a factor of 10 and XOR to whiten.
+// TODO(bbe): disentangle this value which is used to calculate the size of the
+// stack buffer in RAND_need entropy based on a calculation.
+#define BORINGSSL_FIPS_OVERREAD 10
+
+#endif  // BORINGSSL_FIPS
+
+// BCM_rand_load_entropy supplies |entropy_len| bytes of entropy to the BCM
+// module. The |want_additional_input| parameter is true iff the entropy was
+// obtained from a source other than the system, e.g. directly from the CPU.
+bcm_infallible BCM_rand_load_entropy(const uint8_t *entropy, size_t entropy_len,
+                       int want_additional_input);
+
+// BCM_rand_bytes is the same as the public |RAND_bytes| function, other
+// than returning a bcm_infallible status indicator.
+OPENSSL_EXPORT bcm_infallible BCM_rand_bytes(uint8_t *out, size_t out_len);
+
+// BCM_rand_bytes_hwrng attempts to fill |out| with |len| bytes of entropy from
+// the CPU hardware random number generator if one is present.
+// bcm_status_approved is returned on success, and a failure status is
+// returned otherwise.
+bcm_status BCM_rand_bytes_hwrng(uint8_t *out, size_t len);
+
+// BCM_rand_bytes_with_additional_data samples from the RNG after mixing 32
+// bytes from |user_additional_data| in.
+bcm_infallible BCM_rand_bytes_with_additional_data(
+    uint8_t *out, size_t out_len, const uint8_t user_additional_data[32]);
+
+
+#if defined(__cplusplus)
+}  // extern C
+#endif
+
+#endif  // OPENSSL_HEADER_CRYPTO_BCM_INTERFACE_H