New-SelfSignedCertificate (pki) (2024)

• Reference

Module:

pki

Indicates that this cmdlet uses RSA-PSS (PKCSv2.1) or an elliptic curve cryptography (ECC)equivalent. If you do not specify this parameter, the cmdlet uses the default, RSA-PSS (PKCSv1.5) oran ECC equivalent.

Specifies the certificate store in which to store the new certificate. If the current path isCert:\CurrentUser or Cert:\CurrentUser\My, the default store is Cert:\CurrentUser\My. If thecurrent path is Cert:\LocalMachine or Cert:\LocalMachine\My, the default store isCert:\LocalMachine\My. Otherwise, you must specify Cert:\CurrentUser\My orCert:\LocalMachine\My for this parameter. This parameter does not support other certificatestores.

Identifies the certificate to copy when creating a new certificate. The certificate being cloned canbe identified by an X509 certificate or the file path in the certificate provider. When thisparameter is used, all fields and extensions of the certificate will be inherited except theNotAfter and NotBefore fields and the public key. A new key of the same algorithm and lengthwill be created. The default validity period will be the same as the certificate to copy, exceptthat the NotBefore field will be set to ten minutes in the past.

Prompts you for confirmation before running the cmdlet.

Specifies the name of the container in which this cmdlet stores the key for the new certificate.

When you create a key, a trailing asterisk (*) indicates that the rest of the container namestring is a prefix. An appended GUID string makes the container name unique.

When you use an existing key, the container name must identify an existing key.You may also have to specify the provider.

Specifies how the public key parameters for an elliptic curve key are represented in the newcertificate. The acceptable values for this parameter are:

• CurveParameters
• CurveName
• None

The default value, None, indicates that this cmdlet uses the default value from the underlying keystorage provider (KSP). This parameter is not supported with the RSA algorithm or with cryptographicservice providers (CSPs).

Specifies one or more DNS names to put into the subject alternative name extension of thecertificate when a certificate to be copied is not specified via the CloneCert parameter. Thefirst DNS name is also saved as the Subject Name. If no signing certificate is specified, the firstDNS name is also saved as the Issuer Name.

Indicates that this cmdlet uses an existing key. If you do not specify this parameter, this cmdletcreates a new key. Creating a certificate from an existing key creates a new key with a newcontainer.

When you use an existing key, specify values for the Container parameter, the Providerparameter, and the CertStoreLocation parameter. CertStoreLocation determines the context.The context is user or computer.

Specifies an array of certificate extensions, as X509Extension objects, that this cmdletincludes in the new certificate.

Specifies a friendly name for the new certificate.

Specifies how a hardware key associated with the new certificate may be used. This parameter appliesonly when you specify the Microsoft Platform Crypto Provider. The acceptable values for thisparameter are:

• None
• SignatureKey
• EncryptionKey
• GenericKey
• StorageKey
• IdentityKey

The default value, None, indicates that this cmdlet uses the default value from the underlyingKSP.

Specifies the name of the hash algorithm to use to sign the new certificate. The default hashalgorithm depends on the provider that stores the private key used to sign the new certificate.

Specifies the name of the algorithm that creates the asymmetric keys that are associated with thenew certificate. Available asymmetric key algorithms are RSA and Elliptic Curve Digital SignatureAlgorithms (ECDSA).

The elliptic curve algorithm syntax is the following:

ECDSA_{curvename}

To obtain a value for {curvename}, use the certutil -displayEccCurve command.

Valid curve names contain a value in the Curve OID column in the output of thecertutil -displayEccCurve command.

Specifies a description for the private key that is associated with the new certificate.

Specifies the policy that governs the export of the private key that is associated with thecertificate.

The default value of ExportableEncrypted is not compatible with KSP and CSPs that do not allow keyexport. These include the Microsoft Smart Card Key Storage Provider and theMicrosoft Platform Crypto Key Storage Provider. Specify NonExportable for providers that do notallow key export.

Specifies a friendly name for the private key that is associated with the new certificate.

Specifies the length, in bits, of the key that is associated with the new certificate.

Specifies the file system location where this cmdlet stores the private keys associated with the newcertificate. Specify this parameter only when you specify the Microsoft Platform Crypto Provider.

Specifies the level of protection required to access the private key that is associated with thecertificate. The acceptable values for this parameter are:

• Protect
• ProtectHigh
• ProtectFingerPrint
• None

The default value, None, indicates that this cmdlet uses the default value from the underlying KSPor CSP. For most KSPs and CSPs, the default means that no user interface is required to create anduse the private key. A user interface is required if the provider always requires a user interface,such as a smart card, or if the default configuration of the provider has been changed.

Specifies whether the private key associated with the new certificate can be used for signing,encryption, or both. The acceptable values for this parameter are:

• KeyExchange
• Signature
• None

The default value, None, indicates that this cmdlet uses the default value from the underlyingCSP.

If the private key is managed by a legacy CSP, the value is KeyExchange or Signature. If the keyis managed by a Cryptography Next Generation (CNG) KSP, the value is None.

Specifies the key usages set in the key usage extension of the certificate. The acceptable valuesfor this parameter are:

• CertSign
• CRLSign
• DataEncipherment
• DecipherOnly
• DigitalSignature
• EncipherOnly
• KeyAgreement
• KeyEncipherment
• None
• NonRepudiation

The value, None, indicates that this cmdlet does not include the KeyUsage extension in the newcertificate.

Specifies the key usages for the key usages property of the private key. The acceptable values forthis parameter are:

• All
• Decrypt
• KeyAgreement
• None
• Sign

The default value, None, indicates that this cmdlet uses the default value from the underlyingKSP.

Specifies the date and time, as a DateTime object, that the certificate expires. To obtain aDateTime object, use the Get-Date cmdlet. The default value for this parameter is one yearafter the certificate was created.

Specifies the date and time, as a DateTime object, when the certificate becomes valid. Thedefault value for this parameter is 10 minutes before the certificate was created.

Specifies the personal identification number (PIN) used to access the private key of the newcertificate.

Specifies the name of the KSP or CSP that this cmdlet uses to create the certificate. SeeCryptographic Providers formore information. Some acceptable values include:

• Microsoft Software Key Storage Provider
• Microsoft Smart Card Key Storage Provider
• Microsoft Platform Crypto Provider
• Microsoft Strong Cryptographic Provider
• Microsoft Enhanced Cryptographic Provider v1.0
• Microsoft Enhanced RSA and AES Cryptographic Provider
• Microsoft Base Cryptographic Provider v1.0
• The name of a third party KSP or CSP

Specifies the name of the smart card reader on which to store the private key for the newcertificate.

Specifies the private key security descriptor as a FileSecurity object. Read access is requiredto use the private key. This parameter does not apply to providers that do not support securitydescriptors on private keys, including the smart card CSP and smart card KSP.

Specifies a serial number, as a hexadecimal string, that is associated with the new certificate. Ifyou do not specify this parameter, this cmdlet assigns a pseudo-randomly generated 16-byte value.

Specifies a Certificate object with which this cmdlet signs the new certificate. This value mustbe in the Personal certificate store of the user or device. This cmdlet must have read access to theprivate key of the certificate.

Specifies the PIN that is required to access the private key of the certificate that is used to signthe new certificate.

Specifies the name of the smart card reader that is used to sign the new certificate.

Indicates that the new certificate includes available encryption algorithms to a Secure/MultipurposeInternet Mail Extensions (S/MIME) capabilities extension.

Specifies the string that appears in the subject of the new certificate. This cmdlet prefixes CN=to any value that does not contain an equal sign. For multiple subject relative distinguished names(also known as RDNs), separate each subject relative distinguished name with a comma (,). If thevalue of the relative distinguished name contains commas, separate each subject relativedistinguished name with a semicolon (;).

Specifies an array of object identifier (also known as OID) strings that identify default extensionsto be removed from the new certificate.

Indicates that this cmdlet signs the new certificate by using a built-in test certificate. Thiscmdlet adds the built-in test certificate to the intermediate certification authority (CA)certificate store of the device.

This parameter is for test purposes only. The private key of the test root certificate isessentially public.

Specifies an array of certificate extensions, as strings, which this cmdlet includes in the newcertificate. Each string must employ one of the following formats:

{oid}={base64String}, where {oid} is the object identifier of the extension and {base64String}is a value that you provide. After decoding {base64String}, the value must be valid AbstractSyntax Notation One (ASN.1). For more information, seeAbstract Syntax Notation One (ASN.1): Specification of basic notation.

{oid}={hex}{hexadecimalString}, where {oid} is the object identifier of the extension and{hexadecimalString} is a value that you provide. After decoding {hexadecimalString}, the valuemust be valid ASN.1.

{oid}={text}{String}, where {oid} is the object identifier of the extension and {String} is avalue that you provide. {String} must contain a textual representation of the extension value in aformat specific to each object ID. When {String} is processed, it will be encoded into an ASN.1extension value before being placed into the new certificate as an extension.

To specify that an extension is critical, insert {critical} immediately following {oid}= in anyof the previous cases.

The object identifiers of some common extensions are as follows:

• Application Policy: 1.3.6.1.4.1.311.21.10
• Application Policy Mappings: 1.3.6.1.4.1.311.21.11
• Basic Constraints: 2.5.29.19
• Certificate Policies: 2.5.29.32
• Enhanced Key Usage: 2.5.29.37
• Name Constraints: 2.5.29.30
• Policy Mappings: 2.5.29.33
• Subject Alternative Name: 2.5.29.17

Application Policy extension example: 1.3.6.1.4.1.311.21.10={text}{token}={value}&{token}={value}...

You can specify the following tokens in an Application Policy extension:

• Flags: Bitwise flags in hexadecimal notation: 0x{hexadecimalNumber}
• GUID: A globally unique ID, such as this example: f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39
• Notice: Text notice
• OID: Object identifier in dotted decimal notation, such as this example: 1.2.3.4.5
• URL: The URL of a host, such as this example: http://computer07.contoso.com

To specify an Application Policy extension, specify the first object identifier, followed by zero ormore other {token}={value} entries. These entries are subordinate to the preceding objectidentifier. Specify subsequent object identifiers, each followed by its subordinate{token}={value} entries.

Application Policy Mappings extension example: 1.3.6.1.4.1.311.21.11={text}oid={oid}&oid={oid}...

Certificate Policies extension example: 2.5.29.32={text}{token}={value}&{token}={value}...

You can specify the following tokens in a Certificate Policies extension:

• Flags: Bitwise flags in hexadecimal notation: 0x{hexadecimalNumber}
• GUID: A globally unique ID, such as this example: f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39
• Notice: Text notice
• OID: Object identifier in dotted decimal notation, such as this example: 1.2.3.4.5
• URL: The URL of a host, such as this example: http://computer07.contoso.com

To specify a Certificate Policies extension, follow the same syntax as an Application Policyextension.

Enhanced Key Usage Object Identifiers extension example: 2.5.29.37={text}{oid},{oid}...

These key usages have the following object identifiers:

• Client Authentication: 1.3.6.1.5.5.7.3.2
• Server Authentication: 1.3.6.1.5.5.7.3.1
• Secure Email: 1.3.6.1.5.5.7.3.4
• Code Signing: 1.3.6.1.5.5.7.3.3
• Timestamp Signing: 1.3.6.1.5.5.7.3.8

Name Constraints extension example:2.5.29.30={text}subtree=include&{token}={value}&{token}={value}&subtree=exclude&{token}={value}...

A Name Constraints extension can have Subtree values of Include and Exclude to specifyincluded and excluded names.

You can specify the following tokens in a Name Constraints extension:

• DirectoryName: A distinguished name such as: CN=Name,DC=Domain,DC=com
• DNS: A computer name in the following format: computer.contoso.com
• Email: An email address, such as this example: admin@contoso.com
• IPAddress: {IPV4 address},{IPV4 subnet mask} or {IPV6 address},{IPV6 subnet mask}
• RegisteredID: ID in dotted decimal notation, such as this example: 1.2.3.4.5
• UPN: A user principal name in the following format: admin@contoso.com
• URL: The URL of a host, such as this example: http://computer07.contoso.com/index.html

Policy Mapping extension example: 2.5.29.33={text}oid={oid}&oid={oid}...

Subject Alternative Name extension example: 2.5.29.17={text}token=value&token=value...

You can specify the following tokens in a Subject Alternative Name extension:

• DirectoryName: A distinguished name such as: CN=Name,DC=Domain,DC=com
• DNS: A computer name in the following format: computer.contoso.com
• Email: An email address, such as this example: admin@contoso.com
• GUID: A globally unique ID, such as this example: f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39
• IPAddress: {IPV4 address},{IPV4 subnet mask} or {IPV6 address},{IPV6 subnet mask}
• RegisteredID: ID in dotted decimal notation, such as this example: 1.2.3.4.5
• UPN: A user principal name in the following format: admin@contoso.com
• URL: The URL of a host, such as this example: http://computer07.contoso.com/index.html

Specifies the type of certificate that this cmdlet creates.

Shows what would happen if the cmdlet runs. The cmdlet is not run.