C tutorial

This tutorial uses the following libraries from the nCore API. You may find it useful to familiarize yourself with these libraries by reading the API documentation, which is located at <nfast_dir>/document/ncore/html/index.html.

The following table lists and describes the variables used in this tutorial. Throughout this tutorial you may wish to refer to this table. You may also find it useful to consult the API documentation of the listed types.

Many nCore functions take a call context argument, cctx or ctx, which is passed on to upcalls. The call context structure can be used for any purpose required by an application. For example, the call context could identify an application thread.

The following code shows an example declaration of a call context structure:

By default the nCore API manages memory by using the standard C library functions malloc, realloc, and free. To customize memory management, define a collection of memory allocation upcalls and pass this collection when initializing the application handle. For example, a heavily threaded application may allocate memory per thread, and have separate application handles per thread, to avoid contention. In this code example the memory allocation upcalls re-direct back to the default memory application functions. The call context cctx and the transaction context tctx can contain any context information required by your application.

ncthread_upcalls provides a mechanism to specify how threads are implemented on the target platform. If an application needs to use a non-native thread model then the application can either:

The hardserver application handle is the main access point to nCore functionality. The following code specifies the application initialization arguments and initializes the application handle. The flags sent to the application initialization function in the following code example are:

The following code reads in the Security World information that is associated with the application handle. An application handle will only ever be associated with a single Security World, which consists of one or more modules.

The nCore API supports three types of key protection:

The following three code examples demonstrate how to set up an application to use card set protection.

Keys are generated on a specific module and protected by some form of authorization. When a key is generated the type of authorization that is required to use the key is defined, as well as the purposes for which the key is allowed to be used, for example, only for encryption and decryption, or only for signing and verification.

Start by setting up some command parameters based on the information we have already gathered.

Keys are stored with an ACL, which defines which entities can perform operations with the key. The next step is to populate the acl_params variable with the information needed to create the ACL that will be stored in the key blob along with the key we generate. In this example the application sets the acl_params.f flags parameter to enable key recovery and specify the type of key protection to use. There are three options:

This following code demonstrates how to indicate that a key should be protected by a card set. In this case, the card set is the one selected earlier by the user in Selecting a Security World module.

The make ACL blob flags (acl_params.f) parameter must be same as the make blob flags parameter (blob_params.f), so is set accordingly.

The next step is to define in the ACL for which operations the key is allowed to be used. In this example, the application specifies that the key can be used to sign, verify, encrypt, or decrypt.

The application is now ready to generate the ACL:

The following code sets up further generate key command parameters. The parameters that are required differ according to key type. For example, if an application is generating a Rijndael key, you need to specify the length of the key required, in bytes:

Generating a key in a FIPS140-2 Level 3 environment requires that an application obtains authorization (in this case, card set authorization) before attempting to generate a key. It is possible that the card loader has already obtained the necessary authorization from a prior card-loading operation. In this case, the following call will retrieve this authorization:

If this call returns Status_RQCardMustContinue, an application must explicitly attempt to obtain the correct authorization as follows:

Now that the application has obtained the necessary FIPS 140-2 Level 3 authorization (or cancelled the operation if the correct authorization could not be obtained), it can use the authorization to authorize the creation of the key.

With or without FIPS authorization, the application has now obtained all the information necessary to transact a key-generation operation, so is now ready to send the key-generation command to the selected module. The reply is checked using the reply checking utility function mentioned at the beginning of the chapter.

The application has now generated a new key, but as yet the key exists only in the module’s memory. Next, construct an NFKM_Key key information structure (keyinfo) and then save it to disk.

The next step is to populate the parameters of the blob_params structure, which contains the information that is to be written to the key blob. The following code also checks that a key-generation certificate was included in the reply. The NFKM_MakeBlobsParams flags blob_params.f must be the same as the flags passed to NFKM_newkey_makeaclx() when the application created the private ACL.

The parameters required for the NFKM_newkey_makeblobsx() are now populated, and the application is ready to create the key blob. As this is a symmetric key type the application need only save a private key blob.

The keyinfo structure is now ready to be saved to disk.

The final part of the key-generation process is the important step of unloading the key information in the module.

If you are running your application in FIPS 140-2 Level 3 mode, NFKM_newkey_makeauth() creates a certificate list, which also needs to be freed:

This concludes the explanation of symmetric key-generation. The next section describes the process of generating asymmetric keys.

Keys are generated on a specific module and protected by some form of authorization. When a key is generated the type of authorization that is required to use the key is defined, as well as the purposes for which the key is allowed to be used, for example, only for encryption and decryption, or only for signing and verification.

Start by setting up some command parameters based on the information we have already gathered.

Keys are stored with an ACL which defines which entities can perform operations with the key. The next step is to populate the acl_params variable with the information needed to create the ACL that is stored in the key blob along with the key we generate. The application sets the acl_params.f flags parameter to enable key recovery, and specify the type of key protection to use. There are three options:

This following code demonstrates how to indicate that a key should be protected by a card set. In this case the card set is the one selected earlier by the user in Selecting a Security World module.

The make ACL blob flags (acl_params.f) must be same as the make blob flags (blob_params.f), so it is set accordingly.

The next step is to define in the ACL which operations the key is allowed to be used for. Firstly the application defines the allowed uses for the private key ACL. The is_signing_only_keytype() function is not an nCore function:

The application is now ready to generate the private key ACL:

For asymmetric keys the application also defines a public key ACL.

The public key ACL is created in the same manner as the private key ACL:

The following code sets up further key generation command parameters. The parameters that are required differ according to key type. For example, an application might use the following code when generating a 1024 bit DSA key using strict key verification. For details of the parameters required for the types of key you want to generate, see the relevant nCore API documentation.

Generating a key in a FIPS 140-2 Level 3 environment requires that an application obtains authorization (in this case, card set authorization) before attempting to generate a key. It is possible that the card loader has already obtained the necessary authorization from a prior card-loading operation. In this case, the following call retrieves this authorization:

If this call returns Status_RQCardMustContinue, an application must explicitly attempt to obtain the correct authorization as follows:

Now that the application has obtained the necessary FIPS 140-2 Level 3 authorization (or cancelled the operation if the correct authorization could not be obtained), it can use the authorization to authorize the creation of the key.

With or without FIPS authorization, the application has now obtained all the information necessary to transact a key-generation operation, so is now ready to send the key-generation command to the selected module. The reply is checked using the reply checking utility function mentioned at the beginning of the chapter.

The application has now generated a new key, but as yet the key exists only in the module’s memory. Next, construct an NFKM_Key key information structure (keyinfo) and then save it to disk.

The next step is to populate the parameters of the blob_params structure, which contains the information that will be written to the key blob. The following code also checks that a key-generation certificate was included in the reply. The NFKM_MakeBlobsParams flags blob_params.f must be the same as the flags passed to NFKM_newkey_makeaclx() when the application created the private ACL.

The parameters required for the NFKM_newkey_makeblobsx() are now populated and the application can now create the key blob.

The keyinfo structure is now ready to be saved to disk.

The final part of the key-generation process is the important step of freeing the memory used by the application, so that no key information remains in memory, which would make the key vulnerable to attackers.

If you are running your application in FIPS 140-2 Level 3 mode, NFKM_newkey_makeauth() will have created a certificate list, which also needs to be freed:

This concludes the explanation of asymmetric key-generation.

To load a key, first locate the key blob. A key is identified by the name of the application that created it and the key identifier. The following code tries to find an existing key blob of the requested type. If a key of this type cannot be found, the code generates a new key.

The following code uses a function called generate_key() to generate a key if a key cannot be found.

Before a key can be loaded into a module, an application must obtain the appropriate authorization. In this example the authorization required comes from a card in a card set, so the application must first initialize the card-loading libraries:

A Security World often contains multiple modules, many of which may have the key that is needed to decrypt the key blob an application wants to load. For this example the user is prompted to choose a module that contains the necessary key, and then prompted to provide the card that authorizes the use of the key:

It is also possible for an application to ask the Security World to nominate a usable module by using the NFKM_getusablemodule() function:

Now that the user has selected a module, an application can populate the moduleinfo variable, which is later used as a parameter to the NFKM_cmd_loadblob() function.

The application has now gathered all the information it needs to load the key onto a module using the NFKM_cmd_loadblob() function. The next step is to prepare a pointer to the key that will be loaded into the module. The following code loads the public key blob. An application can load the private key blob in similar fashion using &keyinfo->privblob.

The following code attempts to load the key blob. NFKM_cmd_loadblob() fills in the command structure and handles the reply. Assuming that the command executes successfully, you will now have a handle on the key loaded onto the selected module.