From 85c5d9668fe3aef03dc3b5099adc549039a79ff9 Mon Sep 17 00:00:00 2001
From: Bob Beck <bbe@google.com>
Date: Wed, 21 Feb 2024 22:07:58 +0000
Subject: [PATCH] Make an include/openssl/experimental. Move kyber to it for
 now.

Update-Note: <openssl/kyber.h> has moved to
<openssl/experimental/kyber.h>

Change-Id: I51d37aeb2b6cfbbaae494cc38f1b0a82669d2692
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/66467
Reviewed-by: David Benjamin <davidben@google.com>
Auto-Submit: Bob Beck <bbe@google.com>
Commit-Queue: Bob Beck <bbe@google.com>
---
 API-CONVENTIONS.md                         | 3 +++
 crypto/kyber/internal.h                    | 2 +-
 crypto/kyber/kyber.c                       | 2 +-
 crypto/kyber/kyber_test.cc                 | 2 +-
 include/openssl/{ => experimental}/kyber.h | 0
 ssl/ssl_key_share.cc                       | 2 +-
 tool/speed.cc                              | 2 +-
 util/doc.config                            | 6 +++++-
 8 files changed, 13 insertions(+), 6 deletions(-)
 rename include/openssl/{ => experimental}/kyber.h (100%)

diff --git a/API-CONVENTIONS.md b/API-CONVENTIONS.md
index ec08e57a2..e36037bb2 100644
--- a/API-CONVENTIONS.md
+++ b/API-CONVENTIONS.md
@@ -16,6 +16,9 @@ OpenSSL's legacy ASN.1, X.509, and PEM implementation. If possible, avoid using
 them. These are left largely unmodified from upstream and are retained only for
 compatibility with existing OpenSSL consumers.
 
+Experimental public APIs are found in `include/openssl/experimental`. Use of
+these will likely be incompatible with changes in the near future as they are
+finalized.
 
 ## Forward declarations
 
diff --git a/crypto/kyber/internal.h b/crypto/kyber/internal.h
index 7f4a08c2e..007226904 100644
--- a/crypto/kyber/internal.h
+++ b/crypto/kyber/internal.h
@@ -16,7 +16,7 @@
 #define OPENSSL_HEADER_CRYPTO_KYBER_INTERNAL_H
 
 #include <openssl/base.h>
-#include <openssl/kyber.h>
+#include <openssl/experimental/kyber.h>
 
 #if defined(__cplusplus)
 extern "C" {
diff --git a/crypto/kyber/kyber.c b/crypto/kyber/kyber.c
index e9e3a9198..0e973590e 100644
--- a/crypto/kyber/kyber.c
+++ b/crypto/kyber/kyber.c
@@ -12,7 +12,7 @@
  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
 
-#include <openssl/kyber.h>
+#include <openssl/experimental/kyber.h>
 
 #include <assert.h>
 #include <stdlib.h>
diff --git a/crypto/kyber/kyber_test.cc b/crypto/kyber/kyber_test.cc
index c42db787c..99564788b 100644
--- a/crypto/kyber/kyber_test.cc
+++ b/crypto/kyber/kyber_test.cc
@@ -20,7 +20,7 @@
 
 #include <openssl/bytestring.h>
 #include <openssl/ctrdrbg.h>
-#include <openssl/kyber.h>
+#include <openssl/experimental/kyber.h>
 
 #include "../test/file_test.h"
 #include "../test/test_util.h"
diff --git a/include/openssl/kyber.h b/include/openssl/experimental/kyber.h
similarity index 100%
rename from include/openssl/kyber.h
rename to include/openssl/experimental/kyber.h
diff --git a/ssl/ssl_key_share.cc b/ssl/ssl_key_share.cc
index 80317d898..f4fda3fda 100644
--- a/ssl/ssl_key_share.cc
+++ b/ssl/ssl_key_share.cc
@@ -24,7 +24,7 @@
 #include <openssl/curve25519.h>
 #include <openssl/ec.h>
 #include <openssl/err.h>
-#include <openssl/kyber.h>
+#include <openssl/experimental/kyber.h>
 #include <openssl/hrss.h>
 #include <openssl/mem.h>
 #include <openssl/nid.h>
diff --git a/tool/speed.cc b/tool/speed.cc
index 547390946..a8c058731 100644
--- a/tool/speed.cc
+++ b/tool/speed.cc
@@ -38,8 +38,8 @@
 #include <openssl/ecdsa.h>
 #include <openssl/err.h>
 #include <openssl/evp.h>
+#include <openssl/experimental/kyber.h>
 #include <openssl/hrss.h>
-#include <openssl/kyber.h>
 #include <openssl/mem.h>
 #include <openssl/nid.h>
 #include <openssl/rand.h>
diff --git a/util/doc.config b/util/doc.config
index e36a9601d..2e71c3c65 100644
--- a/util/doc.config
+++ b/util/doc.config
@@ -36,7 +36,6 @@
       "include/openssl/engine.h",
       "include/openssl/hkdf.h",
       "include/openssl/hmac.h",
-      "include/openssl/kyber.h",
       "include/openssl/md5.h",
       "include/openssl/rc4.h",
       "include/openssl/rsa.h",
@@ -60,6 +59,11 @@
       "include/openssl/conf.h",
       "include/openssl/x509.h"
     ]
+  },{
+    "Name": "Experimental primitives. Will be removed and replaced when standardized!",
+    "Headers": [
+      "include/openssl/experimental/kyber.h"
+    ]
   },{
     "Name": "SSL implementation",
     "Headers": [