Deprecate NCONF_WIN32() function

Extensive documentation added in HISTORY section in doc/man5/config.pod

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9578)

7 files changed, 32 insertions, 7 deletions

diff --git a/CHANGES b/CHANGES
index cb6c77bf14..442807f1d3 100644
--- a/CHANGES
+++ b/CHANGES
@@ -9,6 +9,10 @@
 
  Changes between 1.1.1 and 3.0.0 [xx XXX xxxx]
 
+  *) The undocumented function NCONF_WIN32() has been deprecated; for
+     conversion details see the HISTORY section of doc/man5/config.pod
+     [Rich Salz]
+
   *) Introduced the new functions EVP_DigestSignInit_ex() and
      EVP_DigestVerifyInit_ex(). The macros EVP_DigestSignUpdate() and
      EVP_DigestVerifyUpdate() have been converted to functions. See the man
diff --git a/crypto/conf/conf_def.c b/crypto/conf/conf_def.c
index ff4c43fc75..a43225ecf7 100644
--- a/crypto/conf/conf_def.c
+++ b/crypto/conf/conf_def.c
@@ -54,7 +54,9 @@ static BIO *get_next_file(const char *path, OPENSSL_DIR_CTX **dirctx);
 
 static CONF *def_create(CONF_METHOD *meth);
 static int def_init_default(CONF *conf);
+#if !OPENSSL_API_3
 static int def_init_WIN32(CONF *conf);
+#endif
 static int def_destroy(CONF *conf);
 static int def_destroy_data(CONF *conf);
 static int def_load(CONF *conf, const char *name, long *eline);
@@ -76,6 +78,12 @@ static CONF_METHOD default_method = {
     def_load
 };
 
+CONF_METHOD *NCONF_default(void)
+{
+    return &default_method;
+}
+
+#if ! OPENSSL_API_3
 static CONF_METHOD WIN32_method = {
     "WIN32",
     def_create,
@@ -89,15 +97,11 @@ static CONF_METHOD WIN32_method = {
     def_load
 };
 
-CONF_METHOD *NCONF_default(void)
-{
-    return &default_method;
-}
-
 CONF_METHOD *NCONF_WIN32(void)
 {
     return &WIN32_method;
 }
+#endif
 
 static CONF *def_create(CONF_METHOD *meth)
 {
@@ -124,6 +128,7 @@ static int def_init_default(CONF *conf)
     return 1;
 }
 
+#if ! OPENSSL_API_3
 static int def_init_WIN32(CONF *conf)
 {
     if (conf == NULL)
@@ -135,6 +140,7 @@ static int def_init_WIN32(CONF *conf)
 
     return 1;
 }
+#endif
 
 static int def_destroy(CONF *conf)
 {
diff --git a/crypto/conf/conf_def.h b/crypto/conf/conf_def.h
index 9b2a3c1bb9..725c430c63 100644
--- a/crypto/conf/conf_def.h
+++ b/crypto/conf/conf_def.h
@@ -56,6 +56,7 @@ static const unsigned short CONF_type_default[128] = {
     0x0004, 0x0004, 0x0004, 0x0000, 0x0200, 0x0000, 0x0200, 0x0000,
 };
 
+#if ! OPENSSL_API_3
 static const unsigned short CONF_type_win32[128] = {
     0x0008, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000,
     0x0000, 0x0010, 0x0010, 0x0000, 0x0000, 0x0010, 0x0000, 0x0000,
@@ -74,3 +75,4 @@ static const unsigned short CONF_type_win32[128] = {
     0x0004, 0x0004, 0x0004, 0x0004, 0x0004, 0x0004, 0x0004, 0x0004,
     0x0004, 0x0004, 0x0004, 0x0000, 0x0200, 0x0000, 0x0200, 0x0000,
 };
+#endif
diff --git a/crypto/conf/keysets.pl b/crypto/conf/keysets.pl
index 68addbfe20..05b086f7fa 100644
--- a/crypto/conf/keysets.pl
+++ b/crypto/conf/keysets.pl
@@ -108,9 +108,11 @@ for ($i = 0; $i < 128; $i++) {
 }
 print "\n};\n\n";
 
+print "#if ! OPENSSL_API_3\n";
 print "static const unsigned short CONF_type_win32[128] = {";
 for ($i = 0; $i < 128; $i++) {
     print "\n   " if ($i % 8) == 0;
     printf " 0x%04X,", $V_w32[$i];
 }
 print "\n};\n";
+print "#endif\n";
diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 7245132aa1..817a8d1d0c 100644
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -507,6 +507,17 @@ Files are loaded in a single pass. This means that an variable expansion
 will only work if the variables referenced are defined earlier in the
 file.
 
+=head1 HISTORY
+
+An undocumented API, NCONF_WIN32(), used a slightly different set
+of parsing rules there were intended to be tailored to
+the Microsoft Windows platform.
+Specifically, the backslash character was not an escape character and
+could be used in pathnames, only the double-quote character was recognized,
+and comments began with a semi-colon.
+This function was deprecated in OpenSSL 3.0; applications with
+configuration files using that syntax will have to be modified.
+
 =head1 SEE ALSO
 
 L<x509(1)>, L<req(1)>, L<ca(1)>, L<fips_config(5)>
diff --git a/include/openssl/conf.h b/include/openssl/conf.h
index b2f93dda8e..c2bd31176f 100644
--- a/include/openssl/conf.h
+++ b/include/openssl/conf.h
@@ -114,7 +114,7 @@ struct conf_st {
 
 CONF *NCONF_new(CONF_METHOD *meth);
 CONF_METHOD *NCONF_default(void);
-CONF_METHOD *NCONF_WIN32(void);
+DEPRECATEDIN_3(CONF_METHOD *NCONF_WIN32(void))
 void NCONF_free(CONF *conf);
 void NCONF_free_data(CONF *conf);
 
diff --git a/util/libcrypto.num b/util/libcrypto.num
index 0b1e57e9e5..90c355bfbe 100644
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -1663,7 +1663,7 @@ X509_PURPOSE_cleanup                    1700	3_0_0	EXIST::FUNCTION:
 ESS_SIGNING_CERT_dup                    1701	3_0_0	EXIST::FUNCTION:
 ENGINE_set_default_DSA                  1702	3_0_0	EXIST::FUNCTION:ENGINE
 X509_REVOKED_new                        1703	3_0_0	EXIST::FUNCTION:
-NCONF_WIN32                             1704	3_0_0	EXIST::FUNCTION:
+NCONF_WIN32                             1704	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3
 RSA_padding_check_PKCS1_OAEP_mgf1       1705	3_0_0	EXIST::FUNCTION:RSA
 X509_policy_tree_get0_level             1706	3_0_0	EXIST::FUNCTION:
 ASN1_parse_dump                         1708	3_0_0	EXIST::FUNCTION: