How do I get SSL Proxy to work with an OCS that requires client certificate authentication?

Products

• ProxySG Software - SGOS

Issue/Introduction

Sometimes, when a user navigates to a secured Web address in a browser, the OCS requests a certificate to authenticate the user. For intercepted HTTPS connections, this would require the ProxySG appliance to provide the certificate on behalf of the client in order for the transaction to succeed. Starting in SGOS 6.3, you can upload client certificates to the ProxySG appliance for use in SSL proxy connections requiring client authentication. The ProxySG appliance stores individual client certificates and keys in individual keyrings. You can then write policy that instructs the appliance which client certificate to use, and when to use it. For convenience, you can also group client certificates and keyrings into a keylist that contains all of the client certificates for a specific purpose, such as certificates for a specific website or certificates for users in a particular group.

NOTE: The ProxySG appliance cannot select a client certificate during SSL renegotiation. Therefore, if a website requests a client certificate during SSL renegotiation, the appliance will present an empty client certificate to the site. Keep in mind that Microsoft IIS (version 6 and later) is configured to request client certificates during SSL renegotiation handshakes by default and this feature will therefore not work with an IIS server unless you disable this behavior by enabling SSLAlwaysNegoClientCert (IIS 6), using the netsh command (IIS 7) or running the enable_ssl_renegotiate_workaround.js script (IIS 7). Refer to the Microsoft documentation for details on how to use these options. 

Resolution

 To enable SSL proxy to provide client certificates to an OCS:

1. Create the keydata file.
   Although you can import client certificates individually the same way that you would import any other certificate, the easiest way to import a large number of client certificates is using a keydata file. The keydata file bundles multiple keyrings and keylists into a single file, which allows you to import the certificates onto the ProxySG appliance in a batch. To create a keydata file:
   1. Open a new text file.
   2. Add keyring information to the keydata file in the following format:
      #keyring: <keyring_id> 
      #visibility: {show | show-director | no-show} 
      <Private Key>
      <Certificate>
      <CSR>
      
      where:
      • keyring_id—the name of the keyring
      • visibility—how the keyring is displayed in the show configuration output. Options include:
        • show— Private keys associated with keyrings created with this attribute can be displayed in the CLI or included as part of a profile or overlay pushed by Director.
        • show-director—Private keys associated with keyrings created with this attribute are part of the show configuration output if the CLI connection is secure (SSH/RSA) and the command is issued from Director.
        • no-show—Private keys associated with keyrings created with this attribute are not displayed in the show configuration output and cannot be part of a Director profile. The no-show option is provided as additional security for environments where the keys will never be used outside of the particular ProxySG.
      • <Private Key>, <Certificate>, and <CSR>—Paste the contents of the key, certificate or CSR into the text file, including the ---Begin and ---End tags.
        
        For example (note that  the private key and certificate have been truncated):
        
        #keyring:Keyring1
        #visibility:no-show
        -----BEGIN RSA PRIVATE KEY-----
        MIIEpAIBAAKCAQE...KvBgDmSIw6dTXxAT/mMUHGRd7cRew==
        -----END RSA PRIVATE KEY-----
        -----BEGIN CERTIFICATE-----
        MIIDdjCCAl4CCQC...TjUwxwboMEyL60z/tixM=
        -----END CERTIFICATE-----
        #keyring:Keyring2
        .
        .
        .
        
        NOTE: If you plan to include encrypted keys in the keydata file, all encrypted keys must use the same encryption passphrase.
         
   3. (optional) Add keylist information to the file in the following format:
      #keylist: <keylist_name>
      #extractor: <extractor>
      <keyring_id>
      <keyring_id>
      
      where:
      • keylist_name—The name of the keylist..
      • extractor—A string that identifies which certificate field attribute value to extract to determine a policy match, using the $(field.attribute) syntax. Substitutions from all attributes of Subject, Issuer, SubjectAltName, IssuerAltName, and SerialNumber certificate fields are supported.
      • keyring_id—List any keyrings to include in the keylist. The keyrings may be included in the keydata file, or may be keyrings that already exist on the ProxySG appliance.
   4. Save the file as .txt on a Web server that can be accessed by the ProxySG appliance.
       
2. Import the client certificates onto the ProxySG appliance.
   1. Select Configuration > SSL > Keyrings > Import.
   2. In the URL field, type the path to the keydata file you created.
   3. (Optional) If you have encrypted the private keys in the keydata file, enter the Passphrase for the private keys. All keyrings or keylists being imported must have the same Passphrase for the import to be successful.
   4. Click Import.
   5. Click Apply.
       
3. (Optional) Group client certificates into keylists.
   For convenience, you can group client certificates and keyrings into a keylist that contains all of the client certificates for a specific purpose, such as certificates for a specific website or certificates for users in a particular group. This allows you to write a single policy rule that references a keylist rather writing individual rules to match each keyring. However, for the appliance to know which certificate in the keylist to use you must specify which field attribute value in the certificate to use to determine a policy match. You do this by specifying an Extractor value when you create the keylist. The Extractor value specifies which field attribute value in the certificate to extract to match against the substitution variable value specified in the corresponding policy. 
   1. Select Configuration > SSL > Keyrings > Keylists.
   2. Click Create.
   3. In the Name field, type a name for the new keylist.
   4. In the Extractor field enter a string that identifies which certificate field attribute value to extract to determine a policy match. Enter the string using the $(field.attribute) syntax. For example, to extract the value of the CN attribute from the Subject field of the certificate, you would enter $(subject.CN). Alternatively, select values from the Field, Attribute, and Group Name drop-down lists to build an extractor string, and click Add to extractor. The new extractor string is appended to any existing text in the Extractor field. The extractor supports substitutions from all attributes of Subject, Issuer, SubjectAltName, IssuerAltName, and SerialNumber certificate fields. The default extractor value is $(Subject.CN); many other subject attributes are recognized, among them OU, O, L, ST, C, and DC. Note, however, that the resulting extractor value must be unique for each certificate in the file.
   5. From the Available Keyrings list, select the keyrings to include in this keylist and click Add. If any errors are noted in the Included Keyrings list, the keylist cannot be created. Additionally, if the extractor value of a keyring matches the extractor value of any existing keyring, it will not be added to the keylist. For example, if you select $(Subject.DC) as the extractor and all keyrings have the same value for the DC field in the certificate, the policy would not be able to determine which keyring to select. 
   6. To save the keylist click OK.
   7. Click Apply.
       
4. Create the policy to enable the appliance to present client certificates to the OCS.
   After you have imported the client certificates onto the ProxySG appliance, you must write policy that instructs the appliance how to determine which client certificate to use, and when to use it. 
   1. From the VPM, select Policy > Add SSL Access Layer.
   2. Enter a Layer Name or accept the default name and then click OK.
   3. Set the action:
      1. In the Action column of the first row, right-click and then select Set. The Set Action Object dialog displays. 
      2. Click New and select Set Client Keyring. The Add Client Keyring Object dialog displays.
      3. In the Name field, enter a name for the object or leave as is to accept the default.
      4. Specify where the client certificate is located by selecting Keylist or Keyring.
      5. From the drop-down, select the keylist or keyring that contains the client certificates you want to use to enforce this policy rule.
      6. (Keylists only) In the Selector field, enter the substitution variable that contains the value to use to match against the extractor value you defined when you created the keylist (for convenience, this value shown on the Add Client Keyring Object dialog). For example, if you set the Extractor value in the keylist to $(Subject.CN) and this value is set to match the client's user name in the certificate, you must use the Selector value that will also result in a user name value. In this example, you would enter the Selector of $(user) because this value would also match the client's user name. All substitution variables are supported. For more information on substitution variables, refer "CPL Substitutions" of the Content Policy Language Reference.
      7. If you are using the $(group) selector, you must also create a list of the groups to be included in the $(group) substitution variable. Refer to the “Creating the Group Log Order List” of the Visual Policy Manager Reference.
   4. Click OK.
   5. (optional) Restrict client certificate use to a subset of client requests, based on source or destination request attributes. The default settings in the policy rule will cause the ProxySG to use the specified keylist or keyring for all proxied HTTPS transactions requiring client authentication. You can set the Source and/or Destination columns to restrict the use of the specified client certificates to a specified subset of requests. For example:
      1.  In the Source or Destination column of the row, right-click and then select Set. The Set Source Object or Set Destination Object dialog displays.
      2. Click New and then select an object that represents the subset of requests to which you want to restrict this policy rule. After you select an object, you will be prompted to provide details. For example, if you choose the Client IP Address/Subnet object, you will be prompted for an IP address and subnet mask/prefix to which this rule will apply.
   6. (optional) Add additional policy rules to cover all of the cases in which you want to provide client certificates during SSL proxy sessions. Although a single client keyring action in the SSL Access layer is all you need to enable the appliance to provide client certificates during the SSL handshake with an OCS that requires client authentication, you can add as many rules as necessary to enable the appliance to use a specific certificate or group of certificates based on the specific sites and/or users in the transaction.
   7. Arrange the rules according to how you want the ProxySG appliance to enforce them by selecting the rule you want to move and clicking Move up or Move down. The ProxySG appliance evaluates the rules in the order in which the appear in the policy layer. As soon as it finds a rule that matches the request, it will enforce the specified action (in this case, selecting a client certificate based on the keyring or keylist specified in the action). Therefore you should put more specific rules in front of general rules. For example, if you have a keyring that you want to use for one specific site and you want the appliance to use a keylist to select a certificate for all other sites, you would create the first rule to associates a keyring with the specific site. You would then create a second rule to match any source or destination and associate the action with the keylist that contains the client certificates to use for requests to all other sites.
   8. When you are done defining and arranging the rules, click Install Policy.