Intel

Developer Zone

CertificateChain

com.intel.crypto

Class CertificateChain

  • java.lang.Object
    • com.intel.crypto.CertificateChain


  • public abstract class CertificateChain
    extends java.lang.Object

    This class represents a Certificate Chain. This class utilizes the CertificateStore as a trust anchor and provides certificate chains verification capabilities which are decoupled from existence of active SSL connections represented by SslSession instances. If a certificate in the chain contains a critical extension that is not on the list of allowed critical extensions, the certificate will be rejected during the verification process. For a list of critical extensions: isCriticalInfo().

    Important: This class only verifies the signature of the certificates and the chain structure. It is the responsibility of the applet to verify each certificate's validity, extensions and any other security constrains it may have.

    • Method Summary

      Methods
      Modifier and Type Method and Description
      abstract void addCertificate(byte[] input, short inputIndex, short inputLength)
      Adds a single self signed X.509 v3 certificate in DER encoded format to the certificate chain.
      static CertificateChain create(Calendar calendar, byte[] setTimeInfo, short setTimeInfoIndex, CertificateStore certStore)
      Factory method for creating a certificate chain to verify.
      abstract SslSession.Crl createCrl(byte chainIndex, int crlLength)
      A factory method that creates a new CRL instance with a preallocated size.
      abstract void destroy()
      Destroys a certificate chain cleaning up its system resources.
      abstract int getCertificateCount()
      Retrieves the number of certificates in the chain (including the Trusted Root CA).
      abstract SslSession.CertificateInfo[] getChainInfo()
      Returns an array of instances that represent the certificate chain which was constructed and verified.
      The array index is zero based and is from leaf to root: 0 index is the leaf, the last certificate is the root.
      The first certificate in the array is the leaf and the last is the root CA which is the trust anchor for this certificate chain.
      abstract int getFailure()
      Returns the detailed error code of the failure that occurred during the certificate chain verification.
      static short getMaxCertificateCount()
      Returns the maximum number of certificates allowed in the chain (including the Trusted Root CA).
      static short getMaxCertificateLength()
      Returns the maximum size in bytes allowed for the entire certificate chain.
      abstract boolean isCriticalInfo(byte chainIndex, short infoType)
      Indicates whether a certificate has a critical extension related to an info type.
      abstract void verify()
      Verifies only the signature of the certificates and the chain structure.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, toString
    • Method Detail

      • destroy

        public abstract void destroy()
                              throws CryptoException
        Destroys a certificate chain cleaning up its system resources. Must be called when the certificate chain is no longer required.
        Throws:
        IllegalUseException - if destroy() was previously called
        CryptoException - if an internal error occurred
      • addCertificate

        public abstract void addCertificate(byte[] input,
                          short inputIndex,
                          short inputLength)
                                     throws CryptoException
        Adds a single self signed X.509 v3 certificate in DER encoded format to the certificate chain. Certificates must be added in leaf to root ordering.
        Parameters:
        input - the certificate buffer, discarding any other data in the buffer
        inputIndex - the start index in the certificate buffer
        inputLength - the length of the certificate
        Throws:
        IllegalUseException - if destroy() was previously called
        IllegalParameterException - if the certificate format is invalid or there are illegal parameters
        OutOfResourcesException - if one of the following occurs:
        • the certificate chain space reached its maximum capacity
        • the number of certificates that were added reached the maximum number of certificates in a chain
          CryptoException - if an internal error occurred
        • verify 

          public abstract void verify()
                               throws CryptoException
          Verifies only the signature of the certificates and the chain structure. Any other checks such as certificate validity, extensions, subject and etc must be done by the applet itself. For example a certificate that contains NULL character in the subject will pass the verification and the applet should verify that the subject doesn't contain NULL characters in order to mitigate a possible null-prefix attack. Adding the Trusted Root CA certificate to the chain itself is optional and may improve performance. The associated CertificateStore instance must contain the chain's Trusted Root CA certificate for the verification to succeed.
          Throws:
          IllegalUseException - if one of the following occurs
          • destroy() was previously called
          • this certificate chain is empty
          OperationFailedException - the verification of the certificate chain failed
          CryptoException - if an internal error occurred
        • getFailure

          public abstract int getFailure()
                                  throws CryptoException
          Returns the detailed error code of the failure occurred during the certificate chain verification.
          Returns:
          the SSL alert protocol error code of the last failure (one of the SslSession.SSL_ALERT_* constants) or SSL_ALERT_NONE if the verification succeeded
          Throws:
          IllegalUseException - if one of the following occurs
          CryptoException
        • getCertificateCount

          public abstract int getCertificateCount()
                                           throws CryptoException
          Retrieves the number of certificates in the chain (including the Trusted Root CA).
          Returns:
          the number of certificates in the chain
          Throws:
          IllegalUseException - if one of the following occurs
          CryptoException
        • getMaxCertificateLength

          public static short getMaxCertificateLength()
          Returns the maximum size in bytes allowed for the entire certificate chain.
          Returns:
          the maximum size in bytes allowed for the entire certificate chain
        • getMaxCertificateCount

          public static short getMaxCertificateCount()
          Returns the maximum number of certificates allowed in the chain (including the Trusted Root CA).
          Returns:
          the maximal number of certificates in the chain
        • getChainInfo

          public abstract SslSession.CertificateInfo[] getChainInfo()
                                                             throws CryptoException
          Returns an array of instances that represent the certificate chain which was constructed and verified.
          The array index is zero based and is from leaf to root: 0 index is the leaf, the last certificate is the root.
          The first certificate in the array is the leaf and the last is the root CA which is the trust anchor for this certificate chain.
          Returns:
          an array of the certificate info available in the certificate chain
          Throws:
          IllegalUseException - if one of the following occurs
          CryptoException - if an internal error occurred
        • isCriticalInfo

          public abstract boolean isCriticalInfo(byte chainIndex,
                               short infoType)
          Indicates whether a certificate has a critical extension related to an info type. The list of extensions that are allowed to be critical is:
          • Basic Constraints
          • Name Constraints
          • Key Usage
          • CRL Distribution Point
          • Subject Alternative Name
          • Extended Key Usage
          • Application Policies

          The list of extensions that applet can query for criticality is:
          • INFO_TYPE_KEY_USAGE
          • INFO_TYPE_CRL_DIST_POINT
          • INFO_TYPE_SUBJECT_ALTERNATIVE_NAME
          • INFO_TYPE_EXTENDED_KEY_USAGE
          • INFO_TYPE_APPLICATION_POLICIES

          For all of the other given info types, which are not extensions, NotSupportedException will be thrown.
          Parameters:
          infoType - the info type to be queried
          chainIndex - the location of the certificate in the certificate chain
          Returns:
          true if the requested certificate has a critical extension related to the requested info type, false if the the info type is extension but not a critical one. If the info type doesn't exist in the certificate, then false will be returned as well.
          Throws:
          IllegalUseException - if one of the following occurs
          IllegalParameterException - if the given info type or the given chain index are invalid
          NotSupportedException - if the infoType parameter is not an extension
          CryptoException - if an internal error occurred
        • createCrl

          public abstract SslSession.Crl createCrl(byte chainIndex,
                                 int crlLength)
                                            throws CryptoException
          A factory method that creates a new CRL instance with a preallocated size. The system resources required for a CRL are significant therefore
          only a single active CRL instance can exist in all SSL session / certificate chains across all applets.
          Crl.destroy() must be called when the CRL instance is no longer needed.
          Parameters:
          chainIndex - the location of the certificate in the certificate chain for which the CRL is created. Refers to the certificate containing the CRL distribution point
          retrieved by getChainInfo(). Can't be the index of the root CA in the chain - the last element in the array.
          crlLength - the size preallocated for the CRL, can't exceed the value returned by Crl.getMaxCrlLength(). Size must match the exact size of the CRL.
          Returns:
          a new CRL instance for the specified certificate
          Throws:
          IllegalUseException - if one of the following occurs
          IllegalParameterException - when one or more of the parameters is illegal or if the index of the root CA in the chain is specified
          OutOfResourcesException - if there's already an active CRL instance in use by any SSL session / certificate chain
          CryptoException - if an internal error occurred