Adjust and document XEP-0373 API

1 files changed, 56 insertions, 10 deletions

diff --git a/src/rexmpp_openpgp.h b/src/rexmpp_openpgp.h
index 1db5717..bed46b3 100644
--- a/src/rexmpp_openpgp.h
+++ b/src/rexmpp_openpgp.h
@@ -2,7 +2,7 @@
    @file rexmpp_openpgp.h
    @brief XEP-0373 routines
    @author defanor <defanor@uberspace.net>
-   @date 2020
+   @date 2020--2021
    @copyright MIT license.
 */
 #ifndef REXMPP_OPENPGP_H
@@ -10,34 +10,80 @@
 
 #include "rexmpp.h"
 
+/**
+   @brief A mode corresponding to XEP-0373's OpenPGP content element.
+ */
+enum rexmpp_ox_mode {
+  REXMPP_OX_SIGN,
+  REXMPP_OX_CRYPT,
+  REXMPP_OX_SIGNCRYPT
+};
+
+/**
+   @brief Checks whether we have all the keys from the list of known
+   keys for a given JID, requests missing ones.
+   @param[in] s ::rexmpp
+   @param[in] jid A JID.
+   @param[in] items An <items> element with <public-keys-list> in it.
+*/
 rexmpp_err_t
 rexmpp_openpgp_check_keys (rexmpp_t *s,
                            const char *jid,
                            xmlNodePtr items);
 
+/**
+   @brief Publishes a key via PEP/pubsub.
+   @param[in] s ::rexmpp
+   @param[in] fp The fingerprint of a key that should be published.
+   @returns ::REXMPP_SUCCESS or an error code.
+*/
 rexmpp_err_t rexmpp_openpgp_publish_key (rexmpp_t *s, const char *fp);
+
+/**
+   @brief Retracts a key from PEP/pubsub.
+   @param[in] s ::rexmpp
+   @param[in] fp The fingerprint of a key that should be deleted.
+*/
 void rexmpp_openpgp_retract_key (rexmpp_t *s, const char *fp);
 
+/**
+   @brief Tries to decrypt and/or verify an OpenPGP message.
+   @param[in] s ::rexmpp
+   @param[in] cipher_base64 An OpenPGP ciphertext.
+   @returns A plaintext message body.
+*/
 xmlNodePtr
 rexmpp_openpgp_decrypt_verify (rexmpp_t *s,
                                const char *cipher_base64);
 
+/**
+   @brief Tries to decrypt and/or verify an OpenPGP message from a
+   <message> element, taking into account its attributes.
+   @param[in] s ::rexmpp
+   @param[in] message A <message> element.
+   @param[out] valid Will be set to 1 if the message appears to be
+   valid.
+   @returns A decrypted message body.
+*/
 xmlNodePtr
 rexmpp_openpgp_decrypt_verify_message (rexmpp_t *s,
                                        xmlNodePtr message,
                                        int *valid);
 
-char *rexmpp_openpgp_encrypt_sign (rexmpp_t *s,
-                                   xmlNodePtr payload,
-                                   const char **recipients);
-
-char *rexmpp_openpgp_encrypt (rexmpp_t *s,
+/**
+   @brief Encodes a message, producing a signed and/or encrypted
+   payload.
+   @param[in] s ::rexmpp
+   @param[in] payload XML payload.
+   @param[in] recipients A NULL-terminated list of recipient JIDs.
+   @param[in] mode ::rexmpp_ox_mode
+   @returns An encoded <openpgp> payload.
+*/
+char *rexmpp_openpgp_payload (rexmpp_t *s,
                               xmlNodePtr payload,
-                              const char **recipients);
+                              const char **recipients,
+                              enum rexmpp_ox_mode mode);
 
-char *rexmpp_openpgp_sign (rexmpp_t *s,
-                           xmlNodePtr payload,
-                           const char **recipients);
 
 /**
    @brief An utility function for setting GPG home directory. An