## PKCS11 URIs

PKCS11 URIs — Parsing and building PKCS#11 URIs.

## Synopsis

                        GckUriData;
    enum                GckUriFlags;
    GckUriData *        gck_uri_data_new                    (void);
    GckUriData *        gck_uri_parse                       (const gchar *string,
                                                             GckUriFlags flags,
                                                             GError **error);
    gchar *             gck_uri_build                       (GckUriData *uri_data,
                                                             GckUriFlags flags);
    void                gck_uri_data_free                   (GckUriData *uri_data);
    #define             GCK_URI_BAD_PREFIX
    #define             GCK_URI_ERROR

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

## Details

### GckUriData

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

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 GckUriFlags

    typedef enum {
    	GCK_URI_FOR_OBJECT =  (1 << 1),
    	GCK_URI_FOR_TOKEN =   (1 << 2),
    	GCK_URI_FOR_MODULE =  (1 << 3),

    	GCK_URI_FOR_MODULE_WITH_VERSION =
    		(1 << 4) | GCK_URI_FOR_MODULE,

    	GCK_URI_FOR_OBJECT_ON_TOKEN =
    		GCK_URI_FOR_OBJECT | GCK_URI_FOR_TOKEN,

    	GCK_URI_FOR_OBJECT_ON_TOKEN_AND_MODULE =
    		GCK_URI_FOR_OBJECT_ON_TOKEN | GCK_URI_FOR_MODULE,

    	GCK_URI_FOR_ANY =     0x0000FFFF,
    } GckUriFlags;

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

`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_FOR_MODULE_WITH_VERSION` | the URI will match specific version of modules.
`GCK_URI_FOR_OBJECT_ON_TOKEN` | the URI will match objects on a specific token.
`GCK_URI_FOR_OBJECT_ON_TOKEN_AND_MODULE` | the URI will match objects on a specific token inserted into a device with a specific module.
`GCK_URI_FOR_ANY` | parse all recognized components of the URI.

### gck_uri_data_new ()

    GckUriData *        gck_uri_data_new                    (void);

### 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`.

`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()`.

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

`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_free ()

    void                gck_uri_data_free                   (GckUriData *uri_data);

Free a GckUriData.

`uri_data` : | URI data to free.

### GCK_URI_BAD_PREFIX

    #define GCK_URI_BAD_PREFIX GCK_URI_BAD_SCHEME

### GCK_URI_ERROR

    #define             GCK_URI_ERROR                           (gck_uri_get_error_quark ())

Error domain for URI errors.