sqmSQLTool › Commands › Install-sqmCertificateToStore

Install-sqmCertificateToStore Security

Installs a certificate file into the Windows LocalMachine certificate store on one or more computers — locally or remotely via Invoke-Command. Checks for existing thumbprint duplicates and skips without error. Returns one result object per target with Action values Installed, AlreadyPresent, or Failed.

Execution Flow

START begin: Detect format by extension (.pfx/.p12 = PFX, .cer/.crt = CER) Unknown extension: try X509Certificate2 PFX parse → $isPfx; read all bytes → $certBytes Probe cert metadata locally: X509Certificate2 → Thumbprint, Subject, NotAfter Warn if expired or expiring within 30 days; throw on parse failure SecureStringToBSTR → $plainPassword (only in memory; zeroed after each Invoke-Command) process: foreach ($computer in $ComputerName) ShouldProcess confirmed? Action=Skipped; continue $installScriptBlock (runs local or via Invoke-Command -ComputerName) X509Store LocalMachine\$StoreName .Open(ReadWrite) $store.Certificates | Where Thumbprint → if found: Action=AlreadyPresent; else: $store.Add($x509) → Action=Installed Err end: $plainPassword = $null; log summary: Installed=X, AlreadyPresent=Y, Failed=Z Return $results [List<PSCustomObject>] — one entry per target DONE

Synopsis

Reads the certificate file once locally to get metadata (thumbprint, subject, expiry). For remote targets, the raw certificate bytes are passed as an argument to Invoke-Command — no file share access is required on the target. The import script block runs identically whether local or remote. Thumbprint deduplication prevents double-install silently.

No dbatools required. SupportsShouldProcess with ConfirmImpact=Medium. Requires Administrator rights and WinRM access for remote targets. PFX password is converted to plain text in memory only for the duration of the Invoke-Command call and zeroed immediately after in the end block.

Syntax

Install-sqmCertificateToStore
    -CertFile <String>                       # required; .cer/.crt/.pfx/.p12
    [-StoreName <Root|My|TrustedPeople|CA>]   # default Root
    [-ComputerName <String[]>]               # default localhost
    [-CertPassword <SecureString>]           # for PFX files

Parameters

ParameterTypeDefaultDescription
-CertFileString—Required. Path to the certificate file. Must exist and be readable.
-StoreNameStringRootTarget LocalMachine store: Root (Trusted Root CA), My (Personal), TrustedPeople, or CA (Intermediate CA).
-ComputerNameString[]localhostOne or more target computers. Local when localhost, ., or matching $env:COMPUTERNAME.
-CertPasswordSecureString—Password for PFX files. Ignored for CER/CRT.

Return Value (per target)

PropertyDescription
ComputerNameTarget computer name.
StoreNameStore where the certificate was installed.
ThumbprintCertificate thumbprint.
SubjectCertificate subject (CN).
ExpiryCertificate expiry date (NotAfter).
ActionInstalled — newly added; AlreadyPresent — thumbprint duplicate skipped; Failed — error occurred; Skipped — ShouldProcess declined.
ErrorMessageError text when Action = Failed.

Examples

# Distribute CA root certificate to all AlwaysOn replica nodes
$nodes = 'SQL-AG-01', 'SQL-AG-02', 'SQL-AG-03'
Install-sqmCertificateToStore -CertFile 'C:\Certs\CompanyRootCA.cer' `
    -StoreName Root -ComputerName $nodes

# Distribute AlwaysOn partner certificate (CER) to My store on replicas
Install-sqmCertificateToStore -CertFile 'C:\Certs\SQL-AG-01_AG_CERT.cer' `
    -StoreName My -ComputerName 'SQL-AG-02','SQL-AG-03'

# Install PFX with password into Personal store on local machine
$pwd = Read-Host -AsSecureString 'PFX password'
Install-sqmCertificateToStore -CertFile 'C:\Certs\sql-ssl.pfx' `
    -StoreName My -CertPassword $pwd