[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Provides a way to request certificates for use with Microsoft Communications Server 2010 servers and server roles. Also provides a way to check the status of existing certificate requests and, if needed, to cancel any (or all) of those requests.

Syntax

Request-CsCertificate -New <SwitchParameter> -Type <String[]> [-CA <String>] [-CaAccount <String>] [-CaPassword <String>] [-City <String>] [-ClientEKU <$true | $false>] [-ComputerFqdn <Fqdn>] [-Confirm [<SwitchParameter>]] [-Country <String>] [-DomainName <String>] [-Force <SwitchParameter>] [-FriendlyName <String>] [-GlobalCatalog <Fqdn>] [-GlobalSettingsDomainController <Fqdn>] [-KeyAlg <RSA | ECDH_P256 | ECDH_P384 | ECDH_P521>] [-KeySize <Int32>] [-Organization <String>] [-OU <String>] [-Output <String>] [-PrivateKeyExportable <$true | $false>] [-Report <String>] [-State <String>] [-Template <String>] [-WhatIf [<SwitchParameter>]]

Request-CsCertificate -List <SwitchParameter> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-RequestId <Int32>] [-WhatIf [<SwitchParameter>]]

Request-CsCertificate -Retrieve <SwitchParameter> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-RequestId <Int32>] [-WhatIf [<SwitchParameter>]]

Request-CsCertificate -Clear <SwitchParameter> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-RequestId <Int32>] [-WhatIf [<SwitchParameter>]]

Parameters

Parameter Required Type Description

Type

Required

String

Type of certificate being requested. Certificate types include (but are not limited to):

Default

WebServicesInternal

WebServicesExternal

ProvisionService

PICWebService

Internal

AccessEdgeExternal

DataEdgeExternal

BandwidthPolicyToken

MediaRelayEdgeToken

For example, this syntax requests a new ProvisionService certificate: -Type ProvisionService.

FriendlyName

Optional

String

User-assigned name that makes it easier to identify the certificate.

Output

Optional

String

Path to the certificate file. If you do not want to immediately import the new certificate into Communications Server, use the Output parameter and specify a file path for the certificate; for example: -Output C:\Certificates\New_certificate.pfx. The new certificate will be copied to the specified file path, but will not be imported into Communications Server. However, this operation can be done later using Import-CsCertificate.

CA

Optional

String

Fully qualified domain name (FQDN) that points to the certification authority ( CA). For example: -CA "atl-ca-001.litwareinc.com\myca". To obtain a list of known CAs, type the following at the Windows PowerShell prompt, and then press ENTER: certutil. The Config property indicates the location of a CA.

CaAccount

Optional

String

Account name of the user requesting the new certificate, using the format domain_name\user_name. For example: -CaAccount "litwareinc\kenmyer". If not specified, Request-CsCertificate will use the credentials of the logged-on user when requesting the new certificate.

CaPassword

Optional

String

Password for the user requesting the new certificate (specified using the CaAccount parameter).

Template

Optional

String

Indicates the certificate template to be used when generated the new certificate; for example: -Template "Web Server". The requested template must be installed on the CA.

DomainName

Optional

String

Name of your Active Directory domain.

OU

Optional

String

Active Directory organizational unit for the computer that will be assigned the new certificate.

Organization

Optional

String

Name of the organization requesting the new certificate. For example: -Organization "Litwareinc".

City

Optional

String

City where the certificate will be deployed.

State

Optional

String

U.S. state where the certificate will be deployed. For example: -State WA.

Country

Optional

String

Country or region where the certificate will be deployed.

KeySize

Optional

Integer

Indicates the size (in bits) of the private key used by the certificate; in general, larger key sizes are more secure are less-likely to be cracked. For example: -KeySize 2048.

ClientEKU

Optional

Boolean

Set this parameter to True if the certificate is to be used for client authentication. This type of authentication is required if you want your users to be able to exchange instant messages with people who have accounts with AOL. The EKU portion of the parameter name is short for extended key usage; the extended key usage field lists the valid uses for the certificate.

PrivateKeyExportable

Optional

Boolean

Set this parameter to True if you want to make the certificate’s private key exportable. When a private key is exportable, the certificate can be copied and used on multiple computers.

KeyAlg

Optional

PS List Modifier

Indicates the type of cryptographic algorithm to be used in generating the public and private keys for the new certificate. Valid key algorithms include:

RSA

ECDH_P256

ECDH_P384

ECDH_P521

RequestID

Optional

Integer

User-assigned identification number. The RequestID can be any integer value between 0 and 2147483647.

Report

Optional

String

Enables you to specify a file path for the log file created when the cmdlet runs. For example: -Report "C:\Logs\Certificates.xml"

Clear

Optional

Switch Parameter

ComputerFqdn

Optional

String

GlobalCatalog

Optional

String

GlobalSettingsDomainController

Optional

String

List

Optional

Switch Parameter

New

Optional

Switch Parameter

Force

Optional

Switch Parameter

WhatIf

Optional

Switch Parameter

Describes what would happen if you executed the command without actually executing the command.

Confirm

Optional

Switch Parameter

Prompts you for confirmation before executing the command.

Detailed Description

Communications Server 2010 uses certificates as a way for servers and server roles to verify their identities; for example, Edge Servers use certificates to verify that the computer they are communicating with really is a Front End Server and vice versa. In order to fully implement Communications Server, you will need to have the appropriate certificates assigned to the appropriate server roles.

One way to request certificates for use with Communications Server is to use the Request-CsCertificate cmdlet. You can use other standard Windows tools in order to request certificates for use with Communications Server. One major advantage to using Request-CsCertificate, however, is the fact that the cmdlet will analyze your topology before contacting the certification authority (CA). Based on that analysis, Request-CsCertificate will automatically request a certificate with the property Subject Name and Subject Alternate Name fields.

Note that you must have your own CA in order to use Request-CsCertificate. Note as well that Request-CsCertificate is designed to request certificates specifically for use with Communications Server. It is not designed to be an all-purpose certificate management tool.

In addition to requesting new certificates, this cmdlet can also be used to review any pending certificate requests, provided those requests were made using Request-CsCertificate. Request-CsCertificate can also be used to delete pending certificate requests, provided, again, that those requests were made using the cmdlet.

Return Types

Request-CsCertificate helps manage instances of the Microsoft.Rtc.Management.Deployment.CertificateReference object.

Examples

-------------------------- Example 1 ------------------------Add code example

Copy Code 
Request-CsCertificate -New -Type BandwidthPolicyToken -CA "atl-ca-001.litwareinc.com\myca"

The command shown in Example 1 creates a new certificate request; in particular, it contacts the CA atl-ca-001.litwareinc.com\myca and requests a new BandwidthPolicyToken certificate.

-------------------------- Example 2 ------------------------Add code example

Copy Code 
Request-CsCertificate -List

The preceding command lists all the pending certificate requests that were made by using Request-CsCertificate.