pEpEngine/api/message_api.yml2

// p≡p Message API

// Copyleft (c) 2019, p≡p foundation
// this file is under GNU General Public License 3.0
// see LICENSE.txt

// written by Volker Birk


protocol session {
    method encrypt_message
        doc="encrypt message in memory"
    {
        // parms

        supply 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 encformat 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 
            """
    }
}


protocol session {
	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 NULL if no encryption could take place";

		to_fpr
		doc="fingerprint of the recipient key to which the private key should be encrypted";

		use format enc_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
				"""
	}
}


protocol session {
	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 message target_id
		doc="self identity this message should be encrypted for";

		use message src
		doc="message to encrypt";

		provide key? extra
		doc="extra keys for encryption";

		create message dst
		doc="pointer to new encrypted message or NULL on failure";

		use format enc_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_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"
	}
}


protocol session {
	method color_from_rating
		doc="calculate color from rating"
	{
		// parms
	
		provide message 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"
	}
}


protocol session {
	method decrypt_message
		doc="decrypt message in memory"
	{
	// parms

	supply 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 NULL,
		etc) intentionally; when this happens, decrypt_flag_src_modified is set.
		""";

	create message dst
	doc="pointer to new decrypted message or NULL on failure";

	supply message 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.
		""";

	return message rating
	doc="rating for the message";

	// flags
	
	decrypt_flags {
		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)
			"""
		decrypt_flag_consume 0x2 doc=’used by sync';
		decrypt_flag_ignore 0x4 doc=’used by sync';
		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.
			""";
		decrypt_flag_untrusted_server 0x100 
		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 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 NULL.
			"""
	}
}


protocol session {
	method own_message_private_key_details
		doc="details on own key in own message"
	{
	//parms

	use message msg
	doc="""
		message to decrypt. msg MUST be encrypted so that this function 
		can check own signature.
		""";

	create @type? ident
	doc="identity containing uid, address and fpr of key"
	}
}


protocol session {
	method outgoing_message_rating
		doc="get rating for an outgoing message"
	{
	//parms

	use message msg
	doc="""
		message to get the rating for. From must point to a valid pEp_identity.
		Dir must be dir_outgoing.
		""";

	create message rating
	doc="rating for the message"
	}
}


protocol session {
	method outgoing_message_rating_preview
		doc="get rating preview"
	{
	//parms

	use message msg
	doc="""
		message to get the rating for. From must point to a valid pEp_identity.
		Dir must be dir_outgoing.
		""";

	create message rating
	doc="rating preview for the message"
	}
}


protocol session {
	method identity_rating
		doc="get rating for a single identity"
	{
	//parms

	use @type ident
	doc="identity to get the rating for";

	create identity rating
	doc="rating for the identity"
	}
}


protocol session {
	method get_binary_path
		doc="retrieve path of cryptotech binary if available"
	{
	//parms

	use @type tech
	doc="cryptotech to get the binary for";

	use @type path
	doc="""
		path to cryptotech binary or NULL if not available. **path is owned by 
		the library, do not change it!
		"""
	}
}


protocol session {
	method get_trustwords
		doc="get full trustwords string for a *pair* of identities"
	{
	//parms

	provide message id1
		doc="identity of first party in communication - fpr can't be NULL";

	provide message id2
		doc="identity of second party in communication - fpr can't be NULL";

	provide message lang
		doc="C string with ISO 639-1 language code";

	create message words
		doc="""
			pointer to C 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. 
			The word pointer goes to the ownership of the caller. 
			The caller is responsible to free() it (on Windoze use pEp_free())
			""";

	create @type? wsize
		doc="length of full trustwords string";

	provide @type 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 trustword_not_found
		doc="at least one trustword not found"
	}
}


protocol session
	method get_message_trustwords
		doc="get full trustwords string for message sender and reciever identities"
	{
	//parms

	provide @type msg
		doc="message to get sender identity from";

	provide message keylist
		doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";

	provide message received_by
		doc="identity for account receiving message can't be NULL";

	provide @type? lang
		doc="C string with ISO 639-1 language code";

	create message words
		doc="""
			pointer to C 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.
			The word pointer goes to the ownership of the caller. 
			The caller is responsible to free() it (on Windoze use pEp_free())
			""";

	provide @type 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 trustword_not_found
		doc="at least one trustword not found"
	}
}


protocol session
	method re_evaluate_message_rating
		doc="re-evaluate already decrypted message rating"
	{
	//parms

	use @type msg
		doc="message to get the rating for. msg->from must point to a valid pEp_identity";

	use message x_keylist
		doc="decrypted message recipients keys fpr";

	provide message x_enc_status
		doc="original rating for the decrypted message";

	create message rating
		doc="rating for the message"

	// exceptions

	throws illegal_value
		doc="""
			if decrypted message doesn't contain X-EncStatus optional field and 
			x_enc_status is pEp_rating_udefined or if decrypted message doesn't 
			contain X-Keylist optional field and x_keylist is NULL.
			""";

	throws out_of_memory
		doc="if not enough memory could be allocated"
	}
}


protocol session
	method get_key_rating_for_user
		doc="get the rating of a certain key for a certain user"
	{
	//parms

	provide @type? user_id
		doc="string with user ID";

	provide @type fpr
		doc="string with fingerprint";

	create @type rating
		doc="rating of key for this user"
		
	// exceptions

	throws record_not_found
		doc="if no trust record for user_id and fpr can be found"
	}
}