You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
358 lines
10 KiB
358 lines
10 KiB
/**
|
|
* @file rating_api.h
|
|
* @brief rating functions
|
|
* @license GNU General Public License 3.0 - see LICENSE.txt
|
|
*/
|
|
|
|
#ifndef RATING_API_H
|
|
#define RATING_API_H
|
|
|
|
|
|
#include "message.h"
|
|
#include "stringpair.h"
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
/**
|
|
* @enum PEP_rating
|
|
*
|
|
* @brief TODO
|
|
*
|
|
*/
|
|
typedef enum _PEP_rating {
|
|
PEP_rating_undefined = 0,
|
|
|
|
// no color
|
|
|
|
PEP_rating_cannot_decrypt = 1,
|
|
PEP_rating_have_no_key = 2,
|
|
PEP_rating_unencrypted = 3,
|
|
PEP_rating_unreliable = 5,
|
|
|
|
PEP_rating_b0rken = -2,
|
|
|
|
// yellow
|
|
|
|
PEP_rating_reliable = 6,
|
|
|
|
// green
|
|
|
|
PEP_rating_trusted = 7,
|
|
PEP_rating_trusted_and_anonymized = 8,
|
|
PEP_rating_fully_anonymous = 9,
|
|
|
|
// red
|
|
|
|
PEP_rating_mistrust = -1,
|
|
PEP_rating_under_attack = -3
|
|
} PEP_rating;
|
|
|
|
|
|
/**
|
|
* @internal
|
|
*
|
|
* <!-- rating_to_string() -->
|
|
*
|
|
* @brief TODO
|
|
*
|
|
* @param[in] rating PEP_rating
|
|
*
|
|
*/
|
|
const char * rating_to_string(PEP_rating rating);
|
|
|
|
|
|
/**
|
|
* <!-- rating_from_comm_type() -->
|
|
*
|
|
* @brief Get the rating for a comm type
|
|
*
|
|
* @param[in] ct the comm type to deliver the rating for
|
|
*
|
|
* @retval PEP_rating rating value for comm type ct
|
|
*
|
|
*
|
|
*/
|
|
|
|
DYNAMIC_API PEP_rating rating_from_comm_type(PEP_comm_type ct);
|
|
|
|
|
|
/**
|
|
* <!-- add_rating() -->
|
|
*
|
|
* @brief add two ratings together
|
|
*
|
|
* @param[in] rating1 rating to add to
|
|
* @param[in] rating2 rating added
|
|
*
|
|
* @retval PEP_rating rating value for rating1 + rating2
|
|
*
|
|
*
|
|
*/
|
|
|
|
DYNAMIC_API PEP_rating add_rating(PEP_rating rating1, PEP_rating rating2);
|
|
|
|
|
|
typedef PEP_STATUS (*channel_rating_t)(
|
|
PEP_SESSION session, pEp_identity *ident, PEP_rating *rating);
|
|
|
|
/**
|
|
* <!-- rating_of_new_channel() -->
|
|
*
|
|
* @brief get the rating for a new channel to a communication partner
|
|
* outgoing messages are rated using this
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in,out] ident identity to calculate the rating for
|
|
* @param[out] rating calculated rating
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning this function calls update_identity() on the stored identity
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS rating_of_new_channel(
|
|
PEP_SESSION session,
|
|
pEp_identity *ident,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
/**
|
|
* <!-- last_rating_of_new_channel() -->
|
|
*
|
|
* @brief get the rating of a channel to a communication partner based on last
|
|
* calculated comm_type
|
|
* this is for fast outgoing message preview ratings
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in,out] ident identity to calculate the rating for
|
|
* @param[out] rating calculated rating
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning this function uses a given .comm_type
|
|
* this function calls get_identity() if .comm_type is not given
|
|
* .address and .user_id must be given for a stored contact
|
|
* .address must be given if the identity is not from a stored contact
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS last_rating_of_new_channel(
|
|
PEP_SESSION session,
|
|
pEp_identity *ident,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
/**
|
|
* <!-- rating_of_existing_channel() -->
|
|
*
|
|
* @brief get the rating for an existing channel to a communication partner
|
|
* incoming messages are rated using this
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in] ident identity to calculate the rating for
|
|
* @param[out] rating calculated rating
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning this function does not call update_identity() and expects .fpr
|
|
* being preset to comm_partner's key used in this channel
|
|
* .address and .user_id must be given for a stored contact
|
|
* .address must be given if the identity is not from a stored contact
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS rating_of_existing_channel(
|
|
PEP_SESSION session,
|
|
pEp_identity *ident,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
/**
|
|
* <!-- outgoing_message_rating() -->
|
|
*
|
|
* @brief Get rating for an outgoing message
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in] msg message to get the rating for
|
|
* @param[out] rating rating for the message
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning msg->from must point to a valid pEp_identity
|
|
* msg->dir must be PEP_dir_outgoing
|
|
* the ownership of msg remains with the caller
|
|
*
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS outgoing_message_rating(
|
|
PEP_SESSION session,
|
|
message *msg,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
/**
|
|
* <!-- outgoing_message_rating_preview() -->
|
|
*
|
|
* @brief Get rating preview
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in] msg message to get the rating for
|
|
* @param[out] rating rating preview for the message
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning msg->from must point to a valid pEp_identity
|
|
* msg->dir must be PEP_dir_outgoing
|
|
* the ownership of msg remains with the caller
|
|
*
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS outgoing_message_rating_preview(
|
|
PEP_SESSION session,
|
|
message *msg,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
/** @internal
|
|
*
|
|
* <!-- decrypt_rating() -->
|
|
*/
|
|
|
|
PEP_rating decrypt_rating(PEP_STATUS status);
|
|
|
|
|
|
/**
|
|
* @internal
|
|
*
|
|
* <!-- get_receiverRating() -->
|
|
*
|
|
* @brief get a precalculated and stored rating from trusted server
|
|
*
|
|
* @param[in] session PEP_SESSION
|
|
* @param[in] *msg message
|
|
* @param[in] *rating PEP_rating
|
|
*
|
|
*/
|
|
PEP_STATUS get_receiverRating(PEP_SESSION session, message *msg, PEP_rating *rating);
|
|
|
|
|
|
/**
|
|
* @internal
|
|
*
|
|
* <!-- set_receiverRating() -->
|
|
*
|
|
* @brief set a precalculated rating for storing on trusted server
|
|
*
|
|
* @param[in] session PEP_SESSION
|
|
* @param[in] *msg message
|
|
* @param[in] rating PEP_rating
|
|
*
|
|
*/
|
|
PEP_STATUS set_receiverRating(PEP_SESSION session, message *msg, PEP_rating rating);
|
|
|
|
|
|
/**
|
|
* <!-- incoming_message_rating() -->
|
|
*
|
|
* @brief Get rating of an incoming message
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in] src encrypted version of message to get the rating for
|
|
* @param[in] dst decrypted version of message to get the rating for
|
|
* @param[in] known_keys list of fprs of keys known to be used to encrypt src
|
|
* first key MUST be the sender key; if no sender key
|
|
* can be identified the list MUST be empty
|
|
* in case the message was unencrypted and the
|
|
* sender key was identified this MUST have
|
|
* exactly one element
|
|
* @param[in] extra_keys extra keys declared by the sender
|
|
* @param[in] decrypt_status return value of decrypt_and_verify()
|
|
* for a partitioned message:
|
|
* if ANY of the parts are have an error value
|
|
* then the first error value of the parts
|
|
* if ANY of the parts are PEP_UNENCRYPTED
|
|
* then PEP_UNENCRYPTED
|
|
* if ANY of the parts are PEP_DECRYPTED then
|
|
* PEP_DECRYPTED
|
|
*
|
|
* @param[out] rating rating for the message
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning src->from must point to a valid pEp_identity
|
|
* src->dir must be PEP_dir_incoming
|
|
* src->enc_format must be set to the actual encryption format
|
|
* dst->_sender_fpr must be set if available
|
|
* dst->to[*].fpr and dst[*].fpr should be set to the keys used for
|
|
* recipients, respectively
|
|
* extra_keys are pairs (name, fpr)
|
|
* decrypt_status must be PEP_VERFIY_DIFFERENT_KEYS in case of a
|
|
* partitioned format and there is no guarantee that the sender key
|
|
* was being used to sign all partitions
|
|
*
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS incoming_message_rating(
|
|
PEP_SESSION session,
|
|
const message *src,
|
|
const message *dst,
|
|
const stringlist_t *known_keys,
|
|
const stringpair_list_t *extra_keys,
|
|
PEP_STATUS decrypt_status,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
/**
|
|
* <!-- sent_message_rating() -->
|
|
*
|
|
* @brief Get rating of a message, which was encrypted to be sent
|
|
*
|
|
* @param[in] session session handle
|
|
* @param[in] src encrypted version of message to get the rating for
|
|
* @param[in] dst decrypted version of message to get the rating for
|
|
* @param[in] known_keys list of fprs of keys known to be used to encrypt src
|
|
* @param[in] extra_keys extra keys declared by the sender
|
|
* @param[in] decrypt_status return value of decrypt_and_verify()
|
|
* @param[out] rating rating for the message
|
|
*
|
|
* @retval error status or PEP_STATUS_OK on success
|
|
*
|
|
* @warning src->from must point to a valid pEp_identity
|
|
* src->dir must be PEP_dir_outgoing
|
|
* src->enc_format must be set to the actual encryption format
|
|
* dst->_sender_fpr must be set if available
|
|
* dst->to[*].fpr and dst[*].fpr should be set to the keys used for
|
|
* recipients, respectively
|
|
* extra_keys are pairs (name, fpr)
|
|
* decrypt_status must be PEP_VERFIY_DIFFERENT_KEYS in case of a
|
|
* partitioned format and there is no guarantee that the sender key
|
|
* was being used to sign all partitions
|
|
*
|
|
*/
|
|
|
|
DYNAMIC_API PEP_STATUS sent_message_rating(
|
|
PEP_SESSION session,
|
|
const message *src,
|
|
const message *dst,
|
|
const stringlist_t *known_keys,
|
|
const stringpair_list_t *extra_keys,
|
|
PEP_STATUS decrypt_status,
|
|
PEP_rating *rating
|
|
);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // RATING_API_H
|
|
|