Revision control
Copy as Markdown
Other Tools
= 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
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
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
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
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
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
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
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
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`.