neu generate_api
authornk
Wed, 29 May 2019 17:04:04 +0200
branchgenerate_api
changeset 3770257a31e9b412
parent 3769 8f5847c0cd13
child 3771 1bfe9205fc8a
neu
api/basic_api.yml2
api/keymanagement_api.yml2
     1.1 --- a/api/basic_api.yml2	Fri May 17 17:30:57 2019 +0200
     1.2 +++ b/api/basic_api.yml2	Wed May 29 17:04:04 2019 +0200
     1.3 @@ -7,12 +7,12 @@
     1.4  // written by Nana Karlstetter and Volker Birk
     1.5  
     1.6  
     1.7 -type ISO639_1 is string size=2 > a-z
     1.8 +type ISO639_1 is string size=2 > a-z;
     1.9  
    1.10 -type hex is string > a-f0-9
    1.11 +type hexcode is string > a-f0-9;
    1.12  
    1.13 -type hash doc="32bit Key ID to SHA512 in hex"
    1.14 -    is hex min=16, max=128;
    1.15 +type hash doc="32bit Key ID to SHA512 in hexcode"
    1.16 +    is hexcode min=16, max=128;
    1.17  
    1.18  type hash_list doc="sequence of fingerprints of keys"
    1.19      is list< hash >;
    1.20 @@ -24,11 +24,24 @@
    1.21  
    1.22  type identity_list is list< identity >;
    1.23  
    1.24 -type string_list is list< string > ; 
    1.25 +type string_list is list< string >; 
    1.26  
    1.27  type string_pair is pair< string, string >;
    1.28  
    1.29  
    1.30 +enum cipher_suite {
    1.31 +    item cipher_suite_default 0;
    1.32 +    item cipher_suite_cv25519 1;
    1.33 +    item cipher_suite_p256 2;
    1.34 +    item cipher_suite_p384 3;
    1.35 +    item cipher_suite_p521 4;
    1.36 +    item cipher_suite_rsa2k 5;
    1.37 +    item cipher_suite_rsa3k 6;
    1.38 +    item cipher_suite_rsa4k 7;
    1.39 +    item cipher_suite_rsa8k 8;
    1.40 +}
    1.41 +
    1.42 +
    1.43  enum comm_type {
    1.44      hex unknown 0;
    1.45  
    1.46 @@ -91,7 +104,7 @@
    1.47      doc > range 0xc0 to 0xff: confirmed encryption and anonymization
    1.48  
    1.49      hex confirmed_enc_anon 0xc0            doc="generic";
    1.50 -    hex pEp 0xff
    1.51 +    hex pEp 0xff;
    1.52  
    1.53  } // enum comm_type
    1.54  
    1.55 @@ -103,32 +116,293 @@
    1.56      field string user_id doc="ID for person or entity in M2M case";
    1.57      field string username doc="descriptive string";
    1.58      field ISO639_1 lang doc="two-digit language code or null bytes";
    1.59 +} // struct Identity
    1.60  
    1.61 -    flags {
    1.62 -        flag not_for_sync 0x0001
    1.63 -            doc="don't use this identity for Sync";
    1.64  
    1.65 -        flag list 0x0002
    1.66 -            doc="identity of list of persons";
    1.67 +flags {
    1.68 +    flag not_for_sync 0x0001
    1.69 +        doc="don't use this identity for Sync";
    1.70  
    1.71 -        doc | the second octet flags are calculated
    1.72 +    flag list 0x0002
    1.73 +        doc="identity of list of persons";
    1.74  
    1.75 -        flag devicegroup 0x0100
    1.76 -            doc="identity of a device group member"
    1.77 +    doc | the second octet flags are calculated
    1.78 +
    1.79 +    flag devicegroup 0x0100
    1.80 +        doc="identity of a device group member";
    1.81 +}
    1.82 +
    1.83 +
    1.84 +protocol session {
    1.85 +    callback messageToSend
    1.86 +        doc="a message needs to be delivered by application"
    1.87 +    {
    1.88 +        // parms
    1.89 +
    1.90 +        provide struct_message msg doc="message struct with message to send";
    1.91 +
    1.92 +        // exceptions
    1.93 +
    1.94 +        throws any doc="error status";
    1.95      }
    1.96  
    1.97 -} // struct Identity
    1.98  
    1.99 +    method config_passive_mode 
   1.100 +        doc="enable passive mode"
   1.101 +    {
   1.102 +        // parms
   1.103  
   1.104 -callback messageToSend
   1.105 -    doc="a message needs to be delivered by application"
   1.106 -{
   1.107 -    // parms
   1.108 +       use bool enable doc="flag if enabled or disabled";
   1.109 +    }
   1.110  
   1.111 -    provide struct_message msg doc="message struct with message to send"
   1.112  
   1.113 -    // exceptions
   1.114 +    method config_unencrypted_subject
   1.115 +        doc="disable subject encryption"
   1.116 +    {
   1.117 +        // parms
   1.118  
   1.119 -    throws any doc="error status"
   1.120 +        use bool enable doc="flag if enabled or disabled";
   1.121 +    }
   1.122 +
   1.123 +
   1.124 +    method config_use_only_own_private_keys
   1.125 +        doc="enable passive mode"
   1.126 +    {
   1.127 +        // parms
   1.128 +
   1.129 +        use bool enable doc="flag if enabled or disabled";
   1.130 +    }
   1.131 +
   1.132 +
   1.133 +    method config_service_log
   1.134 +        doc="log more for service purposes"
   1.135 +    {
   1.136 +        // parms
   1.137 +
   1.138 +        use bool enable doc="flag if enabled or disabled";
   1.139 +    }
   1.140 +
   1.141 +
   1.142 +    method config_cipher_suite
   1.143 +        doc="cipher suite being used when encrypting"
   1.144 +    {
   1.145 +        // parms
   1.146 +
   1.147 +        use suite cipher_suite doc="cipher suite to use";
   1.148 +
   1.149 +        // exceptions
   1.150 +
   1.151 +        throws cannot_config 
   1.152 +            doc="""
   1.153 +                configuration failed; falling back to default. the default
   1.154 +                ciphersuite for a crypt tech implementation is implementation 
   1.155 +                defined.
   1.156 +                """;
   1.157 +    }
   1.158 +
   1.159 +
   1.160 +    method log_event
   1.161 +        doc="""
   1.162 +            log a user defined event defined by UTF-8 encoded strings into 
   1.163 +            management log.
   1.164 +            """
   1.165 +    {
   1.166 +        // parms
   1.167 +
   1.168 +        use string title doc="string with event name";
   1.169 +
   1.170 +        use string entity doc="string with name of entity which is logging";
   1.171 +
   1.172 +        use string description doc="string with long description for event or NULL if omitted";
   1.173 +
   1.174 +        use string comment doc="string with user defined comment or NULL if omitted";
   1.175 +    }
   1.176 +
   1.177 +
   1.178 +    method get_default own_userid
   1.179 +        doc="get the user_id of the own user"
   1.180 +    {
   1.181 +        // parms
   1.182 +
   1.183 +        create string userid 
   1.184 +        doc="""
   1.185 +            own user id (if it exists). userid will be NULL if not found; otherwise, 
   1.186 +            returned string belongs to the caller.
   1.187 +            """
   1.188 +
   1.189 +        // exceptions
   1.190 +
   1.191 +        throws cannot_find_identity doc="no own_user found in the DB";
   1.192 +
   1.193 +        throws unknown_error 
   1.194 +        doc="""
   1.195 +            results were returned, but no ID found (no reason this 
   1.196 +            should ever occur).
   1.197 +            """;
   1.198 +    }
   1.199 +
   1.200 +
   1.201 +    method mark_as_compromised
   1.202 +        doc="mark key in trust db as compromised"
   1.203 +    {
   1.204 +        // parms
   1.205 +
   1.206 +        use hash fpr doc="fingerprint of key to mark"
   1.207 +    }
   1.208 +
   1.209 +
   1.210 +    method mark_as_compromized
   1.211 +        doc="deprecated to fix misspelling. Please move to mark_as_compromised"
   1.212 +
   1.213 +
   1.214 +    method import_key
   1.215 +        doc="import key from data"
   1.216 +    {
   1.217 +        // parms
   1.218 +
   1.219 +        use string key_data doc="key data, i.e. ASCII armored OpenPGP key";
   1.220 +
   1.221 +        use size_t size doc="amount of data to handle";
   1.222 +
   1.223 +        create identity_list private_keys 
   1.224 +        doc="""
   1.225 +            list of private keys that have been imported. private_keys can 
   1.226 +            be left NULL, it is then ignored.
   1.227 +            """;
   1.228 +    }
   1.229 +
   1.230 +
   1.231 +    method export_key
   1.232 +        doc="export ascii armored key"
   1.233 +    {
   1.234 +        // parms
   1.235 +
   1.236 +        use hash fpr doc="key id or fingerprint of key";
   1.237 +
   1.238 +        create string key_data 
   1.239 +        doc="""
   1.240 +            ASCII armored OpenPGP key. The key_data goes to the ownership of the 
   1.241 +            caller. The caller is responsible to free() it (on Windoze use pEp_free())
   1.242 +            """;
   1.243 +
   1.244 +        return size_t size doc="amount of data to handle";
   1.245 +
   1.246 +        // exceptions
   1.247 +
   1.248 +        throws out_of_memory doc="out of memory";
   1.249 +
   1.250 +        throws key_not_found doc="key not found";
   1.251 +    }
   1.252 +
   1.253 +
   1.254 +    method export_secret_key
   1.255 +        doc="export secret key ascii armored"
   1.256 +    {
   1.257 +        // parms
   1.258 +
   1.259 +        use hash fpr doc="fingerprint of key, at least 16 hex digits"
   1.260 +
   1.261 +        create string key_data 
   1.262 +        doc="""
   1.263 +            ASCII armored OpenPGP secret key. The key_data goes to the ownership of the 
   1.264 +            caller. The caller is responsible to free() it (on Windoze use pEp_free()).
   1.265 +            beware of leaking secret key data - overwrite it in memory after use!
   1.266 +            """;
   1.267 +
   1.268 +        return size_t size doc="amount of data to handle";
   1.269 +
   1.270 +        // exceptions
   1.271 +
   1.272 +        throws out_of_memory doc="out of memory";
   1.273 +
   1.274 +        throws key_not_found doc="key not found";
   1.275 +
   1.276 +        throws cannot_export_key doc="cannot export secret key (i.e. it's on an HKS)";
   1.277 +    }
   1.278 +
   1.279 +
   1.280 +    method export_secrect_key 
   1.281 +        doc="deprecated misspelled function. Please replace with export_secret_key"
   1.282 +
   1.283 +
   1.284 +    method get_crashdump_log
   1.285 +        doc="get the last log messages out"
   1.286 +    {
   1.287 +        // parms
   1.288 +
   1.289 +        use int maxlines doc="maximum number of lines (0 for default)";
   1.290 +
   1.291 +        create string logdata 
   1.292 +        doc="""
   1.293 +            logdata as string in double quoted CSV format
   1.294 +            column1 is title
   1.295 +            column2 is entity
   1.296 +            column3 is description
   1.297 +            column4 is comment
   1.298 +            """;
   1.299 +    }
   1.300 +
   1.301 +
   1.302 +    method get_languagelist
   1.303 +        doc="get the list of languages"
   1.304 +    {
   1.305 +        //parms
   1.306 +
   1.307 +        create string language 
   1.308 +        doc="""
   1.309 +            languages as string in double quoted CSV format
   1.310 +            column 1 is the ISO 639-1 language code
   1.311 +            column 2 is the name of the language
   1.312 +            """;
   1.313 +    }
   1.314 +
   1.315 +
   1.316 +    method get_phrase
   1.317 +        doc="get phrase in a dedicated language through i18n"
   1.318 +    {
   1.319 +        // parms
   1.320 +
   1.321 +        use string lang doc="string with ISO 639-1 language code";
   1.322 +
   1.323 +        use int phrase_id doc="id of phrase in i18n";
   1.324 +
   1.325 +        create string phrase doc="phrase as UTF-8 string";
   1.326 +    }
   1.327 +
   1.328 +
   1.329 +    method get_engine_version
   1.330 +        doc="""
   1.331 +            returns the current version of pEpEngine (this is different
   1.332 +            from the pEp protocol version!).
   1.333 +            """
   1.334 +    {
   1.335 +        // parms doc="none. return_value: const char* to the engine version string constant" 
   1.336 +
   1.337 +   method is_pEp_user
   1.338 +        doc="""
   1.339 +            returns true if the USER corresponding to this identity has been listed 
   1.340 +            in the *person* table as a pEp user.
   1.341 +            This *does not check comm_type*.
   1.342 +            """
   1.343 +    {
   1.344 +        // parms
   1.345 +
   1.346 +        use identity ident
   1.347 +        doc="""
   1.348 +            identity containing the user_id to check (this is the only part of 
   1.349 +            the struct we require to be set).
   1.350 +            """;
   1.351 +
   1.352 +        return bool is_pEp
   1.353 +        doc="""
   1.354 +            boolean pointer - will return true or false by reference with respect 
   1.355 +            to whether or not user is a known pEp user
   1.356 +            """;
   1.357 +
   1.358 +        // exceptions
   1.359 +
   1.360 +        throws illegal_value doc="if no user_id in input";
   1.361 +
   1.362 +        throws cannot_find_person doc="if user_id doesn't exist";
   1.363 +    }
   1.364  }
   1.365 -
     2.1 --- a/api/keymanagement_api.yml2	Fri May 17 17:30:57 2019 +0200
     2.2 +++ b/api/keymanagement_api.yml2	Wed May 29 17:04:04 2019 +0200
     2.3 @@ -41,22 +41,22 @@
     2.4  		END FIXME
     2.5  		"""
     2.6  
     2.7 -		// exceptions
     2.8 +	// exceptions
     2.9  
    2.10 -		throws illegal_value
    2.11 -			doc="""
    2.12 -				if called with illegal inputs, including an identity
    2.13 -				with .me set or with an own user_id specified in the
    2.14 -				*input* (see caveats)
    2.15 -				""";
    2.16 +	throws illegal_value
    2.17 +		doc="""
    2.18 +			if called with illegal inputs, including an identity
    2.19 +			with .me set or with an own user_id specified in the
    2.20 +			*input* (see caveats)
    2.21 +			""";
    2.22  
    2.23 -		throws key_unsuitable
    2.24 -			doc="""
    2.25 -				if a default key was found for this identity, no
    2.26 -				other acceptable keys were found; if this is returned,
    2.27 -				the reason for rejecting the first default key found	
    2.28 -				may be found in the comm_type
    2.29 -				"""
    2.30 +	throws key_unsuitable
    2.31 +		doc="""
    2.32 +			if a default key was found for this identity, no
    2.33 +			other acceptable keys were found; if this is returned,
    2.34 +			the reason for rejecting the first default key found	
    2.35 +			may be found in the comm_type
    2.36 +			"""
    2.37  	}
    2.38  
    2.39  
    2.40 @@ -198,16 +198,20 @@
    2.41      }
    2.42  
    2.43  
    2.44 -method own_keys_retrieve 
    2.45 -        doc="retrieve all flagged keypair fingerprints" 
    2.46 +    method own_keys_retrieve 
    2.47 +        doc="retrieve all flagged keypair fingerprints/private keypair fingerprints" 
    2.48      {
    2.49      // parms
    2.50  
    2.51 -    create hashlist keylist doc="list of fingerprints"
    2.52 +    create hashlist keylist 
    2.53 +        doc="""
    2.54 +            list of fingerprints. This function does not return keys without 
    2.55 +            a private key part.
    2.56 +            """
    2.57      }
    2.58  
    2.59  
    2.60 -method set_own_key 
    2.61 +    method set_own_key 
    2.62          doc="mark a key as own key"
    2.63      {
    2.64      // parms