@ -1,5 +1,16 @@
/ / This file is under GNU General Public License 3.0
/ / see LICENSE . txt
/**
* @ file aux_mime_msg . h
*
* @ brief Auxiliary file which provides the MIME * functions for the enigmail / pEp implementation and some tests .
* Provides access to pEp functions for messages fed in in MIME string format instead of
* through the message struct .
*
* @ deprecated These functions should no longer be used , and these files will be removed shortly .
*
* @ warning No version of the engine which implements pEp sync should use these functions
*
* @ license GNU General Public License 3.0 - see LICENSE . txt
*/
# pragma once
@ -14,29 +25,33 @@
extern " C " {
# endif
/ / MIME_encrypt_message ( ) - encrypt a MIME message , with MIME output
/ /
/ / parameters :
/ / session ( in ) session handle
/ / mimetext ( in ) MIME encoded text to encrypt
/ / size ( in ) size of input mime text
/ / extra ( in ) extra keys for encryption
/ / mime_ciphertext ( out ) encrypted , encoded message
/ / enc_format ( in ) encrypted format
/ / flags ( in ) flags to set special encryption features
/ /
/ / return value :
/ / PEP_STATUS_OK if everything worked
/ / PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
/ / PEP_CANNOT_CREATE_TEMP_FILE
/ / if there are issues with temp files ; in
/ / this case errno will contain the underlying
/ / error
/ / PEP_OUT_OF_MEMORY if not enough memory could be allocated
/ /
/ / caveat :
/ / the encrypted , encoded mime text will go to the ownership of the caller ; mimetext
/ / will remain in the ownership of the caller
/**
* < ! - - MIME_encrypt_message ( ) - - >
*
* @ deprecated
*
* @ brief Encrypt a MIME message , with MIME output
*
* @ param [ in ] session session handle
* @ param [ in ] mimetext MIME encoded text to encrypt
* @ param [ in ] size size of input mime text
* @ param [ in ] extra extra keys for encryption
* @ param [ out ] mime_ciphertext encrypted , encoded message
* @ param [ in ] enc_format encrypted format
* @ param [ in ] flags flags to set special encryption features
*
* @ retval PEP_STATUS_OK if everything worked
* @ retval PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
* @ retval PEP_CANNOT_CREATE_TEMP_FILE if there are issues with temp files ; in
* this case errno will contain the underlying
* error
* @ retval PEP_OUT_OF_MEMORY if not enough memory could be allocated
*
* @ ownership
* - the encrypted , encoded mime text will go to the ownership of the caller
* - the original mimetext will remain in the ownership of the caller
*
*/
DYNAMIC_API PEP_STATUS MIME_encrypt_message (
PEP_SESSION session ,
const char * mimetext ,
@ -48,31 +63,36 @@ DYNAMIC_API PEP_STATUS MIME_encrypt_message(
) ;
/ / MIME_encrypt_message_for_self ( ) - encrypt MIME message for user ' s identity only ,
/ / ignoring recipients and other identities from
/ / the message , with MIME output
/ / parameters :
/ / session ( in ) session handle
/ / target_id ( in ) self identity this message should be encrypted for
/ / mimetext ( in ) MIME encoded text to encrypt
/ / size ( in ) size of input mime text
/ / extra ( in ) extra keys for encryption
/ / mime_ciphertext ( out ) encrypted , encoded message
/ / enc_format ( in ) encrypted format
/ / flags ( in ) flags to set special encryption features
/ /
/ / return value :
/ / PEP_STATUS_OK if everything worked
/ / PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
/ / PEP_CANNOT_CREATE_TEMP_FILE
/ / if there are issues with temp files ; in
/ / this case errno will contain the underlying
/ / error
/ / PEP_OUT_OF_MEMORY if not enough memory could be allocated
/ /
/ / caveat :
/ / the encrypted , encoded mime text will go to the ownership of the caller ; mimetext
/ / will remain in the ownership of the caller
/**
* < ! - - MIME_encrypt_message_for_self ( ) - - >
*
* @ deprecated
*
* @ brief Encrypt MIME message for user ' s identity only ,
* ignoring recipients and other identities from
* the message , with MIME output
*
* @ param [ in ] session session handle
* @ param [ in ] target_id self identity this message should be encrypted for
* @ param [ in ] mimetext MIME encoded text to encrypt
* @ param [ in ] size size of input mime text
* @ param [ in ] extra extra keys for encryption
* @ param [ out ] mime_ciphertext encrypted , encoded message
* @ param [ in ] enc_format encrypted format
* @ param [ in ] flags flags to set special encryption features
*
* @ retval PEP_STATUS_OK if everything worked
* @ retval PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
* @ retval PEP_CANNOT_CREATE_TEMP_FILE if there are issues with temp files ; in
* this case errno will contain the underlying
* error
* @ retval PEP_OUT_OF_MEMORY if not enough memory could be allocated
*
* @ ownership
* - the encrypted , encoded mime text will go to the ownership of the caller
* - the original mimetext will remain in the ownership of the caller
*
*/
DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self (
PEP_SESSION session ,
pEp_identity * target_id ,
@ -86,52 +106,66 @@ DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(
/ / MIME_decrypt_message ( ) - decrypt a MIME message , with MIME output
/ /
/ / parameters :
/ / session ( in ) session handle
/ / mimetext ( in ) MIME encoded text to decrypt
/ / size ( in ) size of mime text to decode ( in order to decrypt )
/ / mime_plaintext ( out ) decrypted , encoded message
/ / keylist ( inout ) in : stringlist with additional keyids for reencryption if needed
/ / ( will be freed and replaced with output keylist )
/ / out : stringlist with keyids
/ / rating ( out ) rating for the message
/ / flags ( inout ) flags to signal special decryption features ( see below )
/ / modified_src ( out ) modified source string , if decrypt had reason to change it
/ /
/ / return value :
/ / decrypt status if everything worked with MIME encode / decode ,
/ / the status of the decryption is returned
/ / ( PEP_STATUS_OK or decryption error status )
/ / PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
/ / PEP_CANNOT_CREATE_TEMP_FILE
/ / if there are issues with temp files ; in
/ / this case errno will contain the underlying
/ / error
/ / PEP_OUT_OF_MEMORY if not enough memory could be allocated
/ /
/ / flag values :
/ / in :
/ / PEP_decrypt_flag_untrusted_server
/ / used to signal that decrypt function should engage in behaviour
/ / specified for when the server storing the source is untrusted .
/ / out :
/ / PEP_decrypt_flag_own_private_key
/ / private key was imported for one of our addresses ( NOT trusted
/ / or set to be used - handshake / trust is required for that )
/ / PEP_decrypt_flag_src_modified
/ / indicates that the modified_src field should contain a modified
/ / version of the source , at the moment always as a result of the
/ / input flags .
/ / PEP_decrypt_flag_consume
/ / used by sync
/ / PEP_decrypt_flag_ignore
/ / used by sync
/ /
/ / caveat :
/ / the decrypted , encoded mime text will go to the ownership of the caller ; mimetext
/ / will remain in the ownership of the caller
/**
* < ! - - MIME_decrypt_message ( ) - - >
*
* @ deprecated
*
* @ brief Decrypt a MIME message , with MIME output
*
* @ param [ in ] session session handle
* @ param [ in ] mimetext MIME encoded text to decrypt
* @ param [ in ] size size of mime text to decode ( in order to decrypt )
* @ param [ out ] mime_plaintext decrypted , encoded message
* @ param [ in , out ] keylist in : stringlist with additional keyids for reencryption if needed
* ( will be freed and replaced with output keylist )
* out : stringlist with keyids
* @ param [ out ] rating rating for the message
* @ param [ in , out ] flags flags to signal special decryption features ( see below )
* @ param [ out ] modified_src modified source string , if decrypt had reason to change it
*
* @ retval decrypt status if everything worked with MIME encode / decode ,
* the status of the decryption is returned
* ( PEP_STATUS_OK or decryption error status )
* @ retval PEP_BUFFER_TOO_SMALL if encoded message size is too big to handle
* @ retval PEP_CANNOT_CREATE_TEMP_FILE if there are issues with temp files ; in
* this case errno will contain the underlying
* error
* @ retval PEP_OUT_OF_MEMORY if not enough memory could be allocated
*
* @ note Flags above are as follows :
* @ verbatim
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
* Incoming flags |
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
* Flag | Description |
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
* PEP_decrypt_flag_untrusted_server | used to signal that decrypt function should engage |
* | in behaviour specified for when the server storing |
* | the source is untrusted . |
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
* Outgoing flags |
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
* PEP_decrypt_flag_own_private_key | private key was imported for one of our addresses |
* | ( NOT trusted or set to be used - handshake / trust is |
* | required for that ) |
* | |
* PEP_decrypt_flag_src_modified | indicates that the modified_src field should contain |
* | a modified version of the source , at the moment |
* | always as a result of the input flags . |
* | |
* PEP_decrypt_flag_consume | used by sync to indicate this was a pEp internal |
* | message and should be consumed externally without |
* | showing it as a normal message to the user |
* | |
* PEP_decrypt_flag_ignore | used by sync |
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | @ endverbatim
*
* @ ownership
* - the decrypted , encoded mime text will go to the ownership of the caller
* - the original mimetext will remain in the ownership of the caller
*
*/
DYNAMIC_API PEP_STATUS MIME_decrypt_message (
PEP_SESSION session ,
const char * mimetext ,