Merge 7c15548 into 254d15e

Author: jimklimov

NEWS.adoc

@@ -122,6 +122,9 @@ https://github.com/networkupstools/nut/milestone/12
    * Revised OpenSSL handshake to support retries requested by the library,
      so it at least works reliably on different platforms within the scope
      it has now. [issue #3331, PR #3344]
+   * Extended `PyNUTClient` to support `STARTTLS` and optional server/self
+     identification, added NIT tests for that ability. [issues #1711, #3329,
+     #1600, PR #3352].
 
  - NUT for Windows specific updates:
    * Revised detection of (relative) paths to program and configuration files

clients/upsclient.c

@@ -204,16 +204,16 @@ static int ssl_error(SSL *ssl, ssize_t ret)
 	switch (e)
 	{
 	case SSL_ERROR_WANT_READ:
-		upslogx(LOG_ERR, "ssl_error() ret=%" PRIiSIZE " SSL_ERROR_WANT_READ", ret);
-		break;
+		upsdebugx(4, "ssl_error() ret=%" PRIiSIZE " SSL_ERROR_WANT_READ", ret);
+		return 0;
 
 	case SSL_ERROR_WANT_WRITE:
-		upslogx(LOG_ERR, "ssl_error() ret=%" PRIiSIZE " SSL_ERROR_WANT_WRITE", ret);
-		break;
+		upsdebugx(4, "ssl_error() ret=%" PRIiSIZE " SSL_ERROR_WANT_WRITE", ret);
+		return 0;
 
 	case SSL_ERROR_SYSCALL:
 		if (ret == 0 && ERR_peek_error() == 0) {
-			upslogx(LOG_ERR, "ssl_error() EOF from client");
+			upslogx(LOG_ERR, "ssl_error() EOF from server");
 		} else {
 			upslogx(LOG_ERR, "ssl_error() ret=%" PRIiSIZE " SSL_ERROR_SYSCALL", ret);
 		}
@@ -709,16 +709,68 @@ static ssize_t net_read(UPSCONN_t *ups, char *buf, size_t buflen, const time_t t
 #ifdef WITH_SSL
 	if (ups->ssl) {
 # ifdef WITH_OPENSSL
+		int	iret, ssl_err, ssl_retries = 0;
+		/* Cap retries to avoid spinning forever on a broken socket.
+		 * 250 * 20 ms = 5 s maximum wait, which is generous for a
+		 * local handshake while being safe for CI timeouts.
+		 */
+		const int	SSL_IO_MAX_RETRIES = 250;
+		fd_set	fds;
+		struct timeval	tv;
+
 		/* SSL_* routines deal with int type for return and buflen
 		 * We might need to window our I/O if we exceed 2GB (in
 		 * 32-bit builds)... Not likely to exceed in 64-bit builds,
 		 * but smaller systems with 16-bits might be endangered :)
 		 */
-		int iret;
 		assert(buflen <= INT_MAX);
-		iret = SSL_read(ups->ssl, buf, (int)buflen);
-		assert(iret <= SSIZE_MAX);
-		ret = (ssize_t)iret;
+
+		while (ssl_retries < SSL_IO_MAX_RETRIES) {
+			iret = SSL_read(ups->ssl, buf, (int)buflen);
+
+			assert(iret <= SSIZE_MAX);
+			if (iret > 0) {
+				ret = (ssize_t)iret;
+				break;
+			}
+
+			if (iret == 0) {
+				/* Orderly shutdown or actual EOF */
+				ret = 0;
+				break;
+			}
+
+			ssl_err = SSL_get_error(ups->ssl, iret);
+			if (ssl_err == SSL_ERROR_WANT_READ
+			 || ssl_err == SSL_ERROR_WANT_WRITE
+			) {
+				FD_ZERO(&fds);
+				FD_SET(ups->fd, &fds);
+				tv.tv_sec  = 0;
+				tv.tv_usec = 20000;	/* 20 ms */
+
+				if (select(ups->fd + 1,
+					(ssl_err == SSL_ERROR_WANT_READ)  ? &fds : NULL,
+					(ssl_err == SSL_ERROR_WANT_WRITE) ? &fds : NULL,
+					NULL, &tv) < 0
+				) {
+					/* select failure is fatal enough to stop retrying */
+					ssl_error(ups->ssl, (ssize_t)iret);
+					return -1;
+				}
+				ssl_retries++;
+				continue;
+			}
+
+			/* Other errors are fatal */
+			ssl_error(ups->ssl, (ssize_t)iret);
+			return -1;
+		}
+
+		if (ssl_retries >= SSL_IO_MAX_RETRIES) {
+			upslogx(LOG_ERR, "%s: SSL_read timed out after %d retries", __func__, ssl_retries);
+			return -1;
+		}
 # elif defined(WITH_NSS) /* WITH_OPENSSL */
 		/* PR_* routines deal in PRInt32 type
 		 * We might need to window our I/O if we exceed 2GB :) */
@@ -794,16 +846,62 @@ static ssize_t net_write(UPSCONN_t *ups, const char *buf, size_t buflen, const t
 #ifdef WITH_SSL
 	if (ups->ssl) {
 # ifdef WITH_OPENSSL
+		int	iret, ssl_err, ssl_retries = 0;
+		/* Cap retries to avoid spinning forever on a broken socket.
+		 * 250 * 20 ms = 5 s maximum wait, which is generous for a
+		 * local handshake while being safe for CI timeouts.
+		 */
+		const int	SSL_IO_MAX_RETRIES = 250;
+		fd_set	fds;
+		struct timeval	tv;
+
 		/* SSL_* routines deal with int type for return and buflen
 		 * We might need to window our I/O if we exceed 2GB (in
 		 * 32-bit builds)... Not likely to exceed in 64-bit builds,
 		 * but smaller systems with 16-bits might be endangered :)
 		 */
-		int iret;
 		assert(buflen <= INT_MAX);
-		iret = SSL_write(ups->ssl, buf, (int)buflen);
-		assert(iret <= SSIZE_MAX);
-		ret = (ssize_t)iret;
+
+		while (ssl_retries < SSL_IO_MAX_RETRIES) {
+			iret = SSL_write(ups->ssl, buf, (int)buflen);
+
+			assert(iret <= SSIZE_MAX);
+			if (iret > 0) {
+				ret = (ssize_t)iret;
+				break;
+			}
+
+			ssl_err = SSL_get_error(ups->ssl, iret);
+			if (ssl_err == SSL_ERROR_WANT_READ
+			 || ssl_err == SSL_ERROR_WANT_WRITE
+			) {
+				FD_ZERO(&fds);
+				FD_SET(ups->fd, &fds);
+				tv.tv_sec  = 0;
+				tv.tv_usec = 20000;	/* 20 ms */
+
+				if (select(ups->fd + 1,
+					(ssl_err == SSL_ERROR_WANT_READ)  ? &fds : NULL,
+					(ssl_err == SSL_ERROR_WANT_WRITE) ? &fds : NULL,
+					NULL, &tv) < 0
+				) {
+					/* select failure is fatal enough to stop retrying */
+					ssl_error(ups->ssl, (ssize_t)iret);
+					return -1;
+				}
+				ssl_retries++;
+				continue;
+			}
+
+			/* Other errors (including iret=0) are fatal */
+			ssl_error(ups->ssl, (ssize_t)iret);
+			return -1;
+		}
+
+		if (ssl_retries >= SSL_IO_MAX_RETRIES) {
+			upslogx(LOG_ERR, "%s: SSL_write timed out after %d retries", __func__, ssl_retries);
+			return -1;
+		}
 # elif defined(WITH_NSS) /* WITH_OPENSSL */
 		/* PR_* routines deal in PRInt32 type
 		 * We might need to window our I/O if we exceed 2GB :) */
@@ -938,13 +1036,14 @@ static int upscli_sslinit(UPSCONN_t *ups, int verifycert)
 		int	ssl_retries = 0;
 		/* Cap retries to avoid spinning forever on a broken socket.
 		 * 250 * 20 ms = 5 s maximum wait, which is generous for a
-		 * local handshake while being safe for CI timeouts.        */
-		const int	SSL_CONNECT_MAX_RETRIES = 250;
+		 * local handshake while being safe for CI timeouts.
+		 */
+		const int	SSL_IO_MAX_RETRIES = 250;
 		fd_set	fds;
 		struct timeval	tv;
 
 		res = -1;
-		while (ssl_retries < SSL_CONNECT_MAX_RETRIES) {
+		while (ssl_retries < SSL_IO_MAX_RETRIES) {
 			res = SSL_connect(ups->ssl);
 
 			if (res == 1) {
@@ -972,7 +1071,7 @@ static int upscli_sslinit(UPSCONN_t *ups, int verifycert)
 					(ssl_err == SSL_ERROR_WANT_READ)
 						? "READ" : "WRITE",
 					ssl_retries + 1,
-					SSL_CONNECT_MAX_RETRIES);
+					SSL_IO_MAX_RETRIES);
 
 				if (select(ups->fd + 1,
 					(ssl_err == SSL_ERROR_WANT_READ)  ? &fds : NULL,
@@ -982,6 +1081,9 @@ static int upscli_sslinit(UPSCONN_t *ups, int verifycert)
 					upsdebug_with_errno(1,
 						"%s: select() failed during SSL_connect",
 						__func__);
+					/* Returns 0 on non-fatal WANT_READ/WRITE;
+					 * we stop retrying even if non-fatal because
+					 * select() itself failed. */
 					ssl_error(ups->ssl, res);
 					return -1;
 				}
@@ -1005,7 +1107,7 @@ static int upscli_sslinit(UPSCONN_t *ups, int verifycert)
 			return -1;
 		}
 
-		if (ssl_retries >= SSL_CONNECT_MAX_RETRIES) {
+		if (ssl_retries >= SSL_IO_MAX_RETRIES) {
 			upslogx(LOG_ERR,
 				"%s: SSL_connect timed out after %d retries"
 				" (non-blocking handshake never completed)",

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3696 utf-8
+personal_ws-1.1 en 3697 utf-8
 AAC
 AAS
 ABI
@@ -1224,6 +1224,7 @@ SPLY
 SPS
 SRC
 SSD
+SSLContext
 SSSS
 STARTTLS
 STATUSCOLOR

scripts/python/module/PyNUT.py.in

@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 
 #   Copyright (C) 2008 David Goncalves <david@lestat.st>
+#   Copyright (C) 2021-2026 Jim Klimov <jimklimov+nut@gmail.com>
 #
 #   This program is free software: you can redistribute it and/or modify
 #   it under the terms of the GNU General Public License as published by
@@ -63,51 +64,105 @@
 #
 # 2025-01-31 cgar <github.com/cgarz> - Version 1.8.0
 #            Removed telnetlib dependency. Switched to using socket directly.
+#
+# 2026-03-16 Jim Klimov <jimklimov+nut@gmail.com> - Version 1.9.0
+#            Implement selectable OpenSSL and NSS client support via
+#            NUT STARTTLS protocol action.
 
 import socket
 
+ssl_available = False
+try:
+    import ssl
+    ssl_available = True
+except:
+    pass
+
 class PyNUTError( Exception ) :
     """ Base class for custom exceptions """
 
 
 class PyNUTClient :
     """ Abstraction class to access NUT (Network UPS Tools) server """
 
-    __debug       = None   # Set class to debug mode (prints everything useful for debuging...)
+    __debug       = None   # Set class to debug mode (prints everything useful for debugging...)
     __host        = None
     __port        = None
     __login       = None
     __password    = None
     __timeout     = None
     __srv_handler = None
     __recv_leftover = b''
+    # Subject to global ssl_available:
+    __use_ssl     = False
+    __ssl_context = None
 
-    __version     = "1.8.0"
-    __release     = "2025-02-07"
+    __version     = "1.9.0"
+    __release     = "2026-03-16"
 
 
-    def __init__( self, host="127.0.0.1", port=3493, login=None, password=None, debug=False, timeout=5 ) :
+    def __init__( self, host="127.0.0.1", port=3493, login=None, password=None, debug=False, timeout=5,
+                  use_ssl=False, ssl_context=None, cert_verify=None, ca_file=None, ca_path=None,
+                  cert_file=None, key_file=None, key_pass=None, force_ssl=False ) :
         """ Class initialization method
 
-host     : Host to connect (default to localhost)
-port     : Port where NUT listens for connections (default to 3493)
-login    : Login used to connect to NUT server (default to None for no authentication)
-password : Password used when using authentication (default to None)
-debug    : Boolean, put class in debug mode (prints everything on console, default to False)
-timeout  : Timeout used to wait for network response
+host        : Host to connect (default to localhost)
+port        : Port where NUT listens for connections (default to 3493)
+login       : Login used to connect to NUT server (default to None for no authentication)
+password    : Password used when using authentication (default to None)
+debug       : Boolean, put class in debug mode (prints everything on console, default to False)
+timeout     : Timeout used to wait for network response
+use_ssl     : Boolean, use SSL/TLS for connection (default to False; subject to 'ssl' module availability)
+ssl_context : ssl.SSLContext object to use for SSL/TLS connection (default to None; subject to 'ssl' module availability)
+cert_verify : Boolean, verify server certificate (default to None, which means True if CA info is provided)
+ca_file     : Path to CA certificate file (PEM format)
+ca_path     : Path to directory with CA certificates (PEM format)
+cert_file   : Path to client certificate file (PEM format)
+key_file    : Path to client private key file (PEM format)
+key_pass    : Password for client private key file (default to None)
+force_ssl   : Boolean, if True, the connection must be secure (default to False)
         """
         self.__debug = debug
 
         if self.__debug :
             print( "[DEBUG] Class initialization..." )
             print( "[DEBUG]  -> Host  = %s (port %s)" % ( host, port ) )
             print( "[DEBUG]  -> Login = '%s' / '%s'" % ( login, password ) )
-
-        self.__host     = host
-        self.__port     = port
-        self.__login    = login
-        self.__password = password
-        self.__timeout  = timeout
+            print( "[DEBUG]  -> SSL   = %s (force: %s, verify: %s)" % (use_ssl, force_ssl, cert_verify) )
+
+        self.__host        = host
+        self.__port        = port
+        self.__login       = login
+        self.__password    = password
+        self.__timeout     = timeout
+        if ssl_available:
+            self.__use_ssl     = use_ssl or force_ssl
+            self.__force_ssl   = force_ssl
+            self.__ssl_context = ssl_context
+            if self.__use_ssl and self.__ssl_context is None:
+                if self.__debug:
+                    print( "[DEBUG] Creating SSL context" )
+                # Create a default context and apply parameters
+                self.__ssl_context = ssl.create_default_context(cafile=ca_file, capath=ca_path)
+                if cert_verify is not None:
+                    if not cert_verify:
+                        # Must be set first, else we get
+                        #   ValueError: Cannot set verify_mode to CERT_NONE when check_hostname is enabled.
+                        self.__ssl_context.check_hostname = False
+                    self.__ssl_context.verify_mode = ssl.CERT_REQUIRED if cert_verify else ssl.CERT_NONE
+                if cert_file:
+                    self.__ssl_context.load_cert_chain(certfile=cert_file, keyfile=key_file, password=key_pass)
+                if self.__debug:
+                    print( "[DEBUG] SSL context created")
+        else:
+            self.__use_ssl     = False
+            self.__force_ssl   = False
+            self.__ssl_context = None
+            if (use_ssl or force_ssl or ssl_context is not None):
+                if self.__debug:
+                    print( "[DEBUG] SSL requested but 'ssl' module was not available for import" )
+                if force_ssl:
+                    raise PyNUTError( "SSL required but 'ssl' module not available" )
 
         self.__connect()
 
@@ -150,6 +205,30 @@ if something goes wrong.
             self.__timeout
         )
 
+        if self.__use_ssl :
+            if self.__debug :
+                print( "[DEBUG] Requesting STARTTLS" )
+            self.__srv_handler.send( b"STARTTLS\n" )
+            result = self.__read_until( b"\n" )
+            if result[:11] == b"OK STARTTLS" :
+                if self.__debug :
+                    print( "[DEBUG] STARTTLS accepted, wrapping socket" )
+                if self.__ssl_context is None :
+                    self.__ssl_context = ssl.create_default_context()
+                self.__srv_handler = self.__ssl_context.wrap_socket(
+                    self.__srv_handler,
+                    server_hostname=self.__host
+                )
+            else :
+                if self.__debug :
+                    print( "[DEBUG] STARTTLS failed: %s" % result )
+                if self.__force_ssl:
+                    raise PyNUTError( "STARTTLS failed but SSL is required: %s" % result.replace( b"\n", b"" ).decode('ascii') )
+                else:
+                    if self.__debug:
+                        print( "[DEBUG] STARTTLS failed, but not forced, continuing insecurely" )
+                    self.__use_ssl = False
+
         if self.__login != None :
             self.__srv_handler.send( ("USERNAME %s\n" % self.__login).encode('ascii') )
             result = self.__read_until( b"\n" )