src/message_api.h
author Edouard Tisserant
Tue, 14 Jun 2016 19:23:20 +0200
branchimport_own_key
changeset 736 496905895282
parent 734 bd9a3eb1d707
child 939 ed7dfdae3031
child 994 808f6fc6c5e5
child 1125 89e75396c69a
permissions -rw-r--r--
Simpler interface for own_message_private_key_details
     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 
    51 typedef enum _PEP_color {
    52     PEP_rating_undefined = 0,
    53     PEP_rating_cannot_decrypt,
    54     PEP_rating_have_no_key,
    55     PEP_rating_unencrypted,
    56     PEP_rating_unencrypted_for_some,
    57     PEP_rating_unreliable,
    58     PEP_rating_reliable,
    59     PEP_rating_yellow = PEP_rating_reliable,
    60     PEP_rating_trusted,
    61     PEP_rating_green = PEP_rating_trusted,
    62     PEP_rating_trusted_and_anonymized,
    63     PEP_rating_fully_anonymous,   
    64 
    65     PEP_rating_mistrust = -1,
    66     PEP_rating_red = PEP_rating_mistrust,
    67     PEP_rating_b0rken = -2,
    68     PEP_rating_under_attack = -3
    69 } PEP_color;
    70 
    71 typedef enum _PEP_decrypt_flags {
    72     PEP_decrypt_flag_own_private_key = 0x1
    73 } PEP_decrypt_flags; 
    74 
    75 typedef uint32_t PEP_decrypt_flags_t;
    76 
    77 // decrypt_message() - decrypt message in memory
    78 //
    79 //  parameters:
    80 //      session (in)        session handle
    81 //      src (in)            message to decrypt
    82 //      dst (out)           pointer to new decrypted message or NULL on failure
    83 //      keylist (out)       stringlist with keyids
    84 //      color (out)         color for the message
    85 //      flags (out)         flags to signal special message features
    86 //
    87 //  return value:
    88 //      error status or PEP_STATUS_OK on success
    89 //
    90 //	caveat:
    91 //	    the ownership of src remains with the caller
    92 //	    the ownership of dst goes to the caller
    93 //	    the ownership of keylist goes to the caller
    94 //	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
    95 //	    dst to NULL
    96 
    97 DYNAMIC_API PEP_STATUS decrypt_message(
    98         PEP_SESSION session,
    99         message *src,
   100         message **dst,
   101         stringlist_t **keylist,
   102         PEP_color *color,
   103         PEP_decrypt_flags_t *flags 
   104 );
   105 
   106 // own_message_private_key_details() - details on own key in own message
   107 //
   108 //  parameters:
   109 //      session (in)        session handle
   110 //      msg (in)            message to decrypt
   111 //      ident (out)         identity containing uid, address and fpr of key
   112 //
   113 //  note:
   114 //      In order to obtain details about key to be possibly imported
   115 //      as a replacement of key currently used as own identity, 
   116 //      application passes message that have been previously flagged by 
   117 //      decrypt_message() as own message containing own key to this function
   118 //
   119 //  return value:
   120 //      error status or PEP_STATUS_OK on success
   121 //
   122 //	caveat:
   123 //	    the ownership of msg remains with the caller
   124 //	    the ownership of ident goes to the caller
   125 //	    msg MUST be encrypted so that this function can check own signature
   126 
   127 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   128         PEP_SESSION session,
   129         message *msg,
   130         pEp_identity **ident 
   131 );
   132 
   133 // outgoing_message_color() - get color for an outgoing message
   134 //
   135 //  parameters:
   136 //      session (in)        session handle
   137 //      msg (in)            message to get the color for
   138 //      color (out)         color for the message
   139 //
   140 //  return value:
   141 //      error status or PEP_STATUS_OK on success
   142 //
   143 //  caveat:
   144 //      msg->from must point to a valid pEp_identity
   145 //      msg->dir must be PEP_dir_outgoing
   146 //      the ownership of msg remains with the caller
   147 
   148 DYNAMIC_API PEP_STATUS outgoing_message_color(
   149         PEP_SESSION session,
   150         message *msg,
   151         PEP_color *color
   152     );
   153 
   154 
   155 // identity_color() - get color for a single identity
   156 //
   157 //  parameters:
   158 //      session (in)        session handle
   159 //      ident (in)          identity to get the color for
   160 //      color (out)         color for the identity
   161 //
   162 //  return value:
   163 //      error status or PEP_STATUS_OK on success
   164 //
   165 //  caveat:
   166 //      the ownership of ident remains with the caller
   167 
   168 DYNAMIC_API PEP_STATUS identity_color(
   169         PEP_SESSION session,
   170         pEp_identity *ident,
   171         PEP_color *color
   172     );
   173 
   174 
   175 // get_binary_path() - retrieve path of cryptotech binary if available
   176 //
   177 //  parameters:
   178 //      tech (in)           cryptotech to get the binary for
   179 //      path (out)          path to cryptotech binary or NULL if not available
   180 //                          **path is owned by the library, do not change it!
   181 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   182 
   183 
   184 #ifdef __cplusplus
   185 }
   186 #endif
   187