OS/2 Shareware BBS: 35 Internet/35-Internet.zip/srev13h.zip/encrypt.doc

Text File | 2001-03-27 | 19KB | 461 lines

13 December 1999. Daniel Hellerstein ([e-mail])

       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