src/blacklist.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Thu, 29 Oct 2020 22:28:23 +0100
branchdoxygen_doc
changeset 5169 f4b476b218e4
parent 5168 aa4b1c977152
permissions -rw-r--r--
changes to documentation for sync generation (not yet complete)
     1 /**
     2  * @file    blacklist.h
     3  * @brief   Functions for maintaining a key blacklist for OpenPGP keys
     4  *          (i.e. keys received from OpenPGP partners). This is currently
     5  *          used by users when an OpenPGP partner has indicated that they
     6  *          do not want us to use a particular key we may have for them.
     7  *          This is marked as deprecated because we want users to use
     8  *          key reset instead, and this code will be in fact removed
     9  *          in Release 2.2.0 when key election is also removed.
    10  *
    11  * @deprecated These files are still in use as of Release 2.1 and will be removed with key election removal.
    12  *
    13  * @license GNU General Public License 3.0 - see LICENSE.txt
    14  */
    15 
    16 #pragma once
    17 
    18 #include "pEpEngine.h"
    19 
    20 #ifdef __cplusplus
    21 extern "C" {
    22 #endif
    23 
    24 /**
    25  *  <!--       blacklist_add()       -->
    26  *
    27  *  @deprecated As of Release 2.2.0
    28  *
    29  *  @brief Add to blacklist
    30  *  
    31  *  @param[in]   session    session to use
    32  *  @param[in]   fpr        fingerprint of key to blacklist
    33  *  
    34  *  @warning there is no point in blacklisting an own key; for any own
    35  *           identity, this will be ignored. The correct function to use
    36  *           for own keys in this event is "key_reset_trust".
    37  *           Also, this is only effective for OpenPGP-level trust. If
    38  *           this key is for a pEp user, the blacklist is ignored.
    39  *  
    40  */
    41 
    42 DYNAMIC_API PEP_STATUS blacklist_add(PEP_SESSION session, const char *fpr);
    43 
    44 
    45 /**
    46  *  <!--       blacklist_delete()       -->
    47  *
    48  *  @deprecated As of Release 2.2.0
    49  *
    50  *  @brief Delete from blacklist
    51  *  
    52  *  @param[in]   session    session to use
    53  *  @param[in]   fpr        fingerprint of key to be removed from blacklist
    54  *  
    55  *  
    56  */
    57 
    58 DYNAMIC_API PEP_STATUS blacklist_delete(PEP_SESSION session, const char *fpr);
    59 
    60 
    61 /**
    62  *  <!--       blacklist_is_listed()       -->
    63  *
    64  *  @deprecated As of Release 2.2.0
    65  *
    66  *  @brief Is listed in blacklist
    67  *  
    68  *  @param[in]   session    session to use
    69  *  @param[in]   fpr        fingerprint of key to blacklist
    70  *  @param[out]  bool       flags if key is blacklisted
    71  *  
    72  *  
    73  */
    74 
    75 DYNAMIC_API PEP_STATUS blacklist_is_listed(
    76         PEP_SESSION session,
    77         const char *fpr,
    78         bool *listed
    79     );
    80 
    81 
    82 /**
    83  *  <!--       blacklist_retrieve()       -->
    84  *
    85  *  @deprecated As of Release 2.2.0
    86  *
    87  *  @brief Retrieve full blacklist of key fingerprints
    88  *  
    89  *  @param[in]   session      session to use
    90  *  @param[out]  blacklist    copy of blacklist
    91  *  
    92  *  @ownership the ownership of the copy of blacklist goes to the caller
    93  *  
    94  */
    95 
    96 DYNAMIC_API PEP_STATUS blacklist_retrieve(
    97         PEP_SESSION session,
    98         stringlist_t **blacklist
    99     );
   100 
   101 
   102 #ifdef __cplusplus
   103 }
   104 #endif
   105