Rewritten July 2016
xcall EFS, 0, status
xcall EFS, 1, status, key {,append}
xcall EFS, 2, status, fspec, isencrypted
xcall EFS, 3, status, ispec {,ospec}
xcall EFS, 4, status, ispec {,ospec}
xcall EFS, 5, status, key
xcall EFS, 6, buildno
xcall EFS, 7, enable'logging
xcall EFS, 14 , flags
xcall EFS, 15, flags
(Linux only) The A-Shell Encrypted File System (EFS) supports AES encryption of files at the I/O layer below that used by A-Shell/BASIC programs. There are various ways to specify which files are to be encrypted, such as in miame.ini by category or extension, and explicitly by a subroutine. But once encrypted, provided the decryption key has been registered, normal A-Shell/BASIC file I/O operations will automatically decrypt and re-encrypt the data on the fly as needed. Although A-Shell provides various cryptographic routines which operate on strings or individual files, if you have a lot of files to encrypt, EFS provides a more encompassing, more secure, and easier-to-implement solution.
opcode (Num) [in]
Operation to perform, per following table
|
Value |
Function |
|
0 |
Check if EFS is supported |
|
1 |
Set key |
|
2 |
Check if file is encrypted |
|
3 |
Encrypt file |
|
4 |
Decrypt file |
|
5 |
Check key |
|
6 |
Check efslib build |
|
7 |
Enable/disable logging |
|
14 |
Set A-Shell/EFS flags |
|
15 |
Get A-Shell/EFS flags |
status (Signed Num) [out]
Status return code, per following table
|
Value |
Meaning |
|
0 |
Available, licensed, okay |
|
-1 |
Available, not licensed |
|
-2 |
Not available |
|
-3 |
Opcode not supported |
|
-4 |
Parameter error |
|
>0 |
Errno |
key (x,32) [in]
specifies encryption key, mapped as:
MAP1 KEY,X,32
MAP2 KEY$,S,32,@KEY
By specifying the unformatted key parameter, it will not show up in the trace log even if TRACE=XCALL is set. Furthermore, if your key is less than 32 bytes long, the remaining key bytes will be supplied from a default internal ashell key. By taking advantage of this feature, even if your part of the key was exposed and a copy of the file stolen, the culprit would still need a licensed copy of A-Shell to decrypt it.
append (Num [in]
if specified and non-zero, specified key is appended to the default internal A-Shell key
fspec (String) [in]
filespec in native or A-Shell notation
ispec (String) [in]
input filespec in native or A-Shell notation
ospec (String) [in]
output filespec in native or A-Shell notation
isencrypted (Num) [out]
returns non-zero if file encrypted, else zero
buildno (Num) [out]
returns the EFS build # (version #), which will be an integer in the range of 1-9999
flags (Num) [in/out]
EFS system option flags, from following table:
ASH_EFS_CLEAR_KEY_ON_EXIT &h0001 Clear EFS key on exit to dot prompt; set by default
enable'logging (Num) [in]
Specify 0 to disable logging, 1 to enable it
When the EFS license option in enabled, A-Shell will automatically detect when a random, ISAM, ISAM-A or sequential file has been encrypted and thus there is no need to specifically identify to A-Shell which files are encrypted, except when you create a new file. In that case, for RANDOM files created with ALLOCATE, use XCALL ASFLAG,AF_CRYPTE prior to the allocate to set the encryption flag. As with other ASFLAG values, the setting only lasts until the end of the current program. For ISAM-A, you can use the ISMUTL /E switch, which requires ISMUTL.LIT 1.3(128) or higher. For old ISAM, you can first use ISMBLD, then use XCALL EFS,3,STS,ISPEC to encrypt the DAT and/or IDX file(s).
For encrypting sequential output files, you can either set the system parameters OPTIONS=EFS_OUT_AMOS or EFS_OUT_HOST, or the corresponding GOP2_EFS_OUT_xxx flags via MX_SETOPTIONS.
You can also request that particular file extensions be automatically encrypted when created via the EFSEXT option in miame.ini.
DIR.LIT will display an "E" next to any encrypted files.
Because EFS is so powerful, and because the stakes are high, developers considering EFS are urged to carefully review the capabilities and configuration options before implementation. You don't want to go to a lot of trouble to lock all the windows but leave the front door open, and you don't want to lock yourself out of the house! We cannot help you recover a lost encryption key!!!
• EFSEXT in maime.ini
• MX_GETOPTIONS, MX_SETOPTIONS
• TRACE=EFS TRACEin miame.ini
History
2014 March, A-Shell 6.1.1379: When ashell enters the interactive dot prompt state, it now (by default) clears the encryption key. This way, if a program should unexpectedly abort and drop to the dot prompt, it will not leave the user with access to encrypted files. You can override this behavior by using one or both of the new opcodes 14 or 15. Currently the only defined flag is:
&h0001 (AEFS_CLR_KEY_ON_EXIT) ! clear encryption key on exit to dot prompt
The AEFS_CLR_KEY_ON_EXIT flag is set by default. To disable the option (returning to the prior behavior), use { XCALL EFS, 14, 0 } to clear the flag.