src/message_api.h
author Volker Birk <vb@pep.foundation>
Thu, 01 Sep 2016 17:55:03 +0200
branchkeysync
changeset 1111 3c46dc58096d
parent 1038 18afd03aedf4
child 1218 748dd3967cb5
permissions -rw-r--r--
merging
     1 #pragma once
     2 
     3 #include "pEpEngine.h"
     4 #include "keymanagement.h"
     5 #include "message.h"
     6 #include "cryptotech.h"
     7 
     8 #ifdef __cplusplus
     9 extern "C" {
    10 #endif
    11 
    12 
    13 bool import_attached_keys(
    14         PEP_SESSION session, 
    15         const message *msg,
    16         identity_list **private_idents
    17     );
    18 void attach_own_key(PEP_SESSION session, message *msg);
    19 PEP_cryptotech determine_encryption_format(message *msg);
    20 void add_opt_field(message *msg, const char *name, const char *value);
    21 
    22 typedef enum _PEP_encrypt_flags {
    23     PEP_encrypt_flag_force_encryption = 0x1
    24 } PEP_encrypt_flags; 
    25 
    26 typedef unsigned int PEP_encrypt_flags_t;
    27 
    28 // encrypt_message() - encrypt message in memory
    29 //
    30 //  parameters:
    31 //      session (in)        session handle
    32 //      src (in)            message to encrypt
    33 //      extra (in)          extra keys for encryption
    34 //      dst (out)           pointer to new encrypted message or NULL on failure
    35 //      enc_format (in)     encrypted format
    36 //      flags (in)          flags to set special encryption features
    37 //
    38 //  return value:
    39 //      PEP_STATUS_OK                   on success
    40 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    41 //		                                could not be found
    42 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    43 //		                                an ambiguous name
    44 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    45 //
    46 //	caveat:
    47 //	    the ownershop of src remains with the caller
    48 //	    the ownership of dst goes to the caller
    49 
    50 DYNAMIC_API PEP_STATUS encrypt_message(
    51         PEP_SESSION session,
    52         message *src,
    53         stringlist_t *extra,
    54         message **dst,
    55         PEP_enc_format enc_format,
    56         PEP_encrypt_flags_t flags
    57     );
    58 
    59 // encrypt_message_for_self() - encrypt message in memory for user's identity only,
    60 //                              ignoring recipients and other identities from
    61 //                              the message
    62 //  parameters:
    63 //      session (in)        session handle
    64 //      target_id (in)      self identity this message should be encrypted for
    65 //      src (in)            message to encrypt
    66 //      dst (out)           pointer to new encrypted message or NULL on failure
    67 //      enc_format (in)     encrypted format
    68 //
    69 //  return value:       (FIXME: This may not be correct or complete)
    70 //      PEP_STATUS_OK                   on success
    71 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    72 //		                                could not be found
    73 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    74 //		                                an ambiguous name
    75 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    76 //
    77 //	caveat:
    78 //	    the ownership of src remains with the caller
    79 //      the ownership of target_id remains w/ caller            
    80 //	    the ownership of dst goes to the caller
    81 //      message is NOT encrypted for identities other than the target_id (and then,
    82 //          only if the target_id refers to self!)
    83 
    84 DYNAMIC_API PEP_STATUS encrypt_message_for_self(
    85         PEP_SESSION session,
    86         pEp_identity* target_id,
    87         message *src,
    88         message **dst,
    89         PEP_enc_format enc_format
    90     );
    91 
    92 typedef enum _PEP_rating {
    93     PEP_rating_undefined = 0,
    94     PEP_rating_cannot_decrypt,
    95     PEP_rating_have_no_key,
    96     PEP_rating_unencrypted,
    97     PEP_rating_unencrypted_for_some,
    98     PEP_rating_unreliable,
    99     PEP_rating_reliable,
   100     PEP_rating_trusted,
   101     PEP_rating_trusted_and_anonymized,
   102     PEP_rating_fully_anonymous,   
   103 
   104     PEP_rating_mistrust = -1,
   105     PEP_rating_b0rken = -2,
   106     PEP_rating_under_attack = -3
   107 } PEP_rating;
   108 
   109 typedef enum _PEP_color {
   110     PEP_color_no_color = 0,
   111     PEP_color_yellow,
   112     PEP_color_green,
   113     PEP_color_red = -1,
   114 } PEP_color;
   115 
   116 // color_from_rating - calculate color from rating
   117 //
   118 //  parameters:
   119 //      rating (in)         rating
   120 //
   121 //  return value:           color representing that rating
   122 
   123 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
   124 
   125 typedef enum _PEP_decrypt_flags {
   126     PEP_decrypt_flag_own_private_key = 0x1
   127 } PEP_decrypt_flags; 
   128 
   129 typedef unsigned int PEP_decrypt_flags_t;
   130 
   131 // decrypt_message() - decrypt message in memory
   132 //
   133 //  parameters:
   134 //      session (in)        session handle
   135 //      src (in)            message to decrypt
   136 //      dst (out)           pointer to new decrypted message or NULL on failure
   137 //      keylist (out)       stringlist with keyids
   138 //      color (out)         color for the message
   139 //      flags (out)         flags to signal special decryption features
   140 //
   141 //  return value:
   142 //      error status or PEP_STATUS_OK on success
   143 //
   144 //	caveat:
   145 //	    the ownership of src remains with the caller
   146 //	    the ownership of dst goes to the caller
   147 //	    the ownership of keylist goes to the caller
   148 //	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   149 //	    dst to NULL
   150 
   151 DYNAMIC_API PEP_STATUS decrypt_message(
   152         PEP_SESSION session,
   153         message *src,
   154         message **dst,
   155         stringlist_t **keylist,
   156         PEP_rating *rating,
   157         PEP_decrypt_flags_t *flags
   158 );
   159 
   160 // own_message_private_key_details() - details on own key in own message
   161 //
   162 //  parameters:
   163 //      session (in)        session handle
   164 //      msg (in)            message to decrypt
   165 //      ident (out)         identity containing uid, address and fpr of key
   166 //
   167 //  note:
   168 //      In order to obtain details about key to be possibly imported
   169 //      as a replacement of key currently used as own identity, 
   170 //      application passes message that have been previously flagged by 
   171 //      decrypt_message() as own message containing own key to this function
   172 //
   173 //  return value:
   174 //      error status or PEP_STATUS_OK on success
   175 //
   176 //	caveat:
   177 //	    the ownership of msg remains with the caller
   178 //	    the ownership of ident goes to the caller
   179 //	    msg MUST be encrypted so that this function can check own signature
   180 
   181 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   182         PEP_SESSION session,
   183         message *msg,
   184         pEp_identity **ident 
   185 );
   186 
   187 // outgoing_message_rating() - get rating for an outgoing message
   188 //
   189 //  parameters:
   190 //      session (in)        session handle
   191 //      msg (in)            message to get the rating for
   192 //      rating (out)        rating for the message
   193 //
   194 //  return value:
   195 //      error status or PEP_STATUS_OK on success
   196 //
   197 //  caveat:
   198 //      msg->from must point to a valid pEp_identity
   199 //      msg->dir must be PEP_dir_outgoing
   200 //      the ownership of msg remains with the caller
   201 
   202 DYNAMIC_API PEP_STATUS outgoing_message_rating(
   203         PEP_SESSION session,
   204         message *msg,
   205         PEP_rating *rating
   206     );
   207 
   208 
   209 // identity_rating() - get rating for a single identity
   210 //
   211 //  parameters:
   212 //      session (in)        session handle
   213 //      ident (in)          identity to get the rating for
   214 //      rating (out)        rating for the identity
   215 //
   216 //  return value:
   217 //      error status or PEP_STATUS_OK on success
   218 //
   219 //  caveat:
   220 //      the ownership of ident remains with the caller
   221 
   222 DYNAMIC_API PEP_STATUS identity_rating(
   223         PEP_SESSION session,
   224         pEp_identity *ident,
   225         PEP_rating *rating
   226     );
   227 
   228 
   229 // get_binary_path() - retrieve path of cryptotech binary if available
   230 //
   231 //  parameters:
   232 //      tech (in)           cryptotech to get the binary for
   233 //      path (out)          path to cryptotech binary or NULL if not available
   234 //                          **path is owned by the library, do not change it!
   235 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   236 
   237 
   238 #ifdef __cplusplus
   239 }
   240 #endif
   241