org.conscrypt

Class TrustedCertificateStore

java.lang.Object

org.conscrypt.TrustedCertificateStore

public final class TrustedCertificateStore
extends Object

A source for trusted root certificate authority (CA) certificates supporting an immutable system CA directory along with mutable directories allowing the user addition of custom CAs and user removal of system CAs. This store supports the TrustedCertificateKeyStoreSpi wrapper to allow a traditional KeyStore interface for use with javax.net.ssl.TrustManagerFactory.init.

The CAs are accessed via KeyStore style aliases. Aliases are made up of a prefix identifying the source ("system:" vs "user:") and a suffix based on the OpenSSL X509_NAME_hash_old function of the CA's subject name. For example, the system CA for "C=US, O=VeriSign, Inc., OU=Class 3 Public Primary Certification Authority" could be represented as "system:7651b327.0". By using the subject hash, operations such as getCertificateAlias can be implemented efficiently without scanning the entire store.

In addition to supporting the TrustedCertificateKeyStoreSpi implementation, TrustedCertificateStore also provides the additional public methods #isTrustAnchor and findIssuer(java.security.cert.X509Certificate) to allow efficient lookup operations for CAs again based on the file naming convention.

The KeyChainService users the installCertificate and deleteCertificateEntry(java.lang.String) to install user CAs as well as delete those user CAs as well as system CAs. The deletion of system CAs is performed by placing an exact copy of that CA in the deleted directory. Such deletions are intended to persist across upgrades but not intended to mask a CA with a matching name or public key but is otherwise reissued in a system update. Reinstalling a deleted system certificate simply removes the copy from the deleted directory, reenabling the original in the system directory.

Note that the default mutable directory is created by init via configuration in the system/core/rootdir/init.rc file. The directive "mkdir /data/misc/keychain 0775 system system" ensures that its owner and group are the system uid and system gid and that it is world readable but only writable by the system user.

Constructor Summary

Constructors

Constructor and Description
TrustedCertificateStore()
TrustedCertificateStore(File systemDir, File addedDir, File deletedDir)

Method Summary

Modifier and Type	Method and Description
Set<String>	aliases()
Set<String>	allSystemAliases()
boolean	containsAlias(String alias)
void	deleteCertificateEntry(String alias) This could be considered the implementation of TrustedCertificateKeyStoreSpi.engineDeleteEntry but we consider TrustedCertificateKeyStoreSpi to be read only.
X509Certificate	findIssuer(X509Certificate c) This non-KeyStoreSpi public interface is used by TrustManagerImpl to locate the CA certificate that signed the provided X509Certificate.
Certificate	getCertificate(String alias)
Certificate	getCertificate(String alias, boolean includeDeletedSystem)
String	getCertificateAlias(Certificate c)
String	getCertificateAlias(Certificate c, boolean includeDeletedSystem)
List<X509Certificate>	getCertificateChain(X509Certificate leaf) Attempt to build a certificate chain from the supplied leaf argument through the chain of issuers as high up as known.
File	getCertificateFile(File dir, X509Certificate x) Returns a File for where the certificate is found if it exists or where it should be installed if it does not exist.
Date	getCreationDate(String alias)
X509Certificate	getTrustAnchor(X509Certificate c) This non-KeyStoreSpi public interface is used by TrustManagerImpl to locate a CA certificate with the same name and public key as the provided X509Certificate.
void	installCertificate(X509Certificate cert) This non-KeyStoreSpi public interface is used by the KeyChainService to install new CA certificates.
static boolean	isSystem(String alias)
static boolean	isUser(String alias)
boolean	isUserAddedCertificate(X509Certificate cert) Returns true to indicate that the certificate was added by the user, false otherwise.
static void	setDefaultUserDirectory(File root)
Set<String>	userAliases()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TrustedCertificateStore

public TrustedCertificateStore()

TrustedCertificateStore

public TrustedCertificateStore(File systemDir,
                               File addedDir,
                               File deletedDir)

Method Detail

isSystem

public static final boolean isSystem(String alias)

isUser

public static final boolean isUser(String alias)

setDefaultUserDirectory

public static void setDefaultUserDirectory(File root)

getCertificate

public Certificate getCertificate(String alias)

getCertificate

public Certificate getCertificate(String alias,
                                  boolean includeDeletedSystem)

getCreationDate

public Date getCreationDate(String alias)

aliases

public Set<String> aliases()

userAliases

public Set<String> userAliases()

allSystemAliases

public Set<String> allSystemAliases()

containsAlias

public boolean containsAlias(String alias)

getCertificateAlias

public String getCertificateAlias(Certificate c)

getCertificateAlias

public String getCertificateAlias(Certificate c,
                                  boolean includeDeletedSystem)

isUserAddedCertificate

public boolean isUserAddedCertificate(X509Certificate cert)

Returns true to indicate that the certificate was added by the user, false otherwise.

getCertificateFile

public File getCertificateFile(File dir,
                               X509Certificate x)

Returns a File for where the certificate is found if it exists or where it should be installed if it does not exist. The caller can disambiguate these cases by calling File.exists() on the result.

getTrustAnchor

public X509Certificate getTrustAnchor(X509Certificate c)

This non-KeyStoreSpi public interface is used by TrustManagerImpl to locate a CA certificate with the same name and public key as the provided X509Certificate. We match on the name and public key and not the entire certificate since a CA may be reissued with the same name and PublicKey but with other differences (for example when switching signature from md2WithRSAEncryption to SHA1withRSA)

findIssuer

public X509Certificate findIssuer(X509Certificate c)

This non-KeyStoreSpi public interface is used by TrustManagerImpl to locate the CA certificate that signed the provided X509Certificate.

getCertificateChain

public List<X509Certificate> getCertificateChain(X509Certificate leaf)
                                          throws CertificateException

Attempt to build a certificate chain from the supplied leaf argument through the chain of issuers as high up as known. If the chain can't be completed, the most complete chain available will be returned. This means that a list with only the leaf certificate is returned if no issuer certificates could be found.

Throws:

CertificateException - if there was a problem parsing the certificates

installCertificate

public void installCertificate(X509Certificate cert)
                        throws IOException,
                               CertificateException

This non-KeyStoreSpi public interface is used by the KeyChainService to install new CA certificates. It silently ignores the certificate if it already exists in the store.

Throws:

IOException

CertificateException

deleteCertificateEntry

public void deleteCertificateEntry(String alias)
                            throws IOException,
                                   CertificateException

This could be considered the implementation of TrustedCertificateKeyStoreSpi.engineDeleteEntry but we consider TrustedCertificateKeyStoreSpi to be read only. Instead, this is used by the KeyChainService to delete CA certificates.

Throws:

IOException

CertificateException