Applies to: Exchange Server 2007
Topic Last Modified: 2007-09-13

Use the New-ExchangeCertificate cmdlet to create a new self-signed certificate or a new certificate request for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) services.

Important:
There are many variables that you must consider when configuring certificates for SSL and TLS services. You must understand how these variables may affect your overall configuration. Before you continue, see Certificate Use in Exchange Server 2007.

Syntax

New-ExchangeCertificate [-DomainController <String>] [-DomainName <MultiValuedProperty>] [-FriendlyName <String>] [-IncludeAcceptedDomains <SwitchParameter>] [-IncludeAutoDiscover <SwitchParameter>] [-Instance <X509Certificate2>] [-KeySize <Int32>] [-PrivateKeyExportable <$true | $false>] [-Services <None | IMAP | POP | UM | IIS | SMTP>] [-SubjectName <X500DistinguishedName>]
New-ExchangeCertificate [-BinaryEncoded <SwitchParameter>] [-DomainController <String>] [-DomainName <MultiValuedProperty>] [-Force <SwitchParameter>] [-FriendlyName <String>] [-GenerateRequest <SwitchParameter>] [-IncludeAcceptedDomains <SwitchParameter>] [-IncludeAutoDiscover <SwitchParameter>] [-Instance <X509Certificate2>] [-KeySize <Int32>] [-Path <String>] [-PrivateKeyExportable <$true | $false>] [-SubjectName <X500DistinguishedName>]

Parameters

Parameter Required Type Description

BinaryEncoded

Optional

System.Management.Automation.SwitchParameter

Use this parameter switch to specify how the exported file will be encoded. By default, this cmdlet will create a Base64-encoded file.

To create a DER-encoded file, set this parameter to $True.

DomainController

Optional

System.String

To specify the fully qualified domain name (FQDN) of the domain controller that retrieves data from the Active Directory directory service, include the DomainController parameter in the command. The DomainController parameter is not supported on computers that run the Edge Transport server role. The Edge Transport server role writes only to the local Active Directory Application Mode (ADAM) instance.

DomainName

Optional

Microsoft.Exchange.Data.MultiValuedProperty

Use this parameter to populate one or more domain names (FQDN) or server names in the resulting certificate request.

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

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

Force

Optional

System.Management.Automation.SwitchParameter

Use this parameter switch to overwrite an existing certificate request file that matches the same file path as specified in this cmdlet.

By default, this cmdlet will not overwrite existing files.

FriendlyName

Optional

System.String

Use this parameter to specify a friendly name for the resulting certificate. The friendly name must be less than 64 characters.

The default friendly name is "Microsoft Exchange".

GenerateRequest

Optional

System.Management.Automation.SwitchParameter

Use this parameter to specify the type of certificate object to create.

By default, this parameter will create a self-signed certificate in the local computer certificate store.

To create a certificate request for a PKI certificate (PKCS #10) in the local request store, set this parameter to $True.

IncludeAcceptedDomains

Optional

System.Management.Automation.SwitchParameter

Use this parameter to include all the defined accepted domains in the domain names field.

You can also specify a DomainName parameter in the request. The resulting certificate or request will contain the union of the two values.

IncludeAutoDiscover

Optional

System.Management.Automation.SwitchParameter

Use this parameter to add the prefix, "autodiscover" to each domain name that is generated for the resulting certificate. You can only specify this parameter when you are running this cmdlet on an Exchange Server That Has the Client Access server role installed. Note: This parameter will not add the "autodiscover" prefix if the domain name already contains the prefix.

Instance

Optional

System.Security.Cryptography.X509Certificates.X509Certificate2

Use this parameter to pass a whole object to the command to be processed. The Instance parameter is mainly used in scripts where a whole object must be passed to the command.

KeySize

Optional

System.Int32

Use this parameter to specify the size (in bits) of the RSA public key associated with the certificate that you are creating.

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

Path

Optional

System.String

Use this parameter to specify a path of the resulting PKCS #10 request file.

This parameter is only valid if GenerateRequest is set to $true.

The New-ExchangeCertificate cmdlet will generate a certificate request in the local certificate store even if the Path parameter is specified. The certificate request that is generated in the local certificate store contains the keys for the resulting certificate.

You must specify the name of the request file when you use this parameter. The name must end with the .req extension, for example:

Copy Code
-Path c:\certificates\request.req

The .req file is used by the certification authority (CA) to generate a certificate.

PrivateKeyExportable

Optional

System.Boolean

Use this parameter to specify whether the resulting certificate will have an exportable private key.

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

You must understand that if you cannot export the private key, the certificate itself cannot be exported and imported.

Set this parameter to $true to allow private key exporting from the resulting certificate.

Services

Optional

Microsoft.Exchange.Management.SystemConfigurationTasks.AllowedServices

Use this parameter to specify the services that will use the resulting certificate. You cannot specify services if you have set the GenerateRequest value to $true.

Valid entries include a combination of the following:

  • IMAP

  • POP

  • UM

  • IIS

  • SMTP

  • None

To create a self-signed certificate for multiple services, enclose the values in quotation marks and separate them by commas, for example:

Copy Code
-Services "IMAP, POP, IIS"

To create a certificate that is disabled so that you can export it to another computer, set this parameter to None.

The default is SMTP.

SubjectName

Optional

System.Security.Cryptography.X509Certificates.X500DistinguishedName

Use this parameter to specify the Subject Name on the resulting certificate.

The Subject Name of a certificate is the field that is used by DNS-aware services. The Subject Name field binds a certificate to a particular server or domain name.

A subject name is an X.500 distinguished name which consists of one or more relative distinguished names (also known as RDN).

By default, the FQDN of the server where the cmdlet is run will be used as the CN in the resulting certificate.

Detailed Description

The New-ExchangeCertificate cmdlet uses many parameters of type SwitchParameter. For more information about how to use this type, see "Switch Parameters" in Parameters.

To run the New-ExchangeCertificate cmdlet, the account you use must be delegated the following:

  • Exchange Server Administrator role and local Administrators group for the target server

To run the New-ExchangeCertificate cmdlet on a computer that has the Edge Transport server role installed, you must log on by using an account that is a member of the local Administrators group on that computer.

For more information about permissions, delegating roles, and the rights that are required to administer Microsoft Exchange Server 2007, see Permission Considerations.

Input Types

Return Types

Errors

Error Description

 

Exceptions

Exceptions Description

 

Example

The first example shows running the cmdlet without arguments. When you run the New-ExchangeCertificate cmdlet without arguments, a self-signed certificate for SMTP SSL/TLS is generated. The certificate has the local computer FQDN as the Subject Name. This internal transport certificate can be used, as is, for direct trust authentication and encryption between Edge Transport servers and Hub Transport servers. The Network Services local security group is also given read access to the private key associated with the certificate. In addition, the certificate is published to Active Directory so that Exchange Server direct trust can be used to validate the authenticity of the server for mutual TLS.

The second example shows running the cmdlet so that a certificate request is generated and copied to a path on the local computer. The certificate that results will have the following attributes associated with it:

  • Subject Name: c=<ES>,o=<Diversión de Bicicleta>,cn=mail1. DiversiondeBicicleta.com

  • Subject Alternate Names: woodgrove.com and example.com

  • An exportable private key

For more examples, see Creating a Certificate or Certificate Request for TLS and the following Exchange Server Team Blog entries:

For more information, see Domain Security White Paper.

Copy Code
New-ExchangeCertificate
New-ExchangeCertificate -GenerateRequest -Path c:\certificates\request.req -SubjectName "c=ES, o=Diversión de Bicicleta, cn=mail1. DiversiondeBicicleta.com" -DomainName woodgrove.com, example.com -PrivateKeyExportable $true