24U SimpleHASP Plug-In 2.0 Syntax

Syntax revision: 7, 2016-10-05.

Created by: Alena Sochůrková, ©2016 24U Software.

Main Goals

Basic technical parameters

File names: SimpleHASP.fmplugin
Creator: Alena Sochůrková, Zdeněk Hejl and Lukáš Liebzeit
Plug-In ID String: 24SH
Function names prefix: SHasp_
Plug-In API version: FileMaker Pro 14.0 Advanced native
OS X SDK Version: OS X 10.11
OS X Compatibility: OS X 10.9 and higher
Windows Compatibility: Windows 7 and higher
Procesor architectures: i386, x86_64
Suported FileMaker: FileMaker Pro 12 or newer, FileMaker Server 14 or newer

Requirements and constraints

Constraints

Few notes about plug-in constraints

Syntax and functionality of the suggested functions

SHasp_Version ( { versionFormat } )

Returns version string of the active 24U SimpleHASP Plug-In, formatted as requested by the parameter.

Parameters

Name Datatype Condition Description
versionFormat string [enum] Defines the format of the returned version.

Parameter values for versionFormat

"short" To get just the version number. Default value.
"long" To get the plug-in name followed by its version number.
"platform" To get the platform of the code currently running.
"autoupdate" To get autoupdate compatible (comparable) version number.

Description

This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?", then the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

SHasp_Version( "long" )
This will return the plug-in name and its version. In this case it is 24U SimpleHASP Plug-In 2.0

SHasp_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on your OS.

SHasp_Version( "autoupdate" )
Returns 02000000 for version 2.0.0 of the plug-in.

SHasp_Get ( feature_id ; set_id ; selector { ; file_id } )

Returns the current value of a HASP HL key parameter selected by selector.

Parameters

Name Datatype Condition Description
feature_id number If you have solution with several modules, each module can be protected separately by assigning it a specified number. Use 0 if you don't have more modules to protect.
set_id string Unique ID for your set of HASP keys. This ID is provided together with plugin.
selector string Name of the parameter to get
file_id number If you want to get size of specific file, use this parameter for its ID. Otherwise the default Read/Write memory file (ID: 65524) will be used.

Parameter values for selector

"rtc" Returns the current time from keys with real time clock capability. Use "key-info" and find <rtc /> to be sure, if your key has rtc.
Some keys supports V-clock. If you enable them and your key doesn't have rtc, then timestamp from V-clock is returned.
"session-info" Returns information regarding a session context.
"key-info" Returns information about the key.
"update-info" Returns update info.
"size" Returns the memory size of the key in bytes.

Description

This function enables you to get info about the HASP HL Key. It can be used to list the capabilities and parameters of your Key or read the real-time clock.

Result

Function returns 0 or one of the error codes.

Examples

SHasp_Get( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; "rtc" )
Returns the current time from the Time key.

SHasp_Get( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; "key-info" )
Returns available info about the connected key in XML format. Use this to get your key's capabilities.

SHasp_Get( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; "size"; 65525 )
Returns the size of the Read Only memory file (ID: 65525) in bytes.

SHasp_Encrypt ( feature_id ; set_id ; data )

Hardware key encryption.

Parameters

Name Datatype Condition Description
feature_id number If you have solution with several modules, each module can be protected separately by assigning it a specified number. Use 0 if you don't have more modules to protect.
set_id string Unique id for your set of HASP keys. This ID is provided together with plugin.
data string or container The submitted data will be encrypted. All data are padded automatically to prevent the encryption from failing due to short input.

Description

Encrypts the provided data with the secret key store in HASP HL Key using AES 128-bit algorithm and encodes the result in Base64 format.
Note: encrypted data have bigger size, than original (about 33%).

Result

If an error occurs the function will return an error code. Please check the result for error codes after every plugin call, please read more here..

Examples

SHasp_Encrypt( 0; "f38e6dd347c9eeef7619d80d151db412" ; "Secret message that needs to be encrypted" )
The output depends on encryption key used. You can decrypt the message using SHasp_Decrypt.

SHasp_Decrypt ( feature_id ; set_id ; data )

Hardware key decryption.

Parameters

Name Datatype Condition Description
feature_id number If you have solution with several modules, each module can be protected separately by assigning it a specified number. Use 0 if you don't have more modules to protect.
set_id string Unique id for your set of HASP keys. This ID is provided together with plugin.
data string Data to decrypt.

Description

Decrypts the provided data with the secret key stored on HASP HL Key using AES 128-bit algorithm.

Result

Returns decrypted data in the same format that was used for encryption - string or container. If an error occurs the function will return an error code. Please check the result for error codes after every plugin call, please read more here..

Examples

SHasp_Decrypt( 0; "f38e6dd347c9eeef7619d80d151db412" ; "oAxZnifvhq4uJPmEKaGJmowsqiBVOrsAOWnzwP9wQ8dF18Xk9p4jOHHMdZj/GfpHSMLE178S7NdR" )
Decrypts the message using the key stored on HASP HL Key.

SHasp_Read ( feature_id ; set_id ; file_id { ; offset } { ; length } )

Reads from the internal memory of HASP HL key if it's available.

Parameters

Name Datatype Condition Description
feature_id number If you have solution with several modules, each module can be protected separately by assigning it a specified number. Use 0 if you don't have more modules to protect.
set_id string Unique id for your set of HASP keys.
file_id number The requested file ID.
offset number Offset to read from in bytes.
length number Length of data to read in bytes. For text data you can read length between 1 and length you used for SHasp_Write. For non-text data you have to use greater or equal length than the one used during SHasp_Write.

Description

Reads data from the internal memory of HASP HL key. Only data previously written using SHasp_Write will be read.

Result

If an error occurs the function will return an error code. Please check the result for error codes after every plugin call, please read more here.

Note

HASP HL Keys with internal storage offer Read/Write Memory and Read Only Memory. The memory type is selected using file_id parameter.

File ID parameters used in HASP HL Keys with storage capability:

Protected Read/Write Memory ID: 65524, sometimes referred to as HASP_FILEID_RW in HASP HL documentation.
Read Only Memory (ROM) ID: 65525, sometimes referred to as HASP_FILEID_RO in HASP HL documentation.

Examples

SHasp_Read( 0; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 3000 )
Reads at most 3000 bytes of stored data from the Read/Write memory file (ID: 65524). The type of returned data depends on the type used for writing.

SHasp_Read( 0; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 3 )
Reads at most 3 bytes of stored data from the Read/Write memory file (ID: 65524). The type of returned data depends on the type used for writing. If stored data aren't text and they are larger, than 3B, then plugin will return error.

SHasp_Read( 0; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 5 )
Assume, that we are trying to read from file (ID: 65524), where was stored "Hello SimpleHASP". This call will return "Hello" read from the Read/Write memory file (ID: 65524).

SHasp_Read( 0; "f38e6dd347c9eeef7619d80d151db412" ; 65524)
Assume, that we are trying to read from file (ID: 65524), where was stored "Hello SimpleHASP" on offset 0, then this will return "Hello SimpleHASP" read from the Read/Write memory file (ID: 65524).

SHasp_Read( 0; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 12; 5 )
Assume, that we are trying to read from file (ID: 65524), where was stored "Hello SimpleHASP" on offset 12. This call will return "Hello" read from the Read/Write memory file (ID: 65524).

SHasp_Update ( set_id ; path_to_file )

Updates a HASP HL key.

Parameters

Name Datatype Condition Description
set_id string Unique id for your set of HASP keys.
path_to_file string Path to file containing informations for update. This ID is provided together with plugin.

Description

This function writes update information to locally connected key.

Result

This function returns an acknowledgment code. If an error occurs the function will return an error code. Please check the result for error codes after every plugin call, please read more here.

Examples

SHasp_Update( "f38e6dd347c9eeef7619d80d151db412" ; "/Users/username/Documents/fileWithUpdate.v2c" )
Updating HASP key requires cooperation of customer and administrator. As customer you have to generate .c2v file. You can generate this file with our plugin - all you have to do is call function SHasp_Get with \"update-info\" param. Store this result into file and save it as something.c2v. After completing this steps send this file to your administrator. As administrator you can find valuable information here.

SHasp_Write ( feature_id ; set_id ; file_id ; offset ; length ; data )

Writes to the internal memory of HASP HL key if it's available.

Parameters

Name Datatype Condition Description
feature_id number If you have solution with several modules, each module can be protected separately by assigning it a specified number. Use 0 if you don't have more modules to protect.
set_id string Unique id for your set of HASP keys.
file_id number The requested file ID.
offset number Offset to write in bytes.
length number Length of data in bytes. If data are larger than length, then error is returned. If data are smaller than length, then bytes of size length are written to HASP.
data string or container The data to be written.

Description

Writes to the internal memory of HASP HL key. The actual data is prepended with SimpleHASP Plug-In header to ensure data integrity. If the data is shorter than the submitted length, the length will be adjusted. Length shorter than the actual data size will result into error.

Result

Function returns 0, if it returns different value, then it is error code. Please check the result for error codes after every plugin call, please read more here..

Examples

SHasp_Write( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 4000; MyFile::ContainerField )
Writes at most 4000 bytes of data from MyFile::ContainerField to the Read/Write memory file (ID: 65524). The default feature ID is used and no offset is applied.

SHasp_Write( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 8; MyFile::NumberField )
Writes number to the Read/Write memory file (ID: 65524). The default feature ID is used and no offset is applied. All numbers are converted by plugin into type double from C language, therefore size of number has to be at least 8B.

SHasp_Write( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 100; MyFile::NumberField )
Writes number to the Read/Write memory file (ID: 65524). The default feature ID is used and no offset is applied.
Note: If you use SHasp_Read with length smaller, then 100 then reading will fail. If you are not sure about length during reading, then don't use that parameter.

SHasp_Write( 0 ; "f38e6dd347c9eeef7619d80d151db412" ; 65524; 0; 10; "some testing text" )
Returns error code (we're trying to write longer text then the specified length).

Additional info

Memory

HASP HL Keys usually offer a limited internal storage.

Feature ID

Always use the same feature_id for encrypting and decrypting (If you use feature_id=3 for encrypting, then you will have to use the same feature_id for decrypting). For more information see HASP documentation.

Writing range

When writing to HASP, plugin creates header containing original data type and length - The size of the header is 10 bytes (can change in future version). Size of the file (e.g. ID: 65524) has to be greater or equal to offset+total_size+10. Note: For text input total_size=2 * size. For more information please read section "Size of data type" below.

Size of data type

Each datatype requires minimal size, so it can be written into HASP file. See list below to known how to count the minimal size for writing.

Error Codes Table

Here is the list of all error codes which can be returned by the plug-in.

CodeDescription
0 Success The given action succeeded and/or there is no problem with proceeding with another.
-4 Not implemented If you see this error please report the error and steps to reproduce it to 24U Support. This error should never be invoked in the released version of the plug-in.
-50 Wrong parameter If you see this error please check documentation for correct usage of the plug-in.
-51 Container empty Returned when decrypt fails to write into container.
-52 Not enough memory Returned when given length is smaller than required.
-53 Error reading header Returned when trying to read data from place where no data were stored.
-54 Wrong key length You are trying to read smaller amount of non-text data, than was stored.
-55 Error reading container Returned when trying to read container, but reading fails.
-56 Unknown data type Returned when trying to work with unknown data type.
2400 Unknown error An unknown error occurred. If you see this error please report the error and steps to reproduce it to 24U Support. We will try to identify error conditions and add the error to this list with a new error code assigned.
1 Out of range HASP HL error Your request exceeds the HASP HL memory range.
2 Unknown feature ID HASP HL error You have requested an unknown feature_id.
3 Out of memory HASP HL error Your system is out of memory.
5 Access denied HASP HL error Access to feature is denied.
6 Legacy decryption HASP HL error The legacy decryption function cannot work on the feature.
7 Key unavailable HASP HL error The HASP HL key is no longer available.
8 Empty data for decrypting Returned when trying to decrypt empty field..
10 Invalid fileID This fileID isn't valid for this HASP key.
11 Driver version HASP HL error The installed driver is too old to execute the function.
12 Real-time clock HASP HL error A real-time clock (rtc) is not available.
14 Driver missing HASP HL error The required driver is not installed.
19 Required XML tags not found If you see this error, your .v2c file for update is corrupted. Contact your administrator for new one.
23 Unsupported encryption HASP HL error The used hardware does not support the encryption type.
27 Remotely running HASP HL error Program is running remotely on a Terminal Server.
31 Feature unavailable HASP HL error The requested feature is no longer available.
43 Length smaller, than text You are trying to write longer text, than is its length.
44 File for update doesn't exist You've entered invalid path (or path to non-existing file) for SHasp_Update.
45 Invalid set ID You've entered invalid set_id parameter. Please provide set_id that you received along with this Plug-In.
54 Hasp update too old You are trying to update already updated HASP.
55 Hasp update too new Update you posses contains update counter value out of range. Contact your administrator for solution.

Error handling

Please check error codes after every plugin call. Omitting to do so can lead to hardly discoverable problems.
For example SHasp_Decrypt ( 1 ; SHasp_Encrypt(1, "text") ) can lead to misleading error in decrypting if the encrypting fails.