com.android.apksig

Interface ApkSignerEngine

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

DefaultApkSignerEngine

public interface ApkSignerEngine
extends Closeable

APK signing logic which is independent of how input and output APKs are stored, parsed, and generated.

Operating Model

The abstract operating model is that there is an input APK which is being signed, thus producing an output APK. In reality, there may be just an output APK being built from scratch, or the input APK and the output APK may be the same file. Because this engine does not deal with reading and writing files, it can handle all of these scenarios.

The engine is stateful and thus cannot be used for signing multiple APKs. However, once the engine signed an APK, the engine can be used to re-sign the APK after it has been modified. This may be more efficient than signing the APK using a new instance of the engine. See Incremental Operation.

In the engine's operating model, a signed APK is produced as follows.

1. JAR entries to be signed are output,
2. JAR archive is signed using JAR signing, thus adding the so-called v1 signature to the output,
3. JAR archive is signed using APK Signature Scheme v2, thus adding the so-called v2 signature to the output.

The input APK may contain JAR entries which, depending on the engine's configuration, may or may not be output (e.g., existing signatures may need to be preserved or stripped) or which the engine will overwrite as part of signing. The engine thus offers inputJarEntry(String) which tells the client whether the input JAR entry needs to be output. This avoids the need for the client to hard-code the aspects of APK signing which determine which parts of input must be ignored. Similarly, the engine offers inputApkSigningBlock(DataSource) to help the client avoid dealing with preserving or stripping APK Signature Scheme v2 signature of the input APK.

To use the engine to sign an input APK (or a collection of JAR entries), follow these steps:

1. Obtain a new instance of the engine -- engine instances are stateful and thus cannot be used for signing multiple APKs.
2. Locate the input APK's APK Signing Block and provide it to inputApkSigningBlock(DataSource).
3. For each JAR entry in the input APK, invoke inputJarEntry(String) to determine whether this entry should be output. The engine may request to inspect the entry.
4. For each output JAR entry, invoke outputJarEntry(String) which may request to inspect the entry.
5. Once all JAR entries have been output, invoke outputJarEntries() which may request that additional JAR entries are output. These entries comprise the output APK's JAR signature.
6. Locate the ZIP Central Directory and ZIP End of Central Directory sections in the output and invoke outputZipSections(DataSource, DataSource, DataSource) which may request that an APK Signature Block is inserted before the ZIP Central Directory. The block contains the output APK's APK Signature Scheme v2 signature.
7. Invoke outputDone() to signal that the APK was output in full. The engine will confirm that the output APK is signed.
8. Invoke close() to signal that the engine will no longer be used. This lets the engine free any resources it no longer needs.

Some invocations of the engine may provide the client with a task to perform. The client is expected to perform all requested tasks before proceeding to the next stage of signing. See documentation of each method about the deadlines for performing the tasks requested by the method.

Incremental Operation

The engine supports incremental operation where a signed APK is produced, then modified and re-signed. This may be useful for IDEs, where an app is frequently re-signed after small changes by the developer. Re-signing may be more efficient than signing from scratch.

To use the engine in incremental mode, keep notifying the engine of changes to the APK through inputApkSigningBlock(DataSource), inputJarEntry(String), inputJarEntryRemoved(String), outputJarEntry(String), and outputJarEntryRemoved(String), perform the tasks requested by the engine through these methods, and, when a new signed APK is desired, run through steps 5 onwards to re-sign the APK.

Output-only Operation

The engine's abstract operating model consists of an input APK and an output APK. However, it is possible to use the engine in output-only mode where the engine's input... methods are not invoked. In this mode, the engine has less control over output because it cannot request that some JAR entries are not output. Nevertheless, the engine will attempt to make the output APK signed and will report an error if cannot do so.

See Also:

Application Signing

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ApkSignerEngine.InputJarEntryInstructions Instructions about how to handle an input APK's JAR entry.
static interface	ApkSignerEngine.InspectJarEntryRequest Request to inspect the specified JAR entry.
static interface	ApkSignerEngine.OutputApkSigningBlockRequest Request to add the specified APK Signing Block to the output APK.
static interface	ApkSignerEngine.OutputJarSignatureRequest Request to add JAR signature (aka v1 signature) to the output APK.

Method Summary

Modifier and Type	Method and Description
void	close() Indicates to this engine that it will no longer be used.
void	inputApkSigningBlock(DataSource apkSigningBlock) Indicates to this engine that the input APK contains the provided APK Signing Block.
ApkSignerEngine.InputJarEntryInstructions	inputJarEntry(String entryName) Indicates to this engine that the specified JAR entry was encountered in the input APK.
ApkSignerEngine.InputJarEntryInstructions.OutputPolicy	inputJarEntryRemoved(String entryName) Indicates to this engine that the specified JAR entry was removed from the input.
void	outputDone() Indicates to this engine that the signed APK was output.
ApkSignerEngine.OutputJarSignatureRequest	outputJarEntries() Indicates to this engine that all JAR entries have been output.
ApkSignerEngine.InspectJarEntryRequest	outputJarEntry(String entryName) Indicates to this engine that the specified JAR entry was output.
void	outputJarEntryRemoved(String entryName) Indicates to this engine that the specified JAR entry was removed from the output.
ApkSignerEngine.OutputApkSigningBlockRequest	outputZipSections(DataSource zipEntries, DataSource zipCentralDirectory, DataSource zipEocd) Indicates to this engine that the ZIP sections comprising the output APK have been output.

Method Detail

inputApkSigningBlock

void inputApkSigningBlock(DataSource apkSigningBlock)
                   throws IOException,
                          ApkFormatException,
                          IllegalStateException

Indicates to this engine that the input APK contains the provided APK Signing Block. The block may contain signatures of the input APK, such as APK Signature Scheme v2 signatures.

Parameters:

apkSigningBlock - APK signing block of the input APK. The provided data source is guaranteed to not be used by the engine after this method terminates.

Throws:

IOException - if an I/O error occurs while reading the APK Signing Block

ApkFormatException - if the APK Signing Block is malformed

IllegalStateException - if this engine is closed

inputJarEntry

ApkSignerEngine.InputJarEntryInstructions inputJarEntry(String entryName)
                                                 throws IllegalStateException

Indicates to this engine that the specified JAR entry was encountered in the input APK.

When an input entry is updated/changed, it's OK to not invoke inputJarEntryRemoved(String) before invoking this method.

Returns:

instructions about how to proceed with this entry

Throws:

IllegalStateException - if this engine is closed

outputJarEntry

ApkSignerEngine.InspectJarEntryRequest outputJarEntry(String entryName)
                                               throws IllegalStateException

Indicates to this engine that the specified JAR entry was output.

It is unnecessary to invoke this method for entries added to output by this engine (e.g., requested by outputJarEntries()) provided the entries were output with exactly the data requested by the engine.

When an already output entry is updated/changed, it's OK to not invoke outputJarEntryRemoved(String) before invoking this method.

Returns:

request to inspect the entry or null if the engine does not need to inspect the entry. The request must be fulfilled before outputJarEntries() is invoked.

Throws:

IllegalStateException - if this engine is closed

inputJarEntryRemoved

ApkSignerEngine.InputJarEntryInstructions.OutputPolicy inputJarEntryRemoved(String entryName)
                                                                     throws IllegalStateException

Indicates to this engine that the specified JAR entry was removed from the input. It's safe to invoke this for entries for which inputJarEntry(String) hasn't been invoked.

Returns:

output policy of this JAR entry. The policy indicates how this input entry affects the output APK. The client of this engine should use this information to determine how the removal of this input APK's JAR entry affects the output APK.

Throws:

IllegalStateException - if this engine is closed

outputJarEntryRemoved

void outputJarEntryRemoved(String entryName)
                    throws IllegalStateException

Indicates to this engine that the specified JAR entry was removed from the output. It's safe to invoke this for entries for which outputJarEntry(String) hasn't been invoked.

Throws:

IllegalStateException - if this engine is closed

outputJarEntries

ApkSignerEngine.OutputJarSignatureRequest outputJarEntries()
                                                    throws ApkFormatException,
                                                           NoSuchAlgorithmException,
                                                           InvalidKeyException,
                                                           SignatureException,
                                                           IllegalStateException

Indicates to this engine that all JAR entries have been output.

Returns:

request to add JAR signature to the output or null if there is no need to add a JAR signature. The request will contain additional JAR entries to be output. The request must be fulfilled before outputZipSections(DataSource, DataSource, DataSource) is invoked.

Throws:

ApkFormatException - if the APK is malformed in a way which is preventing this engine from producing a valid signature. For example, if the engine uses the provided META-INF/MANIFEST.MF as a template and the file is malformed.

NoSuchAlgorithmException - if a signature could not be generated because a required cryptographic algorithm implementation is missing

InvalidKeyException - if a signature could not be generated because a signing key is not suitable for generating the signature

SignatureException - if an error occurred while generating a signature

IllegalStateException - if there are unfulfilled requests, such as to inspect some JAR entries, or if the engine is closed

outputZipSections

ApkSignerEngine.OutputApkSigningBlockRequest outputZipSections(DataSource zipEntries,
                                                               DataSource zipCentralDirectory,
                                                               DataSource zipEocd)
                                                        throws IOException,
                                                               ApkFormatException,
                                                               NoSuchAlgorithmException,
                                                               InvalidKeyException,
                                                               SignatureException,
                                                               IllegalStateException

Indicates to this engine that the ZIP sections comprising the output APK have been output.

The provided data sources are guaranteed to not be used by the engine after this method terminates.

Parameters:

zipEntries - the section of ZIP archive containing Local File Header records and data of the ZIP entries. In a well-formed archive, this section starts at the start of the archive and extends all the way to the ZIP Central Directory.

zipCentralDirectory - ZIP Central Directory section

zipEocd - ZIP End of Central Directory (EoCD) record

Returns:

request to add an APK Signing Block to the output or null if the output must not contain an APK Signing Block. The request must be fulfilled before outputDone() is invoked.

Throws:

IOException - if an I/O error occurs while reading the provided ZIP sections

ApkFormatException - if the provided APK is malformed in a way which prevents this engine from producing a valid signature. For example, if the APK Signing Block provided to the engine is malformed.

NoSuchAlgorithmException - if a signature could not be generated because a required cryptographic algorithm implementation is missing

InvalidKeyException - if a signature could not be generated because a signing key is not suitable for generating the signature

SignatureException - if an error occurred while generating a signature

IllegalStateException - if there are unfulfilled requests, such as to inspect some JAR entries or to output JAR signature, or if the engine is closed

outputDone

void outputDone()
         throws IllegalStateException

Indicates to this engine that the signed APK was output.

This does not change the output APK. The method helps the client confirm that the current output is signed.

Throws:

IllegalStateException - if there are unfulfilled requests, such as to inspect some JAR entries or to output signatures, or if the engine is closed

close

void close()

Indicates to this engine that it will no longer be used. Invoking this on an already closed engine is OK.

This does not change the output APK. For example, if the output APK is not yet fully signed, it will remain so after this method terminates.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable