save_module/3

save_module(+atom_name, +atom_file, @save_options)

Write all the clauses of a compiled module to a file. The first argument is the name of the module to save, the second is the name of the file which will be created or overwritten with the data from the module. The filename must be an atom enclosed by single or double quotes.
The last argument is a list of options on how to save the module, the available options are:

compress/0: the module is saved in the compressed gzip format, files stored in this format have the .gz extension. It is possible to open the compressed files with other (de)compression utilities like WinZip or GZip. The text editor of Trinc-Prolog can also compress and decompress .gz files, for more information see: text editor.
encrypt/2: the module will be encrypted and then saved.

Encryption

The blowfish encryption algorithm is used to encrypt the files, the size of the key is 128 bits. This key is generated by using the supplied password as input to initialize the encryption key. Because a good password is required Trinc-Prolog checks the entered passwords. The rules for password checking are:

The minimum length of the password is 8 characters.
There must at least be one digit character in the password, for example: 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
At least one character must be a special or a symbolic character, example: (, +, -, _, ], [, etc...

Password examples
test2_	this password is too short
test2test	there is no symbolic or special character in the password
test2_test	this is a correct password, it contains a number ('2') and a symbol character ('_').

The blowfish encryption algorithm is free to use, there are no patents restraining its use and also no export restrictions, it was introduced by Bruce Schneier in 1994. For more information about the blowfish encryption algorithm visit the website of Counterpane: www.counterpane.com.

To protect the contents of encrypted modules it is not possible to use the clause/2 predicate for these modules.

The text editor can also encrypt and decrypt files, for more information see: text editor.

Password management

The first parameter of the encrypt/2 save-option determines how the encryption password is managed by the person that will decrypt the file. The three available options are:

store_key: The password will be stored inside the encrypted file, the password is also encrypted. The person that decrypts the file will never have to enter the password. This option is appropriate if the user may not see the Prolog source. It is also the option with the lowest security level as the password is stored inside the file. The password is stored using a variant of the blowfish algorithm with a random key.
However, if the file is opened with the Trinc-Prolog text editor then it always ask for a key.
ask_key: The password is not stored inside the encrypted file. The user that wants to decrypt the file must enter the password. The user has the choice to save the password in a file for later use. Trinc-Prolog will search for the password when the same encrypted file is opened again. The password is stored using a variant of the blowfish algorithm with a random key.
always_ask_key: The password is not stored in the encrypted file and the user that wants to decrypt the file must always enter the password, the password is never stored. This option is the most secure and is appropriate for transferring and using sensitive data.

Trinc-Prolog can detect if the entered password was correct, it does that by calculating an MD5 digest for the original data being encrypted and comparing it with the MD5 digest calculated while decrypting. Incorrect passwords are never stored. The MD5 digest algorithm is described in rfc1321.

Filenames

As can be seen from the example below two backslash characters are used to separate folders, two backslash characters are used to make sure that a part of a filename is not interpreted as an escape sequence, for instance each '\t' character sequence is replaced by the compiler by a single tab character. For more information about this see escape sequences and symbolic control characters.

Example
save_module(m1, 'c:\\mod1.gz', [compress]).	the clauses of the module m1 are written compressed to the file "c:\mod.txt"
save_module(m1, 'c:\\mod1.gz', [encrypt(store_key, 'test2_test')]).	the clauses of the module m1 are encrypted and then written to the file "c:\mod.txt", the key used for encryption will be stored inside the file and 'test2_test' is the key used for encryption
save_module(m1, 'c:\\mod1.gz', [compress, encrypt(ask_key, 'key2+enc']).	the clauses of the module m1 are compressed, encrypted.and then written to the file "c:\mod.txt", 'ask_key' means that the key used for encryption must be entered by the user opening the module, on opening the module the user may store the key

Exceptions
the argument is a variable	an instantiation_error exception is thrown
the argument is not an atom	a type_error(atom, A) exception is thrown
the open-mode is not readwrite	a permission_error(save, module, A) exception is thrown
no module with the specified name	a existence_error(module, A) exception is thrown
error while writing to file	a permission_error(write, file, A) exception is thrown
save_options is a variable	an instantiation_error exception is thrown
save_options is not a list	a type_error(list, A) exception is thrown
an element E of the list save_options is a variable	an instantiation_error exception is thrown
an element E of the list save_options is not a valid option	a domain_error(save_module_option, E) is thrown
the password P to use for encryption is not correct	a evaluation_error(weak_encryption_key, P) exception is thrown

info@trinc-prolog.com