first version message_api.yml2 from Nana generate_api
authornana
Thu, 14 Feb 2019 18:34:23 +0100
branchgenerate_api
changeset 329721c1c1b8b51f
parent 3290 2725d35abc37
child 3298 9b65e15820d5
first version message_api.yml2 from Nana
api/message_api.yml2
     1.1 --- a/api/message_api.yml2	Mon Feb 11 17:47:12 2019 +0100
     1.2 +++ b/api/message_api.yml2	Thu Feb 14 18:34:23 2019 +0100
     1.3 @@ -35,6 +35,11 @@
     1.4          flags {
     1.5              flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
     1.6              flag force_encryption 0x1;
     1.7 +			flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
     1.8 +			flag force_no_attached_key 0x4;
     1.9 +			flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
    1.10 +			flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
    1.11 +			flag key_reset_only 0x20
    1.12          }
    1.13  
    1.14          // exceptions
    1.15 @@ -50,3 +55,477 @@
    1.16      }
    1.17  }
    1.18  
    1.19 +
    1.20 +protocol session {
    1.21 +	method encrypt_message_and_add_priv_key
    1.22 +		doc="encrypt message in memory, adding an encrypted private key (encrypted separately and sent within the inner message)"
    1.23 +	{
    1.24 +		// parms
    1.25 +
    1.26 +		use message src 
    1.27 +		doc="message to encrypt";
    1.28 +
    1.29 +		create message dst
    1.30 +		doc="pointer to new encrypted message or NULL if no encryption could take place";
    1.31 +
    1.32 +		to_fpr
    1.33 +		doc="fingerprint of the recipient key to which the private key should be encrypted";
    1.34 +
    1.35 +		use format enc_format?
    1.36 +		doc="encrypted format";
    1.37 +
    1.38 +		// flags
    1.39 +
    1.40 +		flags {
    1.41 +			flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
    1.42 +			flag force_encryption 0x1;
    1.43 +			flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
    1.44 +			flag force_no_attached_key 0x4;
    1.45 +			flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
    1.46 +			flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
    1.47 +			flag key_reset_only 0x20
    1.48 +		}
    1.49 +
    1.50 +		// exceptions
    1.51 +
    1.52 +		throws key_has_ambig_name
    1.53 +			doc="at least one of the receipient keys has an ambiguous name";
    1.54 +
    1.55 +		throws unencrypted
    1.56 +			doc="""
    1.57 +				on demand or no recipients with usable key, is left unencrypted, 
    1.58 +				and key is attached to it
    1.59 +				"""
    1.60 +	}
    1.61 +}
    1.62 +
    1.63 +
    1.64 +protocol session {
    1.65 +	method encrypt_message_for_self
    1.66 +		doc="""
    1.67 +			encrypt message in memory for user's identity only,
    1.68 +			ignoring recipients and other identities from the message
    1.69 +			"""
    1.70 +	{
    1.71 +		// parms
    1.72 +
    1.73 +		use message target_id
    1.74 +		doc="self identity this message should be encrypted for";
    1.75 +
    1.76 +		use message src
    1.77 +		doc="message to encrypt";
    1.78 +
    1.79 +		provide key? extra
    1.80 +		doc="extra keys for encryption";
    1.81 +
    1.82 +		create message dst
    1.83 +		doc="pointer to new encrypted message or NULL on failure";
    1.84 +
    1.85 +		use format enc_format?
    1.86 +		doc="encrypted format";
    1.87 +
    1.88 +		// flags
    1.89 +
    1.90 +		flags {
    1.91 +			flag default 0x0 doc='"default" means whatever the default behaviour for the function is.';
    1.92 +			flag force_encryption 0x1;
    1.93 +			flag force_unsigned 0x2 doc='This flag is for special use cases and should not be used by normal pEp clients!';
    1.94 +			flag force_no_attached_key 0x4;
    1.95 +			flag inner_message 0x8 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device.';
    1.96 +			flag force_version_1 0x10 doc='This is mainly used by pEp clients to send private keys to their own PGP-only device';
    1.97 +			flag key_reset_only 0x20
    1.98 +		}
    1.99 +
   1.100 +		// exceptions
   1.101 +
   1.102 +		throws key_not_found
   1.103 +			doc="at least one of the receipient keys could not be found";
   1.104 +
   1.105 +		throws key_has_ambig_name
   1.106 +			doc="at least one of the receipient keys has an ambiguous name";
   1.107 +
   1.108 +		throws get_key_failed
   1.109 +			doc="cannot retrieve key"
   1.110 +	}
   1.111 +}
   1.112 +
   1.113 +
   1.114 +protocol session {
   1.115 +	method color_from_rating
   1.116 +		doc="calculate color from rating"
   1.117 +	{
   1.118 +		// parms
   1.119 +	
   1.120 +		provide message rating?
   1.121 +		doc="color representing that rating";
   1.122 +
   1.123 +		// ratings
   1.124 +
   1.125 +		ratings {
   1.126 +			rating_undefined 0;
   1.127 +			rating_cannot_decrypt,
   1.128 +			rating_have_no_key,
   1.129 +			rating_unencrypted,
   1.130 +			rating_unencrypted_for_some doc="don't use this any more",
   1.131 +			rating_unreliable,
   1.132 +			rating_reliable,
   1.133 +			rating_trusted,
   1.134 +			rating_trusted_and_anonymized,
   1.135 +			rating_fully_anonymous,
   1.136 +			rating_mistrust -1;
   1.137 +			rating_b0rken -2;
   1.138 +			rating_under_attack -3
   1.139 +		}
   1.140 +
   1.141 +		// colors
   1.142 +
   1.143 +		colors {
   1.144 +			color_no_color 0;
   1.145 +			color_yellow,
   1.146 +			color_green,
   1.147 +			color_red -1
   1.148 +		}
   1.149 +
   1.150 +		// return value
   1.151 +			doc="color representing that rating"
   1.152 +	}
   1.153 +}
   1.154 +
   1.155 +
   1.156 +protocol session {
   1.157 +	method decrypt_message
   1.158 +		doc="decrypt message in memory"
   1.159 +	{
   1.160 +	// parms
   1.161 +
   1.162 +	supply message src
   1.163 +	doc="""
   1.164 +		message to decrypt. 
   1.165 +		The ownership of src remains with the caller - however, the contents 
   1.166 +		might be modified (strings freed and allocated anew or set to NULL,
   1.167 +		etc) intentionally; when this happens, decrypt_flag_src_modified is set.
   1.168 +		""";
   1.169 +
   1.170 +	create message dst
   1.171 +	doc="pointer to new decrypted message or NULL on failure";
   1.172 +
   1.173 +	supply message keylist
   1.174 +	doc="""
   1.175 +		in: stringlist with additional keyids for reencryption if needed
   1.176 +			(will be freed and replaced with output keylist)
   1.177 +		out: stringlist with keyids used for signing and encryption. first
   1.178 +			first key is signer, additional keys are the ones it was encrypted
   1.179 +			to. Only signer and whichever of the user's keys was used are reliable.
   1.180 +		""";
   1.181 +
   1.182 +	return message rating
   1.183 +	doc="rating for the message";
   1.184 +
   1.185 +	// flags
   1.186 +	
   1.187 +	decrypt_flags {
   1.188 +		decrypt_flag_own_private_key 0x1 
   1.189 +		doc="""
   1.190 +			private key was imported for one of our addresses (NOT trusted
   1.191 +			or set to be used - handshake/trust is required for that)
   1.192 +			"""
   1.193 +		decrypt_flag_consume 0x2 doc=’used by sync';
   1.194 +		decrypt_flag_ignore 0x4 doc=’used by sync';
   1.195 +		decrypt_flag_src_modified 0x8 
   1.196 +		doc="""
   1.197 +			indicates that the src object has been modified. At the moment,
   1.198 +			this is always as a direct result of the behaviour driven
   1.199 +			by the input flags. This flag is the ONLY value that should be
   1.200 +			relied upon to see if such changes have taken place.
   1.201 +			""";
   1.202 +		decrypt_flag_untrusted_server 0x100 
   1.203 +		doc="""
   1.204 +			input flags. Used to signal that decrypt function should engage in behaviour
   1.205 +			specified for when the server storing the source is untrusted.
   1.206 +			"""
   1.207 +	}
   1.208 +
   1.209 +	// exceptions
   1.210 +	
   1.211 +	throws decrypted
   1.212 +		doc="if message decrypted but not verified";
   1.213 +
   1.214 +	throws cannot_reencrypt
   1.215 +		doc="""
   1.216 +			if message was decrypted (and possibly verified) but a reencryption 
   1.217 +			operation is expected by the caller and failed.
   1.218 +			""";
   1.219 +
   1.220 +	throws unencrypted
   1.221 +		doc="""
   1.222 +			if src is unencrypted this function returns unencrypted and sets
   1.223 +			dst to NULL.
   1.224 +			"""
   1.225 +	}
   1.226 +}
   1.227 +
   1.228 +
   1.229 +protocol session {
   1.230 +	method own_message_private_key_details
   1.231 +		doc="details on own key in own message"
   1.232 +	{
   1.233 +	//parms
   1.234 +
   1.235 +	use message msg
   1.236 +	doc="""
   1.237 +		message to decrypt. msg MUST be encrypted so that this function 
   1.238 +		can check own signature.
   1.239 +		""";
   1.240 +
   1.241 +	create @type? ident
   1.242 +	doc="identity containing uid, address and fpr of key"
   1.243 +	}
   1.244 +}
   1.245 +
   1.246 +
   1.247 +protocol session {
   1.248 +	method outgoing_message_rating
   1.249 +		doc="get rating for an outgoing message"
   1.250 +	{
   1.251 +	//parms
   1.252 +
   1.253 +	use message msg
   1.254 +	doc="""
   1.255 +		message to get the rating for. From must point to a valid pEp_identity.
   1.256 +		Dir must be dir_outgoing.
   1.257 +		""";
   1.258 +
   1.259 +	create message rating
   1.260 +	doc="rating for the message"
   1.261 +	}
   1.262 +}
   1.263 +
   1.264 +
   1.265 +protocol session {
   1.266 +	method outgoing_message_rating_preview
   1.267 +		doc="get rating preview"
   1.268 +	{
   1.269 +	//parms
   1.270 +
   1.271 +	use message msg
   1.272 +	doc="""
   1.273 +		message to get the rating for. From must point to a valid pEp_identity.
   1.274 +		Dir must be dir_outgoing.
   1.275 +		""";
   1.276 +
   1.277 +	create message rating
   1.278 +	doc="rating preview for the message"
   1.279 +	}
   1.280 +}
   1.281 +
   1.282 +
   1.283 +protocol session {
   1.284 +	method identity_rating
   1.285 +		doc="get rating for a single identity"
   1.286 +	{
   1.287 +	//parms
   1.288 +
   1.289 +	use @type ident
   1.290 +	doc="identity to get the rating for";
   1.291 +
   1.292 +	create identity rating
   1.293 +	doc="rating for the identity"
   1.294 +	}
   1.295 +}
   1.296 +
   1.297 +
   1.298 +protocol session {
   1.299 +	method get_binary_path
   1.300 +		doc="retrieve path of cryptotech binary if available"
   1.301 +	{
   1.302 +	//parms
   1.303 +
   1.304 +	use @type tech
   1.305 +	doc="cryptotech to get the binary for";
   1.306 +
   1.307 +	use @type path
   1.308 +	doc="""
   1.309 +		path to cryptotech binary or NULL if not available. **path is owned by 
   1.310 +		the library, do not change it!
   1.311 +		"""
   1.312 +	}
   1.313 +}
   1.314 +
   1.315 +
   1.316 +protocol session {
   1.317 +	method get_trustwords
   1.318 +		doc="get full trustwords string for a *pair* of identities"
   1.319 +	{
   1.320 +	//parms
   1.321 +
   1.322 +	provide message id1
   1.323 +		doc="identity of first party in communication - fpr can't be NULL";
   1.324 +
   1.325 +	provide message id2
   1.326 +		doc="identity of second party in communication - fpr can't be NULL";
   1.327 +
   1.328 +	provide message lang
   1.329 +		doc="C string with ISO 639-1 language code";
   1.330 +
   1.331 +	create message words
   1.332 +		doc="""
   1.333 +			pointer to C string with all trustwords UTF-8 encoded, separated 
   1.334 +			by a blank each NULL if language is not supported or trustword 
   1.335 +			wordlist is damaged or unavailable. 
   1.336 +			The word pointer goes to the ownership of the caller. 
   1.337 +			The caller is responsible to free() it (on Windoze use pEp_free())
   1.338 +			""";
   1.339 +
   1.340 +	create @type? wsize
   1.341 +		doc="length of full trustwords string";
   1.342 +
   1.343 +	provide @type full
   1.344 +		doc="""
   1.345 +			if true, generate ALL trustwords for these identities.
   1.346 +			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   1.347 +			subset in next version)
   1.348 +			"""
   1.349 +
   1.350 +	// exceptions
   1.351 +
   1.352 +	throws out_of_memory
   1.353 +		doc="out of memory";
   1.354 +
   1.355 +	throws trustword_not_found
   1.356 +		doc="at least one trustword not found"
   1.357 +	}
   1.358 +}
   1.359 +
   1.360 +
   1.361 +protocol session
   1.362 +	method get_message_trustwords
   1.363 +		doc="get full trustwords string for message sender and reciever identities"
   1.364 +	{
   1.365 +	//parms
   1.366 +
   1.367 +	provide @type msg
   1.368 +		doc="message to get sender identity from";
   1.369 +
   1.370 +	provide message keylist
   1.371 +		doc="NULL if message to be decrypted, keylist returned by decrypt_message() otherwise.";
   1.372 +
   1.373 +	provide message received_by
   1.374 +		doc="identity for account receiving message can't be NULL";
   1.375 +
   1.376 +	provide @type? lang
   1.377 +		doc="C string with ISO 639-1 language code";
   1.378 +
   1.379 +	create message words
   1.380 +		doc="""
   1.381 +			pointer to C string with all trustwords UTF-8 encoded, separated by a blank each.
   1.382 +			NULL if language is not supported or trustword  wordlist is damaged or unavailable.
   1.383 +			The word pointer goes to the ownership of the caller. 
   1.384 +			The caller is responsible to free() it (on Windoze use pEp_free())
   1.385 +			""";
   1.386 +
   1.387 +	provide @type full
   1.388 +		doc="""
   1.389 +			if true, generate ALL trustwords for these identities.
   1.390 +			else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   1.391 +			subset in next version)
   1.392 +			"""
   1.393 +
   1.394 +	// exceptions
   1.395 +
   1.396 +	throws out_of_memory
   1.397 +		doc="out of memory";
   1.398 +
   1.399 +	throws trustword_not_found
   1.400 +		doc="at least one trustword not found"
   1.401 +	}
   1.402 +}
   1.403 +
   1.404 +
   1.405 +protocol session
   1.406 +	method re_evaluate_message_rating
   1.407 +		doc="re-evaluate already decrypted message rating"
   1.408 +	{
   1.409 +	//parms
   1.410 +
   1.411 +	use @type msg
   1.412 +		doc="message to get the rating for. msg->from must point to a valid pEp_identity";
   1.413 +
   1.414 +	use message x_keylist
   1.415 +		doc="decrypted message recipients keys fpr";
   1.416 +
   1.417 +	provide message x_enc_status
   1.418 +		doc="original rating for the decrypted message";
   1.419 +
   1.420 +	create message rating
   1.421 +		doc="rating for the message"
   1.422 +
   1.423 +	// exceptions
   1.424 +
   1.425 +	throws illegal_value
   1.426 +		doc="""
   1.427 +			if decrypted message doesn't contain X-EncStatus optional field and 
   1.428 +			x_enc_status is pEp_rating_udefined or if decrypted message doesn't 
   1.429 +			contain X-Keylist optional field and x_keylist is NULL.
   1.430 +			""";
   1.431 +
   1.432 +	throws out_of_memory
   1.433 +		doc="if not enough memory could be allocated"
   1.434 +	}
   1.435 +}
   1.436 +
   1.437 +
   1.438 +protocol session
   1.439 +	method get_key_rating_for_user
   1.440 +		doc="get the rating of a certain key for a certain user"
   1.441 +	{
   1.442 +	//parms
   1.443 +
   1.444 +	provide @type? user_id
   1.445 +		doc="string with user ID";
   1.446 +
   1.447 +	provide @type fpr
   1.448 +		doc="string with fingerprint";
   1.449 +
   1.450 +	create @type rating
   1.451 +		doc="rating of key for this user"
   1.452 +		
   1.453 +	// exceptions
   1.454 +
   1.455 +	throws record_not_found
   1.456 +		doc="if no trust record for user_id and fpr can be found"
   1.457 +	}
   1.458 +}	
   1.459 +
   1.460 +
   1.461 +
   1.462 +
   1.463 +
   1.464 + 
   1.465 +			
   1.466 +
   1.467 +
   1.468 +
   1.469 +
   1.470 +
   1.471 +
   1.472 +
   1.473 +
   1.474 +
   1.475 +
   1.476 +
   1.477 +	
   1.478 +
   1.479 +
   1.480 +
   1.481 +
   1.482 +
   1.483 +
   1.484 +
   1.485 +
   1.486 +
   1.487 +
   1.488 +
   1.489 +
   1.490 +
   1.491 +
   1.492 +