diff options
Diffstat (limited to 'openpgp-ffi/include/sequoia/openpgp')
-rw-r--r-- | openpgp-ffi/include/sequoia/openpgp/crypto.h | 5 | ||||
-rw-r--r-- | openpgp-ffi/include/sequoia/openpgp/types.h | 473 |
2 files changed, 475 insertions, 3 deletions
diff --git a/openpgp-ffi/include/sequoia/openpgp/crypto.h b/openpgp-ffi/include/sequoia/openpgp/crypto.h index 00d49466..530208a0 100644 --- a/openpgp-ffi/include/sequoia/openpgp/crypto.h +++ b/openpgp-ffi/include/sequoia/openpgp/crypto.h @@ -1,6 +1,8 @@ #ifndef SEQUOIA_OPENPGP_CRYPTO_H #define SEQUOIA_OPENPGP_CRYPTO_H +#include <sequoia/openpgp/types.h> + typedef struct pgp_mpi *pgp_mpi_t; /*/ @@ -26,9 +28,6 @@ void pgp_signer_free (pgp_signer_t s); /*/ typedef struct pgp_key_pair *pgp_key_pair_t; -/* Forward declaration. */ -typedef struct pgp_key *pgp_key_t; - /*/ /// Creates a new key pair. /*/ diff --git a/openpgp-ffi/include/sequoia/openpgp/types.h b/openpgp-ffi/include/sequoia/openpgp/types.h new file mode 100644 index 00000000..8631155f --- /dev/null +++ b/openpgp-ffi/include/sequoia/openpgp/types.h @@ -0,0 +1,473 @@ +#ifndef SEQUOIA_OPENPGP_TYPES_H +#define SEQUOIA_OPENPGP_TYPES_H + +/*/ +/// Holds a fingerprint. +/*/ +typedef struct pgp_fingerprint *pgp_fingerprint_t; + +/*/ +/// Holds a KeyID. +/*/ +typedef struct pgp_keyid *pgp_keyid_t; + +/*/ +/// Specifies the type of data (see [RFC 4880, section 6.2]). +/// +/// [RFC 4880, section 6.2]: https://tools.ietf.org/html/rfc4880#section-6.2 +/*/ +typedef enum pgp_armor_kind { + /*/ + /// When reading an Armored file, accept any type. + /*/ + PGP_ARMOR_KIND_ANY, + + /*/ + /// A generic OpenPGP message. + /*/ + PGP_ARMOR_KIND_MESSAGE, + + /*/ + /// A transferable public key. + /*/ + PGP_ARMOR_KIND_PUBLICKEY, + + /*/ + /// A transferable secret key. + /*/ + PGP_ARMOR_KIND_SECRETKEY, + + /*/ + /// A detached signature. + /*/ + PGP_ARMOR_KIND_SIGNATURE, + + /*/ + /// A generic file. This is a GnuPG extension. + /*/ + PGP_ARMOR_KIND_FILE, + + /* Dummy value to make sure the enumeration has a defined size. Do + not use this value. */ + PGP_ARMOR_KIND_FORCE_WIDTH = INT_MAX, +} pgp_armor_kind_t; + +/*/ +/// Represents a (key, value) pair in an armor header. +/*/ +typedef struct pgp_armor_header { + char *key; + char *value; +} *pgp_armor_header_t; + + +/*/ +/// Holds a revocation status. +/*/ +typedef struct pgp_revocation_status *pgp_revocation_status_t; + +typedef enum pgp_revocation_status_variant { + /*/ + /// The key is definitely revoked. + /// + /// All self-revocations are returned, the most recent revocation + /// first. + /*/ + PGP_REVOCATION_STATUS_REVOKED, + + /*/ + /// We have a third-party revocation certificate that is allegedly + /// from a designated revoker, but we don't have the designated + /// revoker's key to check its validity. + /// + /// All such certificates are returned. The caller must check + /// them manually. + /*/ + PGP_REVOCATION_STATUS_COULD_BE, + + /*/ + /// The key does not appear to be revoked, but perhaps an attacker + /// has performed a DoS, which prevents us from seeing the + /// revocation certificate. + /*/ + PGP_REVOCATION_STATUS_NOT_AS_FAR_AS_WE_KNOW, + + /* Dummy value to make sure the enumeration has a defined size. Do + not use this value. */ + PGP_REVOCATION_STATUS_FORCE_WIDTH = INT_MAX, +} pgp_revocation_status_variant_t; + +typedef enum pgp_reason_for_revocation { + /*/ + /// No reason specified (key revocations or cert revocations) + /*/ + PGP_REASON_FOR_REVOCATION_UNSPECIFIED, + + /*/ + /// Key is superseded (key revocations) + /*/ + PGP_REASON_FOR_REVOCATION_KEY_SUPERSEDED, + + /*/ + /// Key material has been compromised (key revocations) + /*/ + PGP_REASON_FOR_REVOCATION_KEY_COMPROMISED, + + /*/ + /// Key is retired and no longer used (key revocations) + /*/ + PGP_REASON_FOR_REVOCATION_KEY_RETIRED, + + /*/ + /// User ID information is no longer valid (cert revocations) + /*/ + PGP_REASON_FOR_REVOCATION_UID_RETIRED, + + /* Dummy value to make sure the enumeration has a defined size. Do + not use this value. */ + PGP_REASON_FOR_REVOCATION_FORCE_WIDTH = INT_MAX, +} pgp_reason_for_revocation_t; + +typedef enum pgp_public_key_algorithm { + /*/ + /// RSA (Encrypt or Sign) + /*/ + PGP_PUBLIC_KEY_ALGO_RSA_ENCRYPT_SIGN, + + /*/ + /// RSA Encrypt-Only + /*/ + PGP_PUBLIC_KEY_ALGO_RSA_ENCRYPT, + + /*/ + /// RSA Sign-Only + /*/ + PGP_PUBLIC_KEY_ALGO_RSA_SIGN, + + /*/ + /// Elgamal (Encrypt-Only) + /*/ + PGP_PUBLIC_KEY_ALGO_ELGAMAL_ENCRYPT, + + /*/ + /// DSA (Digital Signature Algorithm) + /*/ + PGP_PUBLIC_KEY_ALGO_DSA, + + /*/ + /// Elliptic curve DH + /*/ + PGP_PUBLIC_KEY_ALGO_ECDH, + + /*/ + /// Elliptic curve DSA + /*/ + PGP_PUBLIC_KEY_ALGO_ECDSA, + + /*/ + /// Elgamal (Encrypt or Sign) + /*/ + PGP_PUBLIC_KEY_ALGO_ELGAMAL_ENCRYPT_SIGN, + + /*/ + /// "Twisted" Edwards curve DSA + /*/ + PGP_PUBLIC_KEY_ALGO_EDDSA, + + /* Dummy value to make sure the enumeration has a defined size. Do + not use this value. */ + PGP_PUBLIC_KEY_ALGO_FORCE_WIDTH = INT_MAX, +} sq_public_key_algo_t; + +/*/ +/// The OpenPGP packet tags as defined in [Section 4.3 of RFC 4880]. +/// +/// [Section 4.3 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-4.3 +/// +/// The values correspond to the serialized format. The packet types +/// named `UnassignedXX` are not in use as of RFC 4880. +/// +/// Use [`Tag::from_numeric`] to translate a numeric value to a symbolic +/// one. +/// +/// [`Tag::from_numeric`]: enum.Tag.html#method.from_numeric +/*/ +typedef enum pgp_tag { + PGP_TAG_RESERVED0 = 0, + /* Public-Key Encrypted Session Key Packet. */ + PGP_TAG_PKESK = 1, + PGP_TAG_SIGNATURE = 2, + /* Symmetric-Key Encrypted Session Key Packet. */ + PGP_TAG_SKESK = 3, + /* One-Pass Signature Packet. */ + PGP_TAG_ONE_PASS_SIG = 4, + PGP_TAG_SECRET_KEY = 5, + PGP_TAG_PUBLIC_KEY = 6, + PGP_TAG_SECRET_SUBKEY = 7, + PGP_TAG_COMPRESSED_DATA = 8, + /* Symmetrically Encrypted Data Packet. */ + PGP_TAG_SED = 9, + PGP_TAG_MARKER = 10, + PGP_TAG_LITERAL = 11, + PGP_TAG_TRUST = 12, + PGP_TAG_USER_ID = 13, + PGP_TAG_PUBLIC_SUBKEY = 14, + + PGP_TAG_UNASSIGNED15 = 15, + PGP_TAG_UNASSIGNED16 = 16, + + PGP_TAG_USER_ATTRIBUTE = 17, + /* Sym. Encrypted and Integrity Protected Data Packet. */ + PGP_TAG_SEIP = 18, + /* Modification Detection Code Packet. */ + PGP_TAG_MDC = 19, + + /* Unassigned packets (as of RFC4880). */ + PGP_TAG_UNASSIGNED20 = 20, + PGP_TAG_UNASSIGNED21 = 21, + PGP_TAG_UNASSIGNED22 = 22, + PGP_TAG_UNASSIGNED23 = 23, + PGP_TAG_UNASSIGNED24 = 24, + PGP_TAG_UNASSIGNED25 = 25, + PGP_TAG_UNASSIGNED26 = 26, + PGP_TAG_UNASSIGNED27 = 27, + PGP_TAG_UNASSIGNED28 = 28, + PGP_TAG_UNASSIGNED29 = 29, + + PGP_TAG_UNASSIGNED30 = 30, + PGP_TAG_UNASSIGNED31 = 31, + PGP_TAG_UNASSIGNED32 = 32, + PGP_TAG_UNASSIGNED33 = 33, + PGP_TAG_UNASSIGNED34 = 34, + PGP_TAG_UNASSIGNED35 = 35, + PGP_TAG_UNASSIGNED36 = 36, + PGP_TAG_UNASSIGNED37 = 37, + PGP_TAG_UNASSIGNED38 = 38, + PGP_TAG_UNASSIGNED39 = 39, + + PGP_TAG_UNASSIGNED40 = 40, + PGP_TAG_UNASSIGNED41 = 41, + PGP_TAG_UNASSIGNED42 = 42, + PGP_TAG_UNASSIGNED43 = 43, + PGP_TAG_UNASSIGNED44 = 44, + PGP_TAG_UNASSIGNED45 = 45, + PGP_TAG_UNASSIGNED46 = 46, + PGP_TAG_UNASSIGNED47 = 47, + PGP_TAG_UNASSIGNED48 = 48, + PGP_TAG_UNASSIGNED49 = 49, + + PGP_TAG_UNASSIGNED50 = 50, + PGP_TAG_UNASSIGNED51 = 51, + PGP_TAG_UNASSIGNED52 = 52, + PGP_TAG_UNASSIGNED53 = 53, + PGP_TAG_UNASSIGNED54 = 54, + PGP_TAG_UNASSIGNED55 = 55, + PGP_TAG_UNASSIGNED56 = 56, + PGP_TAG_UNASSIGNED57 = 57, + PGP_TAG_UNASSIGNED58 = 58, + PGP_TAG_UNASSIGNED59 = 59, + + /* Experimental packets. */ + PGP_TAG_PRIVATE0 = 60, + PGP_TAG_PRIVATE1 = 61, + PGP_TAG_PRIVATE2 = 62, + PGP_TAG_PRIVATE3 = 63, +} pgp_tag_t; + +/*/ +/// Opaque types for all the Packets that Sequoia understands. +/*/ +typedef struct pgp_unknown *pgp_unknown_t; +typedef struct pgp_signature *pgp_signature_t; +typedef struct pgp_one_pass_sig *pgp_one_pass_sig_t; +typedef struct pgp_key *pgp_key_t; +typedef struct pgp_user_id *pgp_user_id_t; +typedef struct pgp_user_attribute *pgp_user_attribute_t; +typedef struct pgp_literal *pgp_literal_t; +typedef struct pgp_compressed_data *pgp_compressed_data_t; +typedef struct pgp_pkesk *pgp_pkesk_t; +typedef struct pgp_skesk *pgp_skesk_t; +typedef struct pgp_seip *pgp_seip_t; +typedef struct pgp_mdc *pgp_mdc_t; + +/*/ +/// The OpenPGP packets that Sequoia understands. +/// +/// The different OpenPGP packets are detailed in [Section 5 of RFC 4880]. +/// +/// The `Unknown` packet allows Sequoia to deal with packets that it +/// doesn't understand. The `Unknown` packet is basically a binary +/// blob that includes the packet's tag. +/// +/// The unknown packet is also used for packets that are understood, +/// but use unsupported options. For instance, when the packet parser +/// encounters a compressed data packet with an unknown compression +/// algorithm, it returns the packet in an `Unknown` packet rather +/// than a `CompressedData` packet. +/// +/// [Section 5 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-5 +/*/ +typedef union pgp_packet { + pgp_unknown_t unknown; + pgp_signature_t signature; + pgp_one_pass_sig_t one_pass_sig; + pgp_key_t key; + pgp_user_id_t user_id; + pgp_user_attribute_t user_attribute; + pgp_literal_t literal; + pgp_compressed_data_t compressed_data; + pgp_pkesk_t pkesk; + pgp_skesk_t skesk; + pgp_seip_t seip; + pgp_mdc_t mdc; +} pgp_packet_t; + +/*/ +/// A low-level OpenPGP message parser. +/// +/// A `PacketParser` provides a low-level, iterator-like interface to +/// parse OpenPGP messages. +/// +/// For each iteration, the user is presented with a [`Packet`] +/// corresponding to the last packet, a `PacketParser` for the next +/// packet, and their positions within the message. +/// +/// Using the `PacketParser`, the user is able to configure how the +/// new packet will be parsed. For instance, it is possible to stream +/// the packet's contents (a `PacketParser` implements the +/// `std::io::Read` and the `BufferedReader` traits), buffer them +/// within the [`Packet`], or drop them. The user can also decide to +/// recurse into the packet, if it is a container, instead of getting +/// the following packet. +/*/ +typedef struct pgp_packet_parser *pgp_packet_parser_t; + +/*/ +/// Like an `Option<PacketParser>`, but the `None` variant +/// (`PacketParserEOF`) contains some summary information. +/*/ +typedef struct pgp_packet_parser_result *pgp_packet_parser_result_t; + +/*/ +/// The `None` variant of a `PacketParserResult`. +/*/ +typedef struct pgp_packet_parser_eof *pgp_packet_parser_eof_t; + +/*/ +/// A `PacketPile` holds a deserialized OpenPGP message. +/*/ +typedef struct pgp_packet_pile *pgp_packet_pile_t; + +/*/ +/// A `UserIDBinding`. +/*/ +typedef struct pgp_user_id_binding *pgp_user_id_binding_t; + +/*/ +/// An iterator over `UserIDBinding`s. +/*/ +typedef struct pgp_user_id_binding_iter *pgp_user_id_binding_iter_t; + +/*/ +/// An iterator over keys in a TPK. +/*/ +typedef struct pgp_tpk_key_iter *pgp_tpk_key_iter_t; + +/*/ +/// A transferable public key (TPK). +/// +/// A TPK (see [RFC 4880, section 11.1]) can be used to verify +/// signatures and encrypt data. It can be stored in a keystore and +/// uploaded to keyservers. +/// +/// [RFC 4880, section 11.1]: https://tools.ietf.org/html/rfc4880#section-11.1 +/*/ +typedef struct pgp_tpk *pgp_tpk_t; + + +/*/ +/// A transferable secret key (TSK). +/// +/// A TSK (see [RFC 4880, section 11.2]) can be used to create +/// signatures and decrypt data. +/// +/// [RFC 4880, section 11.2]: https://tools.ietf.org/html/rfc4880#section-11.2 +/*/ +typedef struct pgp_tsk *pgp_tsk_t; + + +typedef enum pgp_tpk_cipher_suite { + /*/ + /// EdDSA and ECDH over Curve25519 with SHA512 and AES256. + /*/ + PGP_TPK_CIPHER_SUITE_CV25519, + + /*/ + /// 3072 bit RSA with SHA512 and AES256. + /*/ + PGP_TPK_CIPHER_SUITE_RSA3K, + + /* Dummy value to make sure the enumeration has a defined size. Do + not use this value. */ + PGP_TPK_CIPHER_SUITE_FORCE_WIDTH = INT_MAX, +} pgp_tpk_cipher_suite_t; + +typedef struct pgp_tpk_builder *pgp_tpk_builder_t; + +typedef struct pgp_writer_stack *pgp_writer_stack_t; + +/*/ +/// Specifies whether to encrypt for archival purposes or for +/// transport. +/*/ +typedef enum pgp_encryption_mode { + /*/ + /// Encrypt data for long-term storage. + /// + /// This should be used for things that should be decryptable for + /// a long period of time, e.g. backups, archives, etc. + /*/ + PGP_ENCRYPTION_MODE_AT_REST = 0, + + /*/ + /// Encrypt data for transport. + /// + /// This should be used to protect a message in transit. The + /// recipient is expected to take additional steps if she wants to + /// be able to decrypt it later on, e.g. store the decrypted + /// session key, or re-encrypt the session key with a different + /// key. + /*/ + PGP_ENCRYPTION_MODE_FOR_TRANSPORT = 1, +} pgp_encryption_mode_t; + +typedef struct pgp_secret *pgp_secret_t; + +typedef struct pgp_verification_results *pgp_verification_results_t; +typedef struct pgp_verification_result *pgp_verification_result_t; + +typedef enum pgp_verification_result_code { + PGP_VERIFICATION_RESULT_CODE_GOOD_CHECKSUM = 1, + PGP_VERIFICATION_RESULT_CODE_MISSING_KEY = 2, + PGP_VERIFICATION_RESULT_CODE_BAD_CHECKSUM = 3, + + /* Dummy value to make sure the enumeration has a defined size. Do + not use this value. */ + PGP_VERIFICATION_RESULT_CODE_FORCE_WIDTH = INT_MAX, +} pgp_verification_result_code_t; + +typedef pgp_status_t (*pgp_sequoia_decrypt_get_public_keys_cb_t) (void *, + pgp_keyid_t *, size_t, + pgp_tpk_t **, size_t *, + void (**free)(void *)); + +typedef pgp_status_t (*pgp_sequoia_decrypt_get_secret_keys_cb_t) (void *, + pgp_pkesk_t *, size_t, + pgp_skesk_t *, size_t, + pgp_secret_t *); + +typedef pgp_status_t (*pgp_sequoia_decrypt_check_signatures_cb_t) (void *, + pgp_verification_results_t, + size_t); + +#endif |