Merge "MIDI test apps are now on Play Store"
diff --git a/src/devices/tech/config/low-ram.jd b/src/devices/tech/config/low-ram.jd
index ca0dd71..f6d9566 100644
--- a/src/devices/tech/config/low-ram.jd
+++ b/src/devices/tech/config/low-ram.jd
@@ -26,9 +26,9 @@
<h2 id="intro">Introduction</h2>
-<p>Android now supports devices with 512MB of RAM. This documentation is intended
-to help OEMs optimize and configure Android 4.4 for low-memory devices. Several
-of these optimizations are generic enough that they can be applied to previous
+<p>Android now supports devices with 512MB of RAM. This documentation is intended
+to help OEMs optimize and configure Android 4.4 for low-memory devices. Several
+of these optimizations are generic enough that they can be applied to previous
releases as well.</p>
<h2 id="optimizations">Android 4.4 platform optimizations</h2>
@@ -38,8 +38,8 @@
<li>Validated memory-saving kernel configurations: Kernel Same-page Merging
(KSM), and Swap to ZRAM.</li>
<li>Kill cached processes if about to be uncached and too large.</li>
-<li>Don’t allow large services to put themselves back into A Services (so they
-can’t cause the launcher to be killed).</li>
+<li>Don't allow large services to put themselves back into A Services (so they
+can't cause the launcher to be killed).</li>
<li>Kill processes (even ordinarily unkillable ones such as the current IME)
that get too large in idle maintenance.</li>
<li>Serialize the launch of background services.</li>
@@ -73,31 +73,32 @@
<p>
New memtrack HAL to track graphics memory allocations, additional information
in dumpsys meminfo, clarified summaries in meminfo (for example reported free
-RAM includes RAM of cached processes, so that OEMs don’t try to optimize the
+RAM includes RAM of cached processes, so that OEMs don't try to optimize the
wrong thing).
</p>
<h2 id="build-time">Build-time configuration</h2>
<h3 id="flag">Enable Low Ram Device flag</h3>
-<p>We are introducing a new API called <code>ActivityManager.isLowRamDevice()</code> for applications to determine if they should turn off specific memory-intensive
+<p>We are introducing a new API called
+<code>ActivityManager.isLowRamDevice()</code> for applications to determine if
+they should turn off specific memory-intensive
features that work poorly on low-memory devices.</p>
-<p>For 512MB devices, this API is expected to return: "true" It can be enabled by
+<p>For 512MB devices, this API is expected to return: "true" It can be enabled by
the following system property in the device makefile.<br/>
<code>PRODUCT_PROPERTY_OVERRIDES += ro.config.low_ram=true</code></p>
<h3 id="jit">Disable JIT</h3>
- <p>System-wide JIT memory usage is dependent on the number of applications
- running and the code footprint of those applications. The JIT establishes a
- maximum translated code cache size and touches the pages within it as needed.
+ <p>System-wide JIT memory usage is dependent on the number of applications
+ running and the code footprint of those applications. The JIT establishes a
+ maximum translated code cache size and touches the pages within it as needed.
JIT costs somewhere between 3M and 6M across a typical running system.<br/>
<br/>
- The large apps tend to max out the code cache fairly quickly (which by default
- has been 1M). On average, JIT cache usage runs somewhere between 100K and 200K
- bytes per app. Reducing the max size of the cache can help somewhat with
- memory usage, but if set too low will send the JIT into a thrashing mode. For
-the really low-memory devices, we recommend the JIT be disabled entirely.<code>
-</code></p>
+ The large apps tend to max out the code cache fairly quickly (which by default
+ has been 1M). On average, JIT cache usage runs somewhere between 100K and 200K
+ bytes per app. Reducing the max size of the cache can help somewhat with
+ memory usage, but if set too low will send the JIT into a thrashing mode. For
+the really low-memory devices, we recommend the JIT be disabled entirely.</p>
<p>This can be achieved by adding the following line to the product makefile:<br/>
<code>PRODUCT_PROPERTY_OVERRIDES += dalvik.vm.jit.codecachesize=0</code></p>
@@ -112,93 +113,135 @@
<h3 id="kernel-tuning">Tuning kernel/ActivityManager to reduce direct reclaim </h3>
- <p>Direct reclaim happens when a process or the kernel tries to allocate a page
- of memory (either directly or due to faulting in a new page) and the kernel
- has used all available free memory. This requires the kernel to block the
- allocation while it frees up a page. This in turn often requires disk I/O to
- flush out a dirty file-backed page or waiting for <code>lowmemorykiller</code> to kill a
+ <p>Direct reclaim happens when a process or the kernel tries to allocate a page
+ of memory (either directly or due to faulting in a new page) and the kernel
+ has used all available free memory. This requires the kernel to block the
+ allocation while it frees up a page. This in turn often requires disk I/O to
+ flush out a dirty file-backed page or waiting for <code>lowmemorykiller</code> to kill a
process. This can result in extra I/O in any thread, including a UI thread.</p>
-
- <p>To avoid direct reclaim, the kernel has watermarks that trigger <code>kswapd</code> or
- background reclaim. This is a thread that tries to free up pages so the next
- time a real thread allocates it can succeed quickly.</p>
-
- <p>The default threshold to trigger background reclaim is fairly low, around 2MB
- on a 2GB device and 636KB on a 512MB device. And the kernel reclaims only a
- few MB of memory in background reclaim. This means any process that quickly
- allocates more than a few megabytes is going to quickly hit direct reclaim.</p>
-
-<p>Support for a new kernel tunable is added in the android-3.4 kernel branch as
- patch 92189d47f66c67e5fd92eafaa287e153197a454f ("add extra free kbytes
- tunable"). Cherry-picking this patch to a device's kernel will allow
- ActivityManager to tell the kernel to try to keep 3 full-screen 32 bpp buffers
- of memory free.</p>
-
-<p>These thresholds can be configured via the framework config.xml</p>
-<p><code> <!-- Device configuration setting the /proc/sys/vm/extra_free_kbytes tunable in the kernel (if it exists). A high value will increase the amount of memory that the kernel tries to keep free, reducing allocation time and causing the lowmemorykiller to kill earlier. A low value allows more memory to be used by processes but may cause more allocations to block waiting on disk I/O or lowmemorykiller. Overrides the default value chosen by ActivityManager based on screen size. 0 prevents keeping any extra memory over what the kernel keeps by default. -1 keeps the default. --><br />
-<integer name="config_extraFreeKbytesAbsolute">-1</integer></code></p>
-<code>
-<p> <!-- Device configuration adjusting the /proc/sys/vm/extra_free_kbytes tunable in the kernel (if it exists). 0 uses the default value chosen by ActivityManager. A positive value will increase the amount of memory that the kernel tries to keep free, reducing allocation time and causing the lowmemorykiller to kill earlier. A negative value allows more memory to be used by processes but may cause more allocations to block waiting on disk I/O or lowmemorykiller. Directly added to the default value chosen by ActivityManager based on screen size. --><br />
- <integer name="config_extraFreeKbytesAdjust">0</integer></code>
+ <p>To avoid direct reclaim, the kernel has watermarks that trigger <code>kswapd</code> or
+ background reclaim. This is a thread that tries to free up pages so the next
+ time a real thread allocates it can succeed quickly.</p>
+
+ <p>The default threshold to trigger background reclaim is fairly low, around 2MB
+ on a 2GB device and 636KB on a 512MB device. And the kernel reclaims only a
+ few MB of memory in background reclaim. This means any process that quickly
+ allocates more than a few megabytes is going to quickly hit direct reclaim.</p>
+
+<p>Support for a new kernel tunable is added in the android-3.4 kernel branch as
+ patch 92189d47f66c67e5fd92eafaa287e153197a454f ("add extra free kbytes
+ tunable"). Cherry-picking this patch to a device's kernel will allow
+ ActivityManager to tell the kernel to try to keep 3 full-screen 32 bpp buffers
+ of memory free.</p>
+
+<p>These thresholds can be configured via the framework config.xml</p>
+
+<pre>
+<!-- Device configuration setting the /proc/sys/vm/extra_free_kbytes tunable
+in the kernel (if it exists). A high value will increase the amount of memory
+that the kernel tries to keep free, reducing allocation time and causing the
+lowmemorykiller to kill earlier. A low value allows more memory to be used by
+processes but may cause more allocations to block waiting on disk I/O or
+lowmemorykiller. Overrides the default value chosen by ActivityManager based
+on screen size. 0 prevents keeping any extra memory over what the kernel keeps
+by default. -1 keeps the default. -->
+<integer name="config_extraFreeKbytesAbsolute">-1</integer>
+</pre>
+
+<pre>
+<!-- Device configuration adjusting the /proc/sys/vm/extra_free_kbytes
+tunable in the kernel (if it exists). 0 uses the default value chosen by
+ActivityManager. A positive value will increase the amount of memory that the
+kernel tries to keep free, reducing allocation time and causing the
+lowmemorykiller to kill earlier. A negative value allows more memory to be
+used by processes but may cause more allocations to block waiting on disk I/O
+or lowmemorykiller. Directly added to the default value chosen by
+ActivityManager based on screen size. -->
+<integer name="config_extraFreeKbytesAdjust">0</integer>
+</pre>
<h3 id="lowmem">Tuning LowMemoryKiller</h3>
-
- <p>ActivityManager configures the thresholds of the LowMemoryKiller to match its
- expectation of the working set of file-backed pages (cached pages) required to
- run the processes in each priority level bucket. If a device has high
- requirements for the working set, for example if the vendor UI requires more
+<p>ActivityManager configures the thresholds of the LowMemoryKiller to match its
+expectation of the working set of file-backed pages (cached pages) required to
+run the processes in each priority level bucket. If a device has high
+requirements for the working set, for example if the vendor UI requires more
memory or if more services have been added, the thresholds can be increased. </p>
-<p>The thresholds can be reduced if too much memory is being reserved for file
- backed pages, so that background processes are being killed long before disk
+
+<p>The thresholds can be reduced if too much memory is being reserved for file
+backed pages, so that background processes are being killed long before disk
thrashing would occur due to the cache getting too small.</p>
-<p> <code><!-- Device configuration setting the minfree tunable in the lowmemorykiller in the kernel. A high value will cause the lowmemorykiller to fire earlier, keeping more memory in the file cache and preventing I/O thrashing, but allowing fewer processes to stay in memory. A low value will keep more processes in memory but may cause thrashing if set too low. Overrides the default value chosen by ActivityManager based on screen size and total memory for the largest lowmemorykiller bucket, and scaled proportionally to the smaller buckets. -1 keeps the default. --><br />
- <integer name="config_lowMemoryKillerMinFreeKbytesAbsolute">-1</integer></code></p>
-<p> <code><!-- Device configuration adjusting the minfree tunable in the lowmemorykiller in the kernel. A high value will cause the lowmemorykiller to fire earlier, keeping more memory in the file cache and preventing I/O thrashing, but allowing fewer processes to stay in memory. A low value will keep more processes in memory but may cause thrashing if set too low. Directly added to the default value chosen by ActivityManager based on screen size and total memory for the largest lowmemorykiller bucket, and scaled proportionally to the smaller buckets. 0 keeps the default. --><br />
- <integer name="config_lowMemoryKillerMinFreeKbytesAdjust">0</integer></code></p>
+
+<pre>
+<!-- Device configuration setting the minfree tunable in the lowmemorykiller
+in the kernel. A high value will cause the lowmemorykiller to fire earlier,
+keeping more memory in the file cache and preventing I/O thrashing, but
+allowing fewer processes to stay in memory. A low value will keep more
+processes in memory but may cause thrashing if set too low. Overrides the
+default value chosen by ActivityManager based on screen size and total memory
+for the largest lowmemorykiller bucket, and scaled proportionally to the
+smaller buckets. -1 keeps the default. -->
+<integer name="config_lowMemoryKillerMinFreeKbytesAbsolute">-1</integer>
+</pre>
+
+<pre>
+<!-- Device configuration adjusting the minfree tunable in the
+lowmemorykiller in the kernel. A high value will cause the lowmemorykiller to
+fire earlier, keeping more memory in the file cache and preventing I/O
+thrashing, but allowing fewer processes to stay in memory. A low value will
+keep more processes in memory but may cause thrashing if set too low. Directly
+added to the default value chosen by ActivityManager based on screen
+size and total memory for the largest lowmemorykiller bucket, and scaled
+proportionally to the smaller buckets. 0 keeps the default. -->
+<integer name="config_lowMemoryKillerMinFreeKbytesAdjust">0</integer>
+</pre>
+
<h3 id="ksm">KSM (Kernel samepage merging)</h3>
+<p>KSM is a kernel thread that runs in the background and compares pages in
+memory that have been marked <code>MADV_MERGEABLE</code> by user-space. If two pages are
+found to be the same, the KSM thread merges them back as a single
+copy-on-write page of memory.</p>
- <p>KSM is a kernel thread that runs in the background and compares pages in
- memory that have been marked <code>MADV_MERGEABLE</code> by user-space. If two pages are
- found to be the same, the KSM thread merges them back as a single
- copy-on-write page of memory.</p>
-
- <p>KSM will save memory over time on a running system, gaining memory duplication
- at a cost of CPU power, which could have an impact on battery life. You should
- measure whether the power tradeoff is worth the memory savings you get by
- enabling KSM.</p>
-
- <p>To test KSM, we recommend looking at long running devices (several hours) and
- seeing whether KSM makes any noticeable improvement on launch times and
- rendering times.</p>
-
-<p>To enable KSM, enable <code>CONFIG_KSM</code> in the kernel and then add the following lines to your` <code>init.<device>.rc</code> file:<br>
- <code>write /sys/kernel/mm/ksm/pages_to_scan 100<br>
- write /sys/kernel/mm/ksm/sleep_millisecs 500<br>
-write /sys/kernel/mm/ksm/run 1</code></p>
-<p>Once enabled, there are few utilities that will help in the debugging namely :
- procrank, librank, & ksminfo. These utilities allow you to see which KSM
- memory is mapped to what process, which processes use the most KSM memory.
- Once you have found a chunk of memory that looks worth exploring you can use
- either the hat utility if it's a duplicate object on the dalvik heap. </p>
+<p>KSM will save memory over time on a running system, gaining memory duplication
+at a cost of CPU power, which could have an impact on battery life. You should
+measure whether the power tradeoff is worth the memory savings you get by
+enabling KSM.</p>
+
+<p>To test KSM, we recommend looking at long running devices (several hours) and
+seeing whether KSM makes any noticeable improvement on launch times and
+rendering times.</p>
+
+<p>To enable KSM, enable <code>CONFIG_KSM</code> in the kernel and then add the
+following lines to your` <code>init.<device>.rc</code> file:<br>
+
+<pre>
+write /sys/kernel/mm/ksm/pages_to_scan 100
+write /sys/kernel/mm/ksm/sleep_millisecs 500
+write /sys/kernel/mm/ksm/run 1
+</pre>
+
+<p>Once enabled, there are few utilities that will help in the debugging namely :
+procrank, librank, & ksminfo. These utilities allow you to see which KSM
+memory is mapped to what process, which processes use the most KSM memory.
+Once you have found a chunk of memory that looks worth exploring you can use
+either the hat utility if it's a duplicate object on the dalvik heap. </p>
+
<h3 id="zram">Swap to zRAM</h3>
+<p>zRAM swap can increase the amount of memory available in the system by
+compressing memory pages and putting them in a dynamically allocated swap area
+of memory.</p>
- <p>zRAM swap can increase the amount of memory available in the system by
- compressing memory pages and putting them in a dynamically allocated swap area
- of memory.</p>
-
- <p>Again, since this is trading off CPU time for a small increase in memory, you
- should be careful about measuring the performance impact zRAM swap has on your
- system.</p>
-
+<p>Again, since this is trading off CPU time for a small increase in memory, you
+should be careful about measuring the performance impact zRAM swap has on your
+system.</p>
<p>Android handles swap to zRAM at several levels:</p>
<ul>
- <li>First, the following kernel options must be enabled to use zRAM swap
+ <li>First, the following kernel options must be enabled to use zRAM swap
effectively:
<ul>
<li><code>CONFIG_SWAP</code></li>
@@ -210,11 +253,11 @@
<li>Then, you should add a line that looks like this to your fstab:<br />
<code>/dev/block/zram0 none swap defaults zramsize=<size in bytes>,swapprio=<swap partition priority></code><br />
<code><br />
- zramsize</code> is mandatory and indicates how much uncompressed memory you want
- the zram area to hold. Compression ratios in the 30-50% range are usually
+ zramsize</code> is mandatory and indicates how much uncompressed memory you want
+ the zram area to hold. Compression ratios in the 30-50% range are usually
observed.<br />
<br />
- <code>swapprio</code> is optional and not needed if you don't have more than one swap
+ <code>swapprio</code> is optional and not needed if you don't have more than one swap
area.<br />
<br />
You should also be sure to label the associated block device as a swap_block_device
@@ -223,43 +266,45 @@
<code>/dev/block/zram0 u:object_r:swap_block_device:s0</code><br />
<br />
</li>
- <li>By default, the Linux kernel swaps in 8 pages of memory at a time. When
- using ZRAM, the incremental cost of reading 1 page at a time is negligible
- and may help in case the device is under extreme memory pressure. To read
- only 1 page at a time, add the following to your init.rc:<br />
- `write /proc/sys/vm/page-cluster 0`</li>
- <li>In your init.rc, after the `mount_all /fstab.X` line, add:<br />
- `swapon_all /fstab.X`</li>
- <li>The memory cgroups are automatically configured at boot time if the
+ <li>By default, the Linux kernel swaps in 8 pages of memory at a time. When
+ using ZRAM, the incremental cost of reading 1 page at a time is negligible
+ and may help in case the device is under extreme memory pressure. To read
+ only 1 page at a time, add the following to your <code>init.rc</code>:<br />
+ <code>write /proc/sys/vm/page-cluster 0</code></li>
+ <li>In your <code>init.rc</code> after the <code>mount_all /fstab.X</code> line, add:<br />
+ <code>swapon_all /fstab.X</code></li>
+ <li>The memory cgroups are automatically configured at boot time if the
feature is enabled in kernel.</li>
- <li>If memory cgroups are available, the ActivityManager will mark lower
- priority threads as being more swappable than other threads. If memory is
- needed, the Android kernel will start migrating memory pages to zRAM swap,
- giving a higher priority to those memory pages that have been marked by
+ <li>If memory cgroups are available, the ActivityManager will mark lower
+ priority threads as being more swappable than other threads. If memory is
+ needed, the Android kernel will start migrating memory pages to zRAM swap,
+ giving a higher priority to those memory pages that have been marked by
ActivityManager. </li>
</ul>
+
<h3 id="carveouts">Carveouts, Ion and Contiguous Memory Allocation (CMA)</h3>
- <p>It is especially important on low memory devices to be mindful about
- carveouts, especially those that will not always be fully utilized -- for
- example a carveout for secure video playback. There are several solutions to
- minimizing the impact of your carveout regions that depend on the exact
- requirements of your hardware.</p>
- <p>If hardware permits discontiguous memory
- allocations, the ion system heap allows memory allocations from system memory,
- eliminating the need for a carveout. It also attempts to make large
- allocations to eliminate TLB pressure on peripherals. If memory regions must
- be contiguous or confined to a specific address range, the contiguous memory
- allocator (CMA) can be used.</p>
-<p>This creates a carveout that the system can also
- use of for movable pages. When the region is needed, movable pages will be
- migrated out of it, allowing the system to use a large carveout for other
- purposes when it is free. CMA can be used directly or more simply via ion by
- using the ion cma heap.</p>
+<p>It is especially important on low memory devices to be mindful about
+carveouts, especially those that will not always be fully utilized -- for
+example a carveout for secure video playback. There are several solutions to
+minimizing the impact of your carveout regions that depend on the exact
+requirements of your hardware.</p>
+
+<p>If hardware permits discontiguous memory allocations, the ion system heap
+allows memory allocations from system memory,
+eliminating the need for a carveout. It also attempts to make large
+allocations to eliminate TLB pressure on peripherals. If memory regions must
+be contiguous or confined to a specific address range, the contiguous memory
+allocator (CMA) can be used.</p>
+
+<p>This creates a carveout that the system can also use of for movable pages.
+When the region is needed, movable pages will be migrated out of it, allowing
+the system to use a large carveout for other purposes when it is free. CMA can
+be used directly or more simply via ion by using the ion cma heap.</p>
<h2 id="app-opts">Application optimization tips</h2>
<ul>
- <li>Review <a
+ <li>Review <a
href="http://developer.android.com/training/articles/memory.html">Managing your
App's Memory</a> and these past blog posts on the same topic:
<ul>
@@ -273,7 +318,7 @@
href="http://tools.android.com/recent/lintperformancechecks">http://tools.android.com/recent/lintperformancechecks</a></li>
</ul>
</li>
- <li>Check/remove any unused assets from preinstalled apps -
+ <li>Check/remove any unused assets from preinstalled apps -
development/tools/findunused (should help make the app smaller).</li>
<li>Use PNG format for assets, especially when they have transparent areas</li>
<li>If writing native code, use calloc() rather than malloc/memset</li>
@@ -289,73 +334,74 @@
<ul>
<li><p>SERVICE - SERVICE_RESTARTING<br/>
- Applications that are making themselves run in the background for their own
- reason. Most common problem apps have when they run in the background too
- much. %duration * pss is probably a good "badness" metric, although this set
- is so focused that just doing %duration is probably better to focus on the
+ Applications that are making themselves run in the background for their own
+ reason. Most common problem apps have when they run in the background too
+ much. %duration * pss is probably a good "badness" metric, although this set
+ is so focused that just doing %duration is probably better to focus on the
fact that we just don't want them running at all.</p></li>
<li><p>IMPORTANT_FOREGROUND - RECEIVER<br/>
- Applications running in the background (not directly interacting with the
- user) for any reason. These all add memory load to the system. In this case
- the (%duration * pss) badness value is probably the best ordering of such
- processes, because many of these will be always running for good reason, and
+ Applications running in the background (not directly interacting with the
+ user) for any reason. These all add memory load to the system. In this case
+ the (%duration * pss) badness value is probably the best ordering of such
+ processes, because many of these will be always running for good reason, and
their pss size then is very important as part of their memory load.</p></li>
<li><p>PERSISTENT<br/>
- Persistent system processes. Track pss to watch for these processes getting
+ Persistent system processes. Track pss to watch for these processes getting
too large.</p></li>
<li><p>TOP<br/>
- Process the user is currently interacting with. Again, pss is the important
+ Process the user is currently interacting with. Again, pss is the important
metric here, showing how much memory load the app is creating while in use.</p></li>
<li><p>HOME - CACHED_EMPTY<br/>
- All of these processes at the bottom are ones that the system is keeping
- around in case they are needed again; but they can be freely killed at any
- time and re-created if needed. These are the basis for how we compute the
- memory state -- normal, moderate, low, critical is based on how many of these
- processes the system can keep around. Again the key thing for these processes
- is the pss; these processes should try to get their memory footprint down as
- much as possible when they are in this state, to allow for the maximum total
- number of processes to be kept around. Generally a well behaved app will have
- a pss footprint that is significantly smaller when in this state than when
+ All of these processes at the bottom are ones that the system is keeping
+ around in case they are needed again; but they can be freely killed at any
+ time and re-created if needed. These are the basis for how we compute the
+ memory state -- normal, moderate, low, critical is based on how many of these
+ processes the system can keep around. Again the key thing for these processes
+ is the pss; these processes should try to get their memory footprint down as
+ much as possible when they are in this state, to allow for the maximum total
+ number of processes to be kept around. Generally a well behaved app will have
+ a pss footprint that is significantly smaller when in this state than when
TOP.</p></li>
<li>
<p>TOP vs. CACHED_ACTIVITY-CACHED_ACTIVITY_CLIENT<em><br/>
- </em>The difference in pss between when a process is TOP vs. when it is in either
- of these specific cached states is the best data for seeing how well it is
- releasing memory when going into the background. Excluding CACHED_EMPTY state
- makes this data better, since it removes situations when the process has
- started for some reasons besides doing UI and so will not have to deal with
+ </em>The difference in pss between when a process is TOP vs. when it is in either
+ of these specific cached states is the best data for seeing how well it is
+ releasing memory when going into the background. Excluding CACHED_EMPTY state
+ makes this data better, since it removes situations when the process has
+ started for some reasons besides doing UI and so will not have to deal with
all of the UI overhead it gets when interacting with the user.</p></li>
</ul>
-
<h2 id="analysis">Analysis</h2>
+
<h3 id="app-startup">Analyzing app startup time</h3>
+<p>Use <code>$ adb shell am start</code> with the <code>-P</code> or
+<code>--start-profiler</code> option to run the profiler when your app starts.
+This will start the profiler almost immediately after your process is forked
+from zygote, before any of your code is loaded into it.</p>
- <p>Use "<code>adb shell am start</code>" with the <code>-P</code> or <code>--start-profiler</code> option to run
- the profiler when your app starts. This will start the profiler almost
- immediately after your process is forked from zygote, before any of your code
-is loaded into it.</p>
<h3 id="bug-reports">Analyze using bugreports </h3>
+<p>Now contains various information that can be used for debugging. The
+services include <code>batterystats</code>, <code>netstats</code>,
+<code>procstats</code>, and <code>usagestats</code>. You can find them with
+lines like this:</p>
- <p>Now contains various information that can be used for debugging. The services
- include <code>batterystats</code>, <code>netstats</code>, <code>procstats</code>, and <code>usagestats</code>. You can
- find them with lines like this:</p>
-
-
-<pre>------ CHECKIN BATTERYSTATS (dumpsys batterystats --checkin) ------
+<pre>
+------ CHECKIN BATTERYSTATS (dumpsys batterystats --checkin) ------
7,0,h,-2558644,97,1946288161,3,2,0,340,4183
7,0,h,-2553041,97,1946288161,3,2,0,340,4183
</pre>
+
<h3 id="persistent">Check for any persistent processes</h3>
-
- <p>Reboot the device and check the processes.<br/>
- Run for a few hours and check the processes again. There should not be any
+<p>Reboot the device and check the processes.<br/>
+Run for a few hours and check the processes again. There should not be any
long running processes.</p>
+
<h3 id="longevity">Run longevity tests</h3>
-
- <p>Run for longer durations and track the memory of the process. Does it
- increase? Does it stay constant? Create Canonical use cases and run longevity tests on these scenarios</p>
+<p>Run for longer durations and track the memory of the process. Does it
+increase? Does it stay constant? Create Canonical use cases and run longevity
+tests on these scenarios</p>
diff --git a/src/index.jd b/src/index.jd
index 5eb740d..4ede719 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -43,6 +43,26 @@
<div class="landing-docs">
<div class="col-8">
<h3>What's New</h3>
+<a href="{@docRoot}security/bulletin/index.html">
+ <h4>Security Bulletins</h4></a>
+ <p>The Android security team now publishes monthly <strong><a
+ href="{@docRoot}security/bulletin/index.html">Nexus Security
+ Bulletins</a></strong> describing key vulnerabilities fixed in AOSP
+ with links to associated changes.</p>
+
+<a href="{@docRoot}source/build-numbers.html">
+ <h4>Lollipop and Marshmallow Build Numbers</h4></a>
+ <p>New <strong><a
+ href="{@docRoot}source/build-numbers.html#source-code-tags-and-builds">Build Numbers</a></strong>
+ have been published for Lollipop on Nexus 6, Nexus 7 (deb), Nexus 9
+ (volantisg), Nexus 10 and Marshmallow on Nexus 5, Nexus 5X, Nexus 6, Nexus 6P,
+ Nexus 7 (flo/deb), Nexus 9 (volantis/volantisg), and Nexus Player.</p>
+
+<a href="{@docRoot}compatibility/downloads.html">
+ <h4>6.0 CTS Downloads</h4></a>
+ <p>Android 6.0 R2 Compatibility Test Suite (CTS) and CTS Verifier are available for <strong><a
+ href="{@docRoot}compatibility/downloads.html#android-60">Download</a></strong>.</p>
+
<a href="{@docRoot}source/community.html">
<h4>Android Resources</h4></a>
<p>Android Community now includes a collection of <strong><a
@@ -71,34 +91,6 @@
Networking Unit Tests</a></strong> describe a suite of tests provided by
Android engineering to help ensure the device kernel will properly
support the Android networking stack.</p>
-
-<a href="{@docRoot}security/verifiedboot/verified-boot.html">
- <h4>Logging Mode Optional When Verifying Boot</h4></a>
- <p><strong><a
- href="{@docRoot}security/verifiedboot/verified-boot.html#boot_partition">Verifying
- Boot</a></strong> now makes it clear logging mode does not have to be
- implemented, and dm-verity may be kept in enforcing mode.</p>
-
-<a href="{@docRoot}compatibility/cts/setup.html">
- <h4>Bluetooth LE Beacons CTS Guidance</h4></a>
- <p><strong><a
- href="{@docRoot}compatibility/cts/setup.html#ble_beacons">Bluetooth LE
- beacons</a></strong> can be used to test the compatibility of Bluetooth low
- energy features on Android devices.</p>
-
-<a href="{@docRoot}devices/audio/index.html">
- <h4>Audio Data Formats, MIDI Architecture, Related Updates</h4></a>
- <p>New information is available about <strong><a
- href="{@docRoot}devices/audio/data_formats.html">Audio Data Formats</a></strong>
- and the <strong><a
- href="{@docRoot}devices/audio/midi_arch.html">MIDI Architecture</a></strong>.
- Also updated are <strong><a
- href="{@docRoot}devices/audio/latency_measurements.html">Latency Measurements</a></strong>
- and <strong><a
- href="{@docRoot}devices/audio/terminology.html">Audio Terminology</a></strong>.
- It also is noted that Android indirectly <strong><a
- href="{@docRoot}devices/audio/midi.html#for-android">supports MIDI 1.0 via
- an external adapter</a></strong>.</p>
</div>
<div class="col-8">
diff --git a/src/security/bulletin/2015-11-01.jd b/src/security/bulletin/2015-11-01.jd
index 9f09262..0cbada2 100644
--- a/src/security/bulletin/2015-11-01.jd
+++ b/src/security/bulletin/2015-11-01.jd
@@ -140,6 +140,8 @@
<li> Natalie Silvanovich of Google Project Zero: CVE-2015-6608
<li> Qidan He (@flanker_hqd) and Wen Xu (@antlr7) from KeenTeam (@K33nTeam,
http://k33nteam.org/): CVE-2015-6612
+ <li> Guang Gong (龚广) (<a href="https://twitter.com/oldfresher">@oldfresher</a>, higongguang@gmail.com) of <a href="http://www.360.cn">Qihoo 360 Technology CC
+o.Ltd</a>: CVE-2015-6612
<li> Seven Shen of Trend Micro: CVE-2015-6610
</ul>
diff --git a/src/security/images/access-to-keymaster.png b/src/security/images/access-to-keymaster.png
index 611f8e3..5f27a31 100644
--- a/src/security/images/access-to-keymaster.png
+++ b/src/security/images/access-to-keymaster.png
Binary files differ
diff --git a/src/security/keystore/features.jd b/src/security/keystore/features.jd
index 7feae91..7d00ebb 100644
--- a/src/security/keystore/features.jd
+++ b/src/security/keystore/features.jd
@@ -24,11 +24,12 @@
</div>
</div>
-<p>This page contains information about the features of <a href="index.html">Keymaster</a> 1.0.</p>
+<p>This page contains information about the features of <a href="index.html">Keystore</a>
+in Android 6.0.</p>
<h2 id=cryptographic_primitives>Cryptographic primitives</h2>
-<p>The <code>libkeymaster</code> library and Keymaster provide the following categories of operations:</p>
+<p>Keystore provides the following categories of operations:</p>
<ul>
<li>Key generation
@@ -42,11 +43,6 @@
<li>Generation and verification of symmetric message authentication codes
</ul>
-<p>Within each category, <code>libkeymaster</code> provides a mechanism for
-discovering the available options (algorithms,
-modes, etc.). But we also specify at least one required option, to ensure that
-client software can depend on the presence of the required primitives.</p>
-
<p>Protocol elements, such as purpose, mode and padding, as well
as <a href="#key_access_control">access control constraints</a>,
must be specified when keys are generated or imported and are permanently
@@ -80,10 +76,10 @@
</ul>
<li>Required padding modes for RSA encryption/decryption are:
<ul>
+ <li>Unpadded
<li>RSAES-OAEP (<code>KM_PAD_RSA_OAEP</code>)
<li>RSAES-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code>)
</ul>
- <li>Unpadded RSA encryption must not be supported
</ul>
<li><a href="http://en.wikipedia.org/wiki/Elliptic_Curve_DSA">ECDSA</a>
<ul>
@@ -125,17 +121,19 @@
<p>Hardware-based keys that can never be extracted from the device don't provide
much security if an attacker can use them at will (though they're more secure
-than keys which <em>can</em> be exfiltrated). Thus, it's crucial that Keymaster enforce access controls.</p>
+than keys which <em>can</em> be exfiltrated). Thus, it's crucial that Keystore
+enforce access controls.</p>
<p>Access controls are defined as an "authorization list" of tag/value pairs.
Authorization tags are 32-bit integers and the values are a variety of types.
Some tags may be repeated to specify multiple values. Whether a tag may be
repeated is specified in the documentation for the tag. When a key is created,
-the caller specifies an authorization list. The Keymaster implementation will
-modify the list to specify some additional information, such as whether the key
-has rollback protection, and return a "final" authorization list, encoded into
-the returned key blob. Any attempt to use the key for any cryptographic
-operation must fail if the final authorization list is modified.</p>
+the caller specifies an authorization list. The Keymaster implementation
+underlying Keystore will modify the list to specify some additional information,
+such as whether the key has rollback protection, and return a "final"
+authorization list, encoded into the returned key blob. Any attempt to use the
+key for any cryptographic operation must fail if the final authorization list is
+modified.</p>
<p>The set of possible tags is defined in the enumeration <code>keymaster_authorization_tag_t</code> and
the set must be permanently fixed (though it can be extended).
@@ -176,42 +174,46 @@
<h3 id=hardware_vs_software_enforcement>Hardware vs. software enforcement</h3>
-<p>Not all Keymaster implementations will implement the same features. To support
-a variety of approaches, Keymaster 1.0 distinguishes between secure and
-non-secure world access control enforcement, which we call hardware and
-software enforcement, respectively.</p>
+<p>Not all secure hardware will implement the same features. To support a
+variety of approaches, Keymaster 1.0 distinguishes between secure and non-secure
+world access control enforcement, which we call hardware and software
+enforcement, respectively.</p>
<p>Implementations are required to:</p>
<ul>
- <li>Enforce exact matching (not enforcement) of all authorizations. Authorization
-lists in key blobs must exactly match the authorizations returned during key
-generation, including ordering. Any mismatch must cause an error diagnostic.
+
+ <li>Enforce exact matching (not enforcement) of all authorizations.
+ Authorization lists in key blobs must exactly match the authorizations
+ returned during key generation, including ordering. Any mismatch must cause an
+ error diagnostic.
+
<li>Declare the authorizations whose semantic values are enforced.
+
</ul>
-<p>The API mechanism for declaring hardware-enforced authorizations is in
-the <code>keymaster_key_characteristics_t</code> structure. It divides the authorization
-list into two sub-lists, <code>hw_enforced</code> and <code>sw_enforced</code>. The
-Keymaster implementation is responsible for placing the appropriate
-values in each, based on what it can enforce.</p>
+<p>The API mechanism for declaring hardware-enforced authorizations is in the
+<code>keymaster_key_characteristics_t</code> structure. It divides the
+authorization list into two sub-lists, <code>hw_enforced</code> and
+<code>sw_enforced</code>. The secure hardware is responsible for placing the
+appropriate values in each, based on what it can enforce.</p>
-<p>In addition, the keystore daemon will implement software-based enforcement of <em>all</em> authorizations,
-whether they're enforced in hardware or not.</p>
+<p>In addition, Keystore implements software-based enforcement of <em>all</em>
+authorizations, whether they're enforced by the secure hardware or not.</p>
<p>For example, consider a TrustZone-based implementation that does not support
key expiration. A key with an expiration date may still be created. That key's
-authorization list will include the tag <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> with
-the expiration date. A request to Keymaster for the key characteristics
-will find this tag in the <code>sw_enforced</code> list and the Keymaster implementation will
-not enforce the expiration
-requirement. However, attempts to use the key after expiration will be rejected
-by the keystore daemon.</p>
+authorization list will include the tag
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> with the expiration date. A
+request to Keystore for the key characteristics will find this tag in the
+<code>sw_enforced</code> list and the secure hardware will not enforce the
+expiration requirement. However, attempts to use the key after expiration will
+be rejected by Keystore.</p>
-<p>If the device is then upgraded with a Keymaster implementation that does
-support expiration, then a request for key characteristics will
-find <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> in
-the <code>hw_enforced</code> list, and attempts to use the key after expiration will fail even if the
+<p>If the device is then upgraded with secure hardware that does support
+expiration, then a request for key characteristics will find
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> in the <code>hw_enforced</code>
+list, and attempts to use the key after expiration will fail even if the
keystore is somehow subverted or bypassed.</p>
<h3 id=cryptographic_message_construction_authorizations>Cryptographic message construction authorizations</h3>
@@ -241,15 +243,6 @@
encrypt and to sign allows an attacker who can convince the system to decrypt
arbitrary data to generate signatures.</p>
-<p>Other purposes for keys that may be added in the future include:</p>
-
-<ul>
- <li>"Derive Key" purpose, for key derivation keys
- <li>"Attest" purpose, for keys that can generate attestations of the Keymaster
-implementation and/or its environment
- <li>"Wrap Key" purpose, for keys used to wrap keys for secure import or export
-</ul>
-
<h3 id=import_and_export>Import and export</h3>
<p>Keymaster supports export of public keys only, in X.509 format, and import of:</p>
@@ -260,8 +253,6 @@
<li>Symmetric keys as raw bytes
</ul>
-<p>Future versions will likely expand the import/export options.</p>
-
<p>To ensure that imported keys can be distinguished from securely-generated
keys, <code>KM_TAG_ORIGIN</code> is included in the appropriate key
authorization list. For example, if a key
@@ -273,9 +264,9 @@
<h3 id=user_authentication>User authentication</h3>
-<p>Keymaster does not implement user authentication, but depends on other trusted
-apps which do. For the interface that must be implemented by these apps, see
-the Gatekeeper page.</p>
+<p>Secure Keymaster implementations do not implement user authentication, but
+depend on other trusted apps which do. For the interface that must be
+implemented by these apps, see the Gatekeeper page.</p>
<p>User authentication requirements are specified via two sets of tags. The first
set indicate which user can use the key:</p>
@@ -313,24 +304,29 @@
<h3 id=client_binding>Client binding</h3>
-<p>Client binding, the association of a key with a particular client application,
-is done via an optional client ID and some optional client data (<code>KM_TAG_APPLICATION_ID</code>
-and <code>KM_TAG_APPLICATION_DATA</code>, respectively). Keymaster treats these values as opaque blobs,
-only ensuring
-that the same blobs presented during key generation/import are presented for
-every use and are byte-for-byte identical. The client binding data is not
-returned by Keymaster. The caller must know it in order to use the key.</p>
+<p>Client binding, the association of a key with a particular client
+application, is done via an optional client ID and some optional client data
+(<code>KM_TAG_APPLICATION_ID</code> and <code>KM_TAG_APPLICATION_DATA</code>,
+respectively). Keystore treats these values as opaque blobs, only ensuring that
+the same blobs presented during key generation/import are presented for every
+use and are byte-for-byte identical. The client binding data is not returned by
+Keymaster. The caller must know it in order to use the key.</p>
+
+<p>This feature is not exposed to applications.
<h3 id=expiration>Expiration</h3>
-<p>Keymaster supports restricting key usage by date. Key start of validity and key
-expirations can be associated with a key and Keymaster will refuse to perform
-key operations if the current date/time is outside of the valid range. The key
-validity range is specified with the tags <code>KM_TAG_ACTIVE_DATETIME</code>,
-<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>, and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code>.
-The distinction between "origination" and "usage" is based on whether the key
-is being used to "originate" a new ciphertext/signature/etc., or to "use" an
-existing ciphertext/signature/etc.</p>
+<p>Keystore supports restricting key usage by date. Key start of validity and
+key expirations can be associated with a key and Keymaster will refuse to
+perform key operations if the current date/time is outside of the valid
+range. The key validity range is specified with the tags
+<code>KM_TAG_ACTIVE_DATETIME</code>,
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>, and
+<code>KM_TAG_USAGE_EXPIRE_DATETIME</code>. The distinction between
+"origination" and "usage" is based on whether the key is being used to
+"originate" a new ciphertext/signature/etc., or to "use" an existing
+ciphertext/signature/etc. Note that this distinction is not exposed to
+applications.</p>
<p>The <code>KM_TAG_ACTIVE_DATETIME</code>, <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>,
and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code> tags are optional. If the tags are absent, it is
@@ -345,37 +341,38 @@
<h3 id=root_of_trust_binding>Root of trust binding</h3>
-<p>Keymaster allows keys to be bound to a root of trust, which is a bitstring
-provided to Keymaster during startup, preferably by the bootloader. If
-provided, this bitstring must be cryptographically bound to every key managed
+<p>Keystore requires keys to be bound to a root of trust, which is a bitstring
+provided to the Keymaster secure hardware during startup, preferably by the
+bootloader. This bitstring must be cryptographically bound to every key managed
by Keymaster.</p>
-<p>The intent is for the bootloader to pass in the public key, used to verify the
-signature on the boot image, along with the verified boot state (locked or
-unlocked). If the public key is changed to allow a different system image to be
-used or if the verified boot state is changed, then none of the
-Keymaster-protected keys created by the previous system will be usable, unless
-the previous root of trust is restored and a system that is signed by that key
-is booted. The goal is to increase the value of the software-enforced key
-access controls by making it imposSTEM</code>sible for an attacker-installed operating
-system to use Keymaster keys.</p>
+<p>The root of trust consists of the public key used to verify the signature on
+the boot image and the lock state of the device. If the public key is changed to
+allow a different system image to be used or if the lock state is changed, then
+none of the Keymaster-protected keys created by the previous system will be
+usable, unless the previous root of trust is restored and a system that is
+signed by that key is booted. The goal is to increase the value of the
+software-enforced key access controls by making it impossible for an
+attacker-installed operating system to use Keymaster keys.</p>
<h3 id=standalone_keys>Standalone keys</h3>
-<p>Some Keymaster implementations may choose to store key material internally and
-return handles rather than encrypted key material. Or there may be other cases
-in which keys cannot be used until some other non-secure or secure world system
-component is available. The Keymaster 1.0 API allows the caller to request that
-a key be "standalone," via the <code>KM_TAG_STANDALONE</code> tag,
-meaning that no resources other than the blob and the running Keymaster
-system are required. The tags associated with a key may be inspected to see
-whether a key is standalone. At present, only two values are defined:</p>
+<p>Some Keymaster secure hardware may choose to store key material internally
+and return handles rather than encrypted key material. Or there may be other
+cases in which keys cannot be used until some other non-secure or secure world
+system component is available. The Keymaster 1.0 HAL allows the caller to
+request that a key be "standalone," via the <code>KM_TAG_STANDALONE</code> tag,
+meaning that no resources other than the blob and the running Keymaster system
+are required. The tags associated with a key may be inspected to see whether a
+key is standalone. At present, only two values are defined:</p>
<ul>
<li><code>KM_BLOB_STANDALONE</code>
<li><code>KM_BLOB_REQUIRES_FILE_SYSTEM</code>
</ul>
+<p>This feature is not exposed to applications.
+
<h3 id=velocity>Velocity</h3>
<p>When it's created, the maximum usage velocity can be specified
@@ -387,26 +384,32 @@
<p>The simple approach to implementing velocity limits is a table of key IDs and
last-use timestamps. This table will likely be of limited size, but must
accommodate at least 16 entries. In the event that the table is full and no
-entries may be updated or discarded, Keymaster implementations must "fail
-safe," preferring to refuse all velocity-limited key operations until one of
-the entries expires. It is acceptable for all entries to expire upon reboot.</p>
+entries may be updated or discarded, secure hardware implementations must "fail
+safe," preferring to refuse all velocity-limited key operations until one of the
+entries expires. It is acceptable for all entries to expire upon reboot.</p>
-<p>Keys can also be limited to <em>n</em> uses per boot with <code>KM_TAG_USES_PER_BOOT</code>.
-This also requires a tracking table, which must accommodate at least four
-keys, and must also fail safe. Note that applications will be unable to create
-per-boot limited keys. This feature will not be exposed through keystore and
-will be reserved for system operations.</p>
+<p>Keys can also be limited to <em>n</em> uses per boot with
+<code>KM_TAG_MAX_USES_PER_BOOT</code>. This also requires a tracking table,
+which must accommodate at least four keys, and must also fail safe. Note that
+applications will be unable to create per-boot limited keys. This feature will
+not be exposed through Keystore and will be reserved for system operations.</p>
+
+<p>This feature is not exposed to applications.</p>
<h3 id=random_number_generator_re-seeding>Random number generator re-seeding</h3>
-<p>Because Keymaster must generate random numbers for key material and
+<p>Because secure hardware must generate random numbers for key material and
Initialization Vectors (IVs), and because hardware random number generators may
-not always be fully trustworthy, Keymaster provides an interface to allow the
-client to provide additional entropy which will be mixed into the random
-numbers generated.</p>
+not always be fully trustworthy, the Keymaster HAL provides an interface to
+allow the client to provide additional entropy which will be mixed into the
+random numbers generated.</p>
-<p>A hardware random-number generator should be used as the primary seed source,
-if available, and the seed data provided through the external API must not be
-the sole source of randomness used for number generation. Further, the mixing
-operation used must ensure that the random output is unpredictable if any one
-of the seed sources is unpredictable.</p>
+<p>A hardware random-number generator must be used as the primary seed source,
+and the seed data provided through the external API must not be the sole source
+of randomness used for number generation. Further, the mixing operation used
+must ensure that the random output is unpredictable if any one of the seed
+sources is unpredictable.</p>
+
+<p>This feature is not exposed to applications but is used by the framework,
+which regularly provides additional entropy, retrieved from a Java SecureRandom
+instance, to the secure hardware.
diff --git a/src/security/keystore/implementer-ref.jd b/src/security/keystore/implementer-ref.jd
index ba8c45a..7375651 100644
--- a/src/security/keystore/implementer-ref.jd
+++ b/src/security/keystore/implementer-ref.jd
@@ -18,7 +18,7 @@
-->
<p>This page provides details to assist implementers of <a href="index.html">Keymaster</a> HALs. It
-covers each tag and each function in the API.</p>
+covers each tag and each function in the HAL.</p>
<h2 id=authorization_tags>Authorization tags</h2>
@@ -341,7 +341,13 @@
<h3 id=km_tag_user_auth_type>KM_TAG_USER_AUTH_TYPE</h3>
<p>Specifies the types of user authenticators that may be used to authorize this
-key.</p>
+key. When Keymaster is requested to perform an operation with a key with this
+tag, it must receive an authentication token, and the token's
+<code>authenticator_type</code> field must match the value in the tag. To be
+precise, it must be true that <code>(ntoh(token.authenticator_type) &
+auth_type_tag_value) != 0, where <code>ntoh</code> is a function that converts
+network-ordered integers to host-ordered integers and
+<code>auth_type_tag_value</code> is the value of this tag.</p>
<p>The value is a 32-bit integer bitmask of values from the enumeration:</p>
@@ -388,6 +394,11 @@
same associated data as part of the <code>in_params</code> set. If the correct
data is not provided the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+<p>The content of this tag must be bound to the key <i>cryptographically</i>,
+meaning it must not be possible for an adversary who has access to all of the
+secure world secrets but does not have access to the tag content to decrypt the
+key (without brute-forcing the tag content).</p>
+
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<p>This tag is not repeatable.</p>
@@ -403,6 +414,14 @@
data as part of the <code>in_params</code> set. If the correct data is not
provided, the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+<p>The content of this tag must be bound to the key <i>cryptographically</i>,
+meaning it must not be possible for an adversary who has access to all of the
+secure world secrets but does not have access to the tag content to decrypt the
+key (without brute-forcing the tag content, which applications can prevent by
+specifying sufficiently high-entropy content).</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes.</p>
+
<p>This tag is not repeatable.</p>
<h3 id=km_tag_creation_datetime>KM_TAG_CREATION_DATETIME</h3>
@@ -911,11 +930,26 @@
<p>Begins a cryptographic operation, using the specified key, for the specified
purpose, with the specified parameters (as appropriate), and returns an
-operation handle which is used with <a href="#update">update</a> and <a href="#finish">finish</a> to complete the operation.</p>
+operation handle which is used with <a href="#update">update</a> and <a
+href="#finish">finish</a> to complete the operation. The operation handle is
+also used as the "challenge" token in authenticated operations, and for such
+operations must be included in the <code>challenge</code> field of the
+authentication token.</p>
-<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>
-were specified during key generation or import, calls to begin must include
-those tags with the originally-specified values in the <code>in_params</code> argument to this method.</p>
+<p>A Keymaster implementation must support at least 16 concurrent
+operations. Keystore will use up to 15, leaving one for vold to use for password
+encryption. When Keystore has 15 operations in progress (<code>begin</code> has
+been called, but <code>finish</code> or <code>abort</code> have not yet been
+called) and it receives a request to begin a 16th, it will call
+<code>abort</code> on the least-recently used operation to reduce the number of
+active operations to 14 before calling <code>begin</code> to start the
+newly-requested operation.
+
+<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a
+href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a> were specified
+during key generation or import, calls to <code>begin</code> must include those
+tags with the originally-specified values in the <code>in_params</code> argument
+to this method.</p>
<h4 id=authorization_enforcement>Authorization enforcement</h4>
@@ -998,18 +1032,34 @@
<p>There are some important interactions between padding modes and digests:</p>
<ul>
- <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be performed. If signing or
-verifying, <code>KM_DIGEST_NONE </code>must be specified for the digest. No digest is required for unpadded encryption
-or decryption.
- <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest, which may be <code>KM_DIGEST_NONE.</code>
+
+ <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be
+ performed. If signing or verifying, <code>KM_DIGEST_NONE</code> must be
+ specified for the digest. No digest is required for unpadded encryption or
+ decryption.
+
+ <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest. The
+ digest may be <code>KM_DIGEST_NONE</code>, in which case the Keymaster
+ implementation cannot build a proper PKCS#1 v1.5 signature structure, because
+ it cannot add the DigestInfo structure. Instead, the implementation must
+ construct <code>0x00 || 0x01 || PS || 0x00 || M</code>, where M is the
+ provided message and PS is the padding string. The size of the RSA key must be
+ at least 11 bytes larger than the message, otherwise the method must return
+ <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.
+
<li><code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> padding does not require a digest.
- <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
- If <code>KM_DIGEST_NONE</code> is specified, the method must return
- <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>. In addition, the
- size of the RSA key must be at least 22 bytes larger than
-the output size of the digest. Otherwise, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
- <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
- If <code>KM_DIGEST_NONE</code> is specified, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+
+ <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be
+ <code>KM_DIGEST_NONE</code>. If <code>KM_DIGEST_NONE</code> is specified, the
+ method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>. In addition, the
+ size of the RSA key must be at least 22 bytes larger than the output size of
+ the digest. Otherwise, the method must return
+ <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+
+ <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be
+ <code>KM_DIGEST_NONE</code>. If <code>KM_DIGEST_NONE</code> is specified, the
+ method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+
</ul>
<h4 id=ec_keys>EC keys</h4>
diff --git a/src/security/keystore/index.jd b/src/security/keystore/index.jd
index e86f253..d05d3f8 100644
--- a/src/security/keystore/index.jd
+++ b/src/security/keystore/index.jd
@@ -29,32 +29,31 @@
security services to the Android OS, to platform services, and even to
third-party apps.</p>
-<p>Keymaster has been <a href="features.html">significantly enhanced</a>
-in Android 6.0 with the addition of symmetric cryptographic primitives,
-AES and HMAC, and the addition of an access control
-system for hardware-backed keys. Access controls are specified during key
-generation and enforced for the lifetime of the key. Keys can be restricted to
-be usable only after the user has authenticated, only at a specific usage
-velocity, and only for specified purposes or with specified cryptographic
-parameters. For more information, please see
-the <a href="implementer-ref.html">Implementer's Reference</a>.</p>
+<p>Keystore has been <a href="features.html">significantly enhanced</a> in
+Android 6.0 with the addition of symmetric cryptographic primitives, AES and
+HMAC, and the addition of an access control system for hardware-backed
+keys. Access controls are specified during key generation and enforced for the
+lifetime of the key. Keys can be restricted to be usable only after the user has
+authenticated, and only for specified purposes or with specified cryptographic
+parameters. For more information, please see the <a
+href="implementer-ref.html">Implementer's Reference</a>.</p>
-<p>Before Keymaster 1.0, Android already had a simple, hardware-backed crypto
-services API: Keymaster versions 0.2 and 0.3, which provided only digital
-signing and verification operations, plus generation of
-asymmetric signing key pairs. This is already
-implemented on many devices, but there are many security goals that cannot
-easily be achieved with only a signature API. The intent of Keymaster 1.0 is to
-extend the Keymaster API to provide a broader range of capabilities.</p>
+<p>Before Android 6.0, Android already had a simple, hardware-backed crypto
+services API, provided by versions 0.2 and 0.3 of the Keymaster Hardware
+Abstraction Layer (HAL). Keystore provided digital signing and verification
+operations, plus generation and import of asymmetric signing key pairs. This is
+already implemented on many devices, but there are many security goals that
+cannot easily be achieved with only a signature API. Keystore in Android 6.0
+extends the Keystore API to provide a broader range of capabilities.</p>
<h2 id=goals>Goals</h2>
-<p>The goal of the Keymaster API is to provide a basic but adequate set of
-cryptographic primitives to allow the implementation of protocols using
-access-controlled, hardware-backed keys.</p>
+<p>The goal of the Android 6.0 Keystore API and the underlying Keymaster 1.0 HAL
+is to provide a basic but adequate set of cryptographic primitives to allow the
+implementation of protocols using access-controlled, hardware-backed keys.</p>
-<p>In addition to expanding the range of cryptographic primitives, Keymaster v1.0
-adds the following:</p>
+<p>In addition to expanding the range of cryptographic primitives, Keystore in
+Android 6.0 adds the following:</p>
<ul>
<li>A usage control scheme to allow key usage to be limited, to mitigate the risk
@@ -65,36 +64,37 @@
<h2 id=architecture>Architecture</h2>
-<p>The Keymaster API is a Hardware Abstraction Layer module, which is a
-dynamically-loaded library. Implementations must not
-perform any sensitive operations in user space, or even in kernel space.
-Sensitive operations are delegated to a secure processor reached through some
-kernel interface. The resulting architecture looks something like the
-following:</p>
+<p>The Keymaster HAL is an OEM-provided, dynamically-loadable library used by the
+Keystore service to provide hardware-backed cryptographic services. HAL
+implementations must not perform any sensitive operations in user space, or even
+in kernel space. Sensitive operations are delegated to a secure processor
+reached through some kernel interface. The resulting architecture looks
+like the following:</p>
-<img src="../images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" />
+<div align="center">
+ <img src="../images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" />
+</div>
<p class="img-caption"><strong>Figure 1.</strong> Access to Keymaster</p>
-<p>Within an Android device, the "client" actually consists of multiple layers
-(e.g. app, framework, keystore daemon), but that can be ignored for the
-purposes of this document. This means that the described API is low-level, used
-by platform-internal components, and not exposed to app developers. The
-higher-level API, for API level 23, is described on
-the <a href="http://developer.android.com/reference/java/security/KeyStore.html">Android Developer site</a>.</p>
+<p>Within an Android device, the "client" of the Keymaster HAL consists of
+multiple layers (e.g. app, framework, Keystore daemon), but that can be ignored
+for the purposes of this document. This means that the described Keymaster HAL
+API is low-level, used by platform-internal components, and not exposed to app
+developers. The higher-level API, for API level 23, is described on the <a
+href="http://developer.android.com/reference/java/security/KeyStore.html">Android
+Developer site</a>.</p>
-<p>The purpose of the <code>libkeymaster</code> library is not to implement the
-security-sensitive algorithms but only to
-marshal and unmarshal requests to the secure world. The wire format is
-implementation-defined.</p>
+<p>The purpose of the Keymaster HAL is not to implement the security-sensitive
+algorithms but only to marshal and unmarshal requests to the secure world. The
+wire format is implementation-defined.</p>
<h2 id=compatibility_with_previous_versions>Compatibility with previous versions</h2>
-<p>The Keymaster v1.0 API is completely incompatible with the previously-released
-APIs, e.g. Keymaster v0.2 and v0.3.
-To facilitate interoperability on pre-Marshmallow devices that launched
-with the older Keymaster APIs, Keystore provides an adapter that provides
-the 1.0 API implemented with calls to the existing hardware library. The result
-cannot provide the full range of functionality in the
-1.0 API. In particular, it will only support RSA and ECDSA algorithms, and all
-of the key authorization enforcement will be performed by the adapter, in the
-non-secure world.</p>
+<p>The Keymaster v1.0 HAL is completely incompatible with the
+previously-released HALs, e.g. Keymaster v0.2 and v0.3. To facilitate
+interoperability on pre-Marshmallow devices that launched with the older
+Keymaster HALs, Keystore provides an adapter that implements the 1.0 HAL with
+calls to the existing hardware library. The result cannot provide the full range
+of functionality in the 1.0 HAL. In particular, it will only support RSA and
+ECDSA algorithms, and all of the key authorization enforcement will be performed
+by the adapter, in the non-secure world.</p>
\ No newline at end of file
diff --git a/src/source/build-numbers.jd b/src/source/build-numbers.jd
index f0e661b..6842771 100644
--- a/src/source/build-numbers.jd
+++ b/src/source/build-numbers.jd
@@ -237,6 +237,18 @@
<td>Nexus 6P</td>
</tr>
<tr>
+ <td>MRA59B</td>
+ <td>android-6.0.0_r7</td>
+ <td>Marshmallow</td>
+ <td>Nexus 7 (deb)</td>
+</tr>
+<tr>
+ <td>MRA58X</td>
+ <td>android-6.0.0_r6</td>
+ <td>Marshmallow</td>
+ <td>Nexus 6</td>
+</tr>
+<tr>
<td>MRA58V</td>
<td>android-6.0.0_r5</td>
<td>Marshmallow</td>
