This is gnutls.info, produced by makeinfo version 4.9 from gnutls.texi. This manual is last updated 23 April 2009 for version 2.6.6 of GNU TLS. Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". INFO-DIR-SECTION GNU Libraries START-INFO-DIR-ENTRY * libgnutls: (gnutls). A Transport Layer Security Library. END-INFO-DIR-ENTRY INFO-DIR-SECTION Network Applications START-INFO-DIR-ENTRY * GnuTLS: (gnutls). Package for Transport Layer Security. * certtool: (gnutls)Invoking certtool. Manipulate certificates and keys. * gnutls-serv: (gnutls)Invoking gnutls-serv. GNU TLS test server. * gnutls-cli: (gnutls)Invoking gnutls-cli. GNU TLS test client. * gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug. GNU TLS debug client. * psktool: (gnutls)Invoking psktool. Simple TLS-Pre-Shared-Keys manager. * srptool: (gnutls)Invoking srptool. Simple SRP password tool. END-INFO-DIR-ENTRY  File: gnutls.info, Node: X.509 certificate functions, Next: GnuTLS-extra functions, Prev: Core functions, Up: Function reference 9.2 X.509 Certificate Functions =============================== The following functions are to be used for X.509 certificate handling. Their prototypes lie in `gnutls/x509.h'. gnutls_pkcs12_bag_decrypt ------------------------- -- Function: int gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t BAG, const char * PASS) BAG: The bag PASS: The password used for encryption. This can only be ASCII. This function will decrypt the given encrypted bag and return 0 on success. gnutls_pkcs12_bag_deinit ------------------------ -- Function: void gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t BAG) BAG: The structure to be initialized This function will deinitialize a PKCS12 Bag structure. gnutls_pkcs12_bag_encrypt ------------------------- -- Function: int gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t BAG, const char * PASS, unsigned int FLAGS) BAG: The bag PASS: The password used for encryption. This can only be ASCII. FLAGS: should be one of gnutls_pkcs_encrypt_flags_t elements bitwise or'd This function will encrypt the given bag and return 0 on success. gnutls_pkcs12_bag_get_count --------------------------- -- Function: int gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t BAG) BAG: The bag This function will return the number of the elements withing the bag. gnutls_pkcs12_bag_get_data -------------------------- -- Function: int gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t BAG, int INDX, gnutls_datum_t * DATA) BAG: The bag INDX: The element of the bag to get the data from 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. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative error code on error. gnutls_pkcs12_bag_get_friendly_name ----------------------------------- -- Function: int gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t BAG, int INDX, char ** NAME) BAG: The bag INDX: The bag's element to add the id 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. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. or a negative value on error. gnutls_pkcs12_bag_get_key_id ---------------------------- -- Function: int gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t BAG, int INDX, gnutls_datum_t * ID) BAG: The bag INDX: The bag's element to add the id 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. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. or a negative value on error. gnutls_pkcs12_bag_get_type -------------------------- -- Function: gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t BAG, int INDX) BAG: The bag INDX: The element of the bag to get the type This function will return the bag's type. One of the gnutls_pkcs12_bag_type_t enumerations. gnutls_pkcs12_bag_init ---------------------- -- Function: int gnutls_pkcs12_bag_init (gnutls_pkcs12_bag_t * BAG) BAG: The structure 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. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs12_bag_set_crl ------------------------- -- Function: int gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t BAG, gnutls_x509_crl_t CRL) BAG: The bag CRL: the CRL to be copied. This function will insert the given CRL into the bag. This is just a wrapper over `gnutls_pkcs12_bag_set_data()'. *Returns:* the index of the added bag on success, or a negative value on failure. gnutls_pkcs12_bag_set_crt ------------------------- -- Function: int gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t BAG, gnutls_x509_crt_t CRT) BAG: The bag CRT: the certificate to be copied. This function will insert the given certificate into the bag. This is just a wrapper over `gnutls_pkcs12_bag_set_data()'. *Returns:* the index of the added bag on success, or a negative value on failure. gnutls_pkcs12_bag_set_data -------------------------- -- Function: int gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t BAG, gnutls_pkcs12_bag_type_t TYPE, const gnutls_datum_t * DATA) BAG: The bag TYPE: The data's type DATA: the data to be copied. This function will insert the given data of the given type into the bag. *Returns:* the index of the added bag on success, or a negative value on error. gnutls_pkcs12_bag_set_friendly_name ----------------------------------- -- Function: int gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t BAG, int INDX, const char * NAME) BAG: The bag INDX: The bag's element to add the id 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. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. or a negative value on error. gnutls_pkcs12_bag_set_key_id ---------------------------- -- Function: int gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t BAG, int INDX, const gnutls_datum_t * ID) BAG: The bag INDX: The bag's element to add the id 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. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. or a negative value on error. gnutls_pkcs12_deinit -------------------- -- Function: void gnutls_pkcs12_deinit (gnutls_pkcs12_t PKCS12) PKCS12: The structure to be initialized This function will deinitialize a PKCS12 structure. gnutls_pkcs12_export -------------------- -- Function: int gnutls_pkcs12_export (gnutls_pkcs12_t PKCS12, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) PKCS12: Holds the pkcs12 structure FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a structure PEM or DER encoded 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". *Return value:* In case of failure a negative value will be returned, and 0 on success. gnutls_pkcs12_generate_mac -------------------------- -- Function: int gnutls_pkcs12_generate_mac (gnutls_pkcs12_t PKCS12, const char * PASS) PKCS12: should contain a gnutls_pkcs12_t structure PASS: The password for the MAC This function will generate a MAC for the PKCS12 structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs12_get_bag --------------------- -- Function: int gnutls_pkcs12_get_bag (gnutls_pkcs12_t PKCS12, int INDX, gnutls_pkcs12_bag_t BAG) PKCS12: should contain a gnutls_pkcs12_t structure INDX: contains the index of the bag to extract BAG: An initialized bag, where the contents of the bag will be copied This function will return a Bag from the PKCS12 structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. After the last Bag has been read GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_pkcs12_import -------------------- -- Function: int gnutls_pkcs12_import (gnutls_pkcs12_t PKCS12, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS) PKCS12: The structure to store the parsed PKCS12. DATA: The DER or PEM encoded PKCS12. FORMAT: One of DER or PEM 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". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs12_init ------------------ -- Function: int gnutls_pkcs12_init (gnutls_pkcs12_t * PKCS12) PKCS12: The structure to be initialized This function will initialize a PKCS12 structure. PKCS12 structures usually contain lists of X.509 Certificates and X.509 Certificate revocation lists. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs12_set_bag --------------------- -- Function: int gnutls_pkcs12_set_bag (gnutls_pkcs12_t PKCS12, gnutls_pkcs12_bag_t BAG) PKCS12: should contain a gnutls_pkcs12_t structure BAG: An initialized bag This function will insert a Bag into the PKCS12 structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs12_verify_mac ------------------------ -- Function: int gnutls_pkcs12_verify_mac (gnutls_pkcs12_t PKCS12, const char * PASS) PKCS12: should contain a gnutls_pkcs12_t structure PASS: The password for the MAC This function will verify the MAC for the PKCS12 structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_deinit ------------------- -- Function: void gnutls_pkcs7_deinit (gnutls_pkcs7_t PKCS7) PKCS7: The structure to be initialized This function will deinitialize a PKCS7 structure. gnutls_pkcs7_delete_crl ----------------------- -- Function: int gnutls_pkcs7_delete_crl (gnutls_pkcs7_t PKCS7, int INDX) INDX: the index of the crl to delete This function will delete a crl from a PKCS7 or RFC2630 crl set. Index starts from 0. Returns 0 on success. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_delete_crt ----------------------- -- Function: int gnutls_pkcs7_delete_crt (gnutls_pkcs7_t PKCS7, int INDX) INDX: the index of the certificate to delete This function will delete a certificate from a PKCS7 or RFC2630 certificate set. Index starts from 0. Returns 0 on success. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_export ------------------- -- Function: int gnutls_pkcs7_export (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) PKCS7: Holds the pkcs7 structure FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a structure PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the pkcs7 structure to DER or PEM format. If the buffer provided is not long enough to hold the output, then *`output_data_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. If the structure is PEM encoded, it will have a header of "BEGIN PKCS7". *Return value:* In case of failure a negative value will be returned, and 0 on success. gnutls_pkcs7_get_crl_count -------------------------- -- Function: int gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t PKCS7) This function will return the number of certifcates in the PKCS7 or RFC2630 crl set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_get_crl_raw ------------------------ -- Function: int gnutls_pkcs7_get_crl_raw (gnutls_pkcs7_t PKCS7, int INDX, void * CRL, size_t * CRL_SIZE) INDX: contains the index of the crl to extract CRL: the contents of the crl will be copied there (may be null) CRL_SIZE: should hold the size of the crl This function will return a crl of the PKCS7 or RFC2630 crl set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. If the provided buffer is not long enough, then `crl_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' is returned. After the last crl has been read `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned. gnutls_pkcs7_get_crt_count -------------------------- -- Function: int gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t PKCS7) This function will return the number of certifcates in the PKCS7 or RFC2630 certificate set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_get_crt_raw ------------------------ -- Function: int gnutls_pkcs7_get_crt_raw (gnutls_pkcs7_t PKCS7, int INDX, void * CERTIFICATE, size_t * CERTIFICATE_SIZE) INDX: contains the index of the certificate to extract CERTIFICATE: the contents of the certificate will be copied there (may be null) CERTIFICATE_SIZE: should hold the size of the certificate This function will return a certificate of the PKCS7 or RFC2630 certificate set. After the last certificate has been read `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. If the provided buffer is not long enough, then `certificate_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' is returned. gnutls_pkcs7_import ------------------- -- Function: int gnutls_pkcs7_import (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT) PKCS7: The structure to store the parsed PKCS7. DATA: The DER or PEM encoded PKCS7. FORMAT: One of DER or PEM This function will convert the given DER or PEM encoded PKCS7 to the native `gnutls_pkcs7_t' format. The output will be stored in 'pkcs7'. If the PKCS7 is PEM encoded it should have a header of "PKCS7". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_init ----------------- -- Function: int gnutls_pkcs7_init (gnutls_pkcs7_t * PKCS7) PKCS7: The structure to be initialized This function will initialize a PKCS7 structure. PKCS7 structures usually contain lists of X.509 Certificates and X.509 Certificate revocation lists. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_set_crl_raw ------------------------ -- Function: int gnutls_pkcs7_set_crl_raw (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * CRL) CRL: the DER encoded crl to be added This function will add a crl to the PKCS7 or RFC2630 crl set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_set_crl -------------------- -- Function: int gnutls_pkcs7_set_crl (gnutls_pkcs7_t PKCS7, gnutls_x509_crl_t CRL) CRL: the DER encoded crl to be added This function will add a parsed CRL to the PKCS7 or RFC2630 crl set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_set_crt_raw ------------------------ -- Function: int gnutls_pkcs7_set_crt_raw (gnutls_pkcs7_t PKCS7, const gnutls_datum_t * CRT) CRT: the DER encoded certificate to be added This function will add a certificate to the PKCS7 or RFC2630 certificate set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_pkcs7_set_crt -------------------- -- Function: int gnutls_pkcs7_set_crt (gnutls_pkcs7_t PKCS7, gnutls_x509_crt_t CRT) CRT: the certificate to be copied. This function will add a parsed certificate to the PKCS7 or RFC2630 certificate set. This is a wrapper function over `gnutls_pkcs7_set_crt_raw()' . *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_check_issuer ---------------------------- -- Function: int gnutls_x509_crl_check_issuer (gnutls_x509_crl_t CERT, gnutls_x509_crt_t ISSUER) ISSUER: is the certificate of a possible issuer This function will check if the given CRL was issued by the given issuer certificate. It will return true (1) if the given CRL was issued by the given issuer, and false (0) if not. A negative value is returned in case of an error. gnutls_x509_crl_deinit ---------------------- -- Function: void gnutls_x509_crl_deinit (gnutls_x509_crl_t CRL) CRL: The structure to be initialized This function will deinitialize a CRL structure. gnutls_x509_crl_export ---------------------- -- Function: int gnutls_x509_crl_export (gnutls_x509_crl_t CRL, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) CRL: Holds the revocation list FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a private key PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the revocation list to DER or PEM format. If the buffer provided is not long enough to hold the output, then ¤GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. If the structure is PEM encoded, it will have a header of "BEGIN X509 CRL". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. and a negative value on failure. gnutls_x509_crl_get_crt_count ----------------------------- -- Function: int gnutls_x509_crl_get_crt_count (gnutls_x509_crl_t CRL) CRL: should contain a `gnutls_x509_crl_t' structure This function will return the number of revoked certificates in the given CRL. *Returns:* number of certificates, a negative value on failure. gnutls_x509_crl_get_crt_serial ------------------------------ -- Function: int gnutls_x509_crl_get_crt_serial (gnutls_x509_crl_t CRL, int INDX, unsigned char * SERIAL, size_t * SERIAL_SIZE, time_t * T) CRL: should contain a `gnutls_x509_crl_t' structure INDX: the index of the certificate to extract (starting from 0) SERIAL: where the serial number will be copied SERIAL_SIZE: initially holds the size of serial T: if non null, will hold the time this certificate was revoked This function will retrieve the serial number of the specified, by the index, revoked certificate. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. and a negative value on error. gnutls_x509_crl_get_dn_oid -------------------------- -- Function: int gnutls_x509_crl_get_dn_oid (gnutls_x509_crl_t CRL, int INDX, void * OID, size_t * SIZEOF_OID) CRL: should contain a gnutls_x509_crl_t structure INDX: Specifies which DN OID to send. Use zero to get the first one. OID: a pointer to a structure to hold the name (may be null) SIZEOF_OID: initially holds the size of 'oid' This function will extract the requested OID of the name of the CRL issuer, specified by the given index. If oid is null then only the size will be filled. *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is not long enough, and in that case the sizeof_oid will be updated with the required size. On success 0 is returned. gnutls_x509_crl_get_issuer_dn_by_oid ------------------------------------ -- Function: int gnutls_x509_crl_get_issuer_dn_by_oid (gnutls_x509_crl_t CRL, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF) CRL: should contain a gnutls_x509_crl_t structure OID: holds an Object Identified in null terminated string INDX: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one. RAW_FLAG: If non zero returns the raw DER data of the DN part. BUF: a pointer to a structure to hold the peer's name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will extract the part of the name of the CRL issuer specified by the given OID. The output will be encoded as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data. Some helper macros with popular OIDs can be found in gnutls/x509.h If raw flag is zero, this function will only return known OIDs as text. Other OIDs will be DER encoded, as described in RFC2253 - in hex format with a '\#' prefix. You can check about known OIDs using `gnutls_x509_dn_oid_known()'. If buf is null then only the size will be filled. *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is not long enough, and in that case the sizeof_buf will be updated with the required size, and 0 on success. gnutls_x509_crl_get_issuer_dn ----------------------------- -- Function: int gnutls_x509_crl_get_issuer_dn (const gnutls_x509_crl_t CRL, char * BUF, size_t * SIZEOF_BUF) CRL: should contain a gnutls_x509_crl_t structure BUF: a pointer to a structure to hold the peer's name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will copy the name of the CRL issuer in the provided buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data. If buf is `NULL' then only the size will be filled. *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is not long enough, and in that case the sizeof_buf will be updated with the required size, and 0 on success. gnutls_x509_crl_get_next_update ------------------------------- -- Function: time_t gnutls_x509_crl_get_next_update (gnutls_x509_crl_t CRL) CRL: should contain a `gnutls_x509_crl_t' structure This function will return the time the next CRL will be issued. This field is optional in a CRL so it might be normal to get an error instead. *Returns:* when the next CRL will be issued, or (time_t)-1 on error. gnutls_x509_crl_get_signature_algorithm --------------------------------------- -- Function: int gnutls_x509_crl_get_signature_algorithm (gnutls_x509_crl_t CRL) CRL: should contain a `gnutls_x509_crl_t' structure This function will return a value of the `gnutls_sign_algorithm_t' enumeration that is the signature algorithm. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_get_signature ----------------------------- -- Function: int gnutls_x509_crl_get_signature (gnutls_x509_crl_t CRL, char * SIG, size_t * SIZEOF_SIG) CRL: should contain a gnutls_x509_crl_t structure SIG: a pointer where the signature part will be copied (may be null). SIZEOF_SIG: initially holds the size of `sig' This function will extract the signature field of a CRL. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. and a negative value on error. gnutls_x509_crl_get_this_update ------------------------------- -- Function: time_t gnutls_x509_crl_get_this_update (gnutls_x509_crl_t CRL) CRL: should contain a `gnutls_x509_crl_t' structure This function will return the time this CRL was issued. *Returns:* when the CRL was issued, or (time_t)-1 on error. gnutls_x509_crl_get_version --------------------------- -- Function: int gnutls_x509_crl_get_version (gnutls_x509_crl_t CRL) CRL: should contain a `gnutls_x509_crl_t' structure This function will return the version of the specified CRL. *Returns:* The version number, or a negative value on error. gnutls_x509_crl_import ---------------------- -- Function: int gnutls_x509_crl_import (gnutls_x509_crl_t CRL, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT) CRL: The structure to store the parsed CRL. DATA: The DER or PEM encoded CRL. FORMAT: One of DER or PEM This function will convert the given DER or PEM encoded CRL to the native `gnutls_x509_crl_t' format. The output will be stored in 'crl'. If the CRL is PEM encoded it should have a header of "X509 CRL". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_init -------------------- -- Function: int gnutls_x509_crl_init (gnutls_x509_crl_t * CRL) CRL: The structure to be initialized This function will initialize a CRL structure. CRL stands for Certificate Revocation List. A revocation list usually contains lists of certificate serial numbers that have been revoked by an Authority. The revocation lists are always signed with the authority's private key. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_print --------------------- -- Function: int gnutls_x509_crl_print (gnutls_x509_crl_t CRL, gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t * OUT) CRL: The structure to be printed FORMAT: Indicate the format to use OUT: Newly allocated datum with zero terminated string. This function will pretty print a X.509 certificate revocation list, suitable for display to a human. The output `out' needs to be deallocate using `gnutls_free()'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_set_crt_serial ------------------------------ -- Function: int gnutls_x509_crl_set_crt_serial (gnutls_x509_crl_t CRL, const void * SERIAL, size_t SERIAL_SIZE, time_t REVOCATION_TIME) CRL: should contain a gnutls_x509_crl_t structure SERIAL: The revoked certificate's serial number SERIAL_SIZE: Holds the size of the serial field. REVOCATION_TIME: The time this certificate was revoked This function will set a revoked certificate's serial number to the CRL. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_set_crt ----------------------- -- Function: int gnutls_x509_crl_set_crt (gnutls_x509_crl_t CRL, gnutls_x509_crt_t CRT, time_t REVOCATION_TIME) CRL: should contain a gnutls_x509_crl_t structure CRT: a certificate of type `gnutls_x509_crt_t' with the revoked certificate REVOCATION_TIME: The time this certificate was revoked This function will set a revoked certificate's serial number to the CRL. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_set_next_update ------------------------------- -- Function: int gnutls_x509_crl_set_next_update (gnutls_x509_crl_t CRL, time_t EXP_TIME) CRL: should contain a gnutls_x509_crl_t structure EXP_TIME: The actual time This function will set the time this CRL will be updated. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_set_this_update ------------------------------- -- Function: int gnutls_x509_crl_set_this_update (gnutls_x509_crl_t CRL, time_t ACT_TIME) CRL: should contain a gnutls_x509_crl_t structure ACT_TIME: The actual time This function will set the time this CRL was issued. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_set_version --------------------------- -- Function: int gnutls_x509_crl_set_version (gnutls_x509_crl_t CRL, unsigned int VERSION) CRL: should contain a gnutls_x509_crl_t structure VERSION: holds the version number. For CRLv1 crls must be 1. This function will set the version of the CRL. This must be one for CRL version 1, and so on. The CRLs generated by gnutls should have a version number of 2. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_sign2 --------------------- -- Function: int gnutls_x509_crl_sign2 (gnutls_x509_crl_t CRL, gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS) CRL: should contain a gnutls_x509_crl_t structure ISSUER: is the certificate of the certificate issuer ISSUER_KEY: holds the issuer's private key DIG: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing. FLAGS: must be 0 This function will sign the CRL with the issuer's private key, and will copy the issuer's information into the CRL. This must be the last step in a certificate CRL since all the previously set parameters are now signed. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_sign -------------------- -- Function: int gnutls_x509_crl_sign (gnutls_x509_crl_t CRL, gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY) CRL: should contain a gnutls_x509_crl_t structure ISSUER: is the certificate of the certificate issuer ISSUER_KEY: holds the issuer's private key This function is the same a `gnutls_x509_crl_sign2()' with no flags, and SHA1 as the hash algorithm. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crl_verify ---------------------- -- Function: int gnutls_x509_crl_verify (gnutls_x509_crl_t CRL, const gnutls_x509_crt_t * CA_LIST, int CA_LIST_LENGTH, unsigned int FLAGS, unsigned int * VERIFY) CRL: is the crl to be verified CA_LIST: is a certificate list that is considered to be trusted one CA_LIST_LENGTH: holds the number of CA certificates in CA_list FLAGS: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. VERIFY: will hold the crl verification output. This function will try to verify the given crl and return its status. See `gnutls_x509_crt_list_verify()' for a detailed description of return values. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_crq_deinit ---------------------- -- Function: void gnutls_x509_crq_deinit (gnutls_x509_crq_t CRQ) CRQ: The structure to be initialized This function will deinitialize a CRL structure. gnutls_x509_crq_export ---------------------- -- Function: int gnutls_x509_crq_export (gnutls_x509_crq_t CRQ, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) CRQ: Holds the request FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a certificate request PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the certificate request to a PKCS10 If the buffer provided is not long enough to hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned and *output_data_size will be updated. If the structure is PEM encoded, it will have a header of "BEGIN NEW CERTIFICATE REQUEST". *Return value:* In case of failure a negative value will be returned, and 0 on success. gnutls_x509_crq_get_attribute_by_oid ------------------------------------ -- Function: int gnutls_x509_crq_get_attribute_by_oid (gnutls_x509_crq_t CRQ, const char * OID, int INDX, void * BUF, size_t * SIZEOF_BUF) CRQ: should contain a gnutls_x509_crq_t structure OID: holds an Object Identified in null terminated string INDX: In case multiple same OIDs exist in the attribute list, this specifies which to send. Use zero to get the first one. BUF: a pointer to a structure to hold the attribute data (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will return the attribute in the certificate request specified by the given Object ID. The attribute will be DER encoded. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_get_challenge_password -------------------------------------- -- Function: int gnutls_x509_crq_get_challenge_password (gnutls_x509_crq_t CRQ, char * PASS, size_t * SIZEOF_PASS) CRQ: should contain a gnutls_x509_crq_t structure PASS: will hold a null terminated password SIZEOF_PASS: Initially holds the size of `pass'. This function will return the challenge password in the request. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_get_dn_by_oid ----------------------------- -- Function: int gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t CRQ, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF) CRQ: should contain a gnutls_x509_crq_t structure OID: holds an Object Identified in null terminated string INDX: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one. RAW_FLAG: If non zero returns the raw DER data of the DN part. BUF: a pointer to a structure to hold the name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will extract the part of the name of the Certificate request subject, specified by the given OID. The output will be encoded as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data. Some helper macros with popular OIDs can be found in gnutls/x509.h If raw flag is zero, this function will only return known OIDs as text. Other OIDs will be DER encoded, as described in RFC2253 - in hex format with a '\#' prefix. You can check about known OIDs using `gnutls_x509_dn_oid_known()'. If `buf' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crq_get_dn_oid -------------------------- -- Function: int gnutls_x509_crq_get_dn_oid (gnutls_x509_crq_t CRQ, int INDX, void * OID, size_t * SIZEOF_OID) CRQ: should contain a gnutls_x509_crq_t structure INDX: Specifies which DN OID to send. Use zero to get the first one. OID: a pointer to a structure to hold the name (may be null) SIZEOF_OID: initially holds the size of `oid' This function will extract the requested OID of the name of the Certificate request subject, specified by the given index. If oid is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_oid will be updated with the required size. On success 0 is returned. gnutls_x509_crq_get_dn ---------------------- -- Function: int gnutls_x509_crq_get_dn (gnutls_x509_crq_t CRQ, char * BUF, size_t * SIZEOF_BUF) CRQ: should contain a gnutls_x509_crq_t structure BUF: a pointer to a structure to hold the name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will copy the name of the Certificate request subject in the provided buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data. If `buf' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crq_get_pk_algorithm -------------------------------- -- Function: int gnutls_x509_crq_get_pk_algorithm (gnutls_x509_crq_t CRQ, unsigned int * BITS) CRQ: should contain a gnutls_x509_crq_t structure BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of a PKCS \`10' certificate request. If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. gnutls_x509_crq_get_version --------------------------- -- Function: int gnutls_x509_crq_get_version (gnutls_x509_crq_t CRQ) CRQ: should contain a gnutls_x509_crq_t structure This function will return the version of the specified Certificate request. *Returns:* version of certificate request, or a negative value on error. gnutls_x509_crq_import ---------------------- -- Function: int gnutls_x509_crq_import (gnutls_x509_crq_t CRQ, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT) CRQ: The structure to store the parsed certificate request. DATA: The DER or PEM encoded certificate. FORMAT: One of DER or PEM This function will convert the given DER or PEM encoded Certificate to the native gnutls_x509_crq_t format. The output will be stored in `cert'. If the Certificate is PEM encoded it should have a header of "NEW CERTIFICATE REQUEST". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_init -------------------- -- Function: int gnutls_x509_crq_init (gnutls_x509_crq_t * CRQ) CRQ: The structure to be initialized This function will initialize a PKCS10 certificate request structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_set_attribute_by_oid ------------------------------------ -- Function: int gnutls_x509_crq_set_attribute_by_oid (gnutls_x509_crq_t CRQ, const char * OID, void * BUF, size_t SIZEOF_BUF) CRQ: should contain a gnutls_x509_crq_t structure OID: holds an Object Identified in null terminated string BUF: a pointer to a structure that holds the attribute data SIZEOF_BUF: holds the size of `buf' This function will set the attribute in the certificate request specified by the given Object ID. The attribute must be be DER encoded. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_set_challenge_password -------------------------------------- -- Function: int gnutls_x509_crq_set_challenge_password (gnutls_x509_crq_t CRQ, const char * PASS) CRQ: should contain a gnutls_x509_crq_t structure PASS: holds a null terminated password This function will set a challenge password to be used when revoking the request. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_set_dn_by_oid ----------------------------- -- Function: int gnutls_x509_crq_set_dn_by_oid (gnutls_x509_crq_t CRQ, const char * OID, unsigned int RAW_FLAG, const void * DATA, unsigned int SIZEOF_DATA) CRQ: should contain a gnutls_x509_crq_t structure OID: holds an Object Identifier in a null terminated string RAW_FLAG: must be 0, or 1 if the data are DER encoded DATA: a pointer to the input data SIZEOF_DATA: holds the size of `data' This function will set the part of the name of the Certificate request subject, specified by the given OID. The input string should be ASCII or UTF-8 encoded. Some helper macros with popular OIDs can be found in gnutls/x509.h With this function you can only set the known OIDs. You can test for known OIDs using `gnutls_x509_dn_oid_known()'. For OIDs that are not known (by gnutls) you should properly DER encode your data, and call this function with raw_flag set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_set_key_rsa_raw ------------------------------- -- Function: int gnutls_x509_crq_set_key_rsa_raw (gnutls_x509_crq_t CRQ, const gnutls_datum_t * M, const gnutls_datum_t * E) CRQ: should contain a `gnutls_x509_crq_t' structure M: holds the modulus E: holds the public exponent This function will set the public parameters from the given private key to the request. Only RSA keys are currently supported. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.6.0 gnutls_x509_crq_set_key ----------------------- -- Function: int gnutls_x509_crq_set_key (gnutls_x509_crq_t CRQ, gnutls_x509_privkey_t KEY) CRQ: should contain a gnutls_x509_crq_t structure KEY: holds a private key This function will set the public parameters from the given private key to the request. Only RSA keys are currently supported. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_set_version --------------------------- -- Function: int gnutls_x509_crq_set_version (gnutls_x509_crq_t CRQ, unsigned int VERSION) CRQ: should contain a gnutls_x509_crq_t structure VERSION: holds the version number. For v1 Requests must be 1. This function will set the version of the certificate request. For version 1 requests this must be one. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crq_sign2 --------------------- -- Function: int gnutls_x509_crq_sign2 (gnutls_x509_crq_t CRQ, gnutls_x509_privkey_t KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS) CRQ: should contain a `gnutls_x509_crq_t' structure KEY: holds a private key DIG: The message digest to use, `GNUTLS_DIG_SHA1' is the safe choice unless you know what you're doing. FLAGS: must be 0 This function will sign the certificate request with a private key. This must be the same key as the one used in `gnutls_x509_crt_set_key()' since a certificate request is self signed. This must be the last step in a certificate request generation since all the previously set parameters are now signed. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. `GNUTLS_E_ASN1_VALUE_NOT_FOUND' is returned if you didn't set all information in the certificate request (e.g., the version using `gnutls_x509_crq_set_version()'). gnutls_x509_crq_sign -------------------- -- Function: int gnutls_x509_crq_sign (gnutls_x509_crq_t CRQ, gnutls_x509_privkey_t KEY) CRQ: should contain a gnutls_x509_crq_t structure KEY: holds a private key This function is the same a `gnutls_x509_crq_sign2()' with no flags, and SHA1 as the hash algorithm. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_check_hostname ------------------------------ -- Function: int gnutls_x509_crt_check_hostname (gnutls_x509_crt_t CERT, const char * HOSTNAME) CERT: should contain an gnutls_x509_crt_t structure HOSTNAME: A null terminated string that contains a DNS name This function will check if the given certificate's subject matches the given hostname. This is a basic implementation of the matching described in RFC2818 (HTTPS), which takes into account wildcards, and the DNSName/IPAddress subject alternative name PKIX extension. *Returns:* non zero for a successful match, and zero on failure. gnutls_x509_crt_check_issuer ---------------------------- -- Function: int gnutls_x509_crt_check_issuer (gnutls_x509_crt_t CERT, gnutls_x509_crt_t ISSUER) CERT: is the certificate to be checked ISSUER: is the certificate of a possible issuer This function will check if the given certificate was issued by the given issuer. It will return true (1) if the given certificate is issued by the given issuer, and false (0) if not. A negative value is returned in case of an error. gnutls_x509_crt_check_revocation -------------------------------- -- Function: int gnutls_x509_crt_check_revocation (gnutls_x509_crt_t CERT, const gnutls_x509_crl_t * CRL_LIST, int CRL_LIST_LENGTH) CERT: should contain a `gnutls_x509_crt_t' structure CRL_LIST: should contain a list of gnutls_x509_crl_t structures CRL_LIST_LENGTH: the length of the crl_list This function will return check if the given certificate is revoked. It is assumed that the CRLs have been verified before. *Returns:* 0 if the certificate is NOT revoked, and 1 if it is. A negative value is returned on error. gnutls_x509_crt_cpy_crl_dist_points ----------------------------------- -- Function: int gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t DST, gnutls_x509_crt_t SRC) DST: a certificate of type `gnutls_x509_crt_t' SRC: the certificate where the dist points will be copied from This function will copy the CRL distribution points certificate extension, from the source to the destination certificate. This may be useful to copy from a CA certificate to issued ones. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_deinit ---------------------- -- Function: void gnutls_x509_crt_deinit (gnutls_x509_crt_t CERT) CERT: The structure to be initialized This function will deinitialize a CRL structure. gnutls_x509_crt_export ---------------------- -- Function: int gnutls_x509_crt_export (gnutls_x509_crt_t CERT, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) CERT: Holds the certificate FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a certificate PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the certificate to DER or PEM format. If the buffer provided is not long enough to hold the output, then *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE". *Return value:* In case of failure a negative value will be returned, and 0 on success. gnutls_x509_crt_get_activation_time ----------------------------------- -- Function: time_t gnutls_x509_crt_get_activation_time (gnutls_x509_crt_t CERT) CERT: should contain a `gnutls_x509_crt_t' structure This function will return the time this Certificate was or will be activated. *Returns:* activation time, or (time_t)-1 on error. gnutls_x509_crt_get_authority_key_id ------------------------------------ -- Function: int gnutls_x509_crt_get_authority_key_id (gnutls_x509_crt_t CERT, void * RET, size_t * RET_SIZE, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure CRITICAL: will be non zero if the extension is marked as critical (may be null) This function will return the X.509v3 certificate authority's key identifier. This is obtained by the X.509 Authority Key identifier extension field (2.5.29.35). Note that this function only returns the keyIdentifier field of the extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_crt_get_basic_constraints ------------------------------------- -- Function: int gnutls_x509_crt_get_basic_constraints (gnutls_x509_crt_t CERT, unsigned int * CRITICAL, int * CA, int * PATHLEN) CERT: should contain a `gnutls_x509_crt_t' structure CRITICAL: will be non zero if the extension is marked as critical CA: pointer to output integer indicating CA status, may be NULL, value is 1 if the certificate CA flag is set, 0 otherwise. PATHLEN: pointer to output integer indicating path length (may be NULL), non-negative values indicate a present pathLenConstraint field and the actual value, -1 indicate that the field is absent. This function will read the certificate's basic constraints, and return the certificates CA status. It reads the basicConstraints X.509 extension (2.5.29.19). *Return value:* If the certificate is a CA a positive value will be returned, or zero if the certificate does not have CA flag set. A negative value may be returned in case of errors. If the certificate does not contain the basicConstraints extension GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_ca_status ----------------------------- -- Function: int gnutls_x509_crt_get_ca_status (gnutls_x509_crt_t CERT, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure CRITICAL: will be non zero if the extension is marked as critical This function will return certificates CA status, by reading the basicConstraints X.509 extension (2.5.29.19). If the certificate is a CA a positive value will be returned, or zero if the certificate does not have CA flag set. Use `gnutls_x509_crt_get_basic_constraints()' if you want to read the pathLenConstraint field too. A negative value may be returned in case of parsing error. If the certificate does not contain the basicConstraints extension GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_crl_dist_points ----------------------------------- -- Function: int gnutls_x509_crt_get_crl_dist_points (gnutls_x509_crt_t CERT, unsigned int SEQ, void * RET, size_t * RET_SIZE, unsigned int * REASON_FLAGS, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure SEQ: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.) RET: is the place where the distribution point will be copied to RET_SIZE: holds the size of ret. REASON_FLAGS: Revocation reasons flags. CRITICAL: will be non zero if the extension is marked as critical (may be null) This function will return the CRL distribution points (2.5.29.31), contained in the given certificate. `reason_flags' should be an ORed sequence of GNUTLS_CRL_REASON_UNUSED, GNUTLS_CRL_REASON_KEY_COMPROMISE, GNUTLS_CRL_REASON_CA_COMPROMISE, GNUTLS_CRL_REASON_AFFILIATION_CHANGED, GNUTLS_CRL_REASON_SUPERSEEDED, GNUTLS_CRL_REASON_CESSATION_OF_OPERATION, GNUTLS_CRL_REASON_CERTIFICATE_HOLD, GNUTLS_CRL_REASON_PRIVILEGE_WITHDRAWN, GNUTLS_CRL_REASON_AA_COMPROMISE, or zero for all possible reasons. This is specified in X509v3 Certificate Extensions. GNUTLS will return the distribution point type, or a negative error code on error. *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' and updates &`ret_size' if &`ret_size' is not enough to hold the distribution point, or the type of the distribution point if everything was ok. The type is one of the enumerated `gnutls_x509_subject_alt_name_t'. If the certificate does not have an Alternative name with the specified sequence number then `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned. gnutls_x509_crt_get_dn_by_oid ----------------------------- -- Function: int gnutls_x509_crt_get_dn_by_oid (gnutls_x509_crt_t CERT, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF) CERT: should contain a `gnutls_x509_crt_t' structure OID: holds an Object Identified in null terminated string INDX: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one. RAW_FLAG: If non zero returns the raw DER data of the DN part. BUF: a pointer where the DN part will be copied (may be null). SIZEOF_BUF: initially holds the size of `buf' This function will extract the part of the name of the Certificate subject specified by the given OID. The output, if the raw flag is not used, will be encoded as described in RFC2253. Thus a string that is ASCII or UTF-8 encoded, depending on the certificate data. Some helper macros with popular OIDs can be found in gnutls/x509.h If raw flag is zero, this function will only return known OIDs as text. Other OIDs will be DER encoded, as described in RFC2253 - in hex format with a '\#' prefix. You can check about known OIDs using `gnutls_x509_dn_oid_known()'. If `buf' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_dn_oid -------------------------- -- Function: int gnutls_x509_crt_get_dn_oid (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * SIZEOF_OID) CERT: should contain a `gnutls_x509_crt_t' structure INDX: This specifies which OID to return. Use zero to get the first one. OID: a pointer to a buffer to hold the OID (may be null) SIZEOF_OID: initially holds the size of `oid' This function will extract the OIDs of the name of the Certificate subject specified by the given index. If oid is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_oid will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_dn ---------------------- -- Function: int gnutls_x509_crt_get_dn (gnutls_x509_crt_t CERT, char * BUF, size_t * SIZEOF_BUF) CERT: should contain a `gnutls_x509_crt_t' structure BUF: a pointer to a structure to hold the name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will copy the name of the Certificate in the provided buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data. If `buf' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_expiration_time ----------------------------------- -- Function: time_t gnutls_x509_crt_get_expiration_time (gnutls_x509_crt_t CERT) CERT: should contain a `gnutls_x509_crt_t' structure This function will return the time this Certificate was or will be expired. *Returns:* expiration time, or (time_t)-1 on error. gnutls_x509_crt_get_extension_by_oid ------------------------------------ -- Function: int gnutls_x509_crt_get_extension_by_oid (gnutls_x509_crt_t CERT, const char * OID, int INDX, void * BUF, size_t * SIZEOF_BUF, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure OID: holds an Object Identified in null terminated string INDX: In case multiple same OIDs exist in the extensions, this specifies which to send. Use zero to get the first one. BUF: a pointer to a structure to hold the name (may be null) SIZEOF_BUF: initially holds the size of `buf' CRITICAL: will be non zero if the extension is marked as critical This function will return the extension specified by the OID in the certificate. The extensions will be returned as binary data DER encoded, in the provided buffer. A negative value may be returned in case of parsing error. If the certificate does not contain the specified extension GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_extension_data ---------------------------------- -- Function: int gnutls_x509_crt_get_extension_data (gnutls_x509_crt_t CERT, int INDX, void * DATA, size_t * SIZEOF_DATA) CERT: should contain a `gnutls_x509_crt_t' structure INDX: Specifies which extension OID to send. Use zero to get the first one. DATA: a pointer to a structure to hold the data (may be null) SIZEOF_DATA: initially holds the size of `oid' This function will return the requested extension data in the certificate. The extension data will be stored as a string in the provided buffer. Use `gnutls_x509_crt_get_extension_info()' to extract the OID and critical flag. Use `gnutls_x509_crt_get_extension_by_oid()' instead, if you want to get data indexed by the extension OID rather than sequence. Return 0 on success. A negative value may be returned in case of parsing error. If you have reached the last extension available GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_extension_info ---------------------------------- -- Function: int gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * SIZEOF_OID, int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure INDX: Specifies which extension OID to send. Use zero to get the first one. OID: a pointer to a structure to hold the OID SIZEOF_OID: initially holds the maximum size of `oid', on return holds actual size of `oid'. CRITICAL: output variable with critical flag, may be NULL. This function will return the requested extension OID in the certificate, and the critical flag for it. The extension OID will be stored as a string in the provided buffer. Use `gnutls_x509_crt_get_extension_data()' to extract the data. If the buffer provided is not long enough to hold the output, then *`sizeof_oid' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. Return 0 on success. A negative value may be returned in case of parsing error. If you have reached the last extension available GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_extension_oid --------------------------------- -- Function: int gnutls_x509_crt_get_extension_oid (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * SIZEOF_OID) CERT: should contain a `gnutls_x509_crt_t' structure INDX: Specifies which extension OID to send. Use zero to get the first one. OID: a pointer to a structure to hold the OID (may be null) SIZEOF_OID: initially holds the size of `oid' This function will return the requested extension OID in the certificate. The extension OID will be stored as a string in the provided buffer. A negative value may be returned in case of parsing error. If your have reached the last extension available GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_fingerprint ------------------------------- -- Function: int gnutls_x509_crt_get_fingerprint (gnutls_x509_crt_t CERT, gnutls_digest_algorithm_t ALGO, void * BUF, size_t * SIZEOF_BUF) CERT: should contain a `gnutls_x509_crt_t' structure ALGO: is a digest algorithm BUF: a pointer to a structure to hold the fingerprint (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will calculate and copy the certificate's fingerprint in the provided buffer. If the buffer is null then only the size will be filled. *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_issuer_dn_by_oid ------------------------------------ -- Function: int gnutls_x509_crt_get_issuer_dn_by_oid (gnutls_x509_crt_t CERT, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF) CERT: should contain a `gnutls_x509_crt_t' structure OID: holds an Object Identified in null terminated string INDX: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one. RAW_FLAG: If non zero returns the raw DER data of the DN part. BUF: a pointer to a structure to hold the name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will extract the part of the name of the Certificate issuer specified by the given OID. The output, if the raw flag is not used, will be encoded as described in RFC2253. Thus a string that is ASCII or UTF-8 encoded, depending on the certificate data. Some helper macros with popular OIDs can be found in gnutls/x509.h If raw flag is zero, this function will only return known OIDs as text. Other OIDs will be DER encoded, as described in RFC2253 - in hex format with a '\#' prefix. You can check about known OIDs using `gnutls_x509_dn_oid_known()'. If `buf' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_issuer_dn_oid --------------------------------- -- Function: int gnutls_x509_crt_get_issuer_dn_oid (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * SIZEOF_OID) CERT: should contain a `gnutls_x509_crt_t' structure INDX: This specifies which OID to return. Use zero to get the first one. OID: a pointer to a buffer to hold the OID (may be null) SIZEOF_OID: initially holds the size of `oid' This function will extract the OIDs of the name of the Certificate issuer specified by the given index. If `oid' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_oid will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_issuer_dn ----------------------------- -- Function: int gnutls_x509_crt_get_issuer_dn (gnutls_x509_crt_t CERT, char * BUF, size_t * SIZEOF_BUF) CERT: should contain a `gnutls_x509_crt_t' structure BUF: a pointer to a structure to hold the name (may be null) SIZEOF_BUF: initially holds the size of `buf' This function will copy the name of the Certificate issuer in the provided buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data. If `buf' is null then only the size will be filled. *Returns:* GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not long enough, and in that case the *sizeof_buf will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_issuer -------------------------- -- Function: int gnutls_x509_crt_get_issuer (gnutls_x509_crt_t CERT, gnutls_x509_dn_t * DN) CERT: should contain a `gnutls_x509_crt_t' structure DN: output variable with pointer to opaque DN Return the Certificate's Issuer DN as an opaque data type. You may use `gnutls_x509_dn_get_rdn_ava()' to decode the DN. Note that `dn' should be treated as constant. Because points into the `cert' object, you may not deallocate `cert' and continue to access `dn'. *Returns:* Returns 0 on success, or an error code. gnutls_x509_crt_get_key_id -------------------------- -- Function: int gnutls_x509_crt_get_key_id (gnutls_x509_crt_t CRT, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) CRT: Holds the certificate FLAGS: should be 0 for now OUTPUT_DATA: will contain the key ID OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will return a unique ID the depends on the public key parameters. This ID can be used in checking whether a certificate corresponds to the given private key. If the buffer provided is not long enough to hold the output, then *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. The output will normally be a SHA-1 hash output, which is 20 bytes. *Return value:* In case of failure a negative value will be returned, and 0 on success. gnutls_x509_crt_get_key_purpose_oid ----------------------------------- -- Function: int gnutls_x509_crt_get_key_purpose_oid (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * SIZEOF_OID, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure INDX: This specifies which OID to return. Use zero to get the first one. OID: a pointer to a buffer to hold the OID (may be null) SIZEOF_OID: initially holds the size of `oid' This function will extract the key purpose OIDs of the Certificate specified by the given index. These are stored in the Extended Key Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for human readable names. If `oid' is null then only the size will be filled. *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the provided buffer is not long enough, and in that case the *sizeof_oid will be updated with the required size. On success 0 is returned. gnutls_x509_crt_get_key_usage ----------------------------- -- Function: int gnutls_x509_crt_get_key_usage (gnutls_x509_crt_t CERT, unsigned int * KEY_USAGE, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure KEY_USAGE: where the key usage bits will be stored CRITICAL: will be non zero if the extension is marked as critical This function will return certificate's key usage, by reading the keyUsage X.509 extension (2.5.29.15). The key usage value will *ORed values of the:* `GNUTLS_KEY_DIGITAL_SIGNATURE', `GNUTLS_KEY_NON_REPUDIATION', `GNUTLS_KEY_KEY_ENCIPHERMENT', `GNUTLS_KEY_DATA_ENCIPHERMENT', `GNUTLS_KEY_KEY_AGREEMENT', `GNUTLS_KEY_KEY_CERT_SIGN', `GNUTLS_KEY_CRL_SIGN', `GNUTLS_KEY_ENCIPHER_ONLY', `GNUTLS_KEY_DECIPHER_ONLY'. *Returns:* the certificate key usage, or a negative value in case of parsing error. If the certificate does not contain the keyUsage extension `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned. gnutls_x509_crt_get_pk_algorithm -------------------------------- -- Function: int gnutls_x509_crt_get_pk_algorithm (gnutls_x509_crt_t CERT, unsigned int * BITS) CERT: should contain a `gnutls_x509_crt_t' structure BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of an X.509 certificate. If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. gnutls_x509_crt_get_pk_dsa_raw ------------------------------ -- Function: int gnutls_x509_crt_get_pk_dsa_raw (gnutls_x509_crt_t CRT, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y) CRT: Holds the certificate P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y This function will export the DSA public key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. gnutls_x509_crt_get_pk_rsa_raw ------------------------------ -- Function: int gnutls_x509_crt_get_pk_rsa_raw (gnutls_x509_crt_t CRT, gnutls_datum_t * M, gnutls_datum_t * E) CRT: Holds the certificate M: will hold the modulus E: will hold the public exponent This function will export the RSA public key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. gnutls_x509_crt_get_proxy ------------------------- -- Function: int gnutls_x509_crt_get_proxy (gnutls_x509_crt_t CERT, unsigned int * CRITICAL, int * PATHLEN, char ** POLICYLANGUAGE, char ** POLICY, size_t * SIZEOF_POLICY) CERT: should contain a `gnutls_x509_crt_t' structure CRITICAL: will be non zero if the extension is marked as critical PATHLEN: pointer to output integer indicating path length (may be NULL), non-negative values indicate a present pCPathLenConstraint field and the actual value, -1 indicate that the field is absent. This function will read the certificate's basic constraints, and return the certificates CA status. It reads the basicConstraints X.509 extension (2.5.29.19). *Return value:* If the certificate is a CA a positive value will be returned, or zero if the certificate does not have CA flag set. A negative value may be returned in case of errors. If the certificate does not contain the basicConstraints extension GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. gnutls_x509_crt_get_raw_dn -------------------------- -- Function: int gnutls_x509_crt_get_raw_dn (gnutls_x509_crt_t CERT, gnutls_datum_t * START) CERT: should contain a `gnutls_x509_crt_t' structure START: will hold the starting point of the DN This function will return a pointer to the DER encoded DN structure and the length. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. or a negative value on error. gnutls_x509_crt_get_raw_issuer_dn --------------------------------- -- Function: int gnutls_x509_crt_get_raw_issuer_dn (gnutls_x509_crt_t CERT, gnutls_datum_t * START) CERT: should contain a `gnutls_x509_crt_t' structure START: will hold the starting point of the DN This function will return a pointer to the DER encoded DN structure and the length. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.or a negative value on error. gnutls_x509_crt_get_serial -------------------------- -- Function: int gnutls_x509_crt_get_serial (gnutls_x509_crt_t CERT, void * RESULT, size_t * RESULT_SIZE) CERT: should contain a `gnutls_x509_crt_t' structure RESULT: The place where the serial number will be copied RESULT_SIZE: Holds the size of the result field. This function will return the X.509 certificate's serial number. This is obtained by the X509 Certificate serialNumber field. Serial is not always a 32 or 64bit number. Some CAs use large serial numbers, thus it may be wise to handle it as something opaque. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_crt_get_signature_algorithm --------------------------------------- -- Function: int gnutls_x509_crt_get_signature_algorithm (gnutls_x509_crt_t CERT) CERT: should contain a `gnutls_x509_crt_t' structure This function will return a value of the `gnutls_sign_algorithm_t' enumeration that is the signature algorithm. *Returns:* a `gnutls_sign_algorithm_t' value, or a negative value on error. gnutls_x509_crt_get_signature ----------------------------- -- Function: int gnutls_x509_crt_get_signature (gnutls_x509_crt_t CERT, char * SIG, size_t * SIZEOF_SIG) CERT: should contain a `gnutls_x509_crt_t' structure SIG: a pointer where the signature part will be copied (may be null). SIZEOF_SIG: initially holds the size of `sig' This function will extract the signature field of a certificate. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. and a negative value on error. gnutls_x509_crt_get_subject_alt_name2 ------------------------------------- -- Function: int gnutls_x509_crt_get_subject_alt_name2 (gnutls_x509_crt_t CERT, unsigned int SEQ, void * RET, size_t * RET_SIZE, unsigned int * RET_TYPE, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure SEQ: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) RET: is the place where the alternative name will be copied to RET_SIZE: holds the size of ret. RET_TYPE: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). CRITICAL: will be non zero if the extension is marked as critical (may be null) This function will return the alternative names, contained in the given certificate. It is the same as `gnutls_x509_crt_get_subject_alt_name()' except for the fact that it will return the type of the alternative name in `ret_type' even if the function fails for some reason (i.e. the buffer provided is not enough). The return values are the same as with `gnutls_x509_crt_get_subject_alt_name()'. gnutls_x509_crt_get_subject_alt_name ------------------------------------ -- Function: int gnutls_x509_crt_get_subject_alt_name (gnutls_x509_crt_t CERT, unsigned int SEQ, void * RET, size_t * RET_SIZE, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure SEQ: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) RET: is the place where the alternative name will be copied to RET_SIZE: holds the size of ret. CRITICAL: will be non zero if the extension is marked as critical (may be null) This function will return the alternative names, contained in the given certificate. This is specified in X509v3 Certificate Extensions. GNUTLS will return the Alternative name (2.5.29.17), or a negative error code. When the SAN type is otherName, it will extract the data in the otherName's value field, and `GNUTLS_SAN_OTHERNAME' is returned. You may use `gnutls_x509_crt_get_subject_alt_othername_oid()' to get the corresponding OID and the "virtual" SAN types (e.g., `GNUTLS_SAN_OTHERNAME_XMPP'). If an otherName OID is known, the data will be decoded. Otherwise the returned data will be DER encoded, and you will have to decode it yourself. Currently, only the RFC 3920 id-on-xmppAddr SAN is recognized. *Returns:* the alternative subject name type on success, one of the enumerated `gnutls_x509_subject_alt_name_t'. It will return `GNUTLS_E_SHORT_MEMORY_BUFFER' if `ret_size' is not large enough to hold the value. In that case `ret_size' will be updated with the required size. If the certificate does not have an Alternative name with the specified sequence number then `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned. gnutls_x509_crt_get_subject_alt_othername_oid --------------------------------------------- -- Function: int gnutls_x509_crt_get_subject_alt_othername_oid (gnutls_x509_crt_t CERT, unsigned int SEQ, void * RET, size_t * RET_SIZE) CERT: should contain a `gnutls_x509_crt_t' structure SEQ: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) RET: is the place where the otherName OID will be copied to RET_SIZE: holds the size of ret. This function will extract the type OID of an otherName Subject Alternative Name, contained in the given certificate, and return the type as an enumerated element. This function is only useful if `gnutls_x509_crt_get_subject_alt_name()' returned `GNUTLS_SAN_OTHERNAME'. *Returns:* the alternative subject name type on success, one of the enumerated gnutls_x509_subject_alt_name_t. For supported OIDs, it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types, e.g. `GNUTLS_SAN_OTHERNAME_XMPP', and `GNUTLS_SAN_OTHERNAME' for unknown OIDs. It will return `GNUTLS_E_SHORT_MEMORY_BUFFER' if `ret_size' is not large enough to hold the value. In that case `ret_size' will be updated with the required size. If the certificate does not have an Alternative name with the specified sequence number and with the otherName type then `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' is returned. gnutls_x509_crt_get_subject_key_id ---------------------------------- -- Function: int gnutls_x509_crt_get_subject_key_id (gnutls_x509_crt_t CERT, void * RET, size_t * RET_SIZE, unsigned int * CRITICAL) CERT: should contain a `gnutls_x509_crt_t' structure RET: The place where the identifier will be copied RET_SIZE: Holds the size of the result field. CRITICAL: will be non zero if the extension is marked as critical (may be null) This function will return the X.509v3 certificate's subject key identifier. This is obtained by the X.509 Subject Key identifier extension field (2.5.29.14). *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_crt_get_subject --------------------------- -- Function: int gnutls_x509_crt_get_subject (gnutls_x509_crt_t CERT, gnutls_x509_dn_t * DN) CERT: should contain a `gnutls_x509_crt_t' structure DN: output variable with pointer to opaque DN. Return the Certificate's Subject DN as an opaque data type. You may use `gnutls_x509_dn_get_rdn_ava()' to decode the DN. Note that `dn' should be treated as constant. Because points into the `cert' object, you may not deallocate `cert' and continue to access `dn'. *Returns:* Returns 0 on success, or an error code. gnutls_x509_crt_get_version --------------------------- -- Function: int gnutls_x509_crt_get_version (gnutls_x509_crt_t CERT) CERT: should contain a `gnutls_x509_crt_t' structure This function will return the version of the specified Certificate. *Returns:* version of certificate, or a negative value on error. gnutls_x509_crt_import ---------------------- -- Function: int gnutls_x509_crt_import (gnutls_x509_crt_t CERT, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT) CERT: The structure to store the parsed certificate. DATA: The DER or PEM encoded certificate. FORMAT: One of DER or PEM This function will convert the given DER or PEM encoded Certificate to the native gnutls_x509_crt_t format. The output will be stored in `cert'. If the Certificate is PEM encoded it should have a header of "X509 CERTIFICATE", or "CERTIFICATE". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_init -------------------- -- Function: int gnutls_x509_crt_init (gnutls_x509_crt_t * CERT) CERT: The structure to be initialized This function will initialize an X.509 certificate structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_list_import --------------------------- -- Function: int gnutls_x509_crt_list_import (gnutls_x509_crt_t * CERTS, unsigned int * CERT_MAX, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS) CERTS: The structures to store the parsed certificate. Must not be initialized. CERT_MAX: Initially must hold the maximum number of certs. It will be updated with the number of certs available. DATA: The PEM encoded certificate. FORMAT: One of DER or PEM. FLAGS: must be zero or an OR'd sequence of gnutls_certificate_import_flags. This function will convert the given PEM encoded certificate list to the native gnutls_x509_crt_t format. The output will be stored in `certs'. They will be automatically initialized. If the Certificate is PEM encoded it should have a header of "X509 CERTIFICATE", or "CERTIFICATE". *Returns:* the number of certificates read or a negative error value. gnutls_x509_crt_list_verify --------------------------- -- Function: int gnutls_x509_crt_list_verify (const gnutls_x509_crt_t * CERT_LIST, int CERT_LIST_LENGTH, const gnutls_x509_crt_t * CA_LIST, int CA_LIST_LENGTH, const gnutls_x509_crl_t * CRL_LIST, int CRL_LIST_LENGTH, unsigned int FLAGS, unsigned int * VERIFY) CERT_LIST: is the certificate list to be verified CERT_LIST_LENGTH: holds the number of certificate in cert_list CA_LIST: is the CA list which will be used in verification CA_LIST_LENGTH: holds the number of CA certificate in CA_list CRL_LIST: holds a list of CRLs. CRL_LIST_LENGTH: the length of CRL list. FLAGS: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. VERIFY: will hold the certificate verification output. This function will try to verify the given certificate list and return its status. If no flags are specified (0), this function will use the basicConstraints (2.5.29.19) PKIX extension. This means that only a certificate authority is allowed to sign a certificate. You must also check the peer's name in order to check if the verified certificate belongs to the actual peer. The certificate verification output will be put in `verify' and will be one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd. For a more detailed verification status use `gnutls_x509_crt_verify()' per list element. *GNUTLS_CERT_INVALID:* the certificate chain is not valid. *GNUTLS_CERT_REVOKED:* a certificate in the chain has been revoked. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_crt_print --------------------- -- Function: int gnutls_x509_crt_print (gnutls_x509_crt_t CERT, gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t * OUT) CERT: The structure to be printed FORMAT: Indicate the format to use OUT: Newly allocated datum with zero terminated string. This function will pretty print a X.509 certificate, suitable for display to a human. If the format is `GNUTLS_CRT_PRINT_FULL' then all fields of the certificate will be output, on multiple lines. The `GNUTLS_CRT_PRINT_ONELINE' format will generate one line with some selected fields, which is useful for logging purposes. The output `out' needs to be deallocate using `gnutls_free()'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_activation_time ----------------------------------- -- Function: int gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t CERT, time_t ACT_TIME) CERT: a certificate of type `gnutls_x509_crt_t' ACT_TIME: The actual time This function will set the time this Certificate was or will be activated. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_authority_key_id ------------------------------------ -- Function: int gnutls_x509_crt_set_authority_key_id (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE) CERT: a certificate of type `gnutls_x509_crt_t' ID: The key ID ID_SIZE: Holds the size of the serial field. This function will set the X.509 certificate's authority key ID extension. Only the keyIdentifier field can be set with this function. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_basic_constraints ------------------------------------- -- Function: int gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t CRT, unsigned int CA, int PATHLENCONSTRAINT) CRT: a certificate of type `gnutls_x509_crt_t' CA: true(1) or false(0). Depending on the Certificate authority status. PATHLENCONSTRAINT: non-negative values indicate maximum length of path, and negative values indicate that the pathLenConstraints field should not be present. This function will set the basicConstraints certificate extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_ca_status ----------------------------- -- Function: int gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t CRT, unsigned int CA) CRT: a certificate of type `gnutls_x509_crt_t' CA: true(1) or false(0). Depending on the Certificate authority status. This function will set the basicConstraints certificate extension. Use `gnutls_x509_crt_set_basic_constraints()' if you want to control the pathLenConstraint field too. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_crl_dist_points2 ------------------------------------ -- Function: int gnutls_x509_crt_set_crl_dist_points2 (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE, const void * DATA, unsigned int DATA_SIZE, unsigned int REASON_FLAGS) CRT: a certificate of type `gnutls_x509_crt_t' TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations DATA: The data to be set DATA_SIZE: The data size REASON_FLAGS: revocation reasons This function will set the CRL distribution points certificate extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.6.0 gnutls_x509_crt_set_crl_dist_points ----------------------------------- -- Function: int gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE, const void * DATA_STRING, unsigned int REASON_FLAGS) CRT: a certificate of type `gnutls_x509_crt_t' TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations DATA_STRING: The data to be set REASON_FLAGS: revocation reasons This function will set the CRL distribution points certificate extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_crq ----------------------- -- Function: int gnutls_x509_crt_set_crq (gnutls_x509_crt_t CRT, gnutls_x509_crq_t CRQ) CRT: a certificate of type `gnutls_x509_crt_t' CRQ: holds a certificate request This function will set the name and public parameters from the given certificate request to the certificate. Only RSA keys are currently supported. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_dn_by_oid ----------------------------- -- Function: int gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t CRT, const char * OID, unsigned int RAW_FLAG, const void * NAME, unsigned int SIZEOF_NAME) CRT: a certificate of type `gnutls_x509_crt_t' OID: holds an Object Identifier in a null terminated string RAW_FLAG: must be 0, or 1 if the data are DER encoded NAME: a pointer to the name SIZEOF_NAME: holds the size of `name' This function will set the part of the name of the Certificate subject, specified by the given OID. The input string should be ASCII or UTF-8 encoded. Some helper macros with popular OIDs can be found in gnutls/x509.h With this function you can only set the known OIDs. You can test for known OIDs using `gnutls_x509_dn_oid_known()'. For OIDs that are not known (by gnutls) you should properly DER encode your data, and call this function with `raw_flag' set. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_expiration_time ----------------------------------- -- Function: int gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t CERT, time_t EXP_TIME) CERT: a certificate of type `gnutls_x509_crt_t' EXP_TIME: The actual time This function will set the time this Certificate will expire. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_extension_by_oid ------------------------------------ -- Function: int gnutls_x509_crt_set_extension_by_oid (gnutls_x509_crt_t CRT, const char * OID, const void * BUF, size_t SIZEOF_BUF, unsigned int CRITICAL) CRT: a certificate of type `gnutls_x509_crt_t' OID: holds an Object Identified in null terminated string BUF: a pointer to a DER encoded data SIZEOF_BUF: holds the size of `buf' CRITICAL: should be non zero if the extension is to be marked as critical This function will set an the extension, by the specified OID, in the certificate. The extension data should be binary data DER encoded. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_crt_set_issuer_dn_by_oid ------------------------------------ -- Function: int gnutls_x509_crt_set_issuer_dn_by_oid (gnutls_x509_crt_t CRT, const char * OID, unsigned int RAW_FLAG, const void * NAME, unsigned int SIZEOF_NAME) CRT: a certificate of type `gnutls_x509_crt_t' OID: holds an Object Identifier in a null terminated string RAW_FLAG: must be 0, or 1 if the data are DER encoded NAME: a pointer to the name SIZEOF_NAME: holds the size of `name' This function will set the part of the name of the Certificate issuer, specified by the given OID. The input string should be ASCII or UTF-8 encoded. Some helper macros with popular OIDs can be found in gnutls/x509.h With this function you can only set the known OIDs. You can test for known OIDs using `gnutls_x509_dn_oid_known()'. For OIDs that are not known (by gnutls) you should properly DER encode your data, and call this function with `raw_flag' set. Normally you do not need to call this function, since the signing operation will copy the signer's name as the issuer of the certificate. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_key_purpose_oid ----------------------------------- -- Function: int gnutls_x509_crt_set_key_purpose_oid (gnutls_x509_crt_t CERT, const void * OID, unsigned int CRITICAL) CERT: a certificate of type `gnutls_x509_crt_t' OID: a pointer to a null terminated string that holds the OID CRITICAL: Whether this extension will be critical or not This function will set the key purpose OIDs of the Certificate. These are stored in the Extended Key Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for human readable names. Subsequent calls to this function will append OIDs to the OID list. On success 0 is returned. gnutls_x509_crt_set_key_usage ----------------------------- -- Function: int gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t CRT, unsigned int USAGE) CRT: a certificate of type `gnutls_x509_crt_t' USAGE: an ORed sequence of the GNUTLS_KEY_* elements. This function will set the keyUsage certificate extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_key ----------------------- -- Function: int gnutls_x509_crt_set_key (gnutls_x509_crt_t CRT, gnutls_x509_privkey_t KEY) CRT: a certificate of type `gnutls_x509_crt_t' KEY: holds a private key This function will set the public parameters from the given private key to the certificate. Only RSA keys are currently supported. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_proxy_dn ---------------------------- -- Function: int gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t CRT, gnutls_x509_crt_t EECRT, unsigned int RAW_FLAG, const void * NAME, unsigned int SIZEOF_NAME) CRT: a gnutls_x509_crt_t structure with the new proxy cert EECRT: the end entity certificate that will be issuing the proxy RAW_FLAG: must be 0, or 1 if the CN is DER encoded NAME: a pointer to the CN name, may be NULL (but MUST then be added later) SIZEOF_NAME: holds the size of `name' This function will set the subject in `crt' to the end entity's `eecrt' subject name, and add a single Common Name component `name' of size `sizeof_name'. This corresponds to the required proxy certificate naming style. Note that if `name' is `NULL', you MUST set it later by using `gnutls_x509_crt_set_dn_by_oid()' or similar. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_proxy ------------------------- -- Function: int gnutls_x509_crt_set_proxy (gnutls_x509_crt_t CRT, int PATHLENCONSTRAINT, const char * POLICYLANGUAGE, const char * POLICY, size_t SIZEOF_POLICY) CRT: a certificate of type `gnutls_x509_crt_t' PATHLENCONSTRAINT: non-negative values indicate maximum length of path, and negative values indicate that the pathLenConstraints field should not be present. POLICYLANGUAGE: OID describing the language of `policy'. POLICY: opaque byte array with policy language, can be `NULL' SIZEOF_POLICY: size of `policy'. This function will set the proxyCertInfo extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_serial -------------------------- -- Function: int gnutls_x509_crt_set_serial (gnutls_x509_crt_t CERT, const void * SERIAL, size_t SERIAL_SIZE) CERT: a certificate of type `gnutls_x509_crt_t' SERIAL: The serial number SERIAL_SIZE: Holds the size of the serial field. This function will set the X.509 certificate's serial number. Serial is not always a 32 or 64bit number. Some CAs use large serial numbers, thus it may be wise to handle it as something opaque. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_subject_alt_name ------------------------------------ -- Function: int gnutls_x509_crt_set_subject_alt_name (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE, const void * DATA, unsigned int DATA_SIZE, unsigned int FLAGS) CRT: a certificate of type `gnutls_x509_crt_t' TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations DATA: The data to be set DATA_SIZE: The size of data to be set FLAGS: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. This function will set the subject alternative name certificate extension. It can set the following types: &GNUTLS_SAN_DNSNAME: as a text string &GNUTLS_SAN_RFC822NAME: as a text string &GNUTLS_SAN_URI: as a text string &GNUTLS_SAN_IPADDRESS: as a binary IP address (4 or 16 bytes) Other values can be set as binary values with the proper DER encoding. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.6.0 gnutls_x509_crt_set_subject_alternative_name -------------------------------------------- -- Function: int gnutls_x509_crt_set_subject_alternative_name (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE, const char * DATA_STRING) CRT: a certificate of type `gnutls_x509_crt_t' TYPE: is one of the gnutls_x509_subject_alt_name_t enumerations DATA_STRING: The data to be set, a zero terminated string This function will set the subject alternative name certificate extension. This function assumes that data can be expressed as a null terminated string. The name of the function is unfortunate since it is incosistent with `gnutls_x509_crt_get_subject_alt_name()'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_subject_key_id ---------------------------------- -- Function: int gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t CERT, const void * ID, size_t ID_SIZE) CERT: a certificate of type `gnutls_x509_crt_t' ID: The key ID ID_SIZE: Holds the size of the serial field. This function will set the X.509 certificate's subject key ID extension. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_set_version --------------------------- -- Function: int gnutls_x509_crt_set_version (gnutls_x509_crt_t CRT, unsigned int VERSION) CRT: a certificate of type `gnutls_x509_crt_t' VERSION: holds the version number. For X.509v1 certificates must be 1. This function will set the version of the certificate. This must be one for X.509 version 1, and so on. Plain certificates without extensions must have version set to one. To create well-formed certificates, you must specify version 3 if you use any certificate extensions. Extensions are created by functions such as `gnutls_x509_crt_set_subject_alt_name()' or `gnutls_x509_crt_set_key_usage()'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_sign2 --------------------- -- Function: int gnutls_x509_crt_sign2 (gnutls_x509_crt_t CRT, gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS) CRT: a certificate of type `gnutls_x509_crt_t' ISSUER: is the certificate of the certificate issuer ISSUER_KEY: holds the issuer's private key DIG: The message digest to use, `GNUTLS_DIG_SHA1' is a safe choice FLAGS: must be 0 This function will sign the certificate with the issuer's private key, and will copy the issuer's information into the certificate. This must be the last step in a certificate generation since all the previously set parameters are now signed. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_sign -------------------- -- Function: int gnutls_x509_crt_sign (gnutls_x509_crt_t CRT, gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY) CRT: a certificate of type `gnutls_x509_crt_t' ISSUER: is the certificate of the certificate issuer ISSUER_KEY: holds the issuer's private key This function is the same a `gnutls_x509_crt_sign2()' with no flags, and SHA1 as the hash algorithm. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_crt_verify_data --------------------------- -- Function: int gnutls_x509_crt_verify_data (gnutls_x509_crt_t CRT, unsigned int FLAGS, const gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE) CRT: Holds the certificate FLAGS: should be 0 for now DATA: holds the data to be signed SIGNATURE: contains the signature This function will verify the given signed data, using the parameters from the certificate. *Returns:* In case of a verification failure 0 is returned, and 1 on success. gnutls_x509_crt_verify ---------------------- -- Function: int gnutls_x509_crt_verify (gnutls_x509_crt_t CERT, const gnutls_x509_crt_t * CA_LIST, int CA_LIST_LENGTH, unsigned int FLAGS, unsigned int * VERIFY) CERT: is the certificate to be verified CA_LIST: is one certificate that is considered to be trusted one CA_LIST_LENGTH: holds the number of CA certificate in CA_list FLAGS: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. VERIFY: will hold the certificate verification output. This function will try to verify the given certificate and return its status. The verification output in this functions cannot be GNUTLS_CERT_NOT_VALID. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value.and a negative value in case of an error. gnutls_x509_dn_deinit --------------------- -- Function: void gnutls_x509_dn_deinit (gnutls_x509_dn_t IDN) IDN: a DN opaque object pointer. This function deallocates the DN object as returned by `gnutls_x509_dn_import()'. *Since:* 2.4.0 gnutls_x509_dn_export --------------------- -- Function: int gnutls_x509_dn_export (gnutls_x509_dn_t DN, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) DN: Holds the opaque DN object FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a DN PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the DN to DER or PEM format. If the buffer provided is not long enough to hold the output, then *`output_data_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. If the structure is PEM encoded, it will have a header of "BEGIN NAME". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_dn_get_rdn_ava -------------------------- -- Function: int gnutls_x509_dn_get_rdn_ava (gnutls_x509_dn_t DN, int IRDN, int IAVA, gnutls_x509_ava_st * AVA) DN: input variable with opaque DN pointer IRDN: index of RDN IAVA: index of AVA. AVA: Pointer to structure which will hold output information. Get pointers to data within the DN. Note that `ava' will contain pointers into the `dn' structure, so you should not modify any data or deallocate it. Note also that the DN in turn points into the original certificate structure, and thus you may not deallocate the certificate and continue to access `dn'. *Returns:* Returns 0 on success, or an error code. gnutls_x509_dn_import --------------------- -- Function: int gnutls_x509_dn_import (gnutls_x509_dn_t ODN, const gnutls_datum_t * DATA) ODN: the structure that will hold the imported DN DATA: should contain a DER encoded RDN sequence This function parses an RDN sequence and stores the result to a `gnutls_x509_dn_t' structure. The structure must have been initialized with `gnutls_x509_dn_init()'. You may use `gnutls_x509_dn_get_rdn_ava()' to decode the DN. This function parses an RDN sequence and stores the result to a `gnutls_x509_dn_t' structure. The structure must have been initialized with `gnutls_x509_dn_init()'. You may use `gnutls_x509_dn_get_rdn_ava()' to decode the DN. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.4.0 gnutls_x509_dn_init ------------------- -- Function: int gnutls_x509_dn_init (gnutls_x509_dn_t * ODN) ODN: the object to be initialized This function initializes a `gnutls_x509_dn_t' structure. The object returned must be deallocated using `gnutls_x509_dn_deinit()'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.4.0 gnutls_x509_dn_oid_known ------------------------ -- Function: int gnutls_x509_dn_oid_known (const char * OID) OID: holds an Object Identifier in a null terminated string This function will inform about known DN OIDs. This is useful since functions like `gnutls_x509_crt_set_dn_by_oid()' use the information on known OIDs to properly encode their input. Object Identifiers that are not known are not encoded by these functions, and their input is stored directly into the ASN.1 structure. In that case of unknown OIDs, you have the responsibility of DER encoding your data. *Returns:* 1 on known OIDs and 0 otherwise. gnutls_x509_privkey_cpy ----------------------- -- Function: int gnutls_x509_privkey_cpy (gnutls_x509_privkey_t DST, gnutls_x509_privkey_t SRC) DST: The destination key, which should be initialized. SRC: The source key This function will copy a private key from source to destination key. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_deinit -------------------------- -- Function: void gnutls_x509_privkey_deinit (gnutls_x509_privkey_t KEY) KEY: The structure to be initialized This function will deinitialize a private key structure. gnutls_x509_privkey_export_dsa_raw ---------------------------------- -- Function: int gnutls_x509_privkey_export_dsa_raw (gnutls_x509_privkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t * X) P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y X: will hold the x This function will export the DSA private key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_export_pkcs8 -------------------------------- -- Function: int gnutls_x509_privkey_export_pkcs8 (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the key FORMAT: the format of output params. One of PEM or DER. PASSWORD: the password that will be used to encrypt the key. FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t OUTPUT_DATA: will contain a private key PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the private key to a PKCS8 structure. Both RSA and DSA keys can be exported. For DSA keys we use PKCS `11' definitions. If the flags do not specify the encryption cipher, then the default 3DES (PBES2) will be used. The `password' can be either ASCII or UTF-8 in the default PBES2 encryption schemas, or ASCII for the PKCS12 schemas. If the buffer provided is not long enough to hold the output, then *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. If the structure is PEM encoded, it will have a header of "BEGIN ENCRYPTED PRIVATE KEY" or "BEGIN PRIVATE KEY" if encryption is not used. *Return value:* In case of failure a negative value will be returned, and 0 on success. gnutls_x509_privkey_export_rsa_raw ---------------------------------- -- Function: int gnutls_x509_privkey_export_rsa_raw (gnutls_x509_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U) KEY: a structure that holds the rsa parameters M: will hold the modulus E: will hold the public exponent D: will hold the private exponent P: will hold the first prime (p) Q: will hold the second prime (q) U: will hold the coefficient This function will export the RSA private key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_export -------------------------- -- Function: int gnutls_x509_privkey_export (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the key FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a private key PEM or DER encoded OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the private key to a PKCS1 structure for RSA keys, or an integer sequence for DSA keys. The DSA keys are in the same format with the parameters used by openssl. If the buffer provided is not long enough to hold the output, then *`output_data_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. If the structure is PEM encoded, it will have a header of "BEGIN RSA PRIVATE KEY". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_fix ----------------------- -- Function: int gnutls_x509_privkey_fix (gnutls_x509_privkey_t KEY) KEY: Holds the key This function will recalculate the secondary parameters in a key. In RSA keys, this can be the coefficient and exponent1,2. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_generate ---------------------------- -- Function: int gnutls_x509_privkey_generate (gnutls_x509_privkey_t KEY, gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned int FLAGS) KEY: should contain a `gnutls_x509_privkey_t' structure ALGO: is one of RSA or DSA. BITS: the size of the modulus FLAGS: unused for now. Must be 0. This function will generate a random private key. Note that this function must be called on an empty private key. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_get_key_id ------------------------------ -- Function: int gnutls_x509_privkey_get_key_id (gnutls_x509_privkey_t KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the key FLAGS: should be 0 for now OUTPUT_DATA: will contain the key ID OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will return a unique ID the depends on the public key parameters. This ID can be used in checking whether a certificate corresponds to the given key. If the buffer provided is not long enough to hold the output, then *`output_data_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. The output will normally be a SHA-1 hash output, which is 20 bytes. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_get_pk_algorithm ------------------------------------ -- Function: int gnutls_x509_privkey_get_pk_algorithm (gnutls_x509_privkey_t KEY) KEY: should contain a `gnutls_x509_privkey_t' structure This function will return the public key algorithm of a private key. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. gnutls_x509_privkey_import_dsa_raw ---------------------------------- -- Function: int gnutls_x509_privkey_import_dsa_raw (gnutls_x509_privkey_t KEY, const gnutls_datum_t * P, const gnutls_datum_t * Q, const gnutls_datum_t * G, const gnutls_datum_t * Y, const gnutls_datum_t * X) KEY: The structure to store the parsed key P: holds the p Q: holds the q G: holds the g Y: holds the y X: holds the x This function will convert the given DSA raw parameters to the native `gnutls_x509_privkey_t' format. The output will be stored in `key'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_import_pkcs8 -------------------------------- -- Function: int gnutls_x509_privkey_import_pkcs8 (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS) KEY: The structure to store the parsed key DATA: The DER or PEM encoded key. FORMAT: One of DER or PEM PASSWORD: the password to decrypt the key (if it is encrypted). FLAGS: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted. This function will convert the given DER or PEM encoded PKCS8 2.0 encrypted key to the native gnutls_x509_privkey_t format. The output will be stored in `key'. Both RSA and DSA keys can be imported, and flags can only be used to indicate an unencrypted key. The `password' can be either ASCII or UTF-8 in the default PBES2 encryption schemas, or ASCII for the PKCS12 schemas. If the Certificate is PEM encoded it should have a header of "ENCRYPTED PRIVATE KEY", or "PRIVATE KEY". You only need to specify the flags if the key is DER encoded, since in that case the encryption status cannot be auto-detected. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_import_rsa_raw ---------------------------------- -- Function: int gnutls_x509_privkey_import_rsa_raw (gnutls_x509_privkey_t KEY, const gnutls_datum_t * M, const gnutls_datum_t * E, const gnutls_datum_t * D, const gnutls_datum_t * P, const gnutls_datum_t * Q, const gnutls_datum_t * U) KEY: The structure to store the parsed key M: holds the modulus E: holds the public exponent D: holds the private exponent P: holds the first prime (p) Q: holds the second prime (q) U: holds the coefficient This function will convert the given RSA raw parameters to the native `gnutls_x509_privkey_t' format. The output will be stored in `key'. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_import -------------------------- -- Function: int gnutls_x509_privkey_import (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT) KEY: The structure to store the parsed key DATA: The DER or PEM encoded certificate. FORMAT: One of DER or PEM This function will convert the given DER or PEM encoded key to the native `gnutls_x509_privkey_t' format. The output will be stored in `key' . If the key is PEM encoded it should have a header of "RSA PRIVATE KEY", or "DSA PRIVATE KEY". *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_init ------------------------ -- Function: int gnutls_x509_privkey_init (gnutls_x509_privkey_t * KEY) KEY: The structure to be initialized This function will initialize an private key structure. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_sign_data ----------------------------- -- Function: int gnutls_x509_privkey_sign_data (gnutls_x509_privkey_t KEY, gnutls_digest_algorithm_t DIGEST, unsigned int FLAGS, const gnutls_datum_t * DATA, void * SIGNATURE, size_t * SIGNATURE_SIZE) KEY: Holds the key DIGEST: should be MD5 or SHA1 FLAGS: should be 0 for now DATA: holds the data to be signed SIGNATURE: will contain the signature SIGNATURE_SIZE: holds the size of signature (and will be replaced by the new size) This function will sign the given data using a signature algorithm supported by the private key. Signature algorithms are always used together with a hash functions. Different hash functions may be used for the RSA algorithm, but only SHA-1 for the DSA keys. If the buffer provided is not long enough to hold the output, then *`signature_size' is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_sign_hash ----------------------------- -- Function: int gnutls_x509_privkey_sign_hash (gnutls_x509_privkey_t KEY, const gnutls_datum_t * HASH, gnutls_datum_t * SIGNATURE) KEY: Holds the key HASH: holds the data to be signed SIGNATURE: will contain newly allocated signature This function will sign the given hash using the private key. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_x509_privkey_verify_data ------------------------------- -- Function: int gnutls_x509_privkey_verify_data (gnutls_x509_privkey_t KEY, unsigned int FLAGS, const gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE) KEY: Holds the key FLAGS: should be 0 for now DATA: holds the data to be signed SIGNATURE: contains the signature This function will verify the given signed data, using the parameters in the private key. *Returns:* In case of a verification failure 0 is returned, and 1 on success. gnutls_x509_rdn_get_by_oid -------------------------- -- Function: int gnutls_x509_rdn_get_by_oid (const gnutls_datum_t * IDN, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * SIZEOF_BUF) IDN: should contain a DER encoded RDN sequence OID: an Object Identifier INDX: In case multiple same OIDs exist in the RDN indicates which to send. Use 0 for the first one. RAW_FLAG: If non zero then the raw DER data are returned. BUF: a pointer to a structure to hold the peer's name SIZEOF_BUF: holds the size of `buf' This function will return the name of the given Object identifier, of the RDN sequence. The name will be encoded using the rules from RFC2253. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, or `GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and *`sizeof_buf' is updated if the provided buffer is not long enough, otherwise a negative error value. gnutls_x509_rdn_get_oid ----------------------- -- Function: int gnutls_x509_rdn_get_oid (const gnutls_datum_t * IDN, int INDX, void * BUF, size_t * SIZEOF_BUF) IDN: should contain a DER encoded RDN sequence INDX: Indicates which OID to return. Use 0 for the first one. This function will return the specified Object identifier, of the RDN sequence. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, or `GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and *`sizeof_buf' is updated if the provided buffer is not long enough, otherwise a negative error value. *Since:* 2.4.0 gnutls_x509_rdn_get ------------------- -- Function: int gnutls_x509_rdn_get (const gnutls_datum_t * IDN, char * BUF, size_t * SIZEOF_BUF) IDN: should contain a DER encoded RDN sequence BUF: a pointer to a structure to hold the peer's name SIZEOF_BUF: holds the size of `buf' This function will return the name of the given RDN sequence. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, or `GNUTLS_E_SHORT_MEMORY_BUFFER' is returned and *`sizeof_buf' is updated if the provided buffer is not long enough, otherwise a negative error value.  File: gnutls.info, Node: GnuTLS-extra functions, Next: OpenPGP functions, Prev: X.509 certificate functions, Up: Function reference 9.3 GnuTLS-extra Functions ========================== These functions are only available in the GPLv3+ version of the library called `gnutls-extra'. The prototypes for this library lie in `gnutls/extra.h'. gnutls_extra_check_version -------------------------- -- Function: const char * gnutls_extra_check_version (const char * REQ_VERSION) REQ_VERSION: the version to check Check that the version of the gnutls-extra library is at minimum the requested one and return the version string; return NULL if the condition is not satisfied. If a NULL is passed to this function, no check is done, but the version string is simply returned. gnutls_global_init_extra ------------------------ -- Function: int gnutls_global_init_extra ( VOID) This function initializes the global state of gnutls-extra library to defaults. Returns zero on success. Note that `gnutls_global_init()' has to be called before this function. If this function is not called then the gnutls-extra library will not be usable.  File: gnutls.info, Node: OpenPGP functions, Next: TLS Inner Application (TLS/IA) functions, Prev: GnuTLS-extra functions, Up: Function reference 9.4 OpenPGP Functions ===================== The following functions are to be used for OpenPGP certificate handling. Their prototypes lie in `gnutls/openpgp.h'. gnutls_certificate_set_openpgp_key_file2 ---------------------------------------- -- Function: int gnutls_certificate_set_openpgp_key_file2 (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, const char * SUBKEY_ID, gnutls_openpgp_crt_fmt_t FORMAT) RES: the destination context to save the data. CERTFILE: the file that contains the public key. KEYFILE: the file that contains the secret key. SUBKEY_ID: a hex encoded subkey id FORMAT: the format of the keys This funtion is used to load OpenPGP keys into the GnuTLS credential structure. The files should contain non encrypted keys. The special keyword "auto" is also accepted as &subkey_id. In that case the `gnutls_openpgp_crt_get_auth_subkey()' will be used to retrieve the subkey. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.4.0 gnutls_certificate_set_openpgp_key_file --------------------------------------- -- Function: int gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, gnutls_openpgp_crt_fmt_t FORMAT) RES: the destination context to save the data. CERTFILE: the file that contains the public key. KEYFILE: the file that contains the secret key. FORMAT: the format of the keys This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. The files should only contain one key which is not encrypted. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_certificate_set_openpgp_key_mem2 --------------------------------------- -- Function: int gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t RES, const gnutls_datum_t * ICERT, const gnutls_datum_t * IKEY, const char * SUBKEY_ID, gnutls_openpgp_crt_fmt_t FORMAT) RES: the destination context to save the data. SUBKEY_ID: a hex encoded subkey id FORMAT: the format of the keys This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. The files should only contain one key which is not encrypted. The special keyword "auto" is also accepted as &subkey_id. In that case the `gnutls_openpgp_crt_get_auth_subkey()' will be used to retrieve the subkey. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. *Since:* 2.4.0 gnutls_certificate_set_openpgp_key_mem -------------------------------------- -- Function: int gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t RES, const gnutls_datum_t * ICERT, const gnutls_datum_t * IKEY, gnutls_openpgp_crt_fmt_t FORMAT) RES: the destination context to save the data. FORMAT: the format of the keys This funtion is used to load OpenPGP keys into the GnuTLS credential structure. The files should contain non encrypted keys. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_certificate_set_openpgp_keyring_file ------------------------------------------- -- Function: int gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t C, const char * FILE, gnutls_openpgp_crt_fmt_t FORMAT) C: A certificate credentials structure FILE: filename of the keyring. The function is used to set keyrings that will be used internally by various OpenPGP functions. For example to find a key when it is needed for an operations. The keyring will also be used at the verification functions. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_certificate_set_openpgp_keyring_mem ------------------------------------------ -- Function: int gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t C, const opaque * DATA, size_t DLEN, gnutls_openpgp_crt_fmt_t FORMAT) C: A certificate credentials structure DATA: buffer with keyring data. DLEN: length of data buffer. The function is used to set keyrings that will be used internally by various OpenPGP functions. For example to find a key when it is needed for an operations. The keyring will also be used at the verification functions. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_certificate_set_openpgp_key ---------------------------------- -- Function: int gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t RES, gnutls_openpgp_crt_t CRT, gnutls_openpgp_privkey_t PKEY) RES: is an `gnutls_certificate_credentials_t' structure. PKEY: is an openpgp private key This function sets a certificate/private key pair in the gnutls_certificate_credentials_t structure. This function may be called more than once (in case multiple keys/certificates exist for the server). With this function the subkeys of the certificate are not used. gnutls_openpgp_crt_check_hostname --------------------------------- -- Function: int gnutls_openpgp_crt_check_hostname (gnutls_openpgp_crt_t KEY, const char * HOSTNAME) KEY: should contain an `gnutls_openpgp_crt_t' structure HOSTNAME: A null terminated string that contains a DNS name This function will check if the given key's owner matches the given hostname. This is a basic implementation of the matching described in RFC2818 (HTTPS), which takes into account wildcards. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_deinit ------------------------- -- Function: void gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t KEY) KEY: The structure to be initialized This function will deinitialize a key structure. gnutls_openpgp_crt_export ------------------------- -- Function: int gnutls_openpgp_crt_export (gnutls_openpgp_crt_t KEY, gnutls_openpgp_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the key. FORMAT: One of gnutls_openpgp_crt_fmt_t elements. OUTPUT_DATA: will contain the key base64 encoded or raw OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will convert the given key to RAW or Base64 format. If the buffer provided is not long enough to hold the output, then `GNUTLS_E_SHORT_MEMORY_BUFFER' will be returned. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_get_auth_subkey ---------------------------------- -- Function: int gnutls_openpgp_crt_get_auth_subkey (gnutls_openpgp_crt_t CRT, gnutls_openpgp_keyid_t KEYID, unsigned int FLAG) KEYID: the struct to save the keyid. FLAG: Non zero indicates that a valid subkey is always returned. Returns the 64-bit keyID of the first valid OpenPGP subkey marked for authentication. If flag is non zero and no authentication subkey exists, then a valid subkey will be returned even if it is not marked for authentication. Returns the 64-bit keyID of the first valid OpenPGP subkey marked for authentication. If flag is non zero and no authentication subkey exists, then a valid subkey will be returned even if it is not marked for authentication. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_get_creation_time ------------------------------------ -- Function: time_t gnutls_openpgp_crt_get_creation_time (gnutls_openpgp_crt_t KEY) KEY: the structure that contains the OpenPGP public key. Get key creation time. *Returns:* the timestamp when the OpenPGP key was created. gnutls_openpgp_crt_get_expiration_time -------------------------------------- -- Function: time_t gnutls_openpgp_crt_get_expiration_time (gnutls_openpgp_crt_t KEY) KEY: the structure that contains the OpenPGP public key. Get key expiration time. A value of '0' means that the key doesn't expire at all. *Returns:* the time when the OpenPGP key expires. gnutls_openpgp_crt_get_fingerprint ---------------------------------- -- Function: int gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t KEY, void * FPR, size_t * FPRLEN) KEY: the raw data that contains the OpenPGP public key. FPR: the buffer to save the fingerprint, must hold at least 20 bytes. FPRLEN: the integer to save the length of the fingerprint. Get key fingerprint. Depending on the algorithm, the fingerprint can be 16 or 20 bytes. *Returns:* On success, 0 is returned. Otherwise, an error code. gnutls_openpgp_crt_get_key_id ----------------------------- -- Function: int gnutls_openpgp_crt_get_key_id (gnutls_openpgp_crt_t KEY, gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. KEYID: the buffer to save the keyid. Get key id string. *Returns:* the 64-bit keyID of the OpenPGP key. *Since:* 2.4.0 gnutls_openpgp_crt_get_key_usage -------------------------------- -- Function: int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t KEY, unsigned int * KEY_USAGE) KEY: should contain a gnutls_openpgp_crt_t structure KEY_USAGE: where the key usage bits will be stored This function will return certificate's key usage, by checking the key algorithm. The key usage value will ORed values of the: `GNUTLS_KEY_DIGITAL_SIGNATURE', `GNUTLS_KEY_KEY_ENCIPHERMENT'. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_get_name --------------------------- -- Function: int gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t KEY, int IDX, char * BUF, size_t * SIZEOF_BUF) KEY: the structure that contains the OpenPGP public key. IDX: the index of the ID to extract BUF: a pointer to a structure to hold the name SIZEOF_BUF: holds the maximum size of `buf', on return hold the actual/required size of `buf'. Extracts the userID from the parsed OpenPGP key. *Returns:* `GNUTLS_E_SUCCESS' on success, and if the index of the ID does not exist `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE', or an error code. gnutls_openpgp_crt_get_pk_algorithm ----------------------------------- -- Function: gnutls_pk_algorithm_t gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t KEY, unsigned int * BITS) KEY: is an OpenPGP key BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of an OpenPGP certificate. If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. gnutls_openpgp_crt_get_pk_dsa_raw --------------------------------- -- Function: int gnutls_openpgp_crt_get_pk_dsa_raw (gnutls_openpgp_crt_t CRT, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y) CRT: Holds the certificate P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y This function will export the DSA public key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_crt_get_pk_rsa_raw --------------------------------- -- Function: int gnutls_openpgp_crt_get_pk_rsa_raw (gnutls_openpgp_crt_t CRT, gnutls_datum_t * M, gnutls_datum_t * E) CRT: Holds the certificate M: will hold the modulus E: will hold the public exponent This function will export the RSA public key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_crt_get_preferred_key_id --------------------------------------- -- Function: int gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t KEY, gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. KEYID: the struct to save the keyid. Get preferred key id. If it hasn't been set it returns `GNUTLS_E_INVALID_REQUEST'. *Returns:* the 64-bit preferred keyID of the OpenPGP key. gnutls_openpgp_crt_get_revoked_status ------------------------------------- -- Function: int gnutls_openpgp_crt_get_revoked_status (gnutls_openpgp_crt_t KEY) KEY: the structure that contains the OpenPGP public key. Get revocation status of key. *Returns:* true (1) if the key has been revoked, or false (0) if it has not. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_count ----------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_count (gnutls_openpgp_crt_t KEY) KEY: is an OpenPGP key This function will return the number of subkeys present in the given OpenPGP certificate. *Returns:* the number of subkeys, or a negative value on error. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_creation_time ------------------------------------------- -- Function: time_t gnutls_openpgp_crt_get_subkey_creation_time (gnutls_openpgp_crt_t KEY, unsigned int IDX) KEY: the structure that contains the OpenPGP public key. IDX: the subkey index Get subkey creation time. *Returns:* the timestamp when the OpenPGP sub-key was created. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_expiration_time --------------------------------------------- -- Function: time_t gnutls_openpgp_crt_get_subkey_expiration_time (gnutls_openpgp_crt_t KEY, unsigned int IDX) KEY: the structure that contains the OpenPGP public key. IDX: the subkey index Get subkey expiration time. A value of '0' means that the key doesn't expire at all. *Returns:* the time when the OpenPGP key expires. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_fingerprint ----------------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_fingerprint (gnutls_openpgp_crt_t KEY, unsigned int IDX, void * FPR, size_t * FPRLEN) KEY: the raw data that contains the OpenPGP public key. IDX: the subkey index FPR: the buffer to save the fingerprint, must hold at least 20 bytes. FPRLEN: the integer to save the length of the fingerprint. Get key fingerprint of a subkey. Depending on the algorithm, the fingerprint can be 16 or 20 bytes. *Returns:* On success, 0 is returned. Otherwise, an error code. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_idx --------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_idx (gnutls_openpgp_crt_t KEY, const gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. KEYID: the keyid. Get subkey's index. *Returns:* the index of the subkey or a negative error value. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_id -------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t KEY, unsigned int IDX, gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. IDX: the subkey index KEYID: the buffer to save the keyid. Get the subkey's key-id. *Returns:* the 64-bit keyID of the OpenPGP key. gnutls_openpgp_crt_get_subkey_pk_algorithm ------------------------------------------ -- Function: gnutls_pk_algorithm_t gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t KEY, unsigned int IDX, unsigned int * BITS) KEY: is an OpenPGP key IDX: is the subkey index BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of a subkey of an OpenPGP certificate. If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_pk_dsa_raw ---------------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_pk_dsa_raw (gnutls_openpgp_crt_t CRT, unsigned int IDX, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y) CRT: Holds the certificate IDX: Is the subkey index P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y This function will export the DSA public key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_pk_rsa_raw ---------------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_pk_rsa_raw (gnutls_openpgp_crt_t CRT, unsigned int IDX, gnutls_datum_t * M, gnutls_datum_t * E) CRT: Holds the certificate IDX: Is the subkey index M: will hold the modulus E: will hold the public exponent This function will export the RSA public key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_revoked_status -------------------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_revoked_status (gnutls_openpgp_crt_t KEY, unsigned int IDX) KEY: the structure that contains the OpenPGP public key. IDX: is the subkey index Get subkey revocation status. A negative value indicates an error. *Returns:* true (1) if the key has been revoked, or false (0) if it has not. *Since:* 2.4.0 gnutls_openpgp_crt_get_subkey_usage ----------------------------------- -- Function: int gnutls_openpgp_crt_get_subkey_usage (gnutls_openpgp_crt_t KEY, unsigned int IDX, unsigned int * KEY_USAGE) KEY: should contain a gnutls_openpgp_crt_t structure IDX: the subkey index KEY_USAGE: where the key usage bits will be stored This function will return certificate's key usage, by checking the key algorithm. The key usage value will ORed values of `GNUTLS_KEY_DIGITAL_SIGNATURE' or `GNUTLS_KEY_KEY_ENCIPHERMENT'. A negative value may be returned in case of parsing error. *Returns:* key usage value. *Since:* 2.4.0 gnutls_openpgp_crt_get_version ------------------------------ -- Function: int gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t KEY) KEY: the structure that contains the OpenPGP public key. Extract the version of the OpenPGP key. *Returns:* the version number is returned, or a negative value on errors. gnutls_openpgp_crt_import ------------------------- -- Function: int gnutls_openpgp_crt_import (gnutls_openpgp_crt_t KEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT) KEY: The structure to store the parsed key. DATA: The RAW or BASE64 encoded key. FORMAT: One of gnutls_openpgp_crt_fmt_t elements. This function will convert the given RAW or Base64 encoded key to the native `gnutls_openpgp_crt_t' format. The output will be stored in 'key'. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_init ----------------------- -- Function: int gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * KEY) KEY: The structure to be initialized This function will initialize an OpenPGP key structure. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_print ------------------------ -- Function: int gnutls_openpgp_crt_print (gnutls_openpgp_crt_t CERT, gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t * OUT) CERT: The structure to be printed FORMAT: Indicate the format to use OUT: Newly allocated datum with zero terminated string. This function will pretty print an OpenPGP certificate, suitable for display to a human. The format should be zero for future compatibility. The output `out' needs to be deallocate using `gnutls_free()'. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_set_preferred_key_id --------------------------------------- -- Function: int gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t KEY, const gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. KEYID: the selected keyid This allows setting a preferred key id for the given certificate. This key will be used by functions that involve key handling. gnutls_openpgp_crt_verify_ring ------------------------------ -- Function: int gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t KEY, gnutls_openpgp_keyring_t KEYRING, unsigned int FLAGS, unsigned int * VERIFY) KEY: the structure that holds the key. KEYRING: holds the keyring to check against FLAGS: unused (should be 0) VERIFY: will hold the certificate verification output. Verify all signatures in the key, using the given set of keys (keyring). The key verification output will be put in `verify' and will be one or more of the `gnutls_certificate_status_t' enumerated elements bitwise or'd. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_crt_verify_self ------------------------------ -- Function: int gnutls_openpgp_crt_verify_self (gnutls_openpgp_crt_t KEY, unsigned int FLAGS, unsigned int * VERIFY) KEY: the structure that holds the key. FLAGS: unused (should be 0) VERIFY: will hold the key verification output. Verifies the self signature in the key. The key verification output will be put in `verify' and will be one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_keyring_check_id ------------------------------- -- Function: int gnutls_openpgp_keyring_check_id (gnutls_openpgp_keyring_t RING, const gnutls_openpgp_keyid_t KEYID, unsigned int FLAGS) RING: holds the keyring to check against KEYID: will hold the keyid to check for. FLAGS: unused (should be 0) Check if a given key ID exists in the keyring. *Returns:* `GNUTLS_E_SUCCESS' on success (if keyid exists) and a negative error code on failure. gnutls_openpgp_keyring_deinit ----------------------------- -- Function: void gnutls_openpgp_keyring_deinit (gnutls_openpgp_keyring_t KEYRING) KEYRING: The structure to be initialized This function will deinitialize a keyring structure. gnutls_openpgp_keyring_get_crt_count ------------------------------------ -- Function: int gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t RING) RING: is an OpenPGP key ring This function will return the number of OpenPGP certificates present in the given keyring. *Returns:* the number of subkeys, or a negative value on error. gnutls_openpgp_keyring_get_crt ------------------------------ -- Function: int gnutls_openpgp_keyring_get_crt (gnutls_openpgp_keyring_t RING, unsigned int IDX, gnutls_openpgp_crt_t * CERT) IDX: the index of the certificate to export This function will extract an OpenPGP certificate from the given keyring. If the index given is out of range `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' will be returned. The returned structure needs to be deinited. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_keyring_import ----------------------------- -- Function: int gnutls_openpgp_keyring_import (gnutls_openpgp_keyring_t KEYRING, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT) KEYRING: The structure to store the parsed key. DATA: The RAW or BASE64 encoded keyring. FORMAT: One of `gnutls_openpgp_keyring_fmt' elements. This function will convert the given RAW or Base64 encoded keyring to the native `gnutls_openpgp_keyring_t' format. The output will be stored in 'keyring'. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_keyring_init --------------------------- -- Function: int gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t * KEYRING) KEYRING: The structure to be initialized This function will initialize an keyring structure. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_privkey_deinit ----------------------------- -- Function: void gnutls_openpgp_privkey_deinit (gnutls_openpgp_privkey_t KEY) KEY: The structure to be initialized This function will deinitialize a key structure. gnutls_openpgp_privkey_export_dsa_raw ------------------------------------- -- Function: int gnutls_openpgp_privkey_export_dsa_raw (gnutls_openpgp_privkey_t PKEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t * X) PKEY: Holds the certificate P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y X: will hold the x This function will export the DSA private key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_privkey_export_rsa_raw ------------------------------------- -- Function: int gnutls_openpgp_privkey_export_rsa_raw (gnutls_openpgp_privkey_t PKEY, gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U) PKEY: Holds the certificate M: will hold the modulus E: will hold the public exponent D: will hold the private exponent P: will hold the first prime (p) Q: will hold the second prime (q) U: will hold the coefficient This function will export the RSA private key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_privkey_export_subkey_dsa_raw -------------------------------------------- -- Function: int gnutls_openpgp_privkey_export_subkey_dsa_raw (gnutls_openpgp_privkey_t PKEY, unsigned int IDX, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t * X) PKEY: Holds the certificate IDX: Is the subkey index P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y X: will hold the x This function will export the DSA private key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_privkey_export_subkey_rsa_raw -------------------------------------------- -- Function: int gnutls_openpgp_privkey_export_subkey_rsa_raw (gnutls_openpgp_privkey_t PKEY, unsigned int IDX, gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U) PKEY: Holds the certificate IDX: Is the subkey index M: will hold the modulus E: will hold the public exponent D: will hold the private exponent P: will hold the first prime (p) Q: will hold the second prime (q) U: will hold the coefficient This function will export the RSA private key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()' and will be stored in the appropriate datum. *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error. *Since:* 2.4.0 gnutls_openpgp_privkey_export ----------------------------- -- Function: int gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the key. FORMAT: One of gnutls_openpgp_crt_fmt_t elements. PASSWORD: the password that will be used to encrypt the key. (unused for now) FLAGS: zero for future compatibility OUTPUT_DATA: will contain the key base64 encoded or raw OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will convert the given key to RAW or Base64 format. If the buffer provided is not long enough to hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. *Since:* 2.4.0 gnutls_openpgp_privkey_get_fingerprint -------------------------------------- -- Function: int gnutls_openpgp_privkey_get_fingerprint (gnutls_openpgp_privkey_t KEY, void * FPR, size_t * FPRLEN) KEY: the raw data that contains the OpenPGP secret key. FPR: the buffer to save the fingerprint, must hold at least 20 bytes. FPRLEN: the integer to save the length of the fingerprint. Get the fingerprint of the OpenPGP key. Depends on the algorithm, the fingerprint can be 16 or 20 bytes. *Returns:* On success, 0 is returned, or an error code. *Since:* 2.4.0 gnutls_openpgp_privkey_get_key_id --------------------------------- -- Function: int gnutls_openpgp_privkey_get_key_id (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP secret key. KEYID: the buffer to save the keyid. Get key-id. *Returns:* the 64-bit keyID of the OpenPGP key. *Since:* 2.4.0 gnutls_openpgp_privkey_get_pk_algorithm --------------------------------------- -- Function: gnutls_pk_algorithm_t gnutls_openpgp_privkey_get_pk_algorithm (gnutls_openpgp_privkey_t KEY, unsigned int * BITS) KEY: is an OpenPGP key BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of an OpenPGP certificate. If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. *Since:* 2.4.0 gnutls_openpgp_privkey_get_preferred_key_id ------------------------------------------- -- Function: int gnutls_openpgp_privkey_get_preferred_key_id (gnutls_openpgp_privkey_t KEY, gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. KEYID: the struct to save the keyid. Get the preferred key-id for the key. *Returns:* the 64-bit preferred keyID of the OpenPGP key, or if it hasn't been set it returns `GNUTLS_E_INVALID_REQUEST'. gnutls_openpgp_privkey_get_revoked_status ----------------------------------------- -- Function: int gnutls_openpgp_privkey_get_revoked_status (gnutls_openpgp_privkey_t KEY) KEY: the structure that contains the OpenPGP private key. Get revocation status of key. *Returns:* true (1) if the key has been revoked, or false (0) if it has not, or a negative value indicates an error. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_count --------------------------------------- -- Function: int gnutls_openpgp_privkey_get_subkey_count (gnutls_openpgp_privkey_t KEY) KEY: is an OpenPGP key This function will return the number of subkeys present in the given OpenPGP certificate. *Returns:* the number of subkeys, or a negative value on error. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_creation_time ----------------------------------------------- -- Function: time_t gnutls_openpgp_privkey_get_subkey_creation_time (gnutls_openpgp_privkey_t KEY, unsigned int IDX) KEY: the structure that contains the OpenPGP private key. IDX: the subkey index Get subkey creation time. *Returns:* the timestamp when the OpenPGP key was created. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_expiration_time ------------------------------------------------- -- Function: time_t gnutls_openpgp_privkey_get_subkey_expiration_time (gnutls_openpgp_privkey_t KEY, unsigned int IDX) KEY: the structure that contains the OpenPGP private key. IDX: the subkey index Get subkey expiration time. A value of '0' means that the key doesn't expire at all. *Returns:* the time when the OpenPGP key expires. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_fingerprint --------------------------------------------- -- Function: int gnutls_openpgp_privkey_get_subkey_fingerprint (gnutls_openpgp_privkey_t KEY, unsigned int IDX, void * FPR, size_t * FPRLEN) KEY: the raw data that contains the OpenPGP secret key. IDX: the subkey index FPR: the buffer to save the fingerprint, must hold at least 20 bytes. FPRLEN: the integer to save the length of the fingerprint. Get the fingerprint of an OpenPGP subkey. Depends on the algorithm, the fingerprint can be 16 or 20 bytes. *Returns:* On success, 0 is returned, or an error code. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_idx ------------------------------------- -- Function: int gnutls_openpgp_privkey_get_subkey_idx (gnutls_openpgp_privkey_t KEY, const gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP private key. KEYID: the keyid. Get index of subkey. *Returns:* the index of the subkey or a negative error value. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_id ------------------------------------ -- Function: int gnutls_openpgp_privkey_get_subkey_id (gnutls_openpgp_privkey_t KEY, unsigned int IDX, gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP secret key. IDX: the subkey index KEYID: the buffer to save the keyid. Get the key-id for the subkey. *Returns:* the 64-bit keyID of the OpenPGP key. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_pk_algorithm ---------------------------------------------- -- Function: gnutls_pk_algorithm_t gnutls_openpgp_privkey_get_subkey_pk_algorithm (gnutls_openpgp_privkey_t KEY, unsigned int IDX, unsigned int * BITS) KEY: is an OpenPGP key IDX: is the subkey index BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of a subkey of an OpenPGP certificate. If bits is non null, it should have enough size to hold the parameters size in bits. For RSA the bits returned is the modulus. For DSA the bits returned are of the public exponent. *Returns:* a member of the `gnutls_pk_algorithm_t' enumeration on success, or a negative value on error. *Since:* 2.4.0 gnutls_openpgp_privkey_get_subkey_revoked_status ------------------------------------------------ -- Function: int gnutls_openpgp_privkey_get_subkey_revoked_status (gnutls_openpgp_privkey_t KEY, unsigned int IDX) KEY: the structure that contains the OpenPGP private key. IDX: is the subkey index Get revocation status of key. *Returns:* true (1) if the key has been revoked, or false (0) if it has not, or a negative value indicates an error. *Since:* 2.4.0 gnutls_openpgp_privkey_import ----------------------------- -- Function: int gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t KEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS) KEY: The structure to store the parsed key. DATA: The RAW or BASE64 encoded key. FORMAT: One of gnutls_openpgp_crt_fmt_t elements. PASSWORD: (unused for now) FLAGS: should be zero This function will convert the given RAW or Base64 encoded key to the native gnutls_openpgp_privkey_t format. The output will be stored in 'key'. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_privkey_init --------------------------- -- Function: int gnutls_openpgp_privkey_init (gnutls_openpgp_privkey_t * KEY) KEY: The structure to be initialized This function will initialize an OpenPGP key structure. *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code. gnutls_openpgp_privkey_set_preferred_key_id ------------------------------------------- -- Function: int gnutls_openpgp_privkey_set_preferred_key_id (gnutls_openpgp_privkey_t KEY, const gnutls_openpgp_keyid_t KEYID) KEY: the structure that contains the OpenPGP public key. KEYID: the selected keyid This allows setting a preferred key id for the given certificate. This key will be used by functions that involve key handling. *Returns:* On success, 0 is returned, or an error code. gnutls_openpgp_privkey_sign_hash -------------------------------- -- Function: int gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t KEY, const gnutls_datum_t * HASH, gnutls_datum_t * SIGNATURE) KEY: Holds the key HASH: holds the data to be signed SIGNATURE: will contain newly allocated signature This function will sign the given hash using the private key. You should use `gnutls_openpgp_privkey_set_subkey()' before calling this function to set the subkey to use. *Returns:* On success, `GNUTLS_E_SUCCESS' is returned, otherwise a negative error value. gnutls_openpgp_set_recv_key_function ------------------------------------ -- Function: void gnutls_openpgp_set_recv_key_function (gnutls_session_t SESSION, gnutls_openpgp_recv_key_func FUNC) SESSION: a TLS session FUNC: the callback This funtion will set a key retrieval function for OpenPGP keys. This callback is only useful in server side, and will be used if the peer sent a key fingerprint instead of a full key.  File: gnutls.info, Node: TLS Inner Application (TLS/IA) functions, Next: Error codes and descriptions, Prev: OpenPGP functions, Up: Function reference 9.5 TLS Inner Application (TLS/IA) Functions ============================================ The following functions are used for TLS Inner Application (TLS/IA). Their prototypes lie in `gnutls/extra.h'. You need to link with `libgnutls-extra' to be able to use these functions (*note GnuTLS-extra functions::). The typical control flow in an TLS/IA client (that would not require an Application Phase for resumed sessions) would be similar to the following: int client_avp (gnuls_session_t *session, void *ptr, const char *last, size_t lastlen, char **new, size_t *newlen) { ... } ... int main () { gnutls_ia_client_credentials_t iacred; ... gnutls_init (&session, GNUTLS_CLIENT); ... /* Enable TLS/IA. */ gnutls_ia_allocate_client_credentials(&iacred); gnutls_ia_set_client_avp_function(iacred, client_avp); gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred); ... ret = gnutls_handshake (session); // Error handling... ... if (gnutls_ia_handshake_p (session)) { ret = gnutls_ia_handshake (session); // Error handling... ... See below for detailed descriptions of all the functions used above. The function `client_avp' would have to be implemented by your application. The function is responsible for handling the AVP data. See `gnutls_ia_set_client_avp_function' below for more information on how that function should be implemented. The control flow in a typical server is similar to the above, use `gnutls_ia_server_credentials_t' instead of `gnutls_ia_client_credentials_t', and replace the call to the client functions with the corresponding server functions. gnutls_ia_allocate_client_credentials ------------------------------------- -- Function: int gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t * SC) SC: is a pointer to an `gnutls_ia_server_credentials_t' structure. This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it. Adding this credential to a session will enable TLS/IA, and will require an Application Phase after the TLS handshake (if the server support TLS/IA). Use `gnutls_ia_require_inner_phase()' to toggle the TLS/IA mode. *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned, otherwise an error code is returned. gnutls_ia_allocate_server_credentials ------------------------------------- -- Function: int gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t * SC) SC: is a pointer to an `gnutls_ia_server_credentials_t' structure. This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it. Adding this credential to a session will enable TLS/IA, and will require an Application Phase after the TLS handshake (if the client support TLS/IA). Use `gnutls_ia_require_inner_phase()' to toggle the TLS/IA mode. *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned, otherwise an error code is returned. gnutls_ia_enable ---------------- -- Function: void gnutls_ia_enable (gnutls_session_t SESSION, int ALLOW_SKIP_ON_RESUME) SESSION: is a `gnutls_session_t' structure. ALLOW_SKIP_ON_RESUME: non-zero if local party allows to skip the TLS/IA application phases for a resumed session. Specify whether we must advertise support for the TLS/IA extension during the handshake. At the client side, we always advertise TLS/IA if gnutls_ia_enable was called before the handshake; at the server side, we also require that the client has advertised that it wants to run TLS/IA before including the advertisement, as required by the protocol. Similarly, at the client side we always advertise that we allow TLS/IA to be skipped for resumed sessions if `allow_skip_on_resume' is non-zero; at the server side, we also require that the session is indeed resumable and that the client has also advertised that it allows TLS/IA to be skipped for resumed sessions. After the TLS handshake, call `gnutls_ia_handshake_p()' to find out whether both parties agreed to do a TLS/IA handshake, before calling `gnutls_ia_handshake()' or one of the lower level gnutls_ia_* functions. gnutls_ia_endphase_send ----------------------- -- Function: int gnutls_ia_endphase_send (gnutls_session_t SESSION, int FINAL_P) SESSION: is a `gnutls_session_t' structure. FINAL_P: Set iff this should signal the final phase. Send a TLS/IA end phase message. In the client, this should only be used to acknowledge an end phase message sent by the server. In the server, this can be called instead of `gnutls_ia_send()' if the server wishes to end an application phase. *Return value:* Return 0 on success, or an error code. gnutls_ia_extract_inner_secret ------------------------------ -- Function: void gnutls_ia_extract_inner_secret (gnutls_session_t SESSION, char * BUFFER) SESSION: is a `gnutls_session_t' structure. BUFFER: pre-allocated buffer to hold 48 bytes of inner secret. Copy the 48 bytes large inner secret into the specified buffer This function is typically used after the TLS/IA handshake has concluded. The TLS/IA inner secret can be used as input to a PRF to derive session keys. Do not use the inner secret directly as a session key, because for a resumed session that does not include an application phase, the inner secret will be identical to the inner secret in the original session. It is important to include, for example, the client and server randomness when deriving a sesssion key from the inner secret. gnutls_ia_free_client_credentials --------------------------------- -- Function: void gnutls_ia_free_client_credentials (gnutls_ia_client_credentials_t SC) SC: is an `gnutls_ia_client_credentials_t' structure. This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it. gnutls_ia_free_server_credentials --------------------------------- -- Function: void gnutls_ia_free_server_credentials (gnutls_ia_server_credentials_t SC) SC: is an `gnutls_ia_server_credentials_t' structure. This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it. gnutls_ia_generate_challenge ---------------------------- -- Function: int gnutls_ia_generate_challenge (gnutls_session_t SESSION, size_t BUFFER_SIZE, char * BUFFER) SESSION: is a `gnutls_session_t' structure. BUFFER_SIZE: size of output buffer. BUFFER: pre-allocated buffer to contain `buffer_size' bytes of output. Generate an application challenge that the client cannot control or predict, based on the TLS/IA inner secret. *Return value:* Returns 0 on success, or an negative error code. gnutls_ia_get_client_avp_ptr ---------------------------- -- Function: void * gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t CRED) CRED: is a `gnutls_ia_client_credentials_t' structure. Returns the pointer that will be provided to the TLS/IA callback function as the first argument. *Returns:* The client callback data pointer. gnutls_ia_get_server_avp_ptr ---------------------------- -- Function: void * gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_t CRED) CRED: is a `gnutls_ia_client_credentials_t' structure. Returns the pointer that will be provided to the TLS/IA callback function as the first argument. *Returns:* The server callback data pointer. gnutls_ia_handshake_p --------------------- -- Function: int gnutls_ia_handshake_p (gnutls_session_t SESSION) SESSION: is a `gnutls_session_t' structure. Predicate to be used after `gnutls_handshake()' to decide whether to invoke `gnutls_ia_handshake()'. Usable by both clients and servers. *Return value:* non-zero if TLS/IA handshake is expected, zero otherwise. gnutls_ia_handshake ------------------- -- Function: int gnutls_ia_handshake (gnutls_session_t SESSION) SESSION: is a `gnutls_session_t' structure. Perform a TLS/IA handshake. This should be called after `gnutls_handshake()' iff `gnutls_ia_handshake_p()'. Return 0 on success, or an error code. gnutls_ia_permute_inner_secret ------------------------------ -- Function: int gnutls_ia_permute_inner_secret (gnutls_session_t SESSION, size_t SESSION_KEYS_SIZE, const char * SESSION_KEYS) SESSION: is a `gnutls_session_t' structure. SESSION_KEYS_SIZE: Size of generated session keys (0 if none). SESSION_KEYS: Generated session keys, used to permute inner secret (NULL if none). Permute the inner secret using the generated session keys. This can be called in the TLS/IA AVP callback to mix any generated session keys with the TLS/IA inner secret. *Return value:* Return zero on success, or a negative error code. gnutls_ia_recv -------------- -- Function: ssize_t gnutls_ia_recv (gnutls_session_t SESSION, char * DATA, size_t SIZEOFDATA) SESSION: is a `gnutls_session_t' structure. DATA: the buffer that the data will be read into, must hold >= 12 bytes. SIZEOFDATA: the number of requested bytes, must be >= 12. Receive TLS/IA data. This function has the similar semantics with `recv()'. The only difference is that is accepts a GNUTLS session, and uses different error codes. If the server attempt to finish an application phase, this function will return `GNUTLS_E_WARNING_IA_IPHF_RECEIVED' or `GNUTLS_E_WARNING_IA_FPHF_RECEIVED'. The caller should then invoke `gnutls_ia_verify_endphase()', and if it runs the client side, also send an endphase message of its own using gnutls_ia_endphase_send. If EINTR is returned by the internal push function (the default is `code'{`recv()'}) then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again, with the same parameters; alternatively you could provide a NULL pointer for data, and 0 for size. *Returns:* The number of bytes received. A negative error code is returned in case of an error. The `GNUTLS_E_WARNING_IA_IPHF_RECEIVED' and `GNUTLS_E_WARNING_IA_FPHF_RECEIVED' errors are returned when an application phase finished message has been sent by the server. gnutls_ia_send -------------- -- Function: ssize_t gnutls_ia_send (gnutls_session_t SESSION, const char * DATA, size_t SIZEOFDATA) SESSION: is a `gnutls_session_t' structure. DATA: contains the data to send SIZEOFDATA: is the length of the data Send TLS/IA application payload data. This function has the similar semantics with `send()'. The only difference is that is accepts a GNUTLS session, and uses different error codes. The TLS/IA protocol is synchronous, so you cannot send more than one packet at a time. The client always send the first packet. To finish an application phase in the server, use `gnutls_ia_endphase_send()'. The client cannot end an application phase unilaterally; rather, a client is required to respond with an endphase of its own if gnutls_ia_recv indicates that the server has sent one. If the EINTR is returned by the internal push function (the default is `send()'} then `GNUTLS_E_INTERRUPTED' will be returned. If `GNUTLS_E_INTERRUPTED' or `GNUTLS_E_AGAIN' is returned, you must call this function again, with the same parameters; alternatively you could provide a `NULL' pointer for data, and 0 for size. *Returns:* The number of bytes sent, or a negative error code. gnutls_ia_set_client_avp_function --------------------------------- -- Function: void gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t CRED, gnutls_ia_avp_func AVP_FUNC) CRED: is a `gnutls_ia_client_credentials_t' structure. AVP_FUNC: is the callback function Set the TLS/IA AVP callback handler used for the session. The AVP callback is called to process AVPs received from the server, and to get a new AVP to send to the server. The callback's function form is: int (*avp_func) (gnutls_session_t session, void *ptr, const char *last, size_t lastlen, char **next, size_t *nextlen); The `session' parameter is the `gnutls_session_t' structure corresponding to the current session. The `ptr' parameter is the application hook pointer, set through `gnutls_ia_set_client_avp_ptr()'. The AVP received from the server is present in `last' of `lastlen' size, which will be `NULL' on the first invocation. The newly allocated output AVP to send to the server should be placed in *`next' of *`nextlen' size. The callback may invoke `gnutls_ia_permute_inner_secret()' to mix any generated session keys with the TLS/IA inner secret. Return 0 (`GNUTLS_IA_APPLICATION_PAYLOAD') on success, or a negative error code to abort the TLS/IA handshake. Note that the callback must use allocate the `next' parameter using `gnutls_malloc()', because it is released via `gnutls_free()' by the TLS/IA handshake function. gnutls_ia_set_client_avp_ptr ---------------------------- -- Function: void gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t CRED, void * PTR) CRED: is a `gnutls_ia_client_credentials_t' structure. PTR: is the pointer Sets the pointer that will be provided to the TLS/IA callback function as the first argument. gnutls_ia_set_server_avp_function --------------------------------- -- Function: void gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t CRED, gnutls_ia_avp_func AVP_FUNC) CRED: is a `gnutls_ia_server_credentials_t' structure. Set the TLS/IA AVP callback handler used for the session. The callback's function form is: int (*avp_func) (gnutls_session_t session, void *ptr, const char *last, size_t lastlen, char **next, size_t *nextlen); The `session' parameter is the `gnutls_session_t' structure corresponding to the current session. The `ptr' parameter is the application hook pointer, set through `gnutls_ia_set_server_avp_ptr()'. The AVP received from the client is present in `last' of `lastlen' size. The newly allocated output AVP to send to the client should be placed in *`next' of *`nextlen' size. The AVP callback is called to process incoming AVPs from the client, and to get a new AVP to send to the client. It can also be used to instruct the TLS/IA handshake to do go into the Intermediate or Final phases. It return a negative error code, or an `gnutls_ia_apptype_t' message type. The callback may invoke `gnutls_ia_permute_inner_secret()' to mix any generated session keys with the TLS/IA inner secret. Specifically, return `GNUTLS_IA_APPLICATION_PAYLOAD' (0) to send another AVP to the client, return `GNUTLS_IA_INTERMEDIATE_PHASE_FINISHED' (1) to indicate that an IntermediatePhaseFinished message should be sent, and return `GNUTLS_IA_FINAL_PHASE_FINISHED' (2) to indicate that an FinalPhaseFinished message should be sent. In the last two cases, the contents of the `next' and `nextlen' parameter is not used. Note that the callback must use allocate the `next' parameter using `gnutls_malloc()', because it is released via `gnutls_free()' by the TLS/IA handshake function. gnutls_ia_set_server_avp_ptr ---------------------------- -- Function: void gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t CRED, void * PTR) CRED: is a `gnutls_ia_client_credentials_t' structure. PTR: is the pointer Sets the pointer that will be provided to the TLS/IA callback function as the first argument. gnutls_ia_verify_endphase ------------------------- -- Function: int gnutls_ia_verify_endphase (gnutls_session_t SESSION, const char * CHECKSUM) SESSION: is a `gnutls_session_t' structure. CHECKSUM: 12-byte checksum data, received from `gnutls_ia_recv()'. Verify TLS/IA end phase checksum data. If verification fails, the `GNUTLS_A_INNER_APPLICATION_VERIFICATION' alert is sent to the other sie. This function is called when `gnutls_ia_recv()' return `GNUTLS_E_WARNING_IA_IPHF_RECEIVED' or `GNUTLS_E_WARNING_IA_FPHF_RECEIVED'. *Return value:* Return 0 on successful verification, or an error code. If the checksum verification of the end phase message fails, `GNUTLS_E_IA_VERIFY_FAILED' is returned.  File: gnutls.info, Node: Error codes and descriptions, Prev: TLS Inner Application (TLS/IA) functions, Up: Function reference 9.6 Error Codes and Descriptions ================================ The error codes used throughout the library are described below. The return code `GNUTLS_E_SUCCESS' indicate successful operation, and is guaranteed to have the value 0, so you can use it in logical expressions. `GNUTLS_E_AGAIN:' Function was interrupted. `GNUTLS_E_ASN1_DER_ERROR:' ASN1 parser: Error in DER parsing. `GNUTLS_E_ASN1_DER_OVERFLOW:' ASN1 parser: Overflow in DER parsing. `GNUTLS_E_ASN1_ELEMENT_NOT_FOUND:' ASN1 parser: Element was not found. `GNUTLS_E_ASN1_GENERIC_ERROR:' ASN1 parser: Generic parsing error. `GNUTLS_E_ASN1_IDENTIFIER_NOT_FOUND:' ASN1 parser: Identifier was not found `GNUTLS_E_ASN1_SYNTAX_ERROR:' ASN1 parser: Syntax error. `GNUTLS_E_ASN1_TAG_ERROR:' ASN1 parser: Error in TAG. `GNUTLS_E_ASN1_TAG_IMPLICIT:' ASN1 parser: error in implicit tag `GNUTLS_E_ASN1_TYPE_ANY_ERROR:' ASN1 parser: Error in type 'ANY'. `GNUTLS_E_ASN1_VALUE_NOT_FOUND:' ASN1 parser: Value was not found. `GNUTLS_E_ASN1_VALUE_NOT_VALID:' ASN1 parser: Value is not valid. `GNUTLS_E_BASE64_DECODING_ERROR:' Base64 decoding error. `GNUTLS_E_BASE64_ENCODING_ERROR:' Base64 encoding error. `GNUTLS_E_BASE64_UNEXPECTED_HEADER_ERROR:' Base64 unexpected header error. `GNUTLS_E_CERTIFICATE_ERROR:' Error in the certificate. `GNUTLS_E_CERTIFICATE_KEY_MISMATCH:' The certificate and the given key do not match. `GNUTLS_E_COMPRESSION_FAILED:' Compression of the TLS record packet has failed. `GNUTLS_E_CONSTRAINT_ERROR:' Some constraint limits were reached. `GNUTLS_E_CRYPTO_ALREADY_REGISTERED:' There is already a crypto algorithm with lower priority. `GNUTLS_E_DB_ERROR:' Error in Database backend. `GNUTLS_E_DECOMPRESSION_FAILED:' Decompression of the TLS record packet has failed. `GNUTLS_E_DECRYPTION_FAILED:' Decryption has failed. `GNUTLS_E_DH_PRIME_UNACCEPTABLE:' The Diffie Hellman prime sent by the server is not acceptable (not long enough). `GNUTLS_E_ENCRYPTION_FAILED:' Encryption has failed. `GNUTLS_E_ERROR_IN_FINISHED_PACKET:' An error was encountered at the TLS Finished packet calculation. `GNUTLS_E_EXPIRED:' The requested session has expired. `GNUTLS_E_FATAL_ALERT_RECEIVED:' A TLS fatal alert has been received. `GNUTLS_E_FILE_ERROR:' Error while reading file. `GNUTLS_E_GOT_APPLICATION_DATA:' TLS Application data were received, while expecting handshake data. `GNUTLS_E_HANDSHAKE_TOO_LARGE:' The handshake data size is too large (DoS?), check gnutls_handshake_set_max_packet_length(). `GNUTLS_E_HASH_FAILED:' Hashing has failed. `GNUTLS_E_IA_VERIFY_FAILED:' Verifying TLS/IA phase checksum failed `GNUTLS_E_ILLEGAL_SRP_USERNAME:' The SRP username supplied is illegal. `GNUTLS_E_INCOMPATIBLE_GCRYPT_LIBRARY:' The gcrypt library version is too old. `GNUTLS_E_INCOMPATIBLE_LIBTASN1_LIBRARY:' The tasn1 library version is too old. `GNUTLS_E_INIT_LIBEXTRA:' The initialization of GnuTLS-extra has failed. `GNUTLS_E_INSUFFICIENT_CREDENTIALS:' Insufficient credentials for that request. `GNUTLS_E_INTERNAL_ERROR:' GnuTLS internal error. `GNUTLS_E_INTERRUPTED:' Function was interrupted. `GNUTLS_E_INVALID_PASSWORD:' The given password contains invalid characters. `GNUTLS_E_INVALID_REQUEST:' The request is invalid. `GNUTLS_E_INVALID_SESSION:' The specified session has been invalidated for some reason. `GNUTLS_E_KEY_USAGE_VIOLATION:' Key usage violation in certificate has been detected. `GNUTLS_E_LARGE_PACKET:' A large TLS record packet was received. `GNUTLS_E_LIBRARY_VERSION_MISMATCH:' The GnuTLS library version does not match the GnuTLS-extra library version. `GNUTLS_E_LZO_INIT_FAILED:' The initialization of LZO has failed. `GNUTLS_E_MAC_VERIFY_FAILED:' The Message Authentication Code verification failed. `GNUTLS_E_MEMORY_ERROR:' Internal error in memory allocation. `GNUTLS_E_MPI_PRINT_FAILED:' Could not export a large integer. `GNUTLS_E_MPI_SCAN_FAILED:' The scanning of a large integer has failed. `GNUTLS_E_NO_CERTIFICATE_FOUND:' The peer did not send any certificate. `GNUTLS_E_NO_CIPHER_SUITES:' No supported cipher suites have been found. `GNUTLS_E_NO_COMPRESSION_ALGORITHMS:' No supported compression algorithms have been found. `GNUTLS_E_NO_TEMPORARY_DH_PARAMS:' No temporary DH parameters were found. `GNUTLS_E_NO_TEMPORARY_RSA_PARAMS:' No temporary RSA parameters were found. `GNUTLS_E_OPENPGP_FINGERPRINT_UNSUPPORTED:' The OpenPGP fingerprint is not supported. `GNUTLS_E_OPENPGP_GETKEY_FAILED:' Could not get OpenPGP key. `GNUTLS_E_OPENPGP_KEYRING_ERROR:' Error loading the keyring. `GNUTLS_E_OPENPGP_SUBKEY_ERROR:' Could not find OpenPGP subkey. `GNUTLS_E_OPENPGP_UID_REVOKED:' The OpenPGP User ID is revoked. `GNUTLS_E_PKCS1_WRONG_PAD:' Wrong padding in PKCS1 packet. `GNUTLS_E_PK_DECRYPTION_FAILED:' Public key decryption has failed. `GNUTLS_E_PK_ENCRYPTION_FAILED:' Public key encryption has failed. `GNUTLS_E_PK_SIGN_FAILED:' Public key signing has failed. `GNUTLS_E_PK_SIG_VERIFY_FAILED:' Public key signature verification has failed. `GNUTLS_E_PULL_ERROR:' Error in the pull function. `GNUTLS_E_PUSH_ERROR:' Error in the push function. `GNUTLS_E_RANDOM_FAILED:' Failed to acquire random data. `GNUTLS_E_RECEIVED_ILLEGAL_EXTENSION:' An illegal TLS extension was received. `GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER:' An illegal parameter has been received. `GNUTLS_E_RECORD_LIMIT_REACHED:' The upper limit of record packet sequence numbers has been reached. Wow! `GNUTLS_E_REHANDSHAKE:' Rehandshake was requested by the peer. `GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE:' The requested data were not available. `GNUTLS_E_SHORT_MEMORY_BUFFER:' The given memory buffer is too short to hold parameters. `GNUTLS_E_SRP_PWD_ERROR:' Error in password file. `GNUTLS_E_SRP_PWD_PARSING_ERROR:' Parsing error in password file. `GNUTLS_E_SUCCESS:' Success. `GNUTLS_E_TOO_MANY_EMPTY_PACKETS:' Too many empty record packets have been received. `GNUTLS_E_UNEXPECTED_HANDSHAKE_PACKET:' An unexpected TLS handshake packet was received. `GNUTLS_E_UNEXPECTED_PACKET:' An unexpected TLS packet was received. `GNUTLS_E_UNEXPECTED_PACKET_LENGTH:' A TLS packet with unexpected length was received. `GNUTLS_E_UNKNOWN_ALGORITHM:' The specified algorithm or protocol is unknown. `GNUTLS_E_UNKNOWN_CIPHER_SUITE:' Could not negotiate a supported cipher suite. `GNUTLS_E_UNKNOWN_CIPHER_TYPE:' The cipher type is unsupported. `GNUTLS_E_UNKNOWN_COMPRESSION_ALGORITHM:' Could not negotiate a supported compression method. `GNUTLS_E_UNKNOWN_HASH_ALGORITHM:' The hash algorithm is unknown. `GNUTLS_E_UNKNOWN_PKCS_BAG_TYPE:' The PKCS structure's bag type is unknown. `GNUTLS_E_UNKNOWN_PKCS_CONTENT_TYPE:' The PKCS structure's content type is unknown. `GNUTLS_E_UNKNOWN_PK_ALGORITHM:' An unknown public key algorithm was encountered. `GNUTLS_E_UNSUPPORTED_CERTIFICATE_TYPE:' The certificate type is not supported. `GNUTLS_E_UNSUPPORTED_VERSION_PACKET:' A record packet with illegal version was received. `GNUTLS_E_UNWANTED_ALGORITHM:' An algorithm that is not enabled was negotiated. `GNUTLS_E_WARNING_ALERT_RECEIVED:' A TLS warning alert has been received. `GNUTLS_E_WARNING_IA_FPHF_RECEIVED:' Received a TLS/IA Final Phase Finished message `GNUTLS_E_WARNING_IA_IPHF_RECEIVED:' Received a TLS/IA Intermediate Phase Finished message `GNUTLS_E_X509_UNKNOWN_SAN:' Unknown Subject Alternative name in X.509 certificate. `GNUTLS_E_X509_UNSUPPORTED_ATTRIBUTE:' The certificate has unsupported attributes. `GNUTLS_E_X509_UNSUPPORTED_CRITICAL_EXTENSION:' Unsupported critical extension in X.509 certificate. `GNUTLS_E_X509_UNSUPPORTED_OID:' The OID is not supported.  File: gnutls.info, Node: All the supported ciphersuites in GnuTLS, Next: Guile Bindings, Prev: Function reference, Up: Top 10 All the Supported Ciphersuites in GnuTLS ******************************************* Available cipher suites: TLS_ANON_DH_ARCFOUR_MD5 0x00 0x18 SSL3.0 TLS_ANON_DH_3DES_EDE_CBC_SHA1 0x00 0x1b SSL3.0 TLS_ANON_DH_AES_128_CBC_SHA1 0x00 0x34 SSL3.0 TLS_ANON_DH_AES_256_CBC_SHA1 0x00 0x3a SSL3.0 TLS_ANON_DH_CAMELLIA_128_CBC_SHA1 0x00 0x46 TLS1.0 TLS_ANON_DH_CAMELLIA_256_CBC_SHA1 0x00 0x89 TLS1.0 TLS_PSK_SHA_ARCFOUR_SHA1 0x00 0x8a TLS1.0 TLS_PSK_SHA_3DES_EDE_CBC_SHA1 0x00 0x8b TLS1.0 TLS_PSK_SHA_AES_128_CBC_SHA1 0x00 0x8c TLS1.0 TLS_PSK_SHA_AES_256_CBC_SHA1 0x00 0x8d TLS1.0 TLS_DHE_PSK_SHA_ARCFOUR_SHA1 0x00 0x8e TLS1.0 TLS_DHE_PSK_SHA_3DES_EDE_CBC_SHA1 0x00 0x8f TLS1.0 TLS_DHE_PSK_SHA_AES_128_CBC_SHA1 0x00 0x90 TLS1.0 TLS_DHE_PSK_SHA_AES_256_CBC_SHA1 0x00 0x91 TLS1.0 TLS_SRP_SHA_3DES_EDE_CBC_SHA1 0xc0 0x1a TLS1.0 TLS_SRP_SHA_AES_128_CBC_SHA1 0xc0 0x1d TLS1.0 TLS_SRP_SHA_AES_256_CBC_SHA1 0xc0 0x20 TLS1.0 TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA1 0xc0 0x1c TLS1.0 TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA1 0xc0 0x1b TLS1.0 TLS_SRP_SHA_DSS_AES_128_CBC_SHA1 0xc0 0x1f TLS1.0 TLS_SRP_SHA_RSA_AES_128_CBC_SHA1 0xc0 0x1e TLS1.0 TLS_SRP_SHA_DSS_AES_256_CBC_SHA1 0xc0 0x22 TLS1.0 TLS_SRP_SHA_RSA_AES_256_CBC_SHA1 0xc0 0x21 TLS1.0 TLS_DHE_DSS_ARCFOUR_SHA1 0x00 0x66 TLS1.0 TLS_DHE_DSS_3DES_EDE_CBC_SHA1 0x00 0x13 SSL3.0 TLS_DHE_DSS_AES_128_CBC_SHA1 0x00 0x32 SSL3.0 TLS_DHE_DSS_AES_256_CBC_SHA1 0x00 0x38 SSL3.0 TLS_DHE_DSS_CAMELLIA_128_CBC_SHA1 0x00 0x44 TLS1.0 TLS_DHE_DSS_CAMELLIA_256_CBC_SHA1 0x00 0x87 TLS1.0 TLS_DHE_RSA_3DES_EDE_CBC_SHA1 0x00 0x16 SSL3.0 TLS_DHE_RSA_AES_128_CBC_SHA1 0x00 0x33 SSL3.0 TLS_DHE_RSA_AES_256_CBC_SHA1 0x00 0x39 SSL3.0 TLS_DHE_RSA_CAMELLIA_128_CBC_SHA1 0x00 0x45 TLS1.0 TLS_DHE_RSA_CAMELLIA_256_CBC_SHA1 0x00 0x88 TLS1.0 TLS_RSA_NULL_MD5 0x00 0x01 SSL3.0 TLS_RSA_EXPORT_ARCFOUR_40_MD5 0x00 0x03 SSL3.0 TLS_RSA_ARCFOUR_SHA1 0x00 0x05 SSL3.0 TLS_RSA_ARCFOUR_MD5 0x00 0x04 SSL3.0 TLS_RSA_3DES_EDE_CBC_SHA1 0x00 0x0a SSL3.0 TLS_RSA_AES_128_CBC_SHA1 0x00 0x2f SSL3.0 TLS_RSA_AES_256_CBC_SHA1 0x00 0x35 SSL3.0 TLS_RSA_CAMELLIA_128_CBC_SHA1 0x00 0x41 TLS1.0 TLS_RSA_CAMELLIA_256_CBC_SHA1 0x00 0x84 TLS1.0 Available certificate types: * X.509 * OPENPGP Available protocols: * SSL3.0 * TLS1.0 * TLS1.1 * TLS1.2 Available ciphers: * AES-256-CBC * AES-128-CBC * 3DES-CBC * DES-CBC * ARCFOUR-128 * ARCFOUR-40 * RC2-40 * CAMELLIA-256-CBC * CAMELLIA-128-CBC * NULL Available MAC algorithms: * SHA1 * MD5 * SHA256 * SHA384 * SHA512 * MD2 * RIPEMD160 * NULL Available key exchange methods: * ANON-DH * RSA * RSA-EXPORT * DHE-RSA * DHE-DSS * SRP-DSS * SRP-RSA * SRP * PSK * DHE-PSK Available public key algorithms: * RSA * DSA Available public key signature algorithms: * RSA-SHA * RSA-SHA256 * RSA-SHA384 * RSA-SHA512 * RSA-RMD160 * DSA-SHA * RSA-MD5 * RSA-MD2 Available compression methods: * DEFLATE * NULL Some additional information regarding some of the algorithms: `RSA' RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir and Leonard Adleman. It can be used with any hash functions. `DSA' DSA is the USA's Digital Signature Standard. It uses only the SHA-1 hash algorithm. `MD2' MD2 is a cryptographic hash algorithm designed by Ron Rivest. It is optimized for 8-bit processors. Outputs 128 bits of data. There are no known weaknesses of this algorithm but since this algorithm is rarely used and not really studied it should not be used today. `MD5' MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs 128 bits of data. It is considered to be broken. `SHA-1' SHA is a cryptographic hash algorithm designed by NSA. Outputs 160 bits of data. It is also considered to be broken, though no practical attacks have been found. `RMD160' RIPEMD is a cryptographic hash algorithm developed in the framework of the EU project RIPE. Outputs 160 bits of data.  File: gnutls.info, Node: Guile Bindings, Next: Internal architecture of GnuTLS, Prev: All the supported ciphersuites in GnuTLS, Up: Top 11 Guile Bindings ***************** This chapter describes the GNU Guile (http://www.gnu.org/software/guile/) Scheme programming interface to GnuTLS. The reader is assumed to have basic knowledge of the protocol and library. Details missing from this chapter may be found in *Note the C API reference: Function reference. At this stage, not all the C functions are available from Scheme, but a large subset thereof is available. * Menu: * Guile Preparations:: Note on installation and environment. * Guile API Conventions:: Naming conventions and other idiosyncrasies. * Guile Examples:: Quick start. * Guile Reference:: The Scheme GnuTLS programming interface.  File: gnutls.info, Node: Guile Preparations, Next: Guile API Conventions, Up: Guile Bindings 11.1 Guile Preparations ======================= The GnuTLS Guile bindings are by default installed under the GnuTLS installation directory (e.g., typically `/usr/local/share/guile/site/'). Normally Guile will not find the module there without help. You may experience something like this: $ guile guile> (use-modules (gnutls)) : no code for module (gnutls) guile> There are two ways to solve this. The first is to make sure that when building GnuTLS, the Guile bindings will be installed in the same place where Guile looks. You may do this by using the `--with-guile-site-dir' parameter as follows: $ ./configure --with-guile-site-dir=no This will instruct GnuTLS to attempt to install the Guile bindings where Guile will look for them. It will use `guile-config info pkgdatadir' to learn the path to use. If Guile was installed into `/usr', you may also install GnuTLS using the same prefix: $ ./configure --prefix=/usr If you want to specify the path to install the Guile bindings you can also specify the path directly: $ ./configure --with-guile-site-dir=/opt/guile/share/guile/site The second solution requires some more work but may be easier to use if you do not have system administrator rights to your machine. You need to instruct Guile so that it finds the GnuTLS Guile bindings. Either use the `GUILE_LOAD_PATH' environment variable as follows: $ GUILE_LOAD_PATH="/usr/local/share/guile/site:$GUILE_LOAD_PATH" guile guile> (use-modules (gnutls)) guile> Alternatively, you can modify Guile's `%load-path' variable (*note Guile's run-time options: (guile)Build Config.). At this point, you might get an error regarding `libguile-gnutls-v-0' similar to: gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "libguile-gnutls-v-0" "scm_init_gnutls"): gnutls.scm:361:1: file: "libguile-gnutls-v-0", message: "libguile-gnutls-v-0.so: cannot open shared object file: No such file or directory" In this case, you will need to modify the run-time linker path, for example as follows: $ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile guile> (use-modules (gnutls)) guile>  File: gnutls.info, Node: Guile API Conventions, Next: Guile Examples, Prev: Guile Preparations, Up: Guile Bindings 11.2 Guile API Conventions ========================== This chapter details the conventions used by Guile API, as well as specificities of the mapping of the C API to Scheme. * Menu: * Enumerates and Constants:: Representation of C-side constants. * Procedure Names:: Naming conventions. * Representation of Binary Data:: Binary data buffers. * Input and Output:: Input and output. * Exception Handling:: Exceptions.  File: gnutls.info, Node: Enumerates and Constants, Next: Procedure Names, Up: Guile API Conventions 11.2.1 Enumerates and Constants ------------------------------- Lots of enumerates and constants are used in the GnuTLS C API. For each C enumerate type, a disjoint Scheme type is used--thus, enumerate values and constants are not represented by Scheme symbols nor by integers. This makes it impossible to use an enumerate value of the wrong type on the Scheme side: such errors are automatically detected by type-checking. The enumerate values are bound to variables exported by the `(gnutls)' and `(gnutls extra)' modules. These variables are named according to the following convention: * All variable names are lower-case; the underscore `_' character used in the C API is replaced by hyphen `-'. * All variable names are prepended by the name of the enumerate type and the slash `/' character. * In some cases, the variable name is made more explicit than the one of the C API, e.g., by avoid abbreviations. Consider for instance this C-side enumerate: typedef enum { GNUTLS_CRD_CERTIFICATE = 1, GNUTLS_CRD_ANON, GNUTLS_CRD_SRP, GNUTLS_CRD_PSK, GNUTLS_CRD_IA } gnutls_credentials_type_t; The corresponding Scheme values are bound to the following variables exported by the `(gnutls)' module: credentials/certificate credentials/anonymous credentials/srp credentials/psk credentials/ia Hopefully, most variable names can be deduced from this convention. Scheme-side "enumerate" values can be compared using `eq?' (*note equality predicates: (guile)Equality.). Consider the following example: (let ((session (make-session connection-end/client))) ;; ;; ... ;; ;; Check the ciphering algorithm currently used by SESSION. (if (eq? cipher/arcfour (session-cipher session)) (format #t "We're using the ARCFOUR algorithm"))) In addition, all enumerate values can be converted to a human-readable string, in a type-specific way. For instance, `(cipher->string cipher/arcfour)' yields `"ARCFOUR 128"', while `(key-usage->string key-usage/digital-signature)' yields `"digital-signature"'. Note that these strings may not be sufficient for use in a user interface since they are fairly concise and not internationalized.  File: gnutls.info, Node: Procedure Names, Next: Representation of Binary Data, Prev: Enumerates and Constants, Up: Guile API Conventions 11.2.2 Procedure Names ---------------------- Unlike C functions in GnuTLS, the corresponding Scheme procedures are named in a way that is close to natural English. Abbreviations are also avoided. For instance, the Scheme procedure corresponding to `gnutls_certificate_set_dh_params' is named `set-certificate-credentials-dh-parameters!'. The `gnutls_' prefix is always omitted from variable names since a similar effect can be achieved using Guile's nifty binding renaming facilities, should it be needed (*note Using Guile Modules: (guile)Using Guile Modules.). Often Scheme procedure names differ from C function names in a way that makes it clearer what objects they operate on. For example, the Scheme procedure named `set-session-transport-port!' corresponds to `gnutls_transport_set_ptr', making it clear that this procedure applies to session.  File: gnutls.info, Node: Representation of Binary Data, Next: Input and Output, Prev: Procedure Names, Up: Guile API Conventions 11.2.3 Representation of Binary Data ------------------------------------ Many procedures operate on binary data. For instance, `pkcs3-import-dh-parameters' expects binary data as input and, similarly, procedures like `pkcs1-export-rsa-parameters' return binary data. Binary data is represented on the Scheme side using SRFI-4 homogeneous vectors (*note SRFI-4: (guile)SRFI-4.). Although any type of homogeneous vector may be used, `u8vector's (i.e., vectors of bytes) are highly recommended. As an example, generating and then exporting RSA parameters in the PEM format can be done as follows: (let* ((rsa-params (make-rsa-parameters 1024)) (raw-data (pkcs1-export-rsa-parameters rsa-params x509-certificate-format/pem))) (uniform-vector-write raw-data (open-output-file "some-file.pem"))) For an example of OpenPGP key import from a file, see *Note Importing OpenPGP Keys Guile Example::.  File: gnutls.info, Node: Input and Output, Next: Exception Handling, Prev: Representation of Binary Data, Up: Guile API Conventions 11.2.4 Input and Output ----------------------- The underlying transport of a TLS session can be any Scheme input/output port (*note Ports and File Descriptors: (guile)Ports and File Descriptors.). This has to be specified using `set-session-transport-port!'. However, for better performance, a raw file descriptor can be specified, using `set-session-transport-fd!'. For instance, if the transport layer is a socket port over an OS-provided socket, you can use the `port->fdes' or `fileno' procedure to obtain the underlying file descriptor and pass it to `set-session-transport-fd!' (*note `port->fdes' and `fileno': (guile)Ports and File Descriptors.). This would work as follows: (let ((socket (socket PF_INET SOCK_STREAM 0)) (session (make-session connection-end/client))) ;; ;; Establish a TCP connection... ;; ;; Use the file descriptor that underlies SOCKET. (set-session-transport-fd! session (fileno socket))) Once a TLS session is established, data can be communicated through it (i.e., _via_ the TLS record layer) using the port returned by `session-record-port': (let ((session (make-session connection-end/client))) ;; ;; Initialize the various parameters of SESSION, set up ;; a network connection, etc... ;; (let ((i/o (session-record-port session))) (write "Hello peer!" i/o) (let ((greetings (read i/o))) ;; ... (bye session close-request/rdwr)))) A lower-level I/O API is provided by `record-send' and `record-receive!' which take an SRFI-4 vector to represent the data sent or received. While it might improve performance, it is much less convenient than the above and should rarely be needed.  File: gnutls.info, Node: Exception Handling, Prev: Input and Output, Up: Guile API Conventions 11.2.5 Exception Handling ------------------------- GnuTLS errors are implemented as Scheme exceptions (*note exceptions in Guile: (guile)Exceptions.). Each time a GnuTLS function returns an error, an exception with key `gnutls-error' is raised. The additional arguments that are thrown include an error code and the name of the GnuTLS procedure that raised the exception. The error code is pretty much like an enumerate value: it is one of the `error/' variables exported by the `(gnutls)' module (*note Enumerates and Constants::). Exceptions can be turned into error messages using the `error->string' procedure. The following examples illustrates how GnuTLS exceptions can be handled: (let ((session (make-session connection-end/server))) ;; ;; ... ;; (catch 'gnutls-error (lambda () (handshake session)) (lambda (key err function . currently-unused) (format (current-error-port) "a GnuTLS error was raised by `~a': ~a~%" function (error->string err))))) Again, error values can be compared using `eq?': ;; `gnutls-error' handler. (lambda (key err function . currently-unused) (if (eq? err error/fatal-alert-received) (format (current-error-port) "a fatal alert was caught!~%") (format (current-error-port) "something bad happened: ~a~%" (error->string err)))) Note that the `catch' handler is currently passed only 3 arguments but future versions might provide it with additional arguments. Thus, it must be prepared to handle more than 3 arguments, as in this example.  File: gnutls.info, Node: Guile Examples, Next: Guile Reference, Prev: Guile API Conventions, Up: Guile Bindings 11.3 Guile Examples =================== This chapter provides examples that illustrate common use cases. * Menu: * Anonymous Authentication Guile Example:: Simplest client and server. * OpenPGP Authentication Guile Example:: Using OpenPGP-based authentication. * Importing OpenPGP Keys Guile Example:: Importing keys from files.  File: gnutls.info, Node: Anonymous Authentication Guile Example, Next: OpenPGP Authentication Guile Example, Up: Guile Examples 11.3.1 Anonymous Authentication Guile Example --------------------------------------------- "Anonymous authentication" is very easy to use. No certificates are needed by the communicating parties. Yet, it allows them to benefit from end-to-end encryption and integrity checks. The client-side code would look like this (assuming SOME-SOCKET is bound to an open socket port): ;; Client-side. (let ((client (make-session connection-end/client))) ;; Use the default settings. (set-session-default-priority! client) ;; Don't use certificate-based authentication. (set-session-certificate-type-priority! client '()) ;; Request the "anonymous Diffie-Hellman" key exchange method. (set-session-kx-priority! client (list kx/anon-dh)) ;; Specify the underlying socket. (set-session-transport-fd! client (fileno some-socket)) ;; Create anonymous credentials. (set-session-credentials! client (make-anonymous-client-credentials)) ;; Perform the TLS handshake with the server. (handshake client) ;; Send data over the TLS record layer. (write "hello, world!" (session-record-port client)) ;; Terminate the TLS session. (bye client close-request/rdwr)) The corresponding server would look like this (again, assuming SOME-SOCKET is bound to a socket port): ;; Server-side. (let ((server (make-session connection-end/server))) (set-session-default-priority! server) (set-session-certificate-type-priority! server '()) (set-session-kx-priority! server (list kx/anon-dh)) ;; Specify the underlying transport socket. (set-session-transport-fd! server (fileno some-socket)) ;; Create anonymous credentials. (let ((cred (make-anonymous-server-credentials)) (dh-params (make-dh-parameters 1024))) ;; Note: DH parameter generation can take some time. (set-anonymous-server-dh-parameters! cred dh-params) (set-session-credentials! server cred)) ;; Perform the TLS handshake with the client. (handshake server) ;; Receive data over the TLS record layer. (let ((message (read (session-record-port server)))) (format #t "received the following message: ~a~%" message) (bye server close-request/rdwr))) This is it!  File: gnutls.info, Node: OpenPGP Authentication Guile Example, Next: Importing OpenPGP Keys Guile Example, Prev: Anonymous Authentication Guile Example, Up: Guile Examples 11.3.2 OpenPGP Authentication Guile Example ------------------------------------------- GnuTLS allows users to authenticate using OpenPGP certificates. The relevant procedures are provided by the `(gnutls extra)' module. Using OpenPGP-based authentication is not more complicated than using anonymous authentication. It requires a bit of extra work, though, to import the OpenPGP public and private key of the client/server. Key import is omitted here and is left as an exercise to the reader (*note Importing OpenPGP Keys Guile Example::). Assuming SOME-SOCKET is bound to an open socket port and PUB and SEC are bound to the client's OpenPGP public and secret key, respectively, client-side code would look like this: ;; Client-side. (define %certs (list certificate-type/openpgp)) (let ((client (make-session connection-end/client)) (cred (make-certificate-credentials))) (set-session-default-priority! client) ;; Choose OpenPGP certificates. (set-session-certificate-type-priority! client %certs) ;; Prepare appropriate client credentials. (set-certificate-credentials-openpgp-keys! cred pub sec) (set-session-credentials! client cred) ;; Specify the underlying transport socket. (set-session-transport-fd! client (fileno some-socket)) (handshake client) (write "hello, world!" (session-record-port client)) (bye client close-request/rdwr)) Similarly, server-side code would be along these lines: ;; Server-side. (define %certs (list certificate-type/openpgp)) (let ((server (make-session connection-end/server)) (rsa (make-rsa-parameters 1024)) (dh (make-dh-parameters 1024))) (set-session-default-priority! server) ;; Choose OpenPGP certificates. (set-session-certificate-type-priority! server %certs) (let ((cred (make-certificate-credentials))) ;; Prepare credentials with RSA and Diffie-Hellman parameters. (set-certificate-credentials-dh-parameters! cred dh) (set-certificate-credentials-rsa-export-parameters! cred rsa) (set-certificate-credentials-openpgp-keys! cred pub sec) (set-session-credentials! server cred)) (set-session-transport-fd! server (fileno some-socket)) (handshake server) (let ((msg (read (session-record-port server)))) (format #t "received: ~a~%" msg) (bye server close-request/rdwr))) In practice, generating RSA parameters (and Diffie-Hellman parameters) can time a long time. Thus, you may want to generate them once and store them in a file for future re-use (*note `pkcs1-export-rsa-parameters' and `pkcs1-import-rsa-parameters': Core Interface.).  File: gnutls.info, Node: Importing OpenPGP Keys Guile Example, Prev: OpenPGP Authentication Guile Example, Up: Guile Examples 11.3.3 Importing OpenPGP Keys Guile Example ------------------------------------------- The following example provides a simple way of importing "ASCII-armored" OpenPGP keys from files, using the `import-openpgp-certificate' and `import-openpgp-private-key' procedures provided by the `(gnutls extra)' module. (use-modules (srfi srfi-4) (gnutls extra)) (define (import-key-from-file import-proc file) ;; Import OpenPGP key from FILE using IMPORT-PROC. ;; Prepare a u8vector large enough to hold the raw ;; key contents. (let* ((size (stat:size (stat path))) (raw (make-u8vector size))) ;; Fill in the u8vector with the contents of FILE. (uniform-vector-read! raw (open-input-file file)) ;; Pass the u8vector to the import procedure. (import-proc raw openpgp-certificate-format/base64))) (define (import-public-key-from-file file) (import-key-from-file import-openpgp-certificate file)) (define (import-private-key-from-file file) (import-key-from-file import-openpgp-private-key file)) The procedures `import-public-key-from-file' and `import-private-key-from-file' can be passed a file name. They return an OpenPGP public key and private key object, respectively (*note OpenPGP key objects: Extra Interface.).  File: gnutls.info, Node: Guile Reference, Prev: Guile Examples, Up: Guile Bindings 11.4 Guile Reference ==================== This chapter documents GnuTLS Scheme procedures available to Guile programmers. * Menu: * Core Interface:: Bindings for core GnuTLS. * Extra Interface:: Bindings for GnuTLS-Extra.  File: gnutls.info, Node: Core Interface, Next: Extra Interface, Up: Guile Reference 11.4.1 Core Interface --------------------- This section lists the Scheme procedures exported by the `(gnutls)' module (*note The Guile module system: (guile)The Guile module system.). This module is licenced under the GNU Lesser General Public Licence, version 2.1 or later. -- Scheme Procedure: set-log-level! level Enable GnuTLS logging up to LEVEL (an integer). -- Scheme Procedure: set-log-procedure! proc Use PROC (a two-argument procedure) as the global GnuTLS log procedure. -- Scheme Procedure: x509-certificate-subject-alternative-name cert index Return two values: the alternative name type for CERT (i.e., one of the `x509-subject-alternative-name/' values) and the actual subject alternative name (a string) at INDEX. Both values are `#f' if no alternative name is available at INDEX. -- Scheme Procedure: x509-certificate-subject-key-id cert Return the subject key ID (a u8vector) for CERT. -- Scheme Procedure: x509-certificate-authority-key-id cert Return the key ID (a u8vector) of the X.509 certificate authority of CERT. -- Scheme Procedure: x509-certificate-key-id cert Return a statistically unique ID (a u8vector) for CERT that depends on its public key parameters. This is normally a 20-byte SHA-1 hash. -- Scheme Procedure: x509-certificate-version cert Return the version of CERT. -- Scheme Procedure: x509-certificate-key-usage cert Return the key usage of CERT (i.e., a list of `key-usage/' values), or the empty list if CERT does not contain such information. -- Scheme Procedure: x509-certificate-public-key-algorithm cert Return two values: the public key algorithm (i.e., one of the `pk-algorithm/' values) of CERT and the number of bits used. -- Scheme Procedure: x509-certificate-signature-algorithm cert Return the signature algorithm used by CERT (i.e., one of the `sign-algorithm/' values). -- Scheme Procedure: x509-certificate-matches-hostname? cert hostname Return true if CERT matches HOSTNAME, a string denoting a DNS host name. This is the basic implementation of RFC 2818 (http://tools.ietf.org/html/rfc2818) (aka. HTTPS). -- Scheme Procedure: x509-certificate-issuer-dn-oid cert index Return the OID (a string) at INDEX from CERT's issuer DN. Return `#f' if no OID is available at INDEX. -- Scheme Procedure: x509-certificate-dn-oid cert index Return OID (a string) at INDEX from CERT. Return `#f' if no OID is available at INDEX. -- Scheme Procedure: x509-certificate-issuer-dn cert Return the distinguished name (DN) of X.509 certificate CERT. -- Scheme Procedure: x509-certificate-dn cert Return the distinguished name (DN) of X.509 certificate CERT. The form of the DN is as described in RFC 2253 (http://tools.ietf.org/html/rfc2253). -- Scheme Procedure: pkcs8-import-x509-private-key data format [pass [encrypted]] Return a new X.509 private key object resulting from the import of DATA (a uniform array) according to FORMAT. Optionally, if PASS is not `#f', it should be a string denoting a passphrase. ENCRYPTED tells whether the private key is encrypted (`#t' by default). -- Scheme Procedure: import-x509-private-key data format Return a new X.509 private key object resulting from the import of DATA (a uniform array) according to FORMAT. -- Scheme Procedure: import-x509-certificate data format Return a new X.509 certificate object resulting from the import of DATA (a uniform array) according to FORMAT. -- Scheme Procedure: server-session-psk-username session Return the username associated with PSK server session SESSION. -- Scheme Procedure: set-psk-client-credentials! cred username key key-format Set the client credentials for CRED, a PSK client credentials object. -- Scheme Procedure: make-psk-client-credentials Return a new PSK client credentials object. -- Scheme Procedure: set-psk-server-credentials-file! cred file Use FILE as the password file for PSK server credentials CRED. -- Scheme Procedure: make-psk-server-credentials Return new PSK server credentials. -- Scheme Procedure: peer-certificate-status session Verify the peer certificate for SESSION and return a list of `certificate-status' values (such as `certificate-status/revoked'), or the empty list if the certificate is valid. -- Scheme Procedure: set-certificate-credentials-verify-flags! cred [flags...] Set the certificate verification flags to FLAGS, a series of `certificate-verify' values. -- Scheme Procedure: set-certificate-credentials-verify-limits! cred max-bits max-depth Set the verification limits of `peer-certificate-status' for certificate credentials CRED to MAX_BITS bits for an acceptable certificate and MAX_DEPTH as the maximum depth of a certificate chain. -- Scheme Procedure: set-certificate-credentials-x509-keys! cred certs privkey Have certificate credentials CRED use the X.509 certificates listed in CERTS and X.509 private key PRIVKEY. -- Scheme Procedure: set-certificate-credentials-x509-key-data! cred cert key format Use X.509 certificate CERT and private key KEY, both uniform arrays containing the X.509 certificate and key in format FORMAT, for certificate credentials CRED. -- Scheme Procedure: set-certificate-credentials-x509-crl-data! cred data format Use DATA (a uniform array) as the X.509 CRL (certificate revocation list) database for CRED. On success, return the number of CRLs processed. -- Scheme Procedure: set-certificate-credentials-x509-trust-data! cred data format Use DATA (a uniform array) as the X.509 trust database for CRED. On success, return the number of certificates processed. -- Scheme Procedure: set-certificate-credentials-x509-crl-file! cred file format Use FILE as the X.509 CRL (certificate revocation list) file for certificate credentials CRED. On success, return the number of CRLs processed. -- Scheme Procedure: set-certificate-credentials-x509-trust-file! cred file format Use FILE as the X.509 trust file for certificate credentials CRED. On success, return the number of certificates processed. -- Scheme Procedure: set-certificate-credentials-x509-key-files! cred cert-file key-file format Use FILE as the password file for PSK server credentials CRED. -- Scheme Procedure: set-certificate-credentials-rsa-export-parameters! cred rsa-params Use RSA parameters RSA_PARAMS for certificate credentials CRED. -- Scheme Procedure: set-certificate-credentials-dh-parameters! cred dh-params Use Diffie-Hellman parameters DH_PARAMS for certificate credentials CRED. -- Scheme Procedure: make-certificate-credentials Return new certificate credentials (i.e., for use with either X.509 or OpenPGP certificates. -- Scheme Procedure: pkcs1-export-rsa-parameters rsa-params format Export Diffie-Hellman parameters RSA_PARAMS in PKCS1 format according for FORMAT (an `x509-certificate-format' value). Return a `u8vector' containing the result. -- Scheme Procedure: pkcs1-import-rsa-parameters array format Import Diffie-Hellman parameters in PKCS1 format (further specified by FORMAT, an `x509-certificate-format' value) from ARRAY (a homogeneous array) and return a new `rsa-params' object. -- Scheme Procedure: make-rsa-parameters bits Return new RSA parameters. -- Scheme Procedure: set-anonymous-server-dh-parameters! cred dh-params Set the Diffie-Hellman parameters of anonymous server credentials CRED. -- Scheme Procedure: make-anonymous-client-credentials Return anonymous client credentials. -- Scheme Procedure: make-anonymous-server-credentials Return anonymous server credentials. -- Scheme Procedure: set-session-dh-prime-bits! session bits Use BITS DH prime bits for SESSION. -- Scheme Procedure: pkcs3-export-dh-parameters dh-params format Export Diffie-Hellman parameters DH_PARAMS in PKCS3 format according for FORMAT (an `x509-certificate-format' value). Return a `u8vector' containing the result. -- Scheme Procedure: pkcs3-import-dh-parameters array format Import Diffie-Hellman parameters in PKCS3 format (further specified by FORMAT, an `x509-certificate-format' value) from ARRAY (a homogeneous array) and return a new `dh-params' object. -- Scheme Procedure: make-dh-parameters bits Return new Diffie-Hellman parameters. -- Scheme Procedure: set-session-transport-port! session port Use PORT as the input/output port for SESSION. -- Scheme Procedure: set-session-transport-fd! session fd Use file descriptor FD as the underlying transport for SESSION. -- Scheme Procedure: session-record-port session Return a read-write port that may be used to communicate over SESSION. All invocations of `session-port' on a given session return the same object (in the sense of `eq?'). -- Scheme Procedure: record-receive! session array Receive data from SESSION into ARRAY, a uniform homogeneous array. Return the number of bytes actually received. -- Scheme Procedure: record-send session array Send the record constituted by ARRAY through SESSION. -- Scheme Procedure: set-session-credentials! session cred Use CRED as SESSION's credentials. -- Scheme Procedure: cipher-suite->string kx cipher mac Return the name of the given cipher suite. -- Scheme Procedure: set-session-default-export-priority! session Have SESSION use the default export priorities. -- Scheme Procedure: set-session-default-priority! session Have SESSION use the default priorities. -- Scheme Procedure: set-session-certificate-type-priority! session items Use ITEMS (a list) as the list of preferred certificate-type for SESSION. -- Scheme Procedure: set-session-protocol-priority! session items Use ITEMS (a list) as the list of preferred protocol for SESSION. -- Scheme Procedure: set-session-kx-priority! session items Use ITEMS (a list) as the list of preferred kx for SESSION. -- Scheme Procedure: set-session-compression-method-priority! session items Use ITEMS (a list) as the list of preferred compression-method for SESSION. -- Scheme Procedure: set-session-mac-priority! session items Use ITEMS (a list) as the list of preferred mac for SESSION. -- Scheme Procedure: set-session-cipher-priority! session items Use ITEMS (a list) as the list of preferred cipher for SESSION. -- Scheme Procedure: set-server-session-certificate-request! session request Tell how SESSION, a server-side session, should deal with certificate requests. REQUEST should be either `certificate-request/request' or `certificate-request/require'. -- Scheme Procedure: session-our-certificate-chain session Return our certificate chain for SESSION (as sent to the peer) in raw format (a u8vector). In the case of OpenPGP there is exactly one certificate. Return the empty list if no certificate was used. -- Scheme Procedure: session-peer-certificate-chain session Return the a list of certificates in raw format (u8vectors) where the first one is the peer's certificate. In the case of OpenPGP, there is always exactly one certificate. In the case of X.509, subsequent certificates indicate form a certificate chain. Return the empty list if no certificate was sent. -- Scheme Procedure: session-client-authentication-type session Return the client authentication type (a `credential-type' value) used in SESSION. -- Scheme Procedure: session-server-authentication-type session Return the server authentication type (a `credential-type' value) used in SESSION. -- Scheme Procedure: session-authentication-type session Return the authentication type (a `credential-type' value) used by SESSION. -- Scheme Procedure: session-protocol session Return the protocol used by SESSION. -- Scheme Procedure: session-certificate-type session Return SESSION's certificate type. -- Scheme Procedure: session-compression-method session Return SESSION's compression method. -- Scheme Procedure: session-mac session Return SESSION's MAC. -- Scheme Procedure: session-kx session Return SESSION's kx. -- Scheme Procedure: session-cipher session Return SESSION's cipher. -- Scheme Procedure: alert-send session level alert Send ALERT via SESSION. -- Scheme Procedure: alert-get session Get an aleter from SESSION. -- Scheme Procedure: rehandshake session Perform a re-handshaking for SESSION. -- Scheme Procedure: handshake session Perform a handshake for SESSION. -- Scheme Procedure: bye session how Close SESSION according to HOW. -- Scheme Procedure: make-session end Return a new session for connection end END, either `connection-end/server' or `connection-end/client'. -- Scheme Procedure: gnutls-version Return a string denoting the version number of the underlying GnuTLS library, e.g., `"1.7.2"'. -- Scheme Procedure: x509-private-key? obj Return true if OBJ is of type `x509-private-key'. -- Scheme Procedure: x509-certificate? obj Return true if OBJ is of type `x509-certificate'. -- Scheme Procedure: psk-client-credentials? obj Return true if OBJ is of type `psk-client-credentials'. -- Scheme Procedure: psk-server-credentials? obj Return true if OBJ is of type `psk-server-credentials'. -- Scheme Procedure: srp-client-credentials? obj Return true if OBJ is of type `srp-client-credentials'. -- Scheme Procedure: srp-server-credentials? obj Return true if OBJ is of type `srp-server-credentials'. -- Scheme Procedure: certificate-credentials? obj Return true if OBJ is of type `certificate-credentials'. -- Scheme Procedure: rsa-parameters? obj Return true if OBJ is of type `rsa-parameters'. -- Scheme Procedure: dh-parameters? obj Return true if OBJ is of type `dh-parameters'. -- Scheme Procedure: anonymous-server-credentials? obj Return true if OBJ is of type `anonymous-server-credentials'. -- Scheme Procedure: anonymous-client-credentials? obj Return true if OBJ is of type `anonymous-client-credentials'. -- Scheme Procedure: session? obj Return true if OBJ is of type `session'. -- Scheme Procedure: error->string enumval Return a string describing ENUMVAL, a `error' value. -- Scheme Procedure: certificate-verify->string enumval Return a string describing ENUMVAL, a `certificate-verify' value. -- Scheme Procedure: key-usage->string enumval Return a string describing ENUMVAL, a `key-usage' value. -- Scheme Procedure: psk-key-format->string enumval Return a string describing ENUMVAL, a `psk-key-format' value. -- Scheme Procedure: sign-algorithm->string enumval Return a string describing ENUMVAL, a `sign-algorithm' value. -- Scheme Procedure: pk-algorithm->string enumval Return a string describing ENUMVAL, a `pk-algorithm' value. -- Scheme Procedure: x509-subject-alternative-name->string enumval Return a string describing ENUMVAL, a `x509-subject-alternative-name' value. -- Scheme Procedure: x509-certificate-format->string enumval Return a string describing ENUMVAL, a `x509-certificate-format' value. -- Scheme Procedure: certificate-type->string enumval Return a string describing ENUMVAL, a `certificate-type' value. -- Scheme Procedure: protocol->string enumval Return a string describing ENUMVAL, a `protocol' value. -- Scheme Procedure: close-request->string enumval Return a string describing ENUMVAL, a `close-request' value. -- Scheme Procedure: certificate-request->string enumval Return a string describing ENUMVAL, a `certificate-request' value. -- Scheme Procedure: certificate-status->string enumval Return a string describing ENUMVAL, a `certificate-status' value. -- Scheme Procedure: handshake-description->string enumval Return a string describing ENUMVAL, a `handshake-description' value. -- Scheme Procedure: alert-description->string enumval Return a string describing ENUMVAL, a `alert-description' value. -- Scheme Procedure: alert-level->string enumval Return a string describing ENUMVAL, a `alert-level' value. -- Scheme Procedure: connection-end->string enumval Return a string describing ENUMVAL, a `connection-end' value. -- Scheme Procedure: compression-method->string enumval Return a string describing ENUMVAL, a `compression-method' value. -- Scheme Procedure: digest->string enumval Return a string describing ENUMVAL, a `digest' value. -- Scheme Procedure: mac->string enumval Return a string describing ENUMVAL, a `mac' value. -- Scheme Procedure: credentials->string enumval Return a string describing ENUMVAL, a `credentials' value. -- Scheme Procedure: params->string enumval Return a string describing ENUMVAL, a `params' value. -- Scheme Procedure: kx->string enumval Return a string describing ENUMVAL, a `kx' value. -- Scheme Procedure: cipher->string enumval Return a string describing ENUMVAL, a `cipher' value.  File: gnutls.info, Node: Extra Interface, Prev: Core Interface, Up: Guile Reference 11.4.2 Extra Interface ---------------------- This section lists the Scheme procedures exported by the `(gnutls extra)' module. This module is licenced under the GNU General Public Licence, version 3 or later. -- Scheme Procedure: set-certificate-credentials-openpgp-keys! cred pub sec Use certificate PUB and secret key SEC in certificate credentials CRED. -- Scheme Procedure: openpgp-keyring-contains-key-id? keyring id Return `#f' if key ID ID is in KEYRING, `#f' otherwise. -- Scheme Procedure: import-openpgp-keyring data format Import DATA (a u8vector) according to FORMAT and return the imported keyring. -- Scheme Procedure: openpgp-certificate-usage key Return a list of values denoting the key usage of KEY. -- Scheme Procedure: openpgp-certificate-version key Return the version of the OpenPGP message format (RFC2440) honored by KEY. -- Scheme Procedure: openpgp-certificate-algorithm key Return two values: the certificate algorithm used by KEY and the number of bits used. -- Scheme Procedure: openpgp-certificate-names key Return the list of names for KEY. -- Scheme Procedure: openpgp-certificate-name key index Return the INDEXth name of KEY. -- Scheme Procedure: openpgp-certificate-fingerprint key Return a new u8vector denoting the fingerprint of KEY. -- Scheme Procedure: openpgp-certificate-fingerprint! key fpr Store in FPR (a u8vector) the fingerprint of KEY. Return the number of bytes stored in FPR. -- Scheme Procedure: openpgp-certificate-id! key id Store the ID (an 8 byte sequence) of certificate KEY in ID (a u8vector). -- Scheme Procedure: openpgp-certificate-id key Return the ID (an 8-element u8vector) of certificate KEY. -- Scheme Procedure: import-openpgp-private-key data format [pass] Return a new OpenPGP private key object resulting from the import of DATA (a uniform array) according to FORMAT. Optionally, a passphrase may be provided. -- Scheme Procedure: import-openpgp-certificate data format Return a new OpenPGP certificate object resulting from the import of DATA (a uniform array) according to FORMAT. -- Scheme Procedure: openpgp-certificate-format->string enumval Return a string describing ENUMVAL, a `openpgp-certificate-format' value. -- Scheme Procedure: openpgp-keyring? obj Return true if OBJ is of type `openpgp-keyring'. -- Scheme Procedure: openpgp-private-key? obj Return true if OBJ is of type `openpgp-private-key'. -- Scheme Procedure: openpgp-certificate? obj Return true if OBJ is of type `openpgp-certificate'.  File: gnutls.info, Node: Internal architecture of GnuTLS, Next: Copying Information, Prev: Guile Bindings, Up: Top 12 Internal Architecture of GnuTLS ********************************** This chapter is to give a brief description of the way GnuTLS works. The focus is to give an idea to potential developers and those who want to know what happens inside the black box. * Menu: * The TLS Protocol:: * TLS Handshake Protocol:: * TLS Authentication Methods:: * TLS Extension Handling:: * Cryptographic Backend::  File: gnutls.info, Node: The TLS Protocol, Next: TLS Handshake Protocol, Up: Internal architecture of GnuTLS 12.1 The TLS Protocol ===================== The main needs for the TLS protocol to be used are shown in the image below. [image src="gnutls-client-server-use-case.png"] This is being accomplished by the following object diagram. Note that since GnuTLS is being developed in C object are just structures with attributes. The operations listed are functions that require the first parameter to be that object. [image src="gnutls-objects.png"]  File: gnutls.info, Node: TLS Handshake Protocol, Next: TLS Authentication Methods, Prev: The TLS Protocol, Up: Internal architecture of GnuTLS 12.2 TLS Handshake Protocol =========================== The GnuTLS handshake protocol is implemented as a state machine that waits for input or returns immediately when the non-blocking transport layer functions are used. The main idea is shown in the following figure. [image src="gnutls-handshake-state.png"] Also the way the input is processed varies per ciphersuite. Several implementations of the internal handlers are available and *Note gnutls_handshake:: only multiplexes the input to the appropriate handler. For example a PSK ciphersuite has a different implementation of the `process_client_key_exchange' than a certificate ciphersuite. [image src="gnutls-handshake-sequence.png"]  File: gnutls.info, Node: TLS Authentication Methods, Next: TLS Extension Handling, Prev: TLS Handshake Protocol, Up: Internal architecture of GnuTLS 12.3 TLS Authentication Methods =============================== In GnuTLS authentication methods can be implemented quite easily. Since the required changes to add a new authentication method affect only the handshake protocol, a simple interface is used. An authentication method needs only to implement the functions as seen in the figure below. [image src="gnutls-mod_auth_st.png"] The functions that need to be implemented are the ones responsible for interpreting the handshake protocol messages. It is common for such functions to read data from one or more `credentials_t' structures(1) and write data, such as certificates, usernames etc. to `auth_info_t' structures. Simple examples of existing authentication methods can be seen in `auth_psk.c' for PSK ciphersuites and `auth_srp.c' for SRP ciphersuites. After implementing these functions the structure holding its pointers has to be registered in `gnutls_algorithms.c' in the `_gnutls_kx_algorithms' structure. ---------- Footnotes ---------- (1) such as the `gnutls_certificate_credentials_t' structures  File: gnutls.info, Node: TLS Extension Handling, Next: Cryptographic Backend, Prev: TLS Authentication Methods, Up: Internal architecture of GnuTLS 12.4 TLS Extension Handling =========================== As with authentication methods, the TLS extensions handlers can be implemented using the following interface. [image src="gnutls-extensions_st.png"] Here there are two functions, one for receiving the extension data and one for sending. These functions have to check internally whether they operate in client or server side. A simple example of an extension handler can be seen in `ext_srp.c' After implementing these functions, together with the extension number they handle, they have to be registered in `gnutls_extensions.c' in the `_gnutls_extensions' structure. 12.4.1 Adding a New TLS Extension --------------------------------- Adding support for a new TLS extension is done from time to time, and the process to do so is not difficult. Here are the steps you need to follow if you wish to do this yourself. For sake of discussion, let's consider adding support for the hypothetical TLS extension `foobar'. 1. Modify `configure.in' to add `--enable-foobar' or `--disable-foobar'. Which to chose depends on whether you intend to make the extension be enabled by default. Look at existing checks (i.e., SRP, authz) for how to model the code. For example: AC_MSG_CHECKING([whether to disable foobar support]) AC_ARG_ENABLE(foobar, AS_HELP_STRING([--disable-foobar], [disable foobar support]), ac_enable_foobar=no) if test x$ac_enable_foobar != xno; then AC_MSG_RESULT(no) AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar]) else ac_full=0 AC_MSG_RESULT(yes) fi AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no") 2. Add IANA extension value to `extensions_t' in `gnutls_int.h'. A good name for the value would be GNUTLS_EXTENSION_FOOBAR. Check with `http://www.iana.org/assignments/tls-extensiontype-values' for allocated values. For experiments, you could pick a number but remember that some consider it a bad idea to deploy such modified version since it will lead to interoperability problems in the future when the IANA allocates that number to someone else, or when the foobar protocol is allocated another number. 3. Add an entry to `_gnutls_extensions' in `gnutls_extensions.c'. A typical entry would be: #if ENABLE_FOOBAR GNUTLS_EXTENSION_ENTRY (GNUTLS_EXTENSION_FOOBAR, _gnutls_foobar_recv_params, _gnutls_foobar_send_params), #endif The GNUTLS_EXTENSION_FOOBAR is the integer value you added to `gnutls_int.h' earlier. The two functions are new functions that you will need to implement, most likely you'll need to add an `#include "ext_foobar.h"' as well. 4. Add new files `ext_foobar.c' and `ext_foobar.h' that implements the extension. The functions you are responsible to add are those mentioned in the previous step. As a starter, you could add this: int _gnutls_foobar_recv_params (gnutls_session_t session, const opaque * data, size_t data_size) { return 0; } int _gnutls_foobar_send_params (gnutls_session_t session, opaque * data, size_t _data_size) { return 0; } The `_gnutls_foobar_recv_params' function is responsible for parsing incoming extension data (both in the client and server). The `_gnutls_foobar_send_params' function is responsible for sending extension data (both in the client and server). If you receive length fields that doesn't match, return `GNUTLS_E_UNEXPECTED_PACKET_LENGTH'. If you receive invalid data, return `GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER'. You can use other error codes too. Return 0 on success. The function typically store some information in the `session' variable for later usage. If you need to add new fields there, check `tls_ext_st' in `gnutls_int.h' and compare with existing TLS extension specific variables. Recall that both the client and server both send and receives parameters, and your code most likely will need to do different things depending on which mode it is in. It may be useful to make this distinction explicit in the code. Thus, for example, a better template than above would be: int _gnutls_foobar_recv_params (gnutls_session_t session, const opaque * data, size_t data_size) { if (session->security_parameters.entity == GNUTLS_CLIENT) return foobar_recv_client (session, data, data_size); else return foobar_recv_server (session, data, data_size); } int _gnutls_foobar_send_params (gnutls_session_t session, opaque * data, size_t data_size) { if (session->security_parameters.entity == GNUTLS_CLIENT) return foobar_send_client (session, data, data_size); else return foobar_send_server (session, data, data_size); } The functions used would be declared as `static' functions, of the appropriate prototype, in the same file. When adding the files, you'll need to add them to `Makefile.am' as well, for example: if ENABLE_FOOBAR COBJECTS += ext_foobar.c HFILES += ext_foobar.h endif 5. Add API functions to enable/disable the extension. Normally the client will have one API to request use of the extension, and setting some extension specific data. The server will have one API to let the library know that it is willing to accept the extension, often this is implemented through a callback but it doesn't have to. The APIs need to be added to `includes/gnutls/gnutls.h' or `includes/gnutls/extra.h' as appropriate. It is recommended that if you don't have a requirement to use the LGPLv2.1+ license for your extension, that you place your work under the GPLv3+ license and thus in the libgnutls-extra library. You can implement the API function in the `ext_foobar.c' file, or if that file ends up becoming rather larger, add a `gnutls_foobar.c' file. 12.5 Certificate Handling ========================= What is provided by the certificate handling functions is summarized in the following diagram. [image src="gnutls-certificate-user-use-case.png"]  File: gnutls.info, Node: Cryptographic Backend, Prev: TLS Extension Handling, Up: Internal architecture of GnuTLS 12.6 Cryptographic Backend ========================== Several new systems provide hardware assisted cryptographic algorithm implementations that offer implementations some orders of magnitude faster than the software. For this reason in current releases of GnuTLS it is possible to override parts of the crypto backend or the whole. It is possible to override them both at runtime and compile time, however here we will discuss the runtime possibility. The API available for this functionality is in `gnutls/crypto.h' header file. 12.6.1 Override specific algorithms ----------------------------------- When an optimized implementation of a single algorithm is available, say a hardware assisted version of AES-CBC then the following functions can be used to register those algorithms. * *Note gnutls_crypto_single_cipher_register2:: To register a cipher algorithm. * *Note gnutls_crypto_single_mac_register2:: To register a MAC algorithm. *Note gnutls_crypto_single_digest_register2:: To register a digest (hash) algorithm. Those registration functions will only replace the specified algorithm and leave the rest of subsystem intact. 12.6.2 Override parts of the backend ------------------------------------ In some systems, such as embedded ones, it might be desirable to override big parts of the cryptographic backend, or even all of them. For this reason the following functions are provided. * *Note gnutls_crypto_cipher_register2:: To override the cryptographic algorithms backend. * *Note gnutls_crypto_mac_register2:: To override the MAC algorithms backend. * *Note gnutls_crypto_digest_register2:: To override the digest algorithms backend. * *Note gnutls_crypto_rnd_register2:: To override the random number generator backend. * *Note gnutls_crypto_bigint_register2:: To override the big number number operations backend. * *Note gnutls_crypto_pk_register2:: To override the public key encryption backend. This is tight to the big number operations so either both of them should be updated or care must be taken to use the same format. If all of them are used then GnuTLS will no longer use libgcrypt.  File: gnutls.info, Node: Copying Information, Next: Concept Index, Prev: Internal architecture of GnuTLS, Up: Top Appendix A Copying Information ****************************** * Menu: * GNU Free Documentation License:: License for copying this manual. * GNU LGPL:: License for copying the core GnuTLS library. * GNU GPL:: License for copying GNUTLS extra and tools.  File: gnutls.info, Node: GNU Free Documentation License, Next: GNU LGPL, Up: Copying Information A.1 GNU Free Documentation License ================================== Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See `http://www.gnu.org/copyleft/'. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. ADDENDUM: How to use this License for your documents ==================================================== To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.