OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

pkcs11 message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [pkcs11] C_GetInterfaceList


Without writing up a full document, I thought I would outline what I was trying to cover on one of the recent calls.
We expect that vendors will use this for their extensions - sorting out an existing mess under pre-3.0 usage - so the list of interfaces will grow over time - an I would expect vendors to define more than one interface each as the list of extensions that have been added far exceed the base set of functions we have in place in the standard.

I think we need two separate functions, rather than one to handle returning the different function lists.Â
One function to return the list of known interfaces - modelled off C_GetMechanismList - which I call C_GetInterfaceList below.
And separately another function for returning a specific interface - modelled off G_GetFunctionList - which I call C_GetInterface below.

The APIs in C_GetMechanismList returns an array - likewise in C_GetInterfaceList
The API in C_GetFunctionList returns a pointer to the function list - likewise in C_GetInterface.

I think where we hit issues is trying to merge this into a single function and not following the API pattern we already have in place.

There are also a few tidy up items we should address:
- interface names should be able to be UTF8CHARÂ
- flags have a CK_FLAG type - not CK_ULONG
- we should use our _PTR types and the current function parameter naming conventionÂ

I don't think we made it clear how the flags match up to the interfaces - can an interface support a range of different behaviours or is the behaviour fixed per interface?
I think from what has been written the flag is a property of the interface - in that the behaviour itself cannot vary for a given interface - you are getting a different interface if you want different flags.
If however we intended to have different behaviours possible on a given interface then we need to specify more things to be able to handle anything other than "global" flag behaviour.
If this is intended to be global then it should not appear in the CK_INTERFACE structure - but it is there in the current working draft header file so I kept it.

Tim.

/* in the style of pkcs11t.h and pkcs11f.h */Â

typedef struct CK_INTERFACE {
    CK_UTF8CHAR_PTR pInterfaceName;
    CK_VOID_PTR  ÂpFunctionList; /* points to a specific function list
                    Â* e.g. CK_FUNCTION_LIST_3_0 - opaque - and the caller has to know
                    Â* the definition of this structure to be able to use it
                    Â*/
    CK_FLAG    Âflags;     /* supported flags - assuming this is a property of the interface */
};

typedef CK_INTERFACE CK_PTR CK_INTERFACE_PTR;
typedef CK_INTERFACE_PTR CK_PTR CK_INTERFACE_PTR_PTR;

/* C_GetInterfaceList obtains a list of interfaces
Â* supported by a provider
Â*/
CK_PKCS11_FUNCTION_INFO(C_GetInterfaceList)
#ifdef CK_NEED_ARG_LIST
(
 CK_INTERFACE_PTR   pInterfaceList, Â/* gets interface. array */
 CK_ULONG_PTR     pulCount     /* gets # of interfaces. */
);
#endif

/* C_GetInterface obtains an interface supported by a provider */
CK_PKCS11_FUNCTION_INFO(C_GetInterface)
#ifdef CK_NEED_ARG_LISTÂ Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â
(Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â
 CK_UTF8CHAR_PTR   ÂpInterfaceName, /* name of interface to get */
 CK_INTERFACE_PTR_PTR ppInterface,  Â/* gets specific interface */
 CK_FLAGS       flags      /* flags for the interface */
);Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â ÂÂ
#endif                                                     ÂÂ
                                     Â

On Mon, Aug 13, 2018 at 9:41 PM Tim Hudson <tjh@cryptsoft.com> wrote:
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/



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]