commands

^

New-DbaComputerCertificate

Author Chrissy LeMaire (@cl), netnerds.net
Availability Windows, Linux, macOS

 

Want to see the source code for this command? Check out New-DbaComputerCertificate on GitHub.
Want to see the Bill Of Health for this command? Check out New-DbaComputerCertificate.

Synopsis

Creates a new computer certificate useful for Forcing Encryption

Description

Creates a new computer certificate - self-signed or signed by an Active Directory CA, using the Web Server certificate.

By default, a key with a length of 1024 and a friendly name of the machines FQDN is generated.

This command was originally intended to help automate the process so that SSL certificates can be available for enforcing encryption on connections.

It makes a lot of assumptions - namely, that your account is allowed to auto-enroll and that you have permission to do everything it needs to do ;)

References:
https://www.itprotoday.com/sql-server/7-steps-ssl-encryption
https://azurebi.jppp.org/2016/01/23/using-lets-encrypt-certificates-for-secure-sql-server-connections/
https://blogs.msdn.microsoft.com/sqlserverfaq/2016/09/26/creating-and-registering-ssl-certificates/

The certificate is generated using AD's webserver SSL template on the client machine and pushed to the remote machine.

Syntax

New-DbaComputerCertificate
    [[-ComputerName] <DbaInstanceParameter[]>]
    [[-Credential] <PSCredential>]
    [[-CaServer] <String>]
    [[-CaName] <String>]
    [[-ClusterInstanceName] <String>]
    [[-SecurePassword] <SecureString>]
    [[-FriendlyName] <String>]
    [[-CertificateTemplate] <String>]
    [[-KeyLength] <Int32>]
    [[-Store] <String>]
    [[-Folder] <String>]
    [[-Flag] <String[]>]
    [[-Dns] <String[]>]
    [-SelfSigned]
    [-EnableException]
    [[-HashAlgorithm] <String>]
    [[-MonthsValid] <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

 

Examples

 

Example: 1
PS C:\> New-DbaComputerCertificate

Creates a computer certificate signed by the local domain CA for the local machine with the keylength of 1024.

Example: 2
PS C:\> New-DbaComputerCertificate -ComputerName Server1

Creates a computer certificate signed by the local domain CA on the local machine for server1 with the keylength of 1024.
The certificate is then copied to the new machine over WinRM and imported.

Example: 3
PS C:\> New-DbaComputerCertificate -ComputerName sqla, sqlb -ClusterInstanceName sqlcluster -KeyLength 4096

Creates a computer certificate for sqlcluster, signed by the local domain CA, with the keylength of 4096.
The certificate is then copied to sqla and sqlb over WinRM and imported.

Example: 4
PS C:\> New-DbaComputerCertificate -ComputerName Server1 -WhatIf

Shows what would happen if the command were run

Example: 5
PS C:\> New-DbaComputerCertificate -SelfSigned

Creates a self-signed certificate

Example: 6
PS C:\> New-DbaComputerCertificate -SelfSigned -HashAlgorithm Sha256 -MonthsValid 60

Creates a self-signed certificate using the SHA256 hashing algorithm that does not expire for 5 years

Optional Parameters

-ComputerName

The target SQL Server instance or instances. Defaults to localhost. If target is a cluster, you must also specify ClusterInstanceName (see below)

Alias
Required False
Pipeline true (ByValue)
Default Value $env:COMPUTERNAME
-Credential

Allows you to login to $ComputerName using alternative credentials.

Alias
Required False
Pipeline false
Default Value
-CaServer

Optional - the CA Server where the request will be sent to

Alias
Required False
Pipeline false
Default Value
-CaName

The properly formatted CA name of the corresponding CaServer

Alias
Required False
Pipeline false
Default Value
-ClusterInstanceName

When creating certs for a cluster, use this parameter to create the certificate for the cluster node name. Use ComputerName for each of the nodes.

Alias
Required False
Pipeline false
Default Value
-SecurePassword

Password to encrypt/decrypt private key for export to remote machine

Alias Password
Required False
Pipeline false
Default Value
-FriendlyName

The FriendlyName listed in the certificate. This defaults to the FQDN of the $ComputerName

Alias
Required False
Pipeline false
Default Value SQL Server
-CertificateTemplate

The domain's Certificate Template - WebServer by default.

Alias
Required False
Pipeline false
Default Value WebServer
-KeyLength

The length of the key - defaults to 1024

Alias
Required False
Pipeline false
Default Value 1024
-Store

Certificate store - defaults to LocalMachine

Alias
Required False
Pipeline false
Default Value LocalMachine
-Folder

Certificate folder - defaults to My (Personal)

Alias
Required False
Pipeline false
Default Value My
-Flag

Defines where and how to import the private key of an X.509 certificate.
Defaults to: Exportable, PersistKeySet
EphemeralKeySet
The key associated with a PFX file is created in memory and not persisted on disk when importing a certificate.
Exportable
Imported keys are marked as exportable.
NonExportable
Expliictly mark keys as nonexportable.
PersistKeySet
The key associated with a PFX file is persisted when importing a certificate.
UserProtected
Notify the user through a dialog box or other method that the key is accessed. The Cryptographic Service Provider (CSP) in use defines the precise behavior. NOTE: This can only be used when you
add a certificate to localhost, as it causes a prompt to appear.

Alias
Required False
Pipeline false
Default Value @("Exportable", "PersistKeySet")
Accepted Values EphemeralKeySet,Exportable,PersistKeySet,UserProtected,NonExportable
-Dns

Specify the Dns entries listed in SAN. By default, it will be ComputerName + FQDN, or in the case of clusters, clustername + cluster FQDN.

Alias
Required False
Pipeline false
Default Value
-SelfSigned

Creates a self-signed certificate. All other parameters can still apply except CaServer and CaName because the command does not go and get the certificate signed.

Alias
Required False
Pipeline false
Default Value False
-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.

Alias
Required False
Pipeline false
Default Value False
-HashAlgorithm

Specifies hashing algorithm for self-signed certificate. Must be one of the values Sha256, sha384, sha512, sha1, md5, md4, md2.

Alias
Required False
Pipeline false
Default Value sha1
Accepted Values Sha256,sha384,sha512,sha1,md5,md4,md2
-MonthsValid

Allows you to specify the number of months a self-signed certificate will be valid for. e.g a value of 60 will generate a certificate vaild until 5 years (60 months) time.

Alias
Required False
Pipeline false
Default Value 12
-WhatIf

Shows what would happen if the command were to run. No actions are actually performed.

Alias wi
Required False
Pipeline false
Default Value
-Confirm

Prompts you for confirmation before executing any changing operations within the command.

Alias cf
Required False
Pipeline false
Default Value