windows: updated docs to include info regarding https validation (#34128)

* updated docs to include info regarding https validation

* some doc edits

docs/docsite/rst/windows_winrm.rst

@@ -17,7 +17,7 @@ Ansible uses the `pywinrm <https://github.com/diyan/pywinrm>`_ package to
 communicate with Windows servers over WinRM. It is not installed by default
 with the Ansible package, but can be installed by running the following::
 
-   pip install "pywinrm>=0.2.2"
+   pip install "pywinrm>=0.3.0"
 
 .. Note:: on distributions with multiple python versions, use pip2 or pip2.x,
     where x matches the python minor version Ansible is running under.
@@ -279,7 +279,7 @@ There are some extra host variables that can be set::
 
     ansible_winrm_kinit_mode: managed/manual (manual means Ansible will not obtain a ticket)
     ansible_winrm_kinit_cmd: the kinit binary to use to obtain a Kerberos ticket (default to kinit)
-    ansible_winrm_keytab: the path to the keytab file
+    ansible_winrm_service: overrides the SPN prefix that is used, the default is ``HTTP`` and should rarely ever need changing
     ansible_winrm_kerberos_delegation: allows the credentials to traverse multiple hops
     ansible_winrm_kerberos_hostname_override: the hostname to be used for the kerberos exchange
 
@@ -639,6 +639,15 @@ for additional configuration of WinRM connections:
   message encryption. ``always`` means message encryption will always be used
   and ``never`` means message encryption will never be used
 
+* ``ansible_winrm_ca_trust_path``: Used to specify a different cacert container
+  than the one used in the ``certifi`` module. See the HTTPS Certificate
+  Validation section for more details.
+
+* ``ansible_winrm_send_cbt``: When using ``ntlm`` or ``kerberos`` over HTTPS,
+  the authentication library will try to send channel binding tokens to
+  mitigate against man in the middle attacks. This flag controls whether these
+  bindings will be sent or not (default: ``True``).
+
 * ``ansible_winrm_*``: Any additional keyword arguments supported by
   ``winrm.Protocol`` may be provided in place of ``*``
 
@@ -679,6 +688,40 @@ would an IPv4 address or hostname::
     use IPv6 addresses in Python 2.6 and 2.7, make sure to run
     ``pip install ipaddress`` which installs a backported package.
 
+HTTPS Certificate Validation
+````````````````````````````
+As part of the TLS protocol, the certificate is validated to ensure the host
+matches the subject and the client trusts the issuer of the server certificate.
+When using a self-signed certificate or setting
+``ansible_winrm_server_cert_validation: ignore`` these security mechanisms are
+bypassed. While self signed certificates will always need the ``ignore`` flag,
+certificates that have been issued from a certificate authority can still be
+validated.
+
+One of the more common ways of setting up a HTTPS listener in a domain
+environment is to use Active Directory Certificate Service (AD CS). AD CS is
+used to generate signed certificates from a Certificate Signing Request (CSR).
+If the WinRM HTTPS listener is using a certificate that has been signed by
+another authority, like AD CS, then Ansible can be set up to trust that
+issuer as part of the TLS handshake.
+
+To get Ansible to trust a Certificate Authority (CA) like AD CS, the issuer
+certificate of the CA can be exported as a PEM encoded certificate. This
+certificate can then be copied locally to the Ansible controller and used as a
+source of certificate validation, otherwise known as a CA chain.
+
+The CA chain can contain a single or multiple issuer certificates and each
+entry is contained on a new line. To then use the custom CA chain as part of
+the validation process, set ``ansible_winrm_ca_trust_path`` to the path of the
+file. If this variable is not set, the default CA chain is used instead which
+is located in the install path of the Python package
+`certifi <https://github.com/certifi/python-certifi>`_.
+
+.. Note:: Each HTTP call is done by the Python requests library which does not
+    use the systems built-in certificate store as a trust authority.
+    Certificate validation will fail if the server's certificate issuer is
+    only added to the system's truststore.
+
 Limitations
 ```````````
 Due to the design of the WinRM protocol , there are a few limitations