Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

Topic Last Modified: 2012-11-19

Use the New-ExchangeCertificate cmdlet to create a self-signed certificate, renew an existing self-signed certificate, or generate a new certificate request for obtaining a certificate from a certification authority (CA).

Important:
There are many variables that you must consider when configuring certificates for Secure Sockets Layer (SSL) and Transport Layer Security (TLS). You must understand how these variables may affect your overall configuration. For more information and before you continue, see Understanding TLS Certificates.

Syntax

New-ExchangeCertificate [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-DomainName <MultiValuedProperty>] [-Force <SwitchParameter>] [-FriendlyName <String>] [-IncludeAcceptedDomains <SwitchParameter>] [-IncludeAutoDiscover <SwitchParameter>] [-IncludeServerFQDN <SwitchParameter>] [-IncludeServerNetBIOSName <SwitchParameter>] [-Instance <X509Certificate2>] [-KeySize <Int32>] [-PrivateKeyExportable <$true | $false>] [-Server <ServerIdParameter>] [-Services <None | IMAP | POP | UM | IIS | SMTP | Federation>] [-SubjectKeyIdentifier <String>] [-SubjectName <X500DistinguishedName>] [-WhatIf [<SwitchParameter>]]
New-ExchangeCertificate [-BinaryEncoded <SwitchParameter>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-DomainName <MultiValuedProperty>] [-Force <SwitchParameter>] [-FriendlyName <String>] [-GenerateRequest <SwitchParameter>] [-IncludeAcceptedDomains <SwitchParameter>] [-IncludeAutoDiscover <SwitchParameter>] [-IncludeServerFQDN <SwitchParameter>] [-IncludeServerNetBIOSName <SwitchParameter>] [-Instance <X509Certificate2>] [-KeySize <Int32>] [-PrivateKeyExportable <$true | $false>] [-Server <ServerIdParameter>] [-SubjectKeyIdentifier <String>] [-SubjectName <X500DistinguishedName>] [-WhatIf [<SwitchParameter>]]

Detailed Description

Microsoft Exchange Server 2010 uses certificates for SSL and TLS encryption. The New-ExchangeCertificate cmdlet uses many parameters of type SwitchParameter. For more information about how to use this parameter type, see "Switch Parameters" in Parameters.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Certificate management" entry in the Exchange and Shell Infrastructure Permissions topic.

Parameters

Parameter Required Type Description

BinaryEncoded

Optional

System.Management.Automation.SwitchParameter

The BinaryEncoded switch specifies how the certificate request is encoded. By default, this cmdlet creates a Base64-encoded request.

Use this switch to create a DER-encoded request.

Note:
The BinaryEncoded switch is available only if you use the GenerateRequest switch.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory. The DomainController parameter isn't supported on the Edge Transport server role. The Edge Transport server role writes only to the Active Directory Lightweight Directory Services (AD LDS) instance.

DomainName

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The DomainName parameter specifies one or more FQDNs or server names to be populated in the Subject Alternative Name field of the resulting certificate request or self-signed certificate.

Domain names are restricted to the characters a through z, 0 through 9, and the hyphen (-). Each domain name can't be longer than 255 characters.

To enter multiple domain or server names, you must enter the names separated by commas.

Note:
If this parameter isn't specified, and you don't use the IncludeAcceptedDomains, IncludeAutoDiscover, IncludeServerFQDN, and IncludeServerNetBIOSName switches, the server's hostname and FQDN are added by default.

Force

Optional

System.Management.Automation.SwitchParameter

The Force switch specifies whether to override the confirmation prompt and set the new self-signed certificate as the default certificate for TLS for internal SMTP communication. By default, this cmdlet requires a confirmation before setting the new certificate as the default certificate for TLS encryption of internal SMTP communication.

FriendlyName

Optional

System.String

The FriendlyName parameter specifies a friendly name for the certificate. The friendly name must be less than 64 characters.

The default friendly name is Microsoft Exchange.

GenerateRequest

Optional

System.Management.Automation.SwitchParameter

The GenerateRequest switch specifies whether to generate a certificate request for a public key infrastructure (PKI) certificate (PKCS #10) in the local request store.

By default, this cmdlet creates a self-signed certificate in the local computer certificate store. The GenerateRequest switch overrides this behavior.

IncludeAcceptedDomains

Optional

System.Management.Automation.SwitchParameter

The IncludeAcceptedDomains switch specifies whether all accepted domains in the organization are included in the Subject Alternative Name field of the certificate request or self-signed certificate.

You can also specify one or more domain names using the DomainName parameter in addition to the accepted domains. The resulting certificate or request contains the specified domains and all accepted domains.

Note:
When you use the IncludeAcceptedDomains switch, any accepted domains you specify in the DomainName parameter aren't duplicated.

IncludeAutoDiscover

Optional

System.Management.Automation.SwitchParameter

The IncludeAutoDiscover switch specifies whether to add a Subject Alternative Name with the prefix autodiscover for each accepted domain in the Exchange organization. For example, if the organization has the accepted domains woodgrovebank.com and woodgrovebank.co.uk, using this switch will result in addition of the following Subject Alternative Name(s):

  • autodiscover.woodgrovebank.com

  • autodiscover.woodgrovebank.co.uk

The switch can only be used on Client Access servers.

The autodiscover prefix isn't added if the domain name already contains the prefix.

IncludeServerFQDN

Optional

System.Management.Automation.SwitchParameter

The IncludeServerFQDN switch specifies whether to include the FQDN of the server in the Subject Alternative Name field of the new certificate request or self-signed certificate.

Note:
When you use the IncludeServerFQDN switch, any FQDNs you specify in the DomainName parameter aren't duplicated.

IncludeServerNetBIOSName

Optional

System.Management.Automation.SwitchParameter

The IncludeServerNetBIOSName switch specifies whether to include the NetBIOS name of the server in the Subject Alternative Name field of the new certificate request or self-signed certificate.

Note:
When you use the IncludeServerNetBIOSName switch, any NetBIOS names you specify in the DomainName parameter aren't duplicated.

Instance

Optional

System.Security.Cryptography.X509Certificates.X509Certificate2

The Instance parameter is no longer used and will be deprecated.

KeySize

Optional

System.Int32

The KeySize parameter specifies the size (in bits) of the RSA public key associated with the certificate that you're creating.

Acceptable values are 4096, 2048, and 1024. The default value is 2048.

PrivateKeyExportable

Optional

System.Boolean

The PrivateKeyExportable parameter specifies whether the new certificate has an exportable private key.

By default, all certificate requests and certificates created by this cmdlet don't allow the private key to be exported.

Important:
If you can't export the private key, the certificate can't be exported or imported.

To allow exporting the private key when exporting the certificate, set this parameter to $true.

Server

Optional

Microsoft.Exchange.Configuration.Tasks.ServerIdParameter

The Server parameter specifies the server name for which you want to create the new certificate. If not specified, the certificate or certificate request is generated for the Exchange server on which the command is executed.

Services

Optional

Microsoft.Exchange.Management.SystemConfigurationTasks.AllowedServices

The Services parameter specifies the services that will use the resulting certificate.

Important:
You can specify services using the New-ExchangeCertificate cmdlet only if you're generating a self-signed certificate. If you're creating a certificate request for a CA using the GenerateRequest switch, you must install the certificate after it's issued by the CA, and then specify services using the Enable-ExchangeCertificate cmdlet.

Valid values include a combination of the following:

  • IIS

  • IMAP

  • None

  • POP

  • SMTP

  • UM

The default values are IMAP, POP, and SMTP.

To create a certificate that isn't enabled for any Exchange service so that you can export it to another computer, set this parameter to None and set the PrivateKeyExportable parameter to $true.

SubjectKeyIdentifier

Optional

System.String

The SubjectKeyIdentifier parameter specifies the subject key identifier extension for the certificate, which isn't required for normal operation.

SubjectName

Optional

System.Security.Cryptography.X509Certificates.X500DistinguishedName

The SubjectName parameter specifies the subject name of the resulting certificate. A subject name is an X.500 distinguished name that consists of one or more relative distinguished names (also known as RDNs).

The subject name of a certificate is the field used by Domain Name System (DNS)-aware services. It binds a certificate to a particular server or domain name.

If the SubjectName parameter isn't specified, the host name of the server where the cmdlet is run is used as the common name (CN) in the resulting certificate. For example, for the server EXMBX01, the SubjectName parameter value CN=EXMBX01 is used.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.

Examples

EXAMPLE 1

This example runs the New-ExchangeCertificate cmdlet without parameters and generates a self-signed certificate. The certificate has the FQDN of the local computer as the subject name. This default certificate can be used for direct trust authentication and encryption between Edge Transport servers and Hub Transport servers. The Network Services local security group is also provided read access to the private key associated with the certificate. In addition, the certificate is published to Active Directory so that Exchange direct trust can validate the authenticity of the server for mutual TLS.

Copy Code 
New-ExchangeCertificate

EXAMPLE 2

This example outputs the certificate request in Base64 format to the command-line console. You must send the certificate request to a CA within the organization, a trusted CA outside the organization, or a commercial CA. You can do this by pasting the certificate request output in an e-mail message or in the appropriate field on the certificate request Web page of the CA. You can also save the certificate request to a file using a text editor such as Notepad.

The certificate that results has the following attributes associated with it:

  • Subject name: c=<ES>,o=<Woodgrove Bank>,cn=mail1.woodgrovebank.com

  • Subject alternate names: woodgrovebank.com and example.com

  • An exportable private key

Copy Code 
New-ExchangeCertificate -GenerateRequest -SubjectName "c=US, o=Woodgrove Bank, cn=mail1.woodgrovebank.com" -DomainName woodgrovebank.com, example.com -PrivateKeyExportable $true

EXAMPLE 3

This example is a variation of the certificate request generated in EXAMPLE 2. However, instead of manually copying and pasting the certificate request output produced by the cmdlet, the Set-Content cmdlet is used to write the request to a file.

The certificate that results has the following attributes associated with it:

  • Subject name: c=<ES>,o=<Woodgrove Bank>,cn=mail1.woodgrovebank.com

  • Subject alternate names: woodgrovebank.com and example.com

  • An exportable private key

In the first step, the New-ExchangeCertificate cmdlet is used to generated the certificate request and save the output in a variable named $Data.

Copy Code 
$Data = New-ExchangeCertificate -GenerateRequest -SubjectName "c=US, o=Woodgrove Bank, cn=mail1.woodgrovebank.com" -DomainName woodgrovebank.com, example.com -PrivateKeyExportable $true

In the second step, the Set-Content cmdlet is used to write data from the variable to the certificate request file MyCertRequest.req in the Docs folder.

Copy Code 
Set-Content -path "C:\Docs\MyCertRequest.req" -Value $Data

EXAMPLE 4

This example creates a DER-encoded certificate request file. The BinaryEncoded parameter is used to generate a DER-encoded certificate request. The Set-Content cmdlet is used with the Encoding parameter to write the request to a file.

The certificate that results will have the following attributes associated with it:

  • Subject name: c=ES,o=Woodgrove Bank,cn=mail1.woodgrovebank.com

  • Subject alternate names: woodgrovebank.com and example.com

  • An exportable private key

In the first step, the New-ExchangeCertificate cmdlet is used to generate the certificate request in DER-encoded format and save the output in a variable named $Data.

Copy Code 
$Data = New-ExchangeCertificate -GenerateRequest -SubjectName "c=ES, o=Woodgrove Bank, cn=mail1.woodgrovebank.com" -DomainName woodgrovebank.com, example.com -BinaryEncoded -PrivateKeyExportable $true

In the second step, the Set-Content cmdlet is used to write data from the variable to the certificate request file MyCertRequest.req in the Docs folder.

Copy Code 
Set-Content -path "C:\Docs\MyCertRequest.req" -Value $Data.FileData -Encoding Byte

EXAMPLE 5

This example shows how to renew a self-signed certificate.

Copy Code 
Get-ExchangeCertificate -Thumbprint c4248cd7065c87cb942d60f7293feb7d533a4afc | New-ExchangeCertificate