Quick Setup: MarshallSoft AES Library for Visual dBase ProjectsThis guide shows a practical, step-by-step approach to integrating the MarshallSoft AES Library into Visual dBASE projects so you can add AES encryption/decryption for files, strings, and data fields. It covers installation, basic usage examples, common pitfalls, and tips for secure key management in dBASE applications.
What the MarshallSoft AES Library provides
The MarshallSoft AES Library is a C/C++-style encryption library with simple APIs for AES (Advanced Encryption Standard) operations. When used from Visual dBASE, it enables:
- AES-128, AES-192, and AES-256 encryption and decryption
- Encrypting/decrypting strings and binary data (files, blobs)
- Support for common modes like ECB, CBC, and possibly CTR (depending on library version)
- Functions accessible through DLL calls from Visual dBASE
Prerequisites
- Visual dBASE (version that supports calling external DLLs) installed and licensed.
- MarshallSoft AES Library DLL (for Windows) — ensure you have a compatible build (32-bit vs 64-bit) matching your Visual dBASE.
- Basic familiarity with Visual dBASE programming and packages, plus working knowledge of AES concepts (keys, IV, modes).
Installation and setup
- Obtain the MarshallSoft AES Library DLL and documentation from MarshallSoft. Unzip and identify the DLL suitable for your platform (e.g., aeslib32.dll or aeslib64.dll).
- Place the DLL in a location accessible to your application: either the same folder as your executable, a system path, or a folder you’ll reference explicitly when loading.
- Read the DLL’s header/guide to determine exported function names and calling conventions (stdcall vs cdecl). Visual dBASE needs the correct convention to call functions successfully.
- If the DLL requires additional runtime dependencies (MSVC runtime, etc.), install them.
Declaring DLL functions in Visual dBASE
Visual dBASE can call external DLL functions using DECLARE FUNCTION/PROCEDURE statements. Example declarations (adjust names, parameter types, and calling convention per the library docs):
DECLARE INTEGER AES_Encrypt IN "aeslib32.dll" STRING pPlaintext, STRING pKey, STRING pIV, INTEGER keyLen, STRING pCiphertext DECLARE INTEGER AES_Decrypt IN "aeslib32.dll" STRING pCiphertext, STRING pKey, STRING pIV, INTEGER keyLen, STRING pPlaintext Notes:
- MarshallSoft functions may use byte buffers instead of dBASE STRINGs. You might need to allocate RAW or BLOB buffers and pass pointers—consult the MarshallSoft header and Visual dBASE pointer handling.
- If the DLL uses stdcall, add the STDCALL keyword in the DECLARE (if supported) or use the documented calling style.
Example: Encrypting and saving a string
A simple example that encrypts a text string and writes the result to a file. Adjust function names/types to match the DLL’s actual API.
FUNCTION EncryptStringToFile(cText, cKey, cIV, nKeyBits, cOutFile) LOCAL nRes, cCipher * Ensure key length matches (128/192/256 bits) IF LEN(cKey) * 8 <> nKeyBits ? "Key length mismatch." RETURN .F. ENDIF * Call the AES encrypt function from DLL nRes = AES_Encrypt(cText, cKey, cIV, nKeyBits, cCipher) IF nRes <> 0 ? "Encryption failed. Error code:", nRes RETURN .F. ENDIF * Save binary ciphertext to file STRTOFILE(cCipher, cOutFile, 0) && 0 = binary RETURN .T. ENDFUNC Example: Decrypting a file to string
FUNCTION DecryptFileToString(cInFile, cKey, cIV, nKeyBits) LOCAL cCipher, nRes, cPlain cCipher = FILETOSTR(cInFile, 0) && read binary nRes = AES_Decrypt(cCipher, cKey, cIV, nKeyBits, cPlain) IF nRes <> 0 ? "Decryption failed. Error code:", nRes RETURN "" ENDIF RETURN cPlain ENDFUNC Handling binary data and buffers
- Visual dBASE STRINGs can hold binary data but be careful with NULL bytes and encoding. Use functions like FILETOSTR/STRTOFILE with the binary flag.
- If the DLL expects pointers, you may need to use the SYS( ) pointer functions or the Visual dBASE SDK facilities to create and pass memory buffers. Consult Visual dBASE documentation for pointer and BLOB handling.
Choosing AES mode and IV usage
- CBC mode requires a random IV for each encryption operation; store the IV alongside ciphertext (e.g., prepend the IV to the ciphertext file).
- ECB mode should generally be avoided for real data because patterns leak.
- If the DLL supports authenticated modes (GCM), prefer them as they provide integrity checking.
Example: Prepend IV to ciphertext when saving:
* Assume cIV is generated securely (16 bytes for AES) cOut = cIV + cCipher STRTOFILE(cOut, cOutFile, 0) Secure key management tips
- Do not hard-code encryption keys in source code.
- Use environment variables, OS-protected key stores, or require user-entered passphrases.
- If using passphrases, derive keys securely (e.g., PBKDF2, scrypt, or Argon2) — check if MarshallSoft provides a KDF; if not, implement or call a KDF library.
- Protect keys in memory when possible and zero memory after use.
Error handling and testing
- Check return codes from each DLL call and map them to meaningful messages.
- Test with known-answer vectors (test vectors) to ensure the wrapper and calling conventions are correct.
- Verify encryption-decryption round trips and test different input sizes, including exact block-size multiples and non-multiples.
Common pitfalls
- 32-bit vs 64-bit mismatch between Visual dBASE and DLL — match them.
- Incorrect calling convention (stdcall vs cdecl) leads to crashes.
- Passing strings vs pointers incorrectly — leads to corrupted data.
- Not handling NULL bytes in binary strings when saving/loading.
Example project structure
- /bin — your app and DLLs
- /src — dBASE source files and wrappers for AES calls
- /tests — test vectors and sample encrypted files
- /docs — MarshallSoft docs, license, and integration notes
Final checklist before deployment
- Confirm DLL license allows redistribution with your app.
- Match platform bitness and runtimes.
- Implement secure key storage or user key entry.
- Test thoroughly with real-world data and edge cases.
- Consider updating to an authenticated mode (GCM) or layering HMAC for integrity if using CBC.
If you want, I can: provide a ready-to-use Visual dBASE wrapper matching the exact MarshallSoft function signatures (I’ll need the DLL’s exported names and calling convention), or convert the examples above to work with Visual dBASE pointer APIs for binary buffers.
Leave a Reply