PKCS11 URIs: Gck Library Reference Manual

PKCS11 URIs

PKCS11 URIs — Parsing and building PKCS#11 URIs.

Functions

GckUriData *	gck_uri_data_new ()
GckUriData *	gck_uri_parse ()
gchar *	gck_uri_build ()
GckUriData *	gck_uri_data_copy ()
void	gck_uri_data_free ()

Types and Values

struct	GckUriData
enum	GckUriError
enum	GckUriFlags
#define	GCK_URI_FOR_MODULE_WITH_VERSION
#define	GCK_URI_FOR_OBJECT_ON_TOKEN
#define	GCK_URI_FOR_OBJECT_ON_TOKEN_AND_MODULE
#define	GCK_URI_ERROR

Object Hierarchy

    GBoxed
    ╰── GckUriData

Description

PKCS\#11 URIs

are a standard for referring to PKCS#11 modules, tokens, or objects. What the PKCS#11 URI refers to depends on the context in which it is used.

A PKCS#11 URI can always resolve to more than one object, token or module. A PKCS#11 URI that refers to a token, would (when used in a context that expects objects) refer to all the token on that module.

In most cases the parsing or building of URIs is handled elsewhere in the GCK library. For example to enumerate objects that match a PKCS#11 URI use the gck_modules_enumerate_uri() function.

To parse a PKCS#11 URI use the gck_uri_parse() function passing in the type of context in which you're using the URI. To build a URI use the gck_uri_build() function.

Functions

gck_uri_data_new ()

GckUriData *
gck_uri_data_new (void);

Allocate a new GckUriData structure. None of the fields will be set.

Returns

a newly allocated GckUriData, free with gck_uri_data_free().

[transfer full]

gck_uri_parse ()

GckUriData *
gck_uri_parse (const gchar *string,
               GckUriFlags flags,
               GError **error);

Parse a PKCS#11 URI for use in a given context.

The result will contain the fields that are relevant for the given context. See GckUriData for more info. Other fields will be set to NULL.

Parameters

string	the URI to parse.
flags	the context in which the URI will be used.
error	a GError, or `NULL`.

Returns

a newly allocated GckUriData; which should be freed with gck_uri_data_free().

[transfer full]

gck_uri_build ()

gchar *
gck_uri_build (GckUriData *uri_data,
               GckUriFlags flags);

Build a PKCS#11 URI. The various parts relevant to the flags specified will be used to build the URI.

Parameters

uri_data	the info to build the URI from.
flags	The context that the URI is for

Returns

a newly allocated string containing a PKCS#11 URI.

gck_uri_data_copy ()

GckUriData *
gck_uri_data_copy (GckUriData *uri_data);

Copy a GckUriData

Parameters

uri_data

URI data to copy

Returns

newly allocated copy of the uri data.

[transfer full]

gck_uri_data_free ()

void
gck_uri_data_free (GckUriData *uri_data);

Free a GckUriData.

Parameters

uri_data

URI data to free.

Types and Values

struct GckUriData

struct GckUriData {
	gboolean any_unrecognized;
	GckModuleInfo *module_info;
	GckTokenInfo *token_info;
	GckAttributes *attributes;
};

Information about the contents of a PKCS#11 URI. Various fields may be NULL depending on the context that the URI was parsed for.

Since PKCS#11 URIs represent a set which results from the intersections of all of the URI parts, if any_recognized is set to TRUE then usually the URI should be treated as not matching anything.

Members

gboolean `any_unrecognized`;	whether any parts of the PKCS#11 URI were unsupported or unrecognized.
GckModuleInfo *`module_info`;	information about the PKCS#11 modules matching the URI.
GckTokenInfo *`token_info`;	information about the PKCS#11 tokens matching the URI.
GckAttributes *`attributes`;	information about the PKCS#11 objects matching the URI.

enum GckUriError

Various error codes used with PKCS#11 URIs

Members

GCK_URI_BAD_SCHEME	invalid URI scheme
GCK_URI_BAD_ENCODING	bad URI encoding
GCK_URI_BAD_SYNTAX	bad URI syntax
GCK_URI_BAD_VERSION	bad URI version component
GCK_URI_NOT_FOUND	piece of the URI was not found

enum GckUriFlags

Which parts of the PKCS#11 URI will be parsed or formatted. These can be combined.

Members

GCK_URI_FOR_OBJECT	the URI will be used to match objects.
GCK_URI_FOR_TOKEN	the URI will be used to match tokens.
GCK_URI_FOR_MODULE	the URI will be used to match modules.
GCK_URI_WITH_VERSION	the URI has specific version numbers for module and/or token
GCK_URI_FOR_ANY	parse all recognized components of the URI.

GCK_URI_FOR_MODULE_WITH_VERSION

#define             GCK_URI_FOR_MODULE_WITH_VERSION         (GCK_URI_WITH_VERSION | GCK_URI_FOR_MODULE)

The URI will match specific version of modules. To be used as a GckUriFlags argument.

GCK_URI_FOR_OBJECT_ON_TOKEN

#define             GCK_URI_FOR_OBJECT_ON_TOKEN             (GCK_URI_FOR_OBJECT | GCK_URI_FOR_TOKEN)

The URI will match objects on a specific token. To be used as a GckUriFlags argument.

GCK_URI_FOR_OBJECT_ON_TOKEN_AND_MODULE

#define             GCK_URI_FOR_OBJECT_ON_TOKEN_AND_MODULE  (GCK_URI_FOR_OBJECT_ON_TOKEN | GCK_URI_FOR_MODULE)

The token inserted into a device with a specific module.

GCK_URI_ERROR

#define             GCK_URI_ERROR                           (gck_uri_error_get_quark ())

Error domain for URI errors.