Default FTP SSL Client Certificate Settings <sslClientCertificates>

Overview

The <sslClientCertificates> element specifies the SSL client certificate options for FTP sites. More specifically, this element contains the following attributes, which are discussed in detail in the configuration section of this topic:

  • The clientCertificatePolicy attribute specifies whether client certificates will be allowed, required, or ignored.
  • The validationFlags attribute specifies an FTP site's behavior for checking for certificate revocation.
  • The revocationFreshnessTime attribute specifies the amount of time that the revocation list is valid.
  • The revocationUrlRetrievalTimeout attribute specifies the time-out for retrieving certificate revocation information
  • The useActiveDirectoryMapping attribute specifies whether Active Directory mapping should be allowed for client certificates. Note: This attribute is used in combination with the <clientCertAuthentication> element to configure certificate mapping by using Active Directory.

Compatibility

Version Notes
IIS 8.5 The <sslClientCertificates> element was not modified in IIS 8.5.
IIS 8.0 The <sslClientCertificates> element was not modified in IIS 8.0.
IIS 7.5 The <sslClientCertificates> element of the <security> element ships as a feature of IIS 7.5.
IIS 7.0 The <sslClientCertificates> element of the <security> element was introduced in FTP 7.0, which was a separate download for IIS 7.0.
IIS 6.0 The <ftpServer> element and its child elements replace the IIS 6.0 FTP settings that were located in the LM/MSFTPSVC metabase path.

Note: The FTP 7.0 and FTP 7.5 services shipped out-of-band for IIS 7.0, which required downloading and installing the modules from the following URL:

http://www.iis.net/expand/FTP

With Windows 7 and Windows Server 2008 R2, the FTP 7.5 service ships as a feature for IIS 7.5, so downloading the FTP service is no longer necessary.

Setup

To support FTP publishing for your Web server, you must install the FTP service. To do so, use the following steps.

Windows Server 2012 or Windows Server 2012 R2

  1. On the taskbar, click Server Manager.
  2. In Server Manager, click the Manage menu, and then click Add Roles and Features.
  3. In the Add Roles and Features wizard, click Next. Select the installation type and click Next. Select the destination server and click Next.
  4. On the Server Roles page, expand Web Server (IIS), and then select FTP Server.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will need to select FTP Extensibility, in addition to FTP Service.
    .
  5. Click Next, and then on the Select features page, click Next again.
  6. On the Confirm installation selections page, click Install.
  7. On the Results page, click Close.

Windows 8 or Windows 8.1

  1. On the Start screen, move the pointer all the way to the lower left corner, right-click the Start button, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows features on or off.
  3. Expand Internet Information Services, and then select FTP Server.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  4. Click OK.
  5. Click Close.

Windows Server 2008 R2

  1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
  2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
  3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
  4. On the Select Role Services page of the Add Role Services Wizard, expand FTP Server.
  5. Select FTP Service.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  6. Click Next.
  7. On the Confirm Installation Selections page, click Install.
  8. On the Results page, click Close.

Windows 7

  1. On the taskbar, click Start, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
  3. Expand Internet Information Services, and then FTP Server.
  4. Select FTP Service.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  5. Click OK.

Windows Server 2008 or Windows Vista

  1. Download the installation package from the following URL:
  2. Follow the instructions in the following walkthrough to install the FTP service:

How To

At this time there is no user interface that enables you to configure the client certificate authentication settings for an FTP site. See the Configuration and Sample Code sections of this document for additional information about how to configure the client certificate authentication settings custom features to an FTP site.

Configuration

Attributes

Attribute Description
clientCertificatePolicy Optional enum attribute.

Specifies the client certificate policy.
Value Description
CertIgnore Specifies that client certificates will not be negotiated for SSL session.

The numeric value is 0.
CertAllow Specifies that client certificates will be allowed. If the client chooses to send a certificate, then certificate must be valid and the server must be able to successfully validate it.

The numeric value is 1.
CertRequire Specifies that client certificates will be required. FTP clients will not be allowed to connect unless they send a valid client certificate to the server.

The numeric value is 2.
The default value is CertIgnore.
validationFlags Optional flags attribute.

Specifies the flags that affect client certificate validation.
Value Description
NoRevocationCheck

Specifies that certificate revocation checks will be skipped.

Warning: It is not recommended to skip revocation validation.

The numeric value is 1.

CertChainRevocationCheckCacheOnly Specifies that revocation checking only accesses cached URLs.

The numeric value is 2.
CertChainCacheOnlyUrlRetrieval Specifies only cached URLs in building a certificate chain. The Internet and intranet are not searched for URL-based objects.

The numeric value is 4.
CertNoUsageCheck Does not check client certificate for usage flags. Usage check is enabled by default and it is meant to assure that only client certificates that allow "Client authentication" are allowed.

The numeric value is 8.
There is no default value.
revocationFreshnessTime Optional timeSpan attribute.

Specifies the amount of time the revocation list is valid.

The default value is 00:00:00.
revocationUrlRetrievalTimeout Optional timeSpan attribute.

Specifies the timeout for retrieving certificate revocation information.

The default value is 00:01:00.
useActiveDirectoryMapping Optional Boolean attribute.

true if Active Directory mapping should be allowed for client certificates; otherwise, false. Active Directory mapping allows domain users to log on by using a client certificate that is configured in Active Directory.

Note: This feature only allows the SSL layer to attempt to map a client certificate to a user token; the token will not be used automatically. The <clientCertAuthentication> element is used to enable the mapped token for use by FTP instead of credentials specified through "USER" and "PASS" commands.

The default value is false.

Child Elements

None.

Configuration Sample

The following sample displays default FTP service settings that require SSL and client certificates for both the data channel and the control channel.

<siteDefaults>
 <ftpServer serverAutoStart="true">
   <security>
    <authentication>
     <anonymousAuthentication enabled="false" />
     <basicAuthentication enabled="true" />
    </authentication>
    <ssl serverCertHash="57686f6120447564652c2049495320526f636b73"
     controlChannelPolicy="SslRequire"
     dataChannelPolicy="SslRequire" />
    <sslClientCertificates clientCertificatePolicy="CertRequire"
     useActiveDirectoryMapping="false" />
   </security>
 </ftpServer>
</siteDefaults>

Sample Code

The following examples configure the default FTP service so that it requires client certificates and requires SSL for both the data channel and the control channel.

AppCmd.exe

appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.ssl.serverCertHash:"57686f6120447564652c2049495320526f636b73" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.ssl.controlChannelPolicy:"SslRequire" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.ssl.dataChannelPolicy:"SslRequire" /commit:apphost

appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.sslClientCertificates.clientCertificatePolicy:"CertRequire" /commit:apphost
appcmd.exe set config -section:system.applicationHost/sites /siteDefaults.ftpServer.security.sslClientCertificates.useActiveDirectoryMapping:"False" /commit:apphost

Note: You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection sitesSection = config.GetSection("system.applicationHost/sites");
         ConfigurationElement siteDefaultsElement = sitesSection.GetChildElement("siteDefaults");
         ConfigurationElement ftpServerElement = siteDefaultsElement.GetChildElement("ftpServer");

         ConfigurationElement securityElement = ftpServerElement.GetChildElement("security");
         ConfigurationElement sslElement = securityElement.GetChildElement("ssl");
            sslElement["controlChannelPolicy"] = @"SslAllow";
            sslElement["dataChannelPolicy"] = @"SslAllow";
            sslElement["serverCertHash"] = "57686f6120447564652c2049495320526f636b73";
         
         ConfigurationElement sslClientCertificatesElement = securityElement.GetChildElement("sslClientCertificates");
            sslClientCertificatesElement["clientCertificatePolicy"] = @"CertRequire";
            sslClientCertificatesElement["useActiveDirectoryMapping"] = false;

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim sitesSection As ConfigurationSection = config.GetSection("system.applicationHost/sites")
      Dim siteDefaultsElement As ConfigurationElement = sitesSection.GetChildElement("siteDefaults")
      Dim ftpServerElement As ConfigurationElement = siteDefaultsElement.GetChildElement("ftpServer")

      Dim securityElement As ConfigurationElement = ftpServerElement.GetChildElement("security")
      Dim sslElement As ConfigurationElement = securityElement.GetChildElement("ssl")
         sslElement("controlChannelPolicy") = "SslAllow"
         sslElement("dataChannelPolicy") = "SslAllow"
         sslElement("serverCertHash") = "57686f6120447564652c2049495320526f636b73"

      Dim sslClientCertificatesElement As ConfigurationElement = securityElement.GetChildElement("sslClientCertificates")
      sslClientCertificatesElement("clientCertificatePolicy") = "CertRequire"
      sslClientCertificatesElement("useActiveDirectoryMapping") = False
      
      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");
var siteDefaultsElement = sitesSection.ChildElements.Item("siteDefaults");
var ftpServerElement = siteDefaultsElement.ChildElements.Item("ftpServer");

var securityElement = ftpServerElement.ChildElements.Item("security");
var sslElement = securityElement.ChildElements.Item("ssl");
   sslElement.Properties.Item("controlChannelPolicy").Value = "SslAllow";
   sslElement.Properties.Item("dataChannelPolicy").Value = "SslAllow";
   sslElement.Properties.Item("serverCertHash").Value = "57686f6120447564652c2049495320526f636b73";

var sslClientCertificatesElement = securityElement.ChildElements.Item("sslClientCertificates");
   sslClientCertificatesElement.Properties.Item("clientCertificatePolicy").Value = "CertRequire";
   sslClientCertificatesElement.Properties.Item("useActiveDirectoryMapping").Value = false;

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST")
Set siteDefaultsElement = sitesSection.ChildElements.Item("siteDefaults")
Set ftpServerElement = siteDefaultsElement.ChildElements.Item("ftpServer")

Set securityElement = ftpServerElement.ChildElements.Item("security")
Set sslElement = securityElement.ChildElements.Item("ssl")
   sslElement.Properties.Item("controlChannelPolicy").Value = "SslAllow"
   sslElement.Properties.Item("dataChannelPolicy").Value = "SslAllow"
   sslElement.Properties.Item("serverCertHash").Value = "57686f6120447564652c2049495320526f636b73"

   Set sslClientCertificatesElement = securityElement.ChildElements.Item("sslClientCertificates")
      sslClientCertificatesElement.Properties.Item("clientCertificatePolicy").Value = "CertRequire"
      sslClientCertificatesElement.Properties.Item("useActiveDirectoryMapping").Value = False

adminManager.CommitChanges()
Deprecated Elements