SREhttp/2 encryption utilties

The SREhttp/2 encryption utilities.

Abstract:

SREhttp/2 provides several encryption tools for both returning contents to clients, and for recieving encrypted requests from clients. This document describe these options.

I Introduction
II Using SREhttp/2 encryption
II.1 Enabling Encryption
II.2 Assigning a shared-secret
II.3 Selecting which responses to encrypt.
II.4 Providing client-side decryption tools
II.4a SRE_A and SRE_B commonalities
II.4b SRE_A
II.4c SRE_B
II.4d SRE_BF and SRE_BFC
III. Custom encryption
IV. Client-side encrpytion of FORM requests
V. Comparing the default encryption algorithims
VI. Notes

I. Introduction

Ideally, SREhttp/2 would be SSL compliant. Unfortunately, the licensing and registration requirements for the public-key procedures used by SSL are overwhelming (at least in the USA). But given the open nature of the Internet, some form of encryption is sometimes necessary,

SREhttp/2 provides a solution to this problem, using a "shared secret" form of encryption. Basically, this requires that a client be "registered" with your site, that she have a username and password stored on your server. Although this is not as convenient as SSL, in many cases it will be sufficient.

SREhttp/2 uses a "pre-response" procedure -- ENCRYPT.REX -- to provide encrypt. This encryption procedure is flexible -- you can use one of the default methods provided (SRE_A, SRE_B, SRE_BF or SRE_BFC), or you can install your own, customized algorithim.

The SRE_A and SRE_B default methods use "40 bit" keys, and are based on a simple randomization of a message, using an MD5 hash of a password as a random number seed. Decryption of this method is accomplished with a javascript program run within your browser (SRE_B), or a rexx program installed as a plug-in launched by your browser (SRE_A).
The SRE_BF and SRE_BFC use the BlowFish encryptor. Since BlowFish is a strong (128 bit, and above) encryption algorithim, we can not include the BlowFish executable with SREhttp/2 -- you'll have to find them on the net. You can try http://hobbes.nmsu.edu, search for BLOWFISH, or http://www.counterpane.com/blowfish.html.
You can fairly easily install and specify your own encryption scheme: as long as it can be called by SREhttp/2 as an external rexx procedure, it probably can be used.

Note: In many cases, where access control is more important then the actual contents of a response, encryption of a user's password is sufficient. This can be accomplished using http/1.1 "digest authentication". Alternatively, since there still are many people using http/1.0 browsers (such as NetScape 4.x), one can use SRE-http/2's dynamic password procedure to simluate digest authentication (see DYNPWD.TXT for further discussion).

Note:	In many cases, where access control is more important then the actual contents of a response, encryption of a user's password is sufficient. This can be accomplished using http/1.1 "digest authentication". Alternatively, since there still are many people using http/1.0 browsers (such as NetScape 4.x), one can use SRE-http/2's `dynamic password` procedure to simluate digest authentication (see DYNPWD.TXT for further discussion).

II) Using SREhttp/2 encryption

To use SREhttp/2's encryption, you need to:

add ENCRYPT.REX to the list of pre-response procedures.
assign a "shared secret" to all users who may need to download encrypted responses
indicate which selectors are to be encrypted by SREhttp/2, and which encryption algorithim to use
depending on the encryption algorithim used, you may need to provide tools to clients, tools that can be used to decrypt the encrypted response.

The following describes these steps.

II.1) Enabling Encryption with the ENCRYPT.REX pre-response procedure.

You'll need to add the following to your PRELOADS.CFG configuration file.
PRE_RESPONSE = ENCRYPT PROCS\ENCRYPT.REX SRE_x
where SRE_x your choice for the default encryption method.

After adding this line, re-start SRE2003.

Notes

The default encryption method can be one of SRE_A, SRE_B, SRE_BF and SRE_BFC. If it is not one of these, then it is assumed to be a custom method.
If you want to use encryption as the default pre-response procedure, you can:
1. Have PRE_RESPONSE = ENCRYPT PROCS\ENCRYPT.REX SRE_x be the only PRE_RESPONSE entry.
  or ....
2. Make sure PRE_RESPONSE = ENCRYPT PROCS\ENCRYPT.REX SRE_x is the first PRE_RESPONSE entry in PRELOADS.CFG
  and make sure that no pre-response entry has a name of DEFAULT
  or ....
3. Instead of PRE_RESPONSE = ENCRYPT PROCS\ENCRYPT.REX SRE_x, use
  PRE_RESPONSE = DEFAULT PROCS\ENCRYPT.REX SRE_x
  If you use this, in the remainder of this documentation, when selector-specific attributes are discussed, you'll have to substitute DEFAULT for ENCRYPT.
Alternatively, if the only pre-response procedure listed is ENCRYPT, but you do not want ENCRYPT to be called by default, you should use:
PRE_RESPONSE = ENCRYPT PROCS\ENCRYPT.REX SRE_A
PRE_RESPONSE = DEFAULT 0
If ENCRYPT is enabled as the default pre-response procedure ....

it is highly recommended that you force SREhttp/2 to lookup client privileges. by setting the ALWAYS_GET_PRIVS=2 SREHTTP2.CFG parameter.
As with other pre-response procedures, ENCRYPT will be called on all requests for static files, including HTML documents with server side includes. However, ENCRYPT will not be called for CGI-BIN scripts, for !SPECIAL request, and for SREhttp/2 addons that directly return results to the client.

II.2) Assigning a shared-secret

The default SREhttp/2 encryption algorithims requires a shared-secret. The shared secret is is a special password< that is known only by you (the server) and the user (the client). When SREhttp/2 needs to encrypt a file, the shared-secret is used to scramble the contents. Furthermore, when the client needs to decrypt the response, she'll need to provide this same shared-secret to the decryption software.

SREhttp/2 uses client-specific secret privileges to assign this shared-secret.

In particular, you should have the following kind of entries in the USERS.CFG file:

username password ?ENCRYPT:a_secret

where a_secret is this case-insensitive user's shared secret.

Notes:

Notes:	"secret privileges" must always start with a `?` Secret privileges should never be reported by any SREhttp/2 application. USERS.HTM contains further discussions of secret-privileges Although it weakens security a bit, shared-secrets are case insensitive. In other words; SREhttp/2 converts `shared-secrets` to upper case.
Examples:	assuming a user `JOE`, with password `COLD`, and a shared-secret of `MOLX4`; the entry (in `USERS.CFG`) could be: `JOE COLD ?ENCRYPT:MOLX4` or, if you want to also assign a few other privileges, you could use: `JOE COLD ?ENCRYPT:MOLX4 USER5 ?MANAGER:ZXI3`

"secret privileges" must always start with a ?
Secret privileges should never be reported by any SREhttp/2 application.
USERS.HTM contains further discussions of secret-privileges
Although it weakens security a bit, shared-secrets are case insensitive. In other words; SREhttp/2 converts shared-secrets to upper case.

Examples:

assuming a user JOE, with password COLD, and a shared-secret of MOLX4; the entry (in USERS.CFG) could be:

JOE COLD ?ENCRYPT:MOLX4

or, if you want to also assign a few other privileges, you could use:
JOE COLD ?ENCRYPT:MOLX4 USER5 ?MANAGER:ZXI3

II.3) Selecting which responses to encrypt.

If you've set ENCRYPT as the default pre-response procedure, then ENCRYPT will be called for most requests, with SRE_x used as the encryption method.

However, if ENCRYPT is not the default pre-response procedure, you can use the SET PRE_RESPONSE advanced option to enable ENCRYPT, and choose an encryption method, on a selector specific basis.

Syntax SET PRE_REPSONSE Encrypt SRE_xx RSP_file
where ...
SRE_xx is SRE_A, SRE_B, SRE_BF, SRE_BFC, or an identifier for a custom encryption algorithim.
RSP_file is optional, and is used only with SRE_B. If specified, it should be the name (either as a selector, or as a fully qualified file name) of a customized version of ENC_SREB.RSP. If you do not include a RSP_FILE, the default version (that should be in your possibly host-specific default data directory) will be used.

Examples:

Syntax	`SET PRE_REPSONSE Encrypt SRE_xx RSP_file` where ... `SRE_xx` is SRE_A, SRE_B, SRE_BF, SRE_BFC, or an identifier for a custom encryption algorithim. `RSP_file` is optional, and is used only with SRE_B. If specified, it should be the name (either as a selector, or as a fully qualified file name) of a customized version of ENC_SREB.RSP. If you do not include a `RSP_FILE`, the default version (that should be in your possibly host-specific default data directory) will be used.
Examples:	If you want all request under `/my_private/` to be encrypted using the SRE_A algorithim, you could create the following entry in ATTRIBS.CFG: `Realm: encrpyt_me Rule: /my_private/* Option: set pre_response Encrypt SRE_A Option: set get_privs 1` Alternatively, if ENCRYPT is enabled by default, but you do not want to encrypt files in `/PUBLIC_FILES/`, you could use the following entry: `Realm: no_encrpyt_me Rule: /public_files/* Option: set pre_response 0 Option: set get_privs 0` Note that the above example, no pre-response procedures will be called.

If you want all request under /my_private/ to be encrypted using the SRE_A algorithim, you could create the following entry in ATTRIBS.CFG:

Realm: encrpyt_me Rule: /my_private/* Option: set pre_response Encrypt SRE_A Option: set get_privs 1

Alternatively, if ENCRYPT is enabled by default, but you do not want to encrypt files in /PUBLIC_FILES/, you could use the following entry:

Realm: no_encrpyt_me Rule: /public_files/* Option: set pre_response 0 Option: set get_privs 0 Note that the above example, no pre-response procedures will be called.

Important Note	To avoid possible problems, it is highly recommended that when encrypting selectors, one also forces SREhttp/2 to lookup client privileges. This can be done by using the `SET GET_PRIVS 1` option. Alternatively, you can use the !FORCE special directive

II.4) Providing client-side decryption tools

After the server sends the encrypted response, the client has to have some way of decrypting it. The SREhttp/2 SRE_ methods offer different means for accomplishing this decryption.

II.4a) SRE_A and SRE_B

The SRE_A and SRE_B methods use a similar randomization technique:

SREhttp/2 generates a "nonce", consisting of the time and the client's ip address.
The client's shared-secret password is appended to this nonce -- the result is the encryption key (this assumes that that client has a ?ENCRYPT:password secret privilege)
An MD5 hash is generated from this encryption key. A verifier is extracted from this hash. In addition, a random number seed is also extracted from the hash.
The random number seed is used to generate a series of random numbers. These are used to randomize the response.
This randomized response is sent to the client.

To decrypt the response, the client must replicate these steps, using the nonce (which is included in the response), and her shared-secret password, to generate an MD5 hash from which the random number seed is extracted.

SRE_A and SRE_B use different strategies to enable this client side decryption:

SRE_A	An external program is run, which decrypts the response and either writes the decrypted response to a file, or displays it in a new browser window
SRE_B	The encrypted response is embedded in an html document containing a javascript program. This javascript program will ask the client for her password, decrypt the file, and then display this decrypted response in a new window.

II.4b) SRE_A

SRE_A requires an external program. In particular, the DE_SREA.CMD program (which can be found in your SREHTTP2\PROCS directory) can be used by clients who have rexx interpreters on their machine -- basically, OS/2 clients who are using NetScape.

Although it can be run in a stand-alone mode, DE_SREA.CMD is best used as a NetScape helper application. Basically, the client should:

copy DE_SREA.CMD to an applications directory; say, D:\OS2\APPS

add a helper-app to netscape, using:

     mimetype: application/x-encrypt_SRE_A
     application: cmd.exe /c "D:\OS2\APPS\DE_SREA.CMD PWD:my_secret"

where my_secret is the client's shared-secret password.

Please see DE_SREA.CMD for more detailed installation

After this installation, NetScape will call DE_SREA whenever a response has the mimetype of application/x-encrypt_SRE_A. DE_SREA will display some info on the response, decrypt it, and then ask whether the response should be displayed in a new NetScape window or whether it should be saved to a file.

II.4c) SRE_B

SRE_B requires a javascript capable browser. SRE_B has the advantage of simplicity -- you do NOT need to distribute (and instruct clients in the installation) of an operating system specific plug-in. The disadvantage is that it is much slower then SRE_A (about 10x slower).

By default, SRE_B uses the ENC_SREB.RSP file (a copy of which can be found in your SREHTTP2\PROCS directory) to create this javascript containing response.

Notes	You can customize the ENC_SREB.RSP "javascript" file, just be careful about non-changeable code! If you want to use a different .RSP file, you can specify one in the `RSP_FILE` token of a SET RESPONSE_FILE selector specific attribute.

II.4d) SRE_BF and SRE_BFC

The SRE_BF and SRE_BFC "BlowFish" methods require that the client have some kind of BlowFish executable. There may be plugins for NetScape, IE, etc. that will run BlowFish for the client.

Lacking that, the DE_SREBF.CMD REXX program can be used to facilitate (on OS/2, or other REXX capable machines) the use of BlowFish.

For details on DE_SREBF.CMD, please see the comments in DE_SREBF.CMD (you can find DE_SREBF.CMD in SREHTTP2\PROCS).

For more information on BlowFish, see http://www.counterpane.com/blowfish.html.

III) Custom encryption

If desired, you can write your own encryption procedure (say, a Java based procedure based on PGP). To incorporate this into SREhttp/2, the following step are required:

Create (and load) a macrospace procecdure named SREH2_CUSTOM_ENCRYPT. If you are implementing more then one custom procecure, SREH2_CUSTOM_ENCRYPT will need to implement all the various encryption algorithims (or call an appropriate set of procedures).
This SREH2_CUSTOM_ENCRYPT procedure will be sent the same set of arguments as any other pre-response procedure.
In addition, it is often wise for the custom procedure to:

create an appropriate Content-Encoding: response header.
set the mimetype.
For example, SRE_A...
sets the mimetype to be application/x-encrypt_SRE_A,
and creates a Content-Encoding: Encrypt_SRE_A response header.
You'll need to arrange a mechanism (i.e.; a seperate helper application, or embedded code) that will help the client decrypt the response.

IV) Encrpyting FORMS submitted by clients.

In order to allow clients to submit encrypted information, SREhttp/2 provides a javascript based procedure that will encrypt elements in an HTML form. These encrypted elements will be then be sent to the server, and the server will then decrypt them for further processing.

This is a several step process:

Include (using an INCLUDE ssi) the ENC_FORM.RSP javascript procedures in an HTML document that contains a FORM (with elements you wish to encrypt).
specify a hidden element with name="nonce" and a hidden element with name="verify".
Using a TEXT element, get a shared-secret password, and then call the comp_md5 javascript procedure to generate an encryption key.
Specify some hidden elements that will contain the encrypted variables
Include some non-hidden form elements (such as TEXT, TEXTAREA, and SELECT), and encrypt their values using the do_encrypt javascript procedure
clear the raw (unencrypted) variables (that is, the raw versions of the variables you encrypted in step 5) using the clear_fields javascript procedure
Submit the form -- the script on the server will have to decrypt (using SREH2_FORM_DECRYPT) the encrypted variables (that were set in steps 4 and 5)

Note that comp_md5, do_encrypt, and clear_fields are part of ENC_FORM.RSP.

ENC_FORM.RSP (in the SREHTTP2\PROCS directory) contains further details on each of these steps.

Notes	`ENC_TEST.SHT` and `ENC_TEST.CMD` demonstrate SRE-http's client-side encryption of form elements. The encryption algorithim used is essentially the same as SRE_B -- it uses a 40 bit key, hence can not be considered secure against sophisicated attack.

V) Comparing the default encryption algorithims

None of the several encryption algorithims are perfect. The following lists their strengths and weaknesses. Note that in all cases, clients requesting encyrpted resources must be "registered" -- which will require some parallel means of communicating passwords and other client-specific attributes.

SRE_A	Speed: Moderate -- adequate for responses less then 25k. Security: Moderate (40 bit) -- will not stop determined/well-equipped crackers Limitations: None Client-side ease of use: Somewhat demanding. Client must obtain and install the `DE_SREA.CMD` program; which requires REXX. Recommendation: best used when you know your clients are OS/2 users.
SRE_B	Speed: Slow -- adequate for responses less then 5k. Security: Moderate (40 bit) -- will not stop determined/well-equipped crackers Limitations: None Client-side ease of use: Fairly easy. Client has to have a javascript enabled browser. Recommendation: best used to return short responses to a variety of cients.
SRE_BF and SRE_BFC	Speed: Fast -- large (>100k) responses are quickly encrypted and decrypted Security: Stronge (128+ bit) -- with adequately long "shared-secrets" (say, 10 or so characters), will probably stop all but the most sophisticated crackers. Limitations: Export restrictions mean that both servers and clients are responsible for obtaining blowfish executables. Howver, this is not difficult to do, they can readily be found on the WWW. Client-side ease of use: Mediocre. Client must obtain an operating system specific version of BlowFish, and be satisified with saving responses to a disk file. However, BlowFish is gaining acceptance, and there may be BlowFish capable plug-ins for the major browsers in the near future. Also, The `DE_SREBF` program can be used (by clients with REXX capable machines) to decrypt & display SRE_BF and SRE_BFC encrypted files. Recommendation: best used when security is important, and clients are capable of obtaining and using BlowFish executables. Note: SRE_BF and SRE_BFC differ only in that SRE_BFC will compress before encrypting. This is a very nice feature, but may not be supported by all implementations of BlowFish.

25 January 2003

The SREhttp/2 encryption utilities.

Contents