From 36082a2fe36ecd800d784ae44c14f1f18c66a7e9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 09:33:12 +0200 Subject: Adding upstream version 3.7.9. Signed-off-by: Daniel Baumann --- doc/x509-api.texi | 8023 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 8023 insertions(+) create mode 100644 doc/x509-api.texi (limited to 'doc/x509-api.texi') diff --git a/doc/x509-api.texi b/doc/x509-api.texi new file mode 100644 index 0000000..4995a95 --- /dev/null +++ b/doc/x509-api.texi @@ -0,0 +1,8023 @@ + +@subheading gnutls_certificate_get_trust_list +@anchor{gnutls_certificate_get_trust_list} +@deftypefun {void} {gnutls_certificate_get_trust_list} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_trust_list_t * @var{tlist}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{tlist}: Location where to store the trust list. + +Obtains the list of trusted certificates stored in @code{res} and writes a +pointer to it to the location @code{tlist} . The pointer will point to memory +internal to @code{res} , and must not be deinitialized. It will be automatically +deallocated when the @code{res} structure is deinitialized. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_certificate_set_trust_list +@anchor{gnutls_certificate_set_trust_list} +@deftypefun {void} {gnutls_certificate_set_trust_list} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_trust_list_t @var{tlist}, unsigned @var{flags}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{tlist}: is a @code{gnutls_x509_trust_list_t} type + +@var{flags}: must be zero + +This function sets a trust list in the gnutls_certificate_credentials_t type. + +Note that the @code{tlist} will become part of the credentials +structure and must not be deallocated. It will be automatically deallocated +when the @code{res} structure is deinitialized. + +@strong{Since:} 3.2.2 +@end deftypefun + +@subheading gnutls_certificate_verification_profile_get_id +@anchor{gnutls_certificate_verification_profile_get_id} +@deftypefun {gnutls_certificate_verification_profiles_t} {gnutls_certificate_verification_profile_get_id} (const char * @var{name}) +@var{name}: is a profile name + +Convert a string to a @code{gnutls_certificate_verification_profiles_t} value. The names are +compared in a case insensitive way. + +@strong{Returns:} a @code{gnutls_certificate_verification_profiles_t} id of the specified profile, +or @code{GNUTLS_PROFILE_UNKNOWN} on failure. +@end deftypefun + +@subheading gnutls_certificate_verification_profile_get_name +@anchor{gnutls_certificate_verification_profile_get_name} +@deftypefun {const char *} {gnutls_certificate_verification_profile_get_name} (gnutls_certificate_verification_profiles_t @var{id}) +@var{id}: is a profile ID + +Convert a @code{gnutls_certificate_verification_profiles_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified profile or @code{NULL} . +@end deftypefun + +@subheading gnutls_pkcs8_info +@anchor{gnutls_pkcs8_info} +@deftypefun {int} {gnutls_pkcs8_info} (const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int * @var{schema}, unsigned int * @var{cipher}, void * @var{salt}, unsigned int * @var{salt_size}, unsigned int * @var{iter_count}, char ** @var{oid}) +@var{data}: Holds the PKCS @code{8} data + +@var{format}: the format of the PKCS @code{8} data + +@var{schema}: indicate the schema as one of @code{gnutls_pkcs_encrypt_flags_t} + +@var{cipher}: the cipher used as @code{gnutls_cipher_algorithm_t} + +@var{salt}: PBKDF2 salt (if non-NULL then @code{salt_size} initially holds its size) + +@var{salt_size}: PBKDF2 salt size + +@var{iter_count}: PBKDF2 iteration count + +@var{oid}: if non-NULL it will contain an allocated null-terminated variable with the OID + +This function will provide information on the algorithms used +in a particular PKCS @code{8} structure. If the structure algorithms +are unknown the code @code{GNUTLS_E_UNKNOWN_CIPHER_TYPE} will be returned, +and only @code{oid} , will be set. That is, @code{oid} will be set on encrypted PKCS @code{8} +structures whether supported or not. It must be deinitialized using @code{gnutls_free()} . +The other variables are only set on supported structures. + +@strong{Returns:} @code{GNUTLS_E_INVALID_REQUEST} if the provided structure isn't an encrypted key, +@code{GNUTLS_E_UNKNOWN_CIPHER_TYPE} if the structure's encryption isn't supported, or +another negative error code in case of a failure. Zero on success. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs_schema_get_name +@anchor{gnutls_pkcs_schema_get_name} +@deftypefun {const char *} {gnutls_pkcs_schema_get_name} (unsigned int @var{schema}) +@var{schema}: Holds the PKCS @code{12} or PBES2 schema (@code{gnutls_pkcs_encrypt_flags_t} ) + +This function will return a human readable description of the +PKCS12 or PBES2 schema. + +@strong{Returns:} a constraint string or @code{NULL} on error. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs_schema_get_oid +@anchor{gnutls_pkcs_schema_get_oid} +@deftypefun {const char *} {gnutls_pkcs_schema_get_oid} (unsigned int @var{schema}) +@var{schema}: Holds the PKCS @code{12} or PBES2 schema (@code{gnutls_pkcs_encrypt_flags_t} ) + +This function will return the object identifier of the +PKCS12 or PBES2 schema. + +@strong{Returns:} a constraint string or @code{NULL} on error. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_session_set_verify_output_function +@anchor{gnutls_session_set_verify_output_function} +@deftypefun {void} {gnutls_session_set_verify_output_function} (gnutls_session_t @var{session}, gnutls_verify_output_function * @var{func}) +@var{session}: is a @code{gnutls_x509_trust_list_t} type. + +@var{func}: is the callback function + +This function sets a callback to be called when the peer's certificate +chain has to be verified and full path to the trusted root has to be +printed. + +The callback's function prototype is defined in `x509.h': +int (*callback)( +gnutls_x509_crt_t cert, +gnutls_x509_crt_t issuer, +gnutls_x509_crl_t crl, +unsigned int verification_output); + +If the callback function is provided then gnutls will call it, in the +certificate verification procedure. +To verify the certificate chain and print its path uptp the trusted root, +functions such as @code{gnutls_certificate_verify_peers()} , +@code{gnutls_x509_trust_list_verify_crt()} , and @code{gnutls_x509_trust_list_verify_crt2()} +can be used. The callback is set in @code{_gnutls_verify_crt_status()} and +@code{_gnutls_pkcs11_verify_crt_status()} . + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_subject_alt_names_deinit +@anchor{gnutls_subject_alt_names_deinit} +@deftypefun {void} {gnutls_subject_alt_names_deinit} (gnutls_subject_alt_names_t @var{sans}) +@var{sans}: The alternative names + +This function will deinitialize an alternative names structure. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_subject_alt_names_get +@anchor{gnutls_subject_alt_names_get} +@deftypefun {int} {gnutls_subject_alt_names_get} (gnutls_subject_alt_names_t @var{sans}, unsigned int @var{seq}, unsigned int * @var{san_type}, gnutls_datum_t * @var{san}, gnutls_datum_t * @var{othername_oid}) +@var{sans}: The alternative names + +@var{seq}: The index of the name to get + +@var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} ) + +@var{san}: The alternative name data (should be treated as constant) + +@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} (should be treated as constant) + +This function will return a specific alternative name as stored in +the @code{sans} type. The returned values should be treated as constant +and valid for the lifetime of @code{sans} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the index is out of bounds, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_subject_alt_names_init +@anchor{gnutls_subject_alt_names_init} +@deftypefun {int} {gnutls_subject_alt_names_init} (gnutls_subject_alt_names_t * @var{sans}) +@var{sans}: The alternative names + +This function will initialize an alternative names structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_subject_alt_names_set +@anchor{gnutls_subject_alt_names_set} +@deftypefun {int} {gnutls_subject_alt_names_set} (gnutls_subject_alt_names_t @var{sans}, unsigned int @var{san_type}, const gnutls_datum_t * @var{san}, const char * @var{othername_oid}) +@var{sans}: The alternative names + +@var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} ) + +@var{san}: The alternative name data + +@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} + +This function will store the specified alternative name in +the @code{sans} . + +Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and +@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aia_deinit +@anchor{gnutls_x509_aia_deinit} +@deftypefun {void} {gnutls_x509_aia_deinit} (gnutls_x509_aia_t @var{aia}) +@var{aia}: The authority info access + +This function will deinitialize an authority info access type. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aia_get +@anchor{gnutls_x509_aia_get} +@deftypefun {int} {gnutls_x509_aia_get} (gnutls_x509_aia_t @var{aia}, unsigned int @var{seq}, gnutls_datum_t * @var{oid}, unsigned * @var{san_type}, gnutls_datum_t * @var{san}) +@var{aia}: The authority info access + +@var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.) + +@var{oid}: the type of available data; to be treated as constant. + +@var{san_type}: Will hold the type of the name of @code{gnutls_subject_alt_names_t} (may be null). + +@var{san}: the access location name; to be treated as constant (may be null). + +This function reads from the Authority Information Access type. + +The @code{seq} input parameter is used to indicate which member of the +sequence the caller is interested in. The first member is 0, the +second member 1 and so on. When the @code{seq} value is out of bounds, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +Typically @code{oid} is @code{GNUTLS_OID_AD_CAISSUERS} or @code{GNUTLS_OID_AD_OCSP} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aia_init +@anchor{gnutls_x509_aia_init} +@deftypefun {int} {gnutls_x509_aia_init} (gnutls_x509_aia_t * @var{aia}) +@var{aia}: The authority info access + +This function will initialize an authority info access type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aia_set +@anchor{gnutls_x509_aia_set} +@deftypefun {int} {gnutls_x509_aia_set} (gnutls_x509_aia_t @var{aia}, const char * @var{oid}, unsigned @var{san_type}, const gnutls_datum_t * @var{san}) +@var{aia}: The authority info access + +@var{oid}: the type of data. + +@var{san_type}: The type of the name (of @code{gnutls_subject_alt_names_t} ) + +@var{san}: The alternative name data + +This function will store the specified alternative name in +the @code{aia} type. + +Typically the value for @code{oid} should be @code{GNUTLS_OID_AD_OCSP} , or +@code{GNUTLS_OID_AD_CAISSUERS} . + +Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , and @code{GNUTLS_SAN_DNSNAME} , +are converted to ACE format when necessary. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aki_deinit +@anchor{gnutls_x509_aki_deinit} +@deftypefun {void} {gnutls_x509_aki_deinit} (gnutls_x509_aki_t @var{aki}) +@var{aki}: The authority key identifier type + +This function will deinitialize an authority key identifier. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aki_get_cert_issuer +@anchor{gnutls_x509_aki_get_cert_issuer} +@deftypefun {int} {gnutls_x509_aki_get_cert_issuer} (gnutls_x509_aki_t @var{aki}, unsigned int @var{seq}, unsigned int * @var{san_type}, gnutls_datum_t * @var{san}, gnutls_datum_t * @var{othername_oid}, gnutls_datum_t * @var{serial}) +@var{aki}: The authority key ID + +@var{seq}: The index of the name to get + +@var{san_type}: Will hold the type of the name (of @code{gnutls_subject_alt_names_t} ) + +@var{san}: The alternative name data + +@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} + +@var{serial}: The authorityCertSerialNumber number + +This function will return a specific authorityCertIssuer name as stored in +the @code{aki} type, as well as the authorityCertSerialNumber. All the returned +values should be treated as constant, and may be set to @code{NULL} when are not required. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the index is out of bounds, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aki_get_id +@anchor{gnutls_x509_aki_get_id} +@deftypefun {int} {gnutls_x509_aki_get_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{id}) +@var{aki}: The authority key ID + +@var{id}: Will hold the identifier + +This function will return the key identifier as stored in +the @code{aki} type. The identifier should be treated as constant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the index is out of bounds, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aki_init +@anchor{gnutls_x509_aki_init} +@deftypefun {int} {gnutls_x509_aki_init} (gnutls_x509_aki_t * @var{aki}) +@var{aki}: The authority key ID type + +This function will initialize an authority key ID. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aki_set_cert_issuer +@anchor{gnutls_x509_aki_set_cert_issuer} +@deftypefun {int} {gnutls_x509_aki_set_cert_issuer} (gnutls_x509_aki_t @var{aki}, unsigned int @var{san_type}, const gnutls_datum_t * @var{san}, const char * @var{othername_oid}, const gnutls_datum_t * @var{serial}) +@var{aki}: The authority key ID + +@var{san_type}: the type of the name (of @code{gnutls_subject_alt_names_t} ), may be null + +@var{san}: The alternative name data + +@var{othername_oid}: The object identifier if @code{san_type} is @code{GNUTLS_SAN_OTHERNAME} + +@var{serial}: The authorityCertSerialNumber number (may be null) + +This function will set the authorityCertIssuer name and the authorityCertSerialNumber +to be stored in the @code{aki} type. When storing multiple names, the serial +should be set on the first call, and subsequent calls should use a @code{NULL} serial. + +Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and +@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_aki_set_id +@anchor{gnutls_x509_aki_set_id} +@deftypefun {int} {gnutls_x509_aki_set_id} (gnutls_x509_aki_t @var{aki}, const gnutls_datum_t * @var{id}) +@var{aki}: The authority key ID + +@var{id}: the key identifier + +This function will set the keyIdentifier to be stored in the @code{aki} type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_cidr_to_rfc5280 +@anchor{gnutls_x509_cidr_to_rfc5280} +@deftypefun {int} {gnutls_x509_cidr_to_rfc5280} (const char * @var{cidr}, gnutls_datum_t * @var{cidr_rfc5280}) +@var{cidr}: CIDR in RFC4632 format (IP/prefix), null-terminated + +@var{cidr_rfc5280}: CIDR range converted to RFC5280 format + +This function will convert text CIDR range with prefix (such as '10.0.0.0/8') +to RFC5280 (IP address in network byte order followed by its network mask). +Works for both IPv4 and IPv6. + +The resulting object is directly usable for IP name constraints usage, +for example in functions @code{gnutls_x509_name_constraints_add_permitted} +or @code{gnutls_x509_name_constraints_add_excluded} . + +The data in datum needs to be deallocated using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.5.4 +@end deftypefun + +@subheading gnutls_x509_crl_check_issuer +@anchor{gnutls_x509_crl_check_issuer} +@deftypefun {unsigned} {gnutls_x509_crl_check_issuer} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}) +@var{crl}: is the CRL to be checked + +@var{issuer}: is the certificate of a possible issuer + +This function will check if the given CRL was issued by the given +issuer certificate. + +@strong{Returns:} true (1) if the given CRL was issued by the given issuer, +and false (0) if not. +@end deftypefun + +@subheading gnutls_x509_crl_deinit +@anchor{gnutls_x509_crl_deinit} +@deftypefun {void} {gnutls_x509_crl_deinit} (gnutls_x509_crl_t @var{crl}) +@var{crl}: The data to be deinitialized + +This function will deinitialize a CRL structure. +@end deftypefun + +@subheading gnutls_x509_crl_dist_points_deinit +@anchor{gnutls_x509_crl_dist_points_deinit} +@deftypefun {void} {gnutls_x509_crl_dist_points_deinit} (gnutls_x509_crl_dist_points_t @var{cdp}) +@var{cdp}: The CRL distribution points + +This function will deinitialize a CRL distribution points type. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crl_dist_points_get +@anchor{gnutls_x509_crl_dist_points_get} +@deftypefun {int} {gnutls_x509_crl_dist_points_get} (gnutls_x509_crl_dist_points_t @var{cdp}, unsigned int @var{seq}, unsigned int * @var{type}, gnutls_datum_t * @var{san}, unsigned int * @var{reasons}) +@var{cdp}: The CRL distribution points + +@var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.) + +@var{type}: The name type of the corresponding name (gnutls_x509_subject_alt_name_t) + +@var{san}: The distribution point names (to be treated as constant) + +@var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} . + +This function retrieves the individual CRL distribution points (2.5.29.31), +contained in provided type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the index is out of bounds, otherwise a negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_dist_points_init +@anchor{gnutls_x509_crl_dist_points_init} +@deftypefun {int} {gnutls_x509_crl_dist_points_init} (gnutls_x509_crl_dist_points_t * @var{cdp}) +@var{cdp}: The CRL distribution points + +This function will initialize a CRL distribution points type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crl_dist_points_set +@anchor{gnutls_x509_crl_dist_points_set} +@deftypefun {int} {gnutls_x509_crl_dist_points_set} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{san}, unsigned int @var{reasons}) +@var{cdp}: The CRL distribution points + +@var{type}: The type of the name (of @code{gnutls_subject_alt_names_t} ) + +@var{san}: The point name data + +@var{reasons}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} . + +This function will store the specified CRL distribution point value +the @code{cdp} type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crl_export +@anchor{gnutls_x509_crl_export} +@deftypefun {int} {gnutls_x509_crl_export} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{crl}: Holds the revocation list + +@var{format}: the format of output params. One of PEM or DER. + +@var{output_data}: will contain a private key PEM or DER encoded + +@var{output_data_size}: holds the size of output_data (and will +be replaced by the actual size of parameters) + +This function will export the revocation list to DER or PEM format. + +If the buffer provided is not long enough to hold the output, then +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned. + +If the structure is PEM encoded, it will have a header +of "BEGIN X509 CRL". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_export2 +@anchor{gnutls_x509_crl_export2} +@deftypefun {int} {gnutls_x509_crl_export2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) +@var{crl}: Holds the revocation list + +@var{format}: the format of output params. One of PEM or DER. + +@var{out}: will contain a private key PEM or DER encoded + +This function will export the revocation list to DER or PEM format. + +The output buffer is allocated using @code{gnutls_malloc()} . + +If the structure is PEM encoded, it will have a header +of "BEGIN X509 CRL". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +Since 3.1.3 +@end deftypefun + +@subheading gnutls_x509_crl_get_authority_key_gn_serial +@anchor{gnutls_x509_crl_get_authority_key_gn_serial} +@deftypefun {int} {gnutls_x509_crl_get_authority_key_gn_serial} (gnutls_x509_crl_t @var{crl}, unsigned int @var{seq}, void * @var{alt}, size_t * @var{alt_size}, unsigned int * @var{alt_type}, void * @var{serial}, size_t * @var{serial_size}, unsigned int * @var{critical}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{alt}: is the place where the alternative name will be copied to + +@var{alt_size}: holds the size of alt. + +@var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). + +@var{serial}: buffer to store the serial number (may be null) + +@var{serial_size}: Holds the size of the serial field (may be null) + +@var{critical}: will be non-zero if the extension is marked as critical (may be null) + +This function will return the X.509 authority key +identifier when stored as a general name (authorityCertIssuer) +and serial number. + +Because more than one general names might be stored + @code{seq} can be used as a counter to request them all until +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Returns:} Returns 0 on success, or an error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_authority_key_id +@anchor{gnutls_x509_crl_get_authority_key_id} +@deftypefun {int} {gnutls_x509_crl_get_authority_key_id} (gnutls_x509_crl_t @var{crl}, void * @var{id}, size_t * @var{id_size}, unsigned int * @var{critical}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{id}: The place where the identifier will be copied + +@var{id_size}: Holds the size of the result field. + +@var{critical}: will be non-zero if the extension is marked as critical +(may be null) + +This function will return the CRL 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 and +@code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains +the name and serial number of the certificate. In that case +@code{gnutls_x509_crl_get_authority_key_gn_serial()} may be used. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_crt_count +@anchor{gnutls_x509_crl_get_crt_count} +@deftypefun {int} {gnutls_x509_crl_get_crt_count} (gnutls_x509_crl_t @var{crl}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +This function will return the number of revoked certificates in the +given CRL. + +@strong{Returns:} number of certificates, a negative error code on failure. +@end deftypefun + +@subheading gnutls_x509_crl_get_crt_serial +@anchor{gnutls_x509_crl_get_crt_serial} +@deftypefun {int} {gnutls_x509_crl_get_crt_serial} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, unsigned char * @var{serial}, size_t * @var{serial_size}, time_t * @var{t}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{indx}: the index of the certificate to extract (starting from 0) + +@var{serial}: where the serial number will be copied + +@var{serial_size}: initially holds the size of serial + +@var{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. + +Note that this function will have performance issues in large sequences +of revoked certificates. In that case use @code{gnutls_x509_crl_iter_crt_serial()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_get_dn_oid +@anchor{gnutls_x509_crl_get_dn_oid} +@deftypefun {int} {gnutls_x509_crl_get_dn_oid} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{indx}: Specifies which DN OID to send. Use (0) to get the first one. + +@var{oid}: a pointer to store the OID (may be null) + +@var{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. + +@strong{Returns:} @code{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. +@end deftypefun + +@subheading gnutls_x509_crl_get_extension_data +@anchor{gnutls_x509_crl_get_extension_data} +@deftypefun {int} {gnutls_x509_crl_get_extension_data} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. + +@var{data}: a pointer to a structure to hold the data (may be null) + +@var{sizeof_data}: initially holds the size of @code{oid} + +This function will return the requested extension data in the CRL. +The extension data will be stored as a string in the provided +buffer. + +Use @code{gnutls_x509_crl_get_extension_info()} to extract the OID and +critical flag. Use @code{gnutls_x509_crl_get_extension_info()} instead, +if you want to get data indexed by the extension OID rather than +sequence. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_extension_data2 +@anchor{gnutls_x509_crl_get_extension_data2} +@deftypefun {int} {gnutls_x509_crl_get_extension_data2} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, gnutls_datum_t * @var{data}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{indx}: Specifies which extension OID to read. Use (0) to get the first one. + +@var{data}: will contain the extension DER-encoded data + +This function will return the requested by the index extension data in the +certificate revocation list. The extension data will be allocated using +@code{gnutls_malloc()} . + +Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If you have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. +@end deftypefun + +@subheading gnutls_x509_crl_get_extension_info +@anchor{gnutls_x509_crl_get_extension_info} +@deftypefun {int} {gnutls_x509_crl_get_extension_info} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{indx}: Specifies which extension OID to send, use (0) to get the first one. + +@var{oid}: a pointer to store the OID + +@var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return +holds actual size of @code{oid} . + +@var{critical}: output variable with critical flag, may be NULL. + +This function will return the requested extension OID in the CRL, +and the critical flag for it. The extension OID will be stored as +a string in the provided buffer. Use +@code{gnutls_x509_crl_get_extension_data()} to extract the data. + +If the buffer provided is not long enough to hold the output, then +* @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be +returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_extension_oid +@anchor{gnutls_x509_crl_get_extension_oid} +@deftypefun {int} {gnutls_x509_crl_get_extension_oid} (gnutls_x509_crl_t @var{crl}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{indx}: Specifies which extension OID to send, use (0) to get the first one. + +@var{oid}: a pointer to store the OID (may be null) + +@var{sizeof_oid}: initially holds the size of @code{oid} + +This function will return the requested extension OID in the CRL. +The extension OID will be stored as a string in the provided +buffer. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_issuer_dn +@anchor{gnutls_x509_crl_get_issuer_dn} +@deftypefun {int} {gnutls_x509_crl_get_issuer_dn} (gnutls_x509_crl_t @var{crl}, char * @var{buf}, size_t * @var{sizeof_buf}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{buf}: a pointer to a structure to hold the peer's name (may be null) + +@var{sizeof_buf}: initially holds the size of @code{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 RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +If buf is @code{NULL} then only the size will be filled. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crl_get_issuer_dn3()} . + +@strong{Returns:} @code{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. +@end deftypefun + +@subheading gnutls_x509_crl_get_issuer_dn2 +@anchor{gnutls_x509_crl_get_issuer_dn2} +@deftypefun {int} {gnutls_x509_crl_get_issuer_dn2} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +This function will allocate buffer and copy the name of the CRL issuer. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crl_get_issuer_dn3()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_crl_get_issuer_dn3 +@anchor{gnutls_x509_crl_get_issuer_dn3} +@deftypefun {int} {gnutls_x509_crl_get_issuer_dn3} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} + +This function will allocate buffer and copy the name of the CRL issuer. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.7 +@end deftypefun + +@subheading gnutls_x509_crl_get_issuer_dn_by_oid +@anchor{gnutls_x509_crl_get_issuer_dn_by_oid} +@deftypefun {int} {gnutls_x509_crl_get_issuer_dn_by_oid} (gnutls_x509_crl_t @var{crl}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{sizeof_buf}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{oid}: holds an Object Identified in null terminated string + +@var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one. + +@var{raw_flag}: If non-zero returns the raw DER data of the DN part. + +@var{buf}: a pointer to a structure to hold the peer's name (may be null) + +@var{sizeof_buf}: initially holds the size of @code{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 RFC4514. 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 (0), this function will only return known OIDs as +text. Other OIDs will be DER encoded, as described in RFC4514 -- in +hex format with a '#' prefix. You can check about known OIDs +using @code{gnutls_x509_dn_oid_known()} . + +If buf is null then only the size will be filled. + +@strong{Returns:} @code{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. +@end deftypefun + +@subheading gnutls_x509_crl_get_next_update +@anchor{gnutls_x509_crl_get_next_update} +@deftypefun {time_t} {gnutls_x509_crl_get_next_update} (gnutls_x509_crl_t @var{crl}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +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. + +@strong{Returns:} when the next CRL will be issued, or (time_t)-1 on error. +@end deftypefun + +@subheading gnutls_x509_crl_get_number +@anchor{gnutls_x509_crl_get_number} +@deftypefun {int} {gnutls_x509_crl_get_number} (gnutls_x509_crl_t @var{crl}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{ret}: The place where the number will be copied + +@var{ret_size}: Holds the size of the result field. + +@var{critical}: will be non-zero if the extension is marked as critical +(may be null) + +This function will return the CRL number extension. This is +obtained by the CRL Number extension field (2.5.29.20). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_raw_issuer_dn +@anchor{gnutls_x509_crl_get_raw_issuer_dn} +@deftypefun {int} {gnutls_x509_crl_get_raw_issuer_dn} (gnutls_x509_crl_t @var{crl}, gnutls_datum_t * @var{dn}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{dn}: will hold the starting point of the DN + +This function will return a pointer to the DER encoded DN structure +and the length. + +@strong{Returns:} a negative error code on error, and (0) on success. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_signature +@anchor{gnutls_x509_crl_get_signature} +@deftypefun {int} {gnutls_x509_crl_get_signature} (gnutls_x509_crl_t @var{crl}, char * @var{sig}, size_t * @var{sizeof_sig}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{sig}: a pointer where the signature part will be copied (may be null). + +@var{sizeof_sig}: initially holds the size of @code{sig} + +This function will extract the signature field of a CRL. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_get_signature_algorithm +@anchor{gnutls_x509_crl_get_signature_algorithm} +@deftypefun {int} {gnutls_x509_crl_get_signature_algorithm} (gnutls_x509_crl_t @var{crl}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +This function will return a value of the @code{gnutls_sign_algorithm_t} +enumeration that is the signature algorithm. + +Since 3.6.0 this function never returns a negative error code. +Error cases and unknown/unsupported signature algorithms are +mapped to @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Returns:} a @code{gnutls_sign_algorithm_t} value +@end deftypefun + +@subheading gnutls_x509_crl_get_signature_oid +@anchor{gnutls_x509_crl_get_signature_oid} +@deftypefun {int} {gnutls_x509_crl_get_signature_oid} (gnutls_x509_crl_t @var{crl}, char * @var{oid}, size_t * @var{oid_size}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will return the OID of the signature algorithm +that has been used to sign this CRL. This is function +is useful in the case @code{gnutls_x509_crl_get_signature_algorithm()} +returned @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Returns:} zero or a negative error code on error. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crl_get_this_update +@anchor{gnutls_x509_crl_get_this_update} +@deftypefun {time_t} {gnutls_x509_crl_get_this_update} (gnutls_x509_crl_t @var{crl}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +This function will return the time this CRL was issued. + +@strong{Returns:} when the CRL was issued, or (time_t)-1 on error. +@end deftypefun + +@subheading gnutls_x509_crl_get_version +@anchor{gnutls_x509_crl_get_version} +@deftypefun {int} {gnutls_x509_crl_get_version} (gnutls_x509_crl_t @var{crl}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +This function will return the version of the specified CRL. + +@strong{Returns:} The version number, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crl_import +@anchor{gnutls_x509_crl_import} +@deftypefun {int} {gnutls_x509_crl_import} (gnutls_x509_crl_t @var{crl}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) +@var{crl}: The data to store the parsed CRL. + +@var{data}: The DER or PEM encoded CRL. + +@var{format}: One of DER or PEM + +This function will convert the given DER or PEM encoded CRL +to the native @code{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". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_init +@anchor{gnutls_x509_crl_init} +@deftypefun {int} {gnutls_x509_crl_init} (gnutls_x509_crl_t * @var{crl}) +@var{crl}: A pointer to the type 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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_iter_crt_serial +@anchor{gnutls_x509_crl_iter_crt_serial} +@deftypefun {int} {gnutls_x509_crl_iter_crt_serial} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crl_iter_t * @var{iter}, unsigned char * @var{serial}, size_t * @var{serial_size}, time_t * @var{t}) +@var{crl}: should contain a @code{gnutls_x509_crl_t} type + +@var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} ) + +@var{serial}: where the serial number will be copied + +@var{serial_size}: initially holds the size of serial + +@var{t}: if non null, will hold the time this certificate was revoked + +This function performs the same as @code{gnutls_x509_crl_get_crt_serial()} , +but reads sequentially and keeps state in the iterator +between calls. That allows it to provide better performance in sequences +with many elements (50000+). + +When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +is returned and the iterator is reset. + +After use, the iterator must be deinitialized using @code{gnutls_x509_crl_iter_deinit()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_iter_deinit +@anchor{gnutls_x509_crl_iter_deinit} +@deftypefun {void} {gnutls_x509_crl_iter_deinit} (gnutls_x509_crl_iter_t @var{iter}) +@var{iter}: The iterator to be deinitialized + +This function will deinitialize an iterator type. +@end deftypefun + +@subheading gnutls_x509_crl_list_import +@anchor{gnutls_x509_crl_list_import} +@deftypefun {int} {gnutls_x509_crl_list_import} (gnutls_x509_crl_t * @var{crls}, unsigned int * @var{crl_max}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) +@var{crls}: Indicates where the parsed CRLs will be copied to. Must not be initialized. + +@var{crl_max}: Initially must hold the maximum number of crls. It will be updated with the number of crls available. + +@var{data}: The PEM encoded CRLs + +@var{format}: One of DER or PEM. + +@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. + +This function will convert the given PEM encoded CRL list +to the native gnutls_x509_crl_t format. The output will be stored +in @code{crls} . They will be automatically initialized. + +If the Certificate is PEM encoded it should have a header of "X509 CRL". + +@strong{Returns:} the number of certificates read or a negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crl_list_import2 +@anchor{gnutls_x509_crl_list_import2} +@deftypefun {int} {gnutls_x509_crl_list_import2} (gnutls_x509_crl_t ** @var{crls}, unsigned int * @var{size}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) +@var{crls}: Will contain the parsed crl list. + +@var{size}: It will contain the size of the list. + +@var{data}: The PEM encoded CRL. + +@var{format}: One of DER or PEM. + +@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. + +This function will convert the given PEM encoded CRL list +to the native gnutls_x509_crl_t format. The output will be stored +in @code{crls} . They will be automatically initialized. + +If the Certificate is PEM encoded it should have a header of "X509 +CRL". + +@strong{Returns:} the number of certificates read or a negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crl_print +@anchor{gnutls_x509_crl_print} +@deftypefun {int} {gnutls_x509_crl_print} (gnutls_x509_crl_t @var{crl}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) +@var{crl}: The data to be printed + +@var{format}: Indicate the format to use + +@var{out}: Newly allocated datum with null terminated string. + +This function will pretty print a X.509 certificate revocation +list, suitable for display to a human. + +The output @code{out} needs to be deallocated using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_set_authority_key_id +@anchor{gnutls_x509_crl_set_authority_key_id} +@deftypefun {int} {gnutls_x509_crl_set_authority_key_id} (gnutls_x509_crl_t @var{crl}, const void * @var{id}, size_t @var{id_size}) +@var{crl}: a CRL of type @code{gnutls_x509_crl_t} + +@var{id}: The key ID + +@var{id_size}: Holds the size of the serial field. + +This function will set the CRL's authority key ID extension. Only +the keyIdentifier field can be set with this function. This may +be used by an authority that holds multiple private keys, to distinguish +the used key. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_set_crt +@anchor{gnutls_x509_crl_set_crt} +@deftypefun {int} {gnutls_x509_crl_set_crt} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{crt}, time_t @var{revocation_time}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} with the revoked certificate + +@var{revocation_time}: The time this certificate was revoked + +This function will set a revoked certificate's serial number to the CRL. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_set_crt_serial +@anchor{gnutls_x509_crl_set_crt_serial} +@deftypefun {int} {gnutls_x509_crl_set_crt_serial} (gnutls_x509_crl_t @var{crl}, const void * @var{serial}, size_t @var{serial_size}, time_t @var{revocation_time}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{serial}: The revoked certificate's serial number + +@var{serial_size}: Holds the size of the serial field. + +@var{revocation_time}: The time this certificate was revoked + +This function will set a revoked certificate's serial number to the CRL. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_set_next_update +@anchor{gnutls_x509_crl_set_next_update} +@deftypefun {int} {gnutls_x509_crl_set_next_update} (gnutls_x509_crl_t @var{crl}, time_t @var{exp_time}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{exp_time}: The actual time + +This function will set the time this CRL will be updated. +This is an optional value to be set on a CRL and this call +can be omitted when generating a CRL. + +Prior to GnuTLS 3.5.7, setting a nextUpdate field was required +in order to generate a CRL. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_set_number +@anchor{gnutls_x509_crl_set_number} +@deftypefun {int} {gnutls_x509_crl_set_number} (gnutls_x509_crl_t @var{crl}, const void * @var{nr}, size_t @var{nr_size}) +@var{crl}: a CRL of type @code{gnutls_x509_crl_t} + +@var{nr}: The CRL number + +@var{nr_size}: Holds the size of the nr field. + +This function will set the CRL's number extension. This +is to be used as a unique and monotonic number assigned to +the CRL by the authority. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crl_set_this_update +@anchor{gnutls_x509_crl_set_this_update} +@deftypefun {int} {gnutls_x509_crl_set_this_update} (gnutls_x509_crl_t @var{crl}, time_t @var{act_time}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{act_time}: The actual time + +This function will set the time this CRL was issued. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_set_version +@anchor{gnutls_x509_crl_set_version} +@deftypefun {int} {gnutls_x509_crl_set_version} (gnutls_x509_crl_t @var{crl}, unsigned int @var{version}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_sign +@anchor{gnutls_x509_crl_sign} +@deftypefun {int} {gnutls_x509_crl_sign} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{issuer}: is the certificate of the certificate issuer + +@var{issuer_key}: holds the issuer's private key + +This function is the same a @code{gnutls_x509_crl_sign2()} with no flags, +and an appropriate hash algorithm. The hash algorithm used may +vary between versions of GnuTLS, and it is tied to the security +level of the issuer's public key. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_sign2 +@anchor{gnutls_x509_crl_sign2} +@deftypefun {int} {gnutls_x509_crl_sign2} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags}) +@var{crl}: should contain a gnutls_x509_crl_t type + +@var{issuer}: is the certificate of the certificate issuer + +@var{issuer_key}: holds the issuer's private key + +@var{dig}: The message digest to use. GNUTLS_DIG_SHA256 is the safe choice unless you know what you're doing. + +@var{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. + +A known limitation of this function is, that a newly-signed CRL will not +be fully functional (e.g., for signature verification), until it +is exported an re-imported. + +After GnuTLS 3.6.1 the value of @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} , +and in that case, a suitable but reasonable for the key algorithm will be selected. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crl_verify +@anchor{gnutls_x509_crl_verify} +@deftypefun {int} {gnutls_x509_crl_verify} (gnutls_x509_crl_t @var{crl}, const gnutls_x509_crt_t * @var{trusted_cas}, unsigned @var{tcas_size}, unsigned int @var{flags}, unsigned int * @var{verify}) +@var{crl}: is the crl to be verified + +@var{trusted_cas}: is a certificate list that is considered to be trusted one + +@var{tcas_size}: holds the number of CA certificates in CA_list + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +@var{verify}: will hold the crl verification output. + +This function will try to verify the given crl and return its verification status. +See @code{gnutls_x509_crt_list_verify()} for a detailed description of +return values. Note that since GnuTLS 3.1.4 this function includes +the time checks. + +Note that value in @code{verify} is set only when the return value of this +function is success (i.e, failure to trust a CRL a certificate does not imply +a negative return value). + +Before GnuTLS 3.5.7 this function would return zero or a positive +number on success. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_deinit +@anchor{gnutls_x509_crq_deinit} +@deftypefun {void} {gnutls_x509_crq_deinit} (gnutls_x509_crq_t @var{crq}) +@var{crq}: the type to be deinitialized + +This function will deinitialize a PKCS@code{10} certificate request +structure. +@end deftypefun + +@subheading gnutls_x509_crq_export +@anchor{gnutls_x509_crq_export} +@deftypefun {int} {gnutls_x509_crq_export} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{format}: the format of output params. One of PEM or DER. + +@var{output_data}: will contain a certificate request PEM or DER encoded + +@var{output_data_size}: holds the size of output_data (and will be +replaced by the actual size of parameters) + +This function will export the certificate request to a PEM or DER +encoded PKCS10 structure. + +If the buffer provided is not long enough to hold the output, then +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be returned and +* @code{output_data_size} will be updated. + +If the structure is PEM encoded, it will have a header of "BEGIN +NEW CERTIFICATE REQUEST". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_export2 +@anchor{gnutls_x509_crq_export2} +@deftypefun {int} {gnutls_x509_crq_export2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{format}: the format of output params. One of PEM or DER. + +@var{out}: will contain a certificate request PEM or DER encoded + +This function will export the certificate request to a PEM or DER +encoded PKCS10 structure. + +The output buffer is allocated using @code{gnutls_malloc()} . + +If the structure is PEM encoded, it will have a header of "BEGIN +NEW CERTIFICATE REQUEST". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +Since 3.1.3 +@end deftypefun + +@subheading gnutls_x509_crq_get_attribute_by_oid +@anchor{gnutls_x509_crq_get_attribute_by_oid} +@deftypefun {int} {gnutls_x509_crq_get_attribute_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: holds an Object Identifier in null-terminated string + +@var{indx}: In case multiple same OIDs exist in the attribute list, this +specifies which to get, use (0) to get the first one + +@var{buf}: a pointer to a structure to hold the attribute data (may be @code{NULL} ) + +@var{buf_size}: initially holds the size of @code{buf} + +This function will return the attribute in the certificate request +specified by the given Object ID. The attribute will be DER +encoded. + +Attributes in a certificate request is an optional set of data +appended to the request. Their interpretation depends on the CA policy. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_get_attribute_data +@anchor{gnutls_x509_crq_get_attribute_data} +@deftypefun {int} {gnutls_x509_crq_get_attribute_data} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{indx}: Specifies which attribute number to get. Use (0) to get the first one. + +@var{data}: a pointer to a structure to hold the data (may be null) + +@var{sizeof_data}: initially holds the size of @code{oid} + +This function will return the requested attribute data in the +certificate request. The attribute data will be stored as a string in the +provided buffer. + +Use @code{gnutls_x509_crq_get_attribute_info()} to extract the OID. +Use @code{gnutls_x509_crq_get_attribute_by_oid()} instead, +if you want to get data indexed by the attribute OID rather than +sequence. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_attribute_info +@anchor{gnutls_x509_crq_get_attribute_info} +@deftypefun {int} {gnutls_x509_crq_get_attribute_info} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{indx}: Specifies which attribute number to get. Use (0) to get the first one. + +@var{oid}: a pointer to a structure to hold the OID + +@var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return +holds actual size of @code{oid} . + +This function will return the requested attribute OID in the +certificate, and the critical flag for it. The attribute OID will +be stored as a string in the provided buffer. Use +@code{gnutls_x509_crq_get_attribute_data()} to extract the data. + +If the buffer provided is not long enough to hold the output, then +* @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be +returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_basic_constraints +@anchor{gnutls_x509_crq_get_basic_constraints} +@deftypefun {int} {gnutls_x509_crq_get_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{critical}, unsigned int * @var{ca}, int * @var{pathlen}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{critical}: will be non-zero if the extension is marked as critical + +@var{ca}: pointer to output integer indicating CA status, may be NULL, +value is 1 if the certificate CA flag is set, 0 otherwise. + +@var{pathlen}: pointer to output integer indicating path length (may be +NULL), non-negative error codes 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). + +@strong{Returns:} If the certificate is a CA a positive value will be +returned, or (0) if the certificate does not have CA flag set. +A negative error code may be returned in case of errors. If the +certificate does not contain the basicConstraints extension +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_challenge_password +@anchor{gnutls_x509_crq_get_challenge_password} +@deftypefun {int} {gnutls_x509_crq_get_challenge_password} (gnutls_x509_crq_t @var{crq}, char * @var{pass}, size_t * @var{pass_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{pass}: will hold a (0)-terminated password string + +@var{pass_size}: Initially holds the size of @code{pass} . + +This function will return the challenge password in the request. +The challenge password is intended to be used for requesting a +revocation of the certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_get_dn +@anchor{gnutls_x509_crq_get_dn} +@deftypefun {int} {gnutls_x509_crq_get_dn} (gnutls_x509_crq_t @var{crq}, char * @var{buf}, size_t * @var{buf_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{buf}: a pointer to a structure to hold the name (may be @code{NULL} ) + +@var{buf_size}: initially holds the size of @code{buf} + +This function will copy the name of the Certificate request subject +to the provided buffer. The name will be in the form +"C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string + @code{buf} will be ASCII or UTF-8 encoded, depending on the certificate +data. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crq_get_dn3()} . + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the * @code{buf_size} will be updated with +the required size. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crq_get_dn2 +@anchor{gnutls_x509_crq_get_dn2} +@deftypefun {int} {gnutls_x509_crq_get_dn2} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +This function will allocate buffer and copy the name of the Certificate +request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crq_get_dn3()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. and a negative error code on error. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_crq_get_dn3 +@anchor{gnutls_x509_crq_get_dn3} +@deftypefun {int} {gnutls_x509_crq_get_dn3} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} + +This function will allocate buffer and copy the name of the Certificate +request. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. and a negative error code on error. + +@strong{Since:} 3.5.7 +@end deftypefun + +@subheading gnutls_x509_crq_get_dn_by_oid +@anchor{gnutls_x509_crq_get_dn_by_oid} +@deftypefun {int} {gnutls_x509_crq_get_dn_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) +@var{crq}: should contain a gnutls_x509_crq_t type + +@var{oid}: holds an Object Identifier in a null terminated string + +@var{indx}: In case multiple same OIDs exist in the RDN, this specifies +which to get. Use (0) to get the first one. + +@var{raw_flag}: If non-zero returns the raw DER data of the DN part. + +@var{buf}: a pointer to a structure to hold the name (may be @code{NULL} ) + +@var{buf_size}: initially holds the size of @code{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 (0), 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 @code{gnutls_x509_dn_oid_known()} . + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is +not long enough, and in that case the * @code{buf_size} will be +updated with the required size. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crq_get_dn_oid +@anchor{gnutls_x509_crq_get_dn_oid} +@deftypefun {int} {gnutls_x509_crq_get_dn_oid} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}) +@var{crq}: should contain a gnutls_x509_crq_t type + +@var{indx}: Specifies which DN OID to get. Use (0) to get the first one. + +@var{oid}: a pointer to a structure to hold the name (may be @code{NULL} ) + +@var{sizeof_oid}: initially holds the size of @code{oid} + +This function will extract the requested OID of the name of the +certificate request subject, specified by the given index. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is +not long enough, and in that case the * @code{sizeof_oid} will be +updated with the required size. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crq_get_extension_by_oid +@anchor{gnutls_x509_crq_get_extension_by_oid} +@deftypefun {int} {gnutls_x509_crq_get_extension_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: holds an Object Identifier in a null terminated string + +@var{indx}: In case multiple same OIDs exist in the extensions, this +specifies which to get. Use (0) to get the first one. + +@var{buf}: a pointer to a structure to hold the name (may be null) + +@var{buf_size}: initially holds the size of @code{buf} + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If the certificate does not +contain the specified extension +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_extension_by_oid2 +@anchor{gnutls_x509_crq_get_extension_by_oid2} +@deftypefun {int} {gnutls_x509_crq_get_extension_by_oid2} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: holds an Object Identifier in a null terminated string + +@var{indx}: In case multiple same OIDs exist in the extensions, this +specifies which to get. Use (0) to get the first one. + +@var{output}: will hold the allocated extension data + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If the certificate does not +contain the specified extension +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_x509_crq_get_extension_data +@anchor{gnutls_x509_crq_get_extension_data} +@deftypefun {int} {gnutls_x509_crq_get_extension_data} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{indx}: Specifies which extension number to get. Use (0) to get the first one. + +@var{data}: a pointer to a structure to hold the data (may be null) + +@var{sizeof_data}: initially holds the size of @code{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 @code{gnutls_x509_crq_get_extension_info()} to extract the OID and +critical flag. Use @code{gnutls_x509_crq_get_extension_by_oid()} instead, +if you want to get data indexed by the extension OID rather than +sequence. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_extension_data2 +@anchor{gnutls_x509_crq_get_extension_data2} +@deftypefun {int} {gnutls_x509_crq_get_extension_data2} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, gnutls_datum_t * @var{data}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{indx}: Specifies which extension OID to read. Use (0) to get the first one. + +@var{data}: will contain the extension DER-encoded data + +This function will return the requested extension data in the +certificate request. The extension data will be allocated using +@code{gnutls_malloc()} . + +Use @code{gnutls_x509_crq_get_extension_info()} to extract the OID. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If you have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_extension_info +@anchor{gnutls_x509_crq_get_extension_info} +@deftypefun {int} {gnutls_x509_crq_get_extension_info} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{indx}: Specifies which extension number to get. Use (0) to get the first one. + +@var{oid}: a pointer to store the OID + +@var{sizeof_oid}: initially holds the maximum size of @code{oid} , on return +holds actual size of @code{oid} . + +@var{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 +@code{gnutls_x509_crq_get_extension_data()} to extract the data. + +If the buffer provided is not long enough to hold the output, then +* @code{sizeof_oid} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be +returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code in case of an error. If your have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_key_id +@anchor{gnutls_x509_crq_get_key_id} +@deftypefun {int} {gnutls_x509_crq_get_key_id} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}) +@var{crq}: a certificate of type @code{gnutls_x509_crq_t} + +@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} + +@var{output_data}: will contain the key ID + +@var{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 that 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 +* @code{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. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_key_purpose_oid +@anchor{gnutls_x509_crq_get_key_purpose_oid} +@deftypefun {int} {gnutls_x509_crq_get_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, unsigned @var{indx}, void * @var{oid}, size_t * @var{sizeof_oid}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{indx}: This specifies which OID to return, use (0) to get the first one + +@var{oid}: a pointer to store the OID (may be @code{NULL} ) + +@var{sizeof_oid}: initially holds the size of @code{oid} + +@var{critical}: output variable with critical flag, may be @code{NULL} . + +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. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is +not long enough, and in that case the * @code{sizeof_oid} will be +updated with the required size. On success 0 is returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_key_rsa_raw +@anchor{gnutls_x509_crq_get_key_rsa_raw} +@deftypefun {int} {gnutls_x509_crq_get_key_rsa_raw} (gnutls_x509_crq_t @var{crq}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}) +@var{crq}: Holds the certificate + +@var{m}: will hold the modulus + +@var{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 +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_key_usage +@anchor{gnutls_x509_crq_get_key_usage} +@deftypefun {int} {gnutls_x509_crq_get_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{key_usage}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{key_usage}: where the key usage bits will be stored + +@var{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: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} , +@code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} , +@code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} , +@code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} , +@code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} . + +@strong{Returns:} the certificate key usage, or a negative error code in case of +parsing error. If the certificate does not contain the keyUsage +extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_pk_algorithm +@anchor{gnutls_x509_crq_get_pk_algorithm} +@deftypefun {int} {gnutls_x509_crq_get_pk_algorithm} (gnutls_x509_crq_t @var{crq}, unsigned int * @var{bits}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{bits}: if bits is non-@code{NULL} it will hold the size of the parameters' in bits + +This function will return the public key algorithm of a PKCS@code{10} +certificate request. + +If bits is non-@code{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. + +@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on +success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crq_get_pk_oid +@anchor{gnutls_x509_crq_get_pk_oid} +@deftypefun {int} {gnutls_x509_crq_get_pk_oid} (gnutls_x509_crq_t @var{crq}, char * @var{oid}, size_t * @var{oid_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will return the OID of the public key algorithm +on that certificate request. This function +is useful in the case @code{gnutls_x509_crq_get_pk_algorithm()} +returned @code{GNUTLS_PK_UNKNOWN} . + +@strong{Returns:} zero or a negative error code on error. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_private_key_usage_period +@anchor{gnutls_x509_crq_get_private_key_usage_period} +@deftypefun {int} {gnutls_x509_crq_get_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t * @var{activation}, time_t * @var{expiration}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{activation}: The activation time + +@var{expiration}: The expiration time + +@var{critical}: the extension status + +This function will return the expiration and activation +times of the private key of the certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_get_signature_algorithm +@anchor{gnutls_x509_crq_get_signature_algorithm} +@deftypefun {int} {gnutls_x509_crq_get_signature_algorithm} (gnutls_x509_crq_t @var{crq}) +@var{crq}: should contain a @code{gnutls_x509_cr_t} type + +This function will return a value of the @code{gnutls_sign_algorithm_t} +enumeration that is the signature algorithm that has been used to +sign this certificate request. + +Since 3.6.0 this function never returns a negative error code. +Error cases and unknown/unsupported signature algorithms are +mapped to @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Returns:} a @code{gnutls_sign_algorithm_t} value + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_signature_oid +@anchor{gnutls_x509_crq_get_signature_oid} +@deftypefun {int} {gnutls_x509_crq_get_signature_oid} (gnutls_x509_crq_t @var{crq}, char * @var{oid}, size_t * @var{oid_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will return the OID of the signature algorithm +that has been used to sign this certificate request. This function +is useful in the case @code{gnutls_x509_crq_get_signature_algorithm()} +returned @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Returns:} zero or a negative error code on error. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_spki +@anchor{gnutls_x509_crq_get_spki} +@deftypefun {int} {gnutls_x509_crq_get_spki} (gnutls_x509_crq_t @var{crq}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} + +@var{flags}: must be zero + +This function will return the public key information of a PKCS@code{10} +certificate request. The provided @code{spki} must be initialized. + +@strong{Returns:} Zero on success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crq_get_subject_alt_name +@anchor{gnutls_x509_crq_get_subject_alt_name} +@deftypefun {int} {gnutls_x509_crq_get_subject_alt_name} (gnutls_x509_crq_t @var{crq}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{ret_type}, unsigned int * @var{critical}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{seq}: specifies the sequence number of the alt name, 0 for the +first one, 1 for the second etc. + +@var{ret}: is the place where the alternative name will be copied to + +@var{ret_size}: holds the size of ret. + +@var{ret_type}: holds the @code{gnutls_x509_subject_alt_name_t} name type + +@var{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 +@code{gnutls_x509_crq_get_subject_alt_name()} except for the fact that it +will return the type of the alternative name in @code{ret_type} even if +the function fails for some reason (i.e. the buffer provided is +not enough). + +@strong{Returns:} the alternative subject name type on success, one of the +enumerated @code{gnutls_x509_subject_alt_name_t} . It will return +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ret_size} is not large enough to +hold the value. In that case @code{ret_size} will be updated with the +required size. If the certificate request does not have an +Alternative name with the specified sequence number then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_subject_alt_othername_oid +@anchor{gnutls_x509_crq_get_subject_alt_othername_oid} +@deftypefun {int} {gnutls_x509_crq_get_subject_alt_othername_oid} (gnutls_x509_crq_t @var{crq}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{ret}: is the place where the otherName OID will be copied to + +@var{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 +@code{gnutls_x509_crq_get_subject_alt_name()} returned +@code{GNUTLS_SAN_OTHERNAME} . + +@strong{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. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for +unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if + @code{ret_size} is not large enough to hold the value. In that case + @code{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 +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_get_tlsfeatures +@anchor{gnutls_x509_crq_get_tlsfeatures} +@deftypefun {int} {gnutls_x509_crq_get_tlsfeatures} (gnutls_x509_crq_t @var{crq}, gnutls_x509_tlsfeatures_t @var{features}, unsigned int @var{flags}, unsigned int * @var{critical}) +@var{crq}: An X.509 certificate request + +@var{features}: If the function succeeds, the +features will be stored in this variable. + +@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} + +@var{critical}: the extension status + +This function will get the X.509 TLS features +extension structure from the certificate request. +The returned structure needs to be freed using +@code{gnutls_x509_tlsfeatures_deinit()} . + +When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , +then if the @code{features} structure is empty this function will behave +identically as if the flag was not set. Otherwise if there are elements +in the @code{features} structure then they will be merged with. + +Note that @code{features} must be initialized prior to calling this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_crq_get_version +@anchor{gnutls_x509_crq_get_version} +@deftypefun {int} {gnutls_x509_crq_get_version} (gnutls_x509_crq_t @var{crq}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +This function will return the version of the specified Certificate +request. + +@strong{Returns:} version of certificate request, or a negative error code on +error. +@end deftypefun + +@subheading gnutls_x509_crq_import +@anchor{gnutls_x509_crq_import} +@deftypefun {int} {gnutls_x509_crq_import} (gnutls_x509_crq_t @var{crq}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) +@var{crq}: The data to store the parsed certificate request. + +@var{data}: The DER or PEM encoded certificate. + +@var{format}: One of DER or PEM + +This function will convert the given DER or PEM encoded certificate +request to a @code{gnutls_x509_crq_t} type. The output will be +stored in @code{crq} . + +If the Certificate is PEM encoded it should have a header of "NEW +CERTIFICATE REQUEST". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_init +@anchor{gnutls_x509_crq_init} +@deftypefun {int} {gnutls_x509_crq_init} (gnutls_x509_crq_t * @var{crq}) +@var{crq}: A pointer to the type to be initialized + +This function will initialize a PKCS@code{10} certificate request +structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_print +@anchor{gnutls_x509_crq_print} +@deftypefun {int} {gnutls_x509_crq_print} (gnutls_x509_crq_t @var{crq}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) +@var{crq}: The data to be printed + +@var{format}: Indicate the format to use + +@var{out}: Newly allocated datum with null terminated string. + +This function will pretty print a certificate request, suitable for +display to a human. + +The output @code{out} needs to be deallocated using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_attribute_by_oid +@anchor{gnutls_x509_crq_set_attribute_by_oid} +@deftypefun {int} {gnutls_x509_crq_set_attribute_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, void * @var{buf}, size_t @var{buf_size}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: holds an Object Identifier in a null-terminated string + +@var{buf}: a pointer to a structure that holds the attribute data + +@var{buf_size}: holds the size of @code{buf} + +This function will set the attribute in the certificate request +specified by the given Object ID. The provided attribute must be be DER +encoded. + +Attributes in a certificate request is an optional set of data +appended to the request. Their interpretation depends on the CA policy. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_basic_constraints +@anchor{gnutls_x509_crq_set_basic_constraints} +@deftypefun {int} {gnutls_x509_crq_set_basic_constraints} (gnutls_x509_crq_t @var{crq}, unsigned int @var{ca}, int @var{pathLenConstraint}) +@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} + +@var{ca}: true(1) or false(0) depending on the Certificate authority status. + +@var{pathLenConstraint}: non-negative error codes indicate maximum length of path, +and negative error codes indicate that the pathLenConstraints field should +not be present. + +This function will set the basicConstraints certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_challenge_password +@anchor{gnutls_x509_crq_set_challenge_password} +@deftypefun {int} {gnutls_x509_crq_set_challenge_password} (gnutls_x509_crq_t @var{crq}, const char * @var{pass}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{pass}: holds a (0)-terminated password + +This function will set a challenge password to be used when +revoking the request. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_dn +@anchor{gnutls_x509_crq_set_dn} +@deftypefun {int} {gnutls_x509_crq_set_dn} (gnutls_x509_crq_t @var{crq}, const char * @var{dn}, const char ** @var{err}) +@var{crq}: a certificate of type @code{gnutls_x509_crq_t} + +@var{dn}: a comma separated DN string (RFC4514) + +@var{err}: indicates the error position (if any) + +This function will set the DN on the provided certificate. +The input string should be plain ASCII or UTF-8 encoded. On +DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_dn_by_oid +@anchor{gnutls_x509_crq_set_dn_by_oid} +@deftypefun {int} {gnutls_x509_crq_set_dn_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned int @var{raw_flag}, const void * @var{data}, unsigned int @var{sizeof_data}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{oid}: holds an Object Identifier in a (0)-terminated string + +@var{raw_flag}: must be 0, or 1 if the data are DER encoded + +@var{data}: a pointer to the input data + +@var{sizeof_data}: holds the size of @code{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 @code{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_extension_by_oid +@anchor{gnutls_x509_crq_set_extension_by_oid} +@deftypefun {int} {gnutls_x509_crq_set_extension_by_oid} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, const void * @var{buf}, size_t @var{sizeof_buf}, unsigned int @var{critical}) +@var{crq}: a certificate of type @code{gnutls_x509_crq_t} + +@var{oid}: holds an Object Identifier in null terminated string + +@var{buf}: a pointer to a DER encoded data + +@var{sizeof_buf}: holds the size of @code{buf} + +@var{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 request. The extension data should be binary data DER +encoded. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_key +@anchor{gnutls_x509_crq_set_key} +@deftypefun {int} {gnutls_x509_crq_set_key} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{key}: holds a private key + +This function will set the public parameters from the given private +key to the request. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_key_purpose_oid +@anchor{gnutls_x509_crq_set_key_purpose_oid} +@deftypefun {int} {gnutls_x509_crq_set_key_purpose_oid} (gnutls_x509_crq_t @var{crq}, const void * @var{oid}, unsigned int @var{critical}) +@var{crq}: a certificate of type @code{gnutls_x509_crq_t} + +@var{oid}: a pointer to a null-terminated string that holds the OID + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_key_rsa_raw +@anchor{gnutls_x509_crq_set_key_rsa_raw} +@deftypefun {int} {gnutls_x509_crq_set_key_rsa_raw} (gnutls_x509_crq_t @var{crq}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{m}: holds the modulus + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_key_usage +@anchor{gnutls_x509_crq_set_key_usage} +@deftypefun {int} {gnutls_x509_crq_set_key_usage} (gnutls_x509_crq_t @var{crq}, unsigned int @var{usage}) +@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} + +@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements. + +This function will set the keyUsage certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_private_key_usage_period +@anchor{gnutls_x509_crq_set_private_key_usage_period} +@deftypefun {int} {gnutls_x509_crq_set_private_key_usage_period} (gnutls_x509_crq_t @var{crq}, time_t @var{activation}, time_t @var{expiration}) +@var{crq}: a certificate of type @code{gnutls_x509_crq_t} + +@var{activation}: The activation time + +@var{expiration}: The expiration time + +This function will set the private key usage period extension (2.5.29.16). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_set_spki +@anchor{gnutls_x509_crq_set_spki} +@deftypefun {int} {gnutls_x509_crq_set_spki} (gnutls_x509_crq_t @var{crq}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) +@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} + +@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} + +@var{flags}: must be zero + +This function will set the certificate request's subject public key +information explicitly. This is intended to be used in the cases +where a single public key (e.g., RSA) can be used for multiple +signature algorithms (RSA PKCS1-1.5, and RSA-PSS). + +To export the public key (i.e., the SubjectPublicKeyInfo part), check +@code{gnutls_pubkey_import_x509()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_subject_alt_name +@anchor{gnutls_x509_crq_set_subject_alt_name} +@deftypefun {int} {gnutls_x509_crq_set_subject_alt_name} (gnutls_x509_crq_t @var{crq}, gnutls_x509_subject_alt_name_t @var{nt}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) +@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} + +@var{nt}: is one of the @code{gnutls_x509_subject_alt_name_t} enumerations + +@var{data}: The data to be set + +@var{data_size}: The size of data to be set + +@var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or +@code{GNUTLS_FSAN_APPEND} to append. + +This function will set the subject alternative name certificate +extension. It can set the following types: + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_subject_alt_othername +@anchor{gnutls_x509_crq_set_subject_alt_othername} +@deftypefun {int} {gnutls_x509_crq_set_subject_alt_othername} (gnutls_x509_crq_t @var{crq}, const char * @var{oid}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) +@var{crq}: a certificate request of type @code{gnutls_x509_crq_t} + +@var{oid}: is the othername OID + +@var{data}: The data to be set + +@var{data_size}: The size of data to be set + +@var{flags}: @code{GNUTLS_FSAN_SET} to clear previous data or +@code{GNUTLS_FSAN_APPEND} to append. + +This function will set the subject alternative name certificate +extension. It can set the following types: + +The values set must be binary values and must be properly DER encoded. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crq_set_tlsfeatures +@anchor{gnutls_x509_crq_set_tlsfeatures} +@deftypefun {int} {gnutls_x509_crq_set_tlsfeatures} (gnutls_x509_crq_t @var{crq}, gnutls_x509_tlsfeatures_t @var{features}) +@var{crq}: An X.509 certificate request + +@var{features}: If the function succeeds, the +features will be added to the certificate +request. + +This function will set the certificate request's +X.509 TLS extension from the given structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_crq_set_version +@anchor{gnutls_x509_crq_set_version} +@deftypefun {int} {gnutls_x509_crq_set_version} (gnutls_x509_crq_t @var{crq}, unsigned int @var{version}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_sign +@anchor{gnutls_x509_crq_sign} +@deftypefun {int} {gnutls_x509_crq_sign} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{key}: holds a private key + +This function is the same a @code{gnutls_x509_crq_sign2()} with no flags, +and an appropriate hash algorithm. The hash algorithm used may +vary between versions of GnuTLS, and it is tied to the security +level of the issuer's public key. + +A known limitation of this function is, that a newly-signed request will not +be fully functional (e.g., for signature verification), until it +is exported an re-imported. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crq_sign2 +@anchor{gnutls_x509_crq_sign2} +@deftypefun {int} {gnutls_x509_crq_sign2} (gnutls_x509_crq_t @var{crq}, gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags}) +@var{crq}: should contain a @code{gnutls_x509_crq_t} type + +@var{key}: holds a private key + +@var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA256} + +@var{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 +@code{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. + +A known limitation of this function is, that a newly-signed request will not +be fully functional (e.g., for signature verification), until it +is exported an re-imported. + +After GnuTLS 3.6.1 the value of @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} , +and in that case, a suitable but reasonable for the key algorithm will be selected. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. +@code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all +information in the certificate request (e.g., the version using +@code{gnutls_x509_crq_set_version()} ). +@end deftypefun + +@subheading gnutls_x509_crq_verify +@anchor{gnutls_x509_crq_verify} +@deftypefun {int} {gnutls_x509_crq_verify} (gnutls_x509_crq_t @var{crq}, unsigned int @var{flags}) +@var{crq}: is the crq to be verified + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +This function will verify self signature in the certificate +request and return its status. + +@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED} +is returned, and zero or positive code on success. + +Since 2.12.0 +@end deftypefun + +@subheading gnutls_x509_crt_check_email +@anchor{gnutls_x509_crt_check_email} +@deftypefun {unsigned} {gnutls_x509_crt_check_email} (gnutls_x509_crt_t @var{cert}, const char * @var{email}, unsigned int @var{flags}) +@var{cert}: should contain an gnutls_x509_crt_t type + +@var{email}: A null terminated string that contains an email address (RFC822) + +@var{flags}: should be zero + +This function will check if the given certificate's subject matches +the given email address. + +@strong{Returns:} non-zero for a successful match, and zero on failure. +@end deftypefun + +@subheading gnutls_x509_crt_check_hostname +@anchor{gnutls_x509_crt_check_hostname} +@deftypefun {unsigned} {gnutls_x509_crt_check_hostname} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}) +@var{cert}: should contain an gnutls_x509_crt_t type + +@var{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 RFC6125, and takes into account wildcards, +and the DNSName/IPAddress subject alternative name PKIX extension. + +For details see also @code{gnutls_x509_crt_check_hostname2()} . + +@strong{Returns:} non-zero for a successful match, and zero on failure. +@end deftypefun + +@subheading gnutls_x509_crt_check_hostname2 +@anchor{gnutls_x509_crt_check_hostname2} +@deftypefun {unsigned} {gnutls_x509_crt_check_hostname2} (gnutls_x509_crt_t @var{cert}, const char * @var{hostname}, unsigned int @var{flags}) +@var{cert}: should contain an gnutls_x509_crt_t type + +@var{hostname}: A null terminated string that contains a DNS name + +@var{flags}: gnutls_certificate_verify_flags + +This function will check if the given certificate's subject matches +the given hostname. This is a basic implementation of the matching +described in RFC6125, and takes into account wildcards, +and the DNSName/IPAddress subject alternative name PKIX extension. + +IPv4 addresses are accepted by this function in the dotted-decimal +format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the hexadecimal +x:x:x:x:x:x:x:x format. For them the IPAddress subject alternative +name extension is consulted. Previous versions to 3.6.0 of GnuTLS +in case of a non-match would consult (in a non-standard extension) +the DNSname and CN fields. This is no longer the case. + +When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS} is specified no +wildcards are considered. Otherwise they are only considered if the +domain name consists of three components or more, and the wildcard +starts at the leftmost position. +When the flag @code{GNUTLS_VERIFY_DO_NOT_ALLOW_IP_MATCHES} is specified, +the input will be treated as a DNS name, and matching of textual IP addresses +against the IPAddress part of the alternative name will not be allowed. + +The function @code{gnutls_x509_crt_check_ip()} is available for matching +IP addresses. + +@strong{Returns:} non-zero for a successful match, and zero on failure. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crt_check_ip +@anchor{gnutls_x509_crt_check_ip} +@deftypefun {unsigned} {gnutls_x509_crt_check_ip} (gnutls_x509_crt_t @var{cert}, const unsigned char * @var{ip}, unsigned int @var{ip_size}, unsigned int @var{flags}) +@var{cert}: should contain an gnutls_x509_crt_t type + +@var{ip}: A pointer to the raw IP address + +@var{ip_size}: the number of bytes in ip (4 or 16) + +@var{flags}: should be zero + +This function will check if the IP allowed IP addresses in +the certificate's subject alternative name match the provided +IP address. + +@strong{Returns:} non-zero for a successful match, and zero on failure. +@end deftypefun + +@subheading gnutls_x509_crt_check_issuer +@anchor{gnutls_x509_crt_check_issuer} +@deftypefun {unsigned} {gnutls_x509_crt_check_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t @var{issuer}) +@var{cert}: is the certificate to be checked + +@var{issuer}: is the certificate of a possible issuer + +This function will check if the given certificate was issued by the +given issuer. It checks the DN fields and the authority +key identifier and subject key identifier fields match. + +If the same certificate is provided at the @code{cert} and @code{issuer} fields, +it will check whether the certificate is self-signed. + +@strong{Returns:} It will return true (1) if the given certificate is issued +by the given issuer, and false (0) if not. +@end deftypefun + +@subheading gnutls_x509_crt_check_key_purpose +@anchor{gnutls_x509_crt_check_key_purpose} +@deftypefun {unsigned} {gnutls_x509_crt_check_key_purpose} (gnutls_x509_crt_t @var{cert}, const char * @var{purpose}, unsigned @var{flags}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{purpose}: a key purpose OID (e.g., @code{GNUTLS_KP_CODE_SIGNING} ) + +@var{flags}: zero or @code{GNUTLS_KP_FLAG_DISALLOW_ANY} + +This function will check whether the given certificate matches +the provided key purpose. If @code{flags} contains @code{GNUTLS_KP_FLAG_ALLOW_ANY} then +it a certificate marked for any purpose will not match. + +@strong{Returns:} zero if the key purpose doesn't match, and non-zero otherwise. + +@strong{Since:} 3.5.6 +@end deftypefun + +@subheading gnutls_x509_crt_check_revocation +@anchor{gnutls_x509_crt_check_revocation} +@deftypefun {int} {gnutls_x509_crt_check_revocation} (gnutls_x509_crt_t @var{cert}, const gnutls_x509_crl_t * @var{crl_list}, unsigned @var{crl_list_length}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{crl_list}: should contain a list of gnutls_x509_crl_t types + +@var{crl_list_length}: the length of the crl_list + +This function will check if the given certificate is +revoked. It is assumed that the CRLs have been verified before. + +@strong{Returns:} 0 if the certificate is NOT revoked, and 1 if it is. A +negative error code is returned on error. +@end deftypefun + +@subheading gnutls_x509_crt_cpy_crl_dist_points +@anchor{gnutls_x509_crt_cpy_crl_dist_points} +@deftypefun {int} {gnutls_x509_crt_cpy_crl_dist_points} (gnutls_x509_crt_t @var{dst}, gnutls_x509_crt_t @var{src}) +@var{dst}: a certificate of type @code{gnutls_x509_crt_t} + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_deinit +@anchor{gnutls_x509_crt_deinit} +@deftypefun {void} {gnutls_x509_crt_deinit} (gnutls_x509_crt_t @var{cert}) +@var{cert}: The data to be deinitialized + +This function will deinitialize a certificate structure. +@end deftypefun + +@subheading gnutls_x509_crt_equals +@anchor{gnutls_x509_crt_equals} +@deftypefun {unsigned} {gnutls_x509_crt_equals} (gnutls_x509_crt_t @var{cert1}, gnutls_x509_crt_t @var{cert2}) +@var{cert1}: The first certificate + +@var{cert2}: The second certificate + +This function will compare two X.509 certificate structures. + +@strong{Returns:} On equality non-zero is returned, otherwise zero. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crt_equals2 +@anchor{gnutls_x509_crt_equals2} +@deftypefun {unsigned} {gnutls_x509_crt_equals2} (gnutls_x509_crt_t @var{cert1}, const gnutls_datum_t * @var{der}) +@var{cert1}: The first certificate + +@var{der}: A DER encoded certificate + +This function will compare an X.509 certificate structures, with DER +encoded certificate data. + +@strong{Returns:} On equality non-zero is returned, otherwise zero. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crt_export +@anchor{gnutls_x509_crt_export} +@deftypefun {int} {gnutls_x509_crt_export} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{cert}: Holds the certificate + +@var{format}: the format of output params. One of PEM or DER. + +@var{output_data}: will contain a certificate PEM or DER encoded + +@var{output_data_size}: holds the size of output_data (and will be +replaced by the actual size of parameters) + +This function will export the 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". + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. +@end deftypefun + +@subheading gnutls_x509_crt_export2 +@anchor{gnutls_x509_crt_export2} +@deftypefun {int} {gnutls_x509_crt_export2} (gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) +@var{cert}: Holds the certificate + +@var{format}: the format of output params. One of PEM or DER. + +@var{out}: will contain a certificate PEM or DER encoded + +This function will export the certificate to DER or PEM format. +The output buffer is allocated using @code{gnutls_malloc()} . + +If the structure is PEM encoded, it will have a header +of "BEGIN CERTIFICATE". + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_x509_crt_get_activation_time +@anchor{gnutls_x509_crt_get_activation_time} +@deftypefun {time_t} {gnutls_x509_crt_get_activation_time} (gnutls_x509_crt_t @var{cert}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +This function will return the time this Certificate was or will be +activated. + +@strong{Returns:} activation time, or (time_t)-1 on error. +@end deftypefun + +@subheading gnutls_x509_crt_get_authority_info_access +@anchor{gnutls_x509_crt_get_authority_info_access} +@deftypefun {int} {gnutls_x509_crt_get_authority_info_access} (gnutls_x509_crt_t @var{crt}, unsigned int @var{seq}, int @var{what}, gnutls_datum_t * @var{data}, unsigned int * @var{critical}) +@var{crt}: Holds the certificate + +@var{seq}: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.) + +@var{what}: what data to get, a @code{gnutls_info_access_what_t} type. + +@var{data}: output data to be freed with @code{gnutls_free()} . + +@var{critical}: pointer to output integer that is set to non-zero if the extension is marked as critical (may be @code{NULL} ) + +Note that a simpler API to access the authority info data is provided +by @code{gnutls_x509_aia_get()} and @code{gnutls_x509_ext_import_aia()} . + +This function extracts the Authority Information Access (AIA) +extension, see RFC 5280 section 4.2.2.1 for more information. The +AIA extension holds a sequence of AccessDescription (AD) data. + +The @code{seq} input parameter is used to indicate which member of the +sequence the caller is interested in. The first member is 0, the +second member 1 and so on. When the @code{seq} value is out of bounds, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +The type of data returned in @code{data} is specified via @code{what} which +should be @code{gnutls_info_access_what_t} values. + +If @code{what} is @code{GNUTLS_IA_ACCESSMETHOD_OID} then @code{data} will hold the +accessMethod OID (e.g., "1.3.6.1.5.5.7.48.1"). + +If @code{what} is @code{GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE} , @code{data} will +hold the accessLocation GeneralName type (e.g., +"uniformResourceIdentifier"). + +If @code{what} is @code{GNUTLS_IA_URI} , @code{data} will hold the accessLocation URI +data. Requesting this @code{what} value leads to an error if the +accessLocation is not of the "uniformResourceIdentifier" type. + +If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI. +Requesting this @code{what} value leads to an error if the accessMethod +is not 1.3.6.1.5.5.7.48.1 aka OCSP, or if accessLocation is not of +the "uniformResourceIdentifier" type. In that case @code{GNUTLS_E_UNKNOWN_ALGORITHM} +will be returned, and @code{seq} should be increased and this function +called again. + +If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers +URI. Requesting this @code{what} value leads to an error if the +accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if +accessLocation is not of the "uniformResourceIdentifier" type. +In that case handle as in @code{GNUTLS_IA_OCSP_URI} . + +More @code{what} values may be allocated in the future as needed. + +If @code{data} is NULL, the function does the same without storing the +output data, that is, it will set @code{critical} and do error checking +as usual. + +The value of the critical flag is returned in * @code{critical} . Supply a +NULL @code{critical} if you want the function to make sure the extension +is non-critical, as required by RFC 5280. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, @code{GNUTLS_E_INVALID_REQUEST} on +invalid @code{crt} , @code{GNUTLS_E_CONSTRAINT_ERROR} if the extension is +incorrectly marked as critical (use a non-NULL @code{critical} to +override), @code{GNUTLS_E_UNKNOWN_ALGORITHM} if the requested OID does +not match (e.g., when using @code{GNUTLS_IA_OCSP_URI} ), otherwise a +negative error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_authority_key_gn_serial +@anchor{gnutls_x509_crt_get_authority_key_gn_serial} +@deftypefun {int} {gnutls_x509_crt_get_authority_key_gn_serial} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{alt}, size_t * @var{alt_size}, unsigned int * @var{alt_type}, void * @var{serial}, size_t * @var{serial_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{alt}: is the place where the alternative name will be copied to + +@var{alt_size}: holds the size of alt. + +@var{alt_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). + +@var{serial}: buffer to store the serial number (may be null) + +@var{serial_size}: Holds the size of the serial field (may be null) + +@var{critical}: will be non-zero if the extension is marked as critical (may be null) + +This function will return the X.509 authority key +identifier when stored as a general name (authorityCertIssuer) +and serial number. + +Because more than one general names might be stored + @code{seq} can be used as a counter to request them all until +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_authority_key_id +@anchor{gnutls_x509_crt_get_authority_key_id} +@deftypefun {int} {gnutls_x509_crt_get_authority_key_id} (gnutls_x509_crt_t @var{cert}, void * @var{id}, size_t * @var{id_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{id}: The place where the identifier will be copied + +@var{id_size}: Holds the size of the id field. + +@var{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 and +@code{GNUTLS_E_X509_UNSUPPORTED_EXTENSION} , if the extension contains +the name and serial number of the certificate. In that case +@code{gnutls_x509_crt_get_authority_key_gn_serial()} may be used. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_get_basic_constraints +@anchor{gnutls_x509_crt_get_basic_constraints} +@deftypefun {int} {gnutls_x509_crt_get_basic_constraints} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}, unsigned int * @var{ca}, int * @var{pathlen}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{critical}: will be non-zero if the extension is marked as critical + +@var{ca}: pointer to output integer indicating CA status, may be NULL, +value is 1 if the certificate CA flag is set, 0 otherwise. + +@var{pathlen}: pointer to output integer indicating path length (may be +NULL), non-negative error codes 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). + +@strong{Returns:} If the certificate is a CA a positive value will be +returned, or (0) if the certificate does not have CA flag set. A +negative error code 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. +@end deftypefun + +@subheading gnutls_x509_crt_get_ca_status +@anchor{gnutls_x509_crt_get_ca_status} +@deftypefun {int} {gnutls_x509_crt_get_ca_status} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{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 (0) if the certificate +does not have CA flag set. + +Use @code{gnutls_x509_crt_get_basic_constraints()} if you want to read the +pathLenConstraint field too. + +@strong{Returns:} If the certificate is a CA a positive value will be +returned, or (0) if the certificate does not have CA flag set. A +negative error code 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. +@end deftypefun + +@subheading gnutls_x509_crt_get_crl_dist_points +@anchor{gnutls_x509_crt_get_crl_dist_points} +@deftypefun {int} {gnutls_x509_crt_get_crl_dist_points} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{san}, size_t * @var{san_size}, unsigned int * @var{reason_flags}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.) + +@var{san}: is the place where the distribution point will be copied to + +@var{san_size}: holds the size of ret. + +@var{reason_flags}: Revocation reasons. An ORed sequence of flags from @code{gnutls_x509_crl_reason_flags_t} . + +@var{critical}: will be non-zero if the extension is marked as critical (may be null) + +This function retrieves the CRL distribution points (2.5.29.31), +contained in the given certificate in the X509v3 Certificate +Extensions. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} and updates @code{ret_size} if + @code{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 @code{gnutls_x509_subject_alt_name_t} . If the +certificate does not have an Alternative name with the specified +sequence number then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is +returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_dn +@anchor{gnutls_x509_crt_get_dn} +@deftypefun {int} {gnutls_x509_crt_get_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{buf}: a pointer to a structure to hold the name (may be null) + +@var{buf_size}: initially holds the size of @code{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 RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +The @code{buf} returned will be null terminated and the @code{buf_size} will account +for the trailing null. If @code{buf} is null then only the size will be filled. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crt_get_dn3()} . + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the @code{buf_size} will be updated +with the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if +the DN does not exist, or another error value on error. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_dn2 +@anchor{gnutls_x509_crt_get_dn2} +@deftypefun {int} {gnutls_x509_crt_get_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +This function will allocate buffer and copy the name of the Certificate. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crt_get_dn3()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_crt_get_dn3 +@anchor{gnutls_x509_crt_get_dn3} +@deftypefun {int} {gnutls_x509_crt_get_dn3} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} + +This function will allocate buffer and copy the name of the Certificate. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.7 +@end deftypefun + +@subheading gnutls_x509_crt_get_dn_by_oid +@anchor{gnutls_x509_crt_get_dn_by_oid} +@deftypefun {int} {gnutls_x509_crt_get_dn_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{oid}: holds an Object Identified in null terminated string + +@var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one. + +@var{raw_flag}: If non-zero returns the raw DER data of the DN part. + +@var{buf}: a pointer where the DN part will be copied (may be null). + +@var{buf_size}: initially holds the size of @code{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 RFC4514. 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 (0), this function will only return known OIDs as +text. Other OIDs will be DER encoded, as described in RFC4514 -- +in hex format with a '#' prefix. You can check about known OIDs +using @code{gnutls_x509_dn_oid_known()} . + +If @code{buf} is null then only the size will be filled. If the @code{raw_flag} is not specified the output is always null terminated, although the + @code{buf_size} will not include the null character. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the @code{buf_size} will be updated with +the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there +are no data in the current index. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_dn_oid +@anchor{gnutls_x509_crt_get_dn_oid} +@deftypefun {int} {gnutls_x509_crt_get_dn_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: This specifies which OID to return. Use (0) to get the first one. + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will extract the OIDs of the name of the Certificate +subject specified by the given index. + +If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not +account for the trailing null. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the @code{buf_size} will be updated with +the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there +are no data in the current index. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_expiration_time +@anchor{gnutls_x509_crt_get_expiration_time} +@deftypefun {time_t} {gnutls_x509_crt_get_expiration_time} (gnutls_x509_crt_t @var{cert}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +This function will return the time this certificate was or will be +expired. + +@strong{Returns:} expiration time, or (time_t)-1 on error. +@end deftypefun + +@subheading gnutls_x509_crt_get_extension_by_oid +@anchor{gnutls_x509_crt_get_extension_by_oid} +@deftypefun {int} {gnutls_x509_crt_get_extension_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{oid}: holds an Object Identified in null terminated string + +@var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one. + +@var{buf}: a pointer to a structure to hold the name (may be null) + +@var{buf_size}: initially holds the size of @code{buf} + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If the certificate does not +contain the specified extension +GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_extension_by_oid2 +@anchor{gnutls_x509_crt_get_extension_by_oid2} +@deftypefun {int} {gnutls_x509_crt_get_extension_by_oid2} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, gnutls_datum_t * @var{output}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{oid}: holds an Object Identified in null terminated string + +@var{indx}: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one. + +@var{output}: will hold the allocated extension data + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If the certificate does not +contain the specified extension +GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_x509_crt_get_extension_data +@anchor{gnutls_x509_crt_get_extension_data} +@deftypefun {int} {gnutls_x509_crt_get_extension_data} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{data}, size_t * @var{sizeof_data}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. + +@var{data}: a pointer to a structure to hold the data (may be null) + +@var{sizeof_data}: initially holds the size of @code{data} + +This function will return the requested extension data in the +certificate. The extension data will be stored in the +provided buffer. + +Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID and +critical flag. Use @code{gnutls_x509_crt_get_extension_by_oid()} instead, +if you want to get data indexed by the extension OID rather than +sequence. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If you have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_extension_data2 +@anchor{gnutls_x509_crt_get_extension_data2} +@deftypefun {int} {gnutls_x509_crt_get_extension_data2} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, gnutls_datum_t * @var{data}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: Specifies which extension OID to read. Use (0) to get the first one. + +@var{data}: will contain the extension DER-encoded data + +This function will return the requested by the index extension data in the +certificate. The extension data will be allocated using +@code{gnutls_malloc()} . + +Use @code{gnutls_x509_crt_get_extension_info()} to extract the OID. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If you have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_extension_info +@anchor{gnutls_x509_crt_get_extension_info} +@deftypefun {int} {gnutls_x509_crt_get_extension_info} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. + +@var{oid}: a pointer to a structure to hold the OID + +@var{oid_size}: initially holds the maximum size of @code{oid} , on return +holds actual size of @code{oid} . + +@var{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 +@code{gnutls_x509_crt_get_extension()} to extract the data. + +If the buffer provided is not long enough to hold the output, then + @code{oid_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will be +returned. The @code{oid} returned will be null terminated, although + @code{oid_size} will not account for the trailing null (the latter is not +true for GnuTLS prior to 3.6.0). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If you have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_extension_oid +@anchor{gnutls_x509_crt_get_extension_oid} +@deftypefun {int} {gnutls_x509_crt_get_extension_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: Specifies which extension OID to send. Use (0) to get the first one. + +@var{oid}: a pointer to a structure to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{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. + +The @code{oid} returned will be null terminated, although @code{oid_size} will not +account for the trailing null. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. If you have reached the +last extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +will be returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_fingerprint +@anchor{gnutls_x509_crt_get_fingerprint} +@deftypefun {int} {gnutls_x509_crt_get_fingerprint} (gnutls_x509_crt_t @var{cert}, gnutls_digest_algorithm_t @var{algo}, void * @var{buf}, size_t * @var{buf_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{algo}: is a digest algorithm + +@var{buf}: a pointer to a structure to hold the fingerprint (may be null) + +@var{buf_size}: initially holds the size of @code{buf} + +This function will calculate and copy the certificate's fingerprint +in the provided buffer. The fingerprint is a hash of the DER-encoded +data of the certificate. + +If the buffer is null then only the size will be filled. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is +not long enough, and in that case the *buf_size will be updated +with the required size. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_inhibit_anypolicy +@anchor{gnutls_x509_crt_get_inhibit_anypolicy} +@deftypefun {int} {gnutls_x509_crt_get_inhibit_anypolicy} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{skipcerts}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{skipcerts}: will hold the number of certificates after which anypolicy is no longer acceptable. + +@var{critical}: will be non-zero if the extension is marked as critical + +This function will return certificate's value of the SkipCerts, i.e., +the Inhibit anyPolicy X.509 extension (2.5.29.54). + +The returned value is the number of additional certificates that +may appear in the path before the anyPolicy is no longer acceptable. + +@strong{Returns:} zero on success, or a negative error code in case of +parsing error. If the certificate does not contain the Inhibit anyPolicy +extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer +@anchor{gnutls_x509_crt_get_issuer} +@deftypefun {int} {gnutls_x509_crt_get_issuer} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: output variable with pointer to uint8_t DN + +Return the Certificate's Issuer DN as a @code{gnutls_x509_dn_t} data type, +that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} . + +Note that @code{dn} should be treated as constant. Because it points +into the @code{cert} object, you should not use @code{dn} after @code{cert} is +deallocated. + +@strong{Returns:} Returns 0 on success, or an error code. +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_alt_name +@anchor{gnutls_x509_crt_get_issuer_alt_name} +@deftypefun {int} {gnutls_x509_crt_get_issuer_alt_name} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ian}, size_t * @var{ian_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{ian}: is the place where the alternative name will be copied to + +@var{ian_size}: holds the size of ian. + +@var{critical}: will be non-zero if the extension is marked as critical (may be null) + +This function retrieves the Issuer Alternative Name (2.5.29.18), +contained in the given certificate in the X509v3 Certificate +Extensions. + +When the SAN type is otherName, it will extract the data in the +otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned. +You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get +the corresponding OID and the "virtual" SAN types (e.g., +@code{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 Issuer +AltName is recognized. + +@strong{Returns:} the alternative issuer name type on success, one of the +enumerated @code{gnutls_x509_subject_alt_name_t} . It will return +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough +to hold the value. In that case @code{ian_size} will be updated with +the required size. If the certificate does not have an +Alternative name with the specified sequence number then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_alt_name2 +@anchor{gnutls_x509_crt_get_issuer_alt_name2} +@deftypefun {int} {gnutls_x509_crt_get_issuer_alt_name2} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ian}, size_t * @var{ian_size}, unsigned int * @var{ian_type}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{ian}: is the place where the alternative name will be copied to + +@var{ian_size}: holds the size of ret. + +@var{ian_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). + +@var{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 +@code{gnutls_x509_crt_get_issuer_alt_name()} except for the fact that it +will return the type of the alternative name in @code{ian_type} even if +the function fails for some reason (i.e. the buffer provided is +not enough). + +@strong{Returns:} the alternative issuer name type on success, one of the +enumerated @code{gnutls_x509_subject_alt_name_t} . It will return +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{ian_size} is not large enough +to hold the value. In that case @code{ian_size} will be updated with +the required size. If the certificate does not have an +Alternative name with the specified sequence number then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_alt_othername_oid +@anchor{gnutls_x509_crt_get_issuer_alt_othername_oid} +@deftypefun {int} {gnutls_x509_crt_get_issuer_alt_othername_oid} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{ret}, size_t * @var{ret_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{ret}: is the place where the otherName OID will be copied to + +@var{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. + +If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not +account for the trailing null. + +This function is only useful if +@code{gnutls_x509_crt_get_issuer_alt_name()} returned +@code{GNUTLS_SAN_OTHERNAME} . + +@strong{Returns:} the alternative issuer 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. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for +unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if + @code{ret_size} is not large enough to hold the value. In that case + @code{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 +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_dn +@anchor{gnutls_x509_crt_get_issuer_dn} +@deftypefun {int} {gnutls_x509_crt_get_issuer_dn} (gnutls_x509_crt_t @var{cert}, char * @var{buf}, size_t * @var{buf_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{buf}: a pointer to a structure to hold the name (may be null) + +@var{buf_size}: initially holds the size of @code{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 RFC4514. The output string +will be ASCII or UTF-8 encoded, depending on the certificate data. + +If @code{buf} is null then only the size will be filled. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crt_get_issuer_dn3()} . + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the @code{buf_size} will be updated +with the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if +the DN does not exist, or another error value on error. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_dn2 +@anchor{gnutls_x509_crt_get_issuer_dn2} +@deftypefun {int} {gnutls_x509_crt_get_issuer_dn2} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +This function will allocate buffer and copy the name of issuer of the Certificate. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_crt_get_issuer_dn3()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_dn3 +@anchor{gnutls_x509_crt_get_issuer_dn3} +@deftypefun {int} {gnutls_x509_crt_get_issuer_dn3} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: a pointer to a structure to hold the name; must be freed using @code{gnutls_free()} + +@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} + +This function will allocate buffer and copy the name of issuer of the Certificate. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.7 +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_dn_by_oid +@anchor{gnutls_x509_crt_get_issuer_dn_by_oid} +@deftypefun {int} {gnutls_x509_crt_get_issuer_dn_by_oid} (gnutls_x509_crt_t @var{cert}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{oid}: holds an Object Identified in null terminated string + +@var{indx}: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one. + +@var{raw_flag}: If non-zero returns the raw DER data of the DN part. + +@var{buf}: a pointer to a structure to hold the name (may be null) + +@var{buf_size}: initially holds the size of @code{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 RFC4514. 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 (0), this function will only return known OIDs as +text. Other OIDs will be DER encoded, as described in RFC4514 -- +in hex format with a '#' prefix. You can check about known OIDs +using @code{gnutls_x509_dn_oid_known()} . + +If @code{buf} is null then only the size will be filled. If the @code{raw_flag} is not specified the output is always null terminated, although the + @code{buf_size} will not include the null character. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the @code{buf_size} will be updated with +the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there +are no data in the current index. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_dn_oid +@anchor{gnutls_x509_crt_get_issuer_dn_oid} +@deftypefun {int} {gnutls_x509_crt_get_issuer_dn_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: This specifies which OID to return. Use (0) to get the first one. + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will extract the OIDs of the name of the Certificate +issuer specified by the given index. + +If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not +account for the trailing null. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is not +long enough, and in that case the @code{buf_size} will be updated with +the required size. @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if there +are no data in the current index. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_issuer_unique_id +@anchor{gnutls_x509_crt_get_issuer_unique_id} +@deftypefun {int} {gnutls_x509_crt_get_issuer_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size}) +@var{crt}: Holds the certificate + +@var{buf}: user allocated memory buffer, will hold the unique id + +@var{buf_size}: size of user allocated memory buffer (on input), will hold +actual size of the unique ID on return. + +This function will extract the issuerUniqueID value (if present) for +the given certificate. + +If the user allocated memory buffer is not large enough to hold the +full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be +returned, and buf_size will be set to the actual length. + +This function had a bug prior to 3.4.8 that prevented the setting +of @code{NULL} @code{buf} to discover the @code{buf_size} . To use this function safely +with the older versions the @code{buf} must be a valid buffer that can hold +at least a single byte if @code{buf_size} is zero. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_key_id +@anchor{gnutls_x509_crt_get_key_id} +@deftypefun {int} {gnutls_x509_crt_get_key_id} (gnutls_x509_crt_t @var{crt}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}) +@var{crt}: Holds the certificate + +@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} + +@var{output_data}: will contain the key ID + +@var{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 that 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. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. +@end deftypefun + +@subheading gnutls_x509_crt_get_key_purpose_oid +@anchor{gnutls_x509_crt_get_key_purpose_oid} +@deftypefun {int} {gnutls_x509_crt_get_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, unsigned @var{indx}, void * @var{oid}, size_t * @var{oid_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: This specifies which OID to return. Use (0) to get the first one. + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +@var{critical}: output flag to indicate criticality of extension + +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 @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not +account for the trailing null. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the provided buffer is +not long enough, and in that case the *oid_size will be updated +with the required size. On success 0 is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_key_usage +@anchor{gnutls_x509_crt_get_key_usage} +@deftypefun {int} {gnutls_x509_crt_get_key_usage} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{key_usage}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{key_usage}: where the key usage bits will be stored + +@var{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: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} , +@code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} , +@code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} , +@code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} , +@code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} . + +@strong{Returns:} zero on success, or a negative error code in case of +parsing error. If the certificate does not contain the keyUsage +extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_name_constraints +@anchor{gnutls_x509_crt_get_name_constraints} +@deftypefun {int} {gnutls_x509_crt_get_name_constraints} (gnutls_x509_crt_t @var{crt}, gnutls_x509_name_constraints_t @var{nc}, unsigned int @var{flags}, unsigned int * @var{critical}) +@var{crt}: should contain a @code{gnutls_x509_crt_t} type + +@var{nc}: The nameconstraints intermediate type + +@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} + +@var{critical}: the extension status + +This function will return an intermediate type containing +the name constraints of the provided CA certificate. That +structure can be used in combination with @code{gnutls_x509_name_constraints_check()} +to verify whether a server's name is in accordance with the constraints. + +When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , +then if the @code{nc} structure is empty this function will behave +identically as if the flag was not set. +Otherwise if there are elements in the @code{nc} structure then the +constraints will be merged with the existing constraints following +RFC5280 p6.1.4 (excluded constraints will be appended, permitted +will be intersected). + +Note that @code{nc} must be initialized prior to calling this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_pk_algorithm +@anchor{gnutls_x509_crt_get_pk_algorithm} +@deftypefun {int} {gnutls_x509_crt_get_pk_algorithm} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{bits}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{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. + +Unknown/unsupported algorithms are mapped to @code{GNUTLS_PK_UNKNOWN} . + +@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on +success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crt_get_pk_dsa_raw +@anchor{gnutls_x509_crt_get_pk_dsa_raw} +@deftypefun {int} {gnutls_x509_crt_get_pk_dsa_raw} (gnutls_x509_crt_t @var{crt}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}) +@var{crt}: Holds the certificate + +@var{p}: will hold the p + +@var{q}: will hold the q + +@var{g}: will hold the g + +@var{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 +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_x509_crt_get_pk_ecc_raw +@anchor{gnutls_x509_crt_get_pk_ecc_raw} +@deftypefun {int} {gnutls_x509_crt_get_pk_ecc_raw} (gnutls_x509_crt_t @var{crt}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}) +@var{crt}: Holds the certificate + +@var{curve}: will hold the curve + +@var{x}: will hold the x-coordinate + +@var{y}: will hold the y-coordinate + +This function will export the ECC public key's parameters found in +the given certificate. The new parameters will be allocated using +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +In EdDSA curves the @code{y} parameter will be @code{NULL} and the other parameters +will be in the native format for the curve. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.4.1 +@end deftypefun + +@subheading gnutls_x509_crt_get_pk_gost_raw +@anchor{gnutls_x509_crt_get_pk_gost_raw} +@deftypefun {int} {gnutls_x509_crt_get_pk_gost_raw} (gnutls_x509_crt_t @var{crt}, gnutls_ecc_curve_t * @var{curve}, gnutls_digest_algorithm_t * @var{digest}, gnutls_gost_paramset_t * @var{paramset}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}) +@var{crt}: Holds the certificate + +@var{curve}: will hold the curve + +@var{digest}: will hold the digest + +@var{paramset}: will hold the GOST parameter set ID + +@var{x}: will hold the x-coordinate + +@var{y}: will hold the y-coordinate + +This function will export the GOST public key's parameters found in +the given certificate. The new parameters will be allocated using +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_x509_crt_get_pk_oid +@anchor{gnutls_x509_crt_get_pk_oid} +@deftypefun {int} {gnutls_x509_crt_get_pk_oid} (gnutls_x509_crt_t @var{cert}, char * @var{oid}, size_t * @var{oid_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will return the OID of the public key algorithm +on that certificate. This is function +is useful in the case @code{gnutls_x509_crt_get_pk_algorithm()} +returned @code{GNUTLS_PK_UNKNOWN} . + +@strong{Returns:} zero or a negative error code on error. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_pk_rsa_raw +@anchor{gnutls_x509_crt_get_pk_rsa_raw} +@deftypefun {int} {gnutls_x509_crt_get_pk_rsa_raw} (gnutls_x509_crt_t @var{crt}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}) +@var{crt}: Holds the certificate + +@var{m}: will hold the modulus + +@var{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 +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_x509_crt_get_policy +@anchor{gnutls_x509_crt_get_policy} +@deftypefun {int} {gnutls_x509_crt_get_policy} (gnutls_x509_crt_t @var{crt}, unsigned @var{indx}, struct gnutls_x509_policy_st * @var{policy}, unsigned int * @var{critical}) +@var{crt}: should contain a @code{gnutls_x509_crt_t} type + +@var{indx}: This specifies which policy to return. Use (0) to get the first one. + +@var{policy}: A pointer to a policy structure. + +@var{critical}: will be non-zero if the extension is marked as critical + +This function will extract the certificate policy (extension 2.5.29.32) +specified by the given index. + +The policy returned by this function must be deinitialized by using +@code{gnutls_x509_policy_release()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.1.5 +@end deftypefun + +@subheading gnutls_x509_crt_get_private_key_usage_period +@anchor{gnutls_x509_crt_get_private_key_usage_period} +@deftypefun {int} {gnutls_x509_crt_get_private_key_usage_period} (gnutls_x509_crt_t @var{cert}, time_t * @var{activation}, time_t * @var{expiration}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{activation}: The activation time + +@var{expiration}: The expiration time + +@var{critical}: the extension status + +This function will return the expiration and activation +times of the private key of the certificate. It relies on +the PKIX extension 2.5.29.16 being present. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_get_proxy +@anchor{gnutls_x509_crt_get_proxy} +@deftypefun {int} {gnutls_x509_crt_get_proxy} (gnutls_x509_crt_t @var{cert}, unsigned int * @var{critical}, int * @var{pathlen}, char ** @var{policyLanguage}, char ** @var{policy}, size_t * @var{sizeof_policy}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{critical}: will be non-zero if the extension is marked as critical + +@var{pathlen}: pointer to output integer indicating path length (may be +NULL), non-negative error codes indicate a present pCPathLenConstraint +field and the actual value, -1 indicate that the field is absent. + +@var{policyLanguage}: output variable with OID of policy language + +@var{policy}: output variable with policy data + +@var{sizeof_policy}: output variable size of policy data + +This function will get information from a proxy certificate. It +reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_raw_dn +@anchor{gnutls_x509_crt_get_raw_dn} +@deftypefun {int} {gnutls_x509_crt_get_raw_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: will hold the starting point of the DN + +This function will return a pointer to the DER encoded DN structure and +the length. This points to allocated data that must be free'd using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crt_get_raw_issuer_dn +@anchor{gnutls_x509_crt_get_raw_issuer_dn} +@deftypefun {int} {gnutls_x509_crt_get_raw_issuer_dn} (gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{dn}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: will hold the starting point of the DN + +This function will return a pointer to the DER encoded DN structure +and the length. This points to allocated data that must be free'd using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value.or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crt_get_serial +@anchor{gnutls_x509_crt_get_serial} +@deftypefun {int} {gnutls_x509_crt_get_serial} (gnutls_x509_crt_t @var{cert}, void * @var{result}, size_t * @var{result_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{result}: The place where the serial number will be copied + +@var{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 uint8_t. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_get_signature +@anchor{gnutls_x509_crt_get_signature} +@deftypefun {int} {gnutls_x509_crt_get_signature} (gnutls_x509_crt_t @var{cert}, char * @var{sig}, size_t * @var{sig_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{sig}: a pointer where the signature part will be copied (may be null). + +@var{sig_size}: initially holds the size of @code{sig} + +This function will extract the signature field of a certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_get_signature_algorithm +@anchor{gnutls_x509_crt_get_signature_algorithm} +@deftypefun {int} {gnutls_x509_crt_get_signature_algorithm} (gnutls_x509_crt_t @var{cert}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +This function will return a value of the @code{gnutls_sign_algorithm_t} +enumeration that is the signature algorithm that has been used to +sign this certificate. + +Since 3.6.0 this function never returns a negative error code. +Error cases and unknown/unsupported signature algorithms are +mapped to @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Returns:} a @code{gnutls_sign_algorithm_t} value +@end deftypefun + +@subheading gnutls_x509_crt_get_signature_oid +@anchor{gnutls_x509_crt_get_signature_oid} +@deftypefun {int} {gnutls_x509_crt_get_signature_oid} (gnutls_x509_crt_t @var{cert}, char * @var{oid}, size_t * @var{oid_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{oid}: a pointer to a buffer to hold the OID (may be null) + +@var{oid_size}: initially holds the size of @code{oid} + +This function will return the OID of the signature algorithm +that has been used to sign this certificate. This is function +is useful in the case @code{gnutls_x509_crt_get_signature_algorithm()} +returned @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Returns:} zero or a negative error code on error. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_spki +@anchor{gnutls_x509_crt_get_spki} +@deftypefun {int} {gnutls_x509_crt_get_spki} (gnutls_x509_crt_t @var{cert}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} + +@var{flags}: must be zero + +This function will return the public key information of an X.509 +certificate. The provided @code{spki} must be initialized. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_crt_get_subject +@anchor{gnutls_x509_crt_get_subject} +@deftypefun {int} {gnutls_x509_crt_get_subject} (gnutls_x509_crt_t @var{cert}, gnutls_x509_dn_t * @var{dn}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{dn}: output variable with pointer to uint8_t DN. + +Return the Certificate's Subject DN as a @code{gnutls_x509_dn_t} data type, +that can be decoded using @code{gnutls_x509_dn_get_rdn_ava()} . + +Note that @code{dn} should be treated as constant. Because it points +into the @code{cert} object, you should not use @code{dn} after @code{cert} is +deallocated. + +@strong{Returns:} Returns 0 on success, or an error code. +@end deftypefun + +@subheading gnutls_x509_crt_get_subject_alt_name +@anchor{gnutls_x509_crt_get_subject_alt_name} +@deftypefun {int} {gnutls_x509_crt_get_subject_alt_name} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{san}, size_t * @var{san_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{san}: is the place where the alternative name will be copied to + +@var{san_size}: holds the size of san. + +@var{critical}: will be non-zero if the extension is marked as critical (may be null) + +This function retrieves the Alternative Name (2.5.29.17), contained +in the given certificate in the X509v3 Certificate Extensions. + +When the SAN type is otherName, it will extract the data in the +otherName's value field, and @code{GNUTLS_SAN_OTHERNAME} is returned. +You may use @code{gnutls_x509_crt_get_subject_alt_othername_oid()} to get +the corresponding OID and the "virtual" SAN types (e.g., +@code{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. + +@strong{Returns:} the alternative subject name type on success, one of the +enumerated @code{gnutls_x509_subject_alt_name_t} . It will return +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough to +hold the value. In that case @code{san_size} will be updated with the +required size. If the certificate does not have an Alternative +name with the specified sequence number then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_subject_alt_name2 +@anchor{gnutls_x509_crt_get_subject_alt_name2} +@deftypefun {int} {gnutls_x509_crt_get_subject_alt_name2} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{san}, size_t * @var{san_size}, unsigned int * @var{san_type}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{san}: is the place where the alternative name will be copied to + +@var{san_size}: holds the size of ret. + +@var{san_type}: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t). + +@var{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 +@code{gnutls_x509_crt_get_subject_alt_name()} except for the fact that it +will return the type of the alternative name in @code{san_type} even if +the function fails for some reason (i.e. the buffer provided is +not enough). + +@strong{Returns:} the alternative subject name type on success, one of the +enumerated @code{gnutls_x509_subject_alt_name_t} . It will return +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} if @code{san_size} is not large enough +to hold the value. In that case @code{san_size} will be updated with +the required size. If the certificate does not have an +Alternative name with the specified sequence number then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_subject_alt_othername_oid +@anchor{gnutls_x509_crt_get_subject_alt_othername_oid} +@deftypefun {int} {gnutls_x509_crt_get_subject_alt_othername_oid} (gnutls_x509_crt_t @var{cert}, unsigned int @var{seq}, void * @var{oid}, size_t * @var{oid_size}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{seq}: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.) + +@var{oid}: is the place where the otherName OID will be copied to + +@var{oid_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 +@code{gnutls_x509_crt_get_subject_alt_name()} returned +@code{GNUTLS_SAN_OTHERNAME} . + +If @code{oid} is null then only the size will be filled. The @code{oid} returned will be null terminated, although @code{oid_size} will not +account for the trailing null. + +@strong{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. @code{GNUTLS_SAN_OTHERNAME_XMPP} , and @code{GNUTLS_SAN_OTHERNAME} for +unknown OIDs. It will return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if + @code{ian_size} is not large enough to hold the value. In that case + @code{ian_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 +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. +@end deftypefun + +@subheading gnutls_x509_crt_get_subject_key_id +@anchor{gnutls_x509_crt_get_subject_key_id} +@deftypefun {int} {gnutls_x509_crt_get_subject_key_id} (gnutls_x509_crt_t @var{cert}, void * @var{ret}, size_t * @var{ret_size}, unsigned int * @var{critical}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +@var{ret}: The place where the identifier will be copied + +@var{ret_size}: Holds the size of the result field. + +@var{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). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_get_subject_unique_id +@anchor{gnutls_x509_crt_get_subject_unique_id} +@deftypefun {int} {gnutls_x509_crt_get_subject_unique_id} (gnutls_x509_crt_t @var{crt}, char * @var{buf}, size_t * @var{buf_size}) +@var{crt}: Holds the certificate + +@var{buf}: user allocated memory buffer, will hold the unique id + +@var{buf_size}: size of user allocated memory buffer (on input), will hold +actual size of the unique ID on return. + +This function will extract the subjectUniqueID value (if present) for +the given certificate. + +If the user allocated memory buffer is not large enough to hold the +full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be +returned, and buf_size will be set to the actual length. + +This function had a bug prior to 3.4.8 that prevented the setting +of @code{NULL} @code{buf} to discover the @code{buf_size} . To use this function safely +with the older versions the @code{buf} must be a valid buffer that can hold +at least a single byte if @code{buf_size} is zero. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_x509_crt_get_tlsfeatures +@anchor{gnutls_x509_crt_get_tlsfeatures} +@deftypefun {int} {gnutls_x509_crt_get_tlsfeatures} (gnutls_x509_crt_t @var{crt}, gnutls_x509_tlsfeatures_t @var{features}, unsigned int @var{flags}, unsigned int * @var{critical}) +@var{crt}: A X.509 certificate + +@var{features}: If the function succeeds, the +features will be stored in this variable. + +@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} + +@var{critical}: the extension status + +This function will get the X.509 TLS features +extension structure from the certificate. The +returned structure needs to be freed using +@code{gnutls_x509_tlsfeatures_deinit()} . + +When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , +then if the @code{features} structure is empty this function will behave +identically as if the flag was not set. Otherwise if there are elements +in the @code{features} structure then they will be merged with. + +Note that @code{features} must be initialized prior to calling this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_crt_get_version +@anchor{gnutls_x509_crt_get_version} +@deftypefun {int} {gnutls_x509_crt_get_version} (gnutls_x509_crt_t @var{cert}) +@var{cert}: should contain a @code{gnutls_x509_crt_t} type + +This function will return the version of the specified Certificate. + +@strong{Returns:} version of certificate, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_crt_import +@anchor{gnutls_x509_crt_import} +@deftypefun {int} {gnutls_x509_crt_import} (gnutls_x509_crt_t @var{cert}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) +@var{cert}: The data to store the parsed certificate. + +@var{data}: The DER or PEM encoded certificate. + +@var{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 @code{cert} . + +If the Certificate is PEM encoded it should have a header of "X509 +CERTIFICATE", or "CERTIFICATE". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_import_url +@anchor{gnutls_x509_crt_import_url} +@deftypefun {int} {gnutls_x509_crt_import_url} (gnutls_x509_crt_t @var{crt}, const char * @var{url}, unsigned int @var{flags}) +@var{crt}: A certificate of type @code{gnutls_x509_crt_t} + +@var{url}: A PKCS 11 url + +@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags for PKCS@code{11} URLs or zero otherwise + +This function will import a certificate present in a PKCS@code{11} token +or any type of back-end that supports URLs. + +In previous versions of gnutls this function was named +gnutls_x509_crt_import_pkcs11_url, and the old name is +an alias to this one. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_crt_init +@anchor{gnutls_x509_crt_init} +@deftypefun {int} {gnutls_x509_crt_init} (gnutls_x509_crt_t * @var{cert}) +@var{cert}: A pointer to the type to be initialized + +This function will initialize an X.509 certificate structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_list_import +@anchor{gnutls_x509_crt_list_import} +@deftypefun {int} {gnutls_x509_crt_list_import} (gnutls_x509_crt_t * @var{certs}, unsigned int * @var{cert_max}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) +@var{certs}: Indicates where the parsed list will be copied to. Must not be initialized. + +@var{cert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available. + +@var{data}: The PEM encoded certificate. + +@var{format}: One of DER or PEM. + +@var{flags}: must be (0) 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 @code{certs} . They will be automatically initialized. + +The flag @code{GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED} will cause +import to fail if the certificates in the provided buffer are more +than the available structures. The @code{GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED} +flag will cause the function to fail if the provided list is not +sorted from subject to issuer. + +If the Certificate is PEM encoded it should have a header of "X509 +CERTIFICATE", or "CERTIFICATE". + +@strong{Returns:} the number of certificates read or a negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_list_import2 +@anchor{gnutls_x509_crt_list_import2} +@deftypefun {int} {gnutls_x509_crt_list_import2} (gnutls_x509_crt_t ** @var{certs}, unsigned int * @var{size}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) +@var{certs}: Will hold the parsed certificate list. + +@var{size}: It will contain the size of the list. + +@var{data}: The PEM encoded certificate. + +@var{format}: One of DER or PEM. + +@var{flags}: must be (0) 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 @code{certs} which will be allocated and initialized. + +If the Certificate is PEM encoded it should have a header of "X509 +CERTIFICATE", or "CERTIFICATE". + +To deinitialize @code{certs} , you need to deinitialize each crt structure +independently, and use @code{gnutls_free()} at @code{certs} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crt_list_import_url +@anchor{gnutls_x509_crt_list_import_url} +@deftypefun {int} {gnutls_x509_crt_list_import_url} (gnutls_x509_crt_t ** @var{certs}, unsigned int * @var{size}, const char * @var{url}, gnutls_pin_callback_t @var{pin_fn}, void * @var{pin_fn_userdata}, unsigned int @var{flags}) +@var{certs}: Will hold the allocated certificate list. + +@var{size}: It will contain the size of the list. + +@var{url}: A PKCS 11 url + +@var{pin_fn}: a PIN callback if not globally set + +@var{pin_fn_userdata}: parameter for the PIN callback + +@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags for PKCS@code{11} URLs or zero otherwise + +This function will import a certificate chain present in a PKCS@code{11} token +or any type of back-end that supports URLs. The certificates +must be deinitialized afterwards using @code{gnutls_x509_crt_deinit()} +and the returned pointer must be freed using @code{gnutls_free()} . + +The URI provided must be the first certificate in the chain; subsequent +certificates will be retrieved using @code{gnutls_pkcs11_get_raw_issuer()} or +equivalent functionality for the supported URI. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_x509_crt_list_verify +@anchor{gnutls_x509_crt_list_verify} +@deftypefun {int} {gnutls_x509_crt_list_verify} (const gnutls_x509_crt_t * @var{cert_list}, unsigned @var{cert_list_length}, const gnutls_x509_crt_t * @var{CA_list}, unsigned @var{CA_list_length}, const gnutls_x509_crl_t * @var{CRL_list}, unsigned @var{CRL_list_length}, unsigned int @var{flags}, unsigned int * @var{verify}) +@var{cert_list}: is the certificate list to be verified + +@var{cert_list_length}: holds the number of certificate in cert_list + +@var{CA_list}: is the CA list which will be used in verification + +@var{CA_list_length}: holds the number of CA certificate in CA_list + +@var{CRL_list}: holds a list of CRLs. + +@var{CRL_list_length}: the length of CRL list. + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +@var{verify}: will hold the certificate verification output. + + +This function will try to verify the given certificate list and +return its status. The details of the verification are the same +as in @code{gnutls_x509_trust_list_verify_crt2()} . + +You must 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 @code{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 +@code{gnutls_x509_crt_verify()} per list element. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_print +@anchor{gnutls_x509_crt_print} +@deftypefun {int} {gnutls_x509_crt_print} (gnutls_x509_crt_t @var{cert}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) +@var{cert}: The data to be printed + +@var{format}: Indicate the format to use + +@var{out}: Newly allocated datum with null terminated string. + +This function will pretty print a X.509 certificate, suitable for +display to a human. + +If the format is @code{GNUTLS_CRT_PRINT_FULL} then all fields of the +certificate will be output, on multiple lines. The +@code{GNUTLS_CRT_PRINT_ONELINE} format will generate one line with some +selected fields, which is useful for logging purposes. + +The output @code{out} needs to be deallocated using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_activation_time +@anchor{gnutls_x509_crt_set_activation_time} +@deftypefun {int} {gnutls_x509_crt_set_activation_time} (gnutls_x509_crt_t @var{cert}, time_t @var{act_time}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{act_time}: The actual time + +This function will set the time this certificate was or will be +activated. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_authority_info_access +@anchor{gnutls_x509_crt_set_authority_info_access} +@deftypefun {int} {gnutls_x509_crt_set_authority_info_access} (gnutls_x509_crt_t @var{crt}, int @var{what}, gnutls_datum_t * @var{data}) +@var{crt}: Holds the certificate + +@var{what}: what data to get, a @code{gnutls_info_access_what_t} type. + +@var{data}: output data to be freed with @code{gnutls_free()} . + +This function sets the Authority Information Access (AIA) +extension, see RFC 5280 section 4.2.2.1 for more information. + +The type of data stored in @code{data} is specified via @code{what} which +should be @code{gnutls_info_access_what_t} values. + +If @code{what} is @code{GNUTLS_IA_OCSP_URI} , @code{data} will hold the OCSP URI. +If @code{what} is @code{GNUTLS_IA_CAISSUERS_URI} , @code{data} will hold the caIssuers +URI. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_authority_key_id +@anchor{gnutls_x509_crt_set_authority_key_id} +@deftypefun {int} {gnutls_x509_crt_set_authority_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{id}: The key ID + +@var{id_size}: Holds the size of the key ID field. + +This function will set the X.509 certificate's authority key ID extension. +Only the keyIdentifier field can be set with this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_basic_constraints +@anchor{gnutls_x509_crt_set_basic_constraints} +@deftypefun {int} {gnutls_x509_crt_set_basic_constraints} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}, int @var{pathLenConstraint}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{ca}: true(1) or false(0). Depending on the Certificate authority status. + +@var{pathLenConstraint}: non-negative error codes indicate maximum length of path, +and negative error codes indicate that the pathLenConstraints field should +not be present. + +This function will set the basicConstraints certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_ca_status +@anchor{gnutls_x509_crt_set_ca_status} +@deftypefun {int} {gnutls_x509_crt_set_ca_status} (gnutls_x509_crt_t @var{crt}, unsigned int @var{ca}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{ca}: true(1) or false(0). Depending on the Certificate authority status. + +This function will set the basicConstraints certificate extension. +Use @code{gnutls_x509_crt_set_basic_constraints()} if you want to control +the pathLenConstraint field too. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_crl_dist_points +@anchor{gnutls_x509_crt_set_crl_dist_points} +@deftypefun {int} {gnutls_x509_crt_set_crl_dist_points} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data_string}, unsigned int @var{reason_flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations + +@var{data_string}: The data to be set + +@var{reason_flags}: revocation reasons + +This function will set the CRL distribution points certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_crl_dist_points2 +@anchor{gnutls_x509_crt_set_crl_dist_points2} +@deftypefun {int} {gnutls_x509_crt_set_crl_dist_points2} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{reason_flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations + +@var{data}: The data to be set + +@var{data_size}: The data size + +@var{reason_flags}: revocation reasons + +This function will set the CRL distribution points certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_crq +@anchor{gnutls_x509_crt_set_crq} +@deftypefun {int} {gnutls_x509_crt_set_crq} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{crq}: holds a certificate request + +This function will set the name and public parameters as well as +the extensions from the given certificate request to the certificate. +Only RSA keys are currently supported. + +Note that this function will only set the @code{crq} if it is self +signed and the signature is correct. See @code{gnutls_x509_crq_sign2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_crq_extension_by_oid +@anchor{gnutls_x509_crt_set_crq_extension_by_oid} +@deftypefun {int} {gnutls_x509_crt_set_crq_extension_by_oid} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq}, const char * @var{oid}, unsigned @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{crq}: holds a certificate request + +@var{oid}: the object identifier of the OID to copy + +@var{flags}: should be zero + +This function will set the extension specify by @code{oid} from the given request to the +certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_crt_set_crq_extensions +@anchor{gnutls_x509_crt_set_crq_extensions} +@deftypefun {int} {gnutls_x509_crt_set_crq_extensions} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crq_t @var{crq}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{crq}: holds a certificate request + +This function will set the extensions from the given request to the +certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_dn +@anchor{gnutls_x509_crt_set_dn} +@deftypefun {int} {gnutls_x509_crt_set_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{dn}: a comma separated DN string (RFC4514) + +@var{err}: indicates the error position (if any) + +This function will set the DN on the provided certificate. +The input string should be plain ASCII or UTF-8 encoded. On +DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. + +Note that DNs are not expected to hold DNS information, and thus +no automatic IDNA conversions are attempted when using this function. +If that is required (e.g., store a domain in CN), process the corresponding +input with @code{gnutls_idna_map()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_dn_by_oid +@anchor{gnutls_x509_crt_set_dn_by_oid} +@deftypefun {int} {gnutls_x509_crt_set_dn_by_oid} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, unsigned int @var{raw_flag}, const void * @var{name}, unsigned int @var{sizeof_name}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{oid}: holds an Object Identifier in a null terminated string + +@var{raw_flag}: must be 0, or 1 if the data are DER encoded + +@var{name}: a pointer to the name + +@var{sizeof_name}: holds the size of @code{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 @code{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 @code{raw_flag} set. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_expiration_time +@anchor{gnutls_x509_crt_set_expiration_time} +@deftypefun {int} {gnutls_x509_crt_set_expiration_time} (gnutls_x509_crt_t @var{cert}, time_t @var{exp_time}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{exp_time}: The actual time + +This function will set the time this Certificate will expire. +Setting an expiration time to (time_t)-1 will set +to the no well-defined expiration date value. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_extension_by_oid +@anchor{gnutls_x509_crt_set_extension_by_oid} +@deftypefun {int} {gnutls_x509_crt_set_extension_by_oid} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, const void * @var{buf}, size_t @var{sizeof_buf}, unsigned int @var{critical}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{oid}: holds an Object Identifier in null terminated string + +@var{buf}: a pointer to a DER encoded data + +@var{sizeof_buf}: holds the size of @code{buf} + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_flags +@anchor{gnutls_x509_crt_set_flags} +@deftypefun {void} {gnutls_x509_crt_set_flags} (gnutls_x509_crt_t @var{cert}, unsigned int @var{flags}) +@var{cert}: A type @code{gnutls_x509_crt_t} + +@var{flags}: flags from the @code{gnutls_x509_crt_flags} + +This function will set flags for the specified certificate. +Currently this is useful for the @code{GNUTLS_X509_CRT_FLAG_IGNORE_SANITY} +which allows importing certificates even if they have known issues. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_inhibit_anypolicy +@anchor{gnutls_x509_crt_set_inhibit_anypolicy} +@deftypefun {int} {gnutls_x509_crt_set_inhibit_anypolicy} (gnutls_x509_crt_t @var{crt}, unsigned int @var{skipcerts}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{skipcerts}: number of certificates after which anypolicy is no longer acceptable. + +This function will set the Inhibit anyPolicy certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_issuer_alt_name +@anchor{gnutls_x509_crt_set_issuer_alt_name} +@deftypefun {int} {gnutls_x509_crt_set_issuer_alt_name} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations + +@var{data}: The data to be set + +@var{data_size}: The size of data to be set + +@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. + +This function will set the issuer alternative name certificate +extension. It can set the same types as @code{gnutls_x509_crt_set_subject_alt_name()} . + +Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and +@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_issuer_alt_othername +@anchor{gnutls_x509_crt_set_issuer_alt_othername} +@deftypefun {int} {gnutls_x509_crt_set_issuer_alt_othername} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{oid}: The other name OID + +@var{data}: The data to be set + +@var{data_size}: The size of data to be set + +@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. + +This function will set an "othername" to the issuer alternative name certificate +extension. + +The values set are set as binary values and are expected to have the proper DER encoding. +For convenience the flags @code{GNUTLS_FSAN_ENCODE_OCTET_STRING} and @code{GNUTLS_FSAN_ENCODE_UTF8_STRING} +can be used to encode the provided data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_issuer_dn +@anchor{gnutls_x509_crt_set_issuer_dn} +@deftypefun {int} {gnutls_x509_crt_set_issuer_dn} (gnutls_x509_crt_t @var{crt}, const char * @var{dn}, const char ** @var{err}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{dn}: a comma separated DN string (RFC4514) + +@var{err}: indicates the error position (if any) + +This function will set the DN on the provided certificate. +The input string should be plain ASCII or UTF-8 encoded. On +DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_issuer_dn_by_oid +@anchor{gnutls_x509_crt_set_issuer_dn_by_oid} +@deftypefun {int} {gnutls_x509_crt_set_issuer_dn_by_oid} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, unsigned int @var{raw_flag}, const void * @var{name}, unsigned int @var{sizeof_name}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{oid}: holds an Object Identifier in a null terminated string + +@var{raw_flag}: must be 0, or 1 if the data are DER encoded + +@var{name}: a pointer to the name + +@var{sizeof_name}: holds the size of @code{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 @code{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 @code{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_issuer_unique_id +@anchor{gnutls_x509_crt_set_issuer_unique_id} +@deftypefun {int} {gnutls_x509_crt_set_issuer_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{id}: The unique ID + +@var{id_size}: Holds the size of the unique ID. + +This function will set the X.509 certificate's issuer unique ID field. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.7 +@end deftypefun + +@subheading gnutls_x509_crt_set_key +@anchor{gnutls_x509_crt_set_key} +@deftypefun {int} {gnutls_x509_crt_set_key} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{key}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{key}: holds a private key + +This function will set the public parameters from the given +private key to the certificate. + +To export the public key (i.e., the SubjectPublicKeyInfo part), check +@code{gnutls_pubkey_import_x509()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_key_purpose_oid +@anchor{gnutls_x509_crt_set_key_purpose_oid} +@deftypefun {int} {gnutls_x509_crt_set_key_purpose_oid} (gnutls_x509_crt_t @var{cert}, const void * @var{oid}, unsigned int @var{critical}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{oid}: a pointer to a null terminated string that holds the OID + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_x509_crt_set_key_usage +@anchor{gnutls_x509_crt_set_key_usage} +@deftypefun {int} {gnutls_x509_crt_set_key_usage} (gnutls_x509_crt_t @var{crt}, unsigned int @var{usage}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements. + +This function will set the keyUsage certificate extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_name_constraints +@anchor{gnutls_x509_crt_set_name_constraints} +@deftypefun {int} {gnutls_x509_crt_set_name_constraints} (gnutls_x509_crt_t @var{crt}, gnutls_x509_name_constraints_t @var{nc}, unsigned int @var{critical}) +@var{crt}: The certificate + +@var{nc}: The nameconstraints structure + +@var{critical}: whether this extension will be critical + +This function will set the provided name constraints to +the certificate extension list. This extension is always +marked as critical. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_pin_function +@anchor{gnutls_x509_crt_set_pin_function} +@deftypefun {void} {gnutls_x509_crt_set_pin_function} (gnutls_x509_crt_t @var{crt}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) +@var{crt}: The certificate structure + +@var{fn}: the callback + +@var{userdata}: data associated with the callback + +This function will set a callback function to be used when +it is required to access a protected object. This function overrides +the global function set using @code{gnutls_pkcs11_set_pin_function()} . + +Note that this callback is currently used only during the import +of a PKCS @code{11} certificate with @code{gnutls_x509_crt_import_url()} . + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_policy +@anchor{gnutls_x509_crt_set_policy} +@deftypefun {int} {gnutls_x509_crt_set_policy} (gnutls_x509_crt_t @var{crt}, const struct gnutls_x509_policy_st * @var{policy}, unsigned int @var{critical}) +@var{crt}: should contain a @code{gnutls_x509_crt_t} type + +@var{policy}: A pointer to a policy + +@var{critical}: use non-zero if the extension is marked as critical + +This function will set the certificate policy extension (2.5.29.32). +Multiple calls to this function append a new policy. + +Note the maximum text size for the qualifier @code{GNUTLS_X509_QUALIFIER_NOTICE} +is 200 characters. This function will fail with @code{GNUTLS_E_INVALID_REQUEST} +if this is exceeded. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.1.5 +@end deftypefun + +@subheading gnutls_x509_crt_set_private_key_usage_period +@anchor{gnutls_x509_crt_set_private_key_usage_period} +@deftypefun {int} {gnutls_x509_crt_set_private_key_usage_period} (gnutls_x509_crt_t @var{crt}, time_t @var{activation}, time_t @var{expiration}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{activation}: The activation time + +@var{expiration}: The expiration time + +This function will set the private key usage period extension (2.5.29.16). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_proxy +@anchor{gnutls_x509_crt_set_proxy} +@deftypefun {int} {gnutls_x509_crt_set_proxy} (gnutls_x509_crt_t @var{crt}, int @var{pathLenConstraint}, const char * @var{policyLanguage}, const char * @var{policy}, size_t @var{sizeof_policy}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{pathLenConstraint}: non-negative error codes indicate maximum length of path, +and negative error codes indicate that the pathLenConstraints field should +not be present. + +@var{policyLanguage}: OID describing the language of @code{policy} . + +@var{policy}: uint8_t byte array with policy language, can be @code{NULL} + +@var{sizeof_policy}: size of @code{policy} . + +This function will set the proxyCertInfo extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_proxy_dn +@anchor{gnutls_x509_crt_set_proxy_dn} +@deftypefun {int} {gnutls_x509_crt_set_proxy_dn} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{eecrt}, unsigned int @var{raw_flag}, const void * @var{name}, unsigned int @var{sizeof_name}) +@var{crt}: a gnutls_x509_crt_t type with the new proxy cert + +@var{eecrt}: the end entity certificate that will be issuing the proxy + +@var{raw_flag}: must be 0, or 1 if the CN is DER encoded + +@var{name}: a pointer to the CN name, may be NULL (but MUST then be added later) + +@var{sizeof_name}: holds the size of @code{name} + +This function will set the subject in @code{crt} to the end entity's + @code{eecrt} subject name, and add a single Common Name component @code{name} of size @code{sizeof_name} . This corresponds to the required proxy +certificate naming style. Note that if @code{name} is @code{NULL} , you MUST +set it later by using @code{gnutls_x509_crt_set_dn_by_oid()} or similar. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_serial +@anchor{gnutls_x509_crt_set_serial} +@deftypefun {int} {gnutls_x509_crt_set_serial} (gnutls_x509_crt_t @var{cert}, const void * @var{serial}, size_t @var{serial_size}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{serial}: The serial number + +@var{serial_size}: Holds the size of the serial field. + +This function will set the X.509 certificate's serial number. +While the serial number is an integer, it is often handled +as an opaque field by several CAs. For this reason this function +accepts any kind of data as a serial number. To be consistent +with the X.509/PKIX specifications the provided @code{serial} should be +a big-endian positive number (i.e. its leftmost bit should be zero). + +The size of the serial is restricted to 20 bytes maximum by RFC5280. +This function allows writing more than 20 bytes but the generated +certificates in that case may be rejected by other implementations. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_spki +@anchor{gnutls_x509_crt_set_spki} +@deftypefun {int} {gnutls_x509_crt_set_spki} (gnutls_x509_crt_t @var{crt}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} + +@var{flags}: must be zero + +This function will set the certificate's subject public key +information explicitly. This is intended to be used in the cases +where a single public key (e.g., RSA) can be used for multiple +signature algorithms (RSA PKCS1-1.5, and RSA-PSS). + +To export the public key (i.e., the SubjectPublicKeyInfo part), check +@code{gnutls_pubkey_import_x509()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_subject_alt_name +@anchor{gnutls_x509_crt_set_subject_alt_name} +@deftypefun {int} {gnutls_x509_crt_set_subject_alt_name} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations + +@var{data}: The data to be set + +@var{data_size}: The size of data to be set + +@var{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: @code{GNUTLS_SAN_DNSNAME} as a text string, +@code{GNUTLS_SAN_RFC822NAME} as a text string, @code{GNUTLS_SAN_URI} as a text string, +@code{GNUTLS_SAN_IPADDRESS} as a binary IP address (4 or 16 bytes), +@code{GNUTLS_SAN_OTHERNAME_XMPP} as a UTF8 string (since 3.5.0). + +Since version 3.5.7 the @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DNSNAME} , and +@code{GNUTLS_SAN_OTHERNAME_XMPP} are converted to ACE format when necessary. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_subject_alt_othername +@anchor{gnutls_x509_crt_set_subject_alt_othername} +@deftypefun {int} {gnutls_x509_crt_set_subject_alt_othername} (gnutls_x509_crt_t @var{crt}, const char * @var{oid}, const void * @var{data}, unsigned int @var{data_size}, unsigned int @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{oid}: The other name OID + +@var{data}: The data to be set + +@var{data_size}: The size of data to be set + +@var{flags}: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append. + +This function will set an "othername" to the subject alternative name certificate +extension. + +The values set are set as binary values and are expected to have the proper DER encoding. +For convenience the flags @code{GNUTLS_FSAN_ENCODE_OCTET_STRING} and @code{GNUTLS_FSAN_ENCODE_UTF8_STRING} +can be used to encode the provided data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_crt_set_subject_alternative_name +@anchor{gnutls_x509_crt_set_subject_alternative_name} +@deftypefun {int} {gnutls_x509_crt_set_subject_alternative_name} (gnutls_x509_crt_t @var{crt}, gnutls_x509_subject_alt_name_t @var{type}, const char * @var{data_string}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{type}: is one of the gnutls_x509_subject_alt_name_t enumerations + +@var{data_string}: The data to be set, a (0) 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 inconsistent with +@code{gnutls_x509_crt_get_subject_alt_name()} . + +See @code{gnutls_x509_crt_set_subject_alt_name()} for more information. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_subject_key_id +@anchor{gnutls_x509_crt_set_subject_key_id} +@deftypefun {int} {gnutls_x509_crt_set_subject_key_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{id}: The key ID + +@var{id_size}: Holds the size of the subject key ID field. + +This function will set the X.509 certificate's subject key ID +extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_set_subject_unique_id +@anchor{gnutls_x509_crt_set_subject_unique_id} +@deftypefun {int} {gnutls_x509_crt_set_subject_unique_id} (gnutls_x509_crt_t @var{cert}, const void * @var{id}, size_t @var{id_size}) +@var{cert}: a certificate of type @code{gnutls_x509_crt_t} + +@var{id}: The unique ID + +@var{id_size}: Holds the size of the unique ID. + +This function will set the X.509 certificate's subject unique ID field. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.7 +@end deftypefun + +@subheading gnutls_x509_crt_set_tlsfeatures +@anchor{gnutls_x509_crt_set_tlsfeatures} +@deftypefun {int} {gnutls_x509_crt_set_tlsfeatures} (gnutls_x509_crt_t @var{crt}, gnutls_x509_tlsfeatures_t @var{features}) +@var{crt}: A X.509 certificate + +@var{features}: If the function succeeds, the +features will be added to the certificate. + +This function will set the certificates +X.509 TLS extension from the given structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_crt_set_version +@anchor{gnutls_x509_crt_set_version} +@deftypefun {int} {gnutls_x509_crt_set_version} (gnutls_x509_crt_t @var{crt}, unsigned int @var{version}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{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 @code{gnutls_x509_crt_set_subject_alt_name()} +or @code{gnutls_x509_crt_set_key_usage()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_sign +@anchor{gnutls_x509_crt_sign} +@deftypefun {int} {gnutls_x509_crt_sign} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{issuer}: is the certificate of the certificate issuer + +@var{issuer_key}: holds the issuer's private key + +This function is the same a @code{gnutls_x509_crt_sign2()} with no flags, +and an appropriate hash algorithm. The hash algorithm used may +vary between versions of GnuTLS, and it is tied to the security +level of the issuer's public key. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_sign2 +@anchor{gnutls_x509_crt_sign2} +@deftypefun {int} {gnutls_x509_crt_sign2} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags}) +@var{crt}: a certificate of type @code{gnutls_x509_crt_t} + +@var{issuer}: is the certificate of the certificate issuer + +@var{issuer_key}: holds the issuer's private key + +@var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA256} is a safe choice + +@var{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. + +A known limitation of this function is, that a newly-signed certificate will not +be fully functional (e.g., for signature verification), until it +is exported an re-imported. + +After GnuTLS 3.6.1 the value of @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} , +and in that case, a suitable but reasonable for the key algorithm will be selected. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_verify +@anchor{gnutls_x509_crt_verify} +@deftypefun {int} {gnutls_x509_crt_verify} (gnutls_x509_crt_t @var{cert}, const gnutls_x509_crt_t * @var{CA_list}, unsigned @var{CA_list_length}, unsigned int @var{flags}, unsigned int * @var{verify}) +@var{cert}: is the certificate to be verified + +@var{CA_list}: is one certificate that is considered to be trusted one + +@var{CA_list_length}: holds the number of CA certificate in CA_list + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +@var{verify}: will hold the certificate verification output. + +This function will try to verify the given certificate and return +its status. Note that a verification error does not imply a negative +return status. In that case the @code{verify} status is set. + +The details of the verification are the same +as in @code{gnutls_x509_trust_list_verify_crt2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_crt_verify_data2 +@anchor{gnutls_x509_crt_verify_data2} +@deftypefun {int} {gnutls_x509_crt_verify_data2} (gnutls_x509_crt_t @var{crt}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature}) +@var{crt}: Holds the certificate to verify with + +@var{algo}: The signature algorithm used + +@var{flags}: Zero or an OR list of @code{gnutls_certificate_verify_flags} + +@var{data}: holds the signed data + +@var{signature}: contains the signature + +This function will verify the given signed data, using the +parameters from the certificate. + +@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED} +is returned, @code{GNUTLS_E_EXPIRED} or @code{GNUTLS_E_NOT_YET_ACTIVATED} on expired +or not yet activated certificate and zero or positive code on success. + +Note that since GnuTLS 3.5.6 this function introduces checks in the +end certificate ( @code{crt} ), including time checks and key usage checks. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_ct_sct_get +@anchor{gnutls_x509_ct_sct_get} +@deftypefun {int} {gnutls_x509_ct_sct_get} (const gnutls_x509_ct_scts_t @var{scts}, unsigned @var{idx}, time_t * @var{timestamp}, gnutls_datum_t * @var{logid}, gnutls_sign_algorithm_t * @var{sigalg}, gnutls_datum_t * @var{signature}) +@var{scts}: A list of SCTs + +@var{idx}: The index of the target SCT in the list + +@var{timestamp}: The timestamp of the SCT + +@var{logid}: The LogID field of the SCT; must be freed with @code{gnutls_free()} + +@var{sigalg}: The signature algorithm + +@var{signature}: The signature of the SCT; must be freed with @code{gnutls_free()} + +This function will return a specific SCT (Signed Certificate Timestamp) +stored in the SCT list @code{scts} . + +The datums holding the SCT's LogId and signature will be allocated +using @code{gnutls_malloc()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) will be returned on success, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if @code{idx} exceeds the number of SCTs in the list +or a negative error value. +@end deftypefun + +@subheading gnutls_x509_ct_sct_get_version +@anchor{gnutls_x509_ct_sct_get_version} +@deftypefun {int} {gnutls_x509_ct_sct_get_version} (gnutls_x509_ct_scts_t @var{scts}, unsigned @var{idx}, unsigned int * @var{version_out}) +@var{scts}: A list of SCTs + +@var{idx}: The index of the target SCT in the list + +@var{version_out}: The version of the target SCT. + +This function obtains the version of the SCT at the given position +in the SCT list. + +The version of that SCT will be placed on @code{version_out} . + +Return : @code{GNUTLS_E_SUCCESS} (0) is returned on success, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if @code{idx} exceeds the number of SCTs in the list +and @code{GNUTLS_E_INVALID_REQUEST} if the SCT's version is different than 1, as that's currently +the only defined version. +@end deftypefun + +@subheading gnutls_x509_dn_deinit +@anchor{gnutls_x509_dn_deinit} +@deftypefun {void} {gnutls_x509_dn_deinit} (gnutls_x509_dn_t @var{dn}) +@var{dn}: a DN uint8_t object pointer. + +This function deallocates the DN object as returned by +@code{gnutls_x509_dn_import()} . + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_x509_dn_export +@anchor{gnutls_x509_dn_export} +@deftypefun {int} {gnutls_x509_dn_export} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{dn}: Holds the uint8_t DN object + +@var{format}: the format of output params. One of PEM or DER. + +@var{output_data}: will contain a DN PEM or DER encoded + +@var{output_data_size}: holds the size of output_data (and will be +replaced by the actual size of parameters) + +This function will export the DN to DER or PEM format. + +If the buffer provided is not long enough to hold the output, then +* @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} +will be returned. + +If the structure is PEM encoded, it will have a header +of "BEGIN NAME". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_dn_export2 +@anchor{gnutls_x509_dn_export2} +@deftypefun {int} {gnutls_x509_dn_export2} (gnutls_x509_dn_t @var{dn}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) +@var{dn}: Holds the uint8_t DN object + +@var{format}: the format of output params. One of PEM or DER. + +@var{out}: will contain a DN PEM or DER encoded + +This function will export the DN to DER or PEM format. + +The output buffer is allocated using @code{gnutls_malloc()} . + +If the structure is PEM encoded, it will have a header +of "BEGIN NAME". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_x509_dn_get_rdn_ava +@anchor{gnutls_x509_dn_get_rdn_ava} +@deftypefun {int} {gnutls_x509_dn_get_rdn_ava} (gnutls_x509_dn_t @var{dn}, int @var{irdn}, int @var{iava}, gnutls_x509_ava_st * @var{ava}) +@var{dn}: a pointer to DN + +@var{irdn}: index of RDN + +@var{iava}: index of AVA. + +@var{ava}: Pointer to structure which will hold output information. + +Get pointers to data within the DN. The format of the @code{ava} structure +is shown below. + +struct gnutls_x509_ava_st @{ +gnutls_datum_t oid; +gnutls_datum_t value; +unsigned long value_tag; +@}; + +The X.509 distinguished name is a sequence of sequences of strings +and this is what the @code{irdn} and @code{iava} indexes model. + +Note that @code{ava} will contain pointers into the @code{dn} structure which +in turns points to the original certificate. Thus you should not +modify any data or deallocate any of those. + +This is a low-level function that requires the caller to do the +value conversions when necessary (e.g. from UCS-2). + +@strong{Returns:} Returns 0 on success, or an error code. +@end deftypefun + +@subheading gnutls_x509_dn_get_str +@anchor{gnutls_x509_dn_get_str} +@deftypefun {int} {gnutls_x509_dn_get_str} (gnutls_x509_dn_t @var{dn}, gnutls_datum_t * @var{str}) +@var{dn}: a pointer to DN + +@var{str}: a datum that will hold the name + +This function will allocate buffer and copy the name in the provided DN. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.2 +@end deftypefun + +@subheading gnutls_x509_dn_get_str2 +@anchor{gnutls_x509_dn_get_str2} +@deftypefun {int} {gnutls_x509_dn_get_str2} (gnutls_x509_dn_t @var{dn}, gnutls_datum_t * @var{str}, unsigned @var{flags}) +@var{dn}: a pointer to DN + +@var{str}: a datum that will hold the name + +@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} + +This function will allocate buffer and copy the name in the provided DN. +The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as +described in RFC4514. The output string will be ASCII or UTF-8 +encoded, depending on the certificate data. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.7 +@end deftypefun + +@subheading gnutls_x509_dn_import +@anchor{gnutls_x509_dn_import} +@deftypefun {int} {gnutls_x509_dn_import} (gnutls_x509_dn_t @var{dn}, const gnutls_datum_t * @var{data}) +@var{dn}: the structure that will hold the imported DN + +@var{data}: should contain a DER encoded RDN sequence + +This function parses an RDN sequence and stores the result to a +@code{gnutls_x509_dn_t} type. The data must have been initialized +with @code{gnutls_x509_dn_init()} . You may use @code{gnutls_x509_dn_get_rdn_ava()} to +decode the DN. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_x509_dn_init +@anchor{gnutls_x509_dn_init} +@deftypefun {int} {gnutls_x509_dn_init} (gnutls_x509_dn_t * @var{dn}) +@var{dn}: the object to be initialized + +This function initializes a @code{gnutls_x509_dn_t} type. + +The object returned must be deallocated using +@code{gnutls_x509_dn_deinit()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_x509_dn_oid_known +@anchor{gnutls_x509_dn_oid_known} +@deftypefun {int} {gnutls_x509_dn_oid_known} (const char * @var{oid}) +@var{oid}: holds an Object Identifier in a null terminated string + +This function will inform about known DN OIDs. This is useful since +functions like @code{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. + +@strong{Returns:} 1 on known OIDs and 0 otherwise. +@end deftypefun + +@subheading gnutls_x509_dn_oid_name +@anchor{gnutls_x509_dn_oid_name} +@deftypefun {const char *} {gnutls_x509_dn_oid_name} (const char * @var{oid}, unsigned int @var{flags}) +@var{oid}: holds an Object Identifier in a null terminated string + +@var{flags}: 0 or GNUTLS_X509_DN_OID_* + +This function will return the name of a known DN OID. If +@code{GNUTLS_X509_DN_OID_RETURN_OID} is specified this function +will return the given OID if no descriptive name has been +found. + +@strong{Returns:} A null terminated string or NULL otherwise. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_dn_set_str +@anchor{gnutls_x509_dn_set_str} +@deftypefun {int} {gnutls_x509_dn_set_str} (gnutls_x509_dn_t @var{dn}, const char * @var{str}, const char ** @var{err}) +@var{dn}: a pointer to DN + +@var{str}: a comma separated DN string (RFC4514) + +@var{err}: indicates the error position (if any) + +This function will set the DN on the provided DN structure. +The input string should be plain ASCII or UTF-8 encoded. On +DN parsing error @code{GNUTLS_E_PARSING_ERROR} is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.3 +@end deftypefun + +@subheading gnutls_x509_ext_ct_export_scts +@anchor{gnutls_x509_ext_ct_export_scts} +@deftypefun {int} {gnutls_x509_ext_ct_export_scts} (const gnutls_x509_ct_scts_t @var{scts}, gnutls_datum_t * @var{ext}) +@var{scts}: An initialized SCT list + +@var{ext}: The DER-encoded extension data; must be freed with @code{gnutls_free()} + +This function will convert the provided list of SCTs to a DER-encoded +SignedCertificateTimestampList extension (1.3.6.1.4.1.11129.2.4.2). +The output data in @code{ext} will be allocated using @code{gnutls_malloc()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error value. +@end deftypefun + +@subheading gnutls_x509_ext_ct_import_scts +@anchor{gnutls_x509_ext_ct_import_scts} +@deftypefun {int} {gnutls_x509_ext_ct_import_scts} (const gnutls_datum_t * @var{ext}, gnutls_x509_ct_scts_t @var{scts}, unsigned int @var{flags}) +@var{ext}: a DER-encoded extension + +@var{scts}: The SCT list + +@var{flags}: should be zero + +This function will read a SignedCertificateTimestampList structure +from the DER data of the X.509 Certificate Transparency SCT extension +(OID 1.3.6.1.4.1.11129.2.4.2). + +The list of SCTs (Signed Certificate Timestamps) is placed on @code{scts} , +which must be previously initialized with @code{gnutls_x509_ext_ct_scts_init()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error value. +@end deftypefun + +@subheading gnutls_x509_ext_ct_scts_deinit +@anchor{gnutls_x509_ext_ct_scts_deinit} +@deftypefun {void} {gnutls_x509_ext_ct_scts_deinit} (gnutls_x509_ct_scts_t @var{scts}) +@var{scts}: The SCT list + +This function will deinitialize a Certificate Transparency SCT list. +@end deftypefun + +@subheading gnutls_x509_ext_ct_scts_init +@anchor{gnutls_x509_ext_ct_scts_init} +@deftypefun {int} {gnutls_x509_ext_ct_scts_init} (gnutls_x509_ct_scts_t * @var{scts}) +@var{scts}: The SCT list + +This function will initialize a Certificate Transparency SCT list. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, otherwise a negative error value. +@end deftypefun + +@subheading gnutls_x509_ext_deinit +@anchor{gnutls_x509_ext_deinit} +@deftypefun {void} {gnutls_x509_ext_deinit} (gnutls_x509_ext_st * @var{ext}) +@var{ext}: The extensions structure + +This function will deinitialize an extensions structure. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_x509_ext_export_aia +@anchor{gnutls_x509_ext_export_aia} +@deftypefun {int} {gnutls_x509_ext_export_aia} (gnutls_x509_aia_t @var{aia}, gnutls_datum_t * @var{ext}) +@var{aia}: The authority info access + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will DER encode the Authority Information Access (AIA) +extension; see RFC 5280 section 4.2.2.1 for more information on the +extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_authority_key_id +@anchor{gnutls_x509_ext_export_authority_key_id} +@deftypefun {int} {gnutls_x509_ext_export_authority_key_id} (gnutls_x509_aki_t @var{aki}, gnutls_datum_t * @var{ext}) +@var{aki}: An initialized authority key identifier + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided key identifier to a +DER-encoded PKIX AuthorityKeyIdentifier extension. +The output data in @code{ext} will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_basic_constraints +@anchor{gnutls_x509_ext_export_basic_constraints} +@deftypefun {int} {gnutls_x509_ext_export_basic_constraints} (unsigned int @var{ca}, int @var{pathlen}, gnutls_datum_t * @var{ext}) +@var{ca}: non-zero for a CA + +@var{pathlen}: The path length constraint (set to -1 for no constraint) + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the parameters provided to a basic constraints +DER encoded extension (2.5.29.19). +The @code{ext} data will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_crl_dist_points +@anchor{gnutls_x509_ext_export_crl_dist_points} +@deftypefun {int} {gnutls_x509_ext_export_crl_dist_points} (gnutls_x509_crl_dist_points_t @var{cdp}, gnutls_datum_t * @var{ext}) +@var{cdp}: A pointer to an initialized CRL distribution points. + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided policies, to a certificate policy +DER encoded extension (2.5.29.31). + +The @code{ext} data will be allocated using @code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_inhibit_anypolicy +@anchor{gnutls_x509_ext_export_inhibit_anypolicy} +@deftypefun {int} {gnutls_x509_ext_export_inhibit_anypolicy} (unsigned int @var{skipcerts}, gnutls_datum_t * @var{ext}) +@var{skipcerts}: number of certificates after which anypolicy is no longer acceptable. + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the @code{skipcerts} value to a DER +encoded Inhibit AnyPolicy PKIX extension. The @code{ext} data will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_key_purposes +@anchor{gnutls_x509_ext_export_key_purposes} +@deftypefun {int} {gnutls_x509_ext_export_key_purposes} (gnutls_x509_key_purposes_t @var{p}, gnutls_datum_t * @var{ext}) +@var{p}: The key purposes + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the key purposes type to a +DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension. The output data in + @code{ext} will be allocated using @code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_key_usage +@anchor{gnutls_x509_ext_export_key_usage} +@deftypefun {int} {gnutls_x509_ext_export_key_usage} (unsigned int @var{usage}, gnutls_datum_t * @var{ext}) +@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements. + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the keyUsage bit string to a DER +encoded PKIX extension. The @code{ext} data will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_name_constraints +@anchor{gnutls_x509_ext_export_name_constraints} +@deftypefun {int} {gnutls_x509_ext_export_name_constraints} (gnutls_x509_name_constraints_t @var{nc}, gnutls_datum_t * @var{ext}) +@var{nc}: The nameconstraints + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided name constraints type to a +DER-encoded PKIX NameConstraints (2.5.29.30) extension. The output data in + @code{ext} will be allocated using @code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_policies +@anchor{gnutls_x509_ext_export_policies} +@deftypefun {int} {gnutls_x509_ext_export_policies} (gnutls_x509_policies_t @var{policies}, gnutls_datum_t * @var{ext}) +@var{policies}: A pointer to an initialized policies. + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided policies, to a certificate policy +DER encoded extension (2.5.29.32). + +The @code{ext} data will be allocated using @code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_private_key_usage_period +@anchor{gnutls_x509_ext_export_private_key_usage_period} +@deftypefun {int} {gnutls_x509_ext_export_private_key_usage_period} (time_t @var{activation}, time_t @var{expiration}, gnutls_datum_t * @var{ext}) +@var{activation}: The activation time + +@var{expiration}: The expiration time + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the periods provided to a private key +usage DER encoded extension (2.5.29.16). +The @code{ext} data will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_proxy +@anchor{gnutls_x509_ext_export_proxy} +@deftypefun {int} {gnutls_x509_ext_export_proxy} (int @var{pathLenConstraint}, const char * @var{policyLanguage}, const char * @var{policy}, size_t @var{sizeof_policy}, gnutls_datum_t * @var{ext}) +@var{pathLenConstraint}: A negative value will remove the path length constraint, +while non-negative values will be set as the length of the pathLenConstraints field. + +@var{policyLanguage}: OID describing the language of @code{policy} . + +@var{policy}: uint8_t byte array with policy language, can be @code{NULL} + +@var{sizeof_policy}: size of @code{policy} . + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the parameters provided to a proxyCertInfo extension. + +The @code{ext} data will be allocated using @code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_subject_alt_names +@anchor{gnutls_x509_ext_export_subject_alt_names} +@deftypefun {int} {gnutls_x509_ext_export_subject_alt_names} (gnutls_subject_alt_names_t @var{sans}, gnutls_datum_t * @var{ext}) +@var{sans}: The alternative names + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided alternative names structure to a +DER-encoded SubjectAltName PKIX extension. The output data in @code{ext} will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_subject_key_id +@anchor{gnutls_x509_ext_export_subject_key_id} +@deftypefun {int} {gnutls_x509_ext_export_subject_key_id} (const gnutls_datum_t * @var{id}, gnutls_datum_t * @var{ext}) +@var{id}: The key identifier + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided key identifier to a +DER-encoded PKIX SubjectKeyIdentifier extension. +The output data in @code{ext} will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_export_tlsfeatures +@anchor{gnutls_x509_ext_export_tlsfeatures} +@deftypefun {int} {gnutls_x509_ext_export_tlsfeatures} (gnutls_x509_tlsfeatures_t @var{f}, gnutls_datum_t * @var{ext}) +@var{f}: The features structure + +@var{ext}: The DER-encoded extension data; must be freed using @code{gnutls_free()} . + +This function will convert the provided TLS features structure structure to a +DER-encoded TLS features PKIX extension. The output data in @code{ext} will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_ext_import_aia +@anchor{gnutls_x509_ext_import_aia} +@deftypefun {int} {gnutls_x509_ext_import_aia} (const gnutls_datum_t * @var{ext}, gnutls_x509_aia_t @var{aia}, unsigned int @var{flags}) +@var{ext}: The DER-encoded extension data + +@var{aia}: The authority info access + +@var{flags}: should be zero + +This function extracts the Authority Information Access (AIA) +extension from the provided DER-encoded data; see RFC 5280 section 4.2.2.1 +for more information on the extension. The +AIA extension holds a sequence of AccessDescription (AD) data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_authority_key_id +@anchor{gnutls_x509_ext_import_authority_key_id} +@deftypefun {int} {gnutls_x509_ext_import_authority_key_id} (const gnutls_datum_t * @var{ext}, gnutls_x509_aki_t @var{aki}, unsigned int @var{flags}) +@var{ext}: a DER encoded extension + +@var{aki}: An initialized authority key identifier type + +@var{flags}: should be zero + +This function will return the subject key ID stored in the provided +AuthorityKeyIdentifier extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_basic_constraints +@anchor{gnutls_x509_ext_import_basic_constraints} +@deftypefun {int} {gnutls_x509_ext_import_basic_constraints} (const gnutls_datum_t * @var{ext}, unsigned int * @var{ca}, int * @var{pathlen}) +@var{ext}: the DER encoded extension data + +@var{ca}: will be non zero if the CA status is true + +@var{pathlen}: the path length constraint; will be set to -1 for no limit + +This function will return the CA status and path length constraint +as written in the PKIX extension 2.5.29.19. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_crl_dist_points +@anchor{gnutls_x509_ext_import_crl_dist_points} +@deftypefun {int} {gnutls_x509_ext_import_crl_dist_points} (const gnutls_datum_t * @var{ext}, gnutls_x509_crl_dist_points_t @var{cdp}, unsigned int @var{flags}) +@var{ext}: the DER encoded extension data + +@var{cdp}: A pointer to an initialized CRL distribution points. + +@var{flags}: should be zero + +This function will extract the CRL distribution points extension (2.5.29.31) +and store it into the provided type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_inhibit_anypolicy +@anchor{gnutls_x509_ext_import_inhibit_anypolicy} +@deftypefun {int} {gnutls_x509_ext_import_inhibit_anypolicy} (const gnutls_datum_t * @var{ext}, unsigned int * @var{skipcerts}) +@var{ext}: the DER encoded extension data + +@var{skipcerts}: will hold the number of certificates after which anypolicy is no longer acceptable. + +This function will return certificate's value of SkipCerts, +by reading the DER data of the Inhibit anyPolicy X.509 extension (2.5.29.54). + +The @code{skipcerts} value is the number of additional certificates that +may appear in the path before the anyPolicy (@code{GNUTLS_X509_OID_POLICY_ANY} ) +is no longer acceptable. + +@strong{Returns:} zero, or a negative error code in case of +parsing error. If the certificate does not contain the Inhibit anyPolicy +extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_key_purposes +@anchor{gnutls_x509_ext_import_key_purposes} +@deftypefun {int} {gnutls_x509_ext_import_key_purposes} (const gnutls_datum_t * @var{ext}, gnutls_x509_key_purposes_t @var{p}, unsigned int @var{flags}) +@var{ext}: The DER-encoded extension data + +@var{p}: The key purposes + +@var{flags}: should be zero + +This function will extract the key purposes in the provided DER-encoded +ExtKeyUsageSyntax PKIX extension, to a @code{gnutls_x509_key_purposes_t} type. +The data must be initialized. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_key_usage +@anchor{gnutls_x509_ext_import_key_usage} +@deftypefun {int} {gnutls_x509_ext_import_key_usage} (const gnutls_datum_t * @var{ext}, unsigned int * @var{key_usage}) +@var{ext}: the DER encoded extension data + +@var{key_usage}: where the key usage bits will be stored + +This function will return certificate's key usage, by reading the DER +data of the keyUsage X.509 extension (2.5.29.15). The key usage value will ORed +values of the: @code{GNUTLS_KEY_DIGITAL_SIGNATURE} , +@code{GNUTLS_KEY_NON_REPUDIATION} , @code{GNUTLS_KEY_KEY_ENCIPHERMENT} , +@code{GNUTLS_KEY_DATA_ENCIPHERMENT} , @code{GNUTLS_KEY_KEY_AGREEMENT} , +@code{GNUTLS_KEY_KEY_CERT_SIGN} , @code{GNUTLS_KEY_CRL_SIGN} , +@code{GNUTLS_KEY_ENCIPHER_ONLY} , @code{GNUTLS_KEY_DECIPHER_ONLY} . + +@strong{Returns:} the certificate key usage, or a negative error code in case of +parsing error. If the certificate does not contain the keyUsage +extension @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_name_constraints +@anchor{gnutls_x509_ext_import_name_constraints} +@deftypefun {int} {gnutls_x509_ext_import_name_constraints} (const gnutls_datum_t * @var{ext}, gnutls_x509_name_constraints_t @var{nc}, unsigned int @var{flags}) +@var{ext}: a DER encoded extension + +@var{nc}: The nameconstraints + +@var{flags}: zero or @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} + +This function will return an intermediate type containing +the name constraints of the provided NameConstraints extension. That +can be used in combination with @code{gnutls_x509_name_constraints_check()} +to verify whether a server's name is in accordance with the constraints. + +When the @code{flags} is set to @code{GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND} , then if +the @code{nc} type is empty this function will behave identically as if the flag was not set. +Otherwise if there are elements in the @code{nc} structure then the +constraints will be merged with the existing constraints following +RFC5280 p6.1.4 (excluded constraints will be appended, permitted +will be intersected). + +Note that @code{nc} must be initialized prior to calling this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_policies +@anchor{gnutls_x509_ext_import_policies} +@deftypefun {int} {gnutls_x509_ext_import_policies} (const gnutls_datum_t * @var{ext}, gnutls_x509_policies_t @var{policies}, unsigned int @var{flags}) +@var{ext}: the DER encoded extension data + +@var{policies}: A pointer to an initialized policies. + +@var{flags}: should be zero + +This function will extract the certificate policy extension (2.5.29.32) +and store it the provided policies. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_private_key_usage_period +@anchor{gnutls_x509_ext_import_private_key_usage_period} +@deftypefun {int} {gnutls_x509_ext_import_private_key_usage_period} (const gnutls_datum_t * @var{ext}, time_t * @var{activation}, time_t * @var{expiration}) +@var{ext}: the DER encoded extension data + +@var{activation}: Will hold the activation time + +@var{expiration}: Will hold the expiration time + +This function will return the expiration and activation +times of the private key as written in the +PKIX extension 2.5.29.16. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_proxy +@anchor{gnutls_x509_ext_import_proxy} +@deftypefun {int} {gnutls_x509_ext_import_proxy} (const gnutls_datum_t * @var{ext}, int * @var{pathlen}, char ** @var{policyLanguage}, char ** @var{policy}, size_t * @var{sizeof_policy}) +@var{ext}: the DER encoded extension data + +@var{pathlen}: pointer to output integer indicating path length (may be +NULL), non-negative error codes indicate a present pCPathLenConstraint +field and the actual value, -1 indicate that the field is absent. + +@var{policyLanguage}: output variable with OID of policy language + +@var{policy}: output variable with policy data + +@var{sizeof_policy}: output variable with size of policy data + +This function will return the information from a proxy certificate +extension. It reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14). +The @code{policyLanguage} and @code{policy} values must be deinitialized using @code{gnutls_free()} after use. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_subject_alt_names +@anchor{gnutls_x509_ext_import_subject_alt_names} +@deftypefun {int} {gnutls_x509_ext_import_subject_alt_names} (const gnutls_datum_t * @var{ext}, gnutls_subject_alt_names_t @var{sans}, unsigned int @var{flags}) +@var{ext}: The DER-encoded extension data + +@var{sans}: The alternative names + +@var{flags}: should be zero + +This function will export the alternative names in the provided DER-encoded +SubjectAltName PKIX extension, to a @code{gnutls_subject_alt_names_t} type. @code{sans} must be initialized. + +This function will succeed even if there no subject alternative names +in the structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_subject_key_id +@anchor{gnutls_x509_ext_import_subject_key_id} +@deftypefun {int} {gnutls_x509_ext_import_subject_key_id} (const gnutls_datum_t * @var{ext}, gnutls_datum_t * @var{id}) +@var{ext}: a DER encoded extension + +@var{id}: will contain the subject key ID + +This function will return the subject key ID stored in the provided +SubjectKeyIdentifier extension. The ID will be allocated using +@code{gnutls_malloc()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_ext_import_tlsfeatures +@anchor{gnutls_x509_ext_import_tlsfeatures} +@deftypefun {int} {gnutls_x509_ext_import_tlsfeatures} (const gnutls_datum_t * @var{ext}, gnutls_x509_tlsfeatures_t @var{f}, unsigned int @var{flags}) +@var{ext}: The DER-encoded extension data + +@var{f}: The features structure + +@var{flags}: zero or @code{GNUTLS_EXT_FLAG_APPEND} + +This function will export the features in the provided DER-encoded +TLS Features PKIX extension, to a @code{gnutls_x509_tlsfeatures_t} type. @code{f} must be initialized. + +When the @code{flags} is set to @code{GNUTLS_EXT_FLAG_APPEND} , +then if the @code{features} structure is empty this function will behave +identically as if the flag was not set. Otherwise if there are elements +in the @code{features} structure then they will be merged with. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_ext_print +@anchor{gnutls_x509_ext_print} +@deftypefun {int} {gnutls_x509_ext_print} (gnutls_x509_ext_st * @var{exts}, unsigned int @var{exts_size}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out}) +@var{exts}: The data to be printed + +@var{exts_size}: the number of available structures + +@var{format}: Indicate the format to use + +@var{out}: Newly allocated datum with null terminated string. + +This function will pretty print X.509 certificate extensions, +suitable for display to a human. + +The output @code{out} needs to be deallocated using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_key_purpose_deinit +@anchor{gnutls_x509_key_purpose_deinit} +@deftypefun {void} {gnutls_x509_key_purpose_deinit} (gnutls_x509_key_purposes_t @var{p}) +@var{p}: The key purposes + +This function will deinitialize a key purposes type. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_key_purpose_get +@anchor{gnutls_x509_key_purpose_get} +@deftypefun {int} {gnutls_x509_key_purpose_get} (gnutls_x509_key_purposes_t @var{p}, unsigned @var{idx}, gnutls_datum_t * @var{oid}) +@var{p}: The key purposes + +@var{idx}: The index of the key purpose to retrieve + +@var{oid}: Will hold the object identifier of the key purpose (to be treated as constant) + +This function will retrieve the specified by the index key purpose in the +purposes type. The object identifier will be a null terminated string. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the index is out of bounds, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_key_purpose_init +@anchor{gnutls_x509_key_purpose_init} +@deftypefun {int} {gnutls_x509_key_purpose_init} (gnutls_x509_key_purposes_t * @var{p}) +@var{p}: The key purposes + +This function will initialize an alternative names type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_key_purpose_set +@anchor{gnutls_x509_key_purpose_set} +@deftypefun {int} {gnutls_x509_key_purpose_set} (gnutls_x509_key_purposes_t @var{p}, const char * @var{oid}) +@var{p}: The key purposes + +@var{oid}: The object identifier of the key purpose + +This function will store the specified key purpose in the +purposes. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_add_excluded +@anchor{gnutls_x509_name_constraints_add_excluded} +@deftypefun {int} {gnutls_x509_name_constraints_add_excluded} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{name}) +@var{nc}: The nameconstraints + +@var{type}: The type of the constraints + +@var{name}: The data of the constraints + +This function will add a name constraint to the list of excluded +constraints. The constraints @code{type} can be any of the following types: +@code{GNUTLS_SAN_DNSNAME} , @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DN} , +@code{GNUTLS_SAN_URI} , @code{GNUTLS_SAN_IPADDRESS} . For the latter, an IP address +in network byte order is expected, followed by its network mask (which is +4 bytes in IPv4 or 16-bytes in IPv6). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_add_permitted +@anchor{gnutls_x509_name_constraints_add_permitted} +@deftypefun {int} {gnutls_x509_name_constraints_add_permitted} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{name}) +@var{nc}: The nameconstraints + +@var{type}: The type of the constraints + +@var{name}: The data of the constraints + +This function will add a name constraint to the list of permitted +constraints. The constraints @code{type} can be any of the following types: +@code{GNUTLS_SAN_DNSNAME} , @code{GNUTLS_SAN_RFC822NAME} , @code{GNUTLS_SAN_DN} , +@code{GNUTLS_SAN_URI} , @code{GNUTLS_SAN_IPADDRESS} . For the latter, an IP address +in network byte order is expected, followed by its network mask. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_check +@anchor{gnutls_x509_name_constraints_check} +@deftypefun {unsigned} {gnutls_x509_name_constraints_check} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, const gnutls_datum_t * @var{name}) +@var{nc}: the extracted name constraints + +@var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t) + +@var{name}: the name to be checked + +This function will check the provided name against the constraints in + @code{nc} using the RFC5280 rules. Currently this function is limited to DNS +names, emails and IP addresses (of type @code{GNUTLS_SAN_DNSNAME} , +@code{GNUTLS_SAN_RFC822NAME} and @code{GNUTLS_SAN_IPADDRESS} ). + +@strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_check_crt +@anchor{gnutls_x509_name_constraints_check_crt} +@deftypefun {unsigned} {gnutls_x509_name_constraints_check_crt} (gnutls_x509_name_constraints_t @var{nc}, gnutls_x509_subject_alt_name_t @var{type}, gnutls_x509_crt_t @var{cert}) +@var{nc}: the extracted name constraints + +@var{type}: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t) + +@var{cert}: the certificate to be checked + +This function will check the provided certificate names against the constraints in + @code{nc} using the RFC5280 rules. It will traverse all the certificate's names and +alternative names. + +Currently this function is limited to DNS +names and emails (of type @code{GNUTLS_SAN_DNSNAME} and @code{GNUTLS_SAN_RFC822NAME} ). + +@strong{Returns:} zero if the provided name is not acceptable, and non-zero otherwise. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_deinit +@anchor{gnutls_x509_name_constraints_deinit} +@deftypefun {void} {gnutls_x509_name_constraints_deinit} (gnutls_x509_name_constraints_t @var{nc}) +@var{nc}: The nameconstraints + +This function will deinitialize a name constraints type. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_get_excluded +@anchor{gnutls_x509_name_constraints_get_excluded} +@deftypefun {int} {gnutls_x509_name_constraints_get_excluded} (gnutls_x509_name_constraints_t @var{nc}, unsigned @var{idx}, unsigned * @var{type}, gnutls_datum_t * @var{name}) +@var{nc}: the extracted name constraints + +@var{idx}: the index of the constraint + +@var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t) + +@var{name}: the name in the constraint (of the specific type) + +This function will return an intermediate type containing +the name constraints of the provided CA certificate. That +structure can be used in combination with @code{gnutls_x509_name_constraints_check()} +to verify whether a server's name is in accordance with the constraints. + +The name should be treated as constant and valid for the lifetime of @code{nc} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_get_permitted +@anchor{gnutls_x509_name_constraints_get_permitted} +@deftypefun {int} {gnutls_x509_name_constraints_get_permitted} (gnutls_x509_name_constraints_t @var{nc}, unsigned @var{idx}, unsigned * @var{type}, gnutls_datum_t * @var{name}) +@var{nc}: the extracted name constraints + +@var{idx}: the index of the constraint + +@var{type}: the type of the constraint (of type gnutls_x509_subject_alt_name_t) + +@var{name}: the name in the constraint (of the specific type) + +This function will return an intermediate type containing +the name constraints of the provided CA certificate. That +structure can be used in combination with @code{gnutls_x509_name_constraints_check()} +to verify whether a server's name is in accordance with the constraints. + +The name should be treated as constant and valid for the lifetime of @code{nc} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the extension is not present, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_name_constraints_init +@anchor{gnutls_x509_name_constraints_init} +@deftypefun {int} {gnutls_x509_name_constraints_init} (gnutls_x509_name_constraints_t * @var{nc}) +@var{nc}: The nameconstraints + +This function will initialize a name constraints type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_othername_to_virtual +@anchor{gnutls_x509_othername_to_virtual} +@deftypefun {int} {gnutls_x509_othername_to_virtual} (const char * @var{oid}, const gnutls_datum_t * @var{othername}, unsigned int * @var{virt_type}, gnutls_datum_t * @var{virt}) +@var{oid}: The othername object identifier + +@var{othername}: The othername data + +@var{virt_type}: GNUTLS_SAN_OTHERNAME_XXX + +@var{virt}: allocated printable data + +This function will parse and convert the othername data to a virtual +type supported by gnutls. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_x509_policies_deinit +@anchor{gnutls_x509_policies_deinit} +@deftypefun {void} {gnutls_x509_policies_deinit} (gnutls_x509_policies_t @var{policies}) +@var{policies}: The authority key identifier + +This function will deinitialize an authority key identifier type. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_policies_get +@anchor{gnutls_x509_policies_get} +@deftypefun {int} {gnutls_x509_policies_get} (gnutls_x509_policies_t @var{policies}, unsigned int @var{seq}, struct gnutls_x509_policy_st * @var{policy}) +@var{policies}: The policies + +@var{seq}: The index of the name to get + +@var{policy}: Will hold the policy + +This function will return a specific policy as stored in +the @code{policies} type. The returned values should be treated as constant +and valid for the lifetime of @code{policies} . + +The any policy OID is available as the @code{GNUTLS_X509_OID_POLICY_ANY} macro. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +if the index is out of bounds, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_policies_init +@anchor{gnutls_x509_policies_init} +@deftypefun {int} {gnutls_x509_policies_init} (gnutls_x509_policies_t * @var{policies}) +@var{policies}: The authority key ID + +This function will initialize an authority key ID type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_policies_set +@anchor{gnutls_x509_policies_set} +@deftypefun {int} {gnutls_x509_policies_set} (gnutls_x509_policies_t @var{policies}, const struct gnutls_x509_policy_st * @var{policy}) +@var{policies}: An initialized policies + +@var{policy}: Contains the policy to set + +This function will store the specified policy in +the provided @code{policies} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0), otherwise a negative error value. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_x509_policy_release +@anchor{gnutls_x509_policy_release} +@deftypefun {void} {gnutls_x509_policy_release} (struct gnutls_x509_policy_st * @var{policy}) +@var{policy}: a certificate policy + +This function will deinitialize all memory associated with the provided + @code{policy} . The policy is allocated using @code{gnutls_x509_crt_get_policy()} . + +@strong{Since:} 3.1.5 +@end deftypefun + +@subheading gnutls_x509_privkey_cpy +@anchor{gnutls_x509_privkey_cpy} +@deftypefun {int} {gnutls_x509_privkey_cpy} (gnutls_x509_privkey_t @var{dst}, gnutls_x509_privkey_t @var{src}) +@var{dst}: The destination key, which should be initialized. + +@var{src}: The source key + +This function will copy a private key from source to destination +key. Destination has to be initialized. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_deinit +@anchor{gnutls_x509_privkey_deinit} +@deftypefun {void} {gnutls_x509_privkey_deinit} (gnutls_x509_privkey_t @var{key}) +@var{key}: The key to be deinitialized + +This function will deinitialize a private key structure. +@end deftypefun + +@subheading gnutls_x509_privkey_export +@anchor{gnutls_x509_privkey_export} +@deftypefun {int} {gnutls_x509_privkey_export} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{key}: Holds the key + +@var{format}: the format of output params. One of PEM or DER. + +@var{output_data}: will contain a private key PEM or DER encoded + +@var{output_data_size}: holds the size of output_data (and will be +replaced by the actual size of parameters) + +This function will export the private key to a PKCS@code{1} structure for +RSA or RSA-PSS keys, and integer sequence for DSA keys. Other keys types +will be exported in PKCS@code{8} form. + +If the structure is PEM encoded, it will have a header +of "BEGIN RSA PRIVATE KEY". + +It is recommended to use @code{gnutls_x509_privkey_export_pkcs8()} instead +of this function, when a consistent output format is required. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_export2 +@anchor{gnutls_x509_privkey_export2} +@deftypefun {int} {gnutls_x509_privkey_export2} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) +@var{key}: Holds the key + +@var{format}: the format of output params. One of PEM or DER. + +@var{out}: will contain a private key PEM or DER encoded + +This function will export the private key to a PKCS@code{1} structure for +RSA or RSA-PSS keys, and integer sequence for DSA keys. Other keys types +will be exported in PKCS@code{8} form. + +The output buffer is allocated using @code{gnutls_malloc()} . + +It is recommended to use @code{gnutls_x509_privkey_export2_pkcs8()} instead +of this function, when a consistent output format is required. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +Since 3.1.3 +@end deftypefun + +@subheading gnutls_x509_privkey_export2_pkcs8 +@anchor{gnutls_x509_privkey_export2_pkcs8} +@deftypefun {int} {gnutls_x509_privkey_export2_pkcs8} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}, gnutls_datum_t * @var{out}) +@var{key}: Holds the key + +@var{format}: the format of output params. One of PEM or DER. + +@var{password}: the password that will be used to encrypt the key. + +@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t + +@var{out}: will contain a private key PEM or DER encoded + +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 @code{11} definitions. If the flags do not specify the encryption +cipher, then the default 3DES (PBES2) will be used. + +The @code{password} can be either ASCII or UTF-8 in the default PBES2 +encryption schemas, or ASCII for the PKCS12 schemas. + +The output buffer is allocated using @code{gnutls_malloc()} . + +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. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. + +Since 3.1.3 +@end deftypefun + +@subheading gnutls_x509_privkey_export_dsa_raw +@anchor{gnutls_x509_privkey_export_dsa_raw} +@deftypefun {int} {gnutls_x509_privkey_export_dsa_raw} (gnutls_x509_privkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{x}) +@var{key}: a key + +@var{p}: will hold the p + +@var{q}: will hold the q + +@var{g}: will hold the g + +@var{y}: will hold the y + +@var{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 +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_export_ecc_raw +@anchor{gnutls_x509_privkey_export_ecc_raw} +@deftypefun {int} {gnutls_x509_privkey_export_ecc_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k}) +@var{key}: a key + +@var{curve}: will hold the curve + +@var{x}: will hold the x-coordinate + +@var{y}: will hold the y-coordinate + +@var{k}: will hold the private key + +This function will export the ECC private key's parameters found +in the given structure. The new parameters will be allocated using +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +In EdDSA curves the @code{y} parameter will be @code{NULL} and the other parameters +will be in the native format for the curve. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_privkey_export_gost_raw +@anchor{gnutls_x509_privkey_export_gost_raw} +@deftypefun {int} {gnutls_x509_privkey_export_gost_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_digest_algorithm_t * @var{digest}, gnutls_gost_paramset_t * @var{paramset}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k}) +@var{key}: a key + +@var{curve}: will hold the curve + +@var{digest}: will hold the digest + +@var{paramset}: will hold the GOST parameter set ID + +@var{x}: will hold the x-coordinate + +@var{y}: will hold the y-coordinate + +@var{k}: will hold the private key + +This function will export the GOST private key's parameters found +in the given structure. The new parameters will be allocated using +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Note:} parameters will be stored with least significant byte first. On +version 3.6.3 this was incorrectly returned in big-endian format. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_x509_privkey_export_pkcs8 +@anchor{gnutls_x509_privkey_export_pkcs8} +@deftypefun {int} {gnutls_x509_privkey_export_pkcs8} (gnutls_x509_privkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{key}: Holds the key + +@var{format}: the format of output params. One of PEM or DER. + +@var{password}: the password that will be used to encrypt the key. + +@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t + +@var{output_data}: will contain a private key PEM or DER encoded + +@var{output_data_size}: holds the size of output_data (and will be +replaced by the actual size of parameters) + +This function will export the private key to a PKCS8 structure. +Both RSA and DSA keys can be exported. For DSA keys we use +PKCS @code{11} definitions. If the flags do not specify the encryption +cipher, then the default 3DES (PBES2) will be used. + +The @code{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. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. +@end deftypefun + +@subheading gnutls_x509_privkey_export_rsa_raw +@anchor{gnutls_x509_privkey_export_rsa_raw} +@deftypefun {int} {gnutls_x509_privkey_export_rsa_raw} (gnutls_x509_privkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u}) +@var{key}: a key + +@var{m}: will hold the modulus + +@var{e}: will hold the public exponent + +@var{d}: will hold the private exponent + +@var{p}: will hold the first prime (p) + +@var{q}: will hold the second prime (q) + +@var{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 +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_export_rsa_raw2 +@anchor{gnutls_x509_privkey_export_rsa_raw2} +@deftypefun {int} {gnutls_x509_privkey_export_rsa_raw2} (gnutls_x509_privkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u}, gnutls_datum_t * @var{e1}, gnutls_datum_t * @var{e2}) +@var{key}: a key + +@var{m}: will hold the modulus + +@var{e}: will hold the public exponent + +@var{d}: will hold the private exponent + +@var{p}: will hold the first prime (p) + +@var{q}: will hold the second prime (q) + +@var{u}: will hold the coefficient + +@var{e1}: will hold e1 = d mod (p-1) + +@var{e2}: will hold e2 = d mod (q-1) + +This function will export the RSA private key's parameters found +in the given structure. The new parameters will be allocated using +@code{gnutls_malloc()} and will be stored in the appropriate datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_x509_privkey_fix +@anchor{gnutls_x509_privkey_fix} +@deftypefun {int} {gnutls_x509_privkey_fix} (gnutls_x509_privkey_t @var{key}) +@var{key}: a key + +This function will recalculate the secondary parameters in a key. +In RSA keys, this can be the coefficient and exponent1,2. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_generate +@anchor{gnutls_x509_privkey_generate} +@deftypefun {int} {gnutls_x509_privkey_generate} (gnutls_x509_privkey_t @var{key}, gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}, unsigned int @var{flags}) +@var{key}: an initialized key + +@var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} . + +@var{bits}: the size of the parameters to generate + +@var{flags}: Must be zero or flags from @code{gnutls_privkey_flags_t} . + +This function will generate a random private key. Note that this +function must be called on an initialized private key. + +The flag @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} +instructs the key generation process to use algorithms like Shawe-Taylor +(from FIPS PUB186-4) which generate provable parameters out of a seed +for RSA and DSA keys. See @code{gnutls_x509_privkey_generate2()} for more +information. + +Note that when generating an elliptic curve key, the curve +can be substituted in the place of the bits parameter using the +@code{GNUTLS_CURVE_TO_BITS()} macro. The input to the macro is any curve from +@code{gnutls_ecc_curve_t} . + +For DSA keys, if the subgroup size needs to be specified check +the @code{GNUTLS_SUBGROUP_TO_BITS()} macro. + +It is recommended to do not set the number of @code{bits} directly, use @code{gnutls_sec_param_to_pk_bits()} instead . + +See also @code{gnutls_privkey_generate()} , @code{gnutls_x509_privkey_generate2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_generate2 +@anchor{gnutls_x509_privkey_generate2} +@deftypefun {int} {gnutls_x509_privkey_generate2} (gnutls_x509_privkey_t @var{key}, gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}, unsigned int @var{flags}, const gnutls_keygen_data_st * @var{data}, unsigned @var{data_size}) +@var{key}: a key + +@var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} . + +@var{bits}: the size of the modulus + +@var{flags}: Must be zero or flags from @code{gnutls_privkey_flags_t} . + +@var{data}: Allow specifying @code{gnutls_keygen_data_st} types such as the seed to be used. + +@var{data_size}: The number of @code{data} available. + +This function will generate a random private key. Note that this +function must be called on an initialized private key. + +The flag @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} +instructs the key generation process to use algorithms like Shawe-Taylor +(from FIPS PUB186-4) which generate provable parameters out of a seed +for RSA and DSA keys. On DSA keys the PQG parameters are generated using the +seed, while on RSA the two primes. To specify an explicit seed +(by default a random seed is used), use the @code{data} with a @code{GNUTLS_KEYGEN_SEED} +type. + +Note that when generating an elliptic curve key, the curve +can be substituted in the place of the bits parameter using the +@code{GNUTLS_CURVE_TO_BITS()} macro. + +To export the generated keys in memory or in files it is recommended to use the +PKCS@code{8} form as it can handle all key types, and can store additional parameters +such as the seed, in case of provable RSA or DSA keys. +Generated keys can be exported in memory using @code{gnutls_privkey_export_x509()} , +and then with @code{gnutls_x509_privkey_export2_pkcs8()} . + +If key generation is part of your application, avoid setting the number +of bits directly, and instead use @code{gnutls_sec_param_to_pk_bits()} . +That way the generated keys will adapt to the security levels +of the underlying GnuTLS library. + +See also @code{gnutls_privkey_generate2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_get_key_id +@anchor{gnutls_x509_privkey_get_key_id} +@deftypefun {int} {gnutls_x509_privkey_get_key_id} (gnutls_x509_privkey_t @var{key}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}) +@var{key}: a key + +@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} + +@var{output_data}: will contain the key ID + +@var{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 that 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 +* @code{output_data_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will +be returned. The output will normally be a SHA-1 hash output, +which is 20 bytes. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_get_pk_algorithm +@anchor{gnutls_x509_privkey_get_pk_algorithm} +@deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm} (gnutls_x509_privkey_t @var{key}) +@var{key}: should contain a @code{gnutls_x509_privkey_t} type + +This function will return the public key algorithm of a private +key. + +@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on +success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_privkey_get_pk_algorithm2 +@anchor{gnutls_x509_privkey_get_pk_algorithm2} +@deftypefun {int} {gnutls_x509_privkey_get_pk_algorithm2} (gnutls_x509_privkey_t @var{key}, unsigned int * @var{bits}) +@var{key}: should contain a @code{gnutls_x509_privkey_t} type + +@var{bits}: The number of bits in the public key algorithm + +This function will return the public key algorithm of a private +key. + +@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on +success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_privkey_get_seed +@anchor{gnutls_x509_privkey_get_seed} +@deftypefun {int} {gnutls_x509_privkey_get_seed} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t * @var{digest}, void * @var{seed}, size_t * @var{seed_size}) +@var{key}: should contain a @code{gnutls_x509_privkey_t} type + +@var{digest}: if non-NULL it will contain the digest algorithm used for key generation (if applicable) + +@var{seed}: where seed will be copied to + +@var{seed_size}: originally holds the size of @code{seed} , will be updated with actual size + +This function will return the seed that was used to generate the +given private key. That function will succeed only if the key was generated +as a provable key. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_privkey_get_spki +@anchor{gnutls_x509_privkey_get_spki} +@deftypefun {int} {gnutls_x509_privkey_get_spki} (gnutls_x509_privkey_t @var{key}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) +@var{key}: should contain a @code{gnutls_x509_privkey_t} type + +@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} + +@var{flags}: must be zero + +This function will return the public key information of a private +key. The provided @code{spki} must be initialized. + +@strong{Returns:} Zero on success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_privkey_import +@anchor{gnutls_x509_privkey_import} +@deftypefun {int} {gnutls_x509_privkey_import} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}) +@var{key}: The data to store the parsed key + +@var{data}: The DER or PEM encoded certificate. + +@var{format}: One of DER or PEM + +This function will convert the given DER or PEM encoded key to the +native @code{gnutls_x509_privkey_t} format. The output will be stored in + @code{key} . + +If the key is PEM encoded it should have a header that contains "PRIVATE +KEY". Note that this function falls back to PKCS @code{8} decoding without +password, if the default format fails to import. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_import2 +@anchor{gnutls_x509_privkey_import2} +@deftypefun {int} {gnutls_x509_privkey_import2} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}) +@var{key}: The data to store the parsed key + +@var{data}: The DER or PEM encoded key. + +@var{format}: One of DER or PEM + +@var{password}: A password (optional) + +@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t + +This function will import the given DER or PEM encoded key, to +the native @code{gnutls_x509_privkey_t} format, irrespective of the +input format. The input format is auto-detected. + +The supported formats are basic unencrypted key, PKCS8, PKCS12, +and the openssl format. + +If the provided key is encrypted but no password was given, then +@code{GNUTLS_E_DECRYPTION_FAILED} is returned. Since GnuTLS 3.4.0 this +function will utilize the PIN callbacks if any. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_import_dsa_raw +@anchor{gnutls_x509_privkey_import_dsa_raw} +@deftypefun {int} {gnutls_x509_privkey_import_dsa_raw} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{g}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{x}) +@var{key}: The data to store the parsed key + +@var{p}: holds the p + +@var{q}: holds the q + +@var{g}: holds the g + +@var{y}: holds the y (optional) + +@var{x}: holds the x + +This function will convert the given DSA raw parameters to the +native @code{gnutls_x509_privkey_t} format. The output will be stored +in @code{key} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_import_ecc_raw +@anchor{gnutls_x509_privkey_import_ecc_raw} +@deftypefun {int} {gnutls_x509_privkey_import_ecc_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{k}) +@var{key}: The data to store the parsed key + +@var{curve}: holds the curve + +@var{x}: holds the x-coordinate + +@var{y}: holds the y-coordinate + +@var{k}: holds the k + +This function will convert the given elliptic curve parameters to the +native @code{gnutls_x509_privkey_t} format. The output will be stored +in @code{key} . For EdDSA keys, the @code{x} and @code{k} values must be in the +native to curve format. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_privkey_import_gost_raw +@anchor{gnutls_x509_privkey_import_gost_raw} +@deftypefun {int} {gnutls_x509_privkey_import_gost_raw} (gnutls_x509_privkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, gnutls_digest_algorithm_t @var{digest}, gnutls_gost_paramset_t @var{paramset}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{k}) +@var{key}: The data to store the parsed key + +@var{curve}: holds the curve + +@var{digest}: will hold the digest + +@var{paramset}: will hold the GOST parameter set ID + +@var{x}: holds the x-coordinate + +@var{y}: holds the y-coordinate + +@var{k}: holds the k (private key) + +This function will convert the given GOST private key's parameters to the +native @code{gnutls_x509_privkey_t} format. The output will be stored +in @code{key} . @code{digest} should be one of GNUTLS_DIG_GOSR_94, +GNUTLS_DIG_STREEBOG_256 or GNUTLS_DIG_STREEBOG_512. If @code{paramset} is set to +GNUTLS_GOST_PARAMSET_UNKNOWN default one will be selected depending on + @code{digest} . + +@strong{Note:} parameters should be stored with least significant byte first. On +version 3.6.3 big-endian format was used incorrectly. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_x509_privkey_import_openssl +@anchor{gnutls_x509_privkey_import_openssl} +@deftypefun {int} {gnutls_x509_privkey_import_openssl} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, const char * @var{password}) +@var{key}: The data to store the parsed key + +@var{data}: The DER or PEM encoded key. + +@var{password}: the password to decrypt the key (if it is encrypted). + +This function will convert the given PEM encrypted to +the native gnutls_x509_privkey_t format. The +output will be stored in @code{key} . + +The @code{password} should be in ASCII. If the password is not provided +or wrong then @code{GNUTLS_E_DECRYPTION_FAILED} will be returned. + +If the Certificate is PEM encoded it should have a header of +"PRIVATE KEY" and the "DEK-Info" header. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_import_pkcs8 +@anchor{gnutls_x509_privkey_import_pkcs8} +@deftypefun {int} {gnutls_x509_privkey_import_pkcs8} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags}) +@var{key}: The data to store the parsed key + +@var{data}: The DER or PEM encoded key. + +@var{format}: One of DER or PEM + +@var{password}: the password to decrypt the key (if it is encrypted). + +@var{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 @code{key} . Both RSA and DSA keys can be +imported, and flags can only be used to indicate an unencrypted +key. + +The @code{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. + +If the @code{GNUTLS_PKCS_PLAIN} flag is specified and the supplied data +are encrypted then @code{GNUTLS_E_DECRYPTION_FAILED} is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_import_rsa_raw +@anchor{gnutls_x509_privkey_import_rsa_raw} +@deftypefun {int} {gnutls_x509_privkey_import_rsa_raw} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}, const gnutls_datum_t * @var{d}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{u}) +@var{key}: The data to store the parsed key + +@var{m}: holds the modulus + +@var{e}: holds the public exponent + +@var{d}: holds the private exponent + +@var{p}: holds the first prime (p) + +@var{q}: holds the second prime (q) + +@var{u}: holds the coefficient + +This function will convert the given RSA raw parameters to the +native @code{gnutls_x509_privkey_t} format. The output will be stored in + @code{key} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_import_rsa_raw2 +@anchor{gnutls_x509_privkey_import_rsa_raw2} +@deftypefun {int} {gnutls_x509_privkey_import_rsa_raw2} (gnutls_x509_privkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}, const gnutls_datum_t * @var{d}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{u}, const gnutls_datum_t * @var{e1}, const gnutls_datum_t * @var{e2}) +@var{key}: The data to store the parsed key + +@var{m}: holds the modulus + +@var{e}: holds the public exponent + +@var{d}: holds the private exponent + +@var{p}: holds the first prime (p) + +@var{q}: holds the second prime (q) + +@var{u}: holds the coefficient (optional) + +@var{e1}: holds e1 = d mod (p-1) (optional) + +@var{e2}: holds e2 = d mod (q-1) (optional) + +This function will convert the given RSA raw parameters to the +native @code{gnutls_x509_privkey_t} format. The output will be stored in + @code{key} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_init +@anchor{gnutls_x509_privkey_init} +@deftypefun {int} {gnutls_x509_privkey_init} (gnutls_x509_privkey_t * @var{key}) +@var{key}: A pointer to the type to be initialized + +This function will initialize a private key type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_sec_param +@anchor{gnutls_x509_privkey_sec_param} +@deftypefun {gnutls_sec_param_t} {gnutls_x509_privkey_sec_param} (gnutls_x509_privkey_t @var{key}) +@var{key}: a key + +This function will return the security parameter appropriate with +this private key. + +@strong{Returns:} On success, a valid security parameter is returned otherwise +@code{GNUTLS_SEC_PARAM_UNKNOWN} is returned. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_x509_privkey_set_flags +@anchor{gnutls_x509_privkey_set_flags} +@deftypefun {void} {gnutls_x509_privkey_set_flags} (gnutls_x509_privkey_t @var{key}, unsigned int @var{flags}) +@var{key}: A key of type @code{gnutls_x509_privkey_t} + +@var{flags}: flags from the @code{gnutls_privkey_flags} + +This function will set flags for the specified private key, after +it is generated. Currently this is useful for the @code{GNUTLS_PRIVKEY_FLAG_EXPORT_COMPAT} +to allow exporting a "provable" private key in backwards compatible way. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_privkey_set_pin_function +@anchor{gnutls_x509_privkey_set_pin_function} +@deftypefun {void} {gnutls_x509_privkey_set_pin_function} (gnutls_x509_privkey_t @var{privkey}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) +@var{privkey}: The certificate structure + +@var{fn}: the callback + +@var{userdata}: data associated with the callback + +This function will set a callback function to be used when +it is required to access a protected object. This function overrides +the global function set using @code{gnutls_pkcs11_set_pin_function()} . + +Note that this callback is used when decrypting a key. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_privkey_set_spki +@anchor{gnutls_x509_privkey_set_spki} +@deftypefun {int} {gnutls_x509_privkey_set_spki} (gnutls_x509_privkey_t @var{key}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags}) +@var{key}: should contain a @code{gnutls_x509_privkey_t} type + +@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_x509_spki_t} + +@var{flags}: must be zero + +This function will return the public key information of a private +key. The provided @code{spki} must be initialized. + +@strong{Returns:} Zero on success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_x509_privkey_sign_data +@anchor{gnutls_x509_privkey_sign_data} +@deftypefun {int} {gnutls_x509_privkey_sign_data} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{digest}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, void * @var{signature}, size_t * @var{signature_size}) +@var{key}: a key + +@var{digest}: should be a digest algorithm + +@var{flags}: should be 0 for now + +@var{data}: holds the data to be signed + +@var{signature}: will contain the signature + +@var{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 +* @code{signature_size} is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will +be returned. + +Use @code{gnutls_x509_crt_get_preferred_hash_algorithm()} to determine +the hash algorithm. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_verify_params +@anchor{gnutls_x509_privkey_verify_params} +@deftypefun {int} {gnutls_x509_privkey_verify_params} (gnutls_x509_privkey_t @var{key}) +@var{key}: a key + +This function will verify the private key parameters. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_privkey_verify_seed +@anchor{gnutls_x509_privkey_verify_seed} +@deftypefun {int} {gnutls_x509_privkey_verify_seed} (gnutls_x509_privkey_t @var{key}, gnutls_digest_algorithm_t @var{digest}, const void * @var{seed}, size_t @var{seed_size}) +@var{key}: should contain a @code{gnutls_x509_privkey_t} type + +@var{digest}: it contains the digest algorithm used for key generation (if applicable) + +@var{seed}: the seed of the key to be checked with + +@var{seed_size}: holds the size of @code{seed} + +This function will verify that the given private key was generated from +the provided seed. If @code{seed} is @code{NULL} then the seed stored in the @code{key} 's structure +will be used for verification. + +@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PRIVKEY_VERIFICATION_ERROR} +is returned, and zero or positive code on success. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_x509_rdn_get +@anchor{gnutls_x509_rdn_get} +@deftypefun {int} {gnutls_x509_rdn_get} (const gnutls_datum_t * @var{idn}, char * @var{buf}, size_t * @var{buf_size}) +@var{idn}: should contain a DER encoded RDN sequence + +@var{buf}: a pointer to a structure to hold the peer's name + +@var{buf_size}: holds the size of @code{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 +RFC4514. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_x509_rdn_get2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is +updated if the provided buffer is not long enough, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_rdn_get2 +@anchor{gnutls_x509_rdn_get2} +@deftypefun {int} {gnutls_x509_rdn_get2} (const gnutls_datum_t * @var{idn}, gnutls_datum_t * @var{str}, unsigned @var{flags}) +@var{idn}: should contain a DER encoded RDN sequence + +@var{str}: a datum that will hold the name + +@var{flags}: zero of @code{GNUTLS_X509_DN_FLAG_COMPAT} + +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 +RFC4514. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is +updated if the provided buffer is not long enough, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_rdn_get_by_oid +@anchor{gnutls_x509_rdn_get_by_oid} +@deftypefun {int} {gnutls_x509_rdn_get_by_oid} (const gnutls_datum_t * @var{idn}, const char * @var{oid}, unsigned @var{indx}, unsigned int @var{raw_flag}, void * @var{buf}, size_t * @var{buf_size}) +@var{idn}: should contain a DER encoded RDN sequence + +@var{oid}: an Object Identifier + +@var{indx}: In case multiple same OIDs exist in the RDN indicates which +to send. Use 0 for the first one. + +@var{raw_flag}: If non-zero then the raw DER data are returned. + +@var{buf}: a pointer to a structure to hold the peer's name + +@var{buf_size}: holds the size of @code{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 RFC4514. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is +updated if the provided buffer is not long enough, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_x509_rdn_get_oid +@anchor{gnutls_x509_rdn_get_oid} +@deftypefun {int} {gnutls_x509_rdn_get_oid} (const gnutls_datum_t * @var{idn}, unsigned @var{indx}, void * @var{buf}, size_t * @var{buf_size}) +@var{idn}: should contain a DER encoded RDN sequence + +@var{indx}: Indicates which OID to return. Use 0 for the first one. + +@var{buf}: a pointer to a structure to hold the peer's name OID + +@var{buf_size}: holds the size of @code{buf} + +This function will return the specified Object identifier, of the +RDN sequence. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned and * @code{buf_size} is +updated if the provided buffer is not long enough, otherwise a +negative error value. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_x509_spki_deinit +@anchor{gnutls_x509_spki_deinit} +@deftypefun {void} {gnutls_x509_spki_deinit} (gnutls_x509_spki_t @var{spki}) +@var{spki}: the SubjectPublicKeyInfo structure + +This function will deinitialize a SubjectPublicKeyInfo structure. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_spki_get_rsa_pss_params +@anchor{gnutls_x509_spki_get_rsa_pss_params} +@deftypefun {int} {gnutls_x509_spki_get_rsa_pss_params} (gnutls_x509_spki_t @var{spki}, gnutls_digest_algorithm_t * @var{dig}, unsigned int * @var{salt_size}) +@var{spki}: the SubjectPublicKeyInfo structure + +@var{dig}: if non-NULL, it will hold the digest algorithm + +@var{salt_size}: if non-NULL, it will hold the salt size + +This function will get the public key algorithm parameters +of RSA-PSS type. + +@strong{Returns:} zero if the parameters are present or a negative +value on error. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_spki_init +@anchor{gnutls_x509_spki_init} +@deftypefun {int} {gnutls_x509_spki_init} (gnutls_x509_spki_t * @var{spki}) +@var{spki}: A pointer to the type to be initialized + +This function will initialize a SubjectPublicKeyInfo structure used +in PKIX. The structure is used to set additional parameters +in the public key information field of a certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_spki_set_rsa_pss_params +@anchor{gnutls_x509_spki_set_rsa_pss_params} +@deftypefun {void} {gnutls_x509_spki_set_rsa_pss_params} (gnutls_x509_spki_t @var{spki}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{salt_size}) +@var{spki}: the SubjectPublicKeyInfo structure + +@var{dig}: a digest algorithm of type @code{gnutls_digest_algorithm_t} + +@var{salt_size}: the size of salt string + +This function will set the public key parameters for +an RSA-PSS algorithm, in the SubjectPublicKeyInfo structure. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_x509_tlsfeatures_add +@anchor{gnutls_x509_tlsfeatures_add} +@deftypefun {int} {gnutls_x509_tlsfeatures_add} (gnutls_x509_tlsfeatures_t @var{f}, unsigned int @var{feature}) +@var{f}: The TLS features + +@var{feature}: The feature to add + +This function will append a feature to the X.509 TLS features +extension structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_tlsfeatures_check_crt +@anchor{gnutls_x509_tlsfeatures_check_crt} +@deftypefun {unsigned} {gnutls_x509_tlsfeatures_check_crt} (gnutls_x509_tlsfeatures_t @var{feat}, gnutls_x509_crt_t @var{cert}) +@var{feat}: a set of TLSFeatures + +@var{cert}: the certificate to be checked + +This function will check the provided certificate against the TLSFeatures +set in @code{feat} using the RFC7633 p.4.2.2 rules. It will check whether the certificate +contains the features in @code{feat} or a superset. + +@strong{Returns:} non-zero if the provided certificate complies, and zero otherwise. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_tlsfeatures_deinit +@anchor{gnutls_x509_tlsfeatures_deinit} +@deftypefun {void} {gnutls_x509_tlsfeatures_deinit} (gnutls_x509_tlsfeatures_t @var{f}) +@var{f}: The TLS features + +This function will deinitialize a X.509 TLS features extension structure + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_tlsfeatures_get +@anchor{gnutls_x509_tlsfeatures_get} +@deftypefun {int} {gnutls_x509_tlsfeatures_get} (gnutls_x509_tlsfeatures_t @var{f}, unsigned @var{idx}, unsigned int * @var{feature}) +@var{f}: The TLS features + +@var{idx}: The index of the feature to get + +@var{feature}: If the function succeeds, the feature will be stored in this variable + +This function will get a feature from the X.509 TLS features +extension structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_tlsfeatures_init +@anchor{gnutls_x509_tlsfeatures_init} +@deftypefun {int} {gnutls_x509_tlsfeatures_init} (gnutls_x509_tlsfeatures_t * @var{f}) +@var{f}: The TLS features + +This function will initialize a X.509 TLS features extension structure + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error value. + +@strong{Since:} 3.5.1 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_cas +@anchor{gnutls_x509_trust_list_add_cas} +@deftypefun {int} {gnutls_x509_trust_list_add_cas} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crt_t * @var{clist}, unsigned @var{clist_size}, unsigned int @var{flags}) +@var{list}: The list + +@var{clist}: A list of CAs + +@var{clist_size}: The length of the CA list + +@var{flags}: flags from @code{gnutls_trust_list_flags_t} + +This function will add the given certificate authorities +to the trusted list. The CAs in @code{clist} must not be deinitialized +during the lifetime of @code{list} . + +If the flag @code{GNUTLS_TL_NO_DUPLICATES} is specified, then +this function will ensure that no duplicates will be +present in the final trust list. + +If the flag @code{GNUTLS_TL_NO_DUPLICATE_KEY} is specified, then +this function will ensure that no certificates with the +same key are present in the final trust list. + +If either @code{GNUTLS_TL_NO_DUPLICATE_KEY} or @code{GNUTLS_TL_NO_DUPLICATES} +are given, @code{gnutls_x509_trust_list_deinit()} must be called with parameter + @code{all} being 1. + +@strong{Returns:} The number of added elements is returned; that includes +duplicate entries. + +@strong{Since:} 3.0.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_crls +@anchor{gnutls_x509_trust_list_add_crls} +@deftypefun {int} {gnutls_x509_trust_list_add_crls} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crl_t * @var{crl_list}, unsigned @var{crl_size}, unsigned int @var{flags}, unsigned int @var{verification_flags}) +@var{list}: The list + +@var{crl_list}: A list of CRLs + +@var{crl_size}: The length of the CRL list + +@var{flags}: flags from @code{gnutls_trust_list_flags_t} + +@var{verification_flags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL + +This function will add the given certificate revocation lists +to the trusted list. The CRLs in @code{crl_list} must not be deinitialized +during the lifetime of @code{list} . + +This function must be called after @code{gnutls_x509_trust_list_add_cas()} +to allow verifying the CRLs for validity. If the flag @code{GNUTLS_TL_NO_DUPLICATES} +is given, then the final CRL list will not contain duplicate entries. + +If the flag @code{GNUTLS_TL_NO_DUPLICATES} is given, @code{gnutls_x509_trust_list_deinit()} must be +called with parameter @code{all} being 1. + +If flag @code{GNUTLS_TL_VERIFY_CRL} is given the CRLs will be verified before being added, +and if verification fails, they will be skipped. + +@strong{Returns:} The number of added elements is returned; that includes +duplicate entries. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_named_crt +@anchor{gnutls_x509_trust_list_add_named_crt} +@deftypefun {int} {gnutls_x509_trust_list_add_named_crt} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t @var{cert}, const void * @var{name}, size_t @var{name_size}, unsigned int @var{flags}) +@var{list}: The list + +@var{cert}: A certificate + +@var{name}: An identifier for the certificate + +@var{name_size}: The size of the identifier + +@var{flags}: should be 0. + +This function will add the given certificate to the trusted +list and associate it with a name. The certificate will not be +be used for verification with @code{gnutls_x509_trust_list_verify_crt()} +but with @code{gnutls_x509_trust_list_verify_named_crt()} or +@code{gnutls_x509_trust_list_verify_crt2()} - the latter only since +GnuTLS 3.4.0 and if a hostname is provided. + +In principle this function can be used to set individual "server" +certificates that are trusted by the user for that specific server +but for no other purposes. + +The certificate @code{cert} must not be deinitialized during the lifetime +of the @code{list} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_system_trust +@anchor{gnutls_x509_trust_list_add_system_trust} +@deftypefun {int} {gnutls_x509_trust_list_add_system_trust} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) +@var{list}: The structure of the list + +@var{tl_flags}: GNUTLS_TL_* + +@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL + +This function adds the system's default trusted certificate +authorities to the trusted list. Note that on unsupported systems +this function returns @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . + +This function implies the flag @code{GNUTLS_TL_NO_DUPLICATES} . + +@strong{Returns:} The number of added elements or a negative error code on error. + +@strong{Since:} 3.1 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_trust_dir +@anchor{gnutls_x509_trust_list_add_trust_dir} +@deftypefun {int} {gnutls_x509_trust_list_add_trust_dir} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_dir}, const char * @var{crl_dir}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) +@var{list}: The list + +@var{ca_dir}: A directory containing the CAs (optional) + +@var{crl_dir}: A directory containing a list of CRLs (optional) + +@var{type}: The format of the certificates + +@var{tl_flags}: flags from @code{gnutls_trust_list_flags_t} + +@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL + +This function will add the given certificate authorities +to the trusted list. Only directories are accepted by +this function. + +@strong{Returns:} The number of added elements is returned. + +@strong{Since:} 3.3.6 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_trust_file +@anchor{gnutls_x509_trust_list_add_trust_file} +@deftypefun {int} {gnutls_x509_trust_list_add_trust_file} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_file}, const char * @var{crl_file}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) +@var{list}: The list + +@var{ca_file}: A file containing a list of CAs (optional) + +@var{crl_file}: A file containing a list of CRLs (optional) + +@var{type}: The format of the certificates + +@var{tl_flags}: flags from @code{gnutls_trust_list_flags_t} + +@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL + +This function will add the given certificate authorities +to the trusted list. PKCS @code{11} URLs are also accepted, instead +of files, by this function. A PKCS @code{11} URL implies a trust +database (a specially marked module in p11-kit); the URL "pkcs11:" +implies all trust databases in the system. Only a single URL specifying +trust databases can be set; they cannot be stacked with multiple calls. + +@strong{Returns:} The number of added elements is returned. + +@strong{Since:} 3.1 +@end deftypefun + +@subheading gnutls_x509_trust_list_add_trust_mem +@anchor{gnutls_x509_trust_list_add_trust_mem} +@deftypefun {int} {gnutls_x509_trust_list_add_trust_mem} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{cas}, const gnutls_datum_t * @var{crls}, gnutls_x509_crt_fmt_t @var{type}, unsigned int @var{tl_flags}, unsigned int @var{tl_vflags}) +@var{list}: The list + +@var{cas}: A buffer containing a list of CAs (optional) + +@var{crls}: A buffer containing a list of CRLs (optional) + +@var{type}: The format of the certificates + +@var{tl_flags}: flags from @code{gnutls_trust_list_flags_t} + +@var{tl_vflags}: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL + +This function will add the given certificate authorities +to the trusted list. + +If this function is used @code{gnutls_x509_trust_list_deinit()} must be called +with parameter @code{all} being 1. + +@strong{Returns:} The number of added elements is returned. + +@strong{Since:} 3.1 +@end deftypefun + +@subheading gnutls_x509_trust_list_deinit +@anchor{gnutls_x509_trust_list_deinit} +@deftypefun {void} {gnutls_x509_trust_list_deinit} (gnutls_x509_trust_list_t @var{list}, unsigned int @var{all}) +@var{list}: The list to be deinitialized + +@var{all}: if non-zero it will deinitialize all the certificates and CRLs contained in the structure. + +This function will deinitialize a trust list. Note that the + @code{all} flag should be typically non-zero unless you have specified +your certificates using @code{gnutls_x509_trust_list_add_cas()} and you +want to prevent them from being deinitialized by this function. + +@strong{Since:} 3.0.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_get_issuer +@anchor{gnutls_x509_trust_list_get_issuer} +@deftypefun {int} {gnutls_x509_trust_list_get_issuer} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) +@var{list}: The list + +@var{cert}: is the certificate to find issuer for + +@var{issuer}: Will hold the issuer if any. Should be treated as constant +unless @code{GNUTLS_TL_GET_COPY} is set in @code{flags} . + +@var{flags}: flags from @code{gnutls_trust_list_flags_t} (@code{GNUTLS_TL_GET_COPY} is applicable) + +This function will find the issuer of the given certificate. +If the flag @code{GNUTLS_TL_GET_COPY} is specified a copy of the issuer +will be returned which must be freed using @code{gnutls_x509_crt_deinit()} . +In that case the provided @code{issuer} must not be initialized. + +Note that the flag @code{GNUTLS_TL_GET_COPY} is required for this function +to work with PKCS@code{11} trust lists in a thread-safe way. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_get_issuer_by_dn +@anchor{gnutls_x509_trust_list_get_issuer_by_dn} +@deftypefun {int} {gnutls_x509_trust_list_get_issuer_by_dn} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{dn}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) +@var{list}: The list + +@var{dn}: is the issuer's DN + +@var{issuer}: Will hold the issuer if any. Should be deallocated after use. + +@var{flags}: Use zero + +This function will find the issuer with the given name, and +return a copy of the issuer, which must be freed using @code{gnutls_x509_crt_deinit()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_get_issuer_by_subject_key_id +@anchor{gnutls_x509_trust_list_get_issuer_by_subject_key_id} +@deftypefun {int} {gnutls_x509_trust_list_get_issuer_by_subject_key_id} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{dn}, const gnutls_datum_t * @var{spki}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) +@var{list}: The list + +@var{dn}: is the issuer's DN (may be @code{NULL} ) + +@var{spki}: is the subject key ID + +@var{issuer}: Will hold the issuer if any. Should be deallocated after use. + +@var{flags}: Use zero + +This function will find the issuer with the given name and subject key ID, and +return a copy of the issuer, which must be freed using @code{gnutls_x509_crt_deinit()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.2 +@end deftypefun + +@subheading gnutls_x509_trust_list_get_ptr +@anchor{gnutls_x509_trust_list_get_ptr} +@deftypefun {void *} {gnutls_x509_trust_list_get_ptr} (gnutls_x509_trust_list_t @var{tlist}) +@var{tlist}: is a @code{gnutls_x509_trust_list_t} type. + +Get user pointer for tlist. Useful in callback function +gnutls_x509_trust_list_set_getissuer_function. +This is the pointer set with @code{gnutls_x509_trust_list_set_ptr()} . + +@strong{Returns:} the user given pointer from the tlist structure, or +@code{NULL} if it was never set. + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_init +@anchor{gnutls_x509_trust_list_init} +@deftypefun {int} {gnutls_x509_trust_list_init} (gnutls_x509_trust_list_t * @var{list}, unsigned int @var{size}) +@var{list}: A pointer to the type to be initialized + +@var{size}: The size of the internal hash table. Use (0) for default size. + +This function will initialize an X.509 trust list structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_iter_deinit +@anchor{gnutls_x509_trust_list_iter_deinit} +@deftypefun {void} {gnutls_x509_trust_list_iter_deinit} (gnutls_x509_trust_list_iter_t @var{iter}) +@var{iter}: The iterator structure to be deinitialized + +This function will deinitialize an iterator structure. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_iter_get_ca +@anchor{gnutls_x509_trust_list_iter_get_ca} +@deftypefun {int} {gnutls_x509_trust_list_iter_get_ca} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_trust_list_iter_t * @var{iter}, gnutls_x509_crt_t * @var{crt}) +@var{list}: The list + +@var{iter}: A pointer to an iterator (initially the iterator should be @code{NULL} ) + +@var{crt}: where the certificate will be copied + +This function obtains a certificate in the trust list and advances the +iterator to the next certificate. The certificate returned in @code{crt} must be +deallocated with @code{gnutls_x509_crt_deinit()} . + +When past the last element is accessed @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +is returned and the iterator is reset. + +The iterator is deinitialized and reset to @code{NULL} automatically by this +function after iterating through all elements until +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. If the iteration is +aborted early, it must be manually deinitialized using +@code{gnutls_x509_trust_list_iter_deinit()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_remove_cas +@anchor{gnutls_x509_trust_list_remove_cas} +@deftypefun {int} {gnutls_x509_trust_list_remove_cas} (gnutls_x509_trust_list_t @var{list}, const gnutls_x509_crt_t * @var{clist}, unsigned @var{clist_size}) +@var{list}: The list + +@var{clist}: A list of CAs + +@var{clist_size}: The length of the CA list + +This function will remove the given certificate authorities +from the trusted list. + +Note that this function can accept certificates and authorities +not yet known. In that case they will be kept in a separate +black list that will be used during certificate verification. +Unlike @code{gnutls_x509_trust_list_add_cas()} there is no deinitialization +restriction for certificate list provided in this function. + +@strong{Returns:} The number of removed elements is returned. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_trust_list_remove_trust_file +@anchor{gnutls_x509_trust_list_remove_trust_file} +@deftypefun {int} {gnutls_x509_trust_list_remove_trust_file} (gnutls_x509_trust_list_t @var{list}, const char * @var{ca_file}, gnutls_x509_crt_fmt_t @var{type}) +@var{list}: The list + +@var{ca_file}: A file containing a list of CAs + +@var{type}: The format of the certificates + +This function will remove the given certificate authorities +from the trusted list, and add them into a black list when needed. +PKCS 11 URLs are also accepted, instead +of files, by this function. + +See also @code{gnutls_x509_trust_list_remove_cas()} . + +@strong{Returns:} The number of added elements is returned. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_trust_list_remove_trust_mem +@anchor{gnutls_x509_trust_list_remove_trust_mem} +@deftypefun {int} {gnutls_x509_trust_list_remove_trust_mem} (gnutls_x509_trust_list_t @var{list}, const gnutls_datum_t * @var{cas}, gnutls_x509_crt_fmt_t @var{type}) +@var{list}: The list + +@var{cas}: A buffer containing a list of CAs (optional) + +@var{type}: The format of the certificates + +This function will remove the provided certificate authorities +from the trusted list, and add them into a black list when needed. + +See also @code{gnutls_x509_trust_list_remove_cas()} . + +@strong{Returns:} The number of removed elements is returned. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_x509_trust_list_set_getissuer_function +@anchor{gnutls_x509_trust_list_set_getissuer_function} +@deftypefun {void} {gnutls_x509_trust_list_set_getissuer_function} (gnutls_x509_trust_list_t @var{tlist}, gnutls_x509_trust_list_getissuer_function * @var{func}) +@var{tlist}: is a @code{gnutls_x509_trust_list_t} type. + +@var{func}: is the callback function + +This function sets a callback to be called when the peer's certificate +chain is incomplete due a missing intermediate certificate. The callback +may provide the missing certificate for use during verification. + +The callback's function prototype is defined in gnutls/x509.h as: + +int (*callback)(gnutls_x509_trust_list_t list, +const gnutls_x509_crt_t cert, +gnutls_x509_crt_t **issuers, +unsigned int *issuers_size); + +If the callback function is provided then gnutls will call it during the +certificate verification procedure. The callback may wish to use +@code{gnutls_x509_crt_get_authority_info_access()} to get a URI from which +to attempt to download the missing issuer certificate, if available. + +On a successful call, the callback shall allocate the 'issuers' array with +@code{gnutls_x509_crt_list_import2()} . The ownership of both the array and the +elements is transferred to the caller and thus the application does not need +to maintain the memory after the call. + +The callback function should return 0 if the missing issuer certificate +for 'crt' was properly populated and added to the 'issuers', or non-zero +to continue the certificate list verification but with issuer as @code{NULL} . + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_set_ptr +@anchor{gnutls_x509_trust_list_set_ptr} +@deftypefun {void} {gnutls_x509_trust_list_set_ptr} (gnutls_x509_trust_list_t @var{tlist}, void * @var{ptr}) +@var{tlist}: is a @code{gnutls_x509_trust_list_t} type. + +@var{ptr}: is the user pointer + +This function will set (associate) the user given pointer @code{ptr} to +the tlist structure. This pointer can be accessed with +@code{gnutls_x509_trust_list_get_ptr()} . Useful in the callback function +gnutls_x509_trust_list_set_getissuer_function. + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_verify_crt +@anchor{gnutls_x509_trust_list_verify_crt} +@deftypefun {int} {gnutls_x509_trust_list_verify_crt} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t * @var{cert_list}, unsigned int @var{cert_list_size}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func}) +@var{list}: The list + +@var{cert_list}: is the certificate list to be verified + +@var{cert_list_size}: is the certificate list size + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +@var{voutput}: will hold the certificate verification output. + +@var{func}: If non-null will be called on each chain element verification with the output. + +This function will try to verify the given certificate and return +its status. The @code{voutput} parameter will hold an OR'ed sequence of +@code{gnutls_certificate_status_t} flags. + +The details of the verification are the same as in @code{gnutls_x509_trust_list_verify_crt2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_x509_trust_list_verify_crt2 +@anchor{gnutls_x509_trust_list_verify_crt2} +@deftypefun {int} {gnutls_x509_trust_list_verify_crt2} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t * @var{cert_list}, unsigned int @var{cert_list_size}, gnutls_typed_vdata_st * @var{data}, unsigned int @var{elements}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func}) +@var{list}: The list + +@var{cert_list}: is the certificate list to be verified + +@var{cert_list_size}: is the certificate list size + +@var{data}: an array of typed data + +@var{elements}: the number of data elements + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +@var{voutput}: will hold the certificate verification output. + +@var{func}: If non-null will be called on each chain element verification with the output. + +This function will attempt to verify the given certificate chain and return +its status. The @code{voutput} parameter will hold an OR'ed sequence of +@code{gnutls_certificate_status_t} flags. + +When a certificate chain of @code{cert_list_size} with more than one certificates is +provided, the verification status will apply to the first certificate in the chain +that failed verification. The verification process starts from the end of the chain +(from CA to end certificate). The first certificate in the chain must be the end-certificate +while the rest of the members may be sorted or not. + +Additionally a certificate verification profile can be specified +from the ones in @code{gnutls_certificate_verification_profiles_t} by +ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification +flags. + +Additional verification parameters are possible via the @code{data} types; the +acceptable types are @code{GNUTLS_DT_DNS_HOSTNAME} , @code{GNUTLS_DT_IP_ADDRESS} and @code{GNUTLS_DT_KEY_PURPOSE_OID} . +The former accepts as data a null-terminated hostname, and the latter a null-terminated +object identifier (e.g., @code{GNUTLS_KP_TLS_WWW_SERVER} ). +If a DNS hostname is provided then this function will compare +the hostname in the end certificate against the given. If names do not match the +@code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. In addition it +will consider certificates provided with @code{gnutls_x509_trust_list_add_named_crt()} . + +If a key purpose OID is provided and the end-certificate contains the extended key +usage PKIX extension, it will be required to match the provided OID +or be marked for any purpose, otherwise verification will fail with +@code{GNUTLS_CERT_PURPOSE_MISMATCH} status. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. Note that verification failure will not result to an +error code, only @code{voutput} will be updated. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_x509_trust_list_verify_named_crt +@anchor{gnutls_x509_trust_list_verify_named_crt} +@deftypefun {int} {gnutls_x509_trust_list_verify_named_crt} (gnutls_x509_trust_list_t @var{list}, gnutls_x509_crt_t @var{cert}, const void * @var{name}, size_t @var{name_size}, unsigned int @var{flags}, unsigned int * @var{voutput}, gnutls_verify_output_function @var{func}) +@var{list}: The list + +@var{cert}: is the certificate to be verified + +@var{name}: is the certificate's name + +@var{name_size}: is the certificate's name size + +@var{flags}: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations. + +@var{voutput}: will hold the certificate verification output. + +@var{func}: If non-null will be called on each chain element verification with the output. + +This function will try to find a certificate that is associated with the provided +name --see @code{gnutls_x509_trust_list_add_named_crt()} . If a match is found the +certificate is considered valid. In addition to that this function will also +check CRLs. The @code{voutput} parameter will hold an OR'ed sequence of +@code{gnutls_certificate_status_t} flags. + +Additionally a certificate verification profile can be specified +from the ones in @code{gnutls_certificate_verification_profiles_t} by +ORing the result of @code{GNUTLS_PROFILE_TO_VFLAGS()} to the verification +flags. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0.0 +@end deftypefun + -- cgit v1.2.3