Re: [pkcs11] C_GetInterfaceList

[Tim Hudson <tjh@cryptsoft.com>]

I too find the fixed size limit there somewhat out of place - but I wasn't thinking about the usage and discovery model when originally reviewing it.

Going from 1 fixed function list to the ability to have 10 at a time named interfaces was a significant step forward - and I think in our enthusiasm for finally being able to add more functions to the API we overlooked that limitation.

As long as there is a mechanism to get the list of interfaces that is what matters - whether it is a new function or an adjustment to C_GetFunctionLists isn't the important issue for me at least.

The challenge you have is both being able to pass in a named interface (string) and also being able to get the named interfaces returned - i.e. you should be able to get a specific named interface and not have to receive all the interfaces if you only want one.

Your suggestion seems (at first read) to be a return-all option rather than a select a specific one - i.e. you've lost the original usage model.

Tim.

On Mon, Aug 13, 2018 at 9:14 PM, Daniel Minder <Daniel.Minder@utimaco.com> wrote:

Agree. I didnât think about C_GetMechanismInfo. And for consistency there should be a interface enumeration.

Â

However, for consistency, there should be no data structure and function with a fixed array length, which is the case with GetFunctionLists of the current working draft.

Â

But I disagree that my proposal doesnât let an application discover available interfaces. In fact, it provides both: a list of ALL available interfaces and their associated function list pointers WITHOUT the array limitation.

Â

To be more consistent, for example with C_GetMechanismInfo, it could also work like this:

CK_DECLARE_FUNCTION(CK_RV, C_GetFunctionLists)(

 CK_FUNCTION_LISTS_PTR_PTR ppFunctionLists,

 CK_ULONG_PTR pulCount

);

Â

C_GetFunctionLists obtains a pointer to the Cryptoki libraryâs list of supported interfaces and associated function pointer lists. ppFunctionLists points to a value which will receive a pointer to the libraryâs array of CK_FUNCTION_LISTS structures, which in turn contain a pointer to the interface name and a pointer to a list of function pointers for all the Cryptoki API routines in this interface. The pointers thus obtained may point into memory which is owned by the Cryptoki library, and which may or may not be writable. Whether or not this is the case, no attempt should be made to write to this memory. pulCount receivers the number of interfaces.

Â

There are two ways for an application to call C_ GetFunctionLists:

1. If ppFunctionLists is NULL_PTR, then all that C_ GetFunctionLists does is return (in *pulCount) the number of interfaces, without actually returning them. The contents of

*pulCount on entry to C_ GetFunctionLists has no meaning in this case, and the call returns the value CKR_OK.

2. If ppFunctionLists is not NULL_PTR, then *pulCount MUST contain the size (in terms of CK_FUNCTION_LISTS elements) of the buffer pointed to by ppFunctionLists. If that buffer is large enough to hold the list of interfaces and function pointers, then the list is returned in it, and CKR_OK is returned. If not, then the call to C_ GetFunctionLists returns the value CKR_BUFFER_TOO_SMALL. In either case, the value *pulCount is set to hold the number of interfaces.

C_GetFunctionList and C_GetFunctionLists are the only Cryptoki function which an application may call before calling C_Initialize. It is provided to make it easier and faster for applications to use shared Cryptoki libraries and to use more than one Cryptoki library simultaneously.

Â

Best,

Daniel

Â

Â

From: pkcs11@lists.oasis-open.org [mailto:pkcs11@lists.oasis-open.org] On Behalf Of Tim Hudson
Sent: Montag, 13. August 2018 02:10

To: pkcs11@lists.oasis-open.org
Subject: Re: [pkcs11] C_GetInterfaceList

Â

The same thing could be said for mechanisms with parameters - you cannot use the mechanism without understanding the parameters structure - but we still have a discovery approach to be able to get the list of mechanisms.

It is not unreasonable wanting to be able to know what interfaces are supported - independent of being able to actually use the interfaces.

Your suggested changes still wouldn't let an application discover the range of interfaces available.Â

Â

For a class of applications that is important functionality we have omitted.Â

Â

Tim.

Â

On Fri, Aug 10, 2018 at 2:19 AM, Daniel Minder <Daniel.Minder@utimaco.com> wrote:

Tim, All,

Â

I fully agree on the expectation that there will many small interfaces in the future and that applications need to discover whatâs there. However, I come to a different conclusion.

Â

If I understand you correctly, an application would work as follows:

- Call C_GetInterfaceLists to get the list of interfaces supported by the PKCS#11 API.

- Iterate through the returned list and check which of these names are known to the application (i.e. for which a matching function pointer structure exists)

- Select the final interface set the applications wants to work with and create new array(s) of names, max array size is 10 names.

- Pass this/these array/s to C_GetFunctionLists to get the actual function pointers for the interfaces.

Â

However, itâs also possible to work without C_GetInterfaceLists since C_GetFunctionLists does not require to try out every possible combination â it just sets the pFunctions pointer to NULL it the interface does not exist:

- Application can have static arrays of names that it can work with (i.e. for which a matching function pointer structure exists). Again max array size is 10 names.

- Pass this/these array/s to C_GetFunctionLists to get the actual function pointers for the interfaces â or the information that this interface is not supported.

- Iterate through the returned array and check which interfaces are available and select the final interface set.

Â

Â

Going one step further: We expect that there will be many small interfaces. Thus, the limitation to 10 interfaces / function pointers seems to be small already. Moreover, itâs the first time and only example in the PKCS#11 API where an array is limited to an arbitrary number of elements. Therefore, I suggest to change the original proposal and remove this limitation.

Â

There are different approaches to do so. Let me propose one that also fulfils Timâs requirements on getting an interface list.

Â

CK_FUNCTION_LISTS stays almost as it is (IMO we donât need a ptrptr for pFunctions), but CK_INTERFACES can be removed:

typedef struct {

ÂÂÂÂÂ CK_CHAR *pInterface;

ÂÂÂÂÂ void *pFunctions;

} CK_FUNCTION_LISTS;

Â

CK_DECLARE_FUNCTION(CK_RV, C_GetFunctionLists)(

ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ CK_FUNCTION_LISTS_PTR_PTR ppFunctionLists

);

Â

C_GetFunctionLists obtains a pointer to the Cryptoki libraryâs list of supported interfaces and associated function pointer lists. ppFunctionLists points to a value which will receive a pointer to the libraryâs null-terminated array of CK_FUNCTION_LISTS structures, which in turn contain a pointer to the interface name and a pointer to a list of function pointers for all the Cryptoki API routines in this interface. The pointers thus obtained may point into memory which is owned by the Cryptoki library, and which may or may not be writable. Whether or not this is the case, no attempt should be made to write to this memory.

C_GetFunctionList and C_GetFunctionLists are the only Cryptoki function which an application may call before calling C_Initialize. It is provided to make it easier and faster for applications to use shared Cryptoki libraries and to use more than one Cryptoki library simultaneously.

Â

(Note: The last sentence also needs to be changed for C_GetFunctionList.)

Â

Now, implementing this in the PKCS#11 library is quite easy:

CK_FUNCTIONS_LISTS MyP11LibFctLists[] = {

 { "PKCS 11 2.40", &MyP11Lib240Fcts },

 { "PKCS 11 3.0", &MyP11Lib30Fcts },

 { "Vendor Utimaco:Internals 1.0", &MyP11LibIntFcts },

 { NULL, NULL }

};

Â

An application can now just do (for example, simplified):

CK_FUNCTIONS_LISTS_PTR pFunctionsLists, pCurrentInterface;

CK_FUNCTION_LIST_3_0_PTR pFunctions30 = NULL;

CK_FUNCTION_LIST_UTIMACO_INTERNALS_PTR pFunctionsUtiInt = NULL;

C_GetFunctionsLists(&pFunctionsLists);

for (pCurrentInterface = pFunctionsLists; pCurrentInterface->pInterface; ++pCurrentInterface)

{

 if (strcmp(pCurrentInterface->pInterface, "PKCS 11 3.0") == 0)

ÂÂÂ pFunctions30 = pCurrentInterface->pFunctions;

 else if (strcmp(pCurrentInterface->pInterface, " Vendor Utimaco:Internals 1.0") == 0)

ÂÂÂ pFunctionsUtiInt = pCurrentInterface->pFunctions;

}

// then check if pFunctions30 and pFunctionsUtiInt are NULL and act accordingly

Â

Â

Easy, no array restrictions, fully transparent and yet full control.

Â

Â

Best,

Daniel

Â

From: pkcs11@lists.oasis-open.org [mailto:pkcs11@lists.oasis-open.org] On Behalf Of Tim Hudson
Sent: Mittwoch, 8. August 2018 21:51
To: pkcs11@lists.oasis-open.org
Subject: Re: [pkcs11] C_GetInterfaceList

Â

The expectation is that all those vendors that currently have their substantial lists of extension functions will break them into various smaller sets of interfaces and document them going forward.

Â

You will need to know the matching function pointer structures to use them and there are existing applications which do "discovery" to figure such things out.

Â

Being able to get a list of what is supported is important functionality to being able to know what is possible without basically trying every possible combination of which there will be more than 10 if vendors break things up in a fine grained manner.

Â

And we will ourselves extend that list over time and need to know what standard versions are supported as vendors are not required to support all versions. Thinking ahead to PKCS#11 version 3.255 we could have many function lists and we may not want to have to carry around a full superset function table for everything always - we may move to a set of separate interfaces for groups of functions inside one version.

Â

The concept was to avoid being in the situation where adding functions had a major barrier going forward.

Â

And hopefully we can get some of the vendor extension ideas more visible and shared going forward.

Â

Tim.

Â

---

Utimaco IS GmbH
Germanusstr. 4, D.52080 Aachen, Germany, Tel: +49-241-1696-0, www.utimaco.com
Seat: Aachen â Registergericht Aachen HRB 18922
VAT ID No.: DE 815 496 496
Managementboard: Malte Pollmann (Chairman) CEO, Dr. Frank J. Nellissen CFO

This communication is confidential. We only send and receive email on the basis of the terms set out at https://www.utimaco.com/en/e-mail-disclaimer/

Â

---

Utimaco IS GmbH
Germanusstr. 4, D.52080 Aachen, Germany, Tel: +49-241-1696-0, www.utimaco.com
Seat: Aachen â Registergericht Aachen HRB 18922
VAT ID No.: DE 815 496 496
Managementboard: Malte Pollmann (Chairman) CEO, Dr. Frank J. Nellissen CFO

This communication is confidential. We only send and receive email on the basis of the terms set out at https://www.utimaco.com/en/e-mail-disclaimer/