New-ExchangeCertificate
Applies to: Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3
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, read Certificate Use in Exchange Server 2007.
Syntax
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>]]
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.
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 |
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 |
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 |
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 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: 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 |
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 Valid entries include a combination of the following:
To create a self-signed certificate for multiple services, enclose the values in quotation marks and separate them by commas, for example: To create a certificate that is disabled so that you can export it to another computer, set this parameter to The default is |
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. |
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:
Lessons Learned: Generating a Certificate with a 3rd Party CA
More on Exchange 2007 and certificates - with real world scenario
Note
The content of each blog and its URL are subject to change without notice. The content within each blog is provided "AS IS" with no warranties, and confers no rights. Use of included script samples or code is subject to the terms specified in the Microsoft Terms of Use.
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