Future

Future — Future Unstable API

Functions

Types and Values

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

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.