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. */

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#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;

	gnutls_global_init();

	/* Initialize an empty certificate request, and
	 * an empty private key.
	 */
	gnutls_x509_crq_init(&crq);

	gnutls_x509_privkey_init(&key);

	/* Generate an RSA key of moderate security.
	 */
	bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_RSA,
					   GNUTLS_SEC_PARAM_MEDIUM);
	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.
	 */
	gnutls_x509_crq_set_challenge_password(crq,
					       "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, &buffer_size);

	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,
				   &buffer_size);

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

	gnutls_x509_crq_deinit(crq);
	gnutls_x509_privkey_deinit(key);

	return 0;
}

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