1. technology and computing
2. software

What is wzshSDK?
wzshSDK is a generic script program encryption and license enabling software. It
encrypts/protects your Bourne Shell/Korn Shell/bash/Ruby scripts so that they can’t be
inspected and/or modified by other people.
Yet, it provides you the power of putting license protection for your script so you can have
the best control on who can run your protected scripts and on which platform.
wzshSDK is designed to be multi-vendor oriented: Encrypted programs have the vendor's
signature built-in, which means vendor A can generate licenses for its own programs but not
for vendor B's programs.
Compared with other script encryption software available today, wzshSDK provides much
better encryption/protection for your script programs: WZSH uses true, standard based
algorithm for better encryption; WZSH uses a specific technique to prevent original script to
be captured by simply running a "temp watch" program; and WZSH uses a specifically
designed certification mechanism to effectively prevent hacker to use a fake interpreter to
capture your original script. For more detailed comparison, please look at "How does
wzshSDK compare with other similar software?" at end of this readme file.
However, unlike a script encryption software vendor once claimed, there is no way to make
runnable encrypted programs absolutely secure (for example, a person who can change the
UNIX kernel will be able to capture your program in unprotected form when he can run your
encrypted program on his modified kernel, no matter how the program was encrypted). You
should not just use the tool but also use the law to protect your intellectual properties. That
said, WZIS has made great efforts to make the protection of your program strong enough to
prevent it being hacked by most people.
It's very important for you to read all contents in this file to get a more complete picture on
how to setup and use the software properly; otherwise, the secure protection for your
scripts could easily get compromised.
How to setup and use wzshSDK package:
The wzshSDK package includes following programs:
1. /usr/local/bin/wzshLic
2. /usr/local/bin/wzshKey
3. /usr/local/bin/wzshsec
4. /usr/local/bin/wzshcert
5. /usr/local/bin/wzsh
6. /usr/local/bin/wzshrun
7. /usr/local/bin/wzshSDKId
8. /usr/local/bin/wzappkey
9. /usr/local/bin/gwzsh
a. /usr/local/bin/wzshVID
b. /usr/local/bin/wzshappID
To setup the package, first run the wzshSDK.wzpkg-Version_OSname package file on your
machine, this will automatically install the wzshSDK software. To request for a production
license, run the wzshSDKId program to get the Instance ID, send it together with your official
company name to sales @ wziss . com with email subject "Buy wzshSDK License"; Or for a
common DEMO license, send an email with subject "wzshSDK Demo license required" and
state your company name.
When you receive the license, save the license string in /etc/wzshSDK.lic file, and
immediately setup a password for the package by running:
/usr/local/bin/wzappkey -p wzshSDK
And you will be asked for the 32-character HEX key that comes together with your license.
It's very important to make your wzshSDK password and the 32-character HEX key securely
protected. Knowing one of them, it's possible for a person to generate certificates for some
fake interpreters to capture the decrypted script programs you encrypted using the same
KeySN.
To encrypt a need-to-be-protected program, run
WZSH_PKG=PKG_NAME wzshsec [-l] [-c] the-original-program ShellType > protectedprogram
When -l option is used, the result program is license protected, which means a user will
need a license to run the program. (With a DEMO wzshSDK license, you can only generate
an encrypted program with license enabled.) When -c option is used, the interpreter for the
program needs be certified and the certificate will be checked first before starting to run the
encrypted program. Note: certificate checking will provide better protection for your
program.
The protected-program contains your VendorID and the current KeySN.
By using same PKG_NAME for a group of scripts, you only need to generate license for any
one of the scripts, and that license will cover all the scripts in the same PKG_NAME group.
For standalone script, you should use 0 as the PKG_NAME.
For a machine to be able to run WZSH protected programs, the machine need to have WZSH
runtime package wzshRUN (wzshSDK is a superset of wzshRUN; On machine with wzshSDK
installed, you must not install wzshRUN) for that platform installed and a proper license for
the protected program (if it's generated by wzshsec with -l option) available under
/usr/local/etc/wzshapp.licd/
directory.
To generate a license for a protected program, run
/usr/local/bin/wzshLic
to see the usage of the program. The generated license need be saved under
/usr/local/etc/wzshapp.licd/
on the machine that the protected program will be running on.
The license has a format like:
PKG_ID LVYYYYMMDD:OS:HostName:VendorID:KeyString
Here, PKG_ID is the CRC number of the package name the license is for. In encrypted script,
PKG_ID is recorded at position 56, and can be retrieved by
dd if=EncryptedScript bs=1 skip=56 count=8
L is license type (P for permanent; Y for yearly DEMO license; H for half year DEMO license;
Q for 3-month DEMO license and M for monthly DEMO license). V is the license version
number. YYYYMMDD is the date the license generated. OS is the OS type the license is for;
VendorID is a signature of the vendor who generated the license. (wzshLic will check the
encrypted program to make sure the program has the same VendorID signature, so that to
prevent vendor A to generate license for vendor B's program.)
Permanent license is OS type (when "UNIX" is not used as OS-Type) and machine name
dependent; DEMO license is OS type dependent but not machine dependent.
In addition to the program license, for a machine to be able to run a protected script
program with certificate check enabled, the interpreter program on the machine for the
script language must be certified by the vendor who created the protected script program
using the same KeySN registered in the protected script.
To generate a certificate for a version of interpreter, run
wzshcert the-path-of-the-interpreter program-image-to-be-certified
The wzshSDK password is required before it can generate a valid certificate.
You can generate certificates for Linux interpreters even on Solaris sparc machine, for
example, if you want to certify the /bin/bash of a version of Linux, copy the program image
to your Solaris sparc machine with wzshSDK package setup, put it under /tmp as bash, run
/usr/local/bin/wzshcert /bin/bash /tmp/bash
here, you will notice that the-path-of-the-interpreter argument is just a path name, no
actual file is needed. The actual content used for generating certificate comes from the file
specified by the program-image-to-be-certified argument.
A certificate has a format of following:
CertKey:Cksum:VendorID:KeySN:Path
The following is a certificate example:
5gGMOoT0aZjyT/cEG5gpR1:2ea5e67e:451c1816:00a1:/bin/sh
On the users' machine, the certificate has to be put under
/usr/local/etc/wzcert/
to take effect.
When you run wzshsec to encrypt a script or run wzshcert to generate a certificate, you can
set the "KeySN" environment variable to a 4 hexdigit number that is not greater than the
current wzshSDK's KeySN recorded in
/usr/local/etc/wzapp.ksn
file to let wzshsec or wzshcert uses the KeySN you specified. Otherwise, they will get and
use the current KeySN for wzshSDK from the file. You can manage the KeySN using
wzappkey. For how to use wzappkey, please read
/usr/local/bin/wzappkeyVersion.readme, which is installed together with wzshSDK.
Warning:
If you are using a DEMO wzhsSDK license, please remember it's a common license, which
means any other wzshSDK installation with DEMO license will be able to generate certificate
for the interpreter that your program uses, means it will be able to decrypt your program.
So, only use a DEMO license for internal testing. Never distribute need-be-protected
program encrypted under DEMO license to untrusted person.
Important Notes:
Make sure only trusted user[s] on your machine with wzshSDK package configured have the
rights to run the /usr/local/bin/wzshcert program, otherwise the protection for your
programs will not be there.
To secure wzshSDK package on your machine, you could create 3 new user groups, named
as "wzshlic", "wzshcert" and "wzappkey" on the machine; change the ownership and
permission as follows:
cd /usr/local/bin
chown root:wzshlic wzshKey wzshLic
chown root:wzshcert wzshcert wzshSDKId
chown root:wzappkey wzshsec
chmod 750 wzshSDKId wzshKey wzshLic
chmod 2755 wzshsec
chmod 4750 wzshcert
and then
chown root:wzappkey /usr/local/etc/wzapp.k??
chmod 640 /usr/local/etc/wzapp.k??
then only assign those trusted users into "wzshcert" group; and add accounts into "wzshlic"
group for people who need the privilege to generate license for your applications.
Without the special settings for the wzshsec above, either wzshsec will need to be run by
root, or the /usr/local/etc/wzapp.k?? files need be freely readable by the person who runs
the wzshsec, both are not good for security.
We also recommend you to create /var/adm/wzshcert (on Solaris/AIX/HP-UX) or
/var/log/wzshcert (on Linux) directory and set ownership and permission as follows:
chown root:adm /var/adm/wzshcert
chmod 700 /var/adm/wzshcert
or
chown root:adm /var/log/wzshcert
chmod 700 /var/log/wzshcert
Having this directory created and wzshcert setuid root, every time a user tries to generate
certificate using wzshcert program, the image file that is supplied as the interpreter will be
saved under this directory for future verification. And the activity will be logged in
/var/adm/wzshcert.log
or
/var/log/wzshcert.log
file. The following is an example of wzshcert log entry:
Feb 24 14:35:31 100 cyan.wziss.com: A certificate with KeySN=0000 for /bin/sh using
image file /var/log/wzshcert/728383.675276 generated.
Here, "100" is the UID of the account who run the command; "cyan.wziss.com" is the name
of the machine; the first part of the image file name (before the '.') is the cksum of the file
content; second part (after the '.') is the file length. You can run the cksum command on the
file to check: they must be matched.
Note: wzshcert won't run if not setuid root, this is to make sure it can log the activities; and
it also won't run directly by root account.
Notes for KeySN:
When a script is encrypted by wzshsec, a KeySN will be recorded in the encrypted script. A
license for the script will also have KeySN embedded.
The KeySN is also used by the certificate for script interpreter.
What's the purpose of the KeySN?
KeySN is used for damage control. E.g., in a situation, someone has used your machine and
wzshSDK license generated a certificate for a modified version of interpreter, and running
your encrypted script using that interpreter, that person could get the un-encrypted script.
And with that certificate, all your scripts that you want to protect will be in danger.
To control the damage, you can run "wzappky -n wzshSDK" to activate a new KeySN, and
use the new KeySN to encrypt your new scripts, also re-encrypt your existing scripts
provided they haven't been exposed.
As KeySN is recorded in script, so even a person has a license for the same script but has a
different KeySN, due to the miss-match of script KeySN and license KeySN, that license is
considered invalid for this version of the script.
Same for the interpreter certificate: unless certificate KeySN matches with script KeySN, that
certificate is invalid for running the script.
How does wzshSDK compare with other similar software:
shc
shell-lock
ccsh
wzshSDK
Anti syscall tracer
1
0
0
3-4
Anti debug from profile
0
0
5
4-5
Anti debug for long running script
0
0
5
1-2
Password safety in long running script
0
0
0
0-2
Password safety in short running script 1
0
0
4-5
Anti temp watch attack
5
0
5
5
Anti fake interpreter attack
4-5
0
5
4-5
Script modification protection
1
0
5
3-5
Program logic protection
1
0
2
3-4
Execution performance
3
3
5
2
Language support
5
2
1
3(4)*
Permission control
1
0
0
5
Platform/machine independence
0
3
1
3
All numbers above are scaled from 0 to 5, 0 is the worst, 5 is the best.
Except wzshSDK, all the packages here do not support Shell dot command execution of
encrypted or compiled script or modules in Perl, Ruby, etc. In wzshSDK, pdksh compatible
scripts can use the modified pdksh interpreter gwzsh to allow dot command execution of
encrypted scripts.
Following are the explanation for each category:
Anti syscall tracer:
run syscall tracer on protected program.
Anti debug from profile:
debugger can attach when process is in profile execution stage and then retrieve the
original script
Anti debug for long running script:
debugger can attach and then retrieve the original script when the process is in
normal execution stage
Anti temp watch attack:
by running a temp watch daemon, the original script can be captured
Anti fake interpreter attack:
using a fake interpreter to capture the decrypted script
Password safety:
Provided the machine doesn’t have Oracle/SUN’s dtrace running. How difficult to
recover password embedded in the protected script assume the password is used in
the later part of the script.
Script modification protection:
how strong the protection to prevent script modification
Program logic protection:
how difficult to discover the program logic
Execution performance:
Program execution performance: 4 for the original script performance.
Language support:
script languages the package support:
shc can support most commonly used script languages, such as
sh/ksh/bash/csh/tcsh/zsh/perl/ruby, etc.
shell-lock supports sh/ksh.
ccsh supports only sh.
wzshSDK supports sh/ksh/bash.
Note: wzshSDK can also support zsh, perl and ruby scripts, but not well tested and
the protection may not be as good (but would still be better than the protection shc
could provide). Use it with care for these languages.
Permission control:
Control the protected program to be run on what platform, what machine, for what
period.
Platform/machine independence:
Encrypted script can run on different platforms/machines:
shc encrypted script can only run on a machine that runs the same
interpreter image.
SHELL-LOCK supports cross platform development of encrypted scripts using
platform specific modules. But once linked with a platform specific module,
the encrypted script will not run on other platforms.
ccsh compiles Bourne SHELL script into binary executable, and as such the
result program will not run on different platforms.
wzshSDK generated encrypted scripts are platform independent, but the
execution of the encrypted scripts will need the platform dependent
wzshRUN runtime software.
Note:
Both shc and shell-lock had been proven that they did not provide adequate
protection for scripts.
Use password in encrypted script:
Provided the machine doesn’t have dtrace running.
For a script which contains a password or passphrase, if the password or passphrase
is used within a second from the start of script execution, then it should be very safe;
otherwise, it's not impossible for it to be discovered by system call tracer. The work
around solution is to split the script into 2 parts, the part 1 is just before the
password/passphrase used, and part 2 starts from the use of the password, and end
of part 1, call part 2.
How to manage interpreter certificates?
In current days, almost every type of scripting languages have open-source
equivalent interpretor implementation, so if you are using wzshSDK as a way to
protect your Intellective property, encrypting scripts with interpreter certification
enabled is the way to go.
You may have a question now: how can I manage the certificates when my scripts
could be used by many other customers each could use different version of
interpreter?
Tip: instead of having to handle so many different versions of interpreters, you can
copy a working version of interpreter to, say, /usr/local/bin/sh.YouCompanyName,
and update your scripts to replace first line from "#!/bin/sh" to
"#!/usr/local/bin/sh.YouCompanyName", and then use wzshsec to encrypt your
script with interpreter certification enabled. And when you distribute your encrypted
script for use by other machines, distribute it together with
/usr/local/bin/sh.YouCompanyName, and the certificate file. And when your
customer wants to use your script on a different UNIX platform, if you don't have
access to that platform, you can ask customer to send you the interpreter on that
platform, and certify it on your machine (even it's different platform), and ask your
customer to install a copy of the same interpreter at
/usr/local/bin/sh.YouCompanyName