License Management

Each card must be attributed a valid software license in order to be able to use all the features of the middleware. Cards without a valid license will still be readable, but generating signatures and dechipering data with the private keys, as well as performing updates of the card contents will not be allowed. Software licenses are loaded in the cards themselves (in a specific file).

License requirements and loading

Each license is bound to the card model indication and serial number value. Moreover, each license has a start date and an end date. If the license has expired, or if the license loaded in the card does not correspond to its serial number, the consequences are the same as when the card has no license.

The PKCS#11 interface provided by the middleware can be used to:

• Retrieve the model and serial number values required to generate the licenses (through a call to the standard function C_GetTokenInfo).

• Load the generated license in the smart card. This must be done after a succesful C_Login call with the standard user PIN. The license is loaded by calling C_SetAttributeValue, using a NULL (zero) object handle, and a template containing a single attribute filled as follows:

  • type must be set to the vendor-specific constant 0x8000006A
  • value must contain the byte string containing the license data
  • length must be set to the length of the license data (128 bytes)

Note that the PKCS#11 can also be used to check the current status of the license of a smart card. The license data is extracted by calling C_GetAttributeValue, using a NULL (zero) object handle, and a template containing a single attribute filled as follows:

• type must be set to the same vendor-specific constant 0x8000006A as above
• value must point to a buffer of at least 19 bytes long
• length must be set to 19

The data obtained conforms to the following structure:

struct LICENSE_INFO
{
    char licensePresent;
    char serialValid;
    char dateValid;
    char StartDate[8];
    char EndDate[8];
};

If serialValid and dateValid are both true, it means the license is acceptable by the middleware. Note that licensePresent may still be false in that case, for cards that are part of a global license agreement where licenses are not actually stored in the cards. The given dates are in the format YYYYMMDD (the particular 00000000 value indicates there is no limit).

License generation with a batch card

Licenses can be generated using a specific smart card provided by Idopte (called batch cards). Batch cards will keep track of the number of generated licenses, and will only allow generating up to the number of licenses ordered by the client. They can be recredited by submitting specific codes provided by Idopte when the client orders additional licenses.

Commands

The batch cards must be accessed directly by sending APDU commands. Two commands are necessary for this operation:

SELECT APPLICATION

This command selects the license generation application on the batch card. It is necessary to issue this command before generateing licenses. Even though this could be done once for multiple generations, it is still recommended to do it before each license generation, especially when the same workstation runs other smart card related software (like the middleware).

Command

Field	Value	Meaning
CLA	‘00’
INS	‘A4’	Select
P1	‘04’	Select application
P2	‘0C’	No FCI response required
Lc	‘09’	Length of data field
Data		AID of application: ‘A0000003634D574C01’

Response

Status	Meaning
‘6999’	Wrong application AID
‘6E00’	Wrong CLA
‘6A86’	Incorrect P1-P2
‘9000’	Success

GENERATE LICENSE

This command must be sent to generate a license. The license will be generated for the card with the given model idication and serial number value, and will be valid for the period starting at the given date. The batch card will automatically compute the end of validity date, based on the license validity period that it was configured with.

Command

Field	Value	Meaning
CLA	‘00’
INS	‘F8’	Generate license
P1	‘00’
P2	‘00’
Lc	‘28’	Length of data field
Data		License input data
Le	‘88’	Length of response data field

The license input data contains the following fields:

• The model indication (16 bytes), in UTF-8, exactly as given in the model field of the TOKEN_INFO structure returned by the C_GetTokenInfo PKCS#11 call. The padding with space characters to the right must be preserved.
• The serial number (16 bytes), in UTF-8, exactly as given in the serialNumber field of the TOKEN_INFO structure. The padding with space characters to the right must be preserved.
• The license start date (8 bytes), expressed in numeric ASCII with the YYYYMMDD format.

Response

The response data field contains:

• The computed expiration date (8 bytes), in YYYYMMDD format.
• The license data bytes (80 bytes) that must be loaded, unmodified, in the target card, as described in the previous chapter.

Status	Meaning
‘6E00’	Wrong CLA
‘6A86’	Incorrect P1-P2
‘6700’	Invalid input data length
‘6985’	No more credit (remaining license counter reached zero)
‘6A80’	Invalid input data (date incorrectly formatted)
‘61XX’	Success, response will be obtained through GET RESPONSE command. Response length is given in low-order byte.
‘9000’	Success

Batch Card Management

Although the batch card is reported by the Smart Card Manager tool as an “unsupported” card (because it isn’t a regular PKI card), the Manager can still be used to check the state of the batch card (remaining license counter, total number of emitted licenses, etc…). It can also be used to enter recredit codes when additional licenses are ordered.

The batch card tools can be opened by clicking the “Configuration” icon, then “Software license key” (“Clés de produit”), and then opening the top-right menu (Note that, when in the “Software license key” pane, the Manager may report that no card is detected if only the batch card is inserted - you should ignore this indication and click the hamburger menu icon).