tools/publishing/app-signing.jd

page.title=Signing Your Applications
@jd:body

<div id="qv-wrapper">
<div id="qv">

<h2>In this document</h2>

<ol>
<li><a href="#overview">Signing Overview</a>
  <ol>
  	<li><a href="#debug-mode">Signing in Debug Mode</a></li>
  	<li><a href="#release-mode">Signing in Release Mode</a></li>
  	<li><a href="#wear-apps">Signing Android Wear Apps</a></li>
  </ol>
</li>
<li><a href="#studio">Signing Your App in Android Studio</a>
  <ol>
  	<li><a href="sign-auto">Automatically Signing Your App</a></li>
  </ol>
</li>
<li><a href="#studio">Signing Your App with Android Studio</a></li>
<li><a href="#considerations">Signing Considerations</a></li>
<li><a href="#secure-key">Securing Your Private Key</a></li>
<li><a href="#expdebug">Expiry of the Debug Certificate</a></li>
<li><a href="#signing-manually">Signing Your App Manually</a></li>
</ol>

<h2>See also</h2>

<ol>
<li><a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a></li>
<li><a href="{@docRoot}tools/publishing/preparing.html">Preparing to Publish</a></li>
</ol>

</div>
</div>


<p>Android requires that all apps be digitally signed with a certificate before they can be
installed. Android uses this certificate to identify the author of an app, and the certificate
does not need to be signed by a certificate authority. Android apps often use self-signed
certificates. The app developer holds the certificate's private key.</p>


<h2 id="overview">Signing Overview</h2>

<p>You can sign an app in debug or release mode. You sign your app in debug mode during development
and in release mode when you are ready to distribute your app. The Android SDK generates a
certificate to sign apps in debug mode. To sign apps in release mode, you need to generate
your own certificate.</p>

<h3 id="debug-mode">Signing in Debug Mode</h3>

<p>In debug mode, you sign your app with a debug certificate generated by the Android SDK tools.
This certificate has a private key with a known password, so you can run and debug your app
without typing the password every time you make a change to your project.</p>

<p>Android Studio signs your app in debug mode automatically when
you run or debug your project from the IDE.</p>

<p>You can run and debug an app signed in debug mode on the emulator and on devices connected
to your development manchine through USB, but you cannot distribute an app signed in debug
mode.</p>

<p>By default, the <em>debug</em> configuration uses a debug keystore, with a known
password and a default key with a known password.
The debug keystore is located in $HOME/.android/debug.keystore, and is created if not present.

The debug build type is set to use this debug <code>SigningConfig</code> automatically. </p>

<p>For more information about how to build and run apps in debug mode, see
<a href="{@docRoot}tools/building/index.html">Building and Running</a>.</p>

<h3 id="release-mode">Signing in Release Mode</h3>

<p>In release mode, you sign your app with your own certificate:</p>

<ol>
<li><em>Create a keystore.</em> A <strong>keystore</strong> is a binary file that contains a
set of private keys. You must keep your keystore in a safe and secure place.</li>
<li><em>Create a private key.</em> A <strong>private key</strong> represents the entity to
be identified with the app, such as a person or a company.</li>
<li><p>Add the signing configuration to the build file for the <code>app</code> module:</p>
        <p><pre>
...
android {
    ...
    defaultConfig { ... }
    signingConfigs {
        release {
            storeFile file("myreleasekey.keystore")
            storePassword "password"
            keyAlias "MyReleaseKey"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            ...
            signingConfig signingConfigs.release
        }
    }
}
...
</pre></p>
    </li>
<li>Invoke the <code>assembleRelease</code> build task from Android Studio.</li>
</ol>

<p>The package in <code>app/build/apk/app-release.apk</code> is now signed with your release key.</p>

<p class="note"><strong>Note:</strong> Including the passwords for your release key and keystore
inside the build file is not a good security practice. Alternatively, you can configure the build
file to obtain these passwords from environment variables or have the build process prompt you
for these passwords.</p>

<p>To obtain these passwords from environment variables:</p>

<pre>
storePassword System.getenv("KSTOREPWD")
keyPassword System.getenv("KEYPWD")
</pre>

<p>To have the build process prompt you for these passwords if you are invoking the build from
the command line:</p>

<pre>
storePassword System.console().readLine("\nKeystore password: ")
keyPassword System.console().readLine("\nKey password: ")
</pre>


<p>After you complete this process, you can distribute your app and publish it on Google Play.</p>

<p class="warning"><strong>Warning:</strong> Keep your keystore and private key in a safe and
secure place, and ensure that you have secure backups of them. If you publish an app to Google
Play and then lose the key with which you signed your app, you will not be able to publish
any updates to your app, since you must always sign all versions of your app with the same
key.</p>

<p>The rest of this document provides detailed instructions about how to generate a private
key and sign your apps in release mode with Android Studio.</p>

<h3 id="wear-apps">Signing Android Wear Apps</h3>

<p>When publishing Android Wear apps, you package the wearable app inside of a handheld app,
because users cannot browse and install apps directly on the wearable. Both apps must be signed.
For more information on packaging and signing Android Wear apps, see
<a href="{@docRoot}training/wearables/apps/packaging.html">Packaging Wearable Apps</a>.</p>


<h2 id="studio">Signing Your App in Android Studio</h2>

<p>To sign your app in release mode in Android Studio, follow these steps:</p>

<ol>
<li>On the menu bar, click <strong>Build</strong> &gt; <strong>Generate Signed APK</strong>.</li>
<li><p>On the <em>Generate Signed APK Wizard</em> window, click <strong>Create new</strong> to create
a new keystore.</p><p>If you already have a keystore, go to step 4.</p></li>
<li><p>On the <em>New Key Store</em> window, provide the required information as shown
in figure 1.</p><p>Your key should be valid for at least 25 years, so you can sign app updates
with the same key through the lifespan of your app.</p>
<img src="{@docRoot}images/tools/signstudio2.png" alt=""
     width="416" height="364" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 1</strong>. Create a new keystore in Android Studio.</p>
</li>
<li><p>On the <em>Generate Signed APK Wizard</em> window, select a keystore, a private key, and enter
the passwords for both. Then click <strong>Next</strong>.</p>
<img src="{@docRoot}images/tools/signstudio1.png" alt=""
     width="349" height="232" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 2</strong>. Select a private key in Android Studio.</p>
</li>
<li><p>On the next window, select a destination for the signed APK and click
<strong>Finish</strong>.</p>
<img src="{@docRoot}images/tools/signstudio3.png" alt=""
     width="350" height="175" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 3</strong>. Generate a signed APK in Android Studio.</p>
</li>
</ol>

<h3 id="sign-auto">Automatically Signing Your App</h3>

<p>In Android Studio, you can configure your project to sign your release APK automatically
during the build process:</p>

<ol>
<li>On the project browser, right click on your app and select <strong>Open Module
Settings</strong>.</li>
<li>On the <em>Project Structure</em> window, select your app's module under <em>Modules</em>.</li>
<li>Click on the <strong>Signing</strong> tab.</li>
<li><p>Select your keystore file, enter a name for this signing configuration (as you may create
more than one), and enter the required information.</p>
<img src="{@docRoot}images/tools/signstudio10.png" alt=""
     width="623" height="372" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 4</strong>. Create a signing configuration in Android Studio.</p>
</li>
<li>Click on the <strong>Build Types</strong> tab.</li>
<li>Select the <strong>release</strong> build.</li>
<li><p>Under <em>Signing Config</em>, select the signing configuration you just created.</p>
<img src="{@docRoot}images/tools/signstudio11.png" alt=""
     width="623" height="372" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 5</strong>. Select a signing configuration in Android Studio.</p>
</li>
<li>Click <strong>OK</strong>.</li>
</ol>

<p>You can also specify your signing settings in Gradle configuration files. For more information,
see <a href="{@docRoot}tools/building/configuring-gradle.html#configureSigning">Configuring Gradle
Builds</a>.</p>


<h2 id="considerations">Signing Considerations</h2>

<p>You should sign all of your apps with the same certificate throughout the expected lifespan
of your applications. There are several reasons why you should do so:</p>

<ul>
<li>App upgrade: When the system is installing an update to an app, it compares the certificate(s)
in the new version with those in the existing version. The system allows the update if the
certificates match. If you sign the new version with a different certificate, you must assign a
different package name to the application&mdash;in this case, the user installs the new version as
a completely new application.</li>
<li>App modularity: Android allows apps signed by the same certificate to run in the same process,
if the applications so requests, so that the system treats them as a single application. In this
way you can deploy your app in modules, and users can update each of the modules independently.</li>
<li>Code/data sharing through permissions: Android provides signature-based permissions
enforcement, so that an app can expose functionality to another app that is signed with a
specified certificate. By signing multiple apps with the same certificate and using
signature-based permissions checks, your apps can share code and data in a secure manner.</li>
</ul>

<p>If you plan to support upgrades for an app, ensure that your key has a validity
period that exceeds the expected lifespan of that app. A validity period of 25 years or more is
recommended. When your key's validity period expires, users will no longer be able to seamlessly
upgrade to new versions of your application.</p>

<p>If you plan to publish your apps on Google Play, the key you use to sign these apps must have
a validity period ending after 22 October 2033. Google Play enforces this requirement to ensure
that users can seamlessly upgrade apps when new versions are available.</p>


<h2 id="secure-key">Securing Your Private Key</h2>

<p>Maintaining the security of your private key is of critical importance, both to you and to
the user. If you allow someone to use your key, or if you leave your keystore and passwords in
an unsecured location such that a third-party could find and use them, your authoring identity
and the trust of the user are compromised.</p>

<p>If a third party should manage to take your key without your knowledge or permission, that
person could sign and distribute apps that maliciously replace your authentic apps or corrupt
them. Such a person could also sign and distribute apps under your identity that attack
other apps or the system itself, or corrupt or steal user data.</p>

<p>Your private key is required for signing all future versions of your app. If you lose or
misplace your key, you will not be able to publish updates to your existing appn. You cannot
regenerate a previously generated key.</p>

<p>Your reputation as a developer entity depends on your securing your private key properly, at
all times, until the key is expired. Here are some tips for keeping your key secure:</p>

<ul>
<li>Select strong passwords for the keystore and key.</li>
<li>Do not give or lend anyone your private key, and do not let unauthorized persons know your
keystore and key passwords.</li>
<li>Keep the keystore file containing your private key in a safe, secure place.</li>
</ul>

<p>In general, if you follow common-sense precautions when generating, using, and storing
your key, it will remain secure.</p>


<h2 id="expdebug">Expiry of the Debug Certificate</h2>

<p>The self-signed certificate used to sign your application in debug mode has an expiration date
of 365 days from its creation date. When the certificate expires, you will get a build error.</p>

<p>To fix this problem, simply delete the <code>debug.keystore</code> file. The default storage
location is in <code>~/.android/</code> on OS X and Linux, in <code>C:\Documents and
Settings\&lt;user&gt;\.android\</code> on Windows XP, and in
<code>C:\Users\&lt;user&gt;\.android\</code> on Windows Vista and Windows 7.</p>

<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p>

<p>Note that, if your development machine is using a non-Gregorian locale, the build tools may
erroneously generate an already-expired debug certificate, so that you get an error when trying
to compile your application. For workaround information, see the troubleshooting topic
<a href="{@docRoot}resources/faq/troubleshooting.html#signingcalendar">I can't compile my app
because the build tools generated an expired debug certificate</a>.</p>


<h2 id="signing-manually">Signing Your App Manually</h2>

<p>You do not need Android Studio to sign your app. You can sign
your app from the command line using standard tools from the Android SDK and the JDK. To sign
an app in release mode from the command line:</p>

<ol>
<li>
  <p>Generate a private key using
  <code><a href="http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html">keytool</a></code>.
  For example:</p>
<pre>
$ keytool -genkey -v -keystore my-release-key.keystore
-alias alias_name -keyalg RSA -keysize 2048 -validity 10000
</pre>
  <p>This example prompts you for passwords for the keystore and key, and to provide the
  Distinguished Name fields for your key. It then generates the keystore as a file called
  <code>my-release-key.keystore</code>. The keystore contains a single key, valid for 10000 days.
  The alias is a name that you will use later when signing your app.</p>
</li>
<li style="margin-top:18px">
  <p>Compile your app in release mode to obtain an unsigned APK.</p>
</li>
<li style="margin-top:18px">
  <p>Sign your app with your private key using
  <code><a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html">jarsigner</a></code>:
  </p>
<pre>
$ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1
-keystore my-release-key.keystore my_application.apk alias_name
</pre>
  <p>This example prompts you for passwords for the keystore and key. It then modifies the APK
  in-place to sign it. Note that you can sign an APK multiple times with different keys.</p>
</li>
<li style="margin-top:18px">
  <p>Verify that your APK is signed. For example:</p>
<pre>
$ jarsigner -verify -verbose -certs my_application.apk
</pre>
</li>
<li style="margin-top:18px">
  <p>Align the final APK package using
  <code><a href="{@docRoot}tools/help/zipalign.html">zipalign</a></code>.</p>
<pre>
$ zipalign -v 4 your_project_name-unaligned.apk your_project_name.apk
</pre>
  <p><code>zipalign</code> ensures that all uncompressed data starts with a particular byte
  alignment relative to the start of the file, which reduces the amount of RAM consumed by an
  app.</p>
</li>
</ol>