DSCResources/DSC_PfxImport/en-US/about_PfxImport.help.txt

.NAME
    PfxImport
 
.DESCRIPTION
    The resource is used to import a PFX certificate into a Windows certificate
    store.
 
    ## Credentials for Importing a Private Key
 
    Depending on your operating system and domain configuration, you may need to
    use a local or domain administrator credential to import certificates with a
    private key. To do this, set the PsDscRunAsCredential parameter with this
    resource to the credential of a local or domain administrator for this machine.
 
    If you still have problems importing the PFX into the Local Machine store
    please check the account specified in PsDscRunAsCredential has permissions
    to $env:SystemDrive:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys.
    See https://docs.microsoft.com/en-us/troubleshoot/iis/cannot-import-ssl-pfx-local-certificate
    for more information.
 
    ## Requirements
 
    - Target machine must be running Windows Server 2008 R2 or later.
    - To import a certificate exported using AES256_SHA256 cryptographic
      algorithm, the target machine must be running build 1709 or later of
      Windows 10 or Windows Server 2016.
 
      If importing a PFX certificate exported with AES256_SHA256 cryptographic
      algorithm on a target machine running a Windows 10 or Windows Server 2016
      build earlier than 1709, the following error will occur:
 
      `The PFX file you are trying to import requires either a different password
      or membership in an Active Directory principal to which it is protected.`
 
.PARAMETER Thumbprint
    Key - String
    The thumbprint (unique identifier) of the PFX file you're importing.
 
.PARAMETER Path
    Write - String
    The path to the PFX file you want to import.
 
.PARAMETER Content
    Write - String
    The base64 encoded content of the PFX file you want to import.
 
.PARAMETER Location
    Key - String
    Allowed values: LocalMachine, CurrentUser
    The Windows Certificate Store Location to import the PFX file to.
 
.PARAMETER Store
    Key - String
    The Windows Certificate Store Name to import the PFX file to.
 
.PARAMETER Exportable
    Write - Boolean
    Determines whether the private key is exportable from the machine after it has been imported
 
.PARAMETER Credential
    Write - Instance
    A PSCredential object that is used to decrypt the PFX file.
 
.PARAMETER Ensure
    Write - String
    Allowed values: Present, Absent
    Specifies whether the PFX file should be present or absent.
 
.PARAMETER FriendlyName
    Write - String
    The friendly name of the certificate to set in the Windows Certificate Store.
 
.EXAMPLE 1
 
Import a PFX into the 'WebHosting' Local Machine certificate store and
bind it to an IIS Web Site.
 
Configuration PfxImport_InstallPFXForWebSite_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -ModuleName CertificateDsc
    Import-DscResource -ModuleName xWebAdministration -ModuleVersion 3.1.1
 
    Node localhost
    {
        WindowsFeature IIS
        {
            Ensure = 'Present'
            Name = 'Web-Server'
        }
 
        PfxImport CompanyCert
        {
            Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
            Path = '\\Server\Share\Certificates\CompanyCert.pfx'
            Location = 'LocalMachine'
            Store = 'WebHosting'
            Credential = $Credential
            DependsOn = '[WindowsFeature]IIS'
        }
 
        xWebsite CompanySite
        {
            Ensure = 'Present'
            Name = 'CompanySite'
            State = 'Started'
            PhysicalPath = "B:\Web\CompanySite"
            ApplicationPool = "CompanyPool"
            BindingInfo =
                    MSFT_xWebBindingInformation {
                        Protocol = 'HTTPS'
                        Port = 443
                        CertificateThumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
                        CertificateStoreName = 'WebHosting'
                        HostName = "www.example.com"
                    }
            DependsOn = '[WindowsFeature]IIS','[PfxImport]CompanyCert'
        }
    }
}
 
.EXAMPLE 2
 
Import a PFX into the 'My' Local Machine certificate store.
 
Configuration PfxImport_InstallPFX_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -ModuleName CertificateDsc
 
    Node localhost
    {
        PfxImport CompanyCert
        {
            Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
            Path = '\\Server\Share\Certificates\CompanyCert.pfx'
            Location = 'LocalMachine'
            Store = 'My'
            Credential = $Credential
        }
    }
}
 
.EXAMPLE 3
 
Remove a PFX certificate from the 'My' Local Machine certificate store.
 
Configuration PfxImport_RemovePFX_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -ModuleName CertificateDsc
 
    Node localhost
    {
        PfxImport CompanyCert
        {
            Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
            Location = 'LocalMachine'
            Store = 'My'
            Credential = $Credential
            Ensure = 'Absent'
        }
    }
}
 
.EXAMPLE 4
 
Import a PFX into the 'My' Local Machine certificate store and
set the Fiendly Name to 'Web Site Certificate'.
 
Configuration PfxImport_FriendlyName_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -ModuleName CertificateDsc
 
    Node localhost
    {
        PfxImport CompanyCert
        {
            Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
            Path = '\\Server\Share\Certificates\CompanyCert.pfx'
            Location = 'LocalMachine'
            Store = 'My'
            Credential = $Credential
            FriendlyName = 'Web Site Certificate'
        }
    }
}
 
.EXAMPLE 5
 
Import a PFX into the 'Root' Local Machine certificate store using
an administrator credential. The password in the Credential parameter
is used to decrypt the PFX file and the PsDscRunAsCredential is the
account that is used to import the certificate and private key into
Local Machine store. The PsDscRunAsCredential must have permission
to import the certificate and private key.
 
Configuration PfxImport_InstallPFXAdministrator_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential,
 
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $AdminCredential
    )
 
    Import-DscResource -ModuleName CertificateDsc
 
    Node localhost
    {
        PfxImport CompanyCert
        {
            Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
            Path = '\\Server\Share\Certificates\CompanyCert.pfx'
            Location = 'LocalMachine'
            Store = 'Root'
            Credential = $Credential
            PsDscRunAsCredential = $AdminCredential
        }
    }
}
 
.EXAMPLE 6
 
Import a PFX into the 'My' Local Machine certificate store.
 
Configuration PfxImport_InstallPFXFromContent_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullorEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -ModuleName CertificateDsc
 
    <#
        Create mock base64 value
        example for converting an existing file:
        $contentBase64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes($certificateFilePath))
    #>
    $contentBase64 = [System.Convert]::ToBase64String(@(00, 00, 00))
 
    Node localhost
    {
        PfxImport CompanyCert
        {
            Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
            Content = $contentBase64
            Location = 'LocalMachine'
            Store = 'My'
            Credential = $Credential
        }
    }
}