src/message_api.h
author Krista Grothoff <krista@pep-project.org>
Sat, 24 Sep 2016 18:09:18 +0200
branchENGINE-27
changeset 1185 4b01328f3cf2
parent 1034 1ec3384548cb
child 1038 18afd03aedf4
child 1126 129b561095a6
permissions -rw-r--r--
ENGINE-27: update_identity no longer pays attention to the input identity's fpr, but pulls one from elect_pubkey.
     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 
    21 // encrypt_message() - encrypt message in memory
    22 //
    23 //  parameters:
    24 //      session (in)        session handle
    25 //      src (in)            message to encrypt
    26 //      extra (in)          extra keys for encryption
    27 //      dst (out)           pointer to new encrypted message or NULL on failure
    28 //      enc_format (in)     encrypted format
    29 //
    30 //  return value:
    31 //      PEP_STATUS_OK                   on success
    32 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    33 //		                                could not be found
    34 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    35 //		                                an ambiguous name
    36 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    37 //
    38 //	caveat:
    39 //	    the ownershop of src remains with the caller
    40 //	    the ownership of dst goes to the caller
    41 
    42 DYNAMIC_API PEP_STATUS encrypt_message(
    43         PEP_SESSION session,
    44         message *src,
    45         stringlist_t *extra,
    46         message **dst,
    47         PEP_enc_format enc_format
    48     );
    49 
    50 // encrypt_message_for_self() - encrypt message in memory for user's identity only,
    51 //                              ignoring recipients and other identities from
    52 //                              the message
    53 //  parameters:
    54 //      session (in)        session handle
    55 //      target_id (in)      self identity this message should be encrypted for
    56 //      src (in)            message to encrypt
    57 //      dst (out)           pointer to new encrypted message or NULL on failure
    58 //      enc_format (in)     encrypted format
    59 //
    60 //  return value:       (FIXME: This may not be correct or complete)
    61 //      PEP_STATUS_OK                   on success
    62 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    63 //		                                could not be found
    64 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    65 //		                                an ambiguous name
    66 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    67 //
    68 //	caveat:
    69 //	    the ownership of src remains with the caller
    70 //      the ownership of target_id remains w/ caller            
    71 //	    the ownership of dst goes to the caller
    72 //      message is NOT encrypted for identities other than the target_id (and then,
    73 //          only if the target_id refers to self!)
    74 
    75 DYNAMIC_API PEP_STATUS encrypt_message_for_self(
    76         PEP_SESSION session,
    77         pEp_identity* target_id,
    78         message *src,
    79         message **dst,
    80         PEP_enc_format enc_format
    81     );
    82 
    83 typedef enum _PEP_color {
    84     PEP_rating_undefined = 0,
    85     PEP_rating_cannot_decrypt,
    86     PEP_rating_have_no_key,
    87     PEP_rating_unencrypted,
    88     PEP_rating_unencrypted_for_some,
    89     PEP_rating_unreliable,
    90     PEP_rating_reliable,
    91     PEP_rating_yellow = PEP_rating_reliable,
    92     PEP_rating_trusted,
    93     PEP_rating_green = PEP_rating_trusted,
    94     PEP_rating_trusted_and_anonymized,
    95     PEP_rating_fully_anonymous,   
    96 
    97     PEP_rating_mistrust = -1,
    98     PEP_rating_red = PEP_rating_mistrust,
    99     PEP_rating_b0rken = -2,
   100     PEP_rating_under_attack = -3
   101 } PEP_color;
   102 
   103 typedef enum _PEP_decrypt_flags {
   104     PEP_decrypt_flag_own_private_key = 0x1
   105 } PEP_decrypt_flags; 
   106 
   107 typedef uint32_t PEP_decrypt_flags_t;
   108 
   109 // decrypt_message() - decrypt message in memory
   110 //
   111 //  parameters:
   112 //      session (in)        session handle
   113 //      src (in)            message to decrypt
   114 //      dst (out)           pointer to new decrypted message or NULL on failure
   115 //      keylist (out)       stringlist with keyids
   116 //      color (out)         color for the message
   117 //      flags (out)         flags to signal special message features
   118 //
   119 //  return value:
   120 //      error status or PEP_STATUS_OK on success
   121 //
   122 //	caveat:
   123 //	    the ownership of src remains with the caller
   124 //	    the ownership of dst goes to the caller
   125 //	    the ownership of keylist goes to the caller
   126 //	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   127 //	    dst to NULL
   128 
   129 DYNAMIC_API PEP_STATUS decrypt_message(
   130         PEP_SESSION session,
   131         message *src,
   132         message **dst,
   133         stringlist_t **keylist,
   134         PEP_color *color,
   135         PEP_decrypt_flags_t *flags 
   136 );
   137 
   138 // own_message_private_key_details() - details on own key in own message
   139 //
   140 //  parameters:
   141 //      session (in)        session handle
   142 //      msg (in)            message to decrypt
   143 //      ident (out)         identity containing uid, address and fpr of key
   144 //
   145 //  note:
   146 //      In order to obtain details about key to be possibly imported
   147 //      as a replacement of key currently used as own identity, 
   148 //      application passes message that have been previously flagged by 
   149 //      decrypt_message() as own message containing own key to this function
   150 //
   151 //  return value:
   152 //      error status or PEP_STATUS_OK on success
   153 //
   154 //	caveat:
   155 //	    the ownership of msg remains with the caller
   156 //	    the ownership of ident goes to the caller
   157 //	    msg MUST be encrypted so that this function can check own signature
   158 
   159 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   160         PEP_SESSION session,
   161         message *msg,
   162         pEp_identity **ident 
   163 );
   164 
   165 // outgoing_message_color() - get color for an outgoing message
   166 //
   167 //  parameters:
   168 //      session (in)        session handle
   169 //      msg (in)            message to get the color for
   170 //      color (out)         color for the message
   171 //
   172 //  return value:
   173 //      error status or PEP_STATUS_OK on success
   174 //
   175 //  caveat:
   176 //      msg->from must point to a valid pEp_identity
   177 //      msg->dir must be PEP_dir_outgoing
   178 //      the ownership of msg remains with the caller
   179 
   180 DYNAMIC_API PEP_STATUS outgoing_message_color(
   181         PEP_SESSION session,
   182         message *msg,
   183         PEP_color *color
   184     );
   185 
   186 
   187 // identity_color() - get color for a single identity
   188 //
   189 //  parameters:
   190 //      session (in)        session handle
   191 //      ident (in)          identity to get the color for
   192 //      color (out)         color for the identity
   193 //
   194 //  return value:
   195 //      error status or PEP_STATUS_OK on success
   196 //
   197 //  caveat:
   198 //      the ownership of ident remains with the caller
   199 
   200 DYNAMIC_API PEP_STATUS identity_color(
   201         PEP_SESSION session,
   202         pEp_identity *ident,
   203         PEP_color *color
   204     );
   205 
   206 
   207 // get_binary_path() - retrieve path of cryptotech binary if available
   208 //
   209 //  parameters:
   210 //      tech (in)           cryptotech to get the binary for
   211 //      path (out)          path to cryptotech binary or NULL if not available
   212 //                          **path is owned by the library, do not change it!
   213 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   214 
   215 
   216 #ifdef __cplusplus
   217 }
   218 #endif
   219