Hi S-1-1-0! Today I've released a new version of my PowerShell PKI module. It took a bit more that 1 month from previous release. I didn't expected to develop new version too fast. I just got a free time to work on my module and I had few ideas (mostly, based on customer feedbacks) which should significantly improve module usage area and user experience.
New features
The major improvement in PSPKI v2 is Standalone CA and non-domain environment support. Now you can manage Standalone CAs in Active Directory domain or in workgroup environment. I tried several approaches to integrate this support to an existing Get-CertificationAuthority command. Eventually, I decided to create a new universal command which connects to a specified CA server (regardless, it is Enterprise or Standalone CA) — Connect-CertificationAuthority. The idea is that in most cases Enterprise CAs have almost similar configuration and Standalone CAs slightly different due to their different usage. Therefore, Get-CertificationAuthority is still used to manage Enterprise CAs and Connect-CertificationAuthority is used to manage a single CA instance, either Enterprise or Standalone. The output objects are the same (with an exception that Get-CertificationAuthority can return multiple objects) and its result can be piped to all commands that support pipeline input from Get-CertificationAuthority command.
The code was updated to properly handle CA type if this makes a sense. For example, Standalone CAs do not support key archival and certificate templates, therefore if you try to pipe CA object to, for example, Get-CAKRACertificate or Get-CAExchangeCertificate command, an exception will be thrown.
With added non-domain environment support, not all commands are available there. That is, there are not available commands for KRA configuration, certificate template management and Enrollment Web Services installation. Online help has appropriate notes if the certain command is not available in non-domain environments.
Another filtering is added for operating system version. For example, Windows Server 2003 do not support scripted CA installation, CNG algorithms and Enrollment Web Services, these commands are not installed there. Therefore it is unlikely that you accidentally run the command that is not supported by the current OS version. It is better, than throwing exceptions :)
There are number of commands (AD CS role installation) that overlaps with new commands in Windows Server 2012 which are available in ADCSDeployment module. As per my tests, they are fine, therefore the following commands are not installed on Windows Server 2012 machines:
- Add-CertificateEnrollmentPolicyService
- Add-CertificateEnrollmentService
- Remove-CertificateEnrollmentPolicyService
- Remove-CertificateEnrollmentService
- Install-CertificationAuthority
- Uninstall-CertificationAuthority
Instead, you should consider to use built-in commands from ADCSDeployment module. Just for note, all module commands are installed only on Windows Server 2008 R2 domain member.
New commands
As already said, one of the new commands is Connect-CertificationAuthority. Running the command with no parameters, it attempts to connect to a local computer. If you want to connect to a remote server — just specify it's name as a parameter.
This is an advanced version of the Get-ObjectIdentifier command and is supposed to use by experienced PKI and Active Directory administrators. The command returns extended information about registered object identifier — registrations source, OID group and other information. Since certain OID value/display name can be registered many times in different categories, the command returns all matches for specified values. For example, there is a number of hashing algorithms which also can act as signature algorithm:
PS C:\> Get-ObjectIdentifierEx sha1 distinguishedName : OidGroup : HashAlgroithm cbSize : 64 pszOID : 1.3.14.3.2.26 pwszName : sha1 dwGroupId : 1 dwValue : 32772 ExtraInfo : PKI.Structs.Wincrypt+CRYPTOAPI_BLOB pwszCNGAlgid : SHA1 pwszCNGExtraAlgid : distinguishedName : OidGroup : SignatureAlgorithm cbSize : 64 pszOID : 1.3.14.3.2.26 pwszName : sha1NoSign dwGroupId : 4 dwValue : 32772 ExtraInfo : PKI.Structs.Wincrypt+CRYPTOAPI_BLOB pwszCNGAlgid : SHA1 pwszCNGExtraAlgid : CryptOIDInfoNoSign PS C:\> gps rdclip
You can see that OID value = 1.3.14.3.2.26 is registered twice under HashAlgorithm and SignatureAlgorithm. If a certain OID is registered in Active Directory, a LDAP path is included in the output:
PS C:\> Get-ObjectIdentifierEx "web server v2" -UseActiveDirectory
distinguishedName : CN=13726756.CFB8F05CDD97A3CE5B21CFF31AB44891,CN=OID,CN=Public Key Services,CN=Services,CN=Configura
tion,DC=contoso,DC=com
OidGroup : CertificateTemplate
cbSize : 64
pszOID : 1.3.6.1.4.1.311.21.8.149510.7314491.15746959.9320746.3700693.37.12674649.13726756
pwszName : Web Server V2
dwGroupId : 9
dwValue : 0
ExtraInfo : PKI.Structs.Wincrypt+CRYPTOAPI_BLOB
pwszCNGAlgid :
pwszCNGExtraAlgid :
PS C:\>
See that "Web Server V2" OID is registered under CertificateTemplate OID group in Active Directory. A LDAP path is included in distinguishedName property.
This command is used to register a custom object identifier either locally or (if applicable) in Active Directory. The command allows you to register OID only under ApplicationPolicy (aka enhanced key usage) or IssuancePolicy (aka certificate policy) OID groups. You can override existing OID mappings for locally registered OIDs (say, provide additional display name for particular OID value). Be sure that you know what you are doing. The command prompts execution confirmation.
This command unregisters (deletes OID registration) either from local computer or Active Directory. Generally, the command is intended to remove custom OID definitions. For example, a company had custom CPS policy and it was changed/retired. You can use this command to unregister specified OID. The command accepts pipeline input from Get-ObjectIdentifier or Get-ObjectIdentifierEx commands. Be sure that you know what you are doing. The command prompts execution confirmation.
Existing command improvements
Many commands was changed internally (moved to a PKI.Core.dll library) without any user experience changes, so I will not talk here about them. However there is a significant change in Get-CertificateTemplate command. In previous versions, the command returned only basic information about the template. A new output adds almost all certificate template settings:
PS C:\> Get-CertificateTemplate -Name user
DisplayName SchemaVersion SupportedCA AutoenrollmentAllowed
----------- ------------- ----------- ---------------------
User 1 Windows 2000 Server False
PS C:\> Get-CertificateTemplate -Name user | fl *
Name : User
DisplayName : User
Version : 3.1
SchemaVersion : 1
AutoenrollmentAllowed : False
OID : 1.3.6.1.4.1.311.21.8.149510.7314491.15746959.9320746.3700693.37.1.1 ()
LastWriteTime : 2009.02.15. 14:41:18
DN : CN=User,CN=Certificate Templates,CN=Public Key Services,CN=Services,CN=Configuration,DC=contoso
,DC=com
SupportedCA : Windows 2000 Server
Settings : PKI.CertificateTemplates.CertificateTemplateSettings
PS C:\> (Get-CertificateTemplate -Name user).Settings
ValidityPeriod : 1 years
RenewalPeriod : 6 weeks
SubjectType : User
SubjectName : AltSubjectRequireUPN, AltSubjectRequireEmail, SubjectRequireEmail, SubjectrequireDirectoryPath
EnhancedKeyUsage : {Encrypting File System, Secure Email, Client Authentication}
CSPList : {Microsoft Enhanced Cryptographic Provider v1.0, Microsoft Base Cryptographic Provider v1.0}
KeyAlgorithm :
HashAlgorithm :
MinimalKeyLength : 1024
PrivateKeyOptions : AllowKeyExport
KeySpec : AT_KEYEXCHANGE
KeyUsage : KeyEncipherment, DigitalSignature
CNGKeyUsage : 0
SupersededTemplates :
CAManagerApproval : False
RASignatureCount : 0
RAApplicationPolicies : ()
RAIssuancePolicies :
PS C:\>
In the first command call you can notice improved default output formatting. By default I just return template display name and template version is changed to SchemaVersion which returns template version, because template internal version is not much interesting. If you disagree, ping me and we will talk about this. The template object adds a Settings property which contains internal template settings.
PKI library documentation
Version 1.5 introduced a library that hosts many self-written APIs and .NET classes, their properties and methods, it was important to provide a documentation for them. API documentation allows you to learn more about how the module works and use it in your own scripts or programs. It took a time to develop a nice documentation, therefore I wasn't able to publish it prior this release. Here is a link to API documentation exposed by PKI.Core.dll library:
Actually, the library contains much more APIs than are used by the module, therefore you might explore them if you are using particular stuff. For example, the module do not use PKI.ASN, PKI.OCSP, System.Security.Cryptography.X509CertificateRequests namespaces and not all classes in other namespaces are used by the module. In next posts I'll talk about custom OCSP client tool which is exposed by PKI.OCSP namespace and which might be very helpful for PKI administrators to verify their Online Responder configurations.
And, finally, the link to module download page:
Download PowerShell PKI Module v2.0 now!
Post your comment:
Comments: