Next: , Up: More on certificate authentication   [Contents][Index]

4.2.1 PKCS #10 certificate requests

A certificate request is a structure, which contain information about an applicant of a certificate service. It typically contains a public key, a distinguished name and secondary data such as a challenge password. GnuTLS supports the requests defined in PKCS #10 [RFC2986]. Other formats of certificate requests are not currently supported by GnuTLS.

A certificate request can be generated by associating it with a private key, setting the subject’s information and finally self signing it. The last step ensures that the requester is in possession of the private key.

int gnutls_x509_crq_set_version (gnutls_x509_crq_t crq, unsigned int version)
int gnutls_x509_crq_set_dn (gnutls_x509_crq_t crq, const char * dn, const char ** err)
int gnutls_x509_crq_set_dn_by_oid (gnutls_x509_crq_t crq, const char * oid, unsigned int raw_flag, const void * data, unsigned int sizeof_data)
int gnutls_x509_crq_set_key_usage (gnutls_x509_crq_t crq, unsigned int usage)
int gnutls_x509_crq_set_key_purpose_oid (gnutls_x509_crq_t crq, const void * oid, unsigned int critical)
int gnutls_x509_crq_set_basic_constraints (gnutls_x509_crq_t crq, unsigned int ca, int pathLenConstraint)

The gnutls_x509_crq_set_key and gnutls_x509_crq_sign2 functions associate the request with a private key and sign it. If a request is to be signed with a key residing in a PKCS #11 token it is recommended to use the signing functions shown in Abstract key types.

Function: int gnutls_x509_crq_set_key (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)

crq: should contain a gnutls_x509_crq_t type

key: holds a private key

This function will set the public parameters from the given private key to the request.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Function: int gnutls_x509_crq_sign2 (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key, gnutls_digest_algorithm_t dig, unsigned int flags)

crq: should contain a gnutls_x509_crq_t type

key: holds a private key

dig: The message digest to use, i.e., GNUTLS_DIG_SHA256

flags: must be 0

This function will sign the certificate request with a private key. This must be the same key as the one used in gnutls_x509_crt_set_key() since a certificate request is self signed.

This must be the last step in a certificate request generation since all the previously set parameters are now signed.

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 dig may be GNUTLS_DIG_UNKNOWN , and in that case, a suitable but reasonable for the key algorithm will be selected.

Returns: GNUTLS_E_SUCCESS on success, otherwise a negative error 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 gnutls_x509_crq_set_version() ).

The following example is about generating a certificate request, and a private key. A certificate request can be later be processed by a CA which should return a signed certificate.

/* This example code is placed in the public domain. */

#include <config.h>

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gnutls/gnutls.h>
#include <gnutls/x509.h>
#include <gnutls/abstract.h>
#include <time.h>

/* This example will generate a private key and a certificate
 * request.

int main(void)
        gnutls_x509_crq_t crq;
        gnutls_x509_privkey_t key;
        unsigned char buffer[10 * 1024];
        size_t buffer_size = sizeof(buffer);
        unsigned int bits;


        /* Initialize an empty certificate request, and
         * an empty private key.


        /* Generate an RSA key of moderate security.
        bits =
        gnutls_x509_privkey_generate(key, GNUTLS_PK_RSA, bits, 0);

        /* Add stuff to the distinguished name
        gnutls_x509_crq_set_dn_by_oid(crq, GNUTLS_OID_X520_COUNTRY_NAME,
                                      0, "GR", 2);

        gnutls_x509_crq_set_dn_by_oid(crq, GNUTLS_OID_X520_COMMON_NAME,
                                      0, "Nikos", strlen("Nikos"));

        /* Set the request version.
        gnutls_x509_crq_set_version(crq, 1);

        /* Set a challenge password.
                                               "something to remember here");

        /* Associate the request with the private key
        gnutls_x509_crq_set_key(crq, key);

        /* Self sign the certificate request.
        gnutls_x509_crq_sign2(crq, key, GNUTLS_DIG_SHA1, 0);

        /* Export the PEM encoded certificate request, and
         * display it.
        gnutls_x509_crq_export(crq, GNUTLS_X509_FMT_PEM, buffer,

        printf("Certificate Request: \n%s", buffer);

        /* Export the PEM encoded private key, and
         * display it.
        buffer_size = sizeof(buffer);
        gnutls_x509_privkey_export(key, GNUTLS_X509_FMT_PEM, buffer,

        printf("\n\nPrivate key: \n%s", buffer);


        return 0;


Next: , Up: More on certificate authentication   [Contents][Index]