PreviousNextUp[Front page] [Index]

Policy Modules

Each chain consists of one or more policy modules added by the operator. Each module is a function that receives the certification request and some additional data, can make changes to the certificate template and can either accept the request, deny it or pass it to the next module in the chain. If the request 'drops off' at the end of the chain (the last module passes it on), the request is assumed to be denied. A request is only accepted if one of the modules in the chain explicitly accepts it.

A new module is added by selecting it from the chain's pop-up menu marked as -- Add New Policy Module -- and then by clicking one of the numerous Refresh buttons. The page is then updated and the new module is added in the end of its chain. As the modules are run in order, the module's position in the chain is important. The module can be moved within its chain by clicking the Up and Down arrows located on the module's box. The Module can be removed by clicking the adjacent Remove button.

Other items in the module boxes are the module's position in the chain (located on the left), the module's name (on the top row) and either a short description or the module specific parameter configuration (located on the bottom row).

The following modules are available:

  • Accept All

    Accepts all operations. Usually set as the only module in the chain or as the last module after one or more modules that just modify the request.

  • Active Certificate Limit

    Limits the number of active certificates per entity. The request is passed through if the number of active certificates in the corresponding entity is less than the given limit. Requests without an entity are also passed through. Otherwise the request is rejected.

  • Add CA Issuers

    Adds an Authority Info Access extension with the caIssuers method. The extension contains the location of the issuing CA certificate. Client software can use this information to fetch sub-CAs for unknown certificates. Location field must contain either an URL or a directory name. Additional modules can be used to add multiple locations.

  • Add Custom Binary Extension

    Adds a custom extension into the certificate template. The options available in the drop-down box are intended only as examples.

    To create your own custom extensions, edit the add-custom-extension.scm file in the lib/modules/ directory.

  • Add Policy Info Extension

    Adds a policy info extension into the certificate template. The Policy OID field must either contain a valid OID or it must be left empty, in which case no policy info extension is added. If the Overwrite flag is set all existing policy info extensions are first removed.

    This module can add four different types of policy info extensions. The most simple case is No qualifier where only the OID is added to the extension and the content field is ignored.

    Extensions with the CPS URI type must have an URI in contents field. This URI is supposed to point a document containing the Certification Practice Statement that further explains the intended use of certificates that contain this policy extension.

    User notice can either contain a text field or an organization name together with a list of reference numbers. They are given in the content field separated with commas, the organization name first. For example SSH, 1, 2, 3

  • Add Qualified Certificate Statement

    Adds a Qualified Certificate (QC) statement into the certificate template.

    The module can add five different types of QC statements. These are QCSyntax v1, QCSyntax v1 with semantics oid, QC EU Compliance, Monetary limit, and Retention period (years). See Section Certificate Extension Fields for more information.

    QCSyntax v1 and QC EU Compliance require no value to be given. For QCSyntax v1 with semantics oid an OID value, for Monetary limit a sum followed by a space and three-letter currency code, and for Retention period a time period in years must be given in the text box.

  • Apply Policy Attributes

    Applies policy module attributes defined in the associated entity or a pre-shared key of the entity. If this module is not in the receive-request chain, the policy attributes in the entity or the pre-shared key have no effect. See Section Policy Attributes.

  • Apply Profile

    Applies a certificate profile to the certification request. Certificate profiles can perform checks on request validity, change some attributes in the request and remove some attributes entirely. See Section Certificate Profile.

    Note that this policy module will remove all extensions that are not part of the profile from the certificate template.

  • Apply Request Profile

    If the request has an associated certificate profile (by operator action, for example), it is applied by this module. If there is no profile defined in the request, a default profile given in the parameter is applied instead. One possible parameter value is -- no profile -- which means that no profile is applied if the request does not have one.

    Note that this policy module will remove all extensions that are not part of the profile from the certificate template.

  • Check Key Usage

    Checks key usage bits in the request. Key usege bits selected in the Check list are required in the request and all others must be left unset. However, bits selected in the Ignore list are not checked. The module returns accept if the request contains the valid key usage extension and deny otherwise. The module can be used as a test clause in a conditional module.

  • Conditional

    A conditional policy consists of IF-THEN clauses that can contain other policy modules.

    Each clause contains one IF module and one or more THEN modules. The THEN module chain is executed only when the corresponding IF module returns accept. In that case the return value of the THEN chain is the result of the whole conditional module. The THEN chain defaults to continue.

    If the IF module returns continue or deny, the execution moves to the next clause (ELSE IF), if any. If none of the clauses match, the conditional module returns with continue.

  • Drop Extensions

    The selected extensions are removed from the certificate template.

  • Drop Unbound Entities

    This module drops all requests which do not have a valid entity mapped to them or those with an entity that has not been bound to a specific CA. By using this module, it can be ensured that only the requests mapped through an entity to this CA are allowed to proceed.

  • Issue Automatic

    Depending on the parameter value, this module will either accept and automatically issue all requests or just those specific requests with a mapped entity. The primary way to automatically map an entity to an incoming request in the receive-request chain is to use pre-shared secrets. Therefore it may be reasonable to automatically approve such requests. If request is not approved by this policy module, it is passed through to the next module in the chain, so a chain should not be ended with this module. In addition to accepting any requests with some entity mapping, more specific separation can be done based on entity type (server, operator, or RA entity). This module can also be used to automatically accept request approved by one of the delegated RA entities.

  • Issue Manual

    Accepts all requests. Used in the receive-request chain to emphasize that the request must be manually approved.

  • Key Size Filter

    This module drops all requests with insufficient key length. The length limit is given in bits separately for both RSA and DSA keys.

  • Match Subject Name

    Matches the given distinguished name pattern with the request's subject name. The pattern can contain regular expressions (based on the egrep syntax) and literal fields.

    If the Prefix only check box is selected, the subject name can have additional fields after the given pattern. For example, the pattern C=.., O=.*Elephant.* is matched by the subject name C=AS, O=Software-Elephant Inc., S=Gartler + G=Geirmund if prefix only is set, otherwise the S and G fields in the end do not match. Note that for convenience the expression must match the whole component content, meaning that even if normally pattern SSH, as defined by regular expression syntax, does match strings aSSHb, it will not match in this case. If substring matching is wanted, pattern can start and end with .* which will match any character zero or more times.

    Note also that the pattern must be a valid distinguished name, with regular expressions contained as component values. This means that OIDs cannot be selected with expressions and neither can one expression match several components at one time. Regular expressions also use many unusual characters that must be escaped when inside distinguished name. For example, + is commonly used regular expression syntax and must be escaped by double backslashes (\\). See Appendix Egrep Syntax.

    This function accepts all matching requests and passes others to the following module. This allows the user to stack several matchers in the same chain and to terminate in the end with reject.

  • Multi Approve

    Requires that N operators have accepted the request before it is issued.

    Note, however, that an operator with super-user access can approve the request alone (as a super-user operator can also edit the policy chain).

  • Reject All

    Rejects everything. This is a redundant module, as an empty or unterminated chain produces the same results. The module can be used to emphasize that all operations are rejected.

  • Remove Basic Constraints

    Removes the basic constraints extension from certificate template. This is a way to guarantee that no request for CA certificates will pass through.

  • Set Absolute Validity Period

    Sets a validity period with absolute start and end times.

  • Set CRL Distribution Point

    Adds the CRL distribution point and/or OCSP Authority Info Access extensions to the certificate template. The appropriate CRL publishing method must have the Include in Certificates option enabled.

  • Set Certificate Template

    Adds a non-critical certificate template extension (1.3.6.1.4.1.311.20.2) into the certificate.

  • Set Extended Key Usage

    Sets or clears extended key usage OIDs in the request. The first list is used to select mode (set, clear, or add). Set sets all selected OIDs from the OID list below and clears all unselected OIDs. Clear only removes the selected OIDs from the request but all other OIDs are left if they are already set. Add adds the selected OIDs to the request but does not clear others. If the Clear unknown OIDs? checkbox is selected, all OIDs not in the list are cleared. Note that deselecting this option allows arbitrary extended key usage OIDs to pass through this module.

  • Set Extension Criticality

    Resets extension criticality. If the extension is present, its criticality is set as in the corresponding setting in this module. Setting value no change means that the extension is left unchanged, critical marks the extension as critical, and non-critical as non-critical.

  • Set GUID

    Adds a GUID subject alternative name extension (1.3.6.1.4.1.311.25.1) into the certificate. The extension value is expected to be a hex byte string, with bytes separated with ':'. Example: '34:5a:ff:01:12'

  • Set Key Usage

    Sets or clears key usage bits in the request. The first list is used to select mode (set all, clear, or set selected). Set all bits sets all key usage bits. Clear selected bits removes the selected bits from the request but all other bits are left if they are already set. Set only selected bits sets the selected bits to the request but does not clear others.

  • Set Meta Info : CRL Sticky

    Sets the meta info switch in the request that defines whether the certificate is removed from the CRL after its expiration. By default, the switch is not set (and the certificate is removed from CRL after expiration). See Section Additional Parameters.

  • Set Meta Info : Publish

    Sets the meta info switch in the request that defines whether the certificate is published or not. By default, the switch is set (and the certificate is published). See Section Additional Parameters.

  • Set Request Field From Entity

    Copies either the Subject name, Email address, IP address, DNS name, user Principal name, or URI from the entity associated with the request to the certificate template. If the Overwrite flag is not set, the existing attributes in the request are preserved and the new value is added to them. This only works with attributes that are multi-valued. For example, subject name is always overwritten. If the Required flag is set, an error is returned if the entity does not have that attribute (or if there is no entity bound to request). Otherwise the request is left as it is and the policy module is skipped.

  • Set Signature Algorithm

    Sets the signature algorithm (MD5 or SHA-1) the CA uses to sign the certificate.

  • Set Subject Name

    Constructs a new subject name using a format field similar to the format used in LDAP object name configuration. The format can get subject name components from an existing subject name, entity attributes, and the CA certificate.

  • Set Validity Period

    Sets the validity period in the certificate template. If the Overwrite flag is set, an already existing validity period (set in original request or by some other policy code) is overwritten with the new one. Otherwise the validity period is calculated only if the request does not have one.

    To avoid problems with clocks that are slightly off, the start of the validity period (Not before) is set 30 minutes in the past.

    This module is usually set to the receive-request and/or view-request chains so that automatically issued certificates have update validity periods and the operator sees the current validity period when viewing the requests. Setting this module to update-request or accept-request chains prevents operators from modifying the validity periods.

  • Unique Subject Name

    Validates the uniqueness of the subject name. If the scope is set to Name per entity, multiple certificates with the same name are allowed but only if they all belong to the same entity. If the scope is Name per certificate, only one active certificate is allowed per name. Note that this check is only based on active certificates: even if an entity has a matching subject name attribute, this policy still allows certificates of that name to be issued to other entities. Also, a new certificate with the same name can be issued after the existing certificate has expired or has been revoked. Furthermore, the Name per entity scope only checks the first certificate. If the policy has earlier allowed certificates with same subject names, this module can (depending on their order) accept a request even if another entity has a certificate with matching name.

If the chains become too long, editing a chain is made easier if the other chains are hidden away by clicking the Hide button. The only function of the button is to hide the contents of the chain. It does not affect the functionality of the policy chains in any way.

Changes made to the policy chains can be updated to the Database by clicking the Commit Changes button. Click the Cancel button to return to the main CA view without changing anything.


PreviousNextUp[Front page] [Index]