AVEVA Plant (12 Series) PML Encryption LU a ~ oO oO < < < a =AVEVA Plant (12 Series) PML EncryptionAVEVA Plant (12 Series) PML Enoryption Revision Log 03/08/07 Updates All headings containing updated or new material will be highlighted. Suggestion / Problems If you have a suggestion about this manual or the system to which it refers please report it to the AVEVA Group Solutions Centre at gsc@aveva.com This manual provides documentation relating to products to which you may not have access or which may not be licensed to you. For further information on which products are licensed to you please refer to your licence conditions. Visit our website at http://www.aveva.com Disclaimer Information of a technical nature, and particulars of the product and its use, is given by AVEVA Solutions Ltd and its subsidiaries without warranty. AVEVA Solutions Ltd. and its subsidiaries disclaim any and all warranties and conditions, expressed or implied, to the fullest extent permitted by law. Neither the author nor AVEVA Solutions Ltd or any of its subsidiaries shall be liable to any person or entity for any actions, claims, loss or damage arising from the use or possession of any information, particulars or errors in this publication, or any incorrect use of the product, whatsoever. Trademarks AVEVA and Tribon are registered trademarks of AVEVA Solutions Ltd or its subsidiaries. Unauthorised use of the AVEVA or Tribon trademarks is strictly forbidden. AVEVA product names are trademarks or registered trademarks of AVEVA Solutions Ltd or its subsidiaries, registered in the UK, Europe and other countries (worldwide). The copyright, trademark rights or other intellectual property rights in any other product, its name or logo belongs to its respective owner.AVEVA Plant (12 Series) PML Encryption Copyright Copyright and all other intellectual property rights in this manual and the associated software, and every part of it (including source code, object code, any data contained in it, the manual and any other documentation supplied with it) belongs to AVEVA Solutions Ltd. or its subsidiaries. All other rights are reserved to AVEVA Solutions Ltd and its subsidiaries. The information contained in this document is commercially sensitive, and shall not be copied, reproduced, stored in a retrieval system, or transmitted without the prior written permission of AVEVA Solutions Limited. Where such permission is granted, it expressly requires that this Disclaimer and Copyright notice is prominently displayed at the beginning of every copy that is made. ‘The manual and associated documentation may not be adapted, reproduced, or copied in any material or electronic form without the prior written permission of AVEVA Solutions Ltd. The user may also not reverse engineer, decompile, copy or adapt the associated software. Neither the whole nor part of the product described in this publication may be incorporated into any third-party software, product, machine or system without the prior written permission of AVEVA Solutions Limited or save as’ permitted by law. Any such unauthorised action is strictly prohibited and may give rise to civil liabilities and criminal prosecution. The AVEVA products described in this guide are to be installed and operated strictly in accordance with the terms and conditions of the respective licence agreements, and in accordance with the relevant User Documentation. Unauthorised or unlicensed use of the product is strictly prohibited, Printed by AVEVA Solutions on 24 August 2007 © AVEVA Solutions and its subsidiaries 2001 — 2007 AVEVA Solutions Ltd, High Cross, Madingley Road, Cambridge, CB3 OHB, United KingdomContents 1 .4 Using the PML Encryption Utility Program 2.5 Choosing Files ... 25.4 je fil... 2.5.2 Allfiles in a fOIMEF .nnneseere 2.5.3 Files ina pmilib-like folder tree, 25.4 File/Folder paths... 2.6 Encryption Files / Directory Structure. 26.1 — Example PML Files... 26.2 Directory Structure... 2.7 Encryption Algorithms 2.7.1. Encryption Type 0: No Enoryption, 2.7.2 Encryption Type 1: Trivial Encryption 2.7.3 Encryption Type 2: Basic Encryption 2.74 Encryption Type 3: RC4 Encryption, Exercise 4 — Encrypting Single Files. 28 — Encrypting Multiple Files Exercise 2 - Encrypting Single Files. 3 _ Testing Encrypted Macro: 3.4. Modification to pm 3.2 Access to PDMS. 3.3. Checking the pmilib.. 3.4 Testing the example trai 3.4.1. Area function. 3.4.2 Hello Form 3.4.3 Life Object 3.4.4 Running a macro.... Exercise 3 — Testing the Encrypted macros 4 Encryption Miscellaneous Commands. 4A Buffering wenn 42 Editing Published PML File: 43 Using the $R Command .. 4.4 Troubleshooting...AVEVA Plant (12 Series) PML EncryptionCHAPTER 1 ieee! a The following Training Manual describes how to create and use PDMS PML Encryption or Published PML. PML is the AVEVA Programmable Macro Language. You can find details of the language in the VANTAGE Plant Design Software Customisation Guide and the VANTAGE Plant Design Software Customisation Reference Manual PML functions, objects forms and macros may be encrypted using the tools described in this manual, and once encrypted may be used within PDMS but may not 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 desoribed later. (Once a PML file has been encrypted, it can no longer be read or edited. When you publish a file make sure that you retain a safe copy of the original file, in case you want to make further modifications to it later. ‘The Published PML toolkit does not include a decryptor for encrypted files. 1.2 Objectives ‘At the end of this training, you will have a General Overview PDMS PML Encryption or Published PML. 1.3 Prerequisites The Trainees must have completed the Admin or PML Training Course and be familiar with Microsoft Windows 1.4 Course Structure Training will consist of oral and visual presentations, demonstrations and set exercises. Each workstation will have a training project, populated with model objects. This will be used by the trainees to practice their methods, and complete the set exercises. Certain text styles are used to indicate special situations throughout this document, here is a summary: ‘Menu pull downs and button press actions. Are indicated by bold dark turquoise text. Information the user has to Key-in Will be red and bold. Annotation for trainees benefit @® Additional information £1) Refer to other documentation ‘System prompts should be bold and italic in inverted commas i.e. ‘Choose function’ Example files or inputs will be in the courier new font, colours and styles used as before.AVEVA Plant (12 Series) PML EncryptionCHAPTER 2 aa The encryption utility program is a command-line program designed to be included in your PML software development process. Ponerinae 2.4__Typical workflow © Ensure that you have a current backup of the source PML. ® No too! is supplied to decrypt an encrypted file, so it is very important that you keep good backups, in case you overwrite the source PML with an encrypted version. ‘© Copy the source folders to a new location ® 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. '* Encrypt from the source location to the new location. @ Consider writing a batch file, a perl script, or a PML script to automate this procedure for your particular environment, to make it easy £0 create the encrypted PML environment correctly each time the source PML is updated. 2.2 Licensing ‘The pmiencrypt.exe utility program requires a PML Publisher licence in your license file (the feature name is \VPD-PMLPUBLISHER). If this is not present then the program will not run. 2.3 Help If pmiencryptexe is run without arguments, or with an invalid set of arguments, then @ summary similar to this is output. The options are explained further in the following sections. PDMS PML Encryption User Guide 2-1 Version 11.5SP2 2.4 _Using the PML Encryption Utility Program. pmiencrypt [-re4]-basic|-trivial|-none] [-buffer N] [folder|-pmllib] from_path to_path © 104 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 -butfer 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)AVEVA Plant (12 Series) PML Encryption + folder is used to encrypt ALL files from the folder from_path to to_path © -pmili is used to encrypt ALL .pmlobj .pmifne .pmifrm and .pmimac files from the folders in a PMLLIB-lype 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 2.5__Choosing Files PML files are not required to have particular file extensions, PML2 Functions, Objects, Forms and Macros are normally stored in files with the extensions .pmifnc, .pmlobj, .pmifrm and .pmimac respectively, but other PML files, such as those in the pdmsui folder of a PDMS installation have no extension at all, and a PML file with any extension may be read with a $m command. You must therefore be careful, when choosing files to encrypt, that you only encrypt PML files. Other files, such as icon images and configuration files cannot be used by PDMS when encrypted. 2.5.4 Single file If neither of the folder or -pmilib 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 you have a single file to encrypt, and can also be useful within a script, where the fle selection is handled by the script itsett. No assumptions are made about fle extensions, 2.5.2_Allfiles 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 this option is suitable for folders in the %PDMSUI% hierarchy, but you must be careful not to encrypt non-PML files. 2.5.3 Files in a pmillib -like folder tree IF the =pmilib option is used the from_path and to_path arguments are taken fo 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 .pmifnc, .pmlobj, .pmifrm or pmimac 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 image or other unrelated files in the hierarchy — but it will not copy them for you either. 2.5.4 File/Folder paths Be careful when you give the from_path and to_path arguments that they are in that order — otherwise you may overwrite the wrong file. 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. 10AVEVA Plant (12 Series) PML Encryption 2.6 Encryption Files / Directory Structure 2.6.1_Example PML Files In this section we will encrypt the following files which your trainer can provide: - C:testencrypt\pmilib\forms\hello.pmifrm setup form !thello Title ‘My Form Title’ Paragraph .Message text ‘Hello world’ button .bye ‘Goodbye’ OK exit C:Mtestencryptipmillib\funtions\area.pmifne define function !larea(!Radius is REAL) is REAL ICircleArea = |Radius.Power(2) * 3.142 return !CircleArea endfunction C:\testencryptipmlliblobjectsllife.pmlobj define object LIFE member -Answer is REAL ‘endobject define method .Life() IThis.Answer = 42 endmethod define method -Answer() is REAL turn !This.Answer ‘endmethod define method Answer(!Value is REAL) Ithis.Answer = !Value ‘endmethod C:\testencryptipmilib\macrosinewsite.pmimac new site JENCRYPT-SITE. handle(41,12) $p site JENCRYPT-SITE exits DELETE SITE return, endhandle C:testencrypt\pmilib\macros\NZONE JENCRYPT-SITE handle(2,109) $p Site /ENCRYPT-SITE does not exist return endhandle new zone /ENCRYPT-ZONE handie(41,12) $p site IENCRYPT-ZONE exits DELETE ZONE return 4AVEVA Plant (12 Series) PML Encryption endhandle @® Note: Files should exist or be created in the correct directory structure, 2.6.2 Directory Structure ‘The PML files should be stored in the correct PML Directory Structure ecvestencot iib-rgnal prone forms funetons objects macros forms functions objects nacros halle pram arenpmie ——-Mepmiat)—_newsho pnimac zone Original Macro Library Encrypted Macro Library The directory Structure is created using standard windows commands ee eee ostne Broome Srnec mL rorureeny THONG A tena File > New > Folder on a suitable window ® Your trainer will provide the pml macros in the pmllib-original folder 2.7_ Encryption Algorithms There are four possible encryption options as listed below we will investigate each option to save on typing and to avoid errors itis recommended that a batch fle is created using a suitable editor. 2.7.1 Encryption Type 0: No Encryption Encryption Type 0 (No Encryption) adds a standard Published PML header to the file, but does not otherwise encrypt the file. It can be selected by the ~none option. Create a batch file and enter the following lines (all one line): - C:\AVEVAIPMLEncryption11.5.SP2\pmlencrypt___-none C:\testencrypt\pmllib- original\funtions\area.pmifne C:\testencryptipmilib-encryptifuntions\area.pmifne. PAUSE 12AVEVA Plant (12 Series) PML Encryption fae ta fort Yor tee ot example of yee Ji pateacryee (ofca|-bastel-erfviall-none) C-btFar ni) (-folder|-patT4b) frem-path to-path J aveva\enutncrygt ont, s2P2\pelenceypt none _ ci \eervencrype\yatT4b-arSgonal\furefons\area, anne ESE GEGMBCeteh pee ens ea ene SPEEDS ee Save the file toa suitable name File > Save - enorypt.bat Execute the batch file by double clicking it in windows: - ‘The PML Encryption program will display the following: : E a PEE VSI a tte oe © There shoutd be no errors Navigate to the destination directory end edit the area function encryptifuntions\area.pmifnc” eee oe File Edt Format View Help --<000>-- published PML 11.5.5P2 (sep 6 2006) >-- define function !!areaC!Radius is REAL) is REAL Icirclearea = !radius.Power(2) * 3.142 return !Circlearea endfunct ten ‘As you can see from the above example the file is not encrypted but a header is added to the macro. 2.1.2 _Encryption Type 1: Trivial Encryption 13AVEVA Plant (12 Series) PML Enryption Encryption Type 1 (Trivial Encryption) is designed for testing purposes only. It provides no security, as you ‘can read the lines slowly (backwards), but you can use it to check that the decryption system is functioning correctly, and that, for example, an incompatible version of PDMS has not been installed. It can be selected by the -trivial option. Modify the batch file as shown and test the encryption as before: - C:\AVEVA\PMLEncryption1.5.SP2\pmlencrypt -trivialC:\testencryptipmillib- original\funtions\area.pmifnc C:\testencryptipmilib-encrypt\funtions\area.pmiine. PAUSE Cee Fle eat Fost View Hab ---- ue 31 suidan! Caerait noieenut enifed 32 38(Fe, Sudan! eraeter de! fnottenuFdne In the example above the line: noitcnufdne is endfunction when read backwards. 2.7.3 _Eneryption Type 2: Basic Encryption Encryption Type 2 (Basic Encryption) is an alternative simple encryption scheme which is implemented directly, and does not rely on external libraries. It can be selected by the -basic option. Modify the batch file as shown and test the encryption as before: - \VEVA\PMLEncryption11.5.SP2\pmlencrypt -basic_C:\testencrypt\pmllib- original\funtions\area.pmifne C:\testencryptipmilib-encryptifuntions\area.pmifine PAUSE BB. area, pmifnc -Notepad Fle Eat Feet ew Heb }--— published pm 1.5.52 (Sep, 6 2006) >-— return error. 90. "this file’ 42 nat readable by this version of PONS* Is*tadoensa 6243751 b4dan2doss9q06d76. Dente fkon7Sv7yP32H7] s4pkzuLhourd Seat eeicaseat FS Saag cata me aca mentees Sem Hybubbusoupjieyjexciw7burquiasziwburgr). This algorithm is less secure than the RC4 algorithm, and is not recommended for general use. 2.1.4 Eneryption Type 3: RC4 Encryption Encryption Type 3 (RC4 Encryption) is the recommended and default option. It can also be selected by the — re4 option. Modify the batch file as shown and test the encryption as before: - \VEVA\PMLEncryption11.5.SP2\pmiencrypt red. _—_C::\testencryptipmilib- original\funtions\area.pmifnc C:\testencryptipmilib-encryptifuntions\area.pmifne. PAUSE 14AVEVA Plant (12 Series) PML Encryption eerie It is implemented using the Microsoft Base Cryptographic Provider, which is included in, among other ‘operating systems, Windows 2000 and Windows XP. It is also included with Microsoft® Internet Explorer version 3.0 or later. 40-bit keys are used, to operate within limits imposed at one stage on exports of encryption technology. It is therefore expected that all PDMS comps algorithm. le computers will include the libraries required for this @ Please note that even this encryption is of limited strength, and is not secure against all possible attacks Ban mene a ee eae Using the above example investigate the various encryption options 15AVEVA Plant (12 Series) PML Enoryption 2.8 Encrypting Multiple Files All files with valid pmi extensions can be encrypted in one command using the ~pmilib option for example: - C:AVEVAIPMLEncryption11.5.SP2\pmlencrypt -re4 -pmilib C:\testencrypt\pmilib-original C:ltestencrypt\pmilib-encrypt In our example the only file that would not be encrypted would be NZONE as this file does not have a valid pmi extension. All Files without a valid pml extension can be encrypted in one command using the -folder option for example: - C:\AVEVAIPMLEncryption11.5.SP2\pmlencrypt -rc4 -folder C:\testencryptipmllib-originallmacros C:itestencrypt\pmilib-encryptimacros, Care must be taken using this option and some file may not be pmi macros. Barreca eure Using the above example encrypt all the macros in the example directory C:\testencryptipmili 16CHAPTER 3 ECan cuca ‘When PDMS recognises an encrypted macro it is decrypted in memory as itis used. In this chapter we will test the use of encrypted macros, 3.1__Modification to pmillib Ii order to test the encrypted macros the pointer to pmilib must be changed to point to a multi path. Edit the PDMS batch file and locate the line: - call "%pdms_installed_dir%\evars.bat" "%epdms_i add the following file directly after this line: - ‘sot pmilib=C:\testencryptipmilib-encrypt %pmllib% Peete cra) Fle Edt Format View Hep cal] "Xpdms_installed_dirx\evars. bat" "Xpdms_installed_dirx” set pm11ib=c:\testencrypt\pmI1b-encrypt xpm11ib% 3.2__Access to PDMS. Enter PDMS SAM (MP) project, Start > All Programs > AVEVA > PDMS 12 > Run PDMS or user the Icon provided by your Trainer. Project SAM (IMP) Username SYSTEM Password XXXXXX MDS PIPE Module DESIGN 7AVEVA Plant - PML Encryption 3.3 _Checking the pmilib “pmilib” should be set to a multi path this can be checked using the command q evar pmllib (Open a command window: - Display > Command Line Type the command: - evar pmllib “pmilib” should look something like this: - evar pri Environment veriable PMILLIG:C:Yestencryptpmilo-encrypt CAAVEVAIPdnst 2 pia If you look in the encryption directory C:Mtestencryptipmllib-encrypt it should now have an index created called pml.index. Fh Ea Yaw Fovotes Tes tp Om BF Pave prion Dison we abe an ee ~ esa an 3 ‘Dizon one @ put votatee ‘ison ose ppooranlg san 1828 If no "pml.index’ exists then one is created for you, once one exists it needs to be updated using the ‘command *pmi rehash all” Ifyou encrypt any more files you must delete the index and re-enter PDMS or issue the command:- pmi rehash all 18AVEVA Plant - PML Eneryption 3.4 Testing the example training macros Once ail the pmI macros have been encrypted they can be tested as follows:- 3.4.1 Area function The area function returns the area of a circle Typical use could be: - Jarea = !area(100) q var larea 3.4.2 Hello Form “pmi forms” are shown using the show command for example: - show !Ithello 1A De The following is the typical use of an object: - 3.4.3 _Life Object ‘A method of an object may return a result into a member of the object using the return command, IMarvin = object LIFE() ‘The method .Life() is called automatically and the value !marvin is 42 !Number = !Mar var Number Answer() !Number is set to the value 42 because no values were specified You can change the value of Number IMarvin.Answer(50) !Number = !Marvin.Answer() var Number aor cept FED Mer in foe ‘Naess ame 19AVEVA Plant - PML Eneryption 3.4.4 Running a macro ‘Macros are executed using the $m syntax for example: - $miC:\testencrypt\pmillib-encryptimacros\newsite.pmimac $miC:\testencrypt\pmllib-encryptimacros\NZONE SiC testencryptioniis-encryptimacrosinewste,pmiac SiC testencryptpnib-encryptimacras\NZONE The above macros will create items in the database so you must have write access to a design database, Exercise 3 ~ Testing the Encrypted macros Using the above example test that the Encrypted Macros still work as expected in PDMS. 20CHAPTER 4 PW eeu ek emt The following commands can also be used. 4A _ Buffering Decrypting @ PML file takes longer than reading a plain-text version, and in some circumstances PML files may be re-read many times during a session. Anew command PML STATISTICS displays information on the numbers of times each file has been read and some extra information useful to AVEVA when testing the Published PML facilities. PML STATISTICS Buffers Opens Bundles Lines Seconds File/description 9 0 9 9 0.000 SPDOIT Input iene sez) 0.000 %POMSDFLTS%/DES-INIT-MAC. 1010 271 274 0.000 %POMSDFLTS%icom-format-dflts.pmidat 4 4 508 508 0.010 %PDMSUI%/CLIB/FILES/BTMLIN 1 1 87 87 0.000 %PDMSUI%/CLIB/FILES/DDFDATA 101 172 172 0.010 %PDMSUI%/CLIB/FILES/DELEMTYPES 104 421 124 0.010 %PDMSUI%/CLIB/FILES/EDREP In order to reduce the time taken to re-read the files Published PML files may contain a buffering directive in the header-line (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 that many times. ‘You may wish to edit heavily used files to add buffering to the header by hand, or may use the -buffer 5 option of pmiencrypt.exe to include a “buffer after five reads” tag in each file encrypted. A value of five is a good number to start with --<003-5>- Published PML 11.5.SP1 (Jul 6 2006) >-- Many files are read precisely once during module start up — there is a value of five will avoid that, but apply to all heavily used files. ttle benefit in buffering those files, and Ifa fle you are actively developing has a header including buffering, it will not be re-read as often as you are used to, To force all buffered files to be cleared from memory if they are not in current use you can issue the PML REHASH or PML INDEX commands, or switch modules, 4.2 _ Editing Published PML Files Most changes made fo an encrypted PML file will make it unusable (POMS will report a corrupt file if you try) but there are a few exceptions: * You may add or change a buffering-value in the Published PML header-line, eg: --<003>— Published PML 11.5.SP1 (Jul 6 2006) > may be changed to --<003-5>- Published PML 11.5.SP1 (Jul 6 2006) > Adding a buffering-value of 5 (see above for details) 24AVEVA Plant - PML Encryption + You may change the 2nd line of RC4 or Basic encrypted files to report a different error or meesage, eg --<003>-- Published PML 11.5.SP4 (Jul 6 2006) >-- retum error 99 "This file is not readable by this version of PDMS* $"* Sad7b511fc44384a86019797286185152 may be changed to --<003>-- Published PML 11.5.SP1 (Jul 6 2006) > retum error 66 'You need a PDMS patch ~ ring lan on extension 6655! $** 9ad7b51fo44384a86019797285185(52 ‘You may changes lines within Trival on unencrypted files. 4.3 Using the $R Command IF you attempt to display or record enorypted PML using the $R commands, you will find that all lines are replaced by the text . 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. This may change in a future release. 44 Troubleshooting PDMS will issue an error if any of the following occurs: You try to read an encrypted PML file in an incompatible version of PDMS. You try to read an encrypted file that has become corrupted (for example by editing the encrypted text) You try to read files encrypted with algorithms added in future versions of pmiencrypt.exe You try to read an RC4-encrypted file on a computer without the Microsoft Base Cryptographic Provider installed (this is not expected ever to occur). 22