Share via


Import-ExchangeCertificate

 

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

Use the Import-ExchangeCertificate cmdlet for the following purposes:

  • To import a certificate that has been issued from a certification authority.

  • To import an existing certificate and private key from a PKCS #12 (.pfx or .p12) file to the certificate store on the local computer. PKCS #12 is the Personal Information Exchange Syntax Standard that is specified by RSA Laboratories (http://www.rsasecurity.com/rsalabs/node.asp?id=2138).

    Note

    The third-party Web site information in this topic is provided to help you find the technical information you need. The URLs are subject to change without notice.

Important

There are many factors to consider when you configure certificates for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) services. You must understand how these factors may affect your overall configuration. Before you continue, read Creating a Certificate or Certificate Request for TLS.

Syntax

Import-ExchangeCertificate -Path <String> [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-FriendlyName <String>] [-Password <SecureString>] [-WhatIf [<SwitchParameter>]]

Import-ExchangeCertificate [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-FriendlyName <String>] [-Instance <String[]>] [-Password <SecureString>] [-WhatIf [<SwitchParameter>]]

Detailed Description

The certificate may be published in the Active Directory directory service for the purposes of direct trust by using mutual TLS if the following conditions are true:

  • The certificate is marked as a Simple Mail Transfer protocol (SMTP) TLS certificate.

  • The Subject Name on the certificate matches the fully qualified domain name (FQDN) of the local computer.

The certificate may be published in Active Directory by Edge Subscription if the following conditions are true:

  • You import the certificate to an Edge Transport server computer.

  • The certificate has a FQDN that matches the server FQDN.

The Import-ExchangeCertificate cmdlet imports either a certificate that is issued from an outstanding request or a PKCS #12 file.

To run the Import-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 Import-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

Path

Required

System.String

Use this parameter to specify a path of the file that you want to import.

You must specify the name of the request file when you use this parameter, as in the following example:

-Path c:\certificates\import.pfx

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

Microsoft.Exchange.Data.Fqdn

To specify the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory, include the DomainController parameter on the command. The DomainController parameter is not supported on computers that run the Edge Transport server role. The Edge Transport server role reads and writes only to the local ADAM instance.

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".

Instance

Optional

System.String[]

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

Password

Optional

System.Security.SecureString

Use this parameter to specify the password for the key that will be exported with this command. Use the Get-Credential cmdlet to store the password variable.

The Get-Credential cmdlet will prompt you for a user name and password, but only the password field is used to export or import the certificate. Therefore, you don't have to use a real domain name or user name in the Name field. See the example for implementation details.

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 how to import an existing certificate from a PKCS #12 file.

The second example shows how to import a chain of certificates that is issued for a request from a file.

Import-ExchangeCertificate -Path c:\certificates\import.pfx -Password:(Get-Credential).password
Import-ExchangeCertificate -Path c:\certificates\import.p7b