DSL update

api/basic_api.yml2

@@ -169,7 +169,7 @@ protocol session {
 
         // exceptions
 
-        throws any doc="error status";
+        throws any doc="any other value on error";
     }
 
 
@@ -219,6 +219,8 @@ protocol session {
             ciphersuite for a crypt tech implementation is implementation 
             defined.
             """;
+            
+       throws illegal_value doc="illegal parameter values";
     }
 
 
@@ -237,6 +239,10 @@ protocol session {
         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";
+        
+        // exceptions
+
+       throws illegal_value doc="illegal parameter values";
     }
 
 
@@ -259,6 +265,10 @@ protocol session {
             results were returned, but no ID found (no reason this 
             should ever occur).
             """;
+            
+       throws illegal_value doc="illegal parameter value";
+       
+       throws out_of_memory doc="out of memory";
     }
 
 
@@ -267,13 +277,22 @@ protocol session {
         // parms
 
         use hash fpr doc="fingerprint of key to mark";
+        
+        // exceptions
+            
+       throws illegal_value doc="illegal parameter value";
+       
+       throws cannot_set_trust:
     }
 
 
     method mark_as_compromized doc="deprecated to fix misspelling. Please move to mark_as_compromised"
 
 
-    method import_key doc="import key from data"
+    method import_key_with_fpr_return 
+    doc="""
+        import keys from data, return optional list of fprs imported
+        """;
     {
         // parms
 
@@ -283,9 +302,29 @@ protocol session {
 
         create identity_list private_keys 
         doc="""
-            list of private keys that have been imported. private_keys can 
-            be left NULL, it is then ignored.
+            list of identities containing the private keys that have been imported. Private_keys
+            and imported_keys can be left NULL, it is then ignored.
+            *** THIS IS THE ACTUAL FUNCTION IMPLEMENTED BY CRYPTOTECH "import_key" ***
             """;
+            
+        create identity_list imported keys doc="if non-NULL, list of actual keys imported"
+        
+        create identity_list changed_public_keys
+        doc="""
+            if non-NULL AND imported_keys is non-NULL: bitvector - corresponds to the first 
+            64 keys imported. If nth bit is set, import changed a key corresponding to the nth 
+            element in imported keys (i.e. key was in DB and was changed by import).
+            """;
+            
+        // exceptions
+
+        throws out_of_memory doc="out of memory";
+        
+        throws illegal_value 
+        doc="""
+            there is no key data to import, or imported keys was NULL and changed_public_keys 
+            was not.
+            """;    
     }
 
 
@@ -293,7 +332,7 @@ protocol session {
     {
         // parms
 
-        use hash fpr doc="key id or fingerprint of key";
+        use hash fpr doc="fingerprint of key";
 
         create string key_data 
         doc="""
@@ -308,6 +347,8 @@ protocol session {
         throws out_of_memory doc="out of memory";
 
         throws key_not_found doc="key not found";
+        
+        throws illegal_value doc="illegal parameter value";
     }
 
 
@@ -333,6 +374,8 @@ protocol session {
         throws key_not_found doc="key not found";
 
         throws cannot_export_key doc="cannot export secret key (i.e. it's on an HKS)";
+        
+        throws illegal_value doc="illegal parameter value";
     }
 
 
@@ -353,6 +396,14 @@ protocol session {
             column3 is description
             column4 is comment
             """;
+            
+        // exceptions
+
+        throws out_of_memory doc="out of memory";
+        
+        throws illegal_value doc="illegal parameter value";
+        
+        throws unknown_error;
     }
 
 
@@ -366,6 +417,14 @@ protocol session {
             column 1 is the ISO 639-1 language code
             column 2 is the name of the language
             """;
+            
+       // exceptions
+
+        throws out_of_memory doc="out of memory";
+        
+        throws illegal_value doc="illegal parameter value";
+        
+        throws unknown_error;
     }
 
 
@@ -378,6 +437,16 @@ protocol session {
         use int phrase_id doc="id of phrase in i18n";
 
         create string phrase doc="phrase as UTF-8 string";
+        
+        // exceptions
+
+        throws out_of_memory doc="out of memory";
+        
+        throws illegal_value doc="illegal parameter value";
+        
+        throws unknown_db_error:
+        
+        throws phrase_not_found;
     }
 
 
@@ -391,14 +460,13 @@ protocol session {
 
         // exceptions
 
-        throws any doc="string to the engine version string constant"; 
+        throws engine_version; 
     }
 
     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
@@ -427,13 +495,17 @@ protocol session {
     {
         // exceptions
 
-        throws any doc="path to actual per user directory or NULL on failure";
+        throws char* doc="path to actual per user directory";
+        
+        throws NULL doc="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";
+        throws char* doc="path to actual per machine directory";
+        
+        throws NULL doc="on failure";
     }
 }

api/keymanagement_api.yml2

@@ -49,13 +49,7 @@ protocol session {
             *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
-            """;
+        throws any doc="any other value on error";
     }
 
 
@@ -86,6 +80,14 @@ protocol session {
             if you need to do this asynchronous, you need to return an identity
             with retrieve_next_identity() where identity.me is true.
             """;
+
+        // exceptions
+
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -123,6 +125,16 @@ protocol session {
             is not trusted, and 3) set this key as the user default if the current user
             default is not trusted.
             """;
+            
+        // exceptions
+
+        throws key_unsuitable;
+        
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -146,6 +158,16 @@ protocol session {
             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!
             """;
+            
+        // exceptions
+
+        throws key_unsuitable;
+        
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -166,6 +188,14 @@ protocol session {
             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).
             """;
+            
+        // exceptions
+        
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -176,6 +206,12 @@ protocol session {
         use hash fpr doc="fingerprint of key to test";
 
         return bool listed doc="flags if key is own";
+        
+        // exceptions
+        
+        throws illegal_value doc="illegal parameter values";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -189,6 +225,14 @@ protocol session {
             list of own identities. 
             The ownership of the copy of own_identities goes to the caller.
             """;
+        
+        // exceptions
+        
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -201,6 +245,14 @@ protocol session {
             list of fingerprints. This function does not return keys without 
             a private key part.
             """;
+            
+        // exceptions
+        
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -210,17 +262,28 @@ protocol session {
 
         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.
+            own identity this key is used for. 
+            The key has to be in the key ring already identity->address must be set to valid 
+            data update_identity() is called by this function and will create a TOFU user_id + 
+            new entry if none is indicated and heuristic fails to match extant identity identity-
+            >fpr will NOT be updated with the set identity fpr; it is only in,out because 
+            update_identity() is called before setting it.
             """;
 
         use hash fpr doc="fingerprint of the key to mark as own key";
+        
+        // exceptions
+        
+        throws key_unsuitable;
+        
+        throws illegal_value 
+        doc="""
+            illegal parameter values, including if update_identity determines this is an own 
+            identity""";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 }
 

api/message_api.yml2

@@ -152,6 +152,12 @@ protocol session {
             on demand or no recipients with usable key, is left unencrypted,
             and key is attached to it 
             """;
+            
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -194,6 +200,16 @@ protocol session {
                 on demand or no recipients with usable key, is left unencrypted, 
                 and key is attached to it
                 """;
+                
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
+        throws any doc="any other value on error";
+        
+        throws unknown_error;
+        
+        throws any doc="any other value on error";         
     }
 
 
@@ -231,13 +247,19 @@ protocol session {
             flag key_reset_only 0x20;
         }
 
-        doc | (FIXME: The exceptions may not be correct or complete)
+        // exceptions
 
         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";
+        
+        throws cannot_find_identity;
+        
+        throws illegal_value;
+        
+        throws out_of_memory;
     }
 
 
@@ -248,9 +270,23 @@ protocol session {
         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,
+            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.
+            
+            if src is unencrypted this function returns PEP_UNENCRYPTED and sets dst to NULL
+            if src->enc_format is PEP_enc_inline_EA on input then elevated attachments
+            will be expected
+            
+            decrypt_message RELIES on the fact that identity information provided in src 
+            for recips and sender is AS TAKEN FROM THE ORIGINAL PARSED MESSAGE. This means 
+            that if update_identity or myself is called on those identities by the caller 
+            before passing the message struct to decrypt_message, the caller will have to 
+            cache and restore those to their original state before sending them to this  
+            function. ADAPTERS AND APPLICATIONS PLEASE TAKE NOTE OF THIS. (Obviously, this 
+            doesn't include information like user_ids, but we very specifically need the 
+            incoming usernames preserved so that they can be handled by the internal 
+            algorithm appropriately)
             """;
 
         create message dst doc="pointer to new decrypted message or empty on failure";
@@ -271,30 +307,33 @@ protocol session {
         // flags
         
         flags {
+            flag decrypt_flag_untrusted_server 0x100 
+            doc="""
+                incoming flag. Used to signal that decrypt function should engage in behaviour
+                specified for when the server storing the source is untrusted.
+                """;
             flag decrypt_flag_own_private_key 0x1 
             doc="""
-                private key was imported for one of our addresses (NOT trusted
+                outgoing flag: 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.
+                outgoing flag: 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. 
                 """;
-            flag decrypt_flag_untrusted_server 0x100 
+            flag decrypt_flag_consume 0x2 
             doc="""
-                input flag. Used to signal that decrypt function should engage in behaviour
-                specified for when the server storing the source is untrusted.
+                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
                 """;
-            flag decrypt_flag_dont_trigger_sync 0x200;
+            flag decrypt_flag_ignore 0x4 doc='used by sync';
         }
 
         // exceptions
     
+        throws error doc="any error status";
+        
         throws decrypted doc="if message decrypted but not verified";
 
         throws cannot_reencrypt
@@ -308,18 +347,10 @@ protocol session {
             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 
-        to be possibly imported as a replacement of key currently used as own identity, 
-        application passes message that have been previously flagged by decrypt_message() 
-        as own message containing own key to this function.
-        """
+    method own_message_private_key_details doc="details on own key in own message."
     {
         // parms
 
@@ -329,11 +360,20 @@ protocol session {
             can check own signature.
             """;
 
-        create identity ident doc="identity containing uid, address and fpr of key";
+        create identity ident 
+        doc="""
+            identity containing uid, address and fpr of key. 
+            note: In order to obtain details about key to be possibly imported as a replacement 
+            of key currently used as own identity, application passes message that have been 
+            previously flagged by decrypt_message() as own message containing own key to this 
+            function.
+            """;
 
         // exceptions
 
-        throws any doc="error status";
+        throws illegal_value doc="illegal parameter values";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -343,15 +383,15 @@ protocol session {
 
         use message msg
         doc="""
-            message to get the rating for. From must point to a valid pEp_identity.
-            Dir must be dir_outgoing.
+            message to get the rating for. From must point to a valid pEp_identity
+            msg->dir must be PEP_dir_outgoing
             """;
 
         return rating msg_rating doc="rating for the message";
 
         // exceptions
 
-        throws any doc="error status";
+        throws illegal_value doc="illegal parameter values";
     }
 
 
@@ -362,14 +402,14 @@ protocol session {
         use message msg
         doc="""
             message to get the rating for. From must point to a valid pEp_identity.
-            Dir must be dir_outgoing.
+            msg->dir must be dir_outgoing.
             """;
 
         return rating msg_rating doc="rating preview for the message";
 
         // exceptions
 
-        throws any doc="error status";
+        throws illegal_value doc="illegal parameter values";
     }
 
 
@@ -383,7 +423,9 @@ protocol session {
 
         // exceptions
 
-        throws any doc="error status";
+        throws illegal_value doc="illegal parameter values";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -399,12 +441,14 @@ protocol session {
 
         create string words
         doc="""
-            string with all trustwords, separated 
+            pointer to string with all trustwords, separated 
             by a blank each. Empty if language is not supported or trustword 
             wordlist is damaged or unavailable. 
             The word pointer goes to the ownership of the caller. 
             The caller is responsible to free() it (on Windoze use pEp_free())
             """;
+            
+        create size_t wsize doc="length of full trustwords string";
 
         use bool full
         doc="""
@@ -416,6 +460,8 @@ protocol session {
         // exceptions
 
         throws out_of_memory doc="out of memory";
+        
+        throws illegal_value doc="illegal parameter values";
 
         throws trustword_not_found doc="at least one trustword not found";
     }
@@ -435,7 +481,7 @@ protocol session {
 
         create string words
         doc="""
-            string with all trustwords, separated by a blank each.
+            pointer to string with all trustwords, separated by a blank each.
             Empty if language is not supported or trustword  wordlist is damaged or unavailable.
             """;
 
@@ -448,11 +494,15 @@ protocol session {
 
         // exceptions
 
+        throws illegal_value doc="illegal parameter values";
+        
         throws out_of_memory doc="out of memory";
 
         throws trustword_not_found doc="at least one trustword not found";
 
-        throws like decrypt_message doc="error status of decrypt_message() if decryption fails";
+        throws cannot_find_identity doc="identity not found";
+        
+        throws error doc="status of decrypt_message() if decryption fails.";
     }
 
 
@@ -469,7 +519,7 @@ protocol session {
         create string words 
         doc="""
             pointer to string with all trustwords UTF-8 encoded, separated by a blank each. 
-            NULL if language is not supported or trustword wordlist is damaged or unavailable.
+            Empty if language is not supported or trustword wordlist is damaged or unavailable.
             The caller is responsible to free() it (on Windoze use pEp_free()).
             """;
 
@@ -484,6 +534,8 @@ protocol session {
         // exceptions
 
         throws out_of_memory doc="out of memory";
+        
+        throws illegal_value doc="illegal parameter values";
 
         throws trustword_not_found doc="at least one trustword not found";
     }
@@ -511,6 +563,8 @@ protocol session {
             """;
 
         throws out_of_memory doc="if not enough memory could be allocated";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -526,7 +580,13 @@ protocol session {
         
         // exceptions
 
+        throws illegal_value doc="illegal parameter values";
+        
+        throws out_of_memory doc="out of memory";
+        
         throws record_not_found doc="if no trust record for user_id and fpr can be found";
+        
+        throws any doc="any other value on error";
     }
 
 
@@ -538,7 +598,7 @@ protocol session {
 
         // exceptions
 
-        throws any doc="rating value for comm type ct";
+        throws rating doc="rating value for comm type ct";
     }
 }