Export (0) Print
Expand All
9 out of 46 rated this helpful - Rate this topic

New-ExchangeCertificate

 

Applies to: Exchange Server 2007 SP3, Exchange Server 2007 SP2, Exchange Server 2007 SP1

Topic Last Modified: 2009-05-11

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.

importantImportant:
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, read Certificate Use in Exchange Server 2007.

New-ExchangeCertificate [-Confirm [<SwitchParameter>]] [-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>] [-WhatIf [<SwitchParameter>]]


New-ExchangeCertificate [-BinaryEncoded <SwitchParameter>] [-Confirm [<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>] [-WhatIf [<SwitchParameter>]]

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.

 

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.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm parameter 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 parameter.

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:

-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:

-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 hostname of the server where the cmdlet is run is used as the CN in the resulting certificate. For example, if the cmdlet is run on the server EXMBX01, the Subject Name CN=EXMBX01 will be used.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf parameter instructs the command to simulate the actions that it would take on the object. By using the WhatIf parameter, 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 parameter.

 

Error Description

 

 

Exceptions Description

 

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.

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 
To ensure that you are reading the most up-to-date information and to find additional Exchange Server 2007 documentation, visit the Exchange Server TechCenter.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.