Exercise 2 - Testing Working Extracts in Design
4.3 Import from Excel
4.3.1 Selecting an MDB for User Defined Data
Once the import operation has finished, the System Administrator is prompted to supply an MDB if one has not previously been set.
If the imported data contains UDA’s or UDET’s then the MDB selected should contain a Lexicon Database. As DAC may contain references to UDA’s or UDET’s it is important that this is checked prior to importing the data.
If DAC has not been specified, and neither UDA’s or UDET’s have been used, the System Administrator can select <None>.
www.aveva.com
The Admin Database can be rolled back following an Excel import in the event that errors were encountered.
The Rollback utility can be accessed by selecting Utilities > Rollback from the main menu.
The Rollback form is displayed showing the items that will be deleted.
Selecting the Rollback button in the middle of the form instigates the process. Due to the nature of this process, confirmation is immediately sought from the User.
Selecting the Yes button continues the process, while selecting the No button stops the process.
If the Rollback process is continued, the lower portion of the Rollback form will be populated with tasks that have taken place.
The user can verify the results of the Rollback process by refreshing the view of the Admin Explorer.
www.aveva.com
Exercise 3 – Project Setup Excel Export / Import
Use the Export to Excel utility on the Training Project. Open the spreadsheet produced and create some new Teams, Users and Databases.
Import the modified spreadsheet into the Training project, checking for any errors.
Use the database Rollback function to restore the project to the point immediately before the Export utility was used.
www.aveva.com
5 PML Encryption
This chapter describes how to create and use PDMS PML Encryption or Published PML. Various levels of encryption can be applied to any PML functions, forms, objects, and macros.
5.1 Overview of PML Encryption
PML is the AVEVA Programmable Macro Language. The details of the language may be found in the PDMS Software Customisation Guide and the PDMS Software Customisation Reference Manual, supplied with the product.
PML functions, objects, forms and macros may be encrypted using the tools described in this chapter. Once encrypted they may be used within PDMS but cannot easily be read.
Please note that the encryption used is of limited strength, and is not secure against all possible attacks.
Details of the encryptions used are described later.
Once a PML file has been encrypted, it is no longer possible to read or edit the file. The Published PML toolkit does not include a tool for un-encrypting files. It is good practise to ensure that a safe copy of the original file is retained, in case further modifications are required later.
5.2 PML Encryption Utility Program
The encryption utility program is a command window program designed to be included in the PML software development process.
5.2.1 Typical workflow
When undertaking PML encryption tasks the following workflow should be adhered to:
Ensure that a current backup of the source PML is available.
Copy the source folders to a new location.
Encrypt from the source location to the new location.
Check the encryption is successful and the files work in the expected manner.
Not all files within a PML folder hierarchy are always PML. Images, for example, should not be encrypted, but may need to be supplied with the encrypted versions of the PML.
Automating the encryption procedure via batch files, perl script, or a PML script will make it easier to create the encrypted PML files when the source PML is updated.5.2.2 Licensing
The pmlencrypt.exe utility program requires a PML Publisher licence in the license file (the feature name is VPD-PMLPUBLISHER). If this is not present in the license then the program will not run.
www.aveva.com
The form of the PML Encryption Utility Program can be seen by running pmlencrypt.exe without arguments (or with an invalid set of arguments). An output similar to that below is produced.
The command is of the form:
pmlencrypt [-rc4|-basic|-trivial|-none] [-buffer N] [-folder|-pmllib] from_path to_path
Where:
-rc4 uses 40-bit RC4 encryption from the Microsoft Base Cryptographic Provider (default).
-basic uses a simple low-security encryption algorithm.
-trivial uses a human-decipherable encryption scheme - for testing only.
-none no encryption, but can be used with -buffer N.
-buffer N causes the file to be retained in memory until a module switch once it has been read N times (the default is never).
-folder is used to encrypt ALL files from the folder from_path to to_path.
-pmllib is used to encrypt ALL .pmlobj .pmlfnc .pmlfrm and .pmlmac files from the folders in a PMLLIB-type folder structure beneath from_path to to_path.
from_path is the file or folder to be encrypted.
to_path is the output file or folder.
www.aveva.com
PML files are not required to have particular file extensions. PML2 functions, objects, forms and macros are normally stored in files with the extensions .pmlfnc, .pmlobj, .pmlfrm and .pmlmac respectively. However, other PML files such as those in the pdmsui folder of a PDMS installation do not have a file extension.
As any PML file (with or without a file extension) may be read with a $m command, care must be taken when choosing files to encrypt. Other files, such as icon images and configuration files cannot be used by PDMS when encrypted.
5.4.1 Single File
If neither of the –folder or –pmllib options are used the from_path and to_path arguments are taken to be single file-names or paths (which should not include embedded spaces). The to_path file is created or overwritten, as appropriate.
This option may be used whenever there is a single file to encrypt, and can also be useful within a script, where the file selection is handled by the script itself. No assumptions are made about file extensions.
5.4.2 All Files in a Folder
If the –folder option is used the from_path and to_path arguments are taken to be names or paths of folders (which should not include embedded spaces). All files in the from_path folder are encrypted into the to_path folder. The to_path folder is created, if required, and the files inside it are overwritten.
No file extension is required, so care must be taken not to encrypt non-PML files.
5.4.3 Files in a pmllib -like Folder Tree
If the –pmllib option is used the from_path and to_path arguments are taken to be names or paths of folders (which should not include embedded spaces). All folders beneath the from_path folder are scanned, and files with extensions .pmlfnc, .pmlobj, .pmlfrm or .pmlmac are encrypted to a matching structure constructed or overwritten beneath the to_path folder.
As this option is file-extension sensitive, it will not encrypt, or copy, image or other unrelated files in the hierarchy.
5.4.4 File/Folder paths
Care must be taken when the from_path and to_path arguments are given. The from path must precede the to_path, otherwise the wrong file may be overwritten.
The from_path and to_path arguments cannot be identical. This is to reduce the risk of accidental overwriting of the source-files. Embedded spaces are not supported in the paths.
5.5 Encryption Algorithms
There are four encryption options that use different encryption algorithms. The following sections describe the four options.
5.5.1 Encryption Type 0: No Encryption
Encryption Type 0 (No Encryption) adds a standard Published PML header to the file, i.e. --<000>-- Published PML 12.0 >--, but does not otherwise encrypt the file.
It can be selected by choosing the –none option in the encryption call.
www.aveva.com
Encryption Type 1 (Trivial Encryption) is designed for testing purposes only. It provides no security, as the lines can be read backwards. It is used to establish that the encryption system is functioning correctly and that an incompatible version of PDMS has not been installed.
It can be selected by choosing the –trivial option in the encryption call.
5.5.3 Encryption Type 2: Basic Encryption
Encryption Type 2 (Basic Encryption) is an alternative simple encryption algorithm which is implemented directly and does not rely on external libraries.
It can be selected by choosing the –basic option in the encryption call.
5.5.4 Encryption Type 3: RC4 Encryption
Encryption Type 3 (RC4 Encryption) is the recommended and default option.
This encryption uses the Microsoft Base Cryptographic Provider, which is included in Windows 2000, Windows XP, and Windows 7 operating systems as well as Microsoft® Internet Explorer version 3.0 or later.
It is anticipated that all PDMS compatible computers will include the libraries required for this algorithm.
40-bit keys are used to operate within limits imposed by (historic) limitations of encryption technology.
It can be selected by choosing the –rc4 option in the encryption call.
Although this is the most robust encryption algorithm provided, it is still of limited strength and is not secure against all possible attacks.5.6 Encrypting PML Files – A Worked Example
In this worked example supplied PML files will be encrypted using various options.
5.6.1 Supplied Files
The pmlencrypt.exe by default is installed in the C:\AVEVA\Plant\Manage\PMLPublisher1.1 folder.
The following are the simple PML files that will be used for the encryption. The Trainer will provide these files by copying them from the Training Setup. Typically C:\AVEVA\Plant\Training12.1.1\Training\testencrypt. The files are as follows:
C:\testencrypt\pmllib_original\forms\hello.pmlfrm setup form !!hello
Title ‘My Form Title’
Paragraph .Message text ‘Hello world’
button .bye ‘Goodbye’ OK exit
C:\testencrypt\pmllib-original\functions\area.pmlfnc define function !!area(!Radius is REAL) is REAL
!CircleArea = !Radius.Power(2) * 3.142 return !CircleArea
endfunction
www.aveva.com
$p Site /ENCRYPT-SITE does not exist return
The PML files should be stored in the correct PML directory structure.
www.aveva.com
It is recommended that a batch file be created to encrypt the PML files. In this example a simple batch file will be written to test each option.
In a suitable text editor open the batch file, encrypt.bat, in the folder C:\testencrypt most of the lines are commented out using rem with the exception of the second to last line which would display help.
Keep the file open for editing. Ensure all of the sub-folders in the C:\testencrypt\pmllib-encrypt folder are empty.
5.6.4 Testing the None Option
The first test uses the –none option on the area.pmlfnc file to see if the encryption process is working. The encrypt batch file needs to be edited (remove ‘rem’) to allow this line of the file to be run. The batch file should look like this:
Run the batch file by locating encrypt.bat with Windows Explorer then double clicking on it. A cmd window will be displayed. To check the result, navigate to the C:\testencrypt\pmllib-encrypt\functions folder and edit the area.pmlfnc. The function should look like this:
The file is not encrypted but a header is added to the macro.
www.aveva.com
Edit encrypt.bat and enter rem at the start of the line containing the none option. Remove the rem from the start of the line containing the trivial option. The batch file should look like this:
Save the file and double click on it to run the encryption. The file, hello.pmlfrm, has been encrypted using the –trivial option.
Navigate to the C:\testencrypt\pmllib-encrypt\forms folder and edit the hello.pmlfrm. The function should look like this:
Note that the file is readable backwards, i.e. mrof putes is setup form.
5.6.6 Encrypting Multiple Files
All files with valid pml extensions can be encrypted in one command using the –pmllib option.
Edit the encrypt .bat file by entering rem at the start of the line containing the trivial option. Remove the rem from the start of the line containing the rc4 pmllib option. The batch file should look like this:
Save the file and double click on it to run the encryption. Navigate to each of the sub-folders of pmllib-encrypt and note that all pml files have been encrypted with the exception of NZONE as this does not have a valid pml file extension.
All Files without a valid pml extension can be encrypted in one command using the –folder option, however, care must be taken using this option as some files may not be pml macros.
www.aveva.com
rem from the start of the line containing the rc4 folder option. The batch file should look like this:
Save the file and double click on it to run the encryption. Navigate to the macro sub-folder of pmllib-encrypt and note that the file NZONE has now been encrypted.
5.6.7 Testing Encrypted Macros
When PDMS recognises an encrypted macro it is decrypted in memory as it is used. In this section the encrypted macros will be tested. In order to test the encrypted macros the pointer to pmllib must be changed to point to a multi path.
Edit the file evars.bat. This batch file can be found in the %PDMSEXE% directory typically C:\AVEVA\Plant\PDMS12.1.SP2. Close to the bottom of the file add the line:
set pmllib=C:\testencrypt\pmllib-encrypt %pmllib%
Make sure there is a Blank Line at the Bottom of the file.
Save the file and close the editor. Enter PDMS using the following options:
Project Training, Username A.PIPER, Password A, MDB /A-PIPING, Module Design
Ensure DAC is turned off.5.6.7.1 Checking the pmllib Path
The environment variable pmllib should now be set to a multi-path that includes the C:\testencrypt folder.
Open the Command Window and enter Q EVAR PMLLIB.
The file pml.index needs to be updated to include the new files in the extended path.
Enter PML REHASH ALL in the Command Window to regenerate the file. If further files are encrypted the file should be refreshed using this command.
www.aveva.com
The area function returns the area of a circle. In the Command Window enter !area = !!area(100). The function calculates the area of a circle with 100mm diameter.
Enter q var !area in the Command Window to find the answer stored in variable !area
5.6.7.3 Hello Form
PML forms are displayed using the show command. Enter show !!hello in the Command Window to show the Hello form.
5.6.7.4 Life Object
A method of an object may return a result into a member of the object using the return command.
Enter !Marvin = object LIFE() in the Command Window.
The method .Life() is called automatically and the value
!marvin is 42.
Enter !Number = !Marvin.Answer() in the Command Window.
Enter q var !Number in the Command Window.
!Number is set to the value 42 because no values were specified. The value of the variable Number may be changed. Enter the following in the Command Window:
!Marvin.Answer(50)
!Number = !Marvin.Answer() q var !Number
5.6.7.5 Running the pml macros
Macros are executed using the $m/ syntax in the Command Window. Enter the following in the Command Window:
$m/C:\testencrypt\pmllib-encrypt\macros\newsite.pmlmac
$m/C:\testencrypt\pmllib-encrypt\macros\NZONE
www.aveva.com
The newsite.pmlmac macro creates a site named ENCRYPT-SITE.
The NZONE macro creates a Zone under the new site named ENCRYPT-ZONE.
5.7 Buffering Encrypted Files
Reading an encrypted pml file takes longer than reading a plain-text version. In some circumstances PML files may be re-read many times during a session, thus encrypting files may have some impact on performance.
The command PML STATISTICS displays information on the numbers of times each file has been read, together with some additional information useful to AVEVA when testing the Published PML functionality.
In order to reduce the time taken to re-read the files, Published PML files may contain a buffering directive in the header-line, i.e. the first line in the file. If a dash and a number are included directly after the three-digit encryption algorithm id, then PDMS will retain the file in memory indefinitely once it has been read the specified number of times.
Heavily used files may be edited to add buffering to the header by hand. For example:
--<004-5>-- Published PML 1.1 >--
Alternatively, the n option, where n is the number of times the file is to be read before buffering, of pmlencrypt.exe may be used.
For example:
C:\AVEVA\pmlencrypt -rc4 –buffer 5 %from%\functions\area.pmlfnc %to%\functions\area.pmlfnc.
www.aveva.com
is little benefit in buffering these files. Using a value of 5 will avoid that, but will benefit all heavily used files.
If a PML file that is being actively developed has a header including buffering, it will not be re-read as often as usual.
To force all buffered files to be cleared from memory, if they are not in current use, the commands PML REHASH or PML INDEX may be used or a module switch performed.
5.8 Editing Published PML Files
Most changes made to an encrypted PML file will make it unusable, i.e. PDMS will report a corrupt file if attempted, however, there are a few exceptions:
As noted in the previous section, a buffering value may be added or changed in the Published PML header-line. For example:
--<004>-- Published PML 1.1 >-- may be changed to --<004-5>-- Published PML 1.1 >-- Adding a buffering value of 5.
The second line of rc4 or basic encrypted files may be edited to report a different error or message.
For example:
--<003>-- Published PML 1.1 >--
return error 99 'This file is not readable by this version of PDMS' $** 9ad7b51fc44384a8601979728b185f52
may be changed to
--<003>-- Published PML 1.1 >--
return error 66 'You need a PDMS patch – ring Ian on extension 6655' $** 9ad7b51fc44384a8601979728b185f52
Lines in trivial encrypted or un-encrypted files may be changed.
5.9 Using the $R Command
If an attempt to display or record encrypted PML using the $R commands is made, all lines are replaced by the text <hidden>. Error messages and trace-backs will include function names, but not the text of each line.
The only circumstance in which hidden lines can become visible is during a macro which includes a module-switch. After a module switch, any remaining lines in that macro may be traceable.
5.10 Troubleshooting
PDMS will issue an error if any of the following occurs:
Attempting to read an encrypted PML file in an incompatible version of PDMS.
Attempting to read an encrypted file that has become corrupted (e.g. editing encrypted text).
Attepting to read files encrypted with algorithms added in future versions of pmlencrypt.exe.
Attempting to read an rc4 encrypted file on a computer without the Microsoft Base Cryptographic Provider installed.
www.aveva.com
www.aveva.com
6 Intellectual Property Rights Database Protection
PDMS enables strict Intellectual Property Rights (IPR) Protection to be applied at database level, allowing a project administrator to restrict the ability to extract data held within a database.
6.1 IPR Protection Overview
Protected databases are marked as uniquely belonging to the project such that restricted users cannot copy data from that database into another project, even through a physical copy of the database file.
Protected databases are marked as uniquely belonging to the project such that restricted users cannot copy data from that database into another project, even through a physical copy of the database file.