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