NAME

OpenXPKI::Server::Workflow::Activity::Tools::EvaluateSignerTrust

SYNOPSIS

    class: OpenXPKI::Server::Workflow::Activity::Tools::EvaluateSignerTrust
    param:
      _map_rules: scep.[% context.server %].authorized_signer_on_behalf

DESCRIPTION

Evaluate if the signer certificate can be trusted. Populates the result into several context items, all values are boolean. Checks are by default done based on the contents of the certificate database and work only for certificates which are found there. If you want to validate certificates from an external CA you must import the full issuer chain and either set the allow_external_signer flag or import the used signer certificates themselves.

signer_trusted: true if the complete chain is available and certificate status is not revoked. Does NOT check for expiration.
signer_authorized: true if the signer matches one of the given rules. This does NOT depend on the trust status of the certificate, so you need to check both flags or delegate the chain validation to another component (e.g. tls config of webserver). Will be undef in case the certificate chain could not be validated at all or no trust rules have been found.
signer_validity_ok: true if the current date is within the notbefore/notafter window
signer_revoked: true if the certificate is marked revoked.
signer_chain_ok: only available with external signers, true if the certificate chain was successfully build, false otherwise.
signer_cert_identifier: the identifier of the signer certificate
signer_subject: the subject of the signer certificate, only exported if export_subject parameter is set
signer_subject_key_identifier, signer_public_key_hash: the signer_key_identifier / public_key_hash of the signer certificate, see export_key_identifier parameter for details.
signer_in_current_realm: Boolean, weather the signer is an entity in the current realm

Configuration

The check for authorization uses a list of rules. Those can be either given explicitly to the rules parameter or as a pointer to the realm config. A common pattern used in OpenXPKI is to build the path for the rules from the server properties, e.g. the SCEP workflow uses scep.[% context.server ].authorized_signer..

If rules is a scalar, it is considered to be a config path, if it is a hash it is taken as explicitly defined ruleset.

The ruleset structure is a hash of hashes, were each entry is a combination of one or more matching rules. The name of the rule is just used for logging purpose:

  rule1:
    subject: CN=scep-signer.*,dc=OpenXPKI,dc=org
    identifier: AhElV5GzgFhKalmF_yQq-b1TnWg
    profile: client_scep
    realm: democa

Rules

The rules in one entry are ANDed together, values are full string match, except the subject rule. If you want to provide alternatives, add multiple list items.

subject: Evaluated as a regexp against the signers full subject, therefore any characters with a special meaning in perl regexp need to be escaped!
profile: Matches the name of the internal OpenXPKI profile assigned to this certificate. This implies that the certificate was issued by us.
realm: The name of the realm where the certificate originates from, works also for certificates imported into a realm. If not set, the default is the current realm. Pass the special value _any to ignore the realm during rule evaluation.
Special rules apply when matching on "identifier" or "issuer_alias".
identifier: The identifier of the certificate. This works also with external issued or self signed certificates. realm is only matched if set explicit, so realm: _any is the default.
issuer_alias: The name of an alias group as registered in the aliases table. Matches if the certificate issuer has an active alias in the given group. The alias item is searched in the given realm and the global realm, setting realm: _any is ignored (search is done in the global realm only).
Note: The query is done at once for the given and global realm, this might cause unexepcted behaviour when the same alias exists in both with different validity dates (there will be a positive match if either the local or the global realm lists the item as valid).
root_alias: Same as issuer_alias but queries for the root certificate
meta_*: Load the metadata attributes assigned to the certificate and match against the given value.

Parameters

rules

Usually a scalar value, taken as config path to read the rules from. Can also be a hash that represents an explicit ruleset (see Rules).

export_subject

Boolean, if set the signer_subject is exported to the context.

export_key_identifier

Export information about the signers subject_key_identifier. As there is an ambiguity on this term, you can switch the behaviour.

The default behaviour on any true value is to write the key identifier read from the certificate to signer_subject_key_identifier. If you pass hash, you get the value of the SHA1 hash of the public key as defined in RFC5280 in this field. If you pass both, the SHA1 has will be written as an additional field to signer_public_key_hash.

Note: If a certificate does not contain an explicit subject key identifier, this always falls back to the SHA1 hash.

allow_external_signer

Boolean, if set and the signer is not found in the local database the activity tries to verify the certificate chain using the validate_certificate API method.

allow_untrusted_signer

Boolean, if true, the rulesets are processed even if the certificate chain could not be built or validated. This is only useful with external signers.

crl_check

Only used when the certificate is an external signer. Valid values are leaf or all, tries to use CRLs when validating the certificate for either the lead certificate or the full chain. The required CRLs must exist in the CRL table.

allow_surrogate_certificate

Boolean, if set and the signer is not found in the local database and is self-signed the database is searched for an entity certificate with the same subject key id. This is used e.g. in the PoP renewal via EST/RPC.