13 December 1999. Daniel Hellerstein (danieh@crosslink.net) The SRE-http encryption facility. Abstract: SRE-http provides several encryption tools for both returning contents to clients, and for recieving encrypted requests from clients. This document describe these options. ------------------ Contents: I Introduction II Using SRE-http 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, SRE-http 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, SRE-http 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. The encryption algorithim used by SRE-http 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 SRE-http -- 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 SRE-http 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 it may be a few years before digest authentication is fully suported by commonly used browsers, one can use SRE-http's "dynamic password" procedure to simluate "digest authentication" (see DYNPWD.DOC for further discussion). ------------------------------- II) Using SRE-http encryption To use SRE-http's encryption, you need to: ** 1) enable encryption ** 2) assign a "shared secret" to all users who may need to download encrypted responses ** 3) indicate which selectors are to be encrypted by SRE-http, and which encryption algorithim to use ** 4) 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 ENABLE_ENCRYPTION and DEFAULT_ENCRYPTION paramaters The ENABLE_ENCRYPTION parameter (set in INI_STA.80) is used to enable SRE-http's encryption facility. It can take the following values: 0 = Disable the sre-http encryption facility 1 = Check for a !ENCRYPT "modifier", and encrypt if the response is a file, or an "encrypt aware" addon 2 = Same as 1, but handles more cases (i.e.; addons that let sref_gos return results) 3 = Encrypt everything The DEFAULT_ENCRYPTION parameter (also set in INIT_STA.80) parameter specifies what algorithim to use by default. As described in step 3 below, when designating which "selectors" should be encrypted, one can specify the method, or use the "default". DEFAULT_ENCRYPTION specifies what this default method should be. Examples: DEFAULT_ENCRYPTION='SRE_A' DEFAULT_ENCRYPTION='SRE_B' DEFAULT_ENCRYPTION='MY_METHOD' Technical notes: i) The SRE-http encryption facility is invoked by the SREF_GOS procedure. SREF_GOS is used by SREFILTR.80, and by most addons. However, some older addons directly return results to the client, and bypass SREF_GOS. For these "older" addons, encryption (unless explicitily invoked) will NOT be attempted. Addon authors should read the description (in SREFPRC.DOC) of how to specify encryption when using SREF_GOS. ii) ENABLE_ENCRYPTION=1 is a subset of ENABLE_ENCRYPTION=2. If you use ENABLE_ENCRYPTION=1, then calls to SREF_GOS must explicitily include an "encryption" option. SREFILTR.80, and a few of the more commonly used SRE-http utilities, have been modified to send this "explicit encryption" command when calling SREF_GOS. Most addons have NOT been modified. In contrast, ENABLE_ENCRYPTION=2 instructs SREF_GOS to also check the "request specific" environment for an !ENCRYPT flag. Thus, addons that use SREF_GOS can have their output encrypted, even if they don't explicitly tell SREF_GOS to encrypt. ENABLE_ENCRYPTION=2 is the more risk free choice, but it is a bit slower. So, if you know what will be encrypted (say, a small set of static documents), you can speed things up a bit by using ENABLE_ENCRYPTION=1 iii) If ENABLE_ENCRYPTION=3, then all responses (that are handled by SREF_GOS) will be encrypted, using the default algorithim. This is not recommended for general purposes, but may be useful for special secure servers. ** II.2) Assigning a shared-secret The default SRE-http encryption algorithims require 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 SRE-http needs to encrypt a file, the shared-secret is used to scramble the contents. Furthemore, when the client needs to decrypt the response, she'll need to provide this same shared-secret to the decryption software (see 4 below for more on decryption). SRE-http uses client-specific "secret privileges" to assign this "shared- secret". In particular, you could add the following to entries in the USERS.IN file: ?ENCRYPT:a_secret where a_secret is this case-insensitive user's shared secret. *** Although it weakens security a bit, shared-secrets are case insensitive. In other words; SRE-http converts "shared-secrets" to upper case. For example: assuming a user JOE, with password COLD. and a "shared-secret" of MOLX4; the entry (in USERS.IN) could be: JOE COLD ?ENCRYPT:MOLX4 or, if you want to also assign a few other privileges, you could use: JOE COLD USER5 ?ENCRYPT:MOLX4 ?MANAGER:ZXI3 Notes: * "secret privileges" MUST always start with a ? * Secret privileges should NEVER be reported by any SRE-http application. * the SRE-http manual, and the sample USERS.IN file, contain further discussions of secret-privileges * the shared-secret is case insensitive. * Although it's not recommended, you can use the USER_PRIVS parameter (in INITFILT.80) to assign a generic shared-secret to all clients. For example: USER_PRIVS='USER ?ENCRYPT:users1q' If you do this, you won't be able to assign "client specific" shared secrets. ** II.3) Selecting which responses to encrypt. There are two ways to indicate which resources should be encrypted, by prepending an !ENCRYPT to the selector, or by using an advanced option. a) Prepending !ENCRYPT SRE-http looks for a !ENCRYPT "special modifier" in the selector. This modifier can take two forms: !ENCRYPT/selector encrypt using the "default" algorithim (as specified by the DEFAULT_ENCRYPTION parameter). !ENCRYPT_method/selector encrypt using the "method" algorithim For example: !ENCRYPT/private/guests.txt !ENCRYPT_SRE_A/sales/order123.rcp !ENCRYPT_CUSTOM_XYZ/employees/jhm/timesheet.499 Note that !ENCRYPT/ will invoke the algorithim specified by the DEFAULT_ENCRYPTION parameter (specified in section 1). b) Using an advanced option Set an advanced option of: SET ENCRYPT method or SET ENCRYPT 0 (to override any !ENCRYPT special directive) For example: SET ENCRYPT SRE_BFC If you do not specify a method, then the default method (as specified by the DEFAULT_ENCRYPTION parameter) will be used. Note that the "advanced option" may be for a "wildcarded selector" (say, from a wildcarded entry in ACCESS.IN) Please see ADV_OPTS.DOC for further dicussion of advanced options. Note: for a discussion of how to specify a custom algorithim, please see section III. ** 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 default 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: a) SRE-http generates a "nonce", consisting of the time and the client's ip address. b) 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") c) 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. d) The random number seed is used to generate a series of random numbers. These are used to randomize the response. e) 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 is installed in the GoServe data 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 should be installed as a NetScape helper application. DE_SREA.CMD contains detailed installation instructions on how to do this. Basically, the client should: a) copy DE_SREA.CMD to an applications directory; say, D:\OS2\APPS b) 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" 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). SRE_B uses the ENC_SREB.RSP file (which should be located in the, possibly host-specific, default data directory) to create this javascript containing response. You can customize this "response" file, just be careful about non-changeable code! 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. ------------------ III) Custom encryption If desired, you can write your own encryption procedure (say, a Java based procedure based on PGP). To incorporate this into SRE-http, the following step are required: a) Create (and load) a macrospace procecdure named SREF_CUSTOM_ENCRYPT. If you are implementing more then one custom procecure, SREF_CUSTOM_ENCRYPT will need to implement all the various encryption algoritims (or call an appropriate set of procedures). b) This procedure should return the following (seperated by '0d0a'x): i) the mime-type ii) the content encoding iii) the encrypted response That is, the following will be used to parse the reponse: parse var stuff mimetype (crlf) content_encoding (crlf) stuff For example, SRE_A returns: 'application/x-encrypt_SRE_A'||crlf||'Encrypt_SRE_A'||crlf||response where: cflf='0a0a'x response is the encrypted response (which might contain many crlfs) c) 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, SRE-http 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: 1) Include (using an INCLUDE ssi) the ENC_RESP.RSP javascript procedures in an HTML document that contains a FORM (with elements you wish to encrypt). 2) specify a hidden element with name="nonce" and a hidden element with name="verify" 3) Using a TEXT element, get a "shared-secret" password, and then call the comp_md5 javascript procedure to generate an encryption key 4) Specify some hidden elements that will contain the encrypted variables 5) Include some non-hidden form elements (such as TEXT, TEXTAREA, and SELECT), and encrypt their values using do_encrypt javascript procedure 6) clear the raw (unencrypted) variables (that is, the raw versions of the variables you encrypted in step 5) using the clear_fields javascript procedure 7) Submit the form -- the script on the server will have to decrypt (using SREF_FORM_DECRYPT) the encrypted variables (that were set in 4 and 5) ENC_TEST.RSP contains further details on each of these steps. Notes: * ENC_TEST.HTM 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. Vi) Notes * PUBLIC_URLS are NEVER encrypted. * For more information on BlowFish, see http://www.counterpane.com/blowfish.html