PowerShell PKI Module Documentation
Documentation HomeI’m glad to announce the PowerShell PKI (PSPK) v4.0.0-preview version release!
This version resembles deep internal changes, so it is not 100% backward compatible with PSPKI v3 branch. This article outlines notable changes in PSPKI v4.
.NET Framework upgrade
All PSPKI v3 versions were built on top of .NET Framework 4.0, which is out of support and had limited functionality. As part of refactoring underlying support libraries to be .NET Standard 2.0 compliant, PSPKI v4 is built on top of .NET Framework 4.7.2. Not all APIs are .NET Standard compliant because of heavy dependency on Windows-only APIs and DCOM.
Removed commands
In this version, I’ve removed commands specific to Windows Server 2008 R2:
- Add-CertificateEnrollmentPolicyService
- Add-CertificateEnrollmentService
- Install-CertificationAuthority
- Remove-CertificateEnrollmentPolicyService
- Remove-CertificateEnrollmentService
- Uninstall-CertificationAuthority
And the following commands were removed because they are now part of their own modules:
- Start-PsFCIV – now part of PsFCIV module
Changed commands
The following table shows changes in existing commands and their parameters:
- Add-AdCertificateRevocationList
-CertificateRevocationList parameter type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509CRL2
- Convert-PemToPfx
-KeySpec parameter type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509KeySpecFlags
- Get-CertificateContextProperty
-PropertyName parameter type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePropertyType
Return types changed to: SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateContextProperty, SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateContextPropertyCollection, SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePropertyType (depending or selected parameters).
- Get-CertificateRequest
Return type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateRequest
- Get-CertificateRevocationList
Return type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509CRL2
- Get-ObjectIdentifierEx
-OidGroup parameter type is changed to System.Security.Cryptography.OidGroup
Return type is changed to SysadminsLV.PKI.Cryptography.Oid2
- Register-ObjectIdentifier
Return type is changed to SysadminsLV.PKI.Cryptography.Oid2
- Show-CertificateRevocationList
-CRL parameter type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509CRL2
- Unregister-ObjectIdentifier
-Value parameter type is changed to SysadminsLV.PKI.Cryptography.Oid2
- Add-OnlineResponderLocalCrlEntry
-Entry parameter type is changed to SysadminsLV.PKI.Cryptography.X509Certificates.X509CRLEntryCollection
- Set-OnlineResponderRevocationConfiguration
-HashAlgorithm parameter type is changed to SysadminsLV.PKI.Cryptography.Oid2
- Get-CAExchangeCertificate
-EncodingType parameter type is changed to SysadminsLV.Asn1Parser.EncodingType
- Add-CertificateTemplateAcl
- Add-CertificationAuthorityAcl
- Add-OnlineResponderAcl
-AcessRule parameter renamed to -AccessRule (there was a typo in the parameter name).
Notable API changes
This is the biggest change from previous versions. PSPKI v3.x was backed by a SysadminsLV.PKI.dll library which was Windows-only although many APIs I developed were platform-independent that limited the usefulness of the library in other projects. I did a big work on splitting the library into modules and ended up with three libraries:
- SysadminsLV.PKI.dll – a cross-platform, .NET Standard 2.0 compliant library that provides core cryptography extensions, including native certificate request, X.509 CRL, CTL and a lot of X.509 extension implementations.
- SysadminsLV.PKI.OcspClient.dll – a cross-platform, .NET Standard 2.0 compliant library that contains managed OCSP client implementation.
- SysadminsLV.PKI.Win.dll – is a Windows-only, .NET 4.7.2 library that contains Windows- and AD CS-specific functionality including DCOM wrappers and unmanaged CryptoAPI functions.
Another problem (painful) was with namespaces. When I originally started the support DLL development in 2011, I didn’t bother with guidelines and put relevant classes into Microsoft’s System.Security.Cryptography namespace.This wasn’t a problem for more than a decade. However, starting with .NET 6, Microsoft added several crypto classes and I’ve got a problem that their class names and namespaces matches with my implementation, which is certainly a bad thing. I didn’t find a good way to enable soft/comfortable migration of external code to new namespaces and was forced to cut ties and move all my own stuff out from System.Security.* namespace to my own. The table below shows the map of all affected classes (with namespaces) and their new location and name.
If you are using any of classes listed in the first column, you are required to update your code/scripts with new references before upgrading to PSPKI v4.
In addition, there is a new unified API documentation home that includes API docs for all libraries used by PSPKI: https://www.pkisolutions.com/apidocs/pki
| Old class name | New class name |
|---|---|
| SysadminsLV.PKI.Cryptography.Pkcs.ContentInfo2 | REMOVED |
| SysadminsLV.PKI.Cryptography.Pkcs.PKCS7SignedMessage | REMOVED |
| PKI.Enrollment.ClientIdEnum | SysadminsLV.PKI.Cryptography.EnrollmentClientIdType |
| System.Security.Cryptography.X509Certificates.AuthorityKeyIdentifierFlags | SysadminsLV.PKI.Cryptography.X509Certificates.AuthorityKeyIdentifierType |
| SysadminsLV.PKI.Tools.MessageOperations.SignaturePadding | SysadminsLV.PKI.Cryptography.SignaturePadding |
| SysadminsLV.PKI.Utils.CLRExtensions.OidExtensions | SysadminsLV.PKI.CLRExtensions.OidExtensions |
| System.Security.Cryptography.OidGroupEnum | System.Security.Cryptography.OidGroup (.NET) |
| System.Security.Cryptography.OidMapping | SysadminsLV.PKI.Cryptography.X509Certificates.OidMapping |
| PKI.Cryptography.X509AttributeOid | SysadminsLV.PKI.Cryptography.Pkcs.Pkcs9AttributeOid |
| System.Security.Cryptography.X509Attribute | SysadminsLV.PKI.Cryptography.Pkcs.Pkcs9AttributeObject (.NET) |
| System.Security.Cryptography.X509AttributeCollection | SysadminsLV.PKI.Cryptography.Pkcs.Pkcs9AttributeObjectCollection |
| System.Security.Cryptography.X509Certificates.X500RdnAttribute | SysadminsLV.PKI.Cryptography.X509Certificates.X500RdnAttribute |
| System.Security.Cryptography.X509Certificates.X500RdnAttributeCollection | SysadminsLV.PKI.Cryptography.X509Certificates.X500RdnAttributeCollection |
| System.Security.Cryptography.X509Certificates.X509AlternativeNamesEnum | SysadminsLV.PKI.Cryptography.X509Certificates.X509AlternativeNamesEnum |
| System.Security.Cryptography.X509Certificates.X509AlternativeName | SysadminsLV.PKI.Cryptography.X509Certificates.X509AlternativeName |
| System.Security.Cryptography.X509Certificates.X509AlternativeNameCollection | SysadminsLV.PKI.Cryptography.X509Certificates.X509AlternativeNameCollection |
| System.Security.Cryptography.X509Certificates.X509ApplicationPoliciesExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509ApplicationPoliciesExtension |
| System.Security.Cryptography.X509Certificates.X509ApplicationPolicyConstraintsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509ApplicationPolicyConstraintsExtension |
| System.Security.Cryptography.X509Certificates.X509ApplicationPolicyMappingsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509ApplicationPolicyMappingsExtension |
| System.Security.Cryptography.X509Certificates.X509ArchiveCutoffExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509ArchiveCutoffExtension |
| System.Security.Cryptography.X509Certificates.X509AuthorityInformationAccessExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509AuthorityInformationAccessExtension |
| System.Security.Cryptography.X509Certificates.X509AuthorityKeyIdentifierExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509AuthorityKeyIdentifierExtension |
| System.Security.Cryptography.X509Certificates.X509CAVersionExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CAVersionExtension |
| System.Security.Cryptography.X509Certificates.X509CEPEnrollmentPropertyInfo | SysadminsLV.PKI.Cryptography.X509Certificates.X509CEPEnrollmentPropertyInfo |
| System.Security.Cryptography.X509Certificates.X509CertificatePoliciesExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePoliciesExtension |
| System.Security.Cryptography.X509Certificates.X509CertificatePolicy | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePolicy |
| System.Security.Cryptography.X509Certificates.X509CertificatePolicyCollection | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePolicyCollection |
| System.Security.Cryptography.X509Certificates.X509CertificatePolicyConstraintsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePolicyConstraintsExtension |
| System.Security.Cryptography.X509Certificates.X509CertificatePolicyMappingsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePolicyMappingsExtension |
| System.Security.Cryptography.X509Certificates.X509CertificateTemplateExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateTemplateExtension |
| System.Security.Cryptography.X509Certificates.X509CNGKeyUsages | System.Security.Cryptography.CngKeyUsages (.NET) |
| System.Security.Cryptography.X509Certificates.X509CRLEntry | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRLEntry |
| System.Security.Cryptography.X509Certificates.X509CRLEntryCollection | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRLEntryCollection |
| System.Security.Cryptography.X509Certificates.X509DistributionPoint | SysadminsLV.PKI.Cryptography.X509Certificates.X509DistributionPoint |
| System.Security.Cryptography.X509Certificates.X509CRLDistributionPointsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRLDistributionPointsExtension |
| System.Security.Cryptography.X509Certificates.X509CRLNumberExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRLNumberExtension |
| System.Security.Cryptography.X509Certificates.X509CRLReferenceExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRLReferenceExtension |
| System.Security.Cryptography.X509Certificates.X509CrossCertificateDistributionPointsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509CrossCertificateDistributionPointsExtension |
| System.Security.Cryptography.X509Certificates.X509FreshestCRLExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509FreshestCRLExtension |
| System.Security.Cryptography.X509Certificates.X509IssuerAlternativeNamesExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509IssuerAlternativeNamesExtension |
| System.Security.Cryptography.X509Certificates.X509KeySpecFlags | SysadminsLV.PKI.Cryptography.X509Certificates.X509KeySpecFlags |
| System.Security.Cryptography.X509Certificates.X509NameConstraintsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509NameConstraintsExtension |
| System.Security.Cryptography.X509Certificates.X509NextCRLPublishExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509NextCRLPublishExtension |
| System.Security.Cryptography.X509Certificates.X509NonceExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509NonceExtension |
| System.Security.Cryptography.X509Certificates.X509PublishedCrlLocationsExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509PublishedCrlLocationsExtension |
| System.Security.Cryptography.X509Certificates.X509ServiceLocatorExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509ServiceLocatorExtension |
| System.Security.Cryptography.X509Certificates.X509CRL2 | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRL2 |
| System.Security.Cryptography.X509Certificates.X509CRL2Collection | SysadminsLV.PKI.Cryptography.X509Certificates.X509CRL2Collection |
| System.Security.Cryptography.X509Certificates.X509PolicyQualifier | SysadminsLV.PKI.Cryptography.X509Certificates.X509PolicyQualifier |
| System.Security.Cryptography.X509Certificates.X509PolicyQualifierCollection | SysadminsLV.PKI.Cryptography.X509Certificates.X509PolicyQualifierCollection |
| System.Security.Cryptography.X509Certificates.X509PolicyQualifierType | SysadminsLV.PKI.Cryptography.X509Certificates.X509PolicyQualifierType |
| System.Security.Cryptography.X509Certificates.X509RevocationReasons | SysadminsLV.PKI.Cryptography.X509Certificates.X509RevocationReasons |
| System.Security.Cryptography.X509Certificates.X509RevocationReasonFlag | SysadminsLV.PKI.Cryptography.X509Certificates.X509RevocationReasonFlag |
| System.Security.Cryptography.X509Certificates.X509SubjectAlternativeNamesExtension | SysadminsLV.PKI.Cryptography.X509Certificates.X509SubjectAlternativeNamesExtension |
| SysadminsLV.PKI.Cryptography.X509CertificateRequests.X509CertificateRequestPkcs10 | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateRequestPkcs10 |
| System.Security.Cryptography.X509CertificateRequests.X509CertificateRequestType | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateRequestType |
| SysadminsLV.PKI.Cryptography.X509CertificateRequests.X509CertificateRequestCmc | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateRequestCmc |
| System.Security.Cryptography.X509CertificateRequests.X509CertificateRequest | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateRequest |
| SysadminsLV.PKI.Utils.CLRExtensions.BigIntegerExtensions | SysadminsLV.PKI.CLRExtensions.BigIntegerExtensions |
| SysadminsLV.PKI.Utils.CLRExtensions.OidExtensions | SysadminsLV.PKI.Cryptography.OidExtensions |
| SysadminsLV.PKI.Utils.CLRExtensions.PublicKeyExtensions | SysadminsLV.PKI.Cryptography.PublicKeyExtensions |
| SysadminsLV.PKI.Utils.CLRExtensions.X509ExtensionCollectionExtensions | SysadminsLV.PKI.Cryptography.X509Certificates.X509ExtensionCollectionExtensions |
| SysadminsLV.PKI.Utils.CLRExtensions.X509ExtensionExtensions | SysadminsLV.PKI.Cryptography.X509Certificates.X509ExtensionExtensions |
| SysadminsLV.PKI.Utils.CLRExtensions.X509Certificate2CollectionExtensions | SysadminsLV.PKI.Cryptography.X509Certificates.X509Certificate2CollectionExtensions |
| PKI.Utils.CryptographyUtils | SysadminsLV.PKI.Utils.CryptographyUtils |
| PKI.OCSP.CertificateStatus | SysadminsLV.PKI.OcspClient.CertificateStatus |
| PKI.OCSP.OCSPResponseStatus | SysadminsLV.PKI.OcspClient.OCSPResponseStatus |
| PKI.OCSP.OCSPResponseType | SysadminsLV.PKI.OcspClient.OCSPResponseType |
| PKI.OCSP.CertID | SysadminsLV.PKI.OcspClient.CertID |
| PKI.OCSP.OCSPSingleResponse | SysadminsLV.PKI.OcspClient.OCSPSingleResponse |
| PKI.OCSP.OCSPSingleResponseCollection | SysadminsLV.PKI.OcspClient.OCSPSingleResponseCollection |
| PKI.OCSP.OCSPSingleRequest | SysadminsLV.PKI.OcspClient.OCSPSingleRequest |
| PKI.OCSP.OCSPSingleRequestCollection | SysadminsLV.PKI.OcspClient.OCSPSingleRequestCollection |
| PKI.OCSP.OCSPResponseComplianceError | SysadminsLV.PKI.OcspClient.OCSPResponseComplianceError |
| PKI.OCSP.OCSPRequest | SysadminsLV.PKI.OcspClient.OCSPRequest |
| PKI.OCSP.OCSPResponse | SysadminsLV.PKI.OcspClient.OCSPResponse |
| System.Security.Cryptography.X509Certificates.X509CertificateContextProperty | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateContextProperty |
| System.Security.Cryptography.X509Certificates.X509CertificateContextPropertyCollection | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificateContextPropertyCollection |
| System.Security.Cryptography.X509Certificates.X509CertificatePropertyType | SysadminsLV.PKI.Cryptography.X509Certificates.X509CertificatePropertyType |
| System.Security.Cryptography.X509Certificates.X509EnrollmentPropertyInfo | SysadminsLV.PKI.Cryptography.X509Certificates.X509EnrollmentPropertyInfo |
| System.Security.Cryptography.Oid2 | SysadminsLV.PKI.Cryptography.Oid2 |
| PKI.Utils.Error | SysadminsLV.PKI.Utils.ErrorHelper |
| PKI.Exceptions.OfflineSource | SysadminsLV.PKI.Exceptions.OfflineSource |
| PKI.Exceptions.ServerUnavailableException | SysadminsLV.PKI.Exceptions.ServerUnavailableException |
| PKI.Exceptions.UninitializedObjectException | SysadminsLV.PKI.Exceptions.UninitializedObjectException |
This is the first API migration. In second migration, I’m planning to deprecate many things in PKI.CertificateServices namespace and move remaining classes under SysadminsLV.PKI namespace (barely anything apart from CertificateAuthority class will survive deprecation).
Bug Fixes
Apart from introducing breaking changes, this version delivers a lot of annoying bug fixes:
- Custom SAN is not trusted by Chrome
- Set-CertificateTemplateAcl cmd-let issue on v3.7
- Get-CertificationAuthority / not supported path
- Get-CertificateTemplate and setting CT_FLAG_SUBJECT_ALT_REQUIRE_SPN
- Typo in Add-CertificateTemplateAcl parameter
- Copying ACL’s – Unexpected Results
- Add/Set-CertificateTemplate allows setting Autoenroll permission to V1 templates
- Add/Set-CertificateTemplate messes Enroll and Autoenroll
- Add/Set-CertificateTemplate Enroll is not written properly
- Least User Privileges
- PSPKI 3.7.2 – Get-CertificateRequest – Input data does not represent valid ‘OBJECT_IDENTIFIER’ type.
- Set-OnlineResponderRevocationConfiguration Cannot find an overload for “Oid2”
- Get-CertificateRevocationList does not parse OID 2.5.29.28
- Exception when executing Add-OnlineResponderRevocationConfiguration
- Get-CertificationAuthority raises an exception on a workgroup CA
- New-SelfSignedCertificateEx -Subject “CN=TestCA” -IsCA $true -ProviderName “Microsoft Software Key Storage Provider” -Exportable -customextension $extCollection
- Publish-CRL throws: An attempt was made to access an uninitialized object
- Deny-CertificateRequest Raises Exception
- Set-OnlineResponderRevocationConfiguration: Can’t use SigningCertificate
- OcspRevocationConfiguration.RevocationStatusCode shows invalid value
- CryptoConfig.EncodeOID Bug – “Value was either too large or too small for an Int32.”
- IssuanceRequirements.CertificatePolicies is always null
- Value for CertificateTemplateFlags.PersistInDB is incorrect.
- Add new certificate template Enrollment Flag
- OCSP server name is not properly resolved
- .NET7 X509AuthorityKeyIdentifierExtension / X509AuthorityInformationAccessExtension conflict
- Missing PrivateKeyFlags values
- And many more internal code and quality improvements
Download
As always, PSPKI is available on PowerShell Gallery: https://www.powershellgallery.com/packages/PSPKI/