From 278663ad2c73d97d37e2211a610b36a955300192 Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Thu, 4 Jan 2018 08:47:37 +1000 Subject: [PATCH] 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 | 47 ++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/windows_winrm.rst b/docs/docsite/rst/windows_winrm.rst index 8f43990619..aaca984a26 100644 --- a/docs/docsite/rst/windows_winrm.rst +++ b/docs/docsite/rst/windows_winrm.rst @@ -17,7 +17,7 @@ Ansible uses the `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 `_. + +.. 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