Converted .hgignore to .gitignore

.gitignore

@@ -1,14 +1,12 @@
-syntax: regexp
-^asn\.1/.*\.(c|h)$
-^asn\.1/libasn1\.a$
-.*xcuserdata/
-^build/
-^local.conf
-^test_home/
-
-syntax: glob
 asn.1/Makefile.am.*
 asn.1/converter-example.mk
+asn.1/libasn1.a
+local.conf
+build/
+test_home/
+asn.1/*.c
+asn.1/*.h
+xcuserdata/
 *.orig
 *.old
 *.d

api/Makefile

@@ -0,0 +1,18 @@
+all: basic_api.h
+
+YML2=$(wildcard *.yml2)
+YSL2=$(wildcard *.ysl2)
+
+%.xml: %.yml2
+	yml2proc -P $< -o $@
+
+%.xsl: %.ysl2
+	yml2proc -DP $< -o $@
+
+%.h: $(YML2) $(YSL2)
+	yml2proc -y gen_c_header.ysl2 pEp.yml2
+
+.PHONY: clean
+
+clean:
+	rm -f *.xml *.xsl *.h

api/basic_api.yml2

@@ -0,0 +1,439 @@
+// p≡p Basic API
+
+// Copyleft (c) 2019, p≡p foundation
+// this file is under GNU General Public License 3.0
+// see LICENSE.txt
+
+// written by Nana Karlstetter and Volker Birk
+
+
+type ISO639_1 is string size=2 > a-z;
+
+type hexcode is string > a-f0-9;
+
+type hash doc="32bit Key ID to SHA512 in hexcode"
+    is hexcode min=16, max=128;
+
+type hash_list doc="sequence of fingerprints of keys"
+    is list< hash >;
+
+type TID doc="UUID version 4 variant 1"
+    is binary size=16;
+
+type binary_ref is weak< binary >;
+
+enum content_disposition {
+    item attachment 0;
+    item inline 1;
+    item other -1  doc="must be affirmatively set";
+}
+
+struct blob {
+    field function=free binary_ref value;
+
+    field size_t size;
+    field string mime_type;
+    field string filename;
+    field content_disposition disposition;
+}
+
+
+type blob_list is list< blob >;
+
+type identity_list is list< identity >;
+
+type string_list is list< string >; 
+
+type string_pair is pair< string, string >;
+
+type string_pair_list is list< string_pair >;
+
+type any_ref is weak< any >;
+
+
+enum cipher_suite {
+    item default 0;
+    item cv25519 1;
+    item p256 2;
+    item p384 3;
+    item p521 4;
+    item rsa2k 5;
+    item rsa3k 6;
+    item rsa4k 7;
+    item rsa8k 8;
+}
+
+
+enum comm_type {
+    hex unknown 0;
+
+    doc > range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
+
+    hex no_encryption 0x01;
+    hex no_encrypted_channel 0x02;
+    hex key_not_found 0x03;
+    hex key_expired 0x04;
+    hex key_revoked 0x05;
+    hex key_b0rken 0x06;
+
+    hex key_expired_but_confirmed 0x07 
+        doc="NOT with confirmed bit. Just retaining info here in case of renewal.";
+
+    hex my_key_not_included 0x09;
+
+    hex security_by_obscurity 0x0a;
+    hex b0rken_crypto 0x0b;
+    hex key_too_short 0x0c;
+
+    hex compromised 0x0e                   doc="known compromised connection";
+    hex mistrusted 0x0f                    doc="known mistrusted key";
+
+    doc > range 0x10 to 0x3f: unconfirmed encryption
+
+    hex unconfirmed_encryption 0x10        doc="generic";
+    hex OpenPGP_weak_unconfirmed 0x11      doc="RSA 1024 is weak";
+
+    hex to_be_checked 0x20                 doc="generic";
+    hex SMIME_unconfirmed 0x21             doc="encrypted with S/MIME";
+    hex CMS_unconfirmed 0x22;
+
+    hex strong_but_unconfirmed 0x30        doc="generic";
+    hex OpenPGP_unconfirmed 0x38           doc="key at least 2048 bit RSA, EC, or anything useful";
+    hex OTR_unconfirmed 0x3a               doc="encrypted with OTR";
+
+    doc > range 0x40 to 0x7f: unconfirmed encryption and anonymization
+
+    hex unconfirmed_enc_anon 0x40          doc="generic";
+    hex pEp_unconfirmed 0x7f               doc="encrypted with pEp";
+
+    hex confirmed 0x80                     doc="this bit decides if trust is confirmed";
+
+    doc > range 0x81 to 0x8f: reserved
+    doc > range 0x90 to 0xbf: confirmed encryption
+
+    hex confirmed_encryption 0x90          doc="generic";
+    hex OpenPGP_weak 0x91                  doc="RSA 1024 is weak (unused)";
+
+    hex to_be_checked_confirmed 0xa0       doc="generic";
+    hex SMIME 0xa1;
+    hex CMS 0xa2;
+
+    hex strong_encryption 0xb0             doc="generic";
+    hex OpenPGP 0xb8                       doc="key at least 2048 bit RSA or EC";
+    hex OTR 0xba;
+
+    doc > range 0xc0 to 0xff: confirmed encryption and anonymization
+
+    hex confirmed_enc_anon 0xc0            doc="generic";
+    hex pEp 0xff;
+
+} // enum comm_type
+
+
+struct identity {
+    field string address doc="SMTP address or URI. String with address UTF-8 encoded";
+    field hash fpr doc="fingerprint of key being used as ID. String with fingerprint UTF-8 encoded";
+    field string user_id doc="ID for person or system in case of M2M";
+    doc ||
+        user_id MIGHT be set to "pEp_own_userId" (use PEP_OWN_USERID preprocessor define)
+        if this is own user's identity. But it is not REQUIRED to be.
+        ||
+    field string username doc="descriptive string. String with user name UTF-8 encoded";
+    field comm_type comm_type doc="type of communication with this ID";
+    field ISO639_1 lang[3] doc="ISO 639-1 ALPHA-2, last byte is 0";
+    field bool me doc="if this is the local user herself/himself";
+    field unsigned major_ver doc="highest version of pEp message received, if any";
+    field unsigned minor_ver doc="highest version of pEp message received, if any";
+
+    flags {
+        flag not_for_sync 0x0001
+            doc="don't use this identity for Sync";
+
+        flag list 0x0002
+            doc="identity of list of persons";
+
+        doc | the second octet flags are calculated
+
+        flag devicegroup 0x0100
+            doc="identity of a device group member";
+    }
+} // struct Identity
+
+
+protocol session {
+    callback messageToSend doc="a message needs to be delivered by application"
+    {
+        // parms
+
+        provide struct_message msg doc="message struct with message to send";
+
+        // exceptions
+
+        throws any doc="error status";
+    }
+
+
+    method config_passive_mode doc="enable passive mode"
+    {
+        // parms
+
+       use bool enable doc="flag if enabled or disabled";
+    }
+
+
+    method config_unencrypted_subject doc="disable subject encryption"
+    {
+        // parms
+
+        use bool enable doc="flag if enabled or disabled";
+    }
+
+
+    method config_use_only_own_private_keys doc="enable passive mode"
+    {
+        // parms
+
+        use bool enable doc="flag if enabled or disabled";
+    }
+
+
+    method config_service_log doc="log more for service purposes"
+    {
+        // parms
+
+        use bool enable doc="flag if enabled or disabled";
+    }
+
+
+    method config_cipher_suite doc="cipher suite being used when encrypting"
+    {
+        // parms
+
+        use suite cipher_suite doc="cipher suite to use";
+
+        // exceptions
+
+        throws cannot_config 
+        doc="""
+            configuration failed; falling back to default. the default
+            ciphersuite for a crypt tech implementation is implementation 
+            defined.
+            """;
+    }
+
+
+    method log_event
+    doc="""
+        log a user defined event defined by UTF-8 encoded strings into 
+        management log.
+        """
+    {
+        // parms
+
+        use string title doc="string with event name";
+
+        use string entity doc="string with name of entity which is logging";
+
+        use string description doc="string with long description for event or NULL if omitted";
+
+        use string comment doc="string with user defined comment or NULL if omitted";
+    }
+
+
+    method get_default own_userid doc="get the user_id of the own user"
+    {
+        // parms
+
+        create string userid 
+        doc="""
+            own user id (if it exists). userid will be NULL if not found; otherwise, 
+            returned string belongs to the caller.
+            """;
+
+        // exceptions
+
+        throws cannot_find_identity doc="no own_user found in the DB";
+
+        throws unknown_error 
+        doc="""
+            results were returned, but no ID found (no reason this 
+            should ever occur).
+            """;
+    }
+
+
+    method mark_as_compromised doc="mark key in trust db as compromised"
+    {
+        // parms
+
+        use hash fpr doc="fingerprint of key to mark";
+    }
+
+
+    method mark_as_compromized doc="deprecated to fix misspelling. Please move to mark_as_compromised"
+
+
+    method import_key doc="import key from data"
+    {
+        // parms
+
+        use string key_data doc="key data, i.e. ASCII armored OpenPGP key";
+
+        use size_t size doc="amount of data to handle";
+
+        create identity_list private_keys 
+        doc="""
+            list of private keys that have been imported. private_keys can 
+            be left NULL, it is then ignored.
+            """;
+    }
+
+
+    method export_key doc="export ascii armored key"
+    {
+        // parms
+
+        use hash fpr doc="key id or fingerprint of key";
+
+        create string key_data 
+        doc="""
+            ASCII armored OpenPGP key. The key_data goes to the ownership of the 
+            caller. The caller is responsible to free() it (on Windoze use pEp_free())
+            """;
+
+        return size_t size doc="amount of data to handle";
+
+        // exceptions
+
+        throws out_of_memory doc="out of memory";
+
+        throws key_not_found doc="key not found";
+    }
+
+
+    method export_secret_key doc="export secret key ascii armored"
+    {
+        // parms
+
+        use hash fpr doc="fingerprint of key, at least 16 hex digits";
+
+        create string key_data 
+        doc="""
+            ASCII armored OpenPGP secret key. The key_data goes to the ownership of the 
+            caller. The caller is responsible to free() it (on Windoze use pEp_free()).
+            beware of leaking secret key data - overwrite it in memory after use!
+            """;
+
+        return size_t size doc="amount of data to handle";
+
+        // exceptions
+
+        throws out_of_memory doc="out of memory";
+
+        throws key_not_found doc="key not found";
+
+        throws cannot_export_key doc="cannot export secret key (i.e. it's on an HKS)";
+    }
+
+
+    method export_secrect_key doc="deprecated misspelled function. Please replace with export_secret_key"
+
+
+    method get_crashdump_log doc="get the last log messages out"
+    {
+        // parms
+
+        use int maxlines doc="maximum number of lines (0 for default)";
+
+        create string logdata 
+        doc="""
+            logdata as string in double quoted CSV format
+            column1 is title
+            column2 is entity
+            column3 is description
+            column4 is comment
+            """;
+    }
+
+
+    method get_languagelist doc="get the list of languages"
+    {
+        //parms
+
+        create string language 
+        doc="""
+            languages as string in double quoted CSV format
+            column 1 is the ISO 639-1 language code
+            column 2 is the name of the language
+            """;
+    }
+
+
+    method get_phrase doc="get phrase in a dedicated language through i18n"
+    {
+        // parms
+
+        use string lang doc="string with ISO 639-1 language code";
+
+        use int phrase_id doc="id of phrase in i18n";
+
+        create string phrase doc="phrase as UTF-8 string";
+    }
+
+
+    method get_engine_version
+    doc="""
+        returns the current version of pEpEngine (this is different
+        from the pEp protocol version!).
+        """
+    {
+        // parms doc="none"
+
+        // exceptions
+
+        throws any doc="string to the engine version string constant"; 
+    }
+
+    method is_pEp_user
+    doc="""
+        returns true if the USER corresponding to this identity has been listed 
+        in the *person* table as a pEp user.
+        This *does not check comm_type*.
+        """
+    {
+        // parms
+
+        use identity ident
+        doc="""
+            identity containing the user_id to check (this is the only part of 
+            the struct we require to be set).
+            """;
+
+        return bool is_pEp
+        doc="""
+            boolean pointer - will return true or false by reference with respect 
+            to whether or not user is a known pEp user
+            """;
+
+        // exceptions
+
+        throws illegal_value doc="if no user_id in input";
+
+        throws cannot_find_person doc="if user_id doesn't exist";
+    }
+
+
+    method per_user_directory doc="returns the directory for pEp management db"
+    {
+        // exceptions
+
+        throws any doc="path to actual per user directory or NULL on failure";
+    }
+
+    method per_machine_directory doc="returns the directory for pEp system db"
+    {
+        // exceptions
+
+        throws any doc="path to actual per user directory or NULL on failure";
+    }
+}

api/config.yml2

@@ -0,0 +1,2 @@
+version = "version 2.0"
+copyleft = "Copyleft (c) 2019-2020, pEp foundation"

api/gen_c_header.ysl2

@@ -0,0 +1,107 @@
+// p≡p API header generator
+
+// Copyleft (c) 2019-2020, p≡p foundation
+// this file is under GNU General Public License 3.0
+// see LICENSE.txt
+
+// written by Volker Birk
+
+
+include yslt.yml2
+include ./config.yml2
+
+tstylesheet {
+    include ./to_c.ysl2
+    include standardlib.ysl2
+
+    const "version" **version;
+    const "copyleft" **copyleft;
+
+    template "/package"
+        apply "package", 0;
+
+    template "package" document "{@name}_{@type}.h", "text" {
+    ||
+    // «../@name» «$version»
+    // «@name»_«@type».h
+
+    // «$copyleft»
+
+
+    #pragma once
+
+    #ifdef __cplusplus
+    extern "C" {
+    #endif
+
+    #include <pEp/basic_types.h>
+
+    ||
+    apply "doc|type|enum|struct", 0;
+    ||
+
+    #ifdef __cplusplus
+    } // extern "C"
+    #endif
+
+    ||
+    }
+
+    template "type" {
+        apply "@doc", 0;
+        | typedef «func:basetype(@name)» «@name»;
+        |
+    }
+
+    template "struct" {
+    ||
+    typedef struct _«func:name()» {
+    ||
+    apply "field|internal|doc";
+    apply "field[@function='free']", mode=free;
+    ||
+    } «func:name()»;
+
+    ||
+    }
+
+    template "field|internal" {
+        apply "@doc", 0;
+        | «func:c-type(@type)» «@name»;
+    }
+
+    template "field", mode=free
+    ||
+    
+    // free function for «@name»
+    void (*release_«@name»)(«func:c-type(@type)» «@name»);
+    ||
+
+    template "enum" {
+    ||
+    typedef enum _«func:name()» {
+    ||
+    apply "item|doc";
+    ||
+    } «func:name()»;
+
+    ||
+    }
+
+    template "doc|@doc" {
+        > \n
+        for "str:split(., '\n')"
+            | // «.»
+    }
+
+    template "item" {
+        apply "@doc", 0;
+        choose {
+            when "@output='hex'"
+                | «func:name()»`if "text()" { " = 0x" value "yml:dec2hex(., 2)" }``if "position()!=last()" > ,`
+            otherwise
+                | «func:name()»`if "text()" { " = " value "." }``if "position()!=last()" > ,`
+        }
+    }
+}
+

api/keymanagement_api.yml2

@@ -0,0 +1,226 @@
+// p≡p Keymanagement API version 0.1
+
+// Copyleft (c) 2019, p≡p foundation
+// this file is under GNU General Public License 3.0
+// see LICENSE.txt
+
+// written by Nana Karlstetter and Volker Birk
+
+
+protocol session {
+    method update_identity doc="update identity information"
+    {
+        // parms
+
+        lend identity identity
+        doc="""
+            identity information of communication partner
+            (identity->fpr is OUT ONLY), and at least
+            .address must be set. 
+            If .username is set, it will be used to set or patch
+            the username record for this identity.
+            at least identity->address must be a non-empty UTF-8 string as input
+            update_identity() never writes flags; use set_identity_flags() for
+            writing
+            this function NEVER reads the incoming fpr, only writes to it.
+            this function will fail if called on an identity which, with its input
+            values, *explicitly* indicates it is an own identity (i.e. .me is set
+            to true on input, or a user_id is given AND it is a known own user_id).
+            however, it can RETURN an own identity if this is not indicated a
+            priori, and in fact will do so with prejudice when not faced with a
+            matching default (i.e. it is forced to search by address only).
+            if the identity is known to be an own identity (or the caller wishes
+            to make it one), call myself() on the identity instead.
+
+            FIXME: is this next point accurate?
+            if this function returns PEP_ct_unknown or PEP_ct_key_expired in
+            identity->comm_type, the caller must insert the identity into the
+            asynchronous management implementation, so retrieve_next_identity()
+            will return this identity later
+            END FIXME
+            """;
+
+        // exceptions
+
+        throws illegal_value
+        doc="""
+            if called with illegal inputs, including an identity
+            with .me set or with an own user_id specified in the
+            *input* (see caveats)
+            """;
+
+        throws key_unsuitable
+        doc="""
+            if a default key was found for this identity, no
+            other acceptable keys were found; if this is returned,
+            the reason for rejecting the first default key found    
+            may be found in the comm_type
+            """;
+    }
+
+
+    method myself doc="ensures that an own identity is complete"
+    {
+        // parms
+
+        lend identity ident
+        doc="""
+            identity of local user
+            both .address and .user_id must be set.
+            if .fpr is set, an attempt will be made to make
+            that the default key for this identity after key validation
+            if .fpr is not set, key retrieval is performed.
+            If .username is set, it will be used to set or patch
+            the username record for this identity. 
+     
+            If an fpr was entered and is not a valid key, the reason for failure
+            is immediately returned in the status and, possibly, identity->comm_type
+            If a default own user_id exists in the database, an alias will 
+            be created for the default for the input user_id. The ENGINE'S default
+            user_id is always returned in the .user_id field
+            myself() NEVER elects keys from the keyring; it will only choose keys
+            which have been set up explicitly via myself(), or which were imported
+            during a first time DB setup from an OpenPGP keyring (compatibility only) 
+            this function generates a keypair on demand; because it's synchronous
+            it can need a decent amount of time to return
+            if you need to do this asynchronous, you need to return an identity
+            with retrieve_next_identity() where identity.me is true.
+            """;
+    }
+
+
+    method key_mistrusted doc="mark key as being compromised"
+    {
+        //parms
+
+        use identity ident
+        doc="""
+            person and key which was compromised
+            ident is INPUT ONLY. If you want updated trust on the identity, you'll have
+            to call update_identity or myself respectively after this.
+            N.B. If you are calling this on a key that is the identity or user default,
+            it will be removed as the default key for ANY identity and user for which
+            it is the default. Please keep in mind that the undo in undo_last_mistrust
+            will only undo the current identity's / it's user's default, not any
+            other identities which may be impacted (this will not affect most use
+            cases)
+            """;
+    }
+
+
+    method trust_personal_key doc="mark a key as trusted for a user"
+    {
+        // parms
+
+        use identity ident
+        doc="""
+            person and key to trust in - this must not be an own_identity in which 
+            the .me flag is set or the user_id is an own user_id. The fields user_id, 
+            address and fpr must be supplied own identities will result in a return 
+            of illegal_value.
+            For non-own users, this will 1) set the trust bit on its comm type in the DB,
+            2) set this key as the identity default if the current identity default
+            is not trusted, and 3) set this key as the user default if the current user
+            default is not trusted.
+            """;
+    }
+
+
+    method trust_own_key
+    doc="""
+        mark a key as trusted for self, generally used when we need to trust 
+        a public key associated with outselves for issues like manual key import.
+        """
+    {
+        // parms
+
+        use identity ident
+        doc="""
+            own ident containing fpr to trust. 
+            If this is a public key only, keep in mind that if the private part of the 
+            keypair is later added, it will not undergo separate trust evaluation. This 
+            is fine - even desired - as long as the semantics of this function are 
+            understood as both trusting the key and verifying it as an own key. This will 
+            NEVER cause replacement of or setting of a default *alone*. However, if a 
+            private key is ever associated with this fpr, please keep in mind that trusting 
+            it here makes it an eligible key for selection for encryption later. So use 
+            this function on purpose with an understanding of what you're doing!
+            """;
+    }
+
+
+    method key_reset_trust
+    doc="""
+        reset trust bit or explicitly mistrusted status for an identity and its 
+        accompanying key/user_id pair.
+        """
+    {
+        // parms
+
+        use ientity ident
+        doc="""
+            identity for person and key whose trust status is to be reset.
+            Ident is INPUT ONLY. If you want updated trust on the identity, you'll have 
+            to call update_identity or myself respectively after this.
+            N.B. If you are calling this on a key that is the identity or user default,
+            it will be removed as the default key for the identity and user (but is still
+            available for key election, it is just not the cached default anymore).
+            """;
+    }
+
+
+    method own_key_is_listed doc="returns true id key is listed as own key"
+    {
+        // parms
+
+        use hash fpr doc="fingerprint of key to test";
+
+        return bool listed doc="flags if key is own";
+    }
+
+
+    method own_identities_retrieve doc="retrieve all own identities"
+    {
+
+        // parms
+
+        create identity_list own_identities 
+        doc="""
+            list of own identities. 
+            The ownership of the copy of own_identities goes to the caller.
+            """;
+    }
+
+
+    method own_keys_retrieve doc="retrieve all flagged keypair fingerprints/private keypair fingerprints" 
+    {
+        // parms
+
+        create hashlist keylist 
+        doc="""
+            list of fingerprints. This function does not return keys without 
+            a private key part.
+            """;
+    }
+
+
+    method set_own_key doc="mark a key as own key"
+    {
+        // parms
+
+        lend identity me 
+        doc="""
+            own identity this key is used for. The key has to be in the key ring already.
+            me->address, me->user_id and me->username must be set to valid data.
+            myself is called by set_own_key without key generation.
+            me->flags are ignored
+            me->address must not be an alias
+            me->fpr will be ignored and replaced by fpr, but caller MUST surrender ownership of the 
+            me->fpr reference, because it may be freed and replaced within the myself call. caller 
+            owns me->fpr memory again upon return.
+            """;
+
+        use hash fpr doc="fingerprint of the key to mark as own key";
+    }
+}
+

api/message_api.yml2

@@ -0,0 +1,569 @@
+// p≡p Message API
+
+// Copyleft (c) 2019-2020, p≡p foundation
+// this file is under GNU General Public License 3.0
+// see LICENSE.txt
+
+// written by Volker Birk and Nana Karlstetter
+
+
+enum text_format {
+    hex plain 0;
+    hex html 1;
+    hex other 0xff;
+}
+
+
+enum direction {
+    item incoming 0;
+    item outgoing 1;
+}
+
+
+enum enc_format {
+    item none 0 doc='message is not encrypted';
+    item pieces 1 doc='inline PGP + PGP extensions';
+    item S_MIME 2 doc='RFC5751';
+    item PGP_MIME 3 doc='RFC3156';
+    item PEP 4 doc='pEp encryption format';
+    item PGP_MIME_Outlook1 5 doc='Message B0rken by Outlook type 1';
+}
+
+
+enum rating {
+    item undefined 0 doc="no rating available";
+
+    doc "no color";
+
+    item cannot_decrypt 1;
+    item have_no_key 2;
+    item unencrypted 3;
+    // 4 is reserved
+    item unreliable 5;
+
+    doc "yellow";
+
+    item reliable 6;
+
+    doc "green";
+
+    item trusted 7;
+    item trusted_and_anonymized 8;
+    item fully_anonymous 9;
+
+    doc "red";
+
+    item mistrust -1;
+    item b0rken -2;
+    item under_attack -3;
+}
+    
+
+enum color {
+    item no_color 0;
+    item yellow 1;
+    item green 2;
+    item red -1;
+}
+
+
+struct message {
+    field direction dir;
+    field string id doc='string of message ID';
+    field string shortmsg doc='string of short message';
+    field string longmsg doc='string of long message (plain)';
+    field string longmsg_formatted doc='string of long message (formatted)';
+    field blob_list attachments doc='blobs with attachements';
+    field binary_ref rawmsg_ref doc='reference to raw message data';
+    field size_t rawmsg_size doc='size of raw message data';
+    field timestamp sent doc='when the message is sent';
+    field timestamp recv doc='when the message is received';
+    field identity from doc='whom the message is from';
+    field identity_list to doc='whom the message is to';
+    field identity recv_by doc='via which identity the message is received';
+    field identity_list cc doc='whom a CC is being sent';
+    field identity_list bcc doc='whom a BCC is being sent';
+    field identity_list reply_to doc='where a reply should go to';
+    field string_list in_reply_to doc='list of strings with MessageIDs of refering messages';
+    field any_ref refering_msg_ref doc='reference to refering message';
+    field string_list references doc='list of strings with references';
+    field string_list refered_by doc='list of references to messages being refered';
+    field string_list keywords doc='list of strings with keywords';
+    field string comments doc='string with comments';
+    field string_pair_list opt_fields doc='optional fields';
+    field enc_format format doc='format of encrypted data';
+
+    new (msg_direction dir);
+}
+
+
+protocol session {
+    method encrypt_message 
+    doc="""
+        encrypt message in memory. enc_format PEP_enc_inline_EA:
+        internal format of the encrypted attachments is changing, see
+        https://dev.pep.foundation/Engine/ElevatedAttachments
+
+        Only use this for transports without support for attachments
+        when attached data must be sent inline
+        """
+    {
+        // parms
+
+        lend message src
+        doc="""
+            message to encrypt - usually in-only, but can be in-out for
+            unencrypted messages; in that case, we may attach the key and
+            decorate the message
+            """;
+
+        use hash_list extra doc="extra keys for encryption";
+
+        create message dst
+        doc="""
+            pointer to new encrypted message or #NV if no encryption could
+            take place
+            """;
+
+        use enc_format format doc="The desired format this message should be encrypted with";
+
+        // flags
+
+        flags {
+            flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
+            flag force_encryption 0x1;
+            flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
+            flag force_no_attached_key 0x4;
+            flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
+            flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
+            flag key_reset_only 0x20 
+            doc="""This flag is used to let internal functions know that an encryption call is being 
+                used as part of a reencryption operation
+                """;
+            flag encrypt_reencrypt 0x40;
+        }
+
+        // exceptions
+
+        throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
+
+        throws unencrypted
+        doc="""
+            on demand or no recipients with usable key, is left unencrypted,
+            and key is attached to it 
+            """;
+    }
+
+
+    method encrypt_message_and_add_priv_key
+    doc="""
+        encrypt message in memory, adding an encrypted private key (encrypted separately 
+        and sent within the inner message)
+        """
+    {
+        // parms
+
+        use message src doc="message to encrypt";
+
+        create message dst
+            doc="pointer to new encrypted message or empty if no encryption could take place";
+
+        use hash to_fpr
+            doc="fingerprint of the recipient key to which the private key should be encrypted";
+
+        use enc_format format doc="encrypted format";
+
+        // flags
+
+        flags {
+            flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
+            flag force_encryption 0x1;
+            flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
+            flag force_no_attached_key 0x4;
+            flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
+            flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
+            flag key_reset_only 0x20;
+        }
+
+        // exceptions
+
+        throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
+
+        throws unencrypted
+            doc="""
+                on demand or no recipients with usable key, is left unencrypted, 
+                and key is attached to it
+                """;
+    }
+
+
+    method encrypt_message_for_self
+    doc="""
+        encrypt message in memory for user's identity only,
+        ignoring recipients and other identities from the message
+        """
+    {
+        // parms
+
+        use identity target_id
+        doc="""
+            self identity this message should be encrypted for. Message is NOT encrypted for 
+            identities other than the target_id (and then, only if the target_id refers to self!).
+            """;
+
+        use message src doc="message to encrypt";
+
+        use hash_list extra doc="extra keys for encryption";
+
+        create message dst doc="pointer to new encrypted message or empty on failure";
+
+        use enc_format format doc="encrypted format";
+
+        // flags
+
+        flags {
+            flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
+            flag force_encryption 0x1;
+            flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
+            flag force_no_attached_key 0x4;
+            flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
+            flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
+            flag key_reset_only 0x20;
+        }
+
+        doc | (FIXME: The exceptions may not be correct or complete)
+
+        throws key_not_found doc="at least one of the receipient keys could not be found";
+
+        throws key_has_ambig_name doc="at least one of the receipient keys has an ambiguous name";
+
+        throws get_key_failed doc="cannot retrieve key";
+    }
+
+
+    method decrypt_message doc="decrypt message in memory"
+    {
+        // parms
+
+        lend message src
+        doc="""
+            message to decrypt. 
+            The ownership of src remains with the caller - however, the contents 
+            might be modified (strings freed and allocated anew or set to empty,
+            etc) intentionally; when this happens, decrypt_flag_src_modified is set.
+            """;
+
+        create message dst doc="pointer to new decrypted message or empty on failure";
+
+        lend hash_list keylist
+        doc="""
+            in: stringlist with additional keyids for reencryption if needed
+                (will be freed and replaced with output keylist)
+            out: stringlist with keyids used for signing and encryption. first
+                first key is signer, additional keys are the ones it was encrypted
+                to. Only signer and whichever of the user's keys was used are reliable.
+            The ownership of keylist goes to the caller.
+            If src is unencrypted this function returns unencrypted and sets dst to empty.
+            """;
+
+        return rating msg_rating doc="rating for the message";
+
+        // flags
+        
+        flags {
+            flag decrypt_flag_own_private_key 0x1 
+            doc="""
+                private key was imported for one of our addresses (NOT trusted
+                or set to be used - handshake/trust is required for that)
+                """;
+            flag decrypt_flag_consume 0x2 doc='used by sync';
+            flag decrypt_flag_ignore 0x4 doc='used by sync';
+            flag decrypt_flag_src_modified 0x8 
+            doc="""
+                indicates that the src object has been modified. At the moment,
+                this is always as a direct result of the behaviour driven
+                by the input flags. This flag is the ONLY value that should be
+                relied upon to see if such changes have taken place.
+                """;
+            flag decrypt_flag_untrusted_server 0x100 
+            doc="""
+                input flag. Used to signal that decrypt function should engage in behaviour
+                specified for when the server storing the source is untrusted.
+                """;
+            flag decrypt_flag_dont_trigger_sync 0x200;
+        }
+
+        // exceptions
+    
+        throws decrypted doc="if message decrypted but not verified";
+
+        throws cannot_reencrypt
+        doc="""
+            if message was decrypted (and possibly verified) but a reencryption 
+            operation is expected by the caller and failed.
+            """;
+
+        throws unencrypted
+        doc="""
+            if src is unencrypted this function returns unencrypted and sets
+            dst to empty.
+            """;
+
+        throws any doc="all error status values allowed";
+    }
+
+
+    method own_message_private_key_details
+    doc="""
+        details on own key in own message. Note: In order to obtain details about key