release as 2.089

update fingerprints and public suffix

Changes

@@ -1,3 +1,8 @@
+2.089 2024/08/29
+- new option SSL_force_fingerprint to enforce fingerprint matching even if
+  certificate validation would be successful without
+- document _get_ssl_object and _get_ctx_object for cases, where direct use of
+  Net::SSLeay functions is needed
 2.088 2024/07/14
 - minor fixes for use on ancient versions of perl and for building with
   newer versions of openssl

lib/IO/Socket/SSL.pm

@@ -13,7 +13,7 @@
 
 package IO::Socket::SSL;
 
-our $VERSION = '2.088';
+our $VERSION = '2.089';
 
 use IO::Socket;
 use Net::SSLeay 1.46;
@@ -1570,14 +1570,14 @@ sub fileno {
 
 
 ####### IO::Socket::SSL specific functions #######
-# _get_ssl_object is for internal use ONLY!
+# get access to SSL handle for use with Net::SSLeay. Use with caution!
 sub _get_ssl_object {
     my $self = shift;
     return ${*$self}{'_SSL_object'} ||
 	IO::Socket::SSL->_internal_error("Undefined SSL object",9);
 }
 
-# _get_ctx_object is for internal use ONLY!
+# get access to SSL handle for use with Net::SSLeay. Use with caution!
 sub _get_ctx_object {
     my $self = shift;
     my $ctx_object = ${*$self}{_SSL_ctx};
@@ -2319,7 +2319,7 @@ my $DEFAULT_SSL_OP = &Net::SSLeay::OP_ALL
     | ($can_ecdh ? &Net::SSLeay::OP_SINGLE_ECDH_USE : 0);
 
 
-# _get_ctx_object is for internal use ONLY!
+# get access to SSL handle for use with Net::SSLeay. Use with caution!
 sub _get_ctx_object { shift->{context} }
 
 # Note that the final object will actually be a reference to the scalar

lib/IO/Socket/SSL.pod

@@ -2190,6 +2190,20 @@ the print/printf/syswrite and read/sysread families instead.
 
 =back
 
+=head1 ACCESS TO INTERNALS
+
+C<IO::Socket::SSL> uses internally C<Net::SSLeay> which provides a lower level
+API to OpenSSL and provides functions which work directly with OpenSSL SSL and
+CTX handles. Sometimes it might be necessary to get direct access to these
+handles from C<IO::Socket::SSL> in order to apply functionality available only
+with C<Net::SSLeay>.
+
+For this C<_get_ssl_object> can be used on the C<IO::Socket::SSL> object to get
+access to the OpenSSL SSL handle and C<_get_ctx_object> can be used on
+C<IO::Socket::SSL> and C<IO::Socket::SSL_Context> objects to access the OpenSSL
+CTX handle. Use very carefully since OpenSSL memory/reference management must be
+done manually with C<Net::SSLeay>.
+
 =head1 DEPRECATIONS
 
 The following functions are deprecated and are only retained for compatibility: