README
1The tools in this directory are a scheme for autogenerating crypto doc support.
2
3The central file is data/crypto_support.json, which is a JSON file that contains
4the supported API levels for each crypto algorithm that has ever been supported
5by Android. The categories are identified as described in the JCA.
6
7Each algorithm has up to three properties:
8
9name - The name of the algorithm. These are currently normalized to
10all-uppercase versions, but this produces substandard results in some cases
11(eg, PBEWITHHMACSHA versus PBEWithHmacSHA), so it could be improved.
12
13supported_api_levels: The set of Android API levels that this algorithm was/is
14supported for. It should be a sequence of zero or more "N" values or "N-M"
15ranges separated by commas followed by a "N+" value if the algorithm is
16currently supported. For example: "17+", "1-8,22+", "1-10,15,22-24".
17
18deprecated: Whether the algorithm is unsupported at the current API level. This
19is equivalent to supported_api_levels.endswith('+'), but is included for
20clarity's sake.
21
22Updating the documentation is a three-step process: get the set of supported
23algorithms, update the data file, then generate HTML based on the data file.
24
25Getting the set of supported algorithms is done using
26src/java/libcore/java/security/ListProviders.java. It's important that this is
27run using vogar (in mode=device, the default) rather than in an app container,
28as this documentation only includes the libcore-supported crypto support, but
29the Android frameworks (in particular, Android KeyStore) can add additional
30support.
31
32The data from ListProviders is fed into update_crypto_support.py, which rewrites
33the data file. Any newly-added algorithms will be added to the file's data,
34and any newly-removed algorithms will have their supported API levels updated.
35
36The preceding two steps can be performed together by running
37run_update_crypto_support.sh.
38
39Finally, format_supported_algorithm_table.py reads the data file and outputs
40a collection of HTML tables suitable for copying-and-pasting into the docs
41to stdout.
42