com.android.apksig

Class SigningCertificateLineage

java.lang.Object

com.android.apksig.SigningCertificateLineage

public class SigningCertificateLineage
extends java.lang.Object

APK Signer Lineage.

The signer lineage contains a history of signing certificates with each ancestor attesting to the validity of its descendant. Each additional descendant represents a new identity that can be used to sign an APK, and each generation has accompanying attributes which represent how the APK would like to view the older signing certificates, specifically how they should be trusted in certain situations.

Its primary use is to enable APK Signing Certificate Rotation. The Android platform verifies the APK Signer Lineage, and if the current signing certificate for the APK is in the Signer Lineage, and the Lineage contains the certificate the platform associates with the APK, it will allow upgrades to the new certificate.

See Also:

Application Signing

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SigningCertificateLineage.Builder Builder of SigningCertificateLineage instances.
static class	SigningCertificateLineage.SignerCapabilities Representation of the capabilities the APK would like to grant to its old signing certificates.
static class	SigningCertificateLineage.SignerConfig Configuration of a signer.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAGIC

Method Summary

Modifier and Type	Method and Description
static SigningCertificateLineage	consolidateLineages(java.util.List<SigningCertificateLineage> lineages) Consolidates all of the lineages found in an APK into one lineage, which is the longest one.
byte[]	generateV3SignerAttribute()
java.util.List<java.security.cert.X509Certificate>	getCertificatesInLineage() Returns a list containing all of the certificates in the lineage.
SigningCertificateLineage.SignerCapabilities	getSignerCapabilities(SigningCertificateLineage.SignerConfig config) Returns the SignerCapabilities for the signer in the lineage that matches the provided config.
SigningCertificateLineage.SignerCapabilities	getSignerCapabilities(java.security.cert.X509Certificate cert) Returns the SignerCapabilities for the signer in the lineage that matches the provided certificate.
SigningCertificateLineage	getSubLineage(java.security.cert.X509Certificate x509Certificate) Returns a new SigingCertificateLineage which terminates at the node corresponding to the given certificate.
boolean	isCertificateInLineage(java.security.cert.X509Certificate cert) Returns true if the specified certificate is in the lineage.
boolean	isSignerInLineage(SigningCertificateLineage.SignerConfig config) Returns true if the specified config is in the lineage.
static SigningCertificateLineage	readFromApkDataSource(DataSource apk) Extracts a Signing Certificate Lineage from the proof-of-rotation attribute in the V3 signature block of the provided APK DataSource.
static SigningCertificateLineage	readFromApkFile(java.io.File apkFile) Extracts a Signing Certificate Lineage from the proof-of-rotation attribute in the V3 signature block of the provided APK File.
static SigningCertificateLineage	readFromDataSource(DataSource dataSource)
static SigningCertificateLineage	readFromFile(java.io.File file)
static SigningCertificateLineage	readFromSignedData(java.nio.ByteBuffer signedData) Extracts a Signing Certificate Lineage from the proof-of-rotation attribute in the provided signed data portion of a signer in a V3 signature block.
static SigningCertificateLineage	readFromV3AttributeValue(byte[] attrValue) Extracts a Signing Certificate Lineage from a v3 signer proof-of-rotation attribute.
int	size() The number of signing certificates in the lineage, including the current signer, which means this value can also be used to V2determine the number of signing certificate rotations by subtracting 1.
java.util.List<DefaultApkSignerEngine.SignerConfig>	sortSignerConfigs(java.util.List<DefaultApkSignerEngine.SignerConfig> signerConfigs)
SigningCertificateLineage	spawnDescendant(SigningCertificateLineage.SignerConfig parent, SigningCertificateLineage.SignerConfig child) Add a new signing certificate to the lineage.
SigningCertificateLineage	spawnDescendant(SigningCertificateLineage.SignerConfig parent, SigningCertificateLineage.SignerConfig child, SigningCertificateLineage.SignerCapabilities childCapabilities) Add a new signing certificate to the lineage.
void	updateSignerCapabilities(SigningCertificateLineage.SignerConfig config, SigningCertificateLineage.SignerCapabilities capabilities) Updates the SignerCapabilities for the signer in the lineage that matches the provided config.
void	writeToDataSink(DataSink dataSink)
void	writeToFile(java.io.File file)

Methods inherited from class java.lang.Object

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

Field Detail

MAGIC

public static final int MAGIC

See Also:

Constant Field Values

Method Detail

readFromFile

public static SigningCertificateLineage readFromFile(java.io.File file)
                                              throws java.io.IOException

Throws:

java.io.IOException

readFromDataSource

public static SigningCertificateLineage readFromDataSource(DataSource dataSource)
                                                    throws java.io.IOException

Throws:

java.io.IOException

readFromV3AttributeValue

public static SigningCertificateLineage readFromV3AttributeValue(byte[] attrValue)
                                                          throws java.io.IOException

Extracts a Signing Certificate Lineage from a v3 signer proof-of-rotation attribute. this may not give a complete representation of an APK's signing certificate history, since the APK may have multiple signers corresponding to different platform versions. Use readFromApkFile to handle this case.

Parameters:

attrValue -

Throws:

java.io.IOException

readFromApkFile

public static SigningCertificateLineage readFromApkFile(java.io.File apkFile)
                                                 throws java.io.IOException,
                                                        ApkFormatException

Extracts a Signing Certificate Lineage from the proof-of-rotation attribute in the V3 signature block of the provided APK File.

Throws:

java.lang.IllegalArgumentException - if the provided APK does not contain a V3 signature block, or if the V3 signature block does not contain a valid lineage.

java.io.IOException

ApkFormatException

readFromApkDataSource

public static SigningCertificateLineage readFromApkDataSource(DataSource apk)
                                                       throws java.io.IOException,
                                                              ApkFormatException

Extracts a Signing Certificate Lineage from the proof-of-rotation attribute in the V3 signature block of the provided APK DataSource.

Throws:

java.lang.IllegalArgumentException - if the provided APK does not contain a V3 signature block, or if the V3 signature block does not contain a valid lineage.

java.io.IOException

ApkFormatException

readFromSignedData

public static SigningCertificateLineage readFromSignedData(java.nio.ByteBuffer signedData)
                                                    throws java.io.IOException,
                                                           ApkFormatException

Extracts a Signing Certificate Lineage from the proof-of-rotation attribute in the provided signed data portion of a signer in a V3 signature block.

Throws:

java.lang.IllegalArgumentException - if the provided signed data does not contain a valid lineage.

java.io.IOException

ApkFormatException

writeToFile

public void writeToFile(java.io.File file)
                 throws java.io.IOException

Throws:

java.io.IOException

writeToDataSink

public void writeToDataSink(DataSink dataSink)
                     throws java.io.IOException

Throws:

java.io.IOException

spawnDescendant

public SigningCertificateLineage spawnDescendant(SigningCertificateLineage.SignerConfig parent,
                                                 SigningCertificateLineage.SignerConfig child)
                                          throws java.security.cert.CertificateEncodingException,
                                                 java.security.InvalidKeyException,
                                                 java.security.NoSuchAlgorithmException,
                                                 java.security.SignatureException

Add a new signing certificate to the lineage. This effectively creates a signing certificate rotation event, forcing APKs which include this lineage to be signed by the new signer. The flags associated with the new signer are set to a default value.

Parameters:

parent - current signing certificate of the containing APK

child - new signing certificate which will sign the APK contents

Throws:

java.security.cert.CertificateEncodingException

java.security.InvalidKeyException

java.security.NoSuchAlgorithmException

java.security.SignatureException

spawnDescendant

public SigningCertificateLineage spawnDescendant(SigningCertificateLineage.SignerConfig parent,
                                                 SigningCertificateLineage.SignerConfig child,
                                                 SigningCertificateLineage.SignerCapabilities childCapabilities)
                                          throws java.security.cert.CertificateEncodingException,
                                                 java.security.InvalidKeyException,
                                                 java.security.NoSuchAlgorithmException,
                                                 java.security.SignatureException

Add a new signing certificate to the lineage. This effectively creates a signing certificate rotation event, forcing APKs which include this lineage to be signed by the new signer.

Parameters:

parent - current signing certificate of the containing APK

child - new signing certificate which will sign the APK contents

childCapabilities - flags

Throws:

java.security.cert.CertificateEncodingException

java.security.InvalidKeyException

java.security.NoSuchAlgorithmException

java.security.SignatureException

size

public int size()

The number of signing certificates in the lineage, including the current signer, which means this value can also be used to V2determine the number of signing certificate rotations by subtracting 1.

generateV3SignerAttribute

public byte[] generateV3SignerAttribute()

sortSignerConfigs

public java.util.List<DefaultApkSignerEngine.SignerConfig> sortSignerConfigs(java.util.List<DefaultApkSignerEngine.SignerConfig> signerConfigs)

getSignerCapabilities

public SigningCertificateLineage.SignerCapabilities getSignerCapabilities(SigningCertificateLineage.SignerConfig config)

Returns the SignerCapabilities for the signer in the lineage that matches the provided config.

getSignerCapabilities

public SigningCertificateLineage.SignerCapabilities getSignerCapabilities(java.security.cert.X509Certificate cert)

Returns the SignerCapabilities for the signer in the lineage that matches the provided certificate.

updateSignerCapabilities

public void updateSignerCapabilities(SigningCertificateLineage.SignerConfig config,
                                     SigningCertificateLineage.SignerCapabilities capabilities)

Updates the SignerCapabilities for the signer in the lineage that matches the provided config. Only those capabilities that have been modified through the setXX methods will be updated for the signer to prevent unset default values from being applied.

getCertificatesInLineage

public java.util.List<java.security.cert.X509Certificate> getCertificatesInLineage()

Returns a list containing all of the certificates in the lineage.

isSignerInLineage

public boolean isSignerInLineage(SigningCertificateLineage.SignerConfig config)

Returns true if the specified config is in the lineage.

isCertificateInLineage

public boolean isCertificateInLineage(java.security.cert.X509Certificate cert)

Returns true if the specified certificate is in the lineage.

getSubLineage

public SigningCertificateLineage getSubLineage(java.security.cert.X509Certificate x509Certificate)

Returns a new SigingCertificateLineage which terminates at the node corresponding to the given certificate. This is useful in the event of rotating to a new signing algorithm that is only supported on some platform versions. It enables a v3 signature to be generated using this signing certificate and the shortened proof-of-rotation record from this sub lineage in conjunction with the appropriate SDK version values.

Parameters:

x509Certificate - the signing certificate for which to search

Returns:

A new SigningCertificateLineage if the given certificate is present.

Throws:

java.lang.IllegalArgumentException - if the provided certificate is not in the lineage.

consolidateLineages

public static SigningCertificateLineage consolidateLineages(java.util.List<SigningCertificateLineage> lineages)

Consolidates all of the lineages found in an APK into one lineage, which is the longest one. In so doing, it also checks that all of the smaller lineages are contained in the largest, and that they properly cover the desired platform ranges. An APK may contain multiple lineages, one for each signer, which correspond to different supported platform versions. In this event, the lineage(s) from the earlier platform version(s) need to be present in the most recent (longest) one to make sure that when a platform version changes. This does not verify that the largest lineage corresponds to the most recent supported platform version. That check requires is performed during v3 verification.