Please enable JavaScript to view this site.

A-Shell Reference

Rewritten July 2016

EFS (Encrypted File System) is an A-Shell add-on that provides various encryption-related functions. It is only available on certain Linux 32 bit platforms. Contact MicroSabio for further details.

Syntax

The EFS command syntax is dependent on the opcode parameter. The various forms are:

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

 

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.

Parameters

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. See History note for A-Shell 6.1.1379.

enable'logging  (Num)  [in]

Specify 0 to disable logging, 1 to enable it

Comments

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!!!

Also See

EFSEXT in maime.ini
OPTIONS in maime.ini
TRACE=EFS TRACE in miame.ini

History

2014 March, A-Shell 6.1.1379:  When A-Shell 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:

AEFS_CLEAR_KEY_ON_EXIT   &h0001        Clear EFS 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.