PowerShell - New-RsaKeyPair

The New-RsaKeyPair function uses the certreq.exe program to generate an RSA public/private key pair suitable for use in encrypting/decrypting CMS messages, credentials in DSC resources, etc. It uses the following .inf file as input (taken from the first example in the help for the Protect-CmsMessage cmdlet):

[Version]
Signature = "$Windows NT$"

[Strings]
szOID_ENHANCED_KEY_USAGE = "2.5.29.37"
szOID_DOCUMENT_ENCRYPTION = "1.3.6.1.4.1.311.80.1"

[NewRequest]
Subject = $Subject
MachineKeySet = false
KeyLength = $Length
KeySpec = AT_KEYEXCHANGE
HashAlgorithm = $Algorithm
Exportable = true
RequestType = Cert
KeyUsage = "CERT_KEY_ENCIPHERMENT_KEY_USAGE | CERT_DATA_ENCIPHERMENT_KEY_USAGE"
ValidityPeriod = Days
ValidityPeriodUnits = 

[Extensions]
%szOID_ENHANCED_KEY_USAGE% = "{{text}}%szOID_DOCUMENT_ENCRYPTION%"

You can control the subject (via the -Subject parameter), key length (via the -Length parameter), the hash algorithm (via the -Algorithm parameter), and the expiration date of the keys (via the -ValidTo parameter). The subject is always required and should begin with "CN=". The length, hash algorithm, and expiration date are optional, and default to 4096, sha512, and 12/31/9999, respectively.

The certreq.exe command stores the private key in the current user's My certificate store. This function exports that private key to a file and removes it from the current user's My store. The private key is protected with the password provided via the -Password parameter. If you don't provide a password, you will be prompted for one. To not protect the private key with a password, pass $null as the value of the -Password parameter.

The public key is saved as an X509Certificate. The private key is saved as a PFX file. Both can be loaded by .NET's X509Certificate class. Returns System.IO.FileInfo objects for the public and private key, in that order.

Before Carbon 2.1, this function used the makecert.exe and pvk2pfx.exe programs, from the Windows SDK. These programs prompt multiple times for the private key password, so if you're using a version before 2.1, you can't run this function non-interactively.

Related Commands

Parameters

Return Values

EXAMPLE 1

Name	Type	Description	Required?	Pipeline Input	Default Value
Subject	String	The key's subject. Should be of the form `CN=Name,OU=Name,O=SuperMagicFunTime,ST=OR,C=US`. Only the `CN=Name` part is required.	true	false
Algorithm	String	The signature algorithm. Default is `sha512`.	false	false	sha512
ValidFrom	DateTime	The date/time the keys will become valid. Default is now. This parameter was made obsolete in Carbon 2.1.	false	false	(Get-Date)
ValidTo	DateTime	The date/time the keys should expire. Default is `DateTime::MaxValue`.	false	false	([DateTime]::MaxValue)
Length	Int32	The length, in bits, of the generated key length. Default is `4096`.	false	false	4096
Authority	String	The signing authority of the certificate. Must be `commercial` (for certificates used by commercial software publishers) or `individual`, for certificates used by individual software publishers. Default is `individual`. This parameter was made obsolete in Carbon 2.1.	false	false	individual
PublicKeyFile	String	The file where the public key should be stored. Saved as an X509 certificate.	true	false
PrivateKeyFile	String	The file where the private key should be stored. The private key will be saved as an X509 certificate in PFX format and will include the public key.	true	false
Password	SecureString	The password for the private key. If one is not provided, you will be prompted for one. Pass `$null` to not protect your private key with a password. This parameter was introduced in Carbon 2.1.	false	false
Force	SwitchParameter	Overwrites `PublicKeyFile` and/or `PrivateKeyFile`, if they exist.	false	false	False

Demonstrates the minimal parameters needed to generate a key pair. The key will use a sha512 signing algorithm, have a length of 4096 bits, and expire on 12/31/9999. The public key will be saved in the current directory as MyName.cer. The private key will be saved to the current directory as MyName.pfx and protected with password in $secureString.

EXAMPLE 2

Demonstrates how to save the private key unprotected (i.e. without a password). You must set the password to $null. This functionality was introduced in Carbon 2.1.

EXAMPLE 3

Demonstrates how to use all the parameters to create a truly customized key pair. The generated certificate will use the sha1 signing algorithm, becomes effective 1/1/2015, expires 12/31/2015, and is 1024 bits in length.

New-RsaKeyPair