Certificate Validation API Components

ESYA Certificate Validation API uses path building and path validation algorithms. Briefly, when a certficate is to be validated, a certificate chain ending at a trusted root certificat is created first and then the chain is tried to be validated.Until a valid chain is found,these steps are repeated for all possible certificate chains.

ESYA Certificate validation API performs validation steps taking place in structural validation and chain validation within the certificate processing step. The details of the certificate processing can be seen in the figure above.

Certificate Processing consists of some groups of validation steps which can be configured by the certificate validation policy file at run-time. The structure of the policy file takes place in certificate validation policy section. The validation steps are designed and organized to be atomic and for each atomic step a (Checker) class is defined. Checker classes , when performing the defined check operation, may need some resources like certificate, crl, or OCSP response which are found by Finder classes. The resources founded by Finders must be matched if they are the correct ones. For this purpose, Matcher classes are defined. The check operations to be performed (Checkers), the locations and methods for resources that are searched for (Finders) and the methods for resource matching (Matchers) are defined by the validation policy file at run-time. Upon validation, the policy file is read and the corresponding objects of Checker, Finder, Matcher classes are created.

Checker classes check the compatibility of the structural characteristics of the certificate and crls and the chain relation to the standards. The details of these classes are out of the scope of the document. Certificate validation policy files determines which checkers are used in validation. The check operations performed by the checkers and defined in RFC 5280 are organized as follows:

Structural Control Operations includes validity checks of the information taking place in the certificate or crl both structurally and contextually. These operations are:

• Serial Numer Control : To check if the certificate serial number is a poisitive integer.
• Certificate Date Control : To check if the validity period of the certificate covers the validation date.
• Version Control : To check if the version information is valid.
• Extension Control: To check if the extensions of the certificate are valid.
• Signature Algorithm Control: To check if the signature algorithm defined in the certificate matches with the the one used in the signature of the certificate.

Chain Relation Validation includes the controls validating the relation between the certificte or crl and the issuer certificate.

• Name Control:To check if the issuer field of the certificate or the crl matches with the subject field of the issuer certificate.
• Signature Control : To verify the signature in the certificate or the crl by using the public key of the iissuer certificate.
• Basic Constraints Control : To check if the issuer certificate has Basic Constraints extension and this extension contains issuer flag as defined in RFC 5280.
• Key Identifier Control : To check if the authority key identifier field extensionin the certificate or the crl matches with the subject key identifier extension in the issuer certificate.
• Path Length Control:To check if the length of the certificate chain does not exceed the value taking place in the issuer certificate
• Key Usage Control: To check if the key usage of the issuer certificate includes certificate signing usage.

These controls are related with the revocation status of the certificate.

• Revocation Control From CRL :To check revocation status of the certificate by using its CRL.
• Revocation Control From OCSP :To check revocation status of the certificate by using its OCSP.

The subject field of the certificate can only take certain values according to the rules included in the name constraints extension in the issuer certicate. These rules are denoted in RFC 5480 in detail. Name controls check if the certificate is compatible with these rules.

The policy information in the certificate can only take certain values according to the rules included in the policy constraints extension in the issuer certicate. These rules are denoted in RFC 5480 in detail. Policy controls check if the certificate is compatible with these rules.

The list of all checkers defined in ESYA Certificate Validation API is shown in Table 1

Checker classes may need some external data when performing their jobs. These data may be a crl info, an OCSP query response, or an issuer certificate. In general, those external data needed during certificate validaton is found and retrieved by finder classes. When a certificate, crl or OCSP Response is searched for, the finders are operated in the order defined by the validation policy until the demanded data is found. Therefore the order of the Finders is very important for performance. For example, if the Local Certificate Store Finder class is placed before the Remote (HTTP, LDAP, etc.)Certificate Finder class in the policy file, then certificate validation does not search for the certificate at remote places if it is found in the local certificate store which can provides significant performance gain.

Finder classes are orgainzed as follows:

These classes find the CA certificates trusted by the Validation API.

Certificate finders are responsible for finding CA certificates. For example, CertificateFinderFromAIA finds the issuer certificate of a certificate by looking at the authority information access (AIA) extension in the certificate. The certificate finder class finding the certificate at a specied http address is another example.

CRL finders are responsible for finding CRL for revocation control. For example CRLFinderFromCDP finds the crl for a certificate, by looking at the crl distribution points (CDP) extension in the certificate. The crl finder class finding the crl at a specied LDAP address is another example.

OCSP Response finders are responsible for finding or retrieving OCSP response for revocation control. For example, OCSPResponseFinderFromAIA , retrieves the OCSP response for a certificate by querying at the OCSP server whose address is taking place in the authority information access (AIA) extension in the certificate. The ocsp response finder class finding the ocsp response in the local certificate store is another example.

The list of all finders defined in ESYA Certificate Validation API is shown in Table 3

The certificates, crls and OCSP responses that Finders have found, must be matched according to certain criteria in order to guarantee that they are the correct ones. Matchers perform these matching operations according to the rules defined in RFC 5280. Matcher classes are organized as follows:

Certificate matchers decides if a certificate and an issuer certificate are related with issuer-subject relation. For example, RFC 5280 states that the issuer filed in the certificate must be the same as the subject field in the issuer certificate. In the Validation API, there is a certificate matcher class , named IssuerSubjectMatcher, that checks this relation between a certificate and an issuer certificate. Issuer certificates are not added to the certificate chain if they are not matched by the certificate matchers defined in the validation policy.

CRL matchers decides if a certificate matches with the crl found by CRL Finders. For example RFC 5280 states that unless indirec crl is being used, the issuer field in the crl must matched with the issuer field in the certificate for which the crl is published. In the Validation API, there is a crl matcher class , named CRLIssuerMatcher, that checks this relation between a certificate and a crl. CRLs are not used in revocation control of a certificate if they are not matched by the crl matcher classes defined in the validation policy.

OCSP Response matchers decides if a certificate matches with the OCSP Response found by OCSP Response Finders. The basic operational logic is very similar to certificate and crl matchers.

Delta CRL matchers decides if a base CRL matches with the delta CRL found by Delta CRL Finders. The basic operational logic is very similar to certificate and crl matchers.

Cross Certificate matchers decides if a CA certificate matches with another CA certificate found by certificate finders. The basic operational logic is very similar to certificate and crl matchers..

Esya Sertifika Doğrulama API'sinde tanımlı ve politika dosyasında kullanılabilecek tüm eşleştiricilerin listesi Table 2 yer almaktadır.

ESYA Certificate Validation API saves the certificates and CRL's found during validation to the local certificate store. Savers are responsible for this operation. The list of savers can be specified by the validation policy file.

The list of all savers defined in ESYA Certificate Validation API is shown in Table 4

Certificate validation is series of sequentially performed control steps. The list of controls steps to be performed, and some other validation parameters can be defined at run-time via an XML-based file, named as certificate validation policy file. In this file, every element named as “class” represents a class in the Certificate Validation API which is a Checker, Finder, Matcher, or Saver class. At the beginning of the validation operation, the policy file is read and policy object is created. The whole validation process is performed according the configuration information defined by this policy object.

A sample validation policy

certval-policy

<!--Dosyayı xml olarak kaydediniz-->
<?xml version="1.0" encoding="UTF-8"?>
<policy>
    <find>
        <trustedcertificate>
            <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.trusted.TrustedCertificateFinderFromECertStore">
                <param name="securitylevel" value="legal,organizational"/>
			</class>	
            <!--class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.trusted.TrustedCertificateFinderFromFileSystem">
                <param name="dizin" value="path\to\trusted certificates"/>
            </class-->
        </trustedcertificate>
        <certificate>
            <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.CertificateFinderFromECertStore"/>
			<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.CertificateFinderFromHTTP"/>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.CertificateFinderFromLDAP"/>
		</certificate>
        <deltacrl/>
    </find>  
    <match>
        <certificate>
            <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.match.certificate.IssuerSubjectMatcher"/>
        </certificate>
        <crl>
            <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.match.crl.CRLIssuerMatcher"/>
        </crl>
        <deltacrl>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.match.deltacrl.BaseCRLNumberMatcher"/>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.match.deltacrl.CRLNumberMatcher"/>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.match.deltacrl.DeltaCRLIssuerMatcher"/>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.match.deltacrl.ScopeMatcher"/>
        </deltacrl>
		<ocsp>
			<class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.match.ocsp.CertIDOCSPResponseMatcher"/>
		</ocsp>
    </match>
	<save>
		<crl>
			<class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.save.CertStoreCRLSaver"/>
		</crl>
        <!--ocsp>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.save.CertStoreOCSPResponseSaver"/>
        </ocsp>
        <certificate>
            <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.save.CertStoreCertificateSaver"/>
        </certificate-->
	</save>
    <validate>
        <certificate>
            <self>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.SignatureAlgConsistencyChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.PositiveSerialNumberChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.CertificateDateChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.CertificateExtensionChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.VersionChecker"/>
				<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.QualifiedCertificateChecker">
					<param name="statementoids" value="(0.4.0.1862.1.1 AND 2.16.792.1.61.0.1.5070.1.1)"/>
				</class>
            </self>
            <trustedcertificate>
            	<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.SelfSignatureChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.self.CertificateDateChecker"/>
            </trustedcertificate>
            <issuer>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.issuer.BasicConstraintCAChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.issuer.PathLenConstraintChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.issuer.KeyIdentifierChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.issuer.CertificateKeyUsageChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.issuer.CertificateNameChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.issuer.CertificateSignatureChecker"/>
            </issuer>
            <revocation>
                <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.revocation.RevocationFromOCSPChecker">
                    <param name ="devam" value="false"/>
                    <find>
                        <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.ocsp.OCSPResponseFinderFromAIA"/>
                        <!--class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.ocsp.OCSPResponseFinderFromECertStore"/-->
                    </find>
                </class>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.certificate.revocation.RevocationFromCRLChecker">
                    <param name ="cevrimdisicalis" value="false"/>
                    <param name ="checkallcrls" value="false"/>
                    <param name ="devam" value="false"/>
                    <find>
			     		<class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl.CRLFinderFromECertStore"/>
						<class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl.CRLFinderFromECertStore">
			     			<param name = "getactivecrl" value="true"/>
			     		</class>
                        <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl.CRLFinderFromHTTP"/>
                        <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl.CRLFinderfromLDAP"/>
                    </find>
                </class>
			</revocation>
        </certificate>
        <crl>
            <crlself>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.crl.self.CRLDateChecker"/>
                <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.check.crl.self.CRLExtensionChecker"/>
            </crlself>
            <crlissuer>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.crl.issuer.CRLSignatureChecker"/>
                <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.crl.issuer.CRLKeyUsageChecker"/>
            </crlissuer>
        </crl>
		<ocsp>
			<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.ocsp.OCSPResponseDateChecker"/>
			<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.ocsp.ResponseStatusChecker"/>
			<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.ocsp.SigningCertificateChecker"/>
			<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.check.ocsp.OCSPSignatureChecker"/>
		</ocsp>
    </validate>
    <parameters>
        <UserPolicySet value="2.5.29.32.0"/>
        <InitialExplicitPolicy value="false"/>
        <InitialAnyPolicyInhibit value="false"/>
        <InitialPolicyMappingInhibit value="false"/>
    </parameters>
</policy>

Policy file specifies the control steps, location and the find method of external resources, and matching criteria for those resources.Furthermore, the trusted certificates that the certificate chains must end at are also defined by certificate validation policy. Therefore it is crucial that the policy file can not be modified in an unauthorized manner. Malicious people can cause verification of signed documents which are created by invalid certificates by changing the certificate validation policy file. For the security of the policy file the measures below can be taken;

• The Policy file is retrieved from a server and stored in the memory. Thus, unauthorized access to the policy file gets more difficult.
• The hash of the policy file stored at the server-side. Upon verification at the client-side, first the hash of the policy file is calculated and matched with the one at the server-side. This prevents unauthorized modification of the policy file. Hash calculation can be performed by DigestUtil class.
• The Policy file is stored as password-based encrypted and decrypted in memory whenever it is used for certificate validation.
• The policy file can is signed and verified whenever it is used for certificate validation.For the verification of the signature of the policy file, the signing certificate must be embedded into the source code of your application. Since it is very hard to change the embedded certificate in the source code, you have to take great care for not losing the private keys corresponding to the certificate used for signing the policy file. You can use PKCS7 signatures (see pkcs7)

We certainly recommend taking one or more precautions listed above for your security.

ESYA Certificate Validation API creates an object of CertificateStatusInfo or CRLStatusInfo classes after the validation of certificate or crl accordingly. In this object, detailed validation information such as invalid certificate chains found during validation can be found. The usage of CertificateStatusInfo and CRLStatusInfo classes with sample codes can be found in CAdES Signature API

Certificate Store is a file-based database and designed as a storage for the certificates of the trusted issuers. It also plays a cache role for the issuer certificates, crls and OCSP Responses in the certificate validation process. Once those resources are retrieved from a remote source then they are stored in the local certificate store and used upon further demand by other validation operations.

The default location of the certificate store, is the ”.sertifikadeposu” folder located in the user's home directory. The default name for the certificate store file is “SertifikaDeposu.svt”. If a different name and location is used for the certificate store then these parameters must be defined in the certificate validation policy file by specifying the parameter named as “storepath”.

ESYA Certificate Validation API trusts the certificates that are defined as trusted rood certificates in the certificate store.

<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.trusted.TrustedCertificateFinderFromECertStore">
<param name="storepath" value="T:\MA3\api-parent\certStore\SertifikaDeposu.svt"/>
</class>

You can have PATH_VALIDATION_FAILURE error during the validation of the test certificates.Most probably the reason is that the issuer of the test certificates is not defined as trusted root in your certificate store. You can make this issuer certificates trusted by te API by using TrustedCertificateFinderFromFile class, which is only recommended for testing purposes.

<class name="("tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.trusted.TrustedCertificateFinderFromFileSystem">
<param name="dizin" value="T:\\MA3\\api-cmssignature\\testdata\\support\\UGRootCerts\\"/>
</class>

In cases, where the usage of file-based certificate store is not available, an XML-based certificate store is created. Thus, you can work with a certificate store that is located on Internet.

In the certificate validation policy file, you can define the trusted certificate finder class finding trusted certificates from an XML certificate store as follows:

<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.trusted.TrustedCertificateFinderFromXml">
<param name="storepath" value="http://www.kamusm.gov.tr/depo/xml/XmlDepo.xml"/>
</class>

A certificate finder from an XML store is also defined as follows:
<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find.certificate.CertificateFinderFromXml">
<param name="storepath" value="http://www.kamusm.gov.tr/depo/xml/XmlDepo.xml"/>
</class>

TrustedCertificateFinderFromXml takes a URL parameter for the location of the XML store.To increase the performance locating the XML store on the local network should be pereferred if possible.

Besides, XML certificate store must only be used with ESYA Certificate Validation API, which performs signature verification on the trusted certificates. Otherwise, you can not be sure that the store is not altered by any man-in-the-middle attack.

One more thing to be mentioned is about the performance degradation caused by using XML store instead of local certificate store. This happens because you can not save the CRL files found at remote location during certificate validation if you are using XML store as XML store is a read-only source. Thus, you must repeatedly retrieve the same crls from remote locations whenever they are needed.