mirror/thunderbird-android
0
0
Fork 0
mirror of https://github.com/thunderbird/thunderbird-android.git synced 2024-09-19 19:52:14 +02:00
Code

Change format of Markdown files

Browse Source
This commit is contained in:
Wolf Montwe 2023-02-03 17:28:34 +01:00
parent 71ba065d76
commit 0bf2b31d85
No known key found for this signature in database
GPG Key ID: 24A05D13287F876F
7 changed files with 102 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.github/CONTRIBUTING.md vendored
View File

@ -3,23 +3,21 @@
If the app is not behaving like it should, it's not necessarily a bug. Please consult the following resources before
submitting a new issue.
* [User Manual](https://docs.k9mail.app/)
* [Frequently Asked Questions](https://forum.k9mail.app/c/faq)
* [Support Forum](https://forum.k9mail.app/)
- [User Manual](https://docs.k9mail.app/)
- [Frequently Asked Questions](https://forum.k9mail.app/c/faq)
- [Support Forum](https://forum.k9mail.app/)
### Bug report guidelines
* The issue tracker is solely for bug reports and feature/enhancement requests. If you have a question of any kind,
please use the [support forum](https://forum.k9mail.app/c/support) instead.
* Search the [existing issues](https://github.com/thundernest/k-9/issues?q=) first to make sure your issue hasn't been
reported before.
- The issue tracker is solely for bug reports and feature/enhancement requests. If you have a question of any kind,
please use the [support forum](https://forum.k9mail.app/c/support) instead.
- Search the [existing issues](https://github.com/thundernest/k-9/issues?q=) first to make sure your issue hasn't been
reported before.
## Translations
We're using [Transifex](https://www.transifex.com/k-9/k9mail/) to manage translations.
## Contributing code
We love [pull requests](https://github.com/thundernest/k-9/pulls) from everyone!

16
.github/pull_request_template.md vendored
View File

@ -1,12 +1,12 @@
Please ensure that your pull request meets the following requirements - thanks!
* Does not contain merge commits. Rebase instead.
* Contains commits with descriptive titles.
* New code is written in Kotlin whenever possible.
* Follows our existing codestyle (`gradlew ktlintCheck`; will be checked by CI).
* Does not break any unit tests (`gradlew testDebugUnitTest`; will be checked by CI).
* Uses a descriptive title; don't put issue numbers in there.
* Contains a reference to the issue that it fixes (e.g. *Closes #XXX* or *Fixes #XXX*) in the body text.
* For cosmetic changes add one or multiple images, if possible.
- Does not contain merge commits. Rebase instead.
- Contains commits with descriptive titles.
- New code is written in Kotlin whenever possible.
- Follows our existing codestyle (`gradlew ktlintCheck`; will be checked by CI).
- Does not break any unit tests (`gradlew testDebugUnitTest`; will be checked by CI).
- Uses a descriptive title; don't put issue numbers in there.
- Contains a reference to the issue that it fixes (e.g. _Closes #XXX_ or _Fixes #XXX_) in the body text.
- For cosmetic changes add one or multiple images, if possible.
Finally, please replace this template text with a description of the change and additional context if necessary.

11
README.md
View File

@ -1,10 +1,10 @@
# K-9 Mail
[![Latest release](https://img.shields.io/github/release/thundernest/k-9.svg?style=flat-square)](https://github.com/thundernest/k-9/releases/latest)
[![Latest beta release](https://img.shields.io/github/v/release/thundernest/k-9.svg?include_prereleases&style=flat-square)](https://github.com/thundernest/k-9/releases)
K-9 Mail is an open-source email client for Android.
## Download
K-9 Mail can be downloaded from a couple of sources:
@ -15,13 +15,11 @@ K-9 Mail can be downloaded from a couple of sources:
You might also be interested in becoming a [tester](https://forum.k9mail.app/t/how-do-i-become-a-beta-tester/68) to get an early look at new versions.
## Release Notes
Check out the [Release Notes](https://github.com/thundernest/k-9/wiki/ReleaseNotes) to find out what changed
in each version of K-9 Mail.
## Need Help?
If the app is not behaving like it should, you might find these resources helpful:
@ -30,18 +28,15 @@ If the app is not behaving like it should, you might find these resources helpfu
- [Frequently Asked Questions](https://forum.k9mail.app/c/faq)
- [Support Forum](https://forum.k9mail.app/)
## Translations
Interested in helping to translate K-9 Mail? Contribute here:
https://www.transifex.com/projects/p/k9mail/
## Contributing
Thank you for contributing! If you're unfamiliar with the code,
start by reading the [developer documentation](docs/DESIGN.md)
Thank you for contributing! If you're unfamiliar with the code, start by reading the [developer documentation](docs/DESIGN.md)
Please fork this repository and contribute back using [pull requests](https://github.com/thundernest/k-9/pulls).
@ -49,7 +44,6 @@ Any contributions, large or small, major features, bug fixes, unit/integration t
but will be thoroughly reviewed and discussed.
Please make sure you read the [Code Style Guidelines](https://github.com/thundernest/k-9/wiki/CodeStyle).
## Communication
Aside from discussing changes in [pull requests](https://github.com/thundernest/k-9/pulls) and
@ -59,7 +53,6 @@ Aside from discussing changes in [pull requests](https://github.com/thundernest/
- IRC: [#k9mail on Libera Chat](https://web.libera.chat/#k9mail)
- [Developer mailing list](https://groups.google.com/forum/#!forum/k-9-dev)
## License
Licensed under the Apache License, Version 2.0 (the "License");

60
plugins/openpgp-api-lib/CHANGELOG.md
View File

@ -1,48 +1,56 @@
# Version history
## Version 10
* Retrieve whole public key via ACTION_GET_KEY
- Retrieve whole public key via ACTION_GET_KEY
## Version 9
* AIDL Service has been changed from IOpenPgpService.aidl to IOpenPgpService2.aidl
- AIDL Service has been changed from IOpenPgpService.aidl to IOpenPgpService2.aidl
This fixes truncated data streams (thanks to 'mgeier63').
* Fix for OpenPgpKeyPreference: Properly execute pending user interactions
* Charset moved to OpenPgpMetadata
- Fix for OpenPgpKeyPreference: Properly execute pending user interactions
- Charset moved to OpenPgpMetadata
## Version 8
* OpenPgpSignatureResult:
- OpenPgpSignatureResult:
method getStatus() renamed to getResult()
constants have been renamed for clarity
new constants: RESULT_NO_SIGNATURE, RESULT_INVALID_INSECURE
isSignatureOnly() has been deprecated
* RESULT_TYPES have been removed
* new OpenPgpDecryptionResult returned via RESULT_DECRYPTION
* OpenPgpSignatureResult and OpenPgpDecryptionResult are never null, they are always returned.
- RESULT_TYPES have been removed
- new OpenPgpDecryptionResult returned via RESULT_DECRYPTION
- OpenPgpSignatureResult and OpenPgpDecryptionResult are never null, they are always returned.
## Version 7
* Deprecation of ACCOUNT_NAME, please use ACTION_GET_SIGN_KEY_ID to get key id
* Introduce EXTRA_SIGN_KEY_ID
* New extra for ACTION_ENCRYPT and ACTION_SIGN_AND_ENCRYPT: EXTRA_ENABLE_COMPRESSION (default to true)
* Return PendingIntent to view key for signatures
* New result for ACTION_DECRYPT_VERIFY: RESULT_TYPE
* New ACTION_GET_SIGN_KEY_ID
* EXTRA_PASSPHRASE changed from String to char[]
- Deprecation of ACCOUNT_NAME, please use ACTION_GET_SIGN_KEY_ID to get key id
- Introduce EXTRA_SIGN_KEY_ID
- New extra for ACTION_ENCRYPT and ACTION_SIGN_AND_ENCRYPT: EXTRA_ENABLE_COMPRESSION (default to true)
- Return PendingIntent to view key for signatures
- New result for ACTION_DECRYPT_VERIFY: RESULT_TYPE
- New ACTION_GET_SIGN_KEY_ID
- EXTRA_PASSPHRASE changed from String to char[]
## Version 6
* Deprecate ACTION_SIGN
* Introduce ACTION_CLEARTEXT_SIGN and ACTION_DETACHED_SIGN
* New extra for ACTION_DETACHED_SIGN: EXTRA_DETACHED_SIGNATURE
* New result for ACTION_DECRYPT_VERIFY: RESULT_DETACHED_SIGNATURE
* New result for ACTION_DECRYPT_VERIFY: RESULT_CHARSET
- Deprecate ACTION_SIGN
- Introduce ACTION_CLEARTEXT_SIGN and ACTION_DETACHED_SIGN
- New extra for ACTION_DETACHED_SIGN: EXTRA_DETACHED_SIGNATURE
- New result for ACTION_DECRYPT_VERIFY: RESULT_DETACHED_SIGNATURE
- New result for ACTION_DECRYPT_VERIFY: RESULT_CHARSET
## Version 5
* OpenPgpSignatureResult: new consts RESULT_INVALID_KEY_REVOKED and RESULT_INVALID_KEY_EXPIRED
* OpenPgpSignatureResult: ArrayList<String> userIds
- OpenPgpSignatureResult: new consts RESULT_INVALID_KEY_REVOKED and RESULT_INVALID_KEY_EXPIRED
- OpenPgpSignatureResult: ArrayList<String> userIds
## Version 4
* No changes to existing methods -> backward compatible
* Introduction of ACTION_DECRYPT_METADATA, RESULT_METADATA, EXTRA_ORIGINAL_FILENAME, and OpenPgpMetadata parcel
* Introduction of internal NFC extras: EXTRA_NFC_SIGNED_HASH, EXTRA_NFC_SIG_CREATION_TIMESTAMP
- No changes to existing methods -> backward compatible
- Introduction of ACTION_DECRYPT_METADATA, RESULT_METADATA, EXTRA_ORIGINAL_FILENAME, and OpenPgpMetadata parcel
- Introduction of internal NFC extras: EXTRA_NFC_SIGNED_HASH, EXTRA_NFC_SIG_CREATION_TIMESTAMP
## Version 3
* First public stable version
- First public stable version

73
plugins/openpgp-api-lib/README.md
View File

@ -5,11 +5,13 @@ The OpenPGP API provides methods to execute OpenPGP operations, such as sign, en
### News
#### Version 10
* Retrieve whole public key via ACTION_GET_KEY
- Retrieve whole public key via ACTION_GET_KEY
[Full changelog here…](https://github.com/open-keychain/openpgp-api/blob/master/CHANGELOG.md)
### License
While OpenKeychain itself is GPLv3+, the API library is licensed under Apache License v2.
Thus, you are allowed to also use it in closed source applications as long as you respect the [Apache License v2](https://github.com/open-keychain/openpgp-api/blob/master/LICENSE).
@ -28,7 +30,8 @@ dependencies {
```
### Full example
A full working example is available in the [example project](https://github.com/open-keychain/openpgp-api/blob/master/example). The [``OpenPgpApiActivity.java``](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) contains most relevant sourcecode.
A full working example is available in the [example project](https://github.com/open-keychain/openpgp-api/blob/master/example). The [`OpenPgpApiActivity.java`](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) contains most relevant sourcecode.
### API
@ -38,21 +41,24 @@ A full working example is available in the [example project](https://github.com/
**This tutorial only covers the basics, please consult the full example for a complete overview over all methods**
The API is **not** designed around ``Intents`` which are started via ``startActivityForResult``. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API#internal-design-decisions).
The API is **not** designed around `Intents` which are started via `startActivityForResult`. These Intent actions typically start an activity for user interaction, so they are not suitable for background tasks. Most API design decisions are explained at [the bottom of this wiki page](https://github.com/open-keychain/open-keychain/wiki/OpenPGP-API#internal-design-decisions).
We will go through the basic steps to understand how this API works, following this (greatly simplified) sequence diagram:
![](https://github.com/open-keychain/open-keychain/raw/master/Resources/docs/openpgp_api_1.jpg)
In this diagram the client app is depicted on the left side, the OpenPGP provider (in this case OpenKeychain) is depicted on the right.
The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [``IOpenPgpService``](https://github.com/open-keychain/openpgp-api/blob/master/openpgp-api/src/main/aidl/org/openintents/openpgp/IOpenPgpService.aidl).
The remote service is defined via the [AIDL](http://developer.android.com/guide/components/aidl.html) file [`IOpenPgpService`](https://github.com/open-keychain/openpgp-api/blob/master/openpgp-api/src/main/aidl/org/openintents/openpgp/IOpenPgpService.aidl).
It contains only one exposed method which can be invoked remotely:
```java
interface IOpenPgpService {
Intent execute(in Intent data, in ParcelFileDescriptor input, in ParcelFileDescriptor output);
}
```
The interaction between the apps is done by binding from your client app to the remote service of OpenKeychain.
``OpenPgpServiceConnection`` is a helper class from the library to ease this step:
`OpenPgpServiceConnection` is a helper class from the library to ease this step:
```java
OpenPgpServiceConnection mServiceConnection;
@ -72,36 +78,38 @@ public void onDestroy() {
Following the sequence diagram, these steps are executed:
1. Define an ``Intent`` containing the actual PGP instructions which should be done, e.g.
```java
1. Define an `Intent` containing the actual PGP instructions which should be done, e.g.
`java
Intent data = new Intent();
data.setAction(OpenPgpApi.ACTION_ENCRYPT);
data.putExtra(OpenPgpApi.EXTRA_USER_IDS, new String[]{"dominik@dominikschuermann.de"});
data.putExtra(OpenPgpApi.EXTRA_REQUEST_ASCII_ARMOR, true);
```
Define an ``InputStream`` currently holding the plaintext, and an ``OutputStream`` where you want the ciphertext to be written by OpenKeychain's remote service:
```java
`
Define an `InputStream` currently holding the plaintext, and an `OutputStream` where you want the ciphertext to be written by OpenKeychain's remote service:
`java
InputStream is = new ByteArrayInputStream("Hello world!".getBytes("UTF-8"));
ByteArrayOutputStream os = new ByteArrayOutputStream();
```
Using a helper class from the library, ``is`` and ``os`` are passed via ``ParcelFileDescriptors`` as ``input`` and ``output`` together with ``Intent data``, as depicted in the sequence diagram, from the client to the remote service.
`
Using a helper class from the library, `is` and `os` are passed via `ParcelFileDescriptors` as `input` and `output` together with `Intent data`, as depicted in the sequence diagram, from the client to the remote service.
Programmatically, this can be done with:
```java
`java
OpenPgpApi api = new OpenPgpApi(this, mServiceConnection.getService());
Intent result = api.executeApi(data, is, os);
```
`
2. The PGP operation is executed by OpenKeychain and the produced ciphertext is written into ``os`` which can then be accessed by the client app.
2. The PGP operation is executed by OpenKeychain and the produced ciphertext is written into `os` which can then be accessed by the client app.
3. A result Intent is returned containing one of these result codes:
* ``OpenPgpApi.RESULT_CODE_ERROR``
* ``OpenPgpApi.RESULT_CODE_SUCCESS``
* ``OpenPgpApi.RESULT_CODE_USER_INTERACTION_REQUIRED``
If ``RESULT_CODE_USER_INTERACTION_REQUIRED`` is returned, an additional ``PendingIntent`` is returned to the client, which must be used to get user input required to process the request.
A ``PendingIntent`` is executed with ``startIntentSenderForResult``, which starts an activity, originally belonging to OpenKeychain, on the [task stack](http://developer.android.com/guide/components/tasks-and-back-stack.html) of the client.
Only if ``RESULT_CODE_SUCCESS`` is returned, ``os`` actually contains data.
- `OpenPgpApi.RESULT_CODE_ERROR`
- `OpenPgpApi.RESULT_CODE_SUCCESS`
- `OpenPgpApi.RESULT_CODE_USER_INTERACTION_REQUIRED`
If `RESULT_CODE_USER_INTERACTION_REQUIRED` is returned, an additional `PendingIntent` is returned to the client, which must be used to get user input required to process the request.
A `PendingIntent` is executed with `startIntentSenderForResult`, which starts an activity, originally belonging to OpenKeychain, on the [task stack](http://developer.android.com/guide/components/tasks-and-back-stack.html) of the client.
Only if `RESULT_CODE_SUCCESS` is returned, `os` actually contains data.
A nearly complete example looks like this:
```java
switch (result.getIntExtra(OpenPgpApi.RESULT_CODE, OpenPgpApi.RESULT_CODE_ERROR)) {
case OpenPgpApi.RESULT_CODE_SUCCESS: {
@ -135,10 +143,10 @@ Intent result = api.executeApi(data, is, os);
}
```
4. Results from a ``PendingIntent`` are returned in ``onActivityResult`` of the activity, which executed ``startIntentSenderForResult``.
The returned ``Intent data`` in ``onActivityResult`` contains the original PGP operation definition and new values acquired from the user interaction.
Thus, you can now execute the ``Intent`` again, like done in step 1.
This time it should return with ``RESULT_CODE_SUCCESS`` because all required information has been obtained by the previous user interaction stored in this ``Intent``.
4. Results from a `PendingIntent` are returned in `onActivityResult` of the activity, which executed `startIntentSenderForResult`.
The returned `Intent data` in `onActivityResult` contains the original PGP operation definition and new values acquired from the user interaction.
Thus, you can now execute the `Intent` again, like done in step 1.
This time it should return with `RESULT_CODE_SUCCESS` because all required information has been obtained by the previous user interaction stored in this `Intent`.
```java
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
[...]
@ -154,16 +162,17 @@ Intent result = api.executeApi(data, is, os);
}
```
### Tipps
* ``api.executeApi(data, is, os);`` is a blocking call. If you want a convenient asynchronous call, use ``api.executeApiAsync(data, is, os, new MyCallback([... ]));``, where ``MyCallback`` is an private class implementing ``OpenPgpApi.IOpenPgpCallback``.
See [``OpenPgpApiActivity.java``](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) for an example.
* Using
- `api.executeApi(data, is, os);` is a blocking call. If you want a convenient asynchronous call, use `api.executeApiAsync(data, is, os, new MyCallback([... ]));`, where `MyCallback` is an private class implementing `OpenPgpApi.IOpenPgpCallback`.
See [`OpenPgpApiActivity.java`](https://github.com/open-keychain/openpgp-api/blob/master/example/src/main/java/org/openintents/openpgp/example/OpenPgpApiActivity.java) for an example.
- Using
```java
mServiceConnection = new OpenPgpServiceConnection(this, "org.sufficientlysecure.keychain");
```
connects to OpenKeychain directly.
If you want to let the user choose between OpenPGP providers, you can implement the [``OpenPgpAppPreference.java``](https://github.com/open-keychain/openpgp-api/tree/master/openpgp-api/src/main/java/org/openintents/openpgp/util/OpenPgpAppPreference.java) like done in the example app.
* To enable installing a debug and release version at the same time, the `debug` build of OpenKeychain uses `org.sufficientlysecure.keychain.debug` as a package name. Make sure you connect to the right one during development!
connects to OpenKeychain directly.
If you want to let the user choose between OpenPGP providers, you can implement the [`OpenPgpAppPreference.java`](https://github.com/open-keychain/openpgp-api/tree/master/openpgp-api/src/main/java/org/openintents/openpgp/util/OpenPgpAppPreference.java) like done in the example app.
- To enable installing a debug and release version at the same time, the `debug` build of OpenKeychain uses `org.sufficientlysecure.keychain.debug` as a package name. Make sure you connect to the right one during development!