1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2016, Ansible, inc 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7DOCUMENTATION = r''' 8--- 9module: win_certificate_info 10short_description: Get information on certificates from a Windows Certificate Store 11description: 12- Returns information about certificates in a Windows Certificate Store. 13options: 14 thumbprint: 15 description: 16 - The thumbprint as a hex string of a certificate to find. 17 - When specified, filters the I(certificates) return value to a single certificate 18 - See the examples for how to format the thumbprint. 19 type: str 20 required: no 21 store_name: 22 description: 23 - The name of the store to search. 24 - See U(https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.storename) 25 for a list of built-in store names. 26 type: str 27 default: My 28 store_location: 29 description: 30 - The location of the store to search. 31 type: str 32 choices: [ CurrentUser, LocalMachine ] 33 default: LocalMachine 34seealso: 35- module: ansible.windows.win_certificate_store 36author: 37- Micah Hunsberger (@mhunsber) 38''' 39 40EXAMPLES = r''' 41- name: Obtain information about a particular certificate in the computer's personal store 42 community.windows.win_certificate_info: 43 thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27 44 register: mycert 45 46# thumbprint can also be lower case 47- name: Obtain information about a particular certificate in the computer's personal store 48 community.windows.win_certificate_info: 49 thumbprint: bd7af104cf1872bdb518d95c9534ea941665fd27 50 register: mycert 51 52- name: Obtain information about all certificates in the root store 53 community.windows.win_certificate_info: 54 store_name: Root 55 register: ca 56 57# Import a pfx and then get information on the certificates 58- name: Import pfx certificate that is password protected 59 ansible.windows.win_certificate_store: 60 path: C:\Temp\cert.pfx 61 state: present 62 password: VeryStrongPasswordHere! 63 become: yes 64 become_method: runas 65 register: mycert 66 67- name: Obtain information on each certificate that was touched 68 community.windows.win_certificate_info: 69 thumbprint: "{{ item }}" 70 register: mycert_stats 71 loop: "{{ mycert.thumbprints }}" 72''' 73 74RETURN = r''' 75exists: 76 description: 77 - Whether any certificates were found in the store. 78 - When I(thumbprint) is specified, returns true only if the certificate mathing the thumbprint exists. 79 returned: success 80 type: bool 81 sample: true 82certificates: 83 description: 84 - A list of information about certificates found in the store, sorted by thumbprint. 85 returned: success 86 type: list 87 elements: dict 88 contains: 89 archived: 90 description: Indicates that the certificate is archived. 91 type: bool 92 sample: false 93 dns_names: 94 description: Lists the registered dns names for the certificate. 95 type: list 96 elements: str 97 sample: [ '*.m.wikiquote.org', '*.wikipedia.org' ] 98 extensions: 99 description: The collection of the certificates extensions. 100 type: list 101 elements: dict 102 sample: [ 103 { 104 "critical": false, 105 "field": "Subject Key Identifier", 106 "value": "88 27 17 09 a9 b6 18 60 8b ec eb ba f6 47 59 c5 52 54 a3 b7" 107 }, 108 { 109 "critical": true, 110 "field": "Basic Constraints", 111 "value": "Subject Type=CA, Path Length Constraint=None" 112 }, 113 { 114 "critical": false, 115 "field": "Authority Key Identifier", 116 "value": "KeyID=2b d0 69 47 94 76 09 fe f4 6b 8d 2e 40 a6 f7 47 4d 7f 08 5e" 117 }, 118 { 119 "critical": false, 120 "field": "CRL Distribution Points", 121 "value": "[1]CRL Distribution Point: Distribution Point Name:Full Name:URL=http://crl.apple.com/root.crl" 122 }, 123 { 124 "critical": true, 125 "field": "Key Usage", 126 "value": "Digital Signature, Certificate Signing, Off-line CRL Signing, CRL Signing (86)" 127 }, 128 { 129 "critical": false, 130 "field": null, 131 "value": "05 00" 132 } 133 ] 134 friendly_name: 135 description: The associated alias for the certificate. 136 type: str 137 sample: Microsoft Root Authority 138 has_private_key: 139 description: Indicates that the certificate contains a private key. 140 type: bool 141 sample: false 142 intended_purposes: 143 description: lists the intended applications for the certificate. 144 returned: enhanced key usages extension exists. 145 type: list 146 sample: [ "Server Authentication" ] 147 is_ca: 148 description: Indicates that the certificate is a certificate authority (CA) certificate. 149 returned: basic constraints extension exists. 150 type: bool 151 sample: true 152 issued_by: 153 description: The certificate issuer's common name. 154 type: str 155 sample: Apple Root CA 156 issued_to: 157 description: The certificate's common name. 158 type: str 159 sample: Apple Worldwide Developer Relations Certification Authority 160 issuer: 161 description: The certificate issuer's distinguished name. 162 type: str 163 sample: 'CN=Apple Root CA, OU=Apple Certification Authority, O=Apple Inc., C=US' 164 key_usages: 165 description: 166 - Defines how the certificate key can be used. 167 - If this value is not defined, the key can be used for any purpose. 168 returned: key usages extension exists. 169 type: list 170 elements: str 171 sample: [ "CrlSign", "KeyCertSign", "DigitalSignature" ] 172 path_length_constraint: 173 description: 174 - The number of levels allowed in a certificates path. 175 - If this value is 0, the certificate does not have a restriction. 176 returned: basic constraints extension exists 177 type: int 178 sample: 0 179 public_key: 180 description: The base64 encoded public key of the certificate. 181 type: str 182 cert_data: 183 description: The base64 encoded data of the entire certificate. 184 type: str 185 serial_number: 186 description: The serial number of the certificate represented as a hexadecimal string 187 type: str 188 sample: 01DEBCC4396DA010 189 signature_algorithm: 190 description: The algorithm used to create the certificate's signature 191 type: str 192 sample: sha1RSA 193 ski: 194 description: The certificate's subject key identifier 195 returned: subject key identifier extension exists. 196 type: str 197 sample: 88271709A9B618608BECEBBAF64759C55254A3B7 198 subject: 199 description: The certificate's distinguished name. 200 type: str 201 sample: 'CN=Apple Worldwide Developer Relations Certification Authority, OU=Apple Worldwide Developer Relations, O=Apple Inc., C=US' 202 thumbprint: 203 description: 204 - The thumbprint as a hex string of the certificate. 205 - The return format will always be upper case. 206 type: str 207 sample: FF6797793A3CD798DC5B2ABEF56F73EDC9F83A64 208 valid_from: 209 description: The start date of the certificate represented in seconds since epoch. 210 type: float 211 sample: 1360255727 212 valid_from_iso8601: 213 description: The start date of the certificate represented as an iso8601 formatted date. 214 type: str 215 sample: '2017-12-15T08:39:32Z' 216 valid_to: 217 description: The expiry date of the certificate represented in seconds since epoch. 218 type: float 219 sample: 1675788527 220 valid_to_iso8601: 221 description: The expiry date of the certificate represented as an iso8601 formatted date. 222 type: str 223 sample: '2086-01-02T08:39:32Z' 224 version: 225 description: The x509 format version of the certificate 226 type: int 227 sample: 3 228''' 229