Key Usage Enforcement Policy

A Key Usage Enforcement policy is XML code that dictates how an X.509 Certificate may be used by the gateway. This policy is in effect by default, but is ignored if key usage is overridden to provide more lenient usage.
gateway83
A Key Usage Enforcement policy is XML code that dictates how an X.509 Certificate may be used by the
Layer7 API Gateway
. This policy is in effect by default, but is ignored if key usage is overridden to provide more lenient usage.
The default enforcement policy delivered with the Gateway should be adequate for most scenarios, but you can override it with a customized version if you have specific enforcement needs.
Creating a Key Usage Enforcement policy is intended for advanced technical users.
Contents:
To use a customized key usage enforcement policy:
  1. Access the
    Manage Cluster-Wide Properties
    task.
  2. Add the new key usage enforcement policy to the
    pkix.keyUsagePolicy
    cluster property. A sample template is given below to help you get started.
  3. Restart the Gateway.
Recognized Action Names
The following key usage activity names are recognized by the Gateway:
Action
Description
Notes
verifyXml
Verifies signed XML using public key
 
encryptXml
Encrypts XML with public key, for private key
 
sslServerRemote
Allows handshake with remote server certificate
The client performs this check during an outgoing SSL connection.
sslClientRemote
Allows handshake with remote client certificate
The server performs this check during an incoming SSL connection.
verifyClientCert
Verifies certificates signed by this certificate
Check performed during certificate chain verification.
verifyCrl
Verifies the Certificate Revocation List signed by this certificate
Check performed by Gateway's CertValidationProcessor during authentication and during outbound SSL.
decryptXml
Decrypts XML with public key that was encrypted using the private key
This action is highly unusual. The Gateway never attempts to do this in normal use.
signXml
Signs XML using public key
This action is highly unusual. The Gateway never attempts to do this in normal use.
Sample Enforcement Policy Template
Use the following sample template to help you get started. Refer to the embedded comments for more details.
<keyusagepolicy xmlns="http://www.layer7tech.com/ws/keyusage"> <!-- A permit rule without an action applies to every action --> <permit><req>anyExtendedKeyUsage</req></permit><!-- A permit rule without requirements always succeeds --> <permit action="signXml"/> <permit action="decryptXml"/> <!-- Multiple permit rules may be specified for an activity.At least one permit rule must succeed. --> <permit action="verifyXml"><req>digitalSignature</req></permit> <permit action="verifyXml"><req>nonRepudiation</req></permit> <!-- Multiple requirements may be specified for a permit rule. All requirements must match for that permit rule to succeed. --> <permit action="sslClientRemote"><req>digitalSignature</req><req>keyEncipherment</req></permit> <permit action="sslClientRemote"><req>nonRepudiation</req><req>keyEncipherment</req></permit> <!-- An ext. key usage requirement may use a dotted-decimal OID. --> <permit action="sslClientRemote"><req>1.3.6.1.5.5.7.3.2</req></permit> <permit action="encryptXml"><req>keyEncipherment</req></permit> <permit action="sslServerRemote"><req>keyEncipherment</req></permit> <permit action="sslServerRemote"><req>keyAgreement</req></permit> <permit action="sslServerRemote"><req>id-kp-serverAuth</req></permit> <permit action="verifyClientCert"><req>keyCertSign</req></permit> <permit action="verifyCrl"><req>cRLSign</req></permit> </keyusagepolicy>
To create an "Or" logic permission within an action, use this syntax:
<!-- key_usage_value_1 or key_usage_value_2 is required for permission of action_value --> <permit action="action_value"><req>key_usage_value_1></req></permit> <permit action="action_value"><req>key_usage_value_2></req></permit>
To create an "And" logic permission within an action, use this syntax:
<!-- both key_usage_value_1 and key_usage_value_2 are required for permission of action_value --> <permit action="action_value"><req>key_usage_value_1></req><req>key_usage_value_2></req></permit>
Notes from sample template:
  • The enforcer may do zero, one, or two passes through the policy depending on what critical extensions are present:
    • If there is neither a critical KeyUsage nor a critical ExtKeyUsage in the certificate, the enforcer always permits the activity.
    • If there is a critical KeyUsage, the enforcer will scan the policy from top to bottom for a matching KeyUsage permit rule. If it reaches the end of the policy without finding one, the policy is denied. A permit rule pertains to the KeyUsage if it is a blanket permit, or if it contains a requirements for one of the standard KeyUsage bit names:
cRLSign
dataEncipherment
decipherOnly
digitalSignature
encipherOnly
keyAgreement
keyCertSign
keyEncipherment
nonRepudiation
    • If there is a critical ExtKeyUsage, the enforcer will scan the policy from top to bottom for a matching ExtKeyUsage permit rules. If it reaches the end of the policy without finding one, the activity is denied. A permit rule pertains to the ExtKeyUsage if it is a blanket permit, or if it contains a requirement for a dotted-decimal OID string, or a requirement for one of the recognized ExtKeyUsage names:
any
anyExtendedKeyUsage
id-kp-clientAuth
id-kp-codeSigning
id-kp-emailProtection
id-kp-ipsecEndSystem
id-kp-ipsecTunnel
id-kp-ipsecUser
id-kp-OCSPSigning
id-kp-serverAuth
id-kp-smartcardlogon
id-kp-timeStamping
id-pkix-ocsp-nocheck
  • A permit rule for an activity that contains no requirements is a blanket permit for that activity.
  • A KeyUsage matches a permit rule if every requirement in the permit rule has the corresponding bit set in the KeyUsage.
  • An ExtKeyUsage matches a permit rule if every requirement in the permit rule has the corresponding OID present in the ExtKeyUsage.
  • A single permit rule that mixes KeyUsage and ExtKeyUsage requirements inside the same <permit> element can never be matched, since no possible KeyUsage or ExtKeyUsage will be capable of matching all its requirements. A rule such as this is likely an error.