# salt.modules.win_pki

Microsoft certificate management via the PKI Client PowerShell module. https://technet.microsoft.com/en-us/itpro/powershell/windows/pkiclient/pkiclient

The PKI Client PowerShell module is only available on Windows 8+ and Windows Server 2012+. https://technet.microsoft.com/en-us/library/hh848636(v=wps.620).aspx

platform:

  Windows

depends:

  - PowerShell 4

  - PKI Client Module (Windows 8+ / Windows Server 2012+)

Added in version 2016.11.0.

salt.modules.win_pki.export_cert(name, thumbprint, cert_format='cer', context='LocalMachine', store='My', password='')

  Export the certificate to a file from the given certificate store.

  Parameters:

    - name (str) -- The destination path for the exported certificate file.

    - thumbprint (str) -- The thumbprint value of the target certificate.

    - cert_format (`str`, optional) --

      The certificate format. Specify 'cer' for X.509, or 'pfx' for PKCS #12.

      Default is "cer"

    - context (`str`, optional) --

      The name of the certificate store location context.

      Default is "LocalMachine"

    - store (`str`, optional) --

      The name of the certificate store.

      Default is "My"

    - password (`str`, optional) --

      The password of the certificate. Only applicable to pfx format. Note that if used interactively, the password will be seen by all minions. To protect the password, use a state and get the password from pillar.

      Default is "".

  Returns:

    A boolean representing whether all changes succeeded.

  Return type:

    bool

  CLI Example:

      salt '*' win_pki.export_cert name='C:\certs\example.cer' thumbprint='AAA000'

salt.modules.win_pki.get_cert_file(name, cert_format='cer', password='')

  Get the details of the certificate file.

  Parameters:

    - name (str) -- The filesystem path of the certificate file.

    - cert_format (`str`, optional) --

      The certificate format. Specify 'cer' for X.509, or 'pfx' for PKCS #12.

      Default is "cer"

    - password (`str`, optional) --

      The password of the certificate. Only applicable to pfx format. Note that if used interactively, the password will be seen by all minions. To protect the password, use a state and get the password from pillar.

      Default is "".

  Returns:

    A dictionary of the certificate thumbprints and properties.

  Return type:

    dict

  CLI Example:

      salt '*' win_pki.get_cert_file name='C:\certs\example.cer'

salt.modules.win_pki.get_certs(context='LocalMachine', store='My')

  Get the available certificates in the given store.

  Parameters:

    - context (`str`, optional) --

      The name of the certificate store location context.

      Default is "LocalMachine"

    - store (`str`, optional) --

      The name of the certificate store.

      Default is "My"

  Returns:

    A dictionary of the certificate thumbprints and properties.

  Return type:

    dict

  CLI Example:

      salt '*' win_pki.get_certs

salt.modules.win_pki.get_stores()

  Get the certificate location contexts and their corresponding stores.

  Returns:

    A dictionary of the certificate location contexts and stores.

  Return type:

    dict

  CLI Example:

      salt '*' win_pki.get_stores

salt.modules.win_pki.import_cert(name, cert_format='cer', context='LocalMachine', store='My', exportable=True, password='', saltenv='base')

  Import the certificate file into the given certificate store.

  Parameters:

    - name (str) -- The path of the certificate file to import.

    - cert_format (`str`, optional) --

      The certificate format. Specify 'cer' for X.509, or 'pfx' for PKCS #12.

      Default is "cer"

    - context (`str`, optional) --

      The name of the certificate store location context.

      Default is "LocalMachine"

    - store (str) --

      The name of the certificate store.

      Default is "My"

    - exportable (`bool`, optional) --

      Mark the certificate as exportable. Only applicable to pfx format.

      Default is `True`.

    - password (`str`, optional) --

      The password of the certificate. Only applicable to pfx format. Note that if used interactively, the password will be seen by all minions. To protect the password, use a state and get the password from pillar.

      Default is "".

    - saltenv (`str`, optional) --

      The environment the file resides in.

      Default is "base".

  Returns:

    A boolean representing whether all changes succeeded.

  Return type:

    bool

  CLI Example:

      salt '*' win_pki.import_cert name='salt://cert.cer'

salt.modules.win_pki.remove_cert(thumbprint, context='LocalMachine', store='My')

  Remove the certificate from the given certificate store.

  Parameters:

    - thumbprint (str) -- The thumbprint value of the target certificate.

    - context (`str`, optional) --

      The name of the certificate store location context.

      Default is "LocalMachine".

    - store (`str`, optional) --

      The name of the certificate store.

      Default is "My"

  Returns:

    A boolean representing whether all changes succeeded.

  Return type:

    bool

  CLI Example:

      salt '*' win_pki.remove_cert thumbprint='AAA000'

salt.modules.win_pki.test_cert(thumbprint, context='LocalMachine', store='My', untrusted_root=False, dns_name='', eku='')

  Check the certificate for validity.

  Parameters:

    - thumbprint (str) -- The thumbprint value of the target certificate.

    - context (`str`, optional) --

      The name of the certificate store location context.

      Default is "LocalMachine"

    - store (`str`, optional) --

      The name of the certificate store.

      Default is "My"

    - untrusted_root (`bool`, optional) --

      Whether the root certificate is required to be trusted in chain building.

      Default is `False`.

    - dns_name (`str`, optional) --

      The DNS name to verify as valid for the certificate.

      Default is "".

    - eku (`str`, optional) --

      The enhanced key usage object identifiers to verify for the certificate chain.

      Default is "".

  Returns:

    A boolean representing whether the certificate was considered

      valid.

  Return type:

    bool

  CLI Example:

      salt '*' win_pki.test_cert thumbprint='AAA000' dns_name='example.test'