Syntax revision: 8, 2023-09-12.
Created by: Alisher Ibrayev, Alena Sochůrková, ©2023 24U Software.
Few notes about plug-in constraints
In order for plugin function to work on the server you have to create a config file on server and set the read permission to everyone:
SimpleFile plugin functions won't work on server in these cases:
Every line represent one database, first is the name of the database (with suffix .fmp12) followed by tabulator and then function names separated by '|' (vertical bar).
Or name of the database (with suffix .fmp12) followed by tabulator and then the word "any" if you want to allow all the plugin functions.
You can find template of 24uPluginsAllowedFunctions.txt in Examples.
In following example:
MyFileMakerDatabaseOnServer.fmp12 any
MyOtherFileMakerDatabaseOnServer.fmp12 SHasp_Get|SHasp_Set
Returns version string of the active 24U SimpleHASP Plug-In, formatted as requested by the parameter.
| Name | Datatype | Condition | Description |
|---|---|---|---|
| versionFormat | string | [enum] | Defines the format of the returned version. |
| "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. |
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.
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.
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.
Returns the current value of a HASP HL key parameter selected by selector.
| 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. |
| "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. |
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.
Function returns 0 or one of the error codes.
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.
Hardware key encryption.
| 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. |
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%).
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..
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.
Hardware key decryption.
| 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. |
Decrypts the provided data with the secret key stored on HASP HL Key using AES 128-bit algorithm.
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..
SHasp_Decrypt( 0; "f38e6dd347c9eeef7619d80d151db412" ; "oAxZnifvhq4uJPmEKaGJmowsqiBVOrsAOWnzwP9wQ8dF18Xk9p4jOHHMdZj/GfpHSMLE178S7NdR" )
Decrypts
the message using the key stored on HASP HL Key.
Reads from the internal memory of HASP HL key if it's available.
| 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. |
Reads data from the internal memory of HASP HL key. Only data previously written using SHasp_Write will be read.
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.
HASP HL Keys with internal storage offer Read/Write Memory and Read Only Memory. The memory type is selected using file_id parameter.
| 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. |
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).
Updates a HASP HL key.
| 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. |
This function writes update information to locally connected key.
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.
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.
Writes to the internal memory of HASP HL key if it's available.
| 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. |
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.
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..
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).
HASP HL Keys usually offer a limited internal storage.
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.
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.
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.
Here is the list of all error codes which can be returned by the plug-in.
| Code | Description | |
|---|---|---|
| 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. |
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.