syntax-tm / pscerts

A PowerShell module for managing certificates

---

A Powershell module for managing certificates.

Install

Install-Module -Name PSCerts

TOC

• Install
• Commands
  • Add-CertPermissions
  • Add-SiteBinding
  • Get-CertPermissions
  • Get-CertPrivateKey
  • Get-CertSummary
  • Set-CertFriendlyName
• Building
• Testing
  • Unit Tests
• In-Progress
• Backlog
• Reference
• Additional Resources

Commands

Add-CertPermissions

Adds a FileSystemAccessRule to a certificate's private key.

Usage:

Add-CertPermissions [-Certificate] <X509Certificate2> [-Identity] <string> [-FileSystemRights] <FileSystemRights> [[-AccessType] <AccessControlType>]
Add-CertPermissions [-Certificate] <X509Certificate2> [-Rule] <FileSystemAccessRule>
Add-CertPermissions [-Thumbprint] <string> [-Identity] <string> [-FileSystemRights] <FileSystemRights> [[-AccessType] <AccessControlType>]
Add-CertPermissions [-Thumbprint] <string> [-Rule] <FileSystemAccessRule>

Examples:

$cert = Get-Item Cert:\LocalMachine\My\10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae
Add-CertPermissions -Certificate $cert -Identity "Network Service" -FileSystemRights FullControl -AccessType Allow

Add-CertPermissions -Thumbprint "10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae" -Identity "Network Service" -FileSystemRights FullControl -AccessType Allow

Returns: None

---

Add-SiteBinding

Adds or updates the SSL Binding of an IIS site.

Usage:

Add-SiteBinding [-Certificate] <X509Certificate2> [-Site] <string> [[-BindingInformation] <string>] [[-SslFlags] <SslFlags>]
Add-SiteBinding [-Thumbprint] <string> [-Site] <string> [[-BindingInformation] <string>] [[-SslFlags] <SslFlags>]
Add-SiteBinding [-FilePath] <string> [-Password] <string> [-Site] <string> [[-BindingInformation] <string>] [[-SslFlags] <SslFlags>]
Add-SiteBinding [-FilePath] <string> [-SecurePassword] <SecureString> [-Site] <string> [[-BindingInformation] <string>] [[-SslFlags] <SslFlags>]

Examples:

# adds a new SSL binding for the default site
Add-SiteBinding -Thumbprint '10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae' -Site 'Default Web Site'

Returns: CertBinding

---

Get-CertPermissions

Returns the access control and audit security for a certificate's private key.

Get-CertPermissions [-Certificate] <X509Certificate2>
Get-CertPermissions [-Thumbprint] <string>

Examples:

$cert = Get-Item Cert:\LocalMachine\My\10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae
Get-CertPermissions -Certificate $cert

Get-CertPermissions -Thumbprint '10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae'

Returns: List<CertAccessRule>

---

Get-CertPrivateKey

Determines the name and location of the certificate's private key.

Usage:

Get-CertPrivateKey [-Certificate] <X509Certificate2>
Get-CertPrivateKey [-Thumbprint] <string>

Examples:

$cert = Get-Item Cert:\LocalMachine\My\10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae
Get-CertPrivateKey -Certificate $cert

Get-CertPrivateKey -Thumbprint '10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae'

Returns: FileInfo

---

Get-CertSummary

Returns information about the currently installed certificates.

Usage:

Get-CertSummary [-WithPrivateKey]

Examples:

Get-CertSummary
Get-CertSummary -WithPrivateKey

Returns: List<CertSummaryItem>

---

Set-CertFriendlyName

Updates the FriendlyName of an X509Certificate2.

Usage:

Set-CertFriendlyName [-Certificate] <X509Certificate2> [-FriendlyName] <string>
Set-CertFriendlyName [-Thumbprint] <string> [-FriendlyName] <string>

Examples:

Set-CertFriendlyName -Thumbprint '10df834fc47ddfc4d069d2e4fe79e4bf1d6d4dae' -FriendlyName "My Test Cert"

Returns: X509Certificate2

---

Building

The build.ps1 script will build and publish both the CLR (net462) and Core CLR (netstandard2.0) frameworks.

.\src\scripts\build.ps1

Once that is done, the module and all required assemblies, type data, manifest, etc will be in the src\publish directory. If you are wanting to import the module you can use this directory but it's recommended to use the Test script.

Testing

Because PSCerts is a binary module, importing the assembly from the build or publish directory will keep you from being able to buiild and/or deploy. Simply removing the module from the session with Remove-Module is not enough to remove the actual assembly reference. To get around this, test.ps1 will run build.ps1 and copy everything to src\test. You can load the assembly from the test path and still be able run build and publish.

If you are developing in VSCode, which is recommnded, you can configure the PowerShell add-on to create a temporary console for each debugging session. This prevents locking the binary and the script will automatically re-import the module with each session.

"powershell.debugging.createTemporaryIntegratedConsole": true

Unit Tests

PSCerts.Tests is the unit testing project. It's very much a work-in-progress.

---

In-Progress

Import-Certs

certfile (Required): The path to a certificate file stores (Required): One or more stores the certificate will be imported to permissions: File permissions for the private key (Optional) password: The password for the certificate.

The type indicates how to handle the value property (see below).

• Type: text
  • The value is the password. (Not recommended)
  • Example
• Type: file
  • The value is the path to a file that contains the password.
  • Example
• Type: env
  • The value is the name of an environment variable containing the password.
  • Example

Backlog

• Finish documentation for Import-Certs
• Add Cmdlet help information
• Add unit tests
• Add version history, release notes, etc. to the module manifest
• Move non-Cmdlet code to a separate project
• Create NuGet package for the core functionality
• Come up with better names for the model classes (and others)
• Create documentation (wiki)

Reference

• Version History

Additional Resources

• Key Storage and Retrieval