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