5.2.3 Reading objects

All PKCS #11 objects are referenced by GnuTLS functions by URLs as described in [PKCS11URI]. This allows for a consistent naming of objects across systems and applications in the same system. For example a public key on a smart card may be referenced as:

pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
manufacturer=EnterSafe;object=test1;objecttype=public;\
id=32f153f3e37990b08624141077ca5dec2d15faed

while the smart card itself can be referenced as:

pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe

Objects stored in a PKCS #11 token can be extracted if they are not marked as sensitive. Usually only private keys are marked as sensitive and cannot be extracted, while certificates and other data can be retrieved. The functions that can be used to access objects are shown below.

int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t obj, const char * url, unsigned int flags)

int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t obj, gnutls_pkcs11_url_type_t detailed, char ** url)

Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t crt, gnutls_pkcs11_obj_info_t itype, void * output, size_t * output_size)

crt: should contain a gnutls_pkcs11_obj_t structure

itype: Denotes the type of information requested

output: where output will be stored

output_size: contains the maximum size of the output and will be overwritten with actual

This function will return information about the PKCS11 certificate such as the label, id as well as token information where the key is stored. When output is text it returns null terminated string although output_size contains the size of the actual data only.

Returns: GNUTLS_E_SUCCESS (0) on success or a negative error code on error.

Since: 2.12.0

int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt, gnutls_pkcs11_obj_t pkcs11_crt)

int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t crt, const char * url, unsigned int flags)

int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t * certs, unsigned int cert_max, gnutls_pkcs11_obj_t * const objs, unsigned int flags)

Properties of the physical token can also be accessed and altered with GnuTLS. For example data in a token can be erased (initialized), PIN can be altered, etc.

int gnutls_pkcs11_token_init (const char * token_url, const char * so_pin, const char * label)

int gnutls_pkcs11_token_get_url (unsigned int seq, gnutls_pkcs11_url_type_t detailed, char ** url)

int gnutls_pkcs11_token_get_info (const char * url, gnutls_pkcs11_token_info_t ttype, void * output, size_t * output_size)

int gnutls_pkcs11_token_get_flags (const char * url, unsigned int * flags)

int gnutls_pkcs11_token_set_pin (const char * token_url, const char * oldpin, const char * newpin, unsigned int flags)

The following examples demonstrate the usage of the API. The first example will list all available PKCS #11 tokens in a system and the latter will list all certificates in a token that have a corresponding private key.

int i;
char* url;

gnutls_global_init();

for (i=0;;i++) 
  {
    ret = gnutls_pkcs11_token_get_url(i, &url);
    if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
      break;

    if (ret < 0)
      exit(1);
		
    fprintf(stdout, "Token[%d]: URL: %s\n", i, url);
    gnutls_free(url);
  }
gnutls_global_deinit();

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

#include <config.h>
#include <gnutls/gnutls.h>
#include <gnutls/pkcs11.h>
#include <stdio.h>
#include <stdlib.h>

#define URL "pkcs11:URL"

int main(int argc, char **argv)
{
        gnutls_pkcs11_obj_t *obj_list;
        gnutls_x509_crt_t xcrt;
        unsigned int obj_list_size = 0;
        gnutls_datum_t cinfo;
        int ret;
        unsigned int i;

        obj_list_size = 0;
        ret = gnutls_pkcs11_obj_list_import_url(NULL, &obj_list_size, URL,
                                                GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY,
                                                0);
        if (ret < 0 && ret != GNUTLS_E_SHORT_MEMORY_BUFFER)
                return -1;

/* no error checking from now on */
        obj_list = malloc(sizeof(*obj_list) * obj_list_size);

        gnutls_pkcs11_obj_list_import_url(obj_list, &obj_list_size, URL,
                                          GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY,
                                          0);

/* now all certificates are in obj_list */
        for (i = 0; i < obj_list_size; i++) {

                gnutls_x509_crt_init(&xcrt);

                gnutls_x509_crt_import_pkcs11(xcrt, obj_list[i]);

                gnutls_x509_crt_print(xcrt, GNUTLS_CRT_PRINT_FULL, &cinfo);

                fprintf(stdout, "cert[%d]:\n %s\n\n", i, cinfo.data);

                gnutls_free(cinfo.data);
                gnutls_x509_crt_deinit(xcrt);
        }

        return 0;
}

This document was generated on February 9, 2014 using texi2html 5.0.