< Back
New-CRsaKeyPair
Post
NAME New-CRsaKeyPair
SYNOPSIS
Generates a public/private RSA key pair.
SYNTAX
New-CRsaKeyPair [-Subject] <String> [-Algorithm <String>] [-ValidFrom <DateTime>] [-ValidTo <DateTime>] [-Length
<Int32>] [-Authority <String>] [-PublicKeyFile] <String> [-PrivateKeyFile] <String> [-Password <SecureString>]
[-Force] [<CommonParameters>]
DESCRIPTION
The `New-CRsaKeyPair` 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.
PARAMETERS
-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.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Algorithm <String>
The signature algorithm. Default is `sha512`.
Required? false
Position? named
Default value sha512
Accept pipeline input? false
Accept wildcard characters? false
-ValidFrom <DateTime>
The date/time the keys will become valid. Default is now.
This parameter was made obsolete in Carbon 2.1.
Required? false
Position? named
Default value (Get-Date)
Accept pipeline input? false
Accept wildcard characters? false
-ValidTo <DateTime>
The date/time the keys should expire. Default is `DateTime::MaxValue`.
Required? false
Position? named
Default value ([DateTime]::MaxValue)
Accept pipeline input? false
Accept wildcard characters? false
-Length <Int32>
The length, in bits, of the generated key length. Default is `4096`.
Required? false
Position? named
Default value 4096
Accept pipeline input? false
Accept wildcard characters? false
-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.
Required? false
Position? named
Default value individual
Accept pipeline input? false
Accept wildcard characters? false
-PublicKeyFile <String>
The file where the public key should be stored. Saved as an X509 certificate.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Force [<SwitchParameter>]
Overwrites `PublicKeyFile` and/or `PrivateKeyFile`, if they exist.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
System.IO.FileInfo
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>New-CRsaKeyPair -Subject 'CN=MyName' -PublicKeyFile 'MyName.cer' -PrivateKeyFile 'MyName.pfx' -Password
$secureString
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 --------------------------
PS C:\\>New-CRsaKeyPair -Subject 'CN=MyName' -PublicKeyFile 'MyName.cer' -PrivateKeyFile 'MyName.pfx' -Password
$null
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 --------------------------
PS C:\\>New-CRsaKeyPair -Subject 'CN=MyName' -PublicKeyFile 'MyName.cer' -PrivateKeyFile 'MyName.pfx' -Algorithm
'sha1' -ValidTo (Get-Date -Year 2015 -Month 12 -Day 31) -Length 1024 -Password $secureString
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.
RELATED LINKS
Get-CCertificate
Install-CCertificate
SYNOPSIS
Generates a public/private RSA key pair.
SYNTAX
New-CRsaKeyPair [-Subject] <String> [-Algorithm <String>] [-ValidFrom <DateTime>] [-ValidTo <DateTime>] [-Length
<Int32>] [-Authority <String>] [-PublicKeyFile] <String> [-PrivateKeyFile] <String> [-Password <SecureString>]
[-Force] [<CommonParameters>]
DESCRIPTION
The `New-CRsaKeyPair` 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.
PARAMETERS
-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.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Algorithm <String>
The signature algorithm. Default is `sha512`.
Required? false
Position? named
Default value sha512
Accept pipeline input? false
Accept wildcard characters? false
-ValidFrom <DateTime>
The date/time the keys will become valid. Default is now.
This parameter was made obsolete in Carbon 2.1.
Required? false
Position? named
Default value (Get-Date)
Accept pipeline input? false
Accept wildcard characters? false
-ValidTo <DateTime>
The date/time the keys should expire. Default is `DateTime::MaxValue`.
Required? false
Position? named
Default value ([DateTime]::MaxValue)
Accept pipeline input? false
Accept wildcard characters? false
-Length <Int32>
The length, in bits, of the generated key length. Default is `4096`.
Required? false
Position? named
Default value 4096
Accept pipeline input? false
Accept wildcard characters? false
-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.
Required? false
Position? named
Default value individual
Accept pipeline input? false
Accept wildcard characters? false
-PublicKeyFile <String>
The file where the public key should be stored. Saved as an X509 certificate.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Force [<SwitchParameter>]
Overwrites `PublicKeyFile` and/or `PrivateKeyFile`, if they exist.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
System.IO.FileInfo
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>New-CRsaKeyPair -Subject 'CN=MyName' -PublicKeyFile 'MyName.cer' -PrivateKeyFile 'MyName.pfx' -Password
$secureString
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 --------------------------
PS C:\\>New-CRsaKeyPair -Subject 'CN=MyName' -PublicKeyFile 'MyName.cer' -PrivateKeyFile 'MyName.pfx' -Password
$null
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 --------------------------
PS C:\\>New-CRsaKeyPair -Subject 'CN=MyName' -PublicKeyFile 'MyName.cer' -PrivateKeyFile 'MyName.pfx' -Algorithm
'sha1' -ValidTo (Get-Date -Year 2015 -Month 12 -Day 31) -Length 1024 -Password $secureString
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.
RELATED LINKS
Get-CCertificate
Install-CCertificate