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 bySslSession
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()
.
-
-
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 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 a single certificate.abstract boolean
isCriticalInfo(byte chainIndex, short infoType)
Indicates whether a certificate has a critical extension related to an info type.abstract void
verify()
Verifies that each certificate in the chain is valid and that the chain itself is whole and valid.
-
-
-
Method Detail
-
create
public static CertificateChain create(Calendar calendar, byte[] setTimeInfo, short setTimeInfoIndex, CertificateStore certStore) throws CryptoException
Factory method for creating a certificate chain to verify.- Parameters:
calendar
- ACalendar
instance representing the time for this certificate chainsetTimeInfo
- the time info returned from theCalendar.setTime()
methodsetTimeInfoIndex
- the offset in the specified setTimeInfo arraycertStore
- ACertificateStore
instance to associate with this certificate chain- Returns:
- a new
CertificateChain
instance - Throws:
OutOfResourcesException
- in case the maximum allowed number of certificate chains was exceededNotInitializedException
- if the calendar instance was not initialized correctlyIllegalParameterException
- if one or more of the parameters is illegalCryptoException
- if an internal error occurred
-
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
- ifdestroy()
was previously calledCryptoException
- 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 bufferinputIndex
- the start index in the certificate bufferinputLength
- the length of the certificate- Throws:
IllegalUseException
- ifdestroy()
was previously calledIllegalParameterException
- if the certificate format is invalid or there are illegal parametersOutOfResourcesException
- 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 that each certificate in the chain is valid and that the chain itself is whole and valid. Adding the Trusted Root CA certificate to the chain itself is optional and may improve performance. The associatedCertificateStore
instance must contain the chain's Trusted Root CA certificate for the verification to succeed.- Throws:
IllegalUseException
- if one of the following occursdestroy()
was previously called- this certificate chain is empty
OperationFailedException
- the verification of the certificate chain failedCryptoException
- 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 occursdestroy()
was previously called
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 occursCryptoException
-
getMaxCertificateLength
public static short getMaxCertificateLength()
Returns the maximum size in bytes allowed for a single certificate.- Returns:
- the maximum size in bytes allowed for a single certificate
-
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 occursCryptoException
- 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 queriedchainIndex
- 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 occursIllegalParameterException
- if the given info type or the given chain index are invalidNotSupportedException
- if the infoType parameter is not an extensionCryptoException
- 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 bygetChainInfo()
. 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 byCrl.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 occursIllegalParameterException
- when one or more of the parameters is illegal or if the index of the root CA in the chain is specifiedOutOfResourcesException
- if there's already an active CRL instance in use by any SSL session / certificate chainCryptoException
- if an internal error occurred
-
-