doc/pgp-api.texi

   1
   2
   3
   4
   5 @subheading gnutls_certificate_set_openpgp_key_file2
   6 @anchor{gnutls_certificate_set_openpgp_key_file2}
   7 @deftypefun {int} {gnutls_certificate_set_openpgp_key_file2} (gnutls_certificate_credentials_t                                           @var{res}, const char * @var{certfile}, const char * @var{keyfile}, const char * @var{subkey_id}, gnutls_openpgp_crt_fmt_t @var{format})
   8 @var{res}: the destination context to save the data.
   9
  10 @var{certfile}: the file that contains the public key.
  11
  12 @var{keyfile}: the file that contains the secret key.
  13
  14 @var{subkey_id}: a hex encoded subkey id
  15
  16 @var{format}: the format of the keys
  17
  18 This funtion is used to load OpenPGP keys into the GnuTLS credential
  19 structure. The file should contain at least one valid non encrypted subkey.
  20
  21 The special keyword "auto" is also accepted as @code{subkey_id}.  In that
  22 case the @code{gnutls_openpgp_crt_get_auth_subkey()} will be used to
  23 retrieve the subkey.
  24
  25 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
  26 negative error value.
  27
  28 @strong{Since:} 2.4.0
  29 @end deftypefun
  30
  31 @subheading gnutls_certificate_set_openpgp_key_file
  32 @anchor{gnutls_certificate_set_openpgp_key_file}
  33 @deftypefun {int} {gnutls_certificate_set_openpgp_key_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{certfile}, const char * @var{keyfile}, gnutls_openpgp_crt_fmt_t @var{format})
  34 @var{res}: the destination context to save the data.
  35
  36 @var{certfile}: the file that contains the public key.
  37
  38 @var{keyfile}: the file that contains the secret key.
  39
  40 @var{format}: the format of the keys
  41
  42 This funtion is used to load OpenPGP keys into the GnuTLS
  43 credentials structure. The file should contain at least one valid non encrypted subkey.
  44
  45 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
  46 negative error value.
  47 @end deftypefun
  48
  49 @subheading gnutls_certificate_set_openpgp_key_mem2
  50 @anchor{gnutls_certificate_set_openpgp_key_mem2}
  51 @deftypefun {int} {gnutls_certificate_set_openpgp_key_mem2} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{cert}, const gnutls_datum_t * @var{key}, const char * @var{subkey_id}, gnutls_openpgp_crt_fmt_t @var{format})
  52 @var{res}: the destination context to save the data.
  53
  54 @var{cert}: the datum that contains the public key.
  55
  56 @var{key}: the datum that contains the secret key.
  57
  58 @var{subkey_id}: a hex encoded subkey id
  59
  60 @var{format}: the format of the keys
  61
  62 This funtion is used to load OpenPGP keys into the GnuTLS
  63 credentials structure. The datum should contain at least one valid non encrypted subkey.
  64
  65 The special keyword "auto" is also accepted as @code{subkey_id}.  In that
  66 case the @code{gnutls_openpgp_crt_get_auth_subkey()} will be used to
  67 retrieve the subkey.
  68
  69 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
  70 negative error value.
  71
  72 @strong{Since:} 2.4.0
  73 @end deftypefun
  74
  75 @subheading gnutls_certificate_set_openpgp_key_mem
  76 @anchor{gnutls_certificate_set_openpgp_key_mem}
  77 @deftypefun {int} {gnutls_certificate_set_openpgp_key_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{cert}, const gnutls_datum_t * @var{key}, gnutls_openpgp_crt_fmt_t @var{format})
  78 @var{res}: the destination context to save the data.
  79
  80 @var{cert}: the datum that contains the public key.
  81
  82 @var{key}: the datum that contains the secret key.
  83
  84 @var{format}: the format of the keys
  85
  86 This funtion is used to load OpenPGP keys into the GnuTLS credential
  87 structure. The datum should contain at least one valid non encrypted subkey.
  88
  89 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
  90 negative error value.
  91 @end deftypefun
  92
  93 @subheading gnutls_certificate_set_openpgp_keyring_file
  94 @anchor{gnutls_certificate_set_openpgp_keyring_file}
  95 @deftypefun {int} {gnutls_certificate_set_openpgp_keyring_file} (gnutls_certificate_credentials_t                                              @var{c}, const char * @var{file}, gnutls_openpgp_crt_fmt_t @var{format})
  96 @var{c}: A certificate credentials structure
  97
  98 @var{file}: filename of the keyring.
  99
 100 @var{format}: format of keyring.
 101
 102 The function is used to set keyrings that will be used internally
 103 by various OpenPGP functions. For example to find a key when it
 104 is needed for an operations. The keyring will also be used at the
 105 verification functions.
 106
 107 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
 108 negative error value.
 109 @end deftypefun
 110
 111 @subheading gnutls_certificate_set_openpgp_keyring_mem
 112 @anchor{gnutls_certificate_set_openpgp_keyring_mem}
 113 @deftypefun {int} {gnutls_certificate_set_openpgp_keyring_mem} (gnutls_certificate_credentials_t                                             @var{c}, const opaque * @var{data}, size_t @var{dlen}, gnutls_openpgp_crt_fmt_t @var{format})
 114 @var{c}: A certificate credentials structure
 115
 116 @var{data}: buffer with keyring data.
 117
 118 @var{dlen}: length of data buffer.
 119
 120 @var{format}: the format of the keyring
 121
 122 The function is used to set keyrings that will be used internally
 123 by various OpenPGP functions. For example to find a key when it
 124 is needed for an operations. The keyring will also be used at the
 125 verification functions.
 126
 127 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
 128 negative error value.
 129 @end deftypefun
 130
 131 @subheading gnutls_certificate_set_openpgp_key
 132 @anchor{gnutls_certificate_set_openpgp_key}
 133 @deftypefun {int} {gnutls_certificate_set_openpgp_key} (gnutls_certificate_credentials_t @var{res}, gnutls_openpgp_crt_t @var{crt}, gnutls_openpgp_privkey_t @var{pkey})
 134 @var{res}: is a @code{gnutls_certificate_credentials_t} structure.
 135
 136 @var{pkey}: is an openpgp private key
 137
 138 This function sets a certificate/private key pair in the
 139 gnutls_certificate_credentials_t structure.  This function may be
 140 called more than once (in case multiple keys/certificates exist
 141 for the server).
 142
 143 Note that this function requires that the preferred key ids have
 144 been set and be used. See @code{gnutls_openpgp_crt_set_preferred_key_id()}.
 145 Otherwise the master key will be used.
 146
 147 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
 148 otherwise an error code is returned.
 149 @end deftypefun
 150
 151 @subheading gnutls_openpgp_crt_check_hostname
 152 @anchor{gnutls_openpgp_crt_check_hostname}
 153 @deftypefun {int} {gnutls_openpgp_crt_check_hostname} (gnutls_openpgp_crt_t @var{key}, const char * @var{hostname})
 154 @var{key}: should contain a @code{gnutls_openpgp_crt_t} structure
 155
 156 @var{hostname}: A null terminated string that contains a DNS name
 157
 158 This function will check if the given key's owner matches the
 159 given hostname. This is a basic implementation of the matching
 160 described in RFC2818 (HTTPS), which takes into account wildcards.
 161
 162 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 163 @end deftypefun
 164
 165 @subheading gnutls_openpgp_crt_deinit
 166 @anchor{gnutls_openpgp_crt_deinit}
 167 @deftypefun {void} {gnutls_openpgp_crt_deinit} (gnutls_openpgp_crt_t @var{key})
 168 @var{key}: The structure to be initialized
 169
 170 This function will deinitialize a key structure.
 171 @end deftypefun
 172
 173 @subheading gnutls_openpgp_crt_export
 174 @anchor{gnutls_openpgp_crt_export}
 175 @deftypefun {int} {gnutls_openpgp_crt_export} (gnutls_openpgp_crt_t @var{key}, gnutls_openpgp_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size})
 176 @var{key}: Holds the key.
 177
 178 @var{format}: One of gnutls_openpgp_crt_fmt_t elements.
 179
 180 @var{output_data}: will contain the key base64 encoded or raw
 181
 182 @var{output_data_size}: holds the size of output_data (and will
 183 be replaced by the actual size of parameters)
 184
 185 This function will convert the given key to RAW or Base64 format.
 186 If the buffer provided is not long enough to hold the output, then
 187 @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned.
 188
 189 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 190 @end deftypefun
 191
 192 @subheading gnutls_openpgp_crt_get_auth_subkey
 193 @anchor{gnutls_openpgp_crt_get_auth_subkey}
 194 @deftypefun {int} {gnutls_openpgp_crt_get_auth_subkey} (gnutls_openpgp_crt_t @var{crt}, gnutls_openpgp_keyid_t @var{keyid}, unsigned int @var{flag})
 195 @var{crt}: the structure that contains the OpenPGP public key.
 196
 197 @var{keyid}: the struct to save the keyid.
 198
 199 @var{flag}: Non zero indicates that a valid subkey is always returned.
 200
 201 Returns the 64-bit keyID of the first valid OpenPGP subkey marked
 202 for authentication.  If flag is non zero and no authentication
 203 subkey exists, then a valid subkey will be returned even if it is
 204 not marked for authentication.
 205 Returns the 64-bit keyID of the first valid OpenPGP subkey marked
 206 for authentication.  If flag is non zero and no authentication
 207 subkey exists, then a valid subkey will be returned even if it is
 208 not marked for authentication.
 209
 210 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 211 @end deftypefun
 212
 213 @subheading gnutls_openpgp_crt_get_creation_time
 214 @anchor{gnutls_openpgp_crt_get_creation_time}
 215 @deftypefun {time_t} {gnutls_openpgp_crt_get_creation_time} (gnutls_openpgp_crt_t @var{key})
 216 @var{key}: the structure that contains the OpenPGP public key.
 217
 218 Get key creation time.
 219
 220 @strong{Returns:} the timestamp when the OpenPGP key was created.
 221 @end deftypefun
 222
 223 @subheading gnutls_openpgp_crt_get_expiration_time
 224 @anchor{gnutls_openpgp_crt_get_expiration_time}
 225 @deftypefun {time_t} {gnutls_openpgp_crt_get_expiration_time} (gnutls_openpgp_crt_t @var{key})
 226 @var{key}: the structure that contains the OpenPGP public key.
 227
 228 Get key expiration time.  A value of '0' means that the key doesn't
 229 expire at all.
 230
 231 @strong{Returns:} the time when the OpenPGP key expires.
 232 @end deftypefun
 233
 234 @subheading gnutls_openpgp_crt_get_fingerprint
 235 @anchor{gnutls_openpgp_crt_get_fingerprint}
 236 @deftypefun {int} {gnutls_openpgp_crt_get_fingerprint} (gnutls_openpgp_crt_t @var{key}, void * @var{fpr}, size_t * @var{fprlen})
 237 @var{key}: the raw data that contains the OpenPGP public key.
 238
 239 @var{fpr}: the buffer to save the fingerprint, must hold at least 20 bytes.
 240
 241 @var{fprlen}: the integer to save the length of the fingerprint.
 242
 243 Get key fingerprint.  Depending on the algorithm, the fingerprint
 244 can be 16 or 20 bytes.
 245
 246 @strong{Returns:} On success, 0 is returned.  Otherwise, an error code.
 247 @end deftypefun
 248
 249 @subheading gnutls_openpgp_crt_get_key_id
 250 @anchor{gnutls_openpgp_crt_get_key_id}
 251 @deftypefun {int} {gnutls_openpgp_crt_get_key_id} (gnutls_openpgp_crt_t @var{key}, gnutls_openpgp_keyid_t @var{keyid})
 252 @var{key}: the structure that contains the OpenPGP public key.
 253
 254 @var{keyid}: the buffer to save the keyid.
 255
 256 Get key id string.
 257
 258 @strong{Returns:} the 64-bit keyID of the OpenPGP key.
 259
 260 @strong{Since:} 2.4.0
 261 @end deftypefun
 262
 263 @subheading gnutls_openpgp_crt_get_key_usage
 264 @anchor{gnutls_openpgp_crt_get_key_usage}
 265 @deftypefun {int} {gnutls_openpgp_crt_get_key_usage} (gnutls_openpgp_crt_t @var{key}, unsigned int * @var{key_usage})
 266 @var{key}: should contain a gnutls_openpgp_crt_t structure
 267
 268 @var{key_usage}: where the key usage bits will be stored
 269
 270 This function will return certificate's key usage, by checking the
 271 key algorithm. The key usage value will ORed values of the:
 272 @code{GNUTLS_KEY_DIGITAL_SIGNATURE}, @code{GNUTLS_KEY_KEY_ENCIPHERMENT}.
 273
 274 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 275 @end deftypefun
 276
 277 @subheading gnutls_openpgp_crt_get_name
 278 @anchor{gnutls_openpgp_crt_get_name}
 279 @deftypefun {int} {gnutls_openpgp_crt_get_name} (gnutls_openpgp_crt_t @var{key}, int @var{idx}, char * @var{buf}, size_t * @var{sizeof_buf})
 280 @var{key}: the structure that contains the OpenPGP public key.
 281
 282 @var{idx}: the index of the ID to extract
 283
 284 @var{buf}: a pointer to a structure to hold the name, may be @code{NULL}
 285 to only get the @code{sizeof_buf}.
 286
 287 @var{sizeof_buf}: holds the maximum size of @code{buf}, on return hold the
 288 actual/required size of @code{buf}.
 289
 290 Extracts the userID from the parsed OpenPGP key.
 291
 292 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, and if the index of the ID
 293 does not exist @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}, or an
 294 error code.
 295 @end deftypefun
 296
 297 @subheading gnutls_openpgp_crt_get_pk_algorithm
 298 @anchor{gnutls_openpgp_crt_get_pk_algorithm}
 299 @deftypefun {gnutls_pk_algorithm_t} {gnutls_openpgp_crt_get_pk_algorithm} (gnutls_openpgp_crt_t @var{key}, unsigned int * @var{bits})
 300 @var{key}: is an OpenPGP key
 301
 302 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
 303
 304 This function will return the public key algorithm of an OpenPGP
 305 certificate.
 306
 307 If bits is non null, it should have enough size to hold the parameters
 308 size in bits. For RSA the bits returned is the modulus.
 309 For DSA the bits returned are of the public exponent.
 310
 311 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
 312 success, or GNUTLS_PK_UNKNOWN on error.
 313 @end deftypefun
 314
 315 @subheading gnutls_openpgp_crt_get_pk_dsa_raw
 316 @anchor{gnutls_openpgp_crt_get_pk_dsa_raw}
 317 @deftypefun {int} {gnutls_openpgp_crt_get_pk_dsa_raw} (gnutls_openpgp_crt_t @var{crt}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y})
 318 @var{crt}: Holds the certificate
 319
 320 @var{p}: will hold the p
 321
 322 @var{q}: will hold the q
 323
 324 @var{g}: will hold the g
 325
 326 @var{y}: will hold the y
 327
 328 This function will export the DSA public key's parameters found in
 329 the given certificate.  The new parameters will be allocated using
 330 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 331
 332 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 333
 334 @strong{Since:} 2.4.0
 335 @end deftypefun
 336
 337 @subheading gnutls_openpgp_crt_get_pk_rsa_raw
 338 @anchor{gnutls_openpgp_crt_get_pk_rsa_raw}
 339 @deftypefun {int} {gnutls_openpgp_crt_get_pk_rsa_raw} (gnutls_openpgp_crt_t @var{crt}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e})
 340 @var{crt}: Holds the certificate
 341
 342 @var{m}: will hold the modulus
 343
 344 @var{e}: will hold the public exponent
 345
 346 This function will export the RSA public key's parameters found in
 347 the given structure.  The new parameters will be allocated using
 348 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 349
 350 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 351
 352 @strong{Since:} 2.4.0
 353 @end deftypefun
 354
 355 @subheading gnutls_openpgp_crt_get_preferred_key_id
 356 @anchor{gnutls_openpgp_crt_get_preferred_key_id}
 357 @deftypefun {int} {gnutls_openpgp_crt_get_preferred_key_id} (gnutls_openpgp_crt_t @var{key}, gnutls_openpgp_keyid_t @var{keyid})
 358 @var{key}: the structure that contains the OpenPGP public key.
 359
 360 @var{keyid}: the struct to save the keyid.
 361
 362 Get preferred key id.  If it hasn't been set it returns
 363 @code{GNUTLS_E_INVALID_REQUEST}.
 364
 365 @strong{Returns:} the 64-bit preferred keyID of the OpenPGP key.
 366 @end deftypefun
 367
 368 @subheading gnutls_openpgp_crt_get_revoked_status
 369 @anchor{gnutls_openpgp_crt_get_revoked_status}
 370 @deftypefun {int} {gnutls_openpgp_crt_get_revoked_status} (gnutls_openpgp_crt_t @var{key})
 371 @var{key}: the structure that contains the OpenPGP public key.
 372
 373 Get revocation status of key.
 374
 375 @strong{Returns:} true (1) if the key has been revoked, or false (0) if it
 376 has not.
 377
 378 @strong{Since:} 2.4.0
 379 @end deftypefun
 380
 381 @subheading gnutls_openpgp_crt_get_subkey_count
 382 @anchor{gnutls_openpgp_crt_get_subkey_count}
 383 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_count} (gnutls_openpgp_crt_t @var{key})
 384 @var{key}: is an OpenPGP key
 385
 386 This function will return the number of subkeys present in the
 387 given OpenPGP certificate.
 388
 389 @strong{Returns:} the number of subkeys, or a negative value on error.
 390
 391 @strong{Since:} 2.4.0
 392 @end deftypefun
 393
 394 @subheading gnutls_openpgp_crt_get_subkey_creation_time
 395 @anchor{gnutls_openpgp_crt_get_subkey_creation_time}
 396 @deftypefun {time_t} {gnutls_openpgp_crt_get_subkey_creation_time} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx})
 397 @var{key}: the structure that contains the OpenPGP public key.
 398
 399 @var{idx}: the subkey index
 400
 401 Get subkey creation time.
 402
 403 @strong{Returns:} the timestamp when the OpenPGP sub-key was created.
 404
 405 @strong{Since:} 2.4.0
 406 @end deftypefun
 407
 408 @subheading gnutls_openpgp_crt_get_subkey_expiration_time
 409 @anchor{gnutls_openpgp_crt_get_subkey_expiration_time}
 410 @deftypefun {time_t} {gnutls_openpgp_crt_get_subkey_expiration_time} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx})
 411 @var{key}: the structure that contains the OpenPGP public key.
 412
 413 @var{idx}: the subkey index
 414
 415 Get subkey expiration time.  A value of '0' means that the key
 416 doesn't expire at all.
 417
 418 @strong{Returns:} the time when the OpenPGP key expires.
 419
 420 @strong{Since:} 2.4.0
 421 @end deftypefun
 422
 423 @subheading gnutls_openpgp_crt_get_subkey_fingerprint
 424 @anchor{gnutls_openpgp_crt_get_subkey_fingerprint}
 425 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_fingerprint} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx}, void * @var{fpr}, size_t * @var{fprlen})
 426 @var{key}: the raw data that contains the OpenPGP public key.
 427
 428 @var{idx}: the subkey index
 429
 430 @var{fpr}: the buffer to save the fingerprint, must hold at least 20 bytes.
 431
 432 @var{fprlen}: the integer to save the length of the fingerprint.
 433
 434 Get key fingerprint of a subkey.  Depending on the algorithm, the
 435 fingerprint can be 16 or 20 bytes.
 436
 437 @strong{Returns:} On success, 0 is returned.  Otherwise, an error code.
 438
 439 @strong{Since:} 2.4.0
 440 @end deftypefun
 441
 442 @subheading gnutls_openpgp_crt_get_subkey_idx
 443 @anchor{gnutls_openpgp_crt_get_subkey_idx}
 444 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_idx} (gnutls_openpgp_crt_t @var{key}, const gnutls_openpgp_keyid_t @var{keyid})
 445 @var{key}: the structure that contains the OpenPGP public key.
 446
 447 @var{keyid}: the keyid.
 448
 449 Get subkey's index.
 450
 451 @strong{Returns:} the index of the subkey or a negative error value.
 452
 453 @strong{Since:} 2.4.0
 454 @end deftypefun
 455
 456 @subheading gnutls_openpgp_crt_get_subkey_id
 457 @anchor{gnutls_openpgp_crt_get_subkey_id}
 458 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_id} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx}, gnutls_openpgp_keyid_t @var{keyid})
 459 @var{key}: the structure that contains the OpenPGP public key.
 460
 461 @var{idx}: the subkey index
 462
 463 @var{keyid}: the buffer to save the keyid.
 464
 465 Get the subkey's key-id.
 466
 467 @strong{Returns:} the 64-bit keyID of the OpenPGP key.
 468 @end deftypefun
 469
 470 @subheading gnutls_openpgp_crt_get_subkey_pk_algorithm
 471 @anchor{gnutls_openpgp_crt_get_subkey_pk_algorithm}
 472 @deftypefun {gnutls_pk_algorithm_t} {gnutls_openpgp_crt_get_subkey_pk_algorithm} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx}, unsigned int * @var{bits})
 473 @var{key}: is an OpenPGP key
 474
 475 @var{idx}: is the subkey index
 476
 477 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
 478
 479 This function will return the public key algorithm of a subkey of an OpenPGP
 480 certificate.
 481
 482 If bits is non null, it should have enough size to hold the
 483 parameters size in bits.  For RSA the bits returned is the modulus.
 484 For DSA the bits returned are of the public exponent.
 485
 486 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
 487 success, or GNUTLS_PK_UNKNOWN on error.
 488
 489 @strong{Since:} 2.4.0
 490 @end deftypefun
 491
 492 @subheading gnutls_openpgp_crt_get_subkey_pk_dsa_raw
 493 @anchor{gnutls_openpgp_crt_get_subkey_pk_dsa_raw}
 494 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_pk_dsa_raw} (gnutls_openpgp_crt_t @var{crt}, unsigned int @var{idx}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y})
 495 @var{crt}: Holds the certificate
 496
 497 @var{idx}: Is the subkey index
 498
 499 @var{p}: will hold the p
 500
 501 @var{q}: will hold the q
 502
 503 @var{g}: will hold the g
 504
 505 @var{y}: will hold the y
 506
 507 This function will export the DSA public key's parameters found in
 508 the given certificate.  The new parameters will be allocated using
 509 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 510
 511 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 512
 513 @strong{Since:} 2.4.0
 514 @end deftypefun
 515
 516 @subheading gnutls_openpgp_crt_get_subkey_pk_rsa_raw
 517 @anchor{gnutls_openpgp_crt_get_subkey_pk_rsa_raw}
 518 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_pk_rsa_raw} (gnutls_openpgp_crt_t @var{crt}, unsigned int @var{idx}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e})
 519 @var{crt}: Holds the certificate
 520
 521 @var{idx}: Is the subkey index
 522
 523 @var{m}: will hold the modulus
 524
 525 @var{e}: will hold the public exponent
 526
 527 This function will export the RSA public key's parameters found in
 528 the given structure.  The new parameters will be allocated using
 529 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 530
 531 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 532
 533 @strong{Since:} 2.4.0
 534 @end deftypefun
 535
 536 @subheading gnutls_openpgp_crt_get_subkey_revoked_status
 537 @anchor{gnutls_openpgp_crt_get_subkey_revoked_status}
 538 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_revoked_status} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx})
 539 @var{key}: the structure that contains the OpenPGP public key.
 540
 541 @var{idx}: is the subkey index
 542
 543 Get subkey revocation status.  A negative value indicates an error.
 544
 545 @strong{Returns:} true (1) if the key has been revoked, or false (0) if it
 546 has not.
 547
 548 @strong{Since:} 2.4.0
 549 @end deftypefun
 550
 551 @subheading gnutls_openpgp_crt_get_subkey_usage
 552 @anchor{gnutls_openpgp_crt_get_subkey_usage}
 553 @deftypefun {int} {gnutls_openpgp_crt_get_subkey_usage} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{idx}, unsigned int * @var{key_usage})
 554 @var{key}: should contain a gnutls_openpgp_crt_t structure
 555
 556 @var{idx}: the subkey index
 557
 558 @var{key_usage}: where the key usage bits will be stored
 559
 560 This function will return certificate's key usage, by checking the
 561 key algorithm.  The key usage value will ORed values of
 562 @code{GNUTLS_KEY_DIGITAL_SIGNATURE} or @code{GNUTLS_KEY_KEY_ENCIPHERMENT}.
 563
 564 A negative value may be returned in case of parsing error.
 565
 566 @strong{Returns:} key usage value.
 567
 568 @strong{Since:} 2.4.0
 569 @end deftypefun
 570
 571 @subheading gnutls_openpgp_crt_get_version
 572 @anchor{gnutls_openpgp_crt_get_version}
 573 @deftypefun {int} {gnutls_openpgp_crt_get_version} (gnutls_openpgp_crt_t @var{key})
 574 @var{key}: the structure that contains the OpenPGP public key.
 575
 576 Extract the version of the OpenPGP key.
 577
 578 @strong{Returns:} the version number is returned, or a negative value on errors.
 579 @end deftypefun
 580
 581 @subheading gnutls_openpgp_crt_import
 582 @anchor{gnutls_openpgp_crt_import}
 583 @deftypefun {int} {gnutls_openpgp_crt_import} (gnutls_openpgp_crt_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_openpgp_crt_fmt_t @var{format})
 584 @var{key}: The structure to store the parsed key.
 585
 586 @var{data}: The RAW or BASE64 encoded key.
 587
 588 @var{format}: One of gnutls_openpgp_crt_fmt_t elements.
 589
 590 This function will convert the given RAW or Base64 encoded key to
 591 the native @code{gnutls_openpgp_crt_t} format. The output will be stored
 592 in 'key'.
 593
 594 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 595 @end deftypefun
 596
 597 @subheading gnutls_openpgp_crt_init
 598 @anchor{gnutls_openpgp_crt_init}
 599 @deftypefun {int} {gnutls_openpgp_crt_init} (gnutls_openpgp_crt_t * @var{key})
 600 @var{key}: The structure to be initialized
 601
 602 This function will initialize an OpenPGP key structure.
 603
 604 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 605 @end deftypefun
 606
 607 @subheading gnutls_openpgp_crt_print
 608 @anchor{gnutls_openpgp_crt_print}
 609 @deftypefun {int} {gnutls_openpgp_crt_print} (gnutls_openpgp_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
 610 @var{cert}: The structure to be printed
 611
 612 @var{format}: Indicate the format to use
 613
 614 @var{out}: Newly allocated datum with zero terminated string.
 615
 616 This function will pretty print an OpenPGP certificate, suitable
 617 for display to a human.
 618
 619 The format should be zero for future compatibility.
 620
 621 The output @code{out} needs to be deallocate using @code{gnutls_free()}.
 622
 623 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 624 @end deftypefun
 625
 626 @subheading gnutls_openpgp_crt_set_preferred_key_id
 627 @anchor{gnutls_openpgp_crt_set_preferred_key_id}
 628 @deftypefun {int} {gnutls_openpgp_crt_set_preferred_key_id} (gnutls_openpgp_crt_t @var{key}, const gnutls_openpgp_keyid_t @var{keyid})
 629 @var{key}: the structure that contains the OpenPGP public key.
 630
 631 @var{keyid}: the selected keyid
 632
 633 This allows setting a preferred key id for the given certificate.
 634 This key will be used by functions that involve key handling.
 635
 636 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (zero) is returned,
 637 otherwise an error code is returned.
 638 @end deftypefun
 639
 640 @subheading gnutls_openpgp_crt_verify_ring
 641 @anchor{gnutls_openpgp_crt_verify_ring}
 642 @deftypefun {int} {gnutls_openpgp_crt_verify_ring} (gnutls_openpgp_crt_t @var{key}, gnutls_openpgp_keyring_t @var{keyring}, unsigned int @var{flags}, unsigned int * @var{verify})
 643 @var{key}: the structure that holds the key.
 644
 645 @var{keyring}: holds the keyring to check against
 646
 647 @var{flags}: unused (should be 0)
 648
 649 @var{verify}: will hold the certificate verification output.
 650
 651 Verify all signatures in the key, using the given set of keys
 652 (keyring).
 653
 654 The key verification output will be put in @code{verify} and will be one
 655 or more of the @code{gnutls_certificate_status_t} enumerated elements
 656 bitwise or'd.
 657
 658 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 659 @end deftypefun
 660
 661 @subheading gnutls_openpgp_crt_verify_self
 662 @anchor{gnutls_openpgp_crt_verify_self}
 663 @deftypefun {int} {gnutls_openpgp_crt_verify_self} (gnutls_openpgp_crt_t @var{key}, unsigned int @var{flags}, unsigned int * @var{verify})
 664 @var{key}: the structure that holds the key.
 665
 666 @var{flags}: unused (should be 0)
 667
 668 @var{verify}: will hold the key verification output.
 669
 670 Verifies the self signature in the key.  The key verification
 671 output will be put in @code{verify} and will be one or more of the
 672 gnutls_certificate_status_t enumerated elements bitwise or'd.
 673
 674 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 675 @end deftypefun
 676
 677 @subheading gnutls_openpgp_keyring_check_id
 678 @anchor{gnutls_openpgp_keyring_check_id}
 679 @deftypefun {int} {gnutls_openpgp_keyring_check_id} (gnutls_openpgp_keyring_t @var{ring}, const gnutls_openpgp_keyid_t @var{keyid}, unsigned int @var{flags})
 680 @var{ring}: holds the keyring to check against
 681
 682 @var{keyid}: will hold the keyid to check for.
 683
 684 @var{flags}: unused (should be 0)
 685
 686 Check if a given key ID exists in the keyring.
 687
 688 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success (if keyid exists) and a
 689 negative error code on failure.
 690 @end deftypefun
 691
 692 @subheading gnutls_openpgp_keyring_deinit
 693 @anchor{gnutls_openpgp_keyring_deinit}
 694 @deftypefun {void} {gnutls_openpgp_keyring_deinit} (gnutls_openpgp_keyring_t @var{keyring})
 695 @var{keyring}: The structure to be initialized
 696
 697 This function will deinitialize a keyring structure.
 698 @end deftypefun
 699
 700 @subheading gnutls_openpgp_keyring_get_crt_count
 701 @anchor{gnutls_openpgp_keyring_get_crt_count}
 702 @deftypefun {int} {gnutls_openpgp_keyring_get_crt_count} (gnutls_openpgp_keyring_t @var{ring})
 703 @var{ring}: is an OpenPGP key ring
 704
 705 This function will return the number of OpenPGP certificates
 706 present in the given keyring.
 707
 708 @strong{Returns:} the number of subkeys, or a negative value on error.
 709 @end deftypefun
 710
 711 @subheading gnutls_openpgp_keyring_get_crt
 712 @anchor{gnutls_openpgp_keyring_get_crt}
 713 @deftypefun {int} {gnutls_openpgp_keyring_get_crt} (gnutls_openpgp_keyring_t @var{ring}, unsigned int @var{idx}, gnutls_openpgp_crt_t * @var{cert})
 714 @var{ring}: Holds the keyring.
 715
 716 @var{idx}: the index of the certificate to export
 717
 718 @var{cert}: An uninitialized @code{gnutls_openpgp_crt_t} structure
 719
 720 This function will extract an OpenPGP certificate from the given
 721 keyring.  If the index given is out of range
 722 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. The
 723 returned structure needs to be deinited.
 724
 725 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 726 @end deftypefun
 727
 728 @subheading gnutls_openpgp_keyring_import
 729 @anchor{gnutls_openpgp_keyring_import}
 730 @deftypefun {int} {gnutls_openpgp_keyring_import} (gnutls_openpgp_keyring_t @var{keyring}, const gnutls_datum_t * @var{data}, gnutls_openpgp_crt_fmt_t @var{format})
 731 @var{keyring}: The structure to store the parsed key.
 732
 733 @var{data}: The RAW or BASE64 encoded keyring.
 734
 735 @var{format}: One of @code{gnutls_openpgp_keyring_fmt} elements.
 736
 737 This function will convert the given RAW or Base64 encoded keyring
 738 to the native @code{gnutls_openpgp_keyring_t} format.  The output will be
 739 stored in 'keyring'.
 740
 741 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 742 @end deftypefun
 743 @subheading gnutls_openpgp_keyring_init
 744 @anchor{gnutls_openpgp_keyring_init}
 745 @deftypefun {int} {gnutls_openpgp_keyring_init} (gnutls_openpgp_keyring_t * @var{keyring})
 746 @var{keyring}: The structure to be initialized
 747
 748 This function will initialize an keyring structure.
 749
 750 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 751 @end deftypefun
 752
 753 @subheading gnutls_openpgp_privkey_deinit
 754 @anchor{gnutls_openpgp_privkey_deinit}
 755 @deftypefun {void} {gnutls_openpgp_privkey_deinit} (gnutls_openpgp_privkey_t @var{key})
 756 @var{key}: The structure to be initialized
 757
 758 This function will deinitialize a key structure.
 759 @end deftypefun
 760
 761 @subheading gnutls_openpgp_privkey_export_dsa_raw
 762 @anchor{gnutls_openpgp_privkey_export_dsa_raw}
 763 @deftypefun {int} {gnutls_openpgp_privkey_export_dsa_raw} (gnutls_openpgp_privkey_t @var{pkey}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{x})
 764 @var{pkey}: Holds the certificate
 765
 766 @var{p}: will hold the p
 767
 768 @var{q}: will hold the q
 769
 770 @var{g}: will hold the g
 771
 772 @var{y}: will hold the y
 773
 774 @var{x}: will hold the x
 775
 776 This function will export the DSA private key's parameters found in
 777 the given certificate.  The new parameters will be allocated using
 778 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 779
 780 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 781
 782 @strong{Since:} 2.4.0
 783 @end deftypefun
 784
 785 @subheading gnutls_openpgp_privkey_export_rsa_raw
 786 @anchor{gnutls_openpgp_privkey_export_rsa_raw}
 787 @deftypefun {int} {gnutls_openpgp_privkey_export_rsa_raw} (gnutls_openpgp_privkey_t @var{pkey}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u})
 788 @var{pkey}: Holds the certificate
 789
 790 @var{m}: will hold the modulus
 791
 792 @var{e}: will hold the public exponent
 793
 794 @var{d}: will hold the private exponent
 795
 796 @var{p}: will hold the first prime (p)
 797
 798 @var{q}: will hold the second prime (q)
 799
 800 @var{u}: will hold the coefficient
 801
 802 This function will export the RSA private key's parameters found in
 803 the given structure.  The new parameters will be allocated using
 804 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 805
 806 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 807
 808 @strong{Since:} 2.4.0
 809 @end deftypefun
 810
 811 @subheading gnutls_openpgp_privkey_export_subkey_dsa_raw
 812 @anchor{gnutls_openpgp_privkey_export_subkey_dsa_raw}
 813 @deftypefun {int} {gnutls_openpgp_privkey_export_subkey_dsa_raw} (gnutls_openpgp_privkey_t @var{pkey}, unsigned int @var{idx}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{x})
 814 @var{pkey}: Holds the certificate
 815
 816 @var{idx}: Is the subkey index
 817
 818 @var{p}: will hold the p
 819
 820 @var{q}: will hold the q
 821
 822 @var{g}: will hold the g
 823
 824 @var{y}: will hold the y
 825
 826 @var{x}: will hold the x
 827
 828 This function will export the DSA private key's parameters found
 829 in the given certificate.  The new parameters will be allocated
 830 using @code{gnutls_malloc()} and will be stored in the appropriate datum.
 831
 832 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 833
 834 @strong{Since:} 2.4.0
 835 @end deftypefun
 836
 837 @subheading gnutls_openpgp_privkey_export_subkey_rsa_raw
 838 @anchor{gnutls_openpgp_privkey_export_subkey_rsa_raw}
 839 @deftypefun {int} {gnutls_openpgp_privkey_export_subkey_rsa_raw} (gnutls_openpgp_privkey_t @var{pkey}, unsigned int @var{idx}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u})
 840 @var{pkey}: Holds the certificate
 841
 842 @var{idx}: Is the subkey index
 843
 844 @var{m}: will hold the modulus
 845
 846 @var{e}: will hold the public exponent
 847
 848 @var{d}: will hold the private exponent
 849
 850 @var{p}: will hold the first prime (p)
 851
 852 @var{q}: will hold the second prime (q)
 853
 854 @var{u}: will hold the coefficient
 855
 856 This function will export the RSA private key's parameters found in
 857 the given structure.  The new parameters will be allocated using
 858 @code{gnutls_malloc()} and will be stored in the appropriate datum.
 859
 860 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
 861
 862 @strong{Since:} 2.4.0
 863 @end deftypefun
 864
 865 @subheading gnutls_openpgp_privkey_export
 866 @anchor{gnutls_openpgp_privkey_export}
 867 @deftypefun {int} {gnutls_openpgp_privkey_export} (gnutls_openpgp_privkey_t @var{key}, gnutls_openpgp_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}, void * @var{output_data}, size_t * @var{output_data_size})
 868 @var{key}: Holds the key.
 869
 870 @var{format}: One of gnutls_openpgp_crt_fmt_t elements.
 871
 872 @var{password}: the password that will be used to encrypt the key. (unused for now)
 873
 874 @var{flags}: zero for future compatibility
 875
 876 @var{output_data}: will contain the key base64 encoded or raw
 877
 878 @var{output_data_size}: holds the size of output_data (and will be
 879 replaced by the actual size of parameters)
 880
 881 This function will convert the given key to RAW or Base64 format.
 882 If the buffer provided is not long enough to hold the output, then
 883 GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
 884
 885 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
 886
 887 @strong{Since:} 2.4.0
 888 @end deftypefun
 889
 890 @subheading gnutls_openpgp_privkey_get_fingerprint
 891 @anchor{gnutls_openpgp_privkey_get_fingerprint}
 892 @deftypefun {int} {gnutls_openpgp_privkey_get_fingerprint} (gnutls_openpgp_privkey_t @var{key}, void * @var{fpr}, size_t * @var{fprlen})
 893 @var{key}: the raw data that contains the OpenPGP secret key.
 894
 895 @var{fpr}: the buffer to save the fingerprint, must hold at least 20 bytes.
 896
 897 @var{fprlen}: the integer to save the length of the fingerprint.
 898
 899 Get the fingerprint of the OpenPGP key. Depends on the
 900 algorithm, the fingerprint can be 16 or 20 bytes.
 901
 902 @strong{Returns:} On success, 0 is returned, or an error code.
 903
 904 @strong{Since:} 2.4.0
 905 @end deftypefun
 906
 907 @subheading gnutls_openpgp_privkey_get_key_id
 908 @anchor{gnutls_openpgp_privkey_get_key_id}
 909 @deftypefun {int} {gnutls_openpgp_privkey_get_key_id} (gnutls_openpgp_privkey_t @var{key}, gnutls_openpgp_keyid_t @var{keyid})
 910 @var{key}: the structure that contains the OpenPGP secret key.
 911
 912 @var{keyid}: the buffer to save the keyid.
 913
 914 Get key-id.
 915
 916 @strong{Returns:} the 64-bit keyID of the OpenPGP key.
 917
 918 @strong{Since:} 2.4.0
 919 @end deftypefun
 920
 921 @subheading gnutls_openpgp_privkey_get_pk_algorithm
 922 @anchor{gnutls_openpgp_privkey_get_pk_algorithm}
 923 @deftypefun {gnutls_pk_algorithm_t} {gnutls_openpgp_privkey_get_pk_algorithm} (gnutls_openpgp_privkey_t @var{key}, unsigned int * @var{bits})
 924 @var{key}: is an OpenPGP key
 925
 926 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
 927
 928 This function will return the public key algorithm of an OpenPGP
 929 certificate.
 930
 931 If bits is non null, it should have enough size to hold the parameters
 932 size in bits. For RSA the bits returned is the modulus.
 933 For DSA the bits returned are of the public exponent.
 934
 935 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
 936 success, or a negative value on error.
 937
 938 @strong{Since:} 2.4.0
 939 @end deftypefun
 940
 941 @subheading gnutls_openpgp_privkey_get_preferred_key_id
 942 @anchor{gnutls_openpgp_privkey_get_preferred_key_id}
 943 @deftypefun {int} {gnutls_openpgp_privkey_get_preferred_key_id} (gnutls_openpgp_privkey_t @var{key}, gnutls_openpgp_keyid_t @var{keyid})
 944 @var{key}: the structure that contains the OpenPGP public key.
 945
 946 @var{keyid}: the struct to save the keyid.
 947
 948 Get the preferred key-id for the key.
 949
 950 @strong{Returns:} the 64-bit preferred keyID of the OpenPGP key, or if it
 951 hasn't been set it returns @code{GNUTLS_E_INVALID_REQUEST}.
 952 @end deftypefun
 953
 954 @subheading gnutls_openpgp_privkey_get_revoked_status
 955 @anchor{gnutls_openpgp_privkey_get_revoked_status}
 956 @deftypefun {int} {gnutls_openpgp_privkey_get_revoked_status} (gnutls_openpgp_privkey_t @var{key})
 957 @var{key}: the structure that contains the OpenPGP private key.
 958
 959 Get revocation status of key.
 960
 961 @strong{Returns:} true (1) if the key has been revoked, or false (0) if it
 962 has not, or a negative value indicates an error.
 963
 964 @strong{Since:} 2.4.0
 965 @end deftypefun
 966
 967 @subheading gnutls_openpgp_privkey_get_subkey_count
 968 @anchor{gnutls_openpgp_privkey_get_subkey_count}
 969 @deftypefun {int} {gnutls_openpgp_privkey_get_subkey_count} (gnutls_openpgp_privkey_t @var{key})
 970 @var{key}: is an OpenPGP key
 971
 972 This function will return the number of subkeys present in the
 973 given OpenPGP certificate.
 974
 975 @strong{Returns:} the number of subkeys, or a negative value on error.
 976
 977 @strong{Since:} 2.4.0
 978 @end deftypefun
 979
 980 @subheading gnutls_openpgp_privkey_get_subkey_creation_time
 981 @anchor{gnutls_openpgp_privkey_get_subkey_creation_time}
 982 @deftypefun {time_t} {gnutls_openpgp_privkey_get_subkey_creation_time} (gnutls_openpgp_privkey_t @var{key}, unsigned int @var{idx})
 983 @var{key}: the structure that contains the OpenPGP private key.
 984
 985 @var{idx}: the subkey index
 986
 987 Get subkey creation time.
 988
 989 @strong{Returns:} the timestamp when the OpenPGP key was created.
 990
 991 @strong{Since:} 2.4.0
 992 @end deftypefun
 993
 994 @subheading gnutls_openpgp_privkey_get_subkey_expiration_time
 995 @anchor{gnutls_openpgp_privkey_get_subkey_expiration_time}
 996 @deftypefun {time_t} {gnutls_openpgp_privkey_get_subkey_expiration_time} (gnutls_openpgp_privkey_t                                                    @var{key}, unsigned int @var{idx})
 997 @var{key}: the structure that contains the OpenPGP private key.
 998
 999 @var{idx}: the subkey index
1000
1001 Get subkey expiration time.  A value of '0' means that the key
1002 doesn't expire at all.
1003
1004 @strong{Returns:} the time when the OpenPGP key expires.
1005
1006 @strong{Since:} 2.4.0
1007 @end deftypefun
1008
1009 @subheading gnutls_openpgp_privkey_get_subkey_fingerprint
1010 @anchor{gnutls_openpgp_privkey_get_subkey_fingerprint}
1011 @deftypefun {int} {gnutls_openpgp_privkey_get_subkey_fingerprint} (gnutls_openpgp_privkey_t @var{key}, unsigned int @var{idx}, void * @var{fpr}, size_t * @var{fprlen})
1012 @var{key}: the raw data that contains the OpenPGP secret key.
1013
1014 @var{idx}: the subkey index
1015
1016 @var{fpr}: the buffer to save the fingerprint, must hold at least 20 bytes.
1017
1018 @var{fprlen}: the integer to save the length of the fingerprint.
1019
1020 Get the fingerprint of an OpenPGP subkey.  Depends on the
1021 algorithm, the fingerprint can be 16 or 20 bytes.
1022
1023 @strong{Returns:} On success, 0 is returned, or an error code.
1024
1025 @strong{Since:} 2.4.0
1026 @end deftypefun
1027
1028 @subheading gnutls_openpgp_privkey_get_subkey_idx
1029 @anchor{gnutls_openpgp_privkey_get_subkey_idx}
1030 @deftypefun {int} {gnutls_openpgp_privkey_get_subkey_idx} (gnutls_openpgp_privkey_t @var{key}, const gnutls_openpgp_keyid_t @var{keyid})
1031 @var{key}: the structure that contains the OpenPGP private key.
1032
1033 @var{keyid}: the keyid.
1034
1035 Get index of subkey.
1036
1037 @strong{Returns:} the index of the subkey or a negative error value.
1038
1039 @strong{Since:} 2.4.0
1040 @end deftypefun
1041
1042 @subheading gnutls_openpgp_privkey_get_subkey_id
1043 @anchor{gnutls_openpgp_privkey_get_subkey_id}
1044 @deftypefun {int} {gnutls_openpgp_privkey_get_subkey_id} (gnutls_openpgp_privkey_t @var{key}, unsigned int @var{idx}, gnutls_openpgp_keyid_t @var{keyid})
1045 @var{key}: the structure that contains the OpenPGP secret key.
1046
1047 @var{idx}: the subkey index
1048
1049 @var{keyid}: the buffer to save the keyid.
1050
1051 Get the key-id for the subkey.
1052
1053 @strong{Returns:} the 64-bit keyID of the OpenPGP key.
1054
1055 @strong{Since:} 2.4.0
1056 @end deftypefun
1057
1058 @subheading gnutls_openpgp_privkey_get_subkey_pk_algorithm
1059 @anchor{gnutls_openpgp_privkey_get_subkey_pk_algorithm}
1060 @deftypefun {gnutls_pk_algorithm_t} {gnutls_openpgp_privkey_get_subkey_pk_algorithm} (gnutls_openpgp_privkey_t @var{key}, unsigned int @var{idx}, unsigned int * @var{bits})
1061 @var{key}: is an OpenPGP key
1062
1063 @var{idx}: is the subkey index
1064
1065 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
1066
1067 This function will return the public key algorithm of a subkey of an OpenPGP
1068 certificate.
1069
1070 If bits is non null, it should have enough size to hold the parameters
1071 size in bits. For RSA the bits returned is the modulus.
1072 For DSA the bits returned are of the public exponent.
1073
1074 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
1075 success, or a negative value on error.
1076
1077 @strong{Since:} 2.4.0
1078 @end deftypefun
1079
1080 @subheading gnutls_openpgp_privkey_get_subkey_revoked_status
1081 @anchor{gnutls_openpgp_privkey_get_subkey_revoked_status}
1082 @deftypefun {int} {gnutls_openpgp_privkey_get_subkey_revoked_status} (gnutls_openpgp_privkey_t                                                   @var{key}, unsigned int @var{idx})
1083 @var{key}: the structure that contains the OpenPGP private key.
1084
1085 @var{idx}: is the subkey index
1086
1087 Get revocation status of key.
1088
1089 @strong{Returns:} true (1) if the key has been revoked, or false (0) if it
1090 has not, or a negative value indicates an error.
1091
1092 @strong{Since:} 2.4.0
1093 @end deftypefun
1094
1095 @subheading gnutls_openpgp_privkey_import
1096 @anchor{gnutls_openpgp_privkey_import}
1097 @deftypefun {int} {gnutls_openpgp_privkey_import} (gnutls_openpgp_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_openpgp_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags})
1098 @var{key}: The structure to store the parsed key.
1099
1100 @var{data}: The RAW or BASE64 encoded key.
1101
1102 @var{format}: One of @code{gnutls_openpgp_crt_fmt_t} elements.
1103
1104 @var{password}: not used for now
1105
1106 @var{flags}: should be zero
1107
1108 This function will convert the given RAW or Base64 encoded key to
1109 the native gnutls_openpgp_privkey_t format.  The output will be
1110 stored in 'key'.
1111
1112 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
1113 @end deftypefun
1114
1115 @subheading gnutls_openpgp_privkey_init
1116 @anchor{gnutls_openpgp_privkey_init}
1117 @deftypefun {int} {gnutls_openpgp_privkey_init} (gnutls_openpgp_privkey_t * @var{key})
1118 @var{key}: The structure to be initialized
1119
1120 This function will initialize an OpenPGP key structure.
1121
1122 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
1123 @end deftypefun
1124
1125 @subheading gnutls_openpgp_privkey_sec_param
1126 @anchor{gnutls_openpgp_privkey_sec_param}
1127 @deftypefun {gnutls_sec_param_t} {gnutls_openpgp_privkey_sec_param} (gnutls_openpgp_privkey_t @var{key})
1128 @var{key}: a key structure
1129
1130 This function will return the security parameter appropriate with
1131 this private key.
1132
1133 @strong{Returns:} On success, a valid security parameter is returned otherwise
1134 @code{GNUTLS_SEC_PARAM_UNKNOWN} is returned.
1135 @end deftypefun
1136
1137 @subheading gnutls_openpgp_privkey_set_preferred_key_id
1138 @anchor{gnutls_openpgp_privkey_set_preferred_key_id}
1139 @deftypefun {int} {gnutls_openpgp_privkey_set_preferred_key_id} (gnutls_openpgp_privkey_t @var{key}, const gnutls_openpgp_keyid_t                                              @var{keyid})
1140 @var{key}: the structure that contains the OpenPGP public key.
1141
1142 @var{keyid}: the selected keyid
1143
1144 This allows setting a preferred key id for the given certificate.
1145 This key will be used by functions that involve key handling.
1146
1147 @strong{Returns:} On success, 0 is returned, or an error code.
1148 @end deftypefun
1149
1150 @subheading gnutls_openpgp_privkey_sign_hash
1151 @anchor{gnutls_openpgp_privkey_sign_hash}
1152 @deftypefun {int} {gnutls_openpgp_privkey_sign_hash} (gnutls_openpgp_privkey_t @var{key}, const gnutls_datum_t * @var{hash}, gnutls_datum_t * @var{signature})
1153 @var{key}: Holds the key
1154
1155 @var{hash}: holds the data to be signed
1156
1157 @var{signature}: will contain newly allocated signature
1158
1159 This function will sign the given hash using the private key.  You
1160 should use @code{gnutls_openpgp_privkey_set_preferred_key_id()} before
1161 calling this function to set the subkey to use.
1162
1163 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
1164 negative error value.
1165
1166 @strong{Deprecated:} Use @code{gnutls_privkey_sign_hash()} instead.
1167 @end deftypefun
1168
1169 @subheading gnutls_openpgp_set_recv_key_function
1170 @anchor{gnutls_openpgp_set_recv_key_function}
1171 @deftypefun {void} {gnutls_openpgp_set_recv_key_function} (gnutls_session_t @var{session}, gnutls_openpgp_recv_key_func @var{func})
1172 @var{session}: a TLS session
1173
1174 @var{func}: the callback
1175
1176 This funtion will set a key retrieval function for OpenPGP keys. This
1177 callback is only useful in server side, and will be used if the peer
1178 sent a key fingerprint instead of a full key.
1179 @end deftypefun