diff options
Diffstat (limited to 'comm/third_party/rnp/docs')
| -rw-r--r-- | comm/third_party/rnp/docs/c-usage.adoc | 129 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/cli-usage.adoc | 174 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/code-of-conduct.adoc | 128 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/develop.adoc | 435 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/develop/cpp-usage.adoc | 49 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/develop/packaging.adoc | 78 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/develop/release-workflow.adoc | 122 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/installation.adoc | 262 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/navigation.adoc | 18 | ||||
| -rw-r--r-- | comm/third_party/rnp/docs/signing-keys.adoc | 5 |
10 files changed, 1400 insertions, 0 deletions
diff --git a/comm/third_party/rnp/docs/c-usage.adoc b/comm/third_party/rnp/docs/c-usage.adoc new file mode 100644 index 0000000000..b45f9b91bb --- /dev/null +++ b/comm/third_party/rnp/docs/c-usage.adoc @@ -0,0 +1,129 @@ += Using the RNP C API + +This document is for developers who wish to use RNP as a library in C. + +Examples are given below to demonstrate such usage. + +== Examples + +[TIP] +.Location of examples +==== +The source code of these examples can be found under +`https://github.com/rnpgp/rnp/blob/main/src/examples/[src/examples]`. + +If you are planning to build from source, these examples are built +together with the RNP library and will be available under `src/examples` +within your build folder. +==== + +[TIP] +==== +All samples below use APIs exposed via the header file +`https://github.com/rnpgp/rnp/blob/main/include/rnp/rnp.h[include/rnp/rnp.h]`. +For further details please refer to the file directly. +==== + +The following example applications are available: + +`generate`:: Demonstrates generating keys, save/load of keyrings, exporting keys. + +`encrypt`:: Demonstrates how to encrypt a file using a password and/or key. + +`decrypt`:: Demonstrates how to decrypt OpenPGP data using a key and/or password. + +`sign`:: Demonstrates how to sign messages, using one or more keys from a loaded keyring. + +`verify`:: Demonstrates how to verify signed messages using dynamic keys fetching + (using a sample key provider implementation). + +`dump`:: Demonstrates how to dump OpenPGP packet information. + + +=== generate.c + +Location: https://github.com/rnpgp/rnp/blob/main/src/examples/generate.c + +This example is composed from 2 functions: + +* `ffi_generate_keys()`: Demonstrates how to generate and save different key types + (RSA and EDDSA/Curve25519) using JSON key description. + Also demonstrates usage of the password provider. ++ +Keyrings will be saved to files `pubring.pgp` and `secring.pgp` in the current directory. +You can use `rnp --list-packets pubring.pgp` to check the properties of the generated key(s). + +* `ffi_output_keys()`: Demonstrates how to load keyrings, + search for keys (in helper functions `ffi_print_key()`/`ffi_export_key()`), + and how to export them to memory or file in armored format. + +=== encrypt.c + +Location: https://github.com/rnpgp/rnp/blob/main/src/examples/encrypt.c + +This code example does the following: + +* first loads a public keyring (`pubring.pgp`) (created by the `generate.c` example) +* then creates an encryption operation structure and +* configures it with various options (including the setup of password encryption and public-key encryption). + +The result is the encrypted and armored (for easier reading) message +`RNP encryption sample message`. + +This message is saved to the file `encrypted.asc` in current directory. + +What you can do after: + +* Inspect the message with `rnp --list-packets encrypted.asc`. +* Decrypt the saved file via `rnp --keyfile secring.pgp -d encrypted.asc`. + +=== decrypt.c + +Location: https://github.com/rnpgp/rnp/blob/main/src/examples/decrypt.c + +This example uses keyrings generated from the `generate.c` example +to decrypt messages encrypted by the `encrypt.c` example. + +This example demonstrates how to decrypt message with a password or with a key, +and implements a custom password provider for decryption via key or key password. + +The decrypted message is saved to memory and then printed to the `stdout`. + +=== sign.c + +Location: https://github.com/rnpgp/rnp/blob/main/src/examples/sign.c + +This example uses keyrings generated in the preceding `generate.c` example. + +It demonstrates configuration of a signing context, signing of the message, +and the saving of the detached signature to the `signed.asc` file. + +Then the attached signature is used: i.e. the data is encapsulated into +the resulting message. + +What you can do after: + +* Inspect the signed message with `rnp --list-packets signed.asc`. +* Verify the message with `rnp --keyfile pubring.pgp -v signed.asc`. + +=== verify.c + +Location: https://github.com/rnpgp/rnp/blob/main/src/examples/verify.c + +This example uses keyrings generated in the `generate.c` example. + +However, instead of loading the whole keyring, it implements dynamic key fetching +via custom key provider (see function `example_key_provider`). + +After verification, it outputs the verified embedded message +and all signatures to `stdout` (with signing key IDs and statuses). + +=== dump.c + +Location: https://github.com/rnpgp/rnp/blob/main/src/examples/dump.c + +This example dumps OpenPGP packet information from the input stream +(via `stdin` or filename), tuned with flags passed via the +command-line interface. + +The resulting human-readable text or JSON is printed to `stdout`. diff --git a/comm/third_party/rnp/docs/cli-usage.adoc b/comm/third_party/rnp/docs/cli-usage.adoc new file mode 100644 index 0000000000..7039381f77 --- /dev/null +++ b/comm/third_party/rnp/docs/cli-usage.adoc @@ -0,0 +1,174 @@ += Using the RNP command-line interface + +== Generating an RSA private key + +By default, `rnpkeys --generate-key` generates a 2048-bit RSA key. + +[source,console] +---- +export keydir=/tmp +rnpkeys --generate-key --homedir=${keydir} +---- + +=> + +[source,console] +---- +rnpkeys: generated keys in directory ${keydir}/6ed2d908150b82e7 +---- + +NOTE: Here `6ed2d...` is the key fingerprint. + +In order to use fully-featured key-pair generation, the `--expert` flag +should be used. + +With this flag added to `rnpkeys --generate-key`, the user will be +able to generate a key-pair for any supported algorithm and/or key size. + +Example: + +[source,console] +---- +> export keydir=/tmp +> rnpkeys --generate-key --expert --homedir=${keydir} + +Please select what kind of key you want: + (1) RSA (Encrypt or Sign) + (19) ECDSA + (22) EDDSA +> 19 + +Please select which elliptic curve you want: + (1) NIST P-256 + (2) NIST P-384 + (3) NIST P-521 +> 2 + +Generating a new key... +signature 384/ECDSA d45592277b75ada1 2017-06-21 +Key fingerprint: 4244 2969 07ca 42f7 b6d8 1636 d455 9227 7b75 ada1 +uid ECDSA 384-bit key <flowher@localhost> +rnp: generated keys in directory /tmp/.rnp +Enter password for d45592277b75ada1: +Repeat password for d45592277b75ada1: +> +---- + + +== Listing keys + +[source,console] +---- +export keyringdir=${keydir}/MYFINGERPRINT +rnpkeys --list-keys --homedir=${keyringdir} + +---- + +=> + +[source,console] +---- +1 key found +... +---- + + +== Signing a file + + +=== Signing in binary format + +[source,console] +---- +rnp --sign --homedir=${keyringdir} ${filename} +---- + +=> + +Creates `${filename}.gpg` which is an OpenPGP message that includes the +message together with the signature as a 'signed message'. + +This type of file can be verified with: + +* `rnp --verify --homedir=${keyringdir} ${filename}.gpg` + + +=== Signing in binary detached format + +[source,console] +---- +rnp --sign --detach --homedir=${keyringdir} ${filename} +---- + +=> + +Creates `${filename}.sig` which is an OpenPGP message in binary +format, that only contains the signature. + +This type of file can be verified with: + +* `rnp --verify --homedir=${keyringdir} ${filename}.sig` + + +=== Signing in armored ("`ASCII-armored`") format + +[source,console] +---- +rnp --sign --armor --homedir=${keyringdir} ${filename} +---- + +=> + +Creates `${filename}.asc` which is an OpenPGP message in ASCII-armored +format, including the message together with the signature as a +"`signed message`". + +This type of file can be verified with: + +* `rnp --verify --homedir=${keyringdir} ${filename}.asc` + + +=== Other options + +`--clearsign`:: +appends a separate OpenPGP signature to the end of the newly +signed message. + +`--detach`:: +saves the OpenPGP signature in a separate file from the newly +signed message. + + +== Encrypt + + +[source,console] +---- +rnp --encrypt --homedir=${keyringdir} ${filename} +---- + +=> + +Creates `${filename}.gpg`, which is an encrypted OpenPGP message. + + +== Decrypt + +[source,console] +---- +rnp --decrypt --homedir=${keyringdir} ${filename}.gpg +---- + +=> + +Creates `${filename}`, the decrypted form of the `${filename}.gpg` +encrypted OpenPGP message. + + +== Check version + +The output of `rnp --version` contains the `git` hash of the version +the binary was built from, of which value is generated when `cmake` runs. + +Consequently, a release tarball generated with `make dist` will +contain this hash version. diff --git a/comm/third_party/rnp/docs/code-of-conduct.adoc b/comm/third_party/rnp/docs/code-of-conduct.adoc new file mode 100644 index 0000000000..14f5e0365e --- /dev/null +++ b/comm/third_party/rnp/docs/code-of-conduct.adoc @@ -0,0 +1,128 @@ + += Contributor Covenant Code of Conduct + +== Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +== Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +open.source@ribose.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +=== 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +=== 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +=== 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +=== 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla's code of conduct enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/comm/third_party/rnp/docs/develop.adoc b/comm/third_party/rnp/docs/develop.adoc new file mode 100644 index 0000000000..e0c0e4116e --- /dev/null +++ b/comm/third_party/rnp/docs/develop.adoc @@ -0,0 +1,435 @@ += RNP development guide + +The following are a set of conventions and items that are relevant to +contributors. + +== Contributing + +=== Pull Requests + +See also: https://github.com/thoughtbot/guides/tree/master/code-review[Thoughtbot’s Code Review guide] + +Pull Requests should be used for any non-trivial changes. This presents +an opportunity for feedback and allows the CI tests to complete prior to +merging. + +The `master` branch should generally always be in a buildable and +functional state. + +Pull Requests should be: + +* Focused. Do not include changes that are unrelated to the main purpose + of the PR. +* As small as possible. Sometimes large pull requests may be necessary + for adding complex features, but generally they should be kept as small + as possible to ensure a quick and thorough review process. +* Related to a GH issue to which you are assigned. If there is none, + file one (but search first!). This ensures there is no duplication of + effort and allows for a discussion prior to beginning work. + (This may not be necessary for PRs that are purely documentation updates) +* Approved by **2** reviewers before merging. + (Updates related to policies, like this section, should be approved by + the project owner) +* Merged by a reviewer via the most appropriate method + (see https://github.com/rnpgp/guides/tree/master/protocol/git[here]). + +=== Branches + +See also: https://github.com/rnpgp/guides/tree/master/protocol/git[Guides - Protocol / Git] + +Git branches should be used generously. Most branches should be topic branches, +created for adding a specific feature or fixing a specific bug. + +Keep branches short-lived (treat them as disposable/transient) and try to +avoid long-running branches. + +A good example of using a branch would be: + +* User `@joe` notices a bug where a NULL pointer is dereferenced during + key export. He creates GH issue `#500`. +* He creates a new branch to fix this bug named + `joe-500-fix-null-deref-in-pgp_export_key`. +* Joe commits a fix for the issue to this new branch. +* Joe creates a Pull Request to merge this branch in to main. +* Once merged, Joe deletes the branch since it is no longer useful. + +Branch names may vary but should be somewhat descriptive, with words +separated by hyphens. It is also helpful to start the branch name with +your GitHub username, to make it clear who created the branch and +prevent naming conflicts. + +Remember that branch names may be preserved permanently in the commit +history of `main`, depending on how they are merged. + +=== Commits + +* Try to keep commits as small as possible. This may be difficult or + impractical at times, so use your best judgement. +* Each commit should be buildable and should pass all tests. This helps + to ensure that git bisect remains a useful method of pinpointing issues. +* Commit messages should follow 50/72 rule. +* When integrating pull requests, merge function should be preferred over + squashing. From the other hand, developers should squash commits and + create meaningful commit stack before PR is merged into mainstream branch. + Merging commits like "Fix build" or "Implement comments from code review" + should be avoided. + +== Continuous Integration (Github Actions) + +Github actions are used for continuously testing new commits and pull requests. +Those include testing for different operating systems, linting via clang-format and shellcheck, +and code coverage and quality checks via `Codecov` and `LGTM.io`. + +For Github workflows sources see `.github/workflows/` folder and scripts from the `ci/` folder. +Also there is a Cirrus CI runner, configuration for which is stored in `.cirrus.yml`. + +=== Reproducing Locally + +If tests fail in CI, you may attempt to reproduce those locally via `ctest` command: + +[source,console] +-- +ctest -j4 -V -R rnp_tests +-- + +Or, more specific: + +[source,console] +-- +ctest -V -R cli_tests-Misc +-- + +If test fails under the specific OS, you should construct corresponding Docker container and run tests inside, taking Github workflows as a guide. + +== Code Coverage + +CodeCov is used for assessing our test coverage. +The current coverage can always be viewed here: https://codecov.io/github/rnpgp/rnp/ + +== Security / Bug Hunting + +=== Static Analysis + +==== Coverity Scan + +Coverity Scan is used for static analysis of the code base. +It is run daily on the main branch via the Github actions. +See `.github/workflows/coverity.yml` for the details. + +The results can be accessed on https://scan.coverity.com/projects/rnpgp-rnp. +You will need to create an account and request access to the rnpgp/rnp project. + +Since the scan results are not updated live, line numbers may no longer +be accurate against the `main` branch, issues may already be resolved, +etc. + +==== Clang Static Analyzer + +Clang includes a useful static analyzer that can also be used to locate +potential bugs. + +Note: It is normal for the build time to increase significantly when using this static analyzer. + +[source,console] +-- +# it's important to start fresh for this! +rm -rf build && mkdir build && cd build +scan-build cmake .. && scan-build make -j8 +[...] +scan-build: 61 bugs found. +scan-build: Run 'scan-view /tmp/scan-build-2018-09-17-085354-22998-1' to examine bug reports. +-- + +Then use `scan-view`, as indicated above, to start a web server and use +your web browser to view the results. + +=== Dynamic Analysis + +==== Fuzzing + +It is often useful to utilize a fuzzer like +http://lcamtuf.coredump.cx/afl/["american fuzzy lop" ("AFL")] or +https://llvm.org/docs/LibFuzzer.html["libfuzzer"] to find +ways to improve the robustness of the code base. + +Presently, rnp builds in +https://github.com/google/oss-fuzz/tree/master/projects/rnp["OSS-Fuzz"] +and certain fuzzers are enabled there. + +In the `src/fuzzing` directory, we have the fuzzers that run in OSS-Fuzz. +Setting `-DENABLE_SANITIZERS=1 -DENABLE_FUZZERS=1` will build these fuzzers +with the libfuzzer engine; and running the resulting executables will perform +the fuzzing. + +To build and run fuzzers locally, or reproduce an issue, see https://google.github.io/oss-fuzz/advanced-topics/reproducing/ + +===== Further Reading + +* AFL's `README`, `parallel_fuzzing.txt`, and other bundled documentation. +* See https://fuzzing-project.org/tutorial3.html[Tutorial: Instrumented fuzzing with american fuzzy lop] + +==== Clang Sanitizer + +Clang and GCC both support a number of sanitizers that can help locate +issues in the code base during runtime. + +To use them, you should rebuild with the sanitizers enabled, and then +run the tests (or any executable): + +[source,console] +-- +env CXX=clang++ CXXFLAGS="-fsanitize=address,undefined" LDFLAGS="-fsanitize=address,undefined" ./configure +make -j4 +src/tests/rnp_tests +-- + +Here we are using the +https://clang.llvm.org/docs/AddressSanitizer.html[AddressSanitizer] +and +https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html[UndefinedBehaviorSanitizer]. + +This will produce output showing any memory leaks, heap overflows, or +other issues. + +== Code Conventions + +C is a very flexible and powerful language. Because of this, it is +important to establish a set of conventions to avoid common problems and +to maintain a consistent code base. + +=== Code Formatting + +`clang-format` (v9.0.0) can be used to format the code base, utilizing +the `.clang-format` file included in the repository. + +==== clang-format git hook + +A git pre-commit hook exists to perform this task automatically, and can +be enabled like so: + +[source,console] +-- +cd rnp +git-hooks/enable.sh +-- + +If you do not have clang-format v9.0.0 available, you can use a docker +container for this purpose by setting `USE_DOCKER="yes"` in +`git-hooks/pre-commit.sh`. + +This should generally work if you commit from the command line. + +Note that if you have unstaged changes on some of the files you are +attempting to commit, which have formatting issues detected, you will +have to resolve this yourself (the script will inform you of this). + +If your commit does not touch any `.c`/`.h` files, you can skip the +pre-commit hook with git's `--no-verify`/`-n` option. + +==== clang-format (manually) + +If you are not able to use the git hook, you can run `clang-format` +manually in a docker container. + +Create a suitable container image with: + +[source,console] +-- +docker run --name=clang-format alpine:latest apk --no-cache add clang +docker commit clang-format clang-format +docker rm clang-format +-- + +You can then reformat a file (say, `src/lib/crypto/bn.cpp`) like so: + +[source,console] +-- +cd rnp +docker run --rm -v $PWD:/rnp -w /rnp clang-format clang-format -style=file -i src/lib/crypto/bn.cpp +-- + +Also you may wish to reformat all modified uncommitted files: + +[source,console] +-- +docker run --rm -v $PWD:/rnp -w /rnp clang-format clang-format -style=file -i `git ls-files -m |grep "\.\(c\|h\|cpp\)\$"` +-- + +...or files, modified since referenced commit, say `54c5476`: + +[source,console] +-- +docker run --rm -v $PWD:/rnp -w /rnp clang-format clang-format -style=file -i `git diff --name-only 54c5476..HEAD |grep "\.\(c\|h\|cpp\)\$"` +-- + +=== Style Guide + +In order to keep the code base consistent, we should define and adhere +to a single style. + +When in doubt, consult the existing code base. + +==== Naming + +The following are samples that demonstrate the style for naming +different things. + +* Functions: `some_function` +* Variables: `some_variable` +* Filenames: `packet-parse.c` `packet-parse.h` +* Struct: `pgp_key_t` +* Typedefed Enums: `pgp_pubkey_alg_t` +* Enum Values: `PGP_PKA_RSA = 1` +* Constants (macro): `RNP_BUFSIZ` + +==== General Guidelines + +Do: + +* Do use header guards (`#ifndef SOME_HEADER_H [...]`) in headers. +* Do use `sizeof(variable)`, rather than `sizeof(type)`. Or + `sizeof(*variable)` as appropriate. +* Do use commit messages that close GitHub issues automatically, when + applicable. `Fix XYZ. Closes #78.` See + https://help.github.com/articles/closing-issues-via-commit-messages/[here]. +* Do declare functions `static` when they do not need to be referenced + outside the current source file. +* Do always use braces for conditionals, even if the block only contains a + single statement. ++ +[source,c] +-- +if (something) { + return val; +} +-- + +* Do use a default failure (not success) value for `ret` variables. Example: ++ +[source,c] +-- +rnp_result_t ret = RNP_ERROR_GENERIC; +// ... + +return ret; +-- + +Do not: + +* Do not use the static storage class for local variables, *unless* they + are constant. ++ +**Not OK** ++ +[source,c] +-- +int somefunc() { + static char buffer[256]; + //... +} +-- ++ +**OK** ++ +[source,c] +-- +int somefunc() { + static const uint16_t some_data[] = { + 0x00, 0x01, 0x02, //... + }; +} +-- + +* Do not use `pragma`, and try to avoid `__attribute__` as well. + +* Do not use uninitialized memory. Try to ensure your code will not cause any errors in valgrind and other memory checkers. + +==== Documentation + +Documentation is done in Doxygen comments format, which must be put in header files. + +Exception are static or having only definition functions - it is not required to document them, +however if they are documented then this should be done in the source file and using the @private tag. + +Comments should use doxygen markdown style, like the following example: + +[source,c] +-- +/** Some comments regarding the file purpose, like 'PGP packet parsing utilities' + * @file + */ + +/** brief description of the sample function which does something, keyword 'brief' is omitted + * Which may be continued here + * + * After an empty line you may add detailed description in case it is needed. You may put + * details about the memory allocation, what happens if function fails and so on. + * + * @param param1 first parameter, null-terminated string which should not be NULL + * @param param2 integer, some number representing something + * @param size number of bytes available to store in buffer + * @param buffer buffer to store results, may be NULL. In this case size can be used to + * obtain the required buffer length + * @return 0 if operation succeeds, or error code otherwise. If operation succeeds then buffer + * is populated with the resulting data, and size contains the length of this data. + * if error code is E_BUF_TOOSMALL then size will contain the required size to store + * the result + **/ +rnp_result_t +rnp_do_operation(const char *param1, const int param2, int *size, char *buffer); +-- + +== OpenPGP protocol specification + +During development you'll need to reference OpenPGP protocol and related documents. +Here is the list of RFCs and Internet Drafts available at the moment: + +* https://www.ietf.org/rfc/rfc1991.txt[RFC 1991]: PGP Message Exchange Formats. Now obsolete, but may have some historical interest. +* https://www.ietf.org/rfc/rfc2440.txt[RFC 2440]: OpenPGP Message Format. Superseded by RFC 4880. +* https://www.ietf.org/rfc/rfc4880.txt[RFC 4880]: OpenPGP Message Format. Latest RFC available at the moment, however has a lot of suggested changes via RFC 4880bis +* https://tools.ietf.org/rfc/rfc5581.txt[RFC 5581]: The Camellia cipher in OpenPGP. +* https://www.ietf.org/id/draft-ietf-openpgp-rfc4880bis-09.txt[RFC 4880bis-09]: OpenPGP Message Format. Latest suggested update to the RFC 4880. + +More information sources: + +* https://mailarchive.ietf.org/arch/browse/openpgp/[OpenPGP Working Group mailing list]. Here you can pick up all the latest discussions and suggestions regarding the update of RFC 4880 +* https://gitlab.com/openpgp-wg/rfc4880bis[OpenPGP Working Group gitlab]. Latest work on RFC update is available here. + +== Reviewers and Responsibility areas + +The individuals are responsible for the following areas of `rnp`. +When submitting a Pull Request please seek reviews by whoever is +responsible according to this list. + +General: + +* Code style: @dewyatt +* Algorithms: @randombit, @dewyatt, @flowher, @catap, @ni4 +* Performance: @catap, @ni4 +* CLI: @ni4 +* GnuPG compatibility: @MohitKumarAgniotri, @frank-trampe, @ni4 +* Security Testing/Analysis: @MohitKumarAgniotri, @flowher +* Autotools: @randombit, @zgyarmati, @catap + +Data formats: + +* OpenPGP Packet: @randombit, @catap, @ni4 +* Keystore: @catap +* JSON: @zgyarmati +* SSH: @ni4 + +Bindings: + +* FFI: @dewyatt +* Ruby: @dewyatt +* Java/JNI: @catap +* Obj-C/Swift: @ni4 +* Python: @dewyatt, @ni4 + +Platforms: + +* RHEL/CentOS: @dewyatt +* BSD: +* Windows: @rrrooommmaaa +* macOS / iOS / Homebrew: @ni4 +* Debian: @zgyarmati diff --git a/comm/third_party/rnp/docs/develop/cpp-usage.adoc b/comm/third_party/rnp/docs/develop/cpp-usage.adoc new file mode 100644 index 0000000000..e0c18427bf --- /dev/null +++ b/comm/third_party/rnp/docs/develop/cpp-usage.adoc @@ -0,0 +1,49 @@ += Usage of {cpp} within RNP + +This is a provisional document reflecting the recent conversion from C +to {cpp}. It should be revisited as experience with using {cpp} within RNP +codebase increases. + +== Encouraged Features + +These are features which seem broadly useful, their downsides are minimal +and well understood. + + - STL types std::vector, std::string, std::unique_ptr, std::map + + - RAII techniques (destructors, smart pointers) to minimize use of + goto to handle cleanup. + + - Value types, that is to say types which simply encapsulate some + data. + + - std::function or virtual functions to replace function pointers. + + - Prefer virtual functions only on "interface" classes (with no data), + and derive only one level of classes from this interface class. + + - Anonymous namespaces are an alternative to `static` functions. + +== Questionable Features + +These are features that may be useful in certain situations, but should +be used carefully. + + - Exceptions. While convenient, they do have a non-zero cost in runtime + and binary size. + +== Forbidden Features + +These are {cpp} features that simply should be avoided, at least until a +very clear use case for them has been identified and no other approach +suffices. + + - RTTI. This has a significant runtime cost and usually there are + better alternatives. + + - Multiple inheritance. This leads to many confusing and problematic + scenarios. + + - Template metaprogramming. If you have a problem, and you think + template metaprogramming will solve it, now you have two problems, + and one of them is incomprehensible. diff --git a/comm/third_party/rnp/docs/develop/packaging.adoc b/comm/third_party/rnp/docs/develop/packaging.adoc new file mode 100644 index 0000000000..917c9aa71c --- /dev/null +++ b/comm/third_party/rnp/docs/develop/packaging.adoc @@ -0,0 +1,78 @@ += Packaging + +== CentOS 7 + +=== 1. Retrieve the source + +==== Tarball + +[source,console] +-- +curl -LO https://github.com/rnpgp/rnp/archive/v0.9.0.tar.gz +tar xzf v0.9.0.tar.gz +cd rnp-0.9.0 +-- + +==== Git + +[source,console] +-- +git clone https://github.com/rnpgp/rnp +cd rnp +git checkout v0.9.0 +-- + +=== 2. Launch a container + +[source,console] +-- +docker run -ti --rm -v $PWD:/usr/local/rnp centos:7 bash +-- + +From this point, all commands are executed in the container. + +==== 3. Install pre-requisites + +[source,console] +-- +# for newer cmake and other things +yum -y install epel-release + +# rnp +yum -y install git cmake3 make gcc-c++ +yum -y install bzip2-devel zlib-devel json-c12-devel + +# botan +rpm --import https://github.com/riboseinc/yum/raw/master/ribose-packages.pub +rpm --import https://github.com/riboseinc/yum/raw/master/ribose-packages-next.pub +curl -L https://github.com/riboseinc/yum/raw/master/ribose.repo > /etc/yum.repos.d/ribose.repo +yum -y install botan2-devel +-- + +=== 4. Build the RPM + +[source,console] +-- +yum -y install rpm-build +mkdir ~/build +cd ~/build +cmake3 -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off -DCPACK_GENERATOR=RPM /usr/local/rnp +make package +-- + +=== 5. Check and Install the RPM + +It may be helpful to run `rpmlint` on the RPM and note new warnings or errors. + +[source,console] +-- +yum -y install rpmlint +rpmlint rnp-0.9.0-1.el7.centos.x86_64.rpm +-- + +At this point, you can test that the RPM installs successfully: + +[source,console] +-- +yum localinstall rnp-0.9.0-1.el7.centos.x86_64.rpm +-- diff --git a/comm/third_party/rnp/docs/develop/release-workflow.adoc b/comm/third_party/rnp/docs/develop/release-workflow.adoc new file mode 100644 index 0000000000..40f4203bd0 --- /dev/null +++ b/comm/third_party/rnp/docs/develop/release-workflow.adoc @@ -0,0 +1,122 @@ += Releases + +== General notes + +* Avoid tagging commits in the `main` branch. +* Release branches should have annotated tags and a CHANGELOG.md. +* The steps below detail creation of a brand new 1.0.0 release. + Some steps would be omitted for minor releases. + +== Creating an initial release + +=== Update documentation + +Update references to version numbers in relevant documentation to the new +version you intend to release. + +[source,console] +---- +git checkout main +vim docs/installation.adoc +git add docs/installation.adoc +git commit +git push +---- + +=== Create branch + +Release branches have names of the form `release/N.x`, where N is the major +version (and `x` is a literal -- not a placeholder). + +[source,console] +---- +git checkout -b release/1.x main +---- + +[[update-changelog-and-version]] +=== Update CHANGELOG and version + +[source,console] +---- +vim CHANGELOG.md +# Add/update CHANGELOG entry for the new version +git add CHANGELOG.md + +echo 1.0.0 > version.txt +git add -f version.txt + +git commit +---- + +=== Create tag + +An initial release would be tagged as follows: + +[source,console] +---- +git tag -a v1.0.0 -m '' +---- + +=== Push branch and tag + +[source,console] +---- +# push the branch +git push origin release/1.x + +# push the tag +git push origin v1.0.0 +---- + +=== Edit tagged release description on GitHub + +. Navigate to the link:#https://github.com/rnpgp/rnp/releases[Releases] page; + +. Edit the tag that was just pushed; + +. Fill the tag's description with data from the corresponding `CHANGELOG` + entries of the same tag version; + +. Publish the release. + + +== Creating a new release + +Maintaining a release branch involves cherry-picking hotfixes and +similar commits from the `main` branch, while following the rules for +Semantic Versioning. + +The steps below will show the release of version 1.0.1. + +=== Add desired changes + +Cherry-pick the appropriate commits into the appropriate `release/N.x` branch. + +To see what commits are in `main` that are not in the release branch, you +can observe the lines starting with `+` in: + +[source,console] +---- +git cherry -v release/1.x main +---- + +It is often useful to pick a range of commits. For example: + +[source,console] +---- +git checkout release/0.x +git cherry-pick a57b36f^..e23352c +---- + +If there are merge commits in this range, this will not work. +Instead, try: + +[source,console] +---- +git checkout release/0.x +git cherry release/0.x main | grep '^+ ' | cut -c 3-9 | \ + while read commit; do git cherry-pick $commit; done +---- + +From here, you can follow the steps for an initial release, +starting with <<update-changelog-and-version>>. diff --git a/comm/third_party/rnp/docs/installation.adoc b/comm/third_party/rnp/docs/installation.adoc new file mode 100644 index 0000000000..991fa85291 --- /dev/null +++ b/comm/third_party/rnp/docs/installation.adoc @@ -0,0 +1,262 @@ += Installing RNP + +Binaries that will be installed: + +* `rnp` +* `rnpkeys` + + +== On NixOS or Nix package manager + +We provide a Nix package for easy installation on NixOS and any OS with Nix +installed (including Linux and macOS, even NixOS on WSL). + +[source,console] +---- +nix-env -iA nixpkgs.rnp +---- + +== With Nix Flakes + +We provide a Nix flake. + +[source,console] +---- +nix profile install github:rnpgp/rnp +---- + +== On macOS using Homebrew + +We provide a Homebrew tap for easy installation of RNP on macOS. + +[source,console] +---- +brew tap rnpgp/rnp +brew install rnp +---- + +== On RHEL and CentOS via YUM + +We provide pre-built packages for RHEL and CentOS at our YUM repository hosted +at GitHub. + +[source,console] +---- +rpm --import https://github.com/riboseinc/yum/raw/master/ribose-packages.pub +rpm --import https://github.com/riboseinc/yum/raw/master/ribose-packages-next.pub +curl -L https://github.com/riboseinc/yum/raw/master/ribose.repo > /etc/yum.repos.d/ribose.repo +yum install -y rnp +---- + +== On Ubuntu + +Prerequisites: please ensure `git` is installed on the system +[source,console] +---- +# Clone the repository by version tag (or omit it to get the latest sources) +git clone https://github.com/rnpgp/rnp.git -b v0.17.0 + +Please ensure that you clone with submodules if you use a version higher then 0.16.2 +git clone https://github.com/rnpgp/rnp.git --recurse-submodules --shallow-submodules + +# Install required packages +sudo apt install g++-8 cmake libbz2-dev zlib1g-dev libjson-c-dev build-essential python-minimal + +# Download, build and install Botan2 +wget -qO- https://botan.randombit.net/releases/Botan-2.18.2.tar.xz | tar xvJ +cd Botan-2.18.2 +./configure.py --prefix=/usr +make +sudo make install +cd .. + +# CMake encourages building outside of the source directory. +mkdir rnp-build +cd rnp-build + +# Run CMake +cmake -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off ../rnp/ + +# Compile +make + +# Install +sudo make install +---- + +== On Debian + +Prerequisite: please ensure `git` is installed on the system. + +[source,console] +---- +# Clone the repository by version tag (or omit it to get the latest sources) +git clone https://github.com/rnpgp/rnp.git -b v0.17.0 + +Please ensure that you clone with submodules if you use a version higher then 0.16.2 +git clone https://github.com/rnpgp/rnp.git --recurse-submodules --shallow-submodules + +# Enable access to `testing` packages by editing /etc/apt/sources.list +# deb http://deb.debian.org/debian testing main + +# Install required packages +sudo apt install g++-8 cmake libbz2-dev zlib1g-dev libjson-c-dev \ + libbotan-2-dev build-essential + +# Cmake recommend out-of-source builds +mkdir rnp-build +cd rnp-build + +# Cmake it +cmake -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off ../rnp/ + +# Compile and install +sudo make install +---- + +== On Gentoo Linux + +RNP ebuilds are available from an overlay repository named `rnp`. + +=== Using eselect-repository (the current way) + +Prerequisite: ensure `eselect-repository` is installed on your system. + +[source,console] +---- +eselect repository enable rnp +emaint sync -r rnp +emerge -av app-crypt/rnp +---- + +=== Using layman (the old way) + +Prerequisite: ensure `layman` is installed on your system. + +[source,console] +---- +layman -a rnp +layman -s rnp +emerge -av app-crypt/rnp +---- + +== Compile from source + +Clone this repo, or download a release and expand it. + +Enter the source folder and run the following commands: + +[source,console] +---- +cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DBUILD_SHARED_LIBS=on -DBUILD_TESTING=off . + +make install +---- + +== On Windows + +=== Using MSYS/MinGW + +From a clean MSYS2 install, please first update `pacman` and install required +packages via the `msys` console. + +[source,console] +---- +pacman -Syu --noconfirm --needed + +# Most likely you'll need to close msys console and run it again: +pacman -Syu --noconfirm --needed + +# Install packages +pacman --noconfirm -S --needed tar zlib-devel libbz2-devel git automake autoconf libtool automake-wrapper make pkg-config mingw64/mingw-w64-x86_64-cmake mingw64/mingw-w64-x86_64-gcc mingw64/mingw-w64-x86_64-json-c mingw64/mingw-w64-x86_64-libbotan mingw64/mingw-w64-x86_64-python3 +---- + +Then clone the RNP repository and build it. + +Please ensure that you clone with submodules if you use a version higher then 0.16.2 +git clone https://github.com/rnpgp/rnp.git --recurse-submodules --shallow-submodules + +[source,console] +---- +# CMake encourages building outside of the source directory. +mkdir rnp-build +cd rnp-build + +# Add paths to PATH so dependency dll/lib files can be found +export PATH="/c/msys64/mingw64/lib:/c/msys64/mingw64/bin:$PWD/bin:$PATH" + +# Run CMake +cmake -DBUILD_SHARED_LIBS=yes -G "MSYS Makefiles" -DBUILD_TESTING=off ../rnp + +# Compile and install +make && make install +---- + +=== Using Microsoft Visual Studio 2019 and vcpkg + +Install `vcpkg` according to +https://docs.microsoft.com/en-us/cpp/build/install-vcpkg?view=msvc-160&tabs=windows[these instructions]: + +Set the `VCPKG_ROOT` environment variable to the `vcpkg` root folder. + +For botan backend: +[source,console] +---- +vcpkg install --triplet x64-windows bzip2 zlib botan json-c getopt dirent python3[core,enable-shared] +---- + +For openssl backend: +[source,console] +---- +vcpkg install --triplet x64-windows bzip2 zlib botan json-c getopt dirent python3[core,enable-shared] +---- + +If you need to target 32-bit platform you'll need to to replace `x64-windows` with `x86-windows`. + +* The following steps will perform a console build for CMake using Visual Studio 2019 CMake generator: + ++ +-- +[source,console] +---- +cmake -B build -G "Visual Studio 16 2019" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%\scripts\buildsystems\vcpkg.cmake \ + -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=off -DCRYPTO_BACKEND="botan" . +cmake --build . --config Release +cmake --install . +---- +-- +Replace CRYPTO_BACKEND parameter to "openssl" if you target this backend. + +Ensure that the following dependencies are available on path: + +* `librnp.dll` +* `botan.dll` or `libcrypto.dll` depending on target backend and architecture +* `bz2.dll` +* `getopt.dll` +* `json-c.dll` +* `zlib1.dll` + +=== Using Microsoft Visual Studio 2019 and pre-installed libraries + +Install dependencies and make them available either on PATH or using CMAKE_TARGET_PREFIX parameter: + +* Botan(2.14+) or Crypto (OpenSSL 1.1.1+) depending on target backend +* BZip2 +* GetOpt +* JSON-C (0.12.1+) +* ZLIB + +If openssl backend is used note that your environment may have another ("default") openssl installation. +In such case use OPENSSL_ROOT_DIR. + +* The following steps will perform a console build for CMake using Visual Studio 2019 CMake generator: + ++ +-- +[source,console] +---- +cmake -B build -G "Visual Studio 16 2019" -A x64 -DOPENSSL_ROOT_DIR=<openssl root> -DCMAKE_TARGET_PREFIX=<target prefix> \ + -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=off -DCRYPTO_BACKEND="botan" . +cmake --build . --config Release +cmake --install . +---- +-- +Replace CRYPTO_BACKEND parameter to "openssl" if you target this backend, use OPENSSL_ROOT_DIR and CMAKE_TARGET_PREFIX optionally as explained above diff --git a/comm/third_party/rnp/docs/navigation.adoc b/comm/third_party/rnp/docs/navigation.adoc new file mode 100644 index 0000000000..385992cb8f --- /dev/null +++ b/comm/third_party/rnp/docs/navigation.adoc @@ -0,0 +1,18 @@ +--- +items: +- { title: Installation, path: installation/ } +- { title: Command-line usage, path: cli-usage/ } +- { title: C API usage, path: c-usage/ } +- title: Developing RNP + path: develop/ + items: + - { title: "C++ usage", path: develop/cpp-usage/ } + - { title: "Packaging", path: develop/packaging/ } + - { title: "Release workflow", path: develop/release-workflow/ } + # - title: "Acceptance tests" + # path: develop/acceptance-tests/ + # items: + # - { title: "rnpkeys-generate-key", path: develop/acceptance-tests/rnpkeys-generate-key } +--- + += Navigation diff --git a/comm/third_party/rnp/docs/signing-keys.adoc b/comm/third_party/rnp/docs/signing-keys.adoc new file mode 100644 index 0000000000..0ebf7ffe52 --- /dev/null +++ b/comm/third_party/rnp/docs/signing-keys.adoc @@ -0,0 +1,5 @@ + += PGP keys used for signing source code + +The current OpenPGP key used for signing source code for RNP is hosted at +https://www.rnpgp.org/openpgp_keys/[rnpgp.org^]. |