Install-CertificationAuthority
Synopsis
Installs Active Directory Certificate Services role on local computer.
Syntax
Install-CertificationAuthority [-CAName <String>] [-CADNSuffix <String>] [-CAType <String> {Standalone Root | Standalone Subordinate | Enterprise Root | Enterprise Subordinate} ] [-ParentCA <String>] [-CSP <String>] [-KeyLength <Int32>] [-HashAlgorithm <String>] [-ValidForYears <Int32>] [-RequestFileName <String>] [-DBDirectory <String>] [-LogDirectory <String>] [-OverwriteExisting] [-AllowCSPInteraction] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Install-CertificationAuthority -CACertFile <FileInfo> -Password <SecureString> [-DBDirectory <String>] [-LogDirectory <String>] [-OverwriteExisting] [-AllowCSPInteraction] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Install-CertificationAuthority -Thumbprint <String> [-DBDirectory <String>] [-LogDirectory <String>] [-OverwriteExisting] [-AllowCSPInteraction] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Description
Installs Active Directory Certificate Services (AD CS) role on local computer. A user can choose different options, such Certification Authority (CA) type, key pair parameters, CA certificate validity and so on.
The command supports Windows Server 2008 R2 Server Core installations.
Parameters
-CAName <String>
Specifies a custom CA certificate name/subject (what you see in the certificate display UI). If not passed, a '<ComputerName>-CA' form is used for workgroup CAs and '<DomainName>-<ComputerName-CA>' form is used for domain CAs. The parameter supports Unicode names.
Note: common name must not contain comma (,) character, because it is reserved as a RDN attribute delimeter.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-CADNSuffix <String>
Specifies a DN suffix to specify some additional information. For example, company name, country, city, etc. DN suffix is empty for workgroup CAs and includes current domain distinguished name (for example, 'DC=domain, DC=com'). The parameter accepts suffixes in a X500 form, for example: OU=Information Systems, O=Sysadmins LV, C=LV.
Note: common name must use comma as RDN attribute separator. Commas inside the RDN attribute are not allowed.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-CAType <String>
Specifies CA type:
Standalone Root,
Standalone Subordinate,
Enterprise Root,
Enterprise Subordinate.
If not passed, for non-domain environments or if you don't have Enterprise Admins rights, Standalone Root is used. If you have Enterprise Admins rights and your forest already has installed CAs, Enterprise Subordinate is used. If no Enterprise CAs installed in the forest, Enterprise Root is used.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-ParentCA <String>
This parameter allows you to specify parent CA location only if you install Enterprise Subordinate CA. For other CA types, the parameter is ignored. Parent CA information must be passed in the following form: CAComputerName\CASanitizedName. Sanitized name is a sanitized form of CA name (subject). Mostly sanitized name is the same as CA name (unless you use Unicode and/or special characters, that are disallowed in X500). If the parameter is not specified, a certificate request will be generated on the root of system drive. If selected CA type is Standalone Subordinate, the parameter is ignored. Request will be saved in a file.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-CSP <String>
Specifies custom cryptographic service provider. By default 'RSA#Microsoft Software Key Storage Provider' is used (in most cases you will use default CSP). You need to explicitly specify custom CSP only when you setup completely CNG authority (CSPs with ECDSA prefix) or you use HSM. Each HSM uses its own custom CSP. You must install HSM middleware before CA installation.
The full list of supported and available "by default" CSPs for Windows Server 2008+ is:
Microsoft Base Cryptographic Provider v1.0
Microsoft Base DSS Cryptographic Provider
Microsoft Base Smart Card Crypto Provider
Microsoft Enhanced Cryptographic Provider v1.0
Microsoft Strong Cryptographic Provider
RSA#Microsoft Software Key Storage Provider
DSA#Microsoft Software Key Storage Provider
ECDSA_P256#Microsoft Software Key Storage Provider
ECDSA_P384#Microsoft Software Key Storage Provider
ECDSA_P521#Microsoft Software Key Storage Provider
RSA#Microsoft Smart Card Key Storage Provider
ECDSA_P256#Microsoft Smart Card Key Storage Provider
ECDSA_P384#Microsoft Smart Card Key Storage Provider
ECDSA_P521#Microsoft Smart Card Key Storage Provider
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-KeyLength <Int32>
This parameter specifies the key length. If not specified, a 2048-bit key will be generated. There is a little trick: if you look to a CSP list (above), you will see that key length is specified for each ECDSA* provider. I've developed a script logic in that way,so the script ignores this parameter if one of ECDSA* CSP is explicitly chosen and uses key length that is supported by the CSP. Therefore you will not receive an error if you select 'ECDSA_P256#Microsoft Smart Card Key Storage Provider' CSP with 2048 key length. 256-bit key will be selected automatically.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-HashAlgorithm <String>
This parameter specifies hash algorithm that will be used for CA certificate/request hashing. Note that this is important for root CA installations. Subordinate CA certificates are hashed and signed by the parent CA with it's own settings. By default 'SHA1' issued (though this parameter is applicable for all CA installation types).
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-ValidForYears <Int32>
Specifies the validity for root CA installations. By default root CA certificates are valid for 5 years. You can increase this value to 10, 20, 50, whatever you need. For any subordinate CA types this parameter is silently ignored. This is because subordinate CAvalidity is determined by the parent CA. This parameter accepts integer values, assuming that the value is specified in years.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-RequestFileName <String>
If you setup any sort of subordinate (not root) CAs you can specify custom path to a request file. By default request file is generated in the root folder of system drive.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-DBDirectory <String>
Specifies the path to a folder to store CA database. If not specified, the default path: %windir%\System32\CertLog folder is used. If you need to specify custom path (for example, shared storage for CA clusters), you need to specify the next parameter too. The path must be valid.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-LogDirectory <String>
Specifies the path to a folder to store CA database log files. By default %windir%\System32\CertLog folder is used. If you use custom path for either database or log folders, you must explicitly specify both paths.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-OverwriteExisting <SwitchParameter>
Specifies, whether to overwrite any existing database files in the specified directories.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-AllowCSPInteraction <SwitchParameter>
Specifies, whether the cryptographic service provider (CSP) is allowed to interact with the desktop. This parameter should be used only if you use custom hardware-based CSP (HSM or smart card CSP). In other cases you don't need to allow CSP interactions.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-Force <SwitchParameter>
By default, the script explicitly prompts you whether you want to install Certification Authority with selected values. If you want to implement silent (quiet) installations — specify this parameter to suppress any prompts during role installation
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-WhatIf <SwitchParameter>
Describes what would happen if you executed the command without actually executing the command.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-Confirm <SwitchParameter>
Prompts you for confirmation before executing the command.
| Required? | False |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-CACertFile <FileInfo>
Specifies the path to a PFX file with CA certificate. Relative paths are allowed. Setup API performs additional checks for the certificate. Therefore you must ensure if: this is CA certificate (but not EFS encryption ;)), CA certificate is trusted (for non-root certificates)and chains to trusted CA and CA certificate revocation checking can be performed. Otherwise you will unable to setup CA with that CA certificate.
| Required? | True |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-Password <SecureString>
Specifies the password to open PFX file. The parameter supports only secure strings! You can't type a password as a simple text. This is made for security reasons. There are few ways to pass a password in a SecureString form:
'$Password = Read-Host –a' or 'ConvertTo-SecureString <plaintext> –asplaintext –force'
You can enclose last command in parentheses and pass directly as a parameter value.
| Required? | True |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-Thumbprint <String>
Specifies a thumbprint of the certificate to use. The certificate must be installed in Local Machine\Personal store and must be trusted (for non-root certificates) and must not be revoked (the issuer revocation information must be available).
| Required? | True |
| Position? | named |
| Default value | |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, InformationAction, InformationVariable,
WarningAction, WarningVariable, OutBuffer, PipelineVariable and OutVariable.
For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
Inputs
None.
Outputs
SysadminsLV.PKI.Utils.IServiceOperationResult
Notes
Author: Vadims Podans
Blog: https://www.sysadmins.lv
Examples
Example 1
PS C:\> Install-CertificationAuthority -CAName "My Root CA" -CADNSuffix "OU=Information Systems, O=Sysadmins LV, C=LV" ` -CAType "Standalone Root" -ValidForYears 10
In this scenario you setup new Standalone Root CA with 'CN=My Root CA, OU=Information Systems, O=Sysadmins LV, C=LV' subject, that will be valid for 10 years. The CA will use default paths to CA database and log files and certificate will use 'RSA#Microsoft Software Key Storage Provider' CSP with 2048-bit key and SHA1 hashing algorithm.
Example 2
PS C:\> Install-CertificationAuthority -CAName "My Root CA" -CADNSuffix "OU=Information Systems, O=Sysadmins LV, C=LV" ` -CAType "Standalone Root" -ValidForYears 20 -CSP "ECDSA_P256#Microsoft Smart Card Key Storage Provider" ` -HashAlgorithm SHA512
This example is similar to previous, with the exception that this CA will be completely CNG/SHA2 root. CA certificate will use CNG (not RSA) keys and hashing algorithm will be SHA512.
Example 3
PS C:\> Install-CertificationAuthority -CAName "Clustered CA" -CADNSuffix "OU=Information Systems, O=Sysadmins LV, C=LV" ` -CAType "Enterprise Subordinate" -KeyLength 4096 -DBDirectory "S:\CertDB" -LogDirectory "S:\CertLog" ` -RequestFileName "S:\Clustered CA.req"
This example assumes that you setup CA cluster first node (but not necessary). CA database will be stored on a shared storage (attached with S: drive letter). CA certificate will use default 'RSA#Microsoft Software Key Storage Provider' with 4096-bit key and default SHA1 hashing algorithm. CA certificate validity will be determined by the parent CA. In addition, CA certificate request will be stored on the shared storage.
Example 4
PS C:\> $Password = Read-Host -AsSecureString PS> Install-CertificationAuthority -CACertFile .\ClusteredCA.pfx -Password $Password ` -DBDirectory "S:\CertDB" -LogDirectory "S:\CertLog" -OverwriteExisting
This is two-line example. Say, you have successfully installed CA cluster first node and have exported CA certificate to a PFX, and moved it to the second node (to the current directory). At first you will be prompted for a password. Since you type password to a secure string prompt, no characters will be displayed. After that you will specify relative path to a PFX file and specify shared storage to store CA database and log files. You overwrite database files that was created during first node installation. Actually this command installs CA cluster second node.
Example 5
PS C:\> Install-CertificationAuthority -CAName "Company Enterprise CA-2" -CADNSuffix "O=Company, E=companypky@company.com" ` -CAType "Enterprise Subordinate" -ParentCA "ca01.company.com\Company Enterprise CA-1"
From best-practices perspective this is not a very good example, because it assumes at least 2 tiers of Enterprise CAs. However, it is still common. In a given example, Enterprise Subordinate CA will be installed and certificate request will be sent directly to existing Enterprise CA — 'Company Enterprise CA-1' that is hosted on 'ca01.company.com'. Note that existing CA must be online and must issue 'Subordinate Certification Authority' template.
Related links
Uninstall-CertificationAuthority
Minimum PowerShell version support
- PowerShell 3.0
Operating System Support
- Windows Server 2008 all editions
- Windows Server 2008 R2 all editions