path: root/doc/pkcs12-api.texi

@subheading gnutls_pkcs12_bag_decrypt
@anchor{gnutls_pkcs12_bag_decrypt}
@deftypefun {int} {gnutls_pkcs12_bag_decrypt} (gnutls_pkcs12_bag_t @var{bag}, const char * @var{pass})
@var{bag}: The bag

@var{pass}: The password used for encryption, must be ASCII.

This function will decrypt the given encrypted bag and return 0 on
success.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned,
otherwise a negative error code is returned.
@end deftypefun

@subheading gnutls_pkcs12_bag_deinit
@anchor{gnutls_pkcs12_bag_deinit}
@deftypefun {void} {gnutls_pkcs12_bag_deinit} (gnutls_pkcs12_bag_t @var{bag})
@var{bag}: A pointer to the type to be initialized

This function will deinitialize a PKCS12 Bag structure.
@end deftypefun

@subheading gnutls_pkcs12_bag_enc_info
@anchor{gnutls_pkcs12_bag_enc_info}
@deftypefun {int} {gnutls_pkcs12_bag_enc_info} (gnutls_pkcs12_bag_t @var{bag}, unsigned int * @var{schema}, unsigned int * @var{cipher}, void * @var{salt}, unsigned int * @var{salt_size}, unsigned int * @var{iter_count}, char ** @var{oid})
@var{bag}: The bag

@var{schema}: indicate the schema as one of @code{gnutls_pkcs_encrypt_flags_t} 

@var{cipher}: the cipher used as @code{gnutls_cipher_algorithm_t} 

@var{salt}: PBKDF2 salt (if non-NULL then  @code{salt_size} initially holds its size)

@var{salt_size}: PBKDF2 salt size

@var{iter_count}: PBKDF2 iteration count

@var{oid}: if non-NULL it will contain an allocated null-terminated variable with the OID

This function will provide information on the encryption algorithms used
in an encrypted bag. If the structure algorithms
are unknown the code @code{GNUTLS_E_UNKNOWN_CIPHER_TYPE}  will be returned,
and only  @code{oid} , will be set. That is,  @code{oid} will be set on encrypted bags
whether supported or not. It must be deinitialized using @code{gnutls_free()} .
The other variables are only set on supported structures.

@strong{Returns:} @code{GNUTLS_E_INVALID_REQUEST}  if the provided bag isn't encrypted,
@code{GNUTLS_E_UNKNOWN_CIPHER_TYPE}  if the structure's encryption isn't supported, or
another negative error code in case of a failure. Zero on success.
@end deftypefun

@subheading gnutls_pkcs12_bag_encrypt
@anchor{gnutls_pkcs12_bag_encrypt}
@deftypefun {int} {gnutls_pkcs12_bag_encrypt} (gnutls_pkcs12_bag_t @var{bag}, const char * @var{pass}, unsigned int @var{flags})
@var{bag}: The bag

@var{pass}: The password used for encryption, must be ASCII

@var{flags}: should be one of @code{gnutls_pkcs_encrypt_flags_t}  elements bitwise or'd

This function will encrypt the given bag.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned,
otherwise a negative error code is returned.
@end deftypefun

@subheading gnutls_pkcs12_bag_get_count
@anchor{gnutls_pkcs12_bag_get_count}
@deftypefun {int} {gnutls_pkcs12_bag_get_count} (gnutls_pkcs12_bag_t @var{bag})
@var{bag}: The bag

This function will return the number of the elements within the bag.

@strong{Returns:} Number of elements in bag, or an negative error code on
error.
@end deftypefun

@subheading gnutls_pkcs12_bag_get_data
@anchor{gnutls_pkcs12_bag_get_data}
@deftypefun {int} {gnutls_pkcs12_bag_get_data} (gnutls_pkcs12_bag_t @var{bag}, unsigned @var{indx}, gnutls_datum_t * @var{data})
@var{bag}: The bag

@var{indx}: The element of the bag to get the data from

@var{data}: where the bag's data will be. Should be treated as constant.

This function will return the bag's data. The data is a constant
that is stored into the bag.  Should not be accessed after the bag
is deleted.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_bag_get_friendly_name
@anchor{gnutls_pkcs12_bag_get_friendly_name}
@deftypefun {int} {gnutls_pkcs12_bag_get_friendly_name} (gnutls_pkcs12_bag_t @var{bag}, unsigned @var{indx}, char ** @var{name})
@var{bag}: The bag

@var{indx}: The bag's element to add the id

@var{name}: will hold a pointer to the name (to be treated as const)

This function will return the friendly name, of the specified bag
element.  The key ID is usually used to distinguish the local
private key and the certificate pair.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value. or a negative error code on error.
@end deftypefun

@subheading gnutls_pkcs12_bag_get_key_id
@anchor{gnutls_pkcs12_bag_get_key_id}
@deftypefun {int} {gnutls_pkcs12_bag_get_key_id} (gnutls_pkcs12_bag_t @var{bag}, unsigned @var{indx}, gnutls_datum_t * @var{id})
@var{bag}: The bag

@var{indx}: The bag's element to add the id

@var{id}: where the ID will be copied (to be treated as const)

This function will return the key ID, of the specified bag element.
The key ID is usually used to distinguish the local private key and
the certificate pair.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value. or a negative error code on error.
@end deftypefun

@subheading gnutls_pkcs12_bag_get_type
@anchor{gnutls_pkcs12_bag_get_type}
@deftypefun {int} {gnutls_pkcs12_bag_get_type} (gnutls_pkcs12_bag_t @var{bag}, unsigned @var{indx})
@var{bag}: The bag

@var{indx}: The element of the bag to get the type

This function will return the bag's type.

@strong{Returns:} On error a negative error value or one of the @code{gnutls_pkcs12_bag_type_t}  enumerations.
@end deftypefun

@subheading gnutls_pkcs12_bag_init
@anchor{gnutls_pkcs12_bag_init}
@deftypefun {int} {gnutls_pkcs12_bag_init} (gnutls_pkcs12_bag_t * @var{bag})
@var{bag}: A pointer to the type to be initialized

This function will initialize a PKCS12 bag structure. PKCS12 Bags
usually contain private keys, lists of X.509 Certificates and X.509
Certificate revocation lists.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_bag_set_crl
@anchor{gnutls_pkcs12_bag_set_crl}
@deftypefun {int} {gnutls_pkcs12_bag_set_crl} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_crl_t @var{crl})
@var{bag}: The bag

@var{crl}: the CRL to be copied.

This function will insert the given CRL into the
bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()} .

@strong{Returns:} the index of the added bag on success, or a negative error code
on failure.
@end deftypefun

@subheading gnutls_pkcs12_bag_set_crt
@anchor{gnutls_pkcs12_bag_set_crt}
@deftypefun {int} {gnutls_pkcs12_bag_set_crt} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_crt_t @var{crt})
@var{bag}: The bag

@var{crt}: the certificate to be copied.

This function will insert the given certificate into the
bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()} .

@strong{Returns:} the index of the added bag on success, or a negative
value on failure.
@end deftypefun

@subheading gnutls_pkcs12_bag_set_data
@anchor{gnutls_pkcs12_bag_set_data}
@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})
@var{bag}: The bag

@var{type}: The data's type

@var{data}: the data to be copied.

This function will insert the given data of the given type into
the bag.

@strong{Returns:} the index of the added bag on success, or a negative
value on error.
@end deftypefun

@subheading gnutls_pkcs12_bag_set_friendly_name
@anchor{gnutls_pkcs12_bag_set_friendly_name}
@deftypefun {int} {gnutls_pkcs12_bag_set_friendly_name} (gnutls_pkcs12_bag_t @var{bag}, unsigned @var{indx}, const char * @var{name})
@var{bag}: The bag

@var{indx}: The bag's element to add the id

@var{name}: the name

This function will add the given key friendly name, to the
specified, by the index, bag element. The name will be encoded as
a 'Friendly name' bag attribute, which is usually used to set a
user name to the local private key and the certificate pair.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value. or a negative error code on error.
@end deftypefun

@subheading gnutls_pkcs12_bag_set_key_id
@anchor{gnutls_pkcs12_bag_set_key_id}
@deftypefun {int} {gnutls_pkcs12_bag_set_key_id} (gnutls_pkcs12_bag_t @var{bag}, unsigned @var{indx}, const gnutls_datum_t * @var{id})
@var{bag}: The bag

@var{indx}: The bag's element to add the id

@var{id}: the ID

This function will add the given key ID, to the specified, by the
index, bag element. The key ID will be encoded as a 'Local key
identifier' bag attribute, which is usually used to distinguish
the local private key and the certificate pair.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value. or a negative error code on error.
@end deftypefun

@subheading gnutls_pkcs12_bag_set_privkey
@anchor{gnutls_pkcs12_bag_set_privkey}
@deftypefun {int} {gnutls_pkcs12_bag_set_privkey} (gnutls_pkcs12_bag_t @var{bag}, gnutls_x509_privkey_t @var{privkey}, const char * @var{password}, unsigned @var{flags})
@var{bag}: The bag

@var{privkey}: the private key to be copied.

@var{password}: the password to protect the key with (may be @code{NULL} )

@var{flags}: should be one of @code{gnutls_pkcs_encrypt_flags_t}  elements bitwise or'd

This function will insert the given private key into the
bag. This is just a wrapper over @code{gnutls_pkcs12_bag_set_data()} .

@strong{Returns:} the index of the added bag on success, or a negative
value on failure.
@end deftypefun

@subheading gnutls_pkcs12_deinit
@anchor{gnutls_pkcs12_deinit}
@deftypefun {void} {gnutls_pkcs12_deinit} (gnutls_pkcs12_t @var{pkcs12})
@var{pkcs12}: The type to be initialized

This function will deinitialize a PKCS12 type.
@end deftypefun

@subheading gnutls_pkcs12_export
@anchor{gnutls_pkcs12_export}
@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})
@var{pkcs12}: A pkcs12 type

@var{format}: the format of output params. One of PEM or DER.

@var{output_data}: will contain a structure PEM or DER encoded

@var{output_data_size}: holds the size of output_data (and will be
replaced by the actual size of parameters)

This function will export the pkcs12 structure to DER or PEM format.

If the buffer provided is not long enough to hold the output, then
*output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER
will be returned.

If the structure is PEM encoded, it will have a header
of "BEGIN PKCS12".

@strong{Returns:} In case of failure a negative error code will be
returned, and 0 on success.
@end deftypefun

@subheading gnutls_pkcs12_export2
@anchor{gnutls_pkcs12_export2}
@deftypefun {int} {gnutls_pkcs12_export2} (gnutls_pkcs12_t @var{pkcs12}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
@var{pkcs12}: A pkcs12 type

@var{format}: the format of output params. One of PEM or DER.

@var{out}: will contain a structure PEM or DER encoded

This function will export the pkcs12 structure to DER or PEM format.

The output buffer is allocated using @code{gnutls_malloc()} .

If the structure is PEM encoded, it will have a header
of "BEGIN PKCS12".

@strong{Returns:} In case of failure a negative error code will be
returned, and 0 on success.

@strong{Since:} 3.1.3
@end deftypefun

@subheading gnutls_pkcs12_generate_mac
@anchor{gnutls_pkcs12_generate_mac}
@deftypefun {int} {gnutls_pkcs12_generate_mac} (gnutls_pkcs12_t @var{pkcs12}, const char * @var{pass})
@var{pkcs12}: A pkcs12 type

@var{pass}: The password for the MAC

This function will generate a MAC for the PKCS12 structure.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_generate_mac2
@anchor{gnutls_pkcs12_generate_mac2}
@deftypefun {int} {gnutls_pkcs12_generate_mac2} (gnutls_pkcs12_t @var{pkcs12}, gnutls_mac_algorithm_t @var{mac}, const char * @var{pass})
@var{pkcs12}: A pkcs12 type

@var{mac}: the MAC algorithm to use

@var{pass}: The password for the MAC

This function will generate a MAC for the PKCS12 structure.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_get_bag
@anchor{gnutls_pkcs12_get_bag}
@deftypefun {int} {gnutls_pkcs12_get_bag} (gnutls_pkcs12_t @var{pkcs12}, int @var{indx}, gnutls_pkcs12_bag_t @var{bag})
@var{pkcs12}: A pkcs12 type

@var{indx}: contains the index of the bag to extract

@var{bag}: An initialized bag, where the contents of the bag will be copied

This function will return a Bag from the PKCS12 structure.

After the last Bag has been read
@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}  will be returned.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_import
@anchor{gnutls_pkcs12_import}
@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})
@var{pkcs12}: The data to store the parsed PKCS12.

@var{data}: The DER or PEM encoded PKCS12.

@var{format}: One of DER or PEM

@var{flags}: an ORed sequence of gnutls_privkey_pkcs8_flags

This function will convert the given DER or PEM encoded PKCS12
to the native gnutls_pkcs12_t format. The output will be stored in 'pkcs12'.

If the PKCS12 is PEM encoded it should have a header of "PKCS12".

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_init
@anchor{gnutls_pkcs12_init}
@deftypefun {int} {gnutls_pkcs12_init} (gnutls_pkcs12_t * @var{pkcs12})
@var{pkcs12}: A pointer to the type to be initialized

This function will initialize a PKCS12 type. PKCS12 structures
usually contain lists of X.509 Certificates and X.509 Certificate
revocation lists.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_mac_info
@anchor{gnutls_pkcs12_mac_info}
@deftypefun {int} {gnutls_pkcs12_mac_info} (gnutls_pkcs12_t @var{pkcs12}, unsigned int * @var{mac}, void * @var{salt}, unsigned int * @var{salt_size}, unsigned int * @var{iter_count}, char ** @var{oid})
@var{pkcs12}: A pkcs12 type

@var{mac}: the MAC algorithm used as @code{gnutls_mac_algorithm_t} 

@var{salt}: the salt used for string to key (if non-NULL then  @code{salt_size} initially holds its size)

@var{salt_size}: string to key salt size

@var{iter_count}: string to key iteration count

@var{oid}: if non-NULL it will contain an allocated null-terminated variable with the OID

This function will provide information on the MAC algorithm used
in a PKCS @code{12}  structure. If the structure algorithms
are unknown the code @code{GNUTLS_E_UNKNOWN_HASH_ALGORITHM}  will be returned,
and only  @code{oid} , will be set. That is,  @code{oid} will be set on structures
with a MAC whether supported or not. It must be deinitialized using @code{gnutls_free()} .
The other variables are only set on supported structures.

@strong{Returns:} @code{GNUTLS_E_INVALID_REQUEST}  if the provided structure doesn't contain a MAC,
@code{GNUTLS_E_UNKNOWN_HASH_ALGORITHM}  if the structure's MAC isn't supported, or
another negative error code in case of a failure. Zero on success.
@end deftypefun

@subheading gnutls_pkcs12_set_bag
@anchor{gnutls_pkcs12_set_bag}
@deftypefun {int} {gnutls_pkcs12_set_bag} (gnutls_pkcs12_t @var{pkcs12}, gnutls_pkcs12_bag_t @var{bag})
@var{pkcs12}: should contain a gnutls_pkcs12_t type

@var{bag}: An initialized bag

This function will insert a Bag into the PKCS12 structure.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_pkcs12_simple_parse
@anchor{gnutls_pkcs12_simple_parse}
@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})
@var{p12}: A pkcs12 type

@var{password}: optional password used to decrypt the structure, bags and keys.

@var{key}: a structure to store the parsed private key.

@var{chain}: the corresponding to key certificate chain (may be @code{NULL} )

@var{chain_len}: will be updated with the number of additional (may be @code{NULL} )

@var{extra_certs}: optional pointer to receive an array of additional
certificates found in the PKCS12 structure (may be @code{NULL} ).

@var{extra_certs_len}: will be updated with the number of additional
certs (may be @code{NULL} ).

@var{crl}: an optional structure to store the parsed CRL (may be @code{NULL} ).

@var{flags}: should be zero or one of GNUTLS_PKCS12_SP_*

This function parses a PKCS12 structure in  @code{pkcs12} and extracts the
private key, the corresponding certificate chain, any additional
certificates and a CRL. The structures in  @code{key} ,  @code{chain}  @code{crl} , and  @code{extra_certs} must not be initialized.

The  @code{extra_certs} and  @code{extra_certs_len} parameters are optional
and both may be set to @code{NULL} . If either is non-@code{NULL} , then both must
be set. The value for  @code{extra_certs} is allocated
using @code{gnutls_malloc()} .

Encrypted PKCS12 bags and PKCS8 private keys are supported, but
only with password based security and the same password for all
operations.

Note that a PKCS12 structure may contain many keys and/or certificates,
and there is no way to identify which key/certificate pair you want.
For this reason this function is useful for PKCS12 files that contain 
only one key/certificate pair and/or one CRL.

If the provided structure has encrypted fields but no password
is provided then this function returns @code{GNUTLS_E_DECRYPTION_FAILED} .

Note that normally the chain constructed does not include self signed
certificates, to comply with TLS' requirements. If, however, the flag 
@code{GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED}  is specified then
self signed certificates will be included in the chain.

Prior to using this function the PKCS @code{12}  structure integrity must
be verified using @code{gnutls_pkcs12_verify_mac()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_pkcs12_verify_mac
@anchor{gnutls_pkcs12_verify_mac}
@deftypefun {int} {gnutls_pkcs12_verify_mac} (gnutls_pkcs12_t @var{pkcs12}, const char * @var{pass})
@var{pkcs12}: should contain a gnutls_pkcs12_t type

@var{pass}: The password for the MAC

This function will verify the MAC for the PKCS12 structure.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun