USAFE API ReadMe. Who Should Read This Document? Building the USAFE Sample. Using the.mak File. Using the.dsw File

Transcription

1 USAFE API ReadMe This readme file contains information about the USAFE (User s Secure, Authenticated Field Exchange) API functions used for field activation purposes. Who Should Read This Document? This readme file is for developers who want to create a customized field activation option for their customers rather than using the Field Activation Utility. Building the USAFE Sample The sample files are available at the following path in your Sentinel TM SuperPro installation: <installdir>\safe sample\usafe. You can make this as your current directory, or copy all the contents to your current directory. Note: <Installdir> denotes the path where the software, in context, is installed. By default installation: - On 32-bit Windows operating systems <installdir> refers to the following path: <OS Drive>\Program Files\SafeNet Sentinel\SuperPro\<version>. - On 64-bit Windows operating systems <installdir> refers to the following path: <OS Drive>\Program Files(x86)\SafeNet Sentinel\SuperPro\<version>. To build the 32-bit sample: Using the.mak File You can build the Usample example using the following command-line option: nmake /f SafeUtil.mak CFG="SafeUtil - Win32 Release" Using the.dsw File 1. Open SafeUtil.dsw in the Microsoft Visual C (or higher) workspace. 2. Now, build the SafeUtil example. Note: Before running the USAFE sample, make sure that the USAFE object (USAFE32.dll for 32-bit applications or USAFE64.dll for x64 applications.) is copied into the directory where the sample was built. USAFE API ReadMe 1

2 USAFE API Functions Using the.sln File 1. Open SafeUtil.sln in Visual Studio 2005 IDE. 2. Select Win32 from Solution Platforms drop down. 3. Build the SafeUtil example. To build the 64-bit sample: 1. Open SafeUtil.sln in Visual Studio 2005 IDE. 2. Select x64 option from Solution Platforms drop down. 3. Build the SafeUtil example. Note: The USAFE (of current version (7.1)) supports installing the software key that was generated by SuperPro 7.0. USAFE API Functions GlobalBlock The global block is a 5000 byte buffer that contains information about the serialization of a DSAFE/USAFE pair. This information is required by the SAFE API functions, so it must be initialized before any subsequent calls are made. USAFEInitGlobal This function initializes the USAFE GlobalBlock variable. Format USAFEInitGlobal ( Parameter unsigned char *GlobalBlock ); Name Direction Description GlobalBlock OUT Pointer to the initialized global block. Return Code Returns 1 which denotes SUCCESS. Else, returns an error code (other than 1) defined in the Error Codes Summary on page 9. 2 USAFE API ReadMe

3 USAFE API Functions USAFEFindRnboKey This function searches for the key and identifies its Developer ID and Serial number. The variable KeyID contains the information read from the key in encrypted form. If USAFESetSoftSSPConfig and USAFESelectSoftSSP functions have not been called before this function, this function tries to generate the Locking Code for SuperPro hardware key. If the required information is not found, it returns an error. If USAFESetSoftSSPConfig or USAFESelectSoftSSP is called, it tries to find the SuperPro software key to get the Locking Code. If the software key is not found, it returns the Locking Code containing all Host IDs (User Name, Hard Disk, and NIC) for generating the new SuperPro software key. Format RB_STATUS USAFEFindRnboKey ( unsigned char char *GlobalBlock, *keyid); Parameters Name Direction Description GlobalBlock IN A pointer to initialized global block. keyid IN The key ID string that will be passed to DSAFE. Return Code On success, returns 0. Else, returns an error code defined in the Error Codes Summary on page 9. USAFE API ReadMe 3

4 USAFE API Functions USAFEUpdateRnboKey This function updates the key found by the USAFEFindRnboKey or make unidirectional update using an update string obtained from DSAFE. If a read operation is performed or update receipt is required, the KeyIDstr variable contains a string that will be passed to DSAFE. Please note that the KeyIDstr should be initialized depending on how much information is being generated. For a SuperPro software key, this API inserts SuperPro software key into storage or updates an existing SuperPro software key. Format RB_STATUS USAFEUpdateRnboKey( unsigned char char char unsigned short *GlobalBlock, *updatestr, *KeyIDstr, *KeyIDset); Parameters Name Direction Description GlobalBlock IN A pointer to the initialized global block. updatestr IN The update string obtained from DSAFE. This string contains the commands that will be applied to the attached key. KeyIDstr OUT A pointer to the buffer that receives the data read from the key and/or the update receipt. If you want to read data from the key or request update receipt, the parameter should not be NULL. Otherwise, it can be NULL. KeyIDset OUT A pointer to a 2-byte variable that indicates whether any information was read from the SuperPro key or receipt was generated during the update. KeyIDSet value of 0 indicates that KeyIDstr doesn t contain any information. KeyIDSet value of 1 indicates that KeyIDstr contains the information that was read from the key. KeyIDSet value of 2 indicates that KeyIDstr contains the update receipt. KeyIDSet value of 3 indicates that KeyIDstr contains the information that was read from the key and the update receipt. If you want to read data from the key or request update receipt, the parameter should not be NULL. Otherwise, it can be NULL. Note: The size for initializing the KeyIDstr parameter depends on the size of information that is being generated. Return Code On success, returns 0. Else, returns an error code defined in the Error Codes Summary on page 9. 4 USAFE API ReadMe

5 USAFE API Functions USAFESetSoftSSPConfig This function defines the Host IDs that will be embedded into the Locking code output. You should call this function after calling USAFEInitGlobal. Format RB_STATUS USAFESetSoftSSPConfig( unsigned char *GlobalBlock, unsigned long dwconfig, unsigned char *purawfingerprintbuffer); Parameters Name Direction Description hdevicehandle IN A pointer to initialized global block. dwconfig IN dwconfig can contain the following values: RB_SSP_SOFT_USER_NAME_ID Include current user name ID into Locking code RB_SSP_SOFT_HARDDISK_ID Include current hard disk ID into Locking code. RB_SSP_SOFT_MAC_ID Include all MAC IDs of available network card into the Locking code purawfingerprintbuffer IN Physical address of the network card, contained in the current machine. Note: If RB_SSP_SOFT_MAC_ID is set and purawfingerprintbuffer is set to NULL, the Locking code will contain all MAC IDs of the available network card. If RB_SSP_SOFT_MAC_ID is set and purawfingerprintbuffer contains the physical address of the network card (in current machine), the Locking code will contain a specific MAC ID. Return Code On success, returns 0. Else, returns an error code defined in the Error Codes Summary on page 9. USAFE API ReadMe 5

6 USAFE API Functions USAFESelectSoftSSP The function defines which software key will be updated while generating the Locking Code. You should call this function after calling USAFEInitGlobal. Format RB_STATUS USAFESelectSoftSSP( unsigned char char *GlobalBlock, *pszlicensename, unsigned long dwsn); Parameters Name Direction Description GlobalBlock IN A pointer to the initialized global block. pszlicensename IN License name dwsn IN Serial number Using a combination of lpszlicensename and dwsn The combination of lpszlicensename and dwsn defines the search process for searching the SuperPro software key by USAFEFindRnboKey API. pszlicensename dwsn Result Null Zero Tries to find the first SuperPro software key. Not Null Nonzero Tries to find the SuperPro software key with a specific serial number and license name. Null Nonzero Tries to find the SuperPro software key with a specific serial number. Not Null Zero Tries to find the first SuperPro software key with a specific license name. Return Code On success, returns 0. Else, returns an error code defined in the Error Codes Summary on page 9. Note: If you call USAFESelectSoftSSP() without installing a software key, the generated locking code will contain all host ID options (User Name, Hard Disk, and NIC). 6 USAFE API ReadMe

7 USAFE API Functions USAFEEnumSoftSSP This function enumerates all SuperPro software keys in the machine with the same Developer ID, which is embedded into the USAFE binary file. You should call this function after calling USAFEInitGlobal. Format RB_STATUS USAFEEnumSoftSSP ( unsigned char SOFT_SSP_INFO_REC unsigned long *GlobalBlock, *psoftsspinfo, *count); Parameters Name Direction Description GlobalBlock IN A pointer to the initialized global block. psoftsspinfo OUT A pointer to a sequence of SOFT_SSP_INFO_REC structure. If psoftsspinfo =NULL, the returned count refers to the number of items that shall be allocated for the array. count IN/OUT As input, it refers to the number of SOFT_SSP_INFO_REC. As an output, it refers to the number of SOFT_SSP_INFO_REC that should be allocated. Return Code On success, returns 0. Else, returns an error code defined in the Error Codes Summary on page 9. USAFE API ReadMe 7

8 Data Structures Data Structures SOFT_SSP_INFO_REC SOFT_SSP_INFO_REC provides the software key information after calling USAFEEnumSoftSSP. typedef struct _SOFT_SSP_INFO_REC { unsigned long unsigned long char dwdevid; dwsn; szlicensename[128]; } SOFT_SSP_INFO_REC; 8 USAFE API ReadMe

9 Error Codes Summary Error Codes Summary Error Code (Decimal) Description 0 SERR_SUCCESS Success. 1 SERR_NOT_A_PROPER_PACKET The packet is corrupted. Either the Key ID string or the Update string is not valid. 2 SERR_CHKSUM_FAILED The Key ID string or the Update string have been corrupted. 3 SERR_COMMAND_NOT_IN_RANGE The Command array contained an invalid command. 4 SERR_COULD_NOT_CONVERT The string could not be converted. Either the Key ID string or the Update string is invalid. 5 SERR_ILLEGAL_COMMAND The command is not valid. 6 SERR_NOT_SAFE_FORMAT Could not decipher the string. 7 SERR_TOO_MANY_KEY_ATTACHED Too many keys are attached to the port. 8 SERR_VALUE_NOT_IN_RANGE Cell value is out of range. 9 SERR_KEY_NOT_FOUND Could not find an attached key. 10 SERR_PACKET_IS_EMPTY The SAFE packet is empty. 11 SERR_SERNUM_CORRUPTED The Serial Number is corrupted. 13 SERR_BAD_PASSWORD The Write and/or Overwrite Passwords are incorrect. 14 SERR_CREATE_RECOVERY_FAILED Unable to create the key recovery details. 16 SERR_APP_VER_TOO_OLD Application version too old. 17 SERR_PRODUCT_NOT_SUPPORTED Product version too old. 18 SERR_SUBLIC_OUT_OF_RANGE Used for NetSentinel only 19 SERR_SOFTLIM_OUT_OF_RANGE Used for NetSentinel only. 20 SERR_TOO_FEW_KEY_ATTACHED Both the keys were not attached. 21 SERR_PROD_KEY_NOT_FOUND The product key was not attached. 22 SERR_ILLEGAL_UPDATE One or more commands could not be performed. USAFE API ReadMe 9

10 Error Codes Summary Error Code (Decimal) Description 23 SERR_CHECK_DIST_KEY_FAILED Distributor key was not attached. 24 SERR_ZERO_ACTIVATIONS There are zero activations left for a particular product on the distributor key. 25 SERR_DEMO_KEY_NOT_ATTACHED Demo key is not attached. 27 SERR_SLK_NOT_ATTACHED The required key is not attached. 28 SERR_COUNTER_VALUE_TOO_HIGH The counter value cannot exceed SERR_CANT_FIND_RESOURCE Cannot find the resource from the global block. 101 SERR_NSREAD_FAILED Read failure. 102 SERR_NSWRITE_FAILED Write failure. 103 SERR_NSWRITE_FAILED_X Write failure after a successful write occurred. 104 SERR_NSFAMCODE_FAILED Family code failure. 105 SERR_NSINIT_FAILED Initialize failure. 106 SERR_NSENABLE_FAILED Password failure. Note: The codes are repeated because there are separate set of codes for SuperPro and Net Sentinel. Here SX stands for Sentinel SuperPro & NS stands for Net Sentinel. 101 SERR_SXREAD_FAILED Read failure. 102 SERR_SXWRITE_FAILED Write failure. 103 SERR_SXWRITE_FAILED_X Write failure after a successful write occurred. 104 SERR_SXDEC_FAILED Unable to decrement the counter on the key. 105 SERR_SXINIT_FAILED Initialize failure. 106 SERR_SXENABLE_FAILED Password failure. 107 SERR_SXNON_COUNTERCELL Reading a non-counter cell. 108 SERR_SXINC_FAILED Failed to increment counter cell. 10 USAFE API ReadMe

11 Error Codes Summary Error Code (Decimal) Description 110 SERR_SXQUERY_FAILED SproQuery failure. 111 SERR_SXALGO_FAILED Algorithm is inactive. Attempted query failed. 120 SERR_NOT_ENOUGH_MEMORY Not enough storage is available to process this command. 121 SERR_CODE_VER_OLD Old version Locking/License code. 122 SERR_INVALID_PARAMETER Arguments and values passed to the API function are invalid. 123 SERR_HOST_ID_ERROR The fingerprint of the machine has been changed or the license is enforced with the user name and you are using a different user name. 124 SERR_INVALID_LICENSE SuperPro software key is invalid. It can happen in the cases: The license signature is invalid. The license format is invalid. The license format is valid but some information (like Host ID) in the license is invalid. 125 SERR_LIC_RUN_TIME_ERROR License runtime failed to work due to some error. 126 SERR_LIC_MEMORY_CORRUPTED License is corrupted (like invalid cell format). 127 SERR_LIC_ALREADY_EXIST The license already exists in the system. 128 SERR_INSUFFICIENT_PERMISSIONS User has not sufficient permission to install/delete/write/read license. 129 SERR_ERR_LICENSE_IN_USE The license is in use. 130 SERR_METER_KEY_NOT_FOUND The meter key is not attached to the local machine or the driver of the meter key is not installed on the local machine. 131 SERR_METER_KEY_COUNTER_OUT The SuperPro software key generation counter is exhausted. Please contact SafeNet to order a new meter key. 132 SERR_METER_KEY_ERROR The Meter key has a problem or it is not for current Developer ID. Please contact Technical Support for assistance. 133 SERR_DEVELOPER_CODE Invalid Developer Code. 134 SERR_OS_NOT_SUPPORTED The operating system or environment is not supported by the SAFE library. For example, an attempt may have been made to install a software key on windows 98 platform. 135 SERR_SECURE_UPDATE_INVALID_PACKET The secure update packet is invalid. USAFE API ReadMe 11

12 Error Codes Summary Error Code (Decimal) Description 136 SERR_KEY_NOT_SUPPORT_AES_ALGO The key does not support AES algorithm engine. 137 SERR_SOFTWARE_KEY_NOT_SUPPORTED The USAFE DLL does not support software keys. 138 SERR_USAFE_WITHOUT_ONETIMEUPDATE Locking code is generated by a USAFE not configured with one-time update feature. 139 SERR_NOT_SECURE_SOFTWARE_KEY Locking code is generated for a simple/evaluation software key. 140 SERR_NEW_HARD_LIMIT_ILLEGAL Hard Limit count after update is illegal. 141 SERR_LICENSE_CODE_IS_ONETIME_USE License code is one-time use. 142 SERR_SECURITY_RUNTIME_NOT_DETECTED Sentinel Security Runtime was not installed or detected. Installing the secure software key or evaluation software key was not possible. Verify the Sentinel Security Runtime is correctly installed. 143 SERR_SOFTWARE_KEY_CANNOT_REINSTALL The software key cannot be re-installed. For example, you may have tried to re-install a secure software key or an evaluation software key. 144 SERR_COMMAND_CANNOT_COEXIST Some commands cannot coexist with other commands in license code, like increment hard limit command. 145 SERR_CELL_INDEX_IS_ILLEGAL Cell index parameter in some command is illegal. 146 SERR_DATE_OUT_OF_RANGE The date parameter in some command is out of range. 147 SERR_NOT_SECURE_OR_EVALUATION_SOFTWARE_KEY Locking code is generated for a simple software key. 148 SERR_DEVELOPER_CODE_NOT_SET Developer code is not set. 149 SERR_WRONG_LOCKING_CODE_TYPE Error locking code is provided. 150 SERR_ENABLE_KEY_REINSTALL_FAILED Failed to process enable key reinstall command. 151 SERR_ENABLE_DATABASE_RESTORE_FAILED Failed to process enable database restore command. 152 SERR_PRST_DATA_CORRUPT SuperPro persistence data is in a corrupted state. 153 SERR_SECURITY_RUNTIME_VERSION_MISMATCH SuperPro persistence component versions mismatch. 154 SERR_SOFT_DB_CORRUPT Software key database is in a corrupted state. 155 SERR_SOFT_DB_RESTORE_DETECTED Software key database has been illegally restored to an earlier version. 12 USAFE API ReadMe

13 Error Codes Summary Error Code (Decimal) Description 156 SERR_INSTALL_KEY_FAILED Failed to install a software key. 157 SERR_ACCESS_KEY_FAILED Failed to access a SuperPro key. USAFE API ReadMe 13

14 Contacting Technical Support Contacting Technical Support If you have questions, need additional assistance, or encounter a problem, please contact our Technical Support using one of the methods listed in the following table : Technical Support Contact Information Customer Connection Center (C 3 ) Online support system to get quick answers for your queries. It also provides you direct access to SafeNet knowledge base. Sentinel Integration Center (C3) Provides the information you need to successfully integrate Sentinel products with your solutions. Internet United States Americas support@safenet-inc.com Telephone (800) , (410) France Telephone Germany Europe support@safenet-inc.com Telephone United Kingdom Telephone Australia and New Zealand Telephone China , (Intl) Pacific Rim support@safenet-inc.com (Intl) Telephone (86) India Telephone (Intl) 14 USAFE API ReadMe

15 Contacting Technical Support USAFE API ReadMe 15

16 Contacting Technical Support Copyright 2008, SafeNet, Inc. All rights reserved. SafeNet, Sentinel, SuperPro, and UltraPro are either registered trademarks or trademarks of SafeNet, Inc. Microsoft, Windows, Windows 98, Windows ME, Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, and Internet Explorer are either trademarks or registered trademarks of Microsoft Corporation in the United States and other countries. All other trademarks are the property of their respective owners. We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product. December 2008, Revision D 16 USAFE API ReadMe