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, along with
6a couple extra classes.
7
8Each algorithm has up to three properties:
9
10name - The name of the algorithm.  These are currently normalized to
11all-uppercase versions, but this produces substandard results in some cases
12(eg, PBEWITHHMACSHA versus PBEWithHmacSHA), so it could be improved.
13
14supported_api_levels: The set of Android API levels that this algorithm was/is
15supported for.  It should be a sequence of zero or more "N" values or "N-M"
16ranges separated by commas followed by a "N+" value if the algorithm is
17currently supported.  For example: "17+", "1-8,22+", "1-10,15,22-24".
18
19deprecated: Whether the algorithm is unsupported at the current API level.  This
20is equivalent to supported_api_levels.endswith('+'), but is included for
21clarity's sake.
22
23Updating the documentation is a three-step process: get the set of supported
24algorithms, update the data file, then generate HTML based on the data file.
25
26Getting the set of supported algorithms is done using
27src/java/libcore/java/security/ListProviders.java.  It's important that this is
28run using vogar in mode=activity rather than the default of mode=device, as
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.  Add --javadoc to produce output appropriate for inclusion in
42Javadoc.
43