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: .. code-block:: c 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).