doc: S7CommPlus-over-TLS and password-auth sections

doc/connecting.rst

@@ -99,6 +99,88 @@ when needed. You can also force a specific protocol:
 
 See :doc:`API/client` for details on TLS and password authentication.
 
+S7CommPlus over TLS (V2/V3, TIA Portal V17+)
+---------------------------------------------
+
+S7-1500 firmware ≥ V2.9 and S7-1200 firmware ≥ V4.5 negotiate
+S7CommPlus V2 or V3, which transports the protocol inside a TLS 1.3
+session. Pass ``use_tls=True`` to ``connect`` to activate it:
+
+.. code-block:: python
+
+   from s7 import Client, Protocol
+
+   client = Client()
+   client.connect(
+       "192.168.1.10", rack=0, slot=1,
+       protocol=Protocol.S7COMMPLUS,
+       use_tls=True,
+   )
+   data = client.db_read(1, 0, 4)
+   client.disconnect()
+
+The client wraps the ISO-on-TCP socket with TLS 1.3 between the
+``InitSSL`` exchange and the ``CreateObject`` request. By default the
+PLC's certificate is not verified — fine for development, not fine in
+production. To verify the PLC against a CA bundle, pass ``tls_ca``:
+
+.. code-block:: python
+
+   client.connect(
+       "192.168.1.10", rack=0, slot=1,
+       protocol=Protocol.S7COMMPLUS,
+       use_tls=True,
+       tls_ca="/path/to/plc-ca.pem",
+   )
+
+If the PLC requires mutual TLS (client-side certificate), supply
+``tls_cert`` and ``tls_key`` as well.
+
+The ``cryptography`` package is required for TLS support. Install
+with the ``s7commplus`` extra:
+
+.. code-block:: bash
+
+   pip install 'python-snap7[s7commplus]'
+
+.. note::
+
+   Older S7-1200 firmware (FW < 4.5) negotiates V1 of the S7CommPlus
+   protocol, which predates TLS and uses a different proprietary
+   handshake. ``Client(...)`` falls back transparently to legacy
+   PUT/GET on those PLCs (``db_read`` / ``db_write`` work);
+   ``browse()`` and other CommPlus-only operations are not yet
+   supported on those firmwares — see issue #710.
+
+PLC Password Authentication
+----------------------------
+
+If the PLC has a password configured (``Full access (no protection)``
+disabled in TIA Portal), call ``authenticate`` after ``connect``:
+
+.. code-block:: python
+
+   from s7 import Client, Protocol
+
+   client = Client()
+   client.connect(
+       "192.168.1.10", rack=0, slot=1,
+       protocol=Protocol.S7COMMPLUS,
+       use_tls=True,
+   )
+   client.authenticate(password="hunter2")
+   data = client.db_read(1, 0, 4)
+
+Authentication requires TLS to be active (``use_tls=True``). The
+client auto-detects whether the PLC firmware uses the legacy SHA-1
+challenge or the newer AES-256-CBC challenge. For accounts with a
+username (TIA Portal V17+ user-based access control), pass it
+explicitly:
+
+.. code-block:: python
+
+   client.authenticate(password="hunter2", username="operator")
+
 S7-200 / Logo (TSAP Connection)
 --------------------------------