5.3.3 Reading objects

All PKCS #11 objects are referenced by GnuTLS functions by URLs as described in draft-pechanec-pkcs11uri-03. 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

PKCS #11 objects can be accessed with the functions shown below.

• gnutls_pkcs11_obj_init
• gnutls_pkcs11_obj_deinit

• gnutls_pkcs11_obj_import_url

• gnutls_pkcs11_obj_export_url

• gnutls_pkcs11_obj_export

• gnutls_pkcs11_obj_get_info

• gnutls_pkcs11_obj_list_import_url

• gnutls_x509_crt_import_pkcs11
• gnutls_x509_crt_import_pkcs11_url
• gnutls_x509_crt_list_import_pkcs11

Functions that relate to token handling are shown below.

• gnutls_pkcs11_token_init

• gnutls_pkcs11_token_set_pin

• gnutls_pkcs11_token_get_url

• gnutls_pkcs11_token_get_info

• gnutls_pkcs11_token_get_flags

The following example will list all available PKCS #11 tokens in a system.

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();

That example will only list all certificates in a token that have a corresponding private key.

#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 i, ret;

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