DSCResources/DSC_PfxImport/en-US/about_PfxImport.help.txt
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 |
.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 } } } |