doc/pkcs12-api.texi

   1
   2 @subheading gnutls_pkcs12_bag_decrypt
   3 @anchor{gnutls_pkcs12_bag_decrypt}
   4 @deftypefun {int} {gnutls_pkcs12_bag_decrypt} (gnutls_pkcs12_bag_t @var{bag}, const char * @var{pass})
   5 @var{bag}: The bag
   6
   7 @var{pass}: The password used for encryption, must be ASCII.
   8
   9 This function will decrypt the given encrypted bag and return 0 on
  10 success.
  11
  12 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned,
  13 otherwise a negative error code is returned.
  14 @end deftypefun
  15
  16 @subheading gnutls_pkcs12_bag_deinit
  17 @anchor{gnutls_pkcs12_bag_deinit}
  18 @deftypefun {void} {gnutls_pkcs12_bag_deinit} (gnutls_pkcs12_bag_t @var{bag})
  19 @var{bag}: The structure to be initialized
  20
  21 This function will deinitialize a PKCS12 Bag structure.
  22 @end deftypefun
  23
  24 @subheading gnutls_pkcs12_bag_encrypt
  25 @anchor{gnutls_pkcs12_bag_encrypt}
  26 @deftypefun {int} {gnutls_pkcs12_bag_encrypt} (gnutls_pkcs12_bag_t @var{bag}, const char * @var{pass}, unsigned int @var{flags})
  27 @var{bag}: The bag
  28
  29 @var{pass}: The password used for encryption, must be ASCII
  30
  31 @var{flags}: should be one of @code{gnutls_pkcs_encrypt_flags_t}  elements bitwise or'd
  32
  33 This function will encrypt the given bag.
  34
  35 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned,
  36 otherwise a negative error code is returned.
  37 @end deftypefun
  38
  39 @subheading gnutls_pkcs12_bag_get_count
  40 @anchor{gnutls_pkcs12_bag_get_count}
  41 @deftypefun {int} {gnutls_pkcs12_bag_get_count} (gnutls_pkcs12_bag_t @var{bag})
  42 @var{bag}: The bag
  43
  44 This function will return the number of the elements withing the bag.
  45
  46 @strong{Returns:} Number of elements in bag, or an negative error code on
  47 error.
  48 @end deftypefun
  49
  50 @subheading gnutls_pkcs12_bag_get_data
  51 @anchor{gnutls_pkcs12_bag_get_data}
  52 @deftypefun {int} {gnutls_pkcs12_bag_get_data} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, gnutls_datum_t * @var{data})
  53 @var{bag}: The bag
  54
  55 @var{indx}: The element of the bag to get the data from
  56
  57 @var{data}: where the bag's data will be. Should be treated as constant.
  58
  59 This function will return the bag's data. The data is a constant
  60 that is stored into the bag.  Should not be accessed after the bag
  61 is deleted.
  62
  63 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  64 negative error value.
  65 @end deftypefun
  66
  67 @subheading gnutls_pkcs12_bag_get_friendly_name
  68 @anchor{gnutls_pkcs12_bag_get_friendly_name}
  69 @deftypefun {int} {gnutls_pkcs12_bag_get_friendly_name} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, char ** @var{name})
  70 @var{bag}: The bag
  71
  72 @var{indx}: The bag's element to add the id
  73
  74 @var{name}: will hold a pointer to the name (to be treated as const)
  75
  76 This function will return the friendly name, of the specified bag
  77 element.  The key ID is usually used to distinguish the local
  78 private key and the certificate pair.
  79
  80 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  81 negative error value. or a negative error code on error.
  82 @end deftypefun
  83
  84 @subheading gnutls_pkcs12_bag_get_key_id
  85 @anchor{gnutls_pkcs12_bag_get_key_id}
  86 @deftypefun {int} {gnutls_pkcs12_bag_get_key_id} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, gnutls_datum_t * @var{id})
  87 @var{bag}: The bag
  88
  89 @var{indx}: The bag's element to add the id
  90
  91 @var{id}: where the ID will be copied (to be treated as const)
  92
  93 This function will return the key ID, of the specified bag element.
  94 The key ID is usually used to distinguish the local private key and
  95 the certificate pair.
  96
  97 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  98 negative error value. or a negative error code on error.
  99 @end deftypefun
 100
 101 @subheading gnutls_pkcs12_bag_get_type
 102 @anchor{gnutls_pkcs12_bag_get_type}
 103 @deftypefun {gnutls_pkcs12_bag_type_t} {gnutls_pkcs12_bag_get_type} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx})
 104 @var{bag}: The bag
 105
 106 @var{indx}: The element of the bag to get the type
 107
 108 This function will return the bag's type.
 109
 110 @strong{Returns:} One of the @code{gnutls_pkcs12_bag_type_t}  enumerations.
 111 @end deftypefun
 112
 113 @subheading gnutls_pkcs12_bag_init
 114 @anchor{gnutls_pkcs12_bag_init}
 115 @deftypefun {int} {gnutls_pkcs12_bag_init} (gnutls_pkcs12_bag_t * @var{bag})
 116 @var{bag}: The structure to be initialized
 117
 118 This function will initialize a PKCS12 bag structure. PKCS12 Bags
 119 usually contain private keys, lists of X.509 Certificates and X.509
 120 Certificate revocation lists.
 121
 122 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 123 negative error value.
 124 @end deftypefun
 125
 126 @subheading gnutls_pkcs12_bag_set_crl
 127 @anchor{gnutls_pkcs12_bag_set_crl}
 128 @deftypefun {int} {gnutls_pkcs12_bag_set_crl} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_crl_t @var{crl})
 129 @var{bag}: The bag
 130
 131 @var{crl}: the CRL to be copied.
 132
 133 This function will insert the given CRL into the
 134 bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()} .
 135
 136 @strong{Returns:} the index of the added bag on success, or a negative error code
 137 on failure.
 138 @end deftypefun
 139
 140 @subheading gnutls_pkcs12_bag_set_crt
 141 @anchor{gnutls_pkcs12_bag_set_crt}
 142 @deftypefun {int} {gnutls_pkcs12_bag_set_crt} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_crt_t @var{crt})
 143 @var{bag}: The bag
 144
 145 @var{crt}: the certificate to be copied.
 146
 147 This function will insert the given certificate into the
 148 bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()} .
 149
 150 @strong{Returns:} the index of the added bag on success, or a negative
 151 value on failure.
 152 @end deftypefun
 153
 154 @subheading gnutls_pkcs12_bag_set_data
 155 @anchor{gnutls_pkcs12_bag_set_data}
 156 @deftypefun {int} {gnutls_pkcs12_bag_set_data} (gnutls_pkcs12_bag_t @var{bag}, gnutls_pkcs12_bag_type_t @var{type}, const gnutls_datum_t * @var{data})
 157 @var{bag}: The bag
 158
 159 @var{type}: The data's type
 160
 161 @var{data}: the data to be copied.
 162
 163 This function will insert the given data of the given type into
 164 the bag.
 165
 166 @strong{Returns:} the index of the added bag on success, or a negative
 167 value on error.
 168 @end deftypefun
 169
 170 @subheading gnutls_pkcs12_bag_set_friendly_name
 171 @anchor{gnutls_pkcs12_bag_set_friendly_name}
 172 @deftypefun {int} {gnutls_pkcs12_bag_set_friendly_name} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, const char * @var{name})
 173 @var{bag}: The bag
 174
 175 @var{indx}: The bag's element to add the id
 176
 177 @var{name}: the name
 178
 179 This function will add the given key friendly name, to the
 180 specified, by the index, bag element. The name will be encoded as
 181 a 'Friendly name' bag attribute, which is usually used to set a
 182 user name to the local private key and the certificate pair.
 183
 184 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 185 negative error value. or a negative error code on error.
 186 @end deftypefun
 187
 188 @subheading gnutls_pkcs12_bag_set_key_id
 189 @anchor{gnutls_pkcs12_bag_set_key_id}
 190 @deftypefun {int} {gnutls_pkcs12_bag_set_key_id} (gnutls_pkcs12_bag_t @var{bag}, int @var{indx}, const gnutls_datum_t * @var{id})
 191 @var{bag}: The bag
 192
 193 @var{indx}: The bag's element to add the id
 194
 195 @var{id}: the ID
 196
 197 This function will add the given key ID, to the specified, by the
 198 index, bag element. The key ID will be encoded as a 'Local key
 199 identifier' bag attribute, which is usually used to distinguish
 200 the local private key and the certificate pair.
 201
 202 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 203 negative error value. or a negative error code on error.
 204 @end deftypefun
 205
 206 @subheading gnutls_pkcs12_deinit
 207 @anchor{gnutls_pkcs12_deinit}
 208 @deftypefun {void} {gnutls_pkcs12_deinit} (gnutls_pkcs12_t @var{pkcs12})
 209 @var{pkcs12}: The structure to be initialized
 210
 211 This function will deinitialize a PKCS12 structure.
 212 @end deftypefun
 213
 214 @subheading gnutls_pkcs12_export
 215 @anchor{gnutls_pkcs12_export}
 216 @deftypefun {int} {gnutls_pkcs12_export} (gnutls_pkcs12_t @var{pkcs12}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size})
 217 @var{pkcs12}: Holds the pkcs12 structure
 218
 219 @var{format}: the format of output params. One of PEM or DER.
 220
 221 @var{output_data}: will contain a structure PEM or DER encoded
 222
 223 @var{output_data_size}: holds the size of output_data (and will be
 224 replaced by the actual size of parameters)
 225
 226 This function will export the pkcs12 structure to DER or PEM format.
 227
 228 If the buffer provided is not long enough to hold the output, then
 229 *output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER
 230 will be returned.
 231
 232 If the structure is PEM encoded, it will have a header
 233 of "BEGIN PKCS12".
 234
 235 @strong{Returns:} In case of failure a negative error code will be
 236 returned, and 0 on success.
 237 @end deftypefun
 238
 239 @subheading gnutls_pkcs12_export2
 240 @anchor{gnutls_pkcs12_export2}
 241 @deftypefun {int} {gnutls_pkcs12_export2} (gnutls_pkcs12_t @var{pkcs12}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
 242 @var{pkcs12}: Holds the pkcs12 structure
 243
 244 @var{format}: the format of output params. One of PEM or DER.
 245
 246 @var{out}: will contain a structure PEM or DER encoded
 247
 248 This function will export the pkcs12 structure to DER or PEM format.
 249
 250 The output buffer is allocated using @code{gnutls_malloc()} .
 251
 252 If the structure is PEM encoded, it will have a header
 253 of "BEGIN PKCS12".
 254
 255 @strong{Returns:} In case of failure a negative error code will be
 256 returned, and 0 on success.
 257
 258 @strong{Since:} 3.1.3
 259 @end deftypefun
 260
 261 @subheading gnutls_pkcs12_generate_mac
 262 @anchor{gnutls_pkcs12_generate_mac}
 263 @deftypefun {int} {gnutls_pkcs12_generate_mac} (gnutls_pkcs12_t @var{pkcs12}, const char * @var{pass})
 264 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
 265
 266 @var{pass}: The password for the MAC
 267
 268 This function will generate a MAC for the PKCS12 structure.
 269
 270 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 271 negative error value.
 272 @end deftypefun
 273
 274 @subheading gnutls_pkcs12_get_bag
 275 @anchor{gnutls_pkcs12_get_bag}
 276 @deftypefun {int} {gnutls_pkcs12_get_bag} (gnutls_pkcs12_t @var{pkcs12}, int @var{indx}, gnutls_pkcs12_bag_t @var{bag})
 277 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
 278
 279 @var{indx}: contains the index of the bag to extract
 280
 281 @var{bag}: An initialized bag, where the contents of the bag will be copied
 282
 283 This function will return a Bag from the PKCS12 structure.
 284
 285 After the last Bag has been read
 286 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}  will be returned.
 287
 288 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 289 negative error value.
 290 @end deftypefun
 291
 292 @subheading gnutls_pkcs12_import
 293 @anchor{gnutls_pkcs12_import}
 294 @deftypefun {int} {gnutls_pkcs12_import} (gnutls_pkcs12_t @var{pkcs12}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
 295 @var{pkcs12}: The structure to store the parsed PKCS12.
 296
 297 @var{data}: The DER or PEM encoded PKCS12.
 298
 299 @var{format}: One of DER or PEM
 300
 301 @var{flags}: an ORed sequence of gnutls_privkey_pkcs8_flags
 302
 303 This function will convert the given DER or PEM encoded PKCS12
 304 to the native gnutls_pkcs12_t format. The output will be stored in 'pkcs12'.
 305
 306 If the PKCS12 is PEM encoded it should have a header of "PKCS12".
 307
 308 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 309 negative error value.
 310 @end deftypefun
 311
 312 @subheading gnutls_pkcs12_init
 313 @anchor{gnutls_pkcs12_init}
 314 @deftypefun {int} {gnutls_pkcs12_init} (gnutls_pkcs12_t * @var{pkcs12})
 315 @var{pkcs12}: The structure to be initialized
 316
 317 This function will initialize a PKCS12 structure. PKCS12 structures
 318 usually contain lists of X.509 Certificates and X.509 Certificate
 319 revocation lists.
 320
 321 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 322 negative error value.
 323 @end deftypefun
 324
 325 @subheading gnutls_pkcs12_set_bag
 326 @anchor{gnutls_pkcs12_set_bag}
 327 @deftypefun {int} {gnutls_pkcs12_set_bag} (gnutls_pkcs12_t @var{pkcs12}, gnutls_pkcs12_bag_t @var{bag})
 328 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
 329
 330 @var{bag}: An initialized bag
 331
 332 This function will insert a Bag into the PKCS12 structure.
 333
 334 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 335 negative error value.
 336 @end deftypefun
 337
 338 @subheading gnutls_pkcs12_simple_parse
 339 @anchor{gnutls_pkcs12_simple_parse}
 340 @deftypefun {int} {gnutls_pkcs12_simple_parse} (gnutls_pkcs12_t @var{p12}, const char * @var{password}, gnutls_x509_privkey_t * @var{key}, gnutls_x509_crt_t ** @var{chain}, unsigned int * @var{chain_len}, gnutls_x509_crt_t ** @var{extra_certs}, unsigned int * @var{extra_certs_len}, gnutls_x509_crl_t * @var{crl}, unsigned int @var{flags})
 341 @var{p12}: the PKCS12 blob.
 342
 343 @var{password}: optional password used to decrypt PKCS12 blob, bags and keys.
 344
 345 @var{key}: a structure to store the parsed private key.
 346
 347 @var{chain}: the corresponding to key certificate chain (may be @code{NULL} )
 348
 349 @var{chain_len}: will be updated with the number of additional (may be @code{NULL} )
 350
 351 @var{extra_certs}: optional pointer to receive an array of additional
 352 certificates found in the PKCS12 blob (may be @code{NULL} ).
 353
 354 @var{extra_certs_len}: will be updated with the number of additional
 355 certs (may be @code{NULL} ).
 356
 357 @var{crl}: an optional structure to store the parsed CRL (may be @code{NULL} ).
 358
 359 @var{flags}: should be zero or one of GNUTLS_PKCS12_SP_*
 360
 361 This function parses a PKCS12 blob in  @code{p12blob} and extracts the
 362 private key, the corresponding certificate chain, and any additional
 363 certificates and a CRL.
 364
 365 The  @code{extra_certs_ret} and  @code{extra_certs_len} parameters are optional
 366 and both may be set to @code{NULL} . If either is non-@code{NULL} , then both must
 367 be set.
 368
 369 Encrypted PKCS12 bags and PKCS8 private keys are supported.  However,
 370 only password based security, and the same password for all
 371 operations, are supported.
 372
 373 A PKCS12 file may contain many keys and/or certificates, and there
 374 is no way to identify which key/certificate pair you want.  You
 375 should make sure the PKCS12 file only contain one key/certificate
 376 pair and/or one CRL.
 377
 378 It is believed that the limitations of this function are acceptable
 379 for common usage, and that any more flexibility would introduce
 380 complexity that would make it harder to use this functionality at
 381 all.
 382
 383 If the provided structure has encrypted fields but no password
 384 is provided then this function returns @code{GNUTLS_E_DECRYPTION_FAILED} .
 385
 386 Note that normally the chain constructed does not include self signed
 387 certificates, to comply with TLS' requirements. If, however, the flag
 388 @code{GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED}  is specified then
 389 self signed certificates will be included in the chain.
 390
 391 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 392 negative error value.
 393
 394 @strong{Since:} 3.1
 395 @end deftypefun
 396
 397 @subheading gnutls_pkcs12_verify_mac
 398 @anchor{gnutls_pkcs12_verify_mac}
 399 @deftypefun {int} {gnutls_pkcs12_verify_mac} (gnutls_pkcs12_t @var{pkcs12}, const char * @var{pass})
 400 @var{pkcs12}: should contain a gnutls_pkcs12_t structure
 401
 402 @var{pass}: The password for the MAC
 403
 404 This function will verify the MAC for the PKCS12 structure.
 405
 406 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 407 negative error value.
 408 @end deftypefun
 409