not finished. as far as I got today. for tm

api/keymanagement_api.yml2

@@ -7,3 +7,213 @@
 // written by Volker Birk
 
 
+protocol session {
+	method update_identity
+		doc="update identity information"
+	{
+	// parms
+
+	supply 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 initialise_own_identities
+		doc="ensures that an own identity is complete"
+	{
+	// parms
+	
+	supply identity_list my_idents
+	doc="""
+		identities of local user to quick-set
+		For these, at least .address must be set.
+		if no .user_id is set, AND the DB doesn't contain
+		a default user_id, own_userid will be used and
+		become the perennial default for the DB.
+		
+		This function does NOT generate keypairs. It is intended to
+		precede running of the engine on actual messages. It effectively
+		behaves like myself(), but when there would normally be key generation
+		(when there is no valid key, for example),
+		it instead stores an identity without keys.
+
+		N.B. to adapter devs - this function is likely unnecessary, so please
+		do not put work into exposing it yet. Tickets will be filed if need be.
+		"""
+	}
+
+
+	method myself
+		doc="ensures that an own identity is complete"
+	{
+	// parms
+
+	supply identity identity
+	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 retrieve_next_identity
+		doc="callback being called by do_keymanagement"
+	{
+	// parms
+
+XXXXXX
+
+	method examine_identity
+		doc="callback for appending to queue"
+	{
+	// parms
+
+XXXX
+
+	method register_examine_function
+		doc="register examine_identity() callback"
+	{
+	//parms
+
+	provide?? examine_identity?? examine_identity doc="examine_identity() function to register";
+
+	provide void management doc="data structure to deliver (implementation defined)"
+
+XXX?
+// do_keymanagement() - function to be run on an extra thread
+//
+//  parameters:
+//      retrieve_next_identity (in) pointer to retrieve_next_identity()
+//                                  callback which returns at least a valid
+//                                  address field in the identity struct
+//
+//  return value:
+//      PEP_STATUS_OK if thread has to terminate successfully or any other
+//      value on failure
+//
+//  caveat:
+//      to ensure proper working of this library, a thread has to be started
+//      with this function immediately after initialization
+//
+//      do_keymanagement() calls retrieve_next_identity(management)
+//
+//      messageToSend can only be null if no transport is application based
+//      if transport system is not used it must not be NULL
+DYNAMIC_API PEP_STATUS do_keymanagement(
+        retrieve_next_identity_t retrieve_next_identity,
+        void *management
+
+
+	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
+
+	ident (in)          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.
+//
+//  caveat:
+//      the fields user_id, address and fpr must be supplied
+//      own identities will result in a return of PEP_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.
+
+DYNAMIC_API PEP_STATUS trust_personal_key(
+        PEP_SESSION session,
+        pEp_identity *ident
+
+
+
+
+
+
+   
+
+
+
+
+
+
+

api/message_api.yml2

@@ -7,6 +7,70 @@
 // written by Volker Birk
 
 
+enum text_format {
+	hex text_format_plain 0x0;
+	hex text_format_html 0x01;
+	hex text_format_other 0xff;
+}
+
+
+enum msg_direction {
+	hex dir_incoming 0x0;
+	hex dir_outgoing 0x01;
+}
+
+
+enum enc_format {
+	hex enc_none 0x0 doc='message is not encrypted';
+	hex enc_pieces 0x01 doc='inline PGP + PGP extensions';
+	hex enc_S_MIME 0x02 doc='RFC5751';
+	hex enc_PGP_MIME 0x04 doc='RFC3156';
+	hex enc_PEP 0x08 doc='pEp encryption format';
+	hex enc_PGP_MIME_Outlook1 0x10 doc='Message B0rken by Outlook type 1';
+}
+
+
+enum message_wrap_type {
+	message_default doc='typical inner/outer message 2.0';
+	message_transport doc='e.g. for onion layers';
+	message_key_reset doc='for wrapped key reset information';
+}
+
+
+struct message {
+field msg_direction dir;
+	field string id doc='UTF-8 string of message ID';
+	field string shortmsg doc='UTF-8 string of short message';
+	field string longmsg doc='UTF-8 string of long message'(plain)';
+	field string longmsg_formatted doc='UTF-8 string of long message (formatted)';
+   	field bloblist_t attachments doc='blobs with attachements';
+	field char 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 pEp_identity from doc='whom the message is from';
+	field identity_list to doc='whom the message is to';
+	field pEp_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 in_reply_to doc='list of UTF-8 strings with MessageIDs of refering messages';
+	field struct _message refering_msg_ref doc='reference to refering message';
+	field string references doc='list of UTF-8 strings with references';
+	field struct _message_ref_list refered_by doc='list of references to messages being refered';
+    field string keywords doc='list of UTF-8 strings with keywords';
+    field string char comments doc='UTF-8 string with comments';
+    field stringpair_list_t opt_fields doc='optional fields';
+    field enc_format enc_format doc='format of encrypted data';
+}
+
+
+struct message_ref_list {
+    field message msg_ref doc='reference to message';
+    field struct _message_ref_list next;
+}
+
+
 protocol session {
     method encrypt_message
         doc="encrypt message in memory"
@@ -26,9 +90,9 @@ protocol session {
         doc="""
             pointer to new encrypted message or #NV if no encryption could
             take place
-            """
+            """;
 
-        use enc_format enc_format doc="encrypted format";
+        use enc_format format doc="encrypted format";
 
         // flags
 
@@ -39,19 +103,18 @@ protocol session {
 			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
+			flag key_reset_only 0x20;
         }
 
         // exceptions
 
-        throws key_has_ambig_name
-            doc="at least one of the receipient keys has an ambiguous name";
+        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 
-            """
+            """;
     }
 
 
@@ -63,12 +126,12 @@ protocol session {
 		use message src doc="message to encrypt";
 
 		create message dst
-		doc="pointer to new encrypted message or NULL if no encryption could take place";
+			doc="pointer to new encrypted message or NULL if no encryption could take place";
 
-		const char to_fpr
-		doc="fingerprint of the recipient key to which the private key should be encrypted";
+		use const char to_fpr
+			doc="fingerprint of the recipient key to which the private key should be encrypted";
 
-		use enc_format enc_format doc="encrypted format";
+		use enc_format format doc="encrypted format";
 
 		// flags
 
@@ -79,19 +142,18 @@ protocol session {
 			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
+			flag key_reset_only 0x20;
 		}
 
 		// exceptions
 
-		throws key_has_ambig_name
-			doc="at least one of the receipient keys has an ambiguous name";
+		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
-				"""
+				""";
 	}
 
 
@@ -105,17 +167,17 @@ protocol session {
 
 		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!)
+			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";
 
-		provide hash_list extra doc="extra keys for encryption";
+		use hash_list extra doc="extra keys for encryption";
 
 		create message dst doc="pointer to new encrypted message or NULL on failure";
 
-		use enc_format enc_format? doc="encrypted format";
+		use enc_format format doc="encrypted format";
 
 		// flags
 
@@ -126,59 +188,16 @@ protocol session {
 			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
+			flag key_reset_only 0x20;
 		}
 
-		// exceptions
+		// exceptions doc="(FIXME: This may not be correct or complete)"
 
-		throws key_not_found
-			doc="at least one of the receipient keys could not be found";
+		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 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 color_from_rating
-		doc="calculate color from rating"
-	{
-		// parms
-	
-		provide color_from_rating rating
-		doc="color representing that rating";
-
-		// ratings
-
-		ratings {
-			rating_undefined 0;
-			rating_cannot_decrypt,
-			rating_have_no_key,
-			rating_unencrypted,
-			rating_unencrypted_for_some doc="don't use this any more",
-			rating_unreliable,
-			rating_reliable,
-			rating_trusted,
-			rating_trusted_and_anonymized,
-			rating_fully_anonymous,
-			rating_mistrust -1;
-			rating_b0rken -2;
-			rating_under_attack -3
-		}
-
-		// colors
-
-		colors {
-			color_no_color 0;
-			color_yellow,
-			color_green,
-			color_red -1
-		}
-
-		// return value
-			doc="color representing that rating"
+		throws get_key_failed doc="cannot retrieve key";
 	}
 
 
@@ -195,8 +214,7 @@ protocol session {
 		etc) intentionally; when this happens, decrypt_flag_src_modified is set.
 		""";
 
-	create message dst
-	doc="pointer to new decrypted message or NULL on failure";
+	create message dst doc="pointer to new decrypted message or NULL on failure";
 
 	supply hash_list keylist
 	doc="""
@@ -205,10 +223,11 @@ protocol session {
 		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 NULL.
 		""";
 
-	return rating rating
-	doc="rating for the message";
+	return rating msg_rating doc="rating for the message";
 
 	// flags
 	
@@ -217,7 +236,7 @@ protocol session {
 		doc="""
 			private key was imported for one of our addresses (NOT trusted
 			or set to be used - handshake/trust is required for that)
-			"""
+			""";
 		decrypt_flag_consume 0x2 doc=’used by sync';
 		decrypt_flag_ignore 0x4 doc=’used by sync';
 		decrypt_flag_src_modified 0x8 
@@ -231,13 +250,12 @@ protocol session {
 		doc="""
 			input flags. Used to signal that decrypt function should engage in behaviour
 			specified for when the server storing the source is untrusted.
-			"""
+			""";
 	}
 
 	// exceptions
 	
-	throws decrypted
-		doc="if message decrypted but not verified";
+	throws decrypted doc="if message decrypted but not verified";
 
 	throws cannot_reencrypt
 		doc="""
@@ -249,12 +267,19 @@ protocol session {
 		doc="""
 			if src is unencrypted this function returns unencrypted and sets
 			dst to NULL.
-			"""
+			""";
+
+	throws any doc="error status";
 	}
 
 
 	method own_message_private_key_details
-		doc="details on own key in own message"
+		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.
+			"""
 	{
 	//parms
 
@@ -264,8 +289,11 @@ 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";
+
+	// exceptions
+
+	throws any doc="error status"
 	}
 
 
@@ -280,8 +308,11 @@ protocol session {
 		Dir must be dir_outgoing.
 		""";
 
-	create rating rating
-	doc="rating for the message"
+	return rating msg_rating doc="rating for the message";
+
+	// exceptions
+
+	throws any doc="error status"
 	}
 
 
@@ -296,8 +327,11 @@ protocol session {
 		Dir must be dir_outgoing.
 		""";
 
-	create rating rating
-	doc="rating preview for the message"
+	return rating msg_rating doc="rating preview for the message";
+
+	// exceptions
+
+	throws any doc="error status"
 	}
 
 
@@ -306,27 +340,13 @@ protocol session {
 	{
 	//parms
 
-	use identity ident
-	doc="identity to get the rating for";
-
-	create rating rating
-	doc="rating for the identity"
-	}
-
+	use identity ident doc="identity to get the rating for";
 
-	method get_binary_path
-		doc="retrieve path of cryptotech binary if available"
-	{
-	//parms
+	return rating identity_rating doc="rating for the identity";
 
-	use @type tech
-	doc="cryptotech to get the binary for";
+	// exceptions
 
-	use @type path
-	doc="""
-		path to cryptotech binary or NULL if not available. **path is owned by 
-		the library, do not change it!
-		"""
+	throws any doc="error status"
 	}
 
 
@@ -335,14 +355,11 @@ protocol session {
 	{
 	//parms
 
-	provide const identity id1
-		doc="identity of first party in communication - fpr can't be NULL";
+	use const identity id1 doc="identity of first party in communication - fpr can't be NULL";
 
-	provide const identity id2
-		doc="identity of second party in communication - fpr can't be NULL";
+	use const identity id2 doc="identity of second party in communication - fpr can't be NULL";
 
-	provide const char lang
-		doc="C string with ISO 639-1 language code";
+	use const char lang doc="C string with ISO 639-1 language code";
 
 	create char words
 		doc="""
@@ -353,15 +370,14 @@ protocol session {
 			The caller is responsible to free() it (on Windoze use pEp_free())
 			""";
 
-	create size_t wsize
-		doc="length of full trustwords string";
+	create size_t wsize doc="length of full trustwords string";
 
-	provide bool full
+	use bool full
 		doc="""
 			if true, generate ALL trustwords for these identities.
 			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
 			subset in next version)
-			"""
+			""";
 
 	// exceptions
 
@@ -369,7 +385,7 @@ protocol session {
 		doc="out of memory";
 
 	throws trustword_not_found
-		doc="at least one trustword not found"
+		doc="at least one trustword not found";
 	}
 
 
@@ -378,17 +394,14 @@ protocol session {
 	{
 	//parms
 
-	provide message msg
-		doc="message to get sender identity from";
+	use message msg doc="message to get sender identity from";
 
-	provide hash_list keylist
+	use hash_list keylist
 		doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
 
-	provide identity received_by
-		doc="identity for account receiving message can't be NULL";
+	use identity received_by doc="identity for account receiving message can't be NULL";
 
-	provide const char lang
-		doc="C string with ISO 639-1 language code";
+	use string lang doc="C string with ISO 639-1 language code";
 
 	create char words
 		doc="""
@@ -398,20 +411,20 @@ protocol session {
 			The caller is responsible to free() it (on Windoze use pEp_free())
 			""";
 
-	provide bool full
+	use bool full
 		doc="""
 			if true, generate ALL trustwords for these identities.
 			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
 			subset in next version)
-			"""
+			""";
 
 	// exceptions
 
-	throws out_of_memory
-		doc="out of memory";
+	throws out_of_memory doc="out of memory";
 
-	throws trustword_not_found
-		doc="at least one trustword not found"
+	throws trustword_not_found doc="at least one trustword not found";
+
+	throws like decrypt_message doc="error status of decrypt_message() if decryption fails"
 	}
 
 
@@ -423,14 +436,11 @@ protocol session {
 	use message msg
 		doc="message to get the rating for. msg->from must point to a valid pEp_identity";
 
-	use hash_list x_keylist
-		doc="decrypted message recipients keys fpr";
+	use hash_list x_keylist doc="decrypted message recipients keys fpr";
 
-	provide rating x_enc_status
-		doc="original rating for the decrypted message";
+	use rating x_enc_status doc="original rating for the decrypted message";
 
-	create message rating
-		doc="rating for the message"
+	return rating msg_rating doc="rating for the message";
 
 	// exceptions
 
@@ -441,8 +451,7 @@ protocol session {
 			contain X-Keylist optional field and x_keylist is NULL.
 			""";
 
-	throws out_of_memory
-		doc="if not enough memory could be allocated"
+	throws out_of_memory doc="if not enough memory could be allocated";
 	}
 
 
@@ -451,14 +460,11 @@ protocol session {
 	{
 	//parms
 
-	provide const char user_id
-		doc="string with user ID";
+	use string user_id doc="string with user ID";
 
-	provide const char fpr
-		doc="string with fingerprint";
+	use string fpr doc="string with fingerprint";
 
-	create rating rating
-		doc="rating of key for this user"
+	return rating key_rating doc="rating of key for this user";
 		
 	// exceptions
 
@@ -468,11 +474,37 @@ protocol session {
 }	
 
 
+	func color_from_rating
+		doc="calculate color from rating"
+	{
+		// parms
 
+		provide color_from_rating rating doc="color representing that rating"
 
+		// return value
+		return color rating_color doc="color representing that rating"
+}
 
- 
 			
+	func get_binary_path
+		doc="retrieve path of cryptotech binary if available"
+	{
+	//parms
+
+	use cryptotech tech
+	doc="cryptotech to get the binary for";
+
+	use string path
+	doc="""
+		path to cryptotech binary or NULL if not available. **path is owned by 
+		the library, do not change it!;
+		"""
+}
+
+
+
+
+
 
 
 
@@ -484,6 +516,37 @@ protocol session {
 
 
 
+	// ratings
+
+	ratings {
+		item rating_undefined 0;
+		item rating_cannot_decrypt 1;
+		item rating_have_no_key 2;
+		item rating_unencrypted 3;
+		item rating_unencrypted_for_some doc="don't use this any more",
+		item rating_unreliable 4;
+		item rating_reliable 5;
+		item rating_trusted 6;
+		item rating_trusted_and_anonymized 7;
+		item rating_fully_anonymous 8;
+		item rating_mistrust -1;
+		item rating_b0rken -2;
+		item rating_under_attack -3;
+	}
+
+	// colors
+
+	colors {
+		item color_no_color 0;
+		item color_yellow 1;
+		item color_green 2;
+		item color_red -1;
+	}
+
+
+
+
+