GH-329 Update documentation about the recent OPENSSL_Applink changes.

Closes #411.

Author: h-vn

Changes

@@ -21,6 +21,18 @@ Revision history for Perl extension Net::SSLeay.
 	    - LibreSSL on OpenBSD 6.9
 	    - LibreSSL on OpenBSD 7.1
 	    - Cygwin on x86_64
+	- Fix compilation failure using cl. Microsoft cl compiler do
+	  not like when preprocessor directives are inside a
+	  macro. Fixes GH-403. Thanks to Jean-Damien Durand.
+	- Update CTX_use_PKCS12_file() and CTX_use_PKCS12_file() to
+	  use BIO functions for avoiding "no OPENSSL_Applink" runtime
+	  errors. Fixes GH-281 and RT#101638. Thanks to Jean-Damien
+	  Durand.
+	- Add to README.Win32 more information about OPENSSL_Applink
+	  and how it may be needed with FILE pointers and POSIX/Unix
+	  fds. Recommended method is to avoid them and use OpenSSL BIO
+	  functions instead. Update SSLeay.pod with alternatives to
+	  Net::SSLeay::SESSION_print_fp(). Closes GH-411.
 	- Refactor variable declarations in RSA_generate_key to allow SSLeay.xs to
 	  compile under -Werror=declaration-after-statement. Fixes GH-407. Thanks to
 	  dharanlinux for the report.

README.Win32

@@ -6,10 +6,22 @@ Building on Win 32 platforms
 10.7.2007. Complete rewrite to agree with latest version 1.31. References to
 ancient versions and untested procedures removed --mikem
 22.4.2010 Updated info for 64 bit versions --mikem
+23.12.2022 Update OPENSSL_Applink for 1.93_02 and later --hvn
 
 Notes: 
 
-1. With some combinations of Windows, perl, compiler and compiler options, you
+1. "no OPENSSL_Applink" runtime error
+Changes in Net::SSLeay 1.93_02 fix this error with
+Net::SSLeay::P_PKCS12_load_file and Net::SSLeay::CTX_use_PKCS12_file
+functions. The error is caused when a file pointer or descriptor (FILE
+*, POSIX/unix fd) is passed between boundaries, as described
+below. Recommended fix is to use OpenSSL BIO API. Net::SSLeay still
+exposes SSL_SESSION_print_fp() which expects a FILE * as its first
+argument. See Net::SSLeay manual for more information about
+Net::SSLeay::SESSION_print_fp() and a possible workaround.
+
+Information for Net::SSLeay 1.93_01 and earlier follows:
+With some combinations of Windows, perl, compiler and compiler options, you
 may see a runtime error "no OPENSSL_Applink", when calling
 Net::SSLeay::P_PKCS12_load_file. This appears to be due to incompatible
 compile options between the openssl libraries and Net::SSLeay. In particular

lib/Net/SSLeay.pod

@@ -1972,8 +1972,9 @@ Examples:
  #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
  my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
 
-B<NOTE> With some combinations of Windows, perl, compiler and compiler options, you
-may see a runtime error "no OPENSSL_Applink", when calling
+B<NOTE> Net::SSLeay 1.92_01 and earlier: With some combinations of
+Windows, perl, compiler and compiler options, you may see a runtime
+error "no OPENSSL_Applink", when calling
 Net::SSLeay::P_PKCS12_load_file. See README.Win32 for more details.
 
 =back
@@ -2226,6 +2227,11 @@ You have to use necessary BIO functions like this:
 
 Prints session details (e.g. protocol version, cipher, session-id ...) to file handle.
 
+B<NOTE> With some combinations of Windows, perl, compiler and compiler
+options, you may see a runtime error "no OPENSSL_Applink", when
+calling Net::SSLeay::SESSION_print_fp. See README.Win32 for more
+details.
+
  my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
  # $fp - perl file handle
  # $ses - value corresponding to openssl's SSL_SESSION structure
@@ -2239,6 +2245,12 @@ Example:
  open my $fh, ">", "output.txt";
  Net::SSLeay::SESSION_print_fp($fh,$ses);
 
+Similar functionality without Net::SSLeay::SESSION_print_fp
+
+ my $ses = Net::SSLeay::get_session($ssl);
+ my $bio = Net::SSLeay::BIO_new_file('output.txt', 'w');
+ Net::SSLeay::SESSION_print($bio, $ses);
+
 =item * SESSION_set_time
 
 Replaces the creation time of the session s with the chosen value $t (seconds since 1.1.1970).
@@ -3391,6 +3403,11 @@ Adds the certificate and private key from PKCS12 file $p12filename to $ctx.
  #
  # returns: 1 on success, 0 on failure
 
+B<NOTE> Net::SSLeay 1.92_01 and earlier: With some combinations of
+Windows, perl, compiler and compiler options, you may see a runtime
+error "no OPENSSL_Applink", when calling
+Net::SSLeay::CTX_use_PKCS12_file. See README.Win32 for more details.
+
 =item * CTX_use_PrivateKey
 
 Adds the private key $pkey to $ctx.