com.android.apksig

Class ApkSigner.Builder

java.lang.Object

com.android.apksig.ApkSigner.Builder

Enclosing class:

ApkSigner

public static class ApkSigner.Builder
extends java.lang.Object

Builder of ApkSigner instances.

The builder requires the following information to construct a working ApkSigner:

• Signer configs or ApkSignerEngine -- provided in the constructor,
• APK to be signed -- see setInputApk variants,
• where to store the output signed APK -- see setOutputApk variants.

Constructor Summary

Constructors

Constructor and Description
Builder(ApkSignerEngine signerEngine) Constructs a new Builder for an ApkSigner which signs using the provided signing engine.
Builder(java.util.List<ApkSigner.SignerConfig> signerConfigs) Constructs a new Builder for an ApkSigner which signs using the provided signer configurations.

Method Summary

Modifier and Type	Method and Description
ApkSigner	build() Returns a new ApkSigner instance initialized according to the configuration of this builder.
ApkSigner.Builder	setCreatedBy(java.lang.String createdBy) Sets the value of the Created-By field in JAR signature files.
ApkSigner.Builder	setDebuggableApkPermitted(boolean permitted) Sets whether the APK should be signed even if it is marked as debuggable (android:debuggable="true" in its AndroidManifest.xml).
ApkSigner.Builder	setInputApk(DataSource inputApk) Sets the APK to be signed.
ApkSigner.Builder	setInputApk(java.io.File inputApk) Sets the APK to be signed.
ApkSigner.Builder	setMinSdkVersion(int minSdkVersion) Sets the minimum Android platform version (API Level) on which APK signatures produced by the signer being built must verify.
ApkSigner.Builder	setOtherSignersSignaturesPreserved(boolean preserved) Sets whether signatures produced by signers other than the ones configured in this engine should be copied from the input APK to the output APK.
ApkSigner.Builder	setOutputApk(DataSink outputApkOut, DataSource outputApkIn) Sets the sink which will receive the output (signed) APK.
ApkSigner.Builder	setOutputApk(java.io.File outputApk) Sets the location of the output (signed) APK.
ApkSigner.Builder	setOutputApk(ReadableDataSink outputApk) Sets the readable data sink which will receive the output (signed) APK.
ApkSigner.Builder	setV1SigningEnabled(boolean enabled) Sets whether the APK should be signed using JAR signing (aka v1 signature scheme).
ApkSigner.Builder	setV2SigningEnabled(boolean enabled) Sets whether the APK should be signed using APK Signature Scheme v2 (aka v2 signature scheme).

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder(java.util.List<ApkSigner.SignerConfig> signerConfigs)

Constructs a new Builder for an ApkSigner which signs using the provided signer configurations. The resulting signer may be further customized through this builder's setters, such as setMinSdkVersion(int), setV1SigningEnabled(boolean), setV2SigningEnabled(boolean), setOtherSignersSignaturesPreserved(boolean), setCreatedBy(String).

#Builder(ApkSignerEngine) is an alternative for advanced use cases where more control over low-level details of signing is desired.

Builder

public Builder(ApkSignerEngine signerEngine)

Constructs a new Builder for an ApkSigner which signs using the provided signing engine. This is meant for advanced use cases where more control is needed over the lower-level details of signing. For typical use cases, #Builder(List) is more appropriate.

Method Detail

setInputApk

public ApkSigner.Builder setInputApk(java.io.File inputApk)

Sets the APK to be signed.

See Also:

setInputApk(DataSource)

setInputApk

public ApkSigner.Builder setInputApk(DataSource inputApk)

Sets the APK to be signed.

See Also:

setInputApk(File)

setOutputApk

public ApkSigner.Builder setOutputApk(java.io.File outputApk)

Sets the location of the output (signed) APK. ApkSigner will create this file if it doesn't exist.

See Also:

setOutputApk(ReadableDataSink), setOutputApk(DataSink, DataSource)

setOutputApk

public ApkSigner.Builder setOutputApk(ReadableDataSink outputApk)

Sets the readable data sink which will receive the output (signed) APK. After signing, the contents of the output APK will be available via the DataSource interface of the sink.

This variant of setOutputApk is useful for avoiding writing the output APK to a file. For example, an in-memory data sink, such as DataSinks.newInMemoryDataSink(), could be used instead of a file.

See Also:

setOutputApk(File), setOutputApk(DataSink, DataSource)

setOutputApk

public ApkSigner.Builder setOutputApk(DataSink outputApkOut,
                                      DataSource outputApkIn)

Sets the sink which will receive the output (signed) APK. Data received by the outputApkOut sink must be visible through the outputApkIn data source.

This is an advanced variant of setOutputApk(ReadableDataSink), enabling the sink and the source to be different objects.

See Also:

setOutputApk(ReadableDataSink), setOutputApk(File)

setMinSdkVersion

public ApkSigner.Builder setMinSdkVersion(int minSdkVersion)

Sets the minimum Android platform version (API Level) on which APK signatures produced by the signer being built must verify. This method is useful for overriding the default behavior where the minimum API Level is obtained from the android:minSdkVersion attribute of the APK's AndroidManifest.xml.

Note: This method may result in APK signatures which don't verify on some Android platform versions supported by the APK.

Note: This method may only be invoked when this builder is not initialized with an ApkSignerEngine.

Throws:

java.lang.IllegalStateException - if this builder was initialized with an ApkSignerEngine

setV1SigningEnabled

public ApkSigner.Builder setV1SigningEnabled(boolean enabled)

Sets whether the APK should be signed using JAR signing (aka v1 signature scheme).

By default, whether APK is signed using JAR signing is determined by ApkSigner, based on the platform versions supported by the APK or specified using setMinSdkVersion(int). Disabling JAR signing will result in APK signatures which don't verify on Android Marshmallow (Android 6.0, API Level 23) and lower.

Note: This method may only be invoked when this builder is not initialized with an ApkSignerEngine.

Parameters:

enabled - true to require the APK to be signed using JAR signing, false to require the APK to not be signed using JAR signing.

Throws:

java.lang.IllegalStateException - if this builder was initialized with an ApkSignerEngine

See Also:

JAR signing

setV2SigningEnabled

public ApkSigner.Builder setV2SigningEnabled(boolean enabled)

Sets whether the APK should be signed using APK Signature Scheme v2 (aka v2 signature scheme).

By default, whether APK is signed using APK Signature Scheme v2 is determined by ApkSigner based on the platform versions supported by the APK or specified using setMinSdkVersion(int).

Note: This method may only be invoked when this builder is not initialized with an ApkSignerEngine.

Parameters:

enabled - true to require the APK to be signed using APK Signature Scheme v2, false to require the APK to not be signed using APK Signature Scheme v2.

Throws:

java.lang.IllegalStateException - if this builder was initialized with an ApkSignerEngine

See Also:

APK Signature Scheme v2

setDebuggableApkPermitted

public ApkSigner.Builder setDebuggableApkPermitted(boolean permitted)

Sets whether the APK should be signed even if it is marked as debuggable (android:debuggable="true" in its AndroidManifest.xml). For backward compatibility reasons, the default value of this setting is true.

It is dangerous to sign debuggable APKs with production/release keys because Android platform loosens security checks for such APKs. For example, arbitrary unauthorized code may be executed in the context of such an app by anybody with ADB shell access.

Note: This method may only be invoked when this builder is not initialized with an ApkSignerEngine.

setOtherSignersSignaturesPreserved

public ApkSigner.Builder setOtherSignersSignaturesPreserved(boolean preserved)

Sets whether signatures produced by signers other than the ones configured in this engine should be copied from the input APK to the output APK.

By default, signatures of other signers are omitted from the output APK.

Note: This method may only be invoked when this builder is not initialized with an ApkSignerEngine.

Throws:

java.lang.IllegalStateException - if this builder was initialized with an ApkSignerEngine

setCreatedBy

public ApkSigner.Builder setCreatedBy(java.lang.String createdBy)

Sets the value of the Created-By field in JAR signature files.

Note: This method may only be invoked when this builder is not initialized with an ApkSignerEngine.

Throws:

java.lang.IllegalStateException - if this builder was initialized with an ApkSignerEngine

build

public ApkSigner build()

Returns a new ApkSigner instance initialized according to the configuration of this builder.