## Future Future — Future Unstable API |

## Functions

void | p11_kit_set_progname ()
void | (*p11_kit_destroyer) ()
P11KitIter * | p11_kit_iter_new ()
void | p11_kit_iter_set_uri ()
void | p11_kit_iter_add_callback ()
void | p11_kit_iter_add_filter ()
CK_RV | (*p11_kit_iter_callback) ()
void | p11_kit_iter_begin ()
void | p11_kit_iter_begin_with ()
CK_RV | p11_kit_iter_next ()
P11KitIterKind | p11_kit_iter_get_kind ()
CK_FUNCTION_LIST_PTR | p11_kit_iter_get_module ()
CK_SLOT_ID | p11_kit_iter_get_slot ()
CK_SLOT_INFO * | p11_kit_iter_get_slot_info ()
CK_TOKEN_INFO * | p11_kit_iter_get_token ()
CK_SESSION_HANDLE | p11_kit_iter_get_session ()
CK_SESSION_HANDLE | p11_kit_iter_keep_session ()
CK_OBJECT_HANDLE | p11_kit_iter_get_object ()
CK_RV | p11_kit_iter_get_attributes ()
CK_RV | p11_kit_iter_load_attributes ()
CK_RV | p11_kit_iter_destroy_object ()
void | p11_kit_iter_free ()
int | p11_kit_remote_serve_module ()
int | p11_kit_remote_serve_token ()
int | p11_kit_remote_serve_tokens ()

## Types and Values

typedef | P11KitIter
typedef | p11_kit_iter
enum | P11KitIterKind
enum | P11KitIterBehavior

## Description

API that is not yet stable enough to be enabled by default. In all likelihood this will be included in the next release. To use this API you must define a MACRO. See the p11-kit.h header for more details.

## Functions

### p11_kit_set_progname ()

    void
    p11_kit_set_progname (const char *progname);

Set the program base name that is used by the `enable-in` and `disable-in` module configuration options.

Normally this is automatically calculated from the program's argument list. You would usually call this before initializing p11-kit modules.

#### Parameters

progname | the program base name |

### p11_kit_destroyer ()

    void
    (*p11_kit_destroyer) (void *data);

A callback called to free a resource.

#### Parameters

data | data to destroy |

### p11_kit_iter_new ()

    P11KitIter *
    p11_kit_iter_new (P11KitUri *uri,
                      P11KitIterBehavior behavior);

Create a new PKCS#11 iterator for iterating over objects. Only objects that match the `uri` will be returned by the iterator. Relevant information in `uri` is copied, and you need not keep `uri` around.

If no `uri` is specified then the iterator will iterate over all objects, unless otherwise filtered.

#### Parameters

uri | a PKCS#11 URI to filter on, or `NULL`. | [allow-none]
behavior | various behavior flags for iterator |

#### Returns

a new iterator, which should be freed with `p11_kit_iter_free()`.

[transfer full]

### p11_kit_iter_set_uri ()

    void
    p11_kit_iter_set_uri (P11KitIter *iter,
                          P11KitUri *uri);

Set the PKCS#11 uri for iterator. Only objects that match the `uri` will be returned by the iterator. Relevant information in `uri` is copied, and you need not keep `uri` around.

If no `uri` is specified then the iterator will iterate over all objects, unless otherwise filtered.

This function should be called at most once, and should be called before iterating begins.

#### Parameters

iter | the iterator |
uri | a PKCS#11 URI to filter on, or `NULL`. | [allow-none]

### p11_kit_iter_add_callback ()

    void
    p11_kit_iter_add_callback (P11KitIter *iter,
                               p11_kit_iter_callback callback,
                               void *callback_data,
                               p11_kit_destroyer callback_destroy);

Adds a callback to the iterator which will be called each time that an object is iterated.

These callbacks can also perform filtering. If any callback indicates through it's `matches` argument that the object should not match, then that object will not be iterated as far as `p11_kit_iter_next()` is concerned.

The callbacks will be called with the `matches` set to `CK_TRUE` and it's up to filters to change it to `CK_FALSE` when necessary.

#### Parameters

iter | the iterator |
callback | a function to call for each iteration |
callback_data | data to pass to the function. | [allow-none]
callback_destroy | used to cleanup the data. | [allow-none]

### p11_kit_iter_add_filter ()

    void
    p11_kit_iter_add_filter (P11KitIter *iter,
                             CK_ATTRIBUTE *matching,
                             CK_ULONG count);

Add a filter to limit the objects that the iterator iterates over.

Only objects matching the passed in attributes will be iterated. This function can be called multiple times.

The `matching` attributes are copied.

#### Parameters

iter | the iterator |
matching | the attributes that the objects should match. | [array length=count]
count | the number of attributes |

### p11_kit_iter_callback ()

    CK_RV
    (*p11_kit_iter_callback) (P11KitIter *iter,
                              CK_BBOOL *matches,
                              void *data);

A callback setup with `p11_kit_iter_add_callback()`. This callback is called for each object iterated.

If the callback sets `matches` to CK_FALSE, then this object is skipped and not matched by `p11_kit_iter_next()`. If you return anything but CKR_OK, then the iteration is stopped, and `p11_kit_iter_next()` returns the result code.

#### Parameters

iter | the iterator |
matches | whether to match the current object. | [out]
data | callback data |

#### Returns

CKR_OK to continue iterating, CKR_CANCEL to stop, or anything else to fail

### p11_kit_iter_begin ()

    void
    p11_kit_iter_begin (P11KitIter *iter,
                        CK_FUNCTION_LIST_PTR *modules);

Begin iterating PKCS#11 objects in the given `modules` .

The `modules` arguments should be a null-terminated list of pointers to the modules' PKCS#11 function pointers.

For each module, all initialized slots will be iterated over, having sessions opened for each of them in turn, and searched for objects matching the search criteria.

#### Parameters

iter | the iterator |
modules | null-terminated list of modules to iterate over. | [array zero-terminated=1]

### p11_kit_iter_begin_with ()

    void
    p11_kit_iter_begin_with (P11KitIter *iter,
                             CK_FUNCTION_LIST_PTR module,
                             CK_SLOT_ID slot,
                             CK_SESSION_HANDLE session);

Begin iterating PKCS#11 objects in the given `module` .

If `slot` is non-zero then the iteration will be limited to that slot.

If `session` is non-zero then the iteration will be limited to objects visible through that session, which implies that they are also limited to the slot which the session was opened for.

#### Parameters

iter | the iterator |
module | the module to iterate over |
slot | the slot to iterate objects in, or zero. | [allow-none]
session | the session to search for objects on, or zero. | [allow-none]

### p11_kit_iter_next ()

    CK_RV
    p11_kit_iter_next (P11KitIter *iter);

Iterate to the next matching object.

To access the object, session and so on, use the `p11_kit_iter_get_object()`, `p11_kit_iter_get_session()`, and `p11_kit_iter_get_module()` functions.

This call must only be called after either `p11_kit_iter_begin()` or `p11_kit_iter_begin_with()` have been called.

Objects which are skipped by callbacks will not be returned here as matching objects.

#### Parameters

iter | the iterator |

#### Returns

CKR_OK if an object matched, CKR_CANCEL if no more objects, or another error

### p11_kit_iter_get_kind ()

    P11KitIterKind
    p11_kit_iter_get_kind (P11KitIter *iter);

Get the kind of the current match (a module, slot, token, or an object).

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

a P11KitIterKind value

### p11_kit_iter_get_module ()

    CK_FUNCTION_LIST_PTR
    p11_kit_iter_get_module (P11KitIter *iter);

Get the module function pointers for the current matching object.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

the module which the current matching object is in

### p11_kit_iter_get_slot ()

    CK_SLOT_ID
    p11_kit_iter_get_slot (P11KitIter *iter);

Get the slot which the current matching object is on.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

the slot of the current matching object

### p11_kit_iter_get_slot_info ()

    CK_SLOT_INFO *
    p11_kit_iter_get_slot_info (P11KitIter *iter);

Get the slot info for the slot which the current matching object is on.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

the slot of the current matching object.

### p11_kit_iter_get_token ()

    CK_TOKEN_INFO *
    p11_kit_iter_get_token (P11KitIter *iter);

Get the token info for the token which the current matching object is on.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

the slot of the current matching object.

### p11_kit_iter_get_session ()

    CK_SESSION_HANDLE
    p11_kit_iter_get_session (P11KitIter *iter);

Get the session which the current matching object is accessible through.

This can only be called after `p11_kit_iter_next()` succeeds.

The session may be closed after the next `p11_kit_iter_next()` call unless `p11_kit_iter_keep_session()` is called.

#### Parameters

iter | the iterator |

#### Returns

the session used to find the current matching object

### p11_kit_iter_keep_session ()

    CK_SESSION_HANDLE
    p11_kit_iter_keep_session (P11KitIter *iter);

After calling this function the session open for iterating the current object will not be automatically closed by the iterator after later calls to `p11_kit_iter_next()` or `p11_kit_iter_free()`.

It is the callers responsibility to close this session, after the iterator has been freed. The session may still be used by the iterator if further iterations are performed.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

the current session

### p11_kit_iter_get_object ()

    CK_OBJECT_HANDLE
    p11_kit_iter_get_object (P11KitIter *iter);

Get the current matching object.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

the current matching object

### p11_kit_iter_get_attributes ()

    CK_RV
    p11_kit_iter_get_attributes (P11KitIter *iter,
                                 CK_ATTRIBUTE *template,
                                 CK_ULONG count);

Get attributes for the current matching object.

This calls `C_GetAttributeValue` for the object currently iterated to. Return value and attribute memory behavior is identical to the PKCS#11 `C_GetAttributeValue` function.

You might choose to use `p11_kit_iter_load_attributes()` for a more helpful variant.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |
template | the attributes to get. | [array length=count][inout]
count | the number of attributes |

#### Returns

The result from `C_GetAttributeValue`.

### p11_kit_iter_load_attributes ()

    CK_RV
    p11_kit_iter_load_attributes (P11KitIter *iter,
                                  CK_ATTRIBUTE *template,
                                  CK_ULONG count);

Retrieve attributes for the current matching object.

Each attribute in the array will be filled in with the value of that attribute retrieved from the object. After use the attribute value memory pointed to by the `pValue` of each attribute should be freed with the `free()` function.

If the `pValue` of an attribute is not `NULL` passed to this function, then it will be passed to `realloc()` to allocate the correct amount of space for the attribute value.

If any attribute is not present on the object, or is sensitive and cannot be retrieved, then the `pValue` will be NULL. If `pValue` was not `NULL` when passed to this function then it will be freed with `free()`. In these cases `CKR_OK` is returned.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |
template | the attributes to load. | [array length=count][inout]
count | the number of attributes |

#### Returns

CKR_OK or a failure code

### p11_kit_iter_destroy_object ()

    CK_RV
    p11_kit_iter_destroy_object (P11KitIter *iter);

Destroy the current matching object.

This can only be called after `p11_kit_iter_next()` succeeds.

#### Parameters

iter | the iterator |

#### Returns

CKR_OK or a failure code

### p11_kit_iter_free ()

    void
    p11_kit_iter_free (P11KitIter *iter);

Frees the iterator and all resources, such as sessions or callbacks held by the iterator.

#### Parameters

iter | the iterator |

### p11_kit_remote_serve_module ()

    int
    p11_kit_remote_serve_module (CK_FUNCTION_LIST *module,
                                 int in_fd,
                                 int out_fd);

Run a module on a given pair of input/output FDs.

#### Parameters

module | a pointer to a loaded module |
in_fd | input fd |
out_fd | output fd |

#### Returns

0 if success, non-zero otherwise.

### p11_kit_remote_serve_token ()

    int
    p11_kit_remote_serve_token (CK_FUNCTION_LIST *module,
                                CK_TOKEN_INFO *token,
                                int in_fd,
                                int out_fd);

`p11_kit_remote_serve_token` is deprecated and should not be used in newly-written code.

use `p11_kit_remote_serve_tokens()`

Run a token wrapped in a module on a given pair of input/output FDs.

#### Parameters

module | a pointer to a loaded module |
token | a token info |
in_fd | input fd |
out_fd | output fd |

#### Returns

0 if success, non-zero otherwise.

### p11_kit_remote_serve_tokens ()

    int
    p11_kit_remote_serve_tokens (const char **tokens,
                                 size_t n_tokens,
                                 CK_FUNCTION_LIST *provider,
                                 int in_fd,
                                 int out_fd);

`p11_kit_remote_serve_tokens` is deprecated and should not be used in newly-written code.

Expose tokens on a given pair of input/output FDs. If `provider` is not NULL, all the tokens must be provided by the same module.

#### Parameters

tokens | a list of token URIs |
n_tokens | the length of `tokens` |
provider | a PKCS#11 module that provides the tokens. | [nullable]
in_fd | input fd |
out_fd | output fd |

#### Returns

0 if success, non-zero otherwise.

## Types and Values

### P11KitIter

    typedef struct p11_kit_iter P11KitIter;

Used to iterate over PKCS#11 objects, tokens, slots, and modules.

### p11_kit_iter

    typedef P11KitIter p11_kit_iter;

### enum P11KitIterKind

The kind of the current match.

#### Members

P11_KIT_ITER_KIND_MODULE | The iterator is pointing to a module. |
P11_KIT_ITER_KIND_SLOT | The iterator is pointing to a slot. |
P11_KIT_ITER_KIND_TOKEN | The iterator is pointing to a token. |
P11_KIT_ITER_KIND_OBJECT | The iterator is pointing to an object. |
P11_KIT_ITER_KIND_UNKNOWN | The iterator doesn't point to anything. |

### enum P11KitIterBehavior

Various flags controlling the behavior of the iterator.

#### Members

P11_KIT_ITER_BUSY_SESSIONS | Allow the iterator's sessions to be in a busy state when the iterator returns an object. |
P11_KIT_ITER_WANT_WRITABLE | Try to open read-write sessions when iterating over objects. |
P11_KIT_ITER_WITH_MODULES | Stop at each module while iterating. |
P11_KIT_ITER_WITH_SLOTS | Stop at each slot while iterating. |
P11_KIT_ITER_WITH_TOKENS | Stop at each token while iterating. |
P11_KIT_ITER_WITHOUT_OBJECTS | Ignore objects while iterating. |