PKCS11 URIs

PKCS11 URIs — Parsing and building PKCS#11 URIs.

Synopsis

                    GckUriInfo;
enum                GckUriParseFlags;
GckUriInfo*         gck_uri_parse                       (const gchar *uri,
                                                         GckUriParseFlags flags,
                                                         GError **error);
gchar*              gck_uri_build                       (GckUriInfo *uri_info);
void                gck_uri_info_free                   (GckUriInfo *uri_info);

Description

PKCS#11 URIs are a standard for referring to PKCS11 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. Or to build a PKCS#11 URI for a given object, use the gck_object_build_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.

Details

GckUriInfo

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

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.

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 GckUriParseFlags

typedef enum {
	GCK_URI_PARSE_MODULE = (1 << 1),
	GCK_URI_PARSE_TOKEN =   (1 << 2) | GCK_URI_PARSE_MODULE,
	GCK_URI_PARSE_OBJECT =  (1 << 3) | GCK_URI_PARSE_TOKEN,
	GCK_URI_PARSE_ANY =     0xFFFFFFFF,
} GckUriParseFlags;


gck_uri_parse ()

GckUriInfo*         gck_uri_parse                       (const gchar *uri,
                                                         GckUriParseFlags 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 GckUriInfo for more info. Other fields will be set to NULL.

uri :

the URI to parse.

flags :

the context in which the URI will be used.

error :

a GError, or NULL.

Returns :

a newly allocated GckUriInfo, which should be freed with gck_uri_info_free().

gck_uri_build ()

gchar*              gck_uri_build                       (GckUriInfo *uri_info);

Build a PKCS#11 URI. Any set fields of uri_info will be used to build the URI.

uri_info :

the info to build the URI from.

Returns :

a newly allocated string containing a PKCS#11 URI.

gck_uri_info_free ()

void                gck_uri_info_free                   (GckUriInfo *uri_info);

Free a GckUriInfo.

uri_info :

URI info to free.