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)

diff --git a/CHANGES b/CHANGES
index cb6c77bf1434e8c0e4ed27e9103854ca2642be8c..442807f1d3cd32f5a279cc82bea7c2e7da751fa5 100644 (file)
--- 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 ff4c43fc7545230ff3e0af95912dfe5dc186a59d..a43225ecf7bbf8446c40207c8faddd858d7828ab 100644 (file)
--- 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 9b2a3c1bb9d954db13000ff78e37b0b7fccb8f92..725c430c63d8d37d144039fbc44d74188ac47390 100644 (file)
--- 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 68addbfe20db977531a048498b5c415a56970b14..05b086f7faa0c760a8cc9b32319c7ddc902ca9bf 100644 (file)
--- 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 7245132aa1c09e0f43f447d45301f1fdf5e0fe45..817a8d1d0c7a58722ed3203eab794a73a05f29c8 100644 (file)
--- 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 b2f93dda8ef204517bd1e6ec6d14e65f91c43112..c2bd31176fba88a78abbfa115e25009b52f9e355 100644 (file)
--- 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 0b1e57e9e559f24e6d42af80088a5a989e840435..90c355bfbe3a655bc22c030680e6fed3c97d38ed 100644 (file)
--- 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: