API Reference | developer.brewmp.com API Reference | developer.brewmp.com


API Reference


Brew Release
Brew MP 1.0.2
See Also
CALLBACK_Cancel IRSA IX509Chain IX509CHAIN_AddOpt IX509Chain_GetFieldPart IX509CHAIN_RemoveOpt IX509CHAIN_VerifyV X509TrustResult X509TrustOverride
Complete and verify the certificate chain
instance of X509Chain
place to put trust result.
called back when verification is complete. ... options
  • IX509CHAIN
  •     void IX509Chain_Verify
          IX509Chain *pMe, 
          509TrustResult *pTrustResult,
          AEECallback *pVerifyCB, 
  • None
Side Effect
  • Causes the cert chain to be formed so that certs, cert fields, and cert field parts can be fetched in the cert chain order using WEBOPT_X509_CHAIN_CERT.
IX509CHAIN_Verify does the heavy crypto to actually verify the signatures on the certs up to a root in the set of roots. Dependending on key length, key modulus, processor speed, and cert chain length, the time for this operation can vary. For most cert chains it should be a couple of seconds. First IX509CHAIN_Verify builds the cert chain. It does this by finding the leaf cert and searching for certs that have a subject matching its issuer. The search is conducted over the options tree, first through the options passed into the Verify operation on the command line, second through the options stored by the instance itself, and on to any default options sets. The search is always first for root certs, then branch certs. Certs added sooner in the options tree are matched first. When forming the certificate chain, there are comparisons of isuer and subject. The comparison of issuer distinguished name (DN) to subject DN complies with RFC 2459/3280 section 6.1, and X.509 section 9. IX509CHAIN_Verify ignores leading and trailing spaces and case for attribute values (AVs) that are of type PrintableString, and does a binary compare for all other AVs. It is sensitive to the structure/order of the relative distinguished names (RDNs) that make up the DN, but not to the order of the AVs within a DN. So the following are equal:
  • 1) (O=fish-tacos, OU=fish, OU=halibut), (CO=mexico,ST=baja)
  • 2) (OU=halibut,O=fish-tacos, OU=fish) (ST=baja,CO=mexico)
but these are not equal to each other or those above:
  • 3) (CO=mexico), (ST=baja), (OU=halibut), (O=fish-tacos, OU=fish)
  • 4) (O=fish-tacos, OU=fish), (OU=halibut), (CO=mexico), (ST=baja)
Once the chain is formed, any certs that are part of the chain, but not stored in the instance of IX509Chain, will be copied. This is so the chain is retained after the verify operation is completed, so that it can be displayed and such. Next the chain is verified. This includes many checks such as validity dates, policy constraints imposed by extensions, the host name on the leaf certificate, and the signatures. The verification does not stop on the first error. It continues over the whole computed cert chain. The rest of this section describes these checks. The errors are accumulated in the bitmaps in the response structure. All these errors are "soft" trust errors that can be overriden. The hard errors are primarily out of memory or lack of a good leaf cert. The individual checks can be turned off or overriden on a per-certificate basis or for the whole chain verification with TrustOverride records. The host name, TrustOverride records, and other options are stored in WebOpts that can either be stored in the instance itself, or be passed on the command line. Note that by passing an instance of IWebOpts as a new default, a whole tree of options can be passed in on the command line. When the verify completes, the callback is called. You may cancel the verify operation by calling CALLBACK_Cancel() on the callback record passed to the verify operation. Note that releasing the IX509Chain object does not cancel the callback. The object will persist and the callback will complete. Thus the callback should be canceled before releasing the IX509Chain object (unless you want the callback to be called after the release). Note also that two verify operations on the same IX509Chain object may be started in parallel, though the usefulness of that seems questionable, and that functionality may be removed in the future. The results are copied into the pTrustResult structure. Make sure to check both nResult and uErrorSummary to get the complete results of the verify operation. Once Verify is called you can fetch the certs in chain order using the WEBOPT_X509_CHAIN_CERT option type. The ordering is generally valid until you call IX509CHAIN_RemoveOpt(), after which it is not guaranteed until you call IX509CHAIN_Verify() again. Note that if you reuse this object for verifying multiple chains by adding and deleting the leaf and branch certs, and you are passing the roots in as an option parameter, the number of copied roots will grow. The host name checking is performed as follows. It is expected that a hostname to match against is supplied in the WEBOPT_X509_HOST option. In a typical browser SSL implementation this is the hostname from the URL. If one is not supplied, an error will be set. Hostname checking is mainly for use with SSL. If you do not want the hostname checked, then set X509CHAIN_NO_TARGET_HOST as a TrustOverride. The comparrison is to the common name part of the subject distinguished name in the leaf certificate. Regular expressions in the CN (common name) are catered for as per the following rules: * matches anything. ? matches one character. \ will escape a special character. $ matches the end of the string. [abc] matches one occurrence of a, b, or c. The only character that needs to be escaped in this is ]; no others are special. [a-z] matches any character between a and z [^az] matches any character except a or z ~ followed by another expression will remove any pattern matching the shell expression from the match list. (foo|bar) will match either the substring foo, or the substring bar. These can be expressions as well. The basic constraints extension is processed as follows. It is ignored on the leaf certificate and on all v1 certificates. On the intermediate and root certificates its presence is required, and the value of the cA boolean must be true. If not, the error X509CHAIN_BASIC_CONST will be given. Also, the pathLen is imposed. If the path is too long, X509CHAIN_LONG_CHAIN is given. The criticality of the basic constraints has no affect on the processing. To turn off all basic constraints processing, set X509CHAIN_BASIC_CONST as an override. BREW 2.x processes basic constraints that are slightly different from BREW 3.0 and higher. It ignores basic constraints on root certificates completely. BREW 3.0 instead does not flag errors on v1 certificates, no matter where they appear in the chain. One result is that a root certificate with cA=FALSE will cause an error in BREW 3.0, but not in BREW 2.x. Another result is that a v1 intermediate certificate will cause an error in BREW 2.x, but not BREW 3.0. The X509v3 Key Use extension is processed as follows. If the extension is not marked as critical, it is completely ignored. If it occurs in a branch or root (not the leaf) and is critical, then it must contain ASNOID_KEYUSE_CERTSIGN or the trust error X509CHAIN_KEY_USE will be given. If it occurs in a leaf cert, then there must be matching values in the extension for every usage bit set in the option WEBOPT_X509_KEY_USE; otherwise the trust error X509CHAIN_KEY_USE will be set. Extended key use processing is turned on if any WebOpts with ID WEBOPT_X509_EXT_KEY_USE are set. If set, then certificates in the chain with extendedKeyUse extensions are processed against it. No processing is done for certificates that don't have an extendedKeyUse, because the implication is that there is no restriction on their usage. By default, only the leaf cert is processed. To have the extension processed in other than the leaf, set the trust override bit X509CHAIN_NON_LEAF_EXT_KEY_USE. It is not recommeded that this be set for SSL. In processing, the extendedKeyUse section of each cert must include the OIDs for all of the usages given in the WEBOPT_X509_EXT_KEY_USE WebOpts. If one is missing, an error is returned. Certs without extendedKeyUse never generate an error. The error returned will be X509CHAIN_EXT_KEY_USE if the extension is not critical, and X509CHAIN_CRIT_EXT_KEY_USE if the extension is critical. To avoid processing entirely, do not set any WebOpts with ID WEBOPT_X509_EXT_KEY_USE. To process them only if they are critical, set the WebOpts and the trust override X509CHAIN_EXT_KEY_USE. Setting X509CHAIN_CRIT_EXT_KEY_USE as a trust override is the same as not setting any WebOpts with ID WEBOPT_X509_EXT_KEY_USE. In Brew 2.0 up to Brew 3.0.1, the X509v3 Extended Key Use extension was processed as follows. It is processed whether or not it is marked critical. If it occured in a root or branch cert (not the leaf) and it is critical, the X509CHAIN_EXT_KEY_USE error is set. If it occurs in the leaf cert, then there must be a matching usage value in the extension for every usage value given in WEBOPT_X509_EXT_KEY_USE; otherwise the X509CHAIN_CRIT EXT_KEY_USE will be set. If it is marked critical on a leaf cert, the X509CHAIN_CRIT_EXT_KEY_USE error will be set. To override all processing, set X509CHAIN_CRIT_EXT_KEY_USE. To override it only if it's not critical, set X509CHAIN_EXT_KEY_USE. There are many more types of extensions in certificates. They are all ignored. Use the IX509Chain_GetFieldPart() function to get and process them. If an extenion is marked critical and not understood, then the X509CHAIN_CRITICAL_EXTENSION will be set. The following summarizes the WebOpt IDs that affect chain verification. Also see the WebOpt IDs under IX509CHAIN_AddOpt() for the certificate types.
  • WEBOPT_X509_HOST Set the hostname to compare with the hostname
  • in the common name in the leaf cert in the
  • chain. It must be a NULL-terminated string,
  • though the host part that is actually compared
  • stops at the first ":", "/" or "," character.
  • If this is unset, a pedantic but overridable
  • trust error will be set.
  • WEBOPT_X509_OVERRIDE You can have serveral of these to override
  • serveral trust errors. See above discussion
  • of X509TrustOverride for details.
  • WEBOPT_X509_MAX_CHAIN Maximum length that will be chained. The function
  • won't chain past X509CHAIN_MAX_CHAIN no matter how
  • large this value is. This is NOT the maximum number
  • of certs that can be held in IX509Chain. That
  • is limited only by memory.
  • WEBOPT_X509_EXT_KEY_USE A set of ASN1OIDs (see AEEASN1OIDs.h) that
  • indicated the intended purpose of the cert
  • chain. There may be several values for this
  • option, with one purpose given as a 32 bit
  • integer in pVal per option. If unset, no
  • checking of the extended key usage extension
  • in the cert will be performed. An example
  • server authentication).
  • WEBOPT_X509_KEY_USE A single bitmap giving the intended use of
  • the cert should be place in pVal of this opt.
  • The bit values should be one of ASNOID_KEYUSE_*.
  • This option allows the client to specify the
  • RSA implementation to be used. For example,
  • some platforms may allow support for hardware-based
  • modular exponentation, and the client
  • may use this option to take advantage of this
  • capability in order to improve performance.
  • WEBOPT_X509_INTEGER_ID This may be used to check that an integer value or
  • set of integer values falls within the range
  • specified in the set-of-integers extension. This is
  • a BREW-specific extension.