home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / encrypt.doc < prev    next >
Text File  |  1999-05-10  |  19KB  |  456 lines
  1. 21 April 1999. Daniel Hellerstein (danieh@econ.ag.gov)
  2.  
  3.        The SRE-http encryption facility.     
  4.  
  5. Abstract:
  6.    SRE-http provides several encryption tools for both
  7.    returning contents to clients, and for recieving
  8.    encrypted requests from clients.  This document
  9.    describe these options.
  10.  
  11.                         ------------------
  12.  
  13. Contents:
  14.    I    Introduction
  15.   II    Using SRE-http encryption
  16.   II.1    Enabling Encryption
  17.   II.2    Assigning a shared-secret
  18.   II.3    Selecting which responses to encrypt.
  19.   II.4    Providing client-side decryption tools
  20.   II.4a     SRE_A and SRE_B commonalities
  21.   II.4b     SRE_A
  22.   II.4c     SRE_B
  23.   II.4d     SRE_BF and SRE_BFC
  24.  III.   Custom encryption
  25.   IV.   Client-side encrpytion of FORM requests
  26.    V.   Comparing the default encryption algorithims
  27.   VI.   Notes
  28.  
  29.      
  30.                         ------------------
  31.  
  32. I. Introduction
  33.  
  34. Ideally, SRE-http would be SSL compliant. Unfortunately,
  35. the licensing and registration requirements for the 
  36. public-key procedures used by SSL are overwhelming
  37. (at least in the USA).  But given the open nature of the
  38. Internet, some form of encryption is sometimes necessary,
  39.  
  40. SRE-http provides a solution to this problem, using a "shared
  41. secret" form of encryption.  Basically, this requires
  42. that a client be "registered" with your site, that she have a 
  43. username and password stored on your server. Although this
  44. is not as convenient as SSL, in many cases it will be sufficient.
  45.  
  46. The encryption algorithim used by SRE-http is flexible -- you can
  47. use one of the default methods provided (SRE_A, SRE_B, SRE_BF or SRE_BFC), 
  48. or you can install your own, customized algorithim.  
  49.  
  50.   * The SRE_A and SRE_B default methods use "40 bit" keys, and are
  51.     based on a simple randomization of  a message, using  an MD5 hash 
  52.     of a password as a random number seed. 
  53.     Decryption of this method is accomplished with a 
  54.     javascript program run within your browser (SRE_B), or a rexx program
  55.     installed as a plug-in launched by your browser (SRE_A).
  56.  
  57.   * The SRE_BF and SRE_BFC use the BlowFish encryptor. Since BlowFish
  58.     is a strong (128 bit, and above) encryption algorithim, we 
  59.     can not include the BlowFish executable with SRE-httpp 
  60.      -- you'll have to find them on the net. You can try 
  61.         http://hobbes.nmsu.edu, search  for BLOWFISH, or 
  62.         http://www.counterpane.com/blowfish.html
  63.  
  64.       * You can fairly easily install and specify your own encryption scheme:
  65.        as long as it can be called by SRE-http as an external rexx
  66.        procedure, it probably can be used.  
  67.  
  68. Note: 
  69.   In many cases, where access control is more important then the actual 
  70.   contents of a response, encryption of a user's password is sufficient.
  71.   This can be accomplished using http/1.1 "digest authentication".  
  72.   Alternatively, since it may be a few years before digest authentication is 
  73.   fully suported by commonly used browsers, one can use SRE-http's 
  74.   "dynamic password" procedure  to simluate "digest authentication" (see 
  75.   DYNPWD.DOC for further discussion).
  76.   
  77.  
  78.                         -------------------------------
  79.  
  80. II) Using SRE-http encryption
  81.  
  82. To use SRE-http's encryption, you need to:
  83.  
  84.   ** 1) enable encryption
  85.   ** 2) assign a "shared secret" to all users who may need to download encrypted 
  86.         responses
  87.   ** 3) indicate which selectors are to be encrypted by SRE-http, and which
  88.         encryption algorithim to use
  89.   ** 4) depending on the encryption algorithim used, you may need to provide tools 
  90.         to clients, tools that can be used to decrypt the encrypted response
  91.  
  92. The following describes these steps.
  93.  
  94. ** II.1) Enabling Encryption with the ENABLE_ENCRYPTION and DEFAULT_ENCRYPTION
  95.       paramaters
  96.  
  97. The ENABLE_ENCRYPTION parameter (set in INI_STA.80) is used to enable 
  98. SRE-http's encryption facility. It can take the following values:
  99.  
  100.   0 = Disable the sre-http encryption facility
  101.  
  102.   1 = Check for a !ENCRYPT "modifier", and encrypt if the response
  103.      is a file, or an "encrypt aware" addon
  104.  
  105.   2 = Same as 1, but handles more cases (i.e.; addons that let
  106.       sref_gos return results)
  107.  
  108.   3 = Encrypt everything
  109.  
  110. The DEFAULT_ENCRYPTION parameter (also set in INIT_STA.80) parameter specifies 
  111. what algorithim to use by default.  As described in step 3 below, when
  112. designating which "selectors" should be encrypted, one can specify
  113. the method, or use the "default". DEFAULT_ENCRYPTION specifies what
  114. this default method should be.
  115.  
  116. Examples:
  117.     DEFAULT_ENCRYPTION='SRE_A'
  118.     DEFAULT_ENCRYPTION='SRE_B'
  119.     DEFAULT_ENCRYPTION='MY_METHOD'
  120.  
  121.  
  122. Technical notes:
  123.  
  124.  i) The SRE-http encryption facility is invoked by the SREF_GOS procedure.
  125.     SREF_GOS is used by SREFILTR.80, and by most addons. However, some older
  126.     addons directly return results to the client, and bypass SREF_GOS.
  127.     For these "older" addons, encryption (unless explicitily invoked) will
  128.     NOT be attempted.
  129.  
  130.     Addon authors should read the description (in SREFPRC.DOC) of
  131.     how to specify encryption when using SREF_GOS.
  132.  
  133.  ii) ENABLE_ENCRYPTION=1 is a subset of ENABLE_ENCRYPTION=2.
  134.      If you use ENABLE_ENCRYPTION=1, then calls to SREF_GOS
  135.      must explicitily include an "encryption" option.  SREFILTR.80,
  136.      and a few of the more commonly used SRE-http utilities, have been 
  137.      modified to send this "explicit encryption" command when calling SREF_GOS.  
  138.      Most addons have NOT been modified.
  139.  
  140.      In contrast, ENABLE_ENCRYPTION=2 instructs SREF_GOS to also check the 
  141.      "request specific" environment for an !ENCRYPT  flag.  Thus, addons 
  142.      that use SREF_GOS can have their output encrypted, even if they
  143.      don't explicitly tell SREF_GOS to encrypt.
  144.  
  145.      ENABLE_ENCRYPTION=2 is the more risk free choice, but it is a bit
  146.      slower. So, if you know what will be encrypted (say, a small
  147.      set of static documents), you can speed things up a bit by using
  148.      ENABLE_ENCRYPTION=1
  149.  
  150.  iii) If ENABLE_ENCRYPTION=3, then all responses (that are handled by SREF_GOS)
  151.       will be encrypted, using the default algorithim. This is not
  152.       recommended for general purposes, but may be useful for special secure
  153.       servers.
  154.  
  155.  
  156. ** II.2) Assigning a shared-secret
  157.  
  158. The default SRE-http encryption algorithims require a "shared-secret". 
  159. The "shared secret" is is a special "password" that is known only by
  160. you (the server) and the  user (the client). When SRE-http needs to encrypt
  161. a file, the shared-secret is used to scramble the contents.  Furthemore, when
  162. the client needs to decrypt the response, she'll need to provide this 
  163. same shared-secret to the decryption software (see 4 below for more 
  164. on decryption).
  165.  
  166. SRE-http uses client-specific "secret privileges" to assign this "shared-secret". 
  167. In particular, you should add the following to entries in the USERS.IN file;
  168.    ?ENCRYPT:a_secret
  169. where  a_secret is this user's shared secret.
  170.  
  171. For example: assuming a user JOE, with password COLD. and a "shared-secret" of MOLX4;
  172. the entry (in USERS.IN) could be:
  173.    JOE COLD ?ENCRYPT:MOLX4
  174.  
  175. or, if you want to also assign a  few other privileges, you could use:
  176.    JOE COLD USER5 ?ENCRYPT:MOLX4 ?MANAGER:zxi3
  177.  
  178.  
  179. Notes:
  180.  * "secret privileges" MUST always start with a ?
  181.  * Secret privileges should NEVER be reported by any SRE-http application.
  182.  * the SRE-http manual, and the sample USERS.IN file, contain further discussions
  183.    of secret-privileges
  184.  * the shared-secret is case insensitive.
  185.  * Although it's not recommended, you can use the USER_PRIVS parameter (in
  186.    INITFILT.80) to assign a generic  shared-secret to all clients. For example:
  187.       USER_PRIVS='USER  ?ENCRYPT:users1q'
  188.   If you do this, you won't be able to assign "client specific" shared secrets.
  189.  
  190. ** II.3) Selecting which responses to encrypt.
  191.  
  192.   There are two ways to indicate which resources should be encrypted,
  193.   by prepending an !ENCRYPT to the selector, and by using an advanced option.
  194.  
  195.  a) Prepending !ENCRYPT
  196.  
  197.   SRE-http looks for a !ENCRYPT "special modifier" in the selector.
  198.   This modifier can take two forms:
  199.  
  200.      !ENCRYPT/selector  
  201.            encrypt using the "default"  algorithim (as specified by the
  202.            DEFAULT_ENCRYPTION parameter).
  203.      !ENCRYPT_method/selector
  204.            encrypt using the "method" algorithim
  205.  
  206.  For example:
  207.    !ENCRYPT/private/guests.txt
  208.    !ENCRYPT_SRE_A/sales/order123.rcp
  209.    !ENCRYPT_CUSTOM_XYZ/employees/jhm/timesheet.499
  210.  
  211.    Note that !ENCRYPT/ will invoke the algorithim specified by the 
  212.    DEFAULT_ENCRYPTION parameter (specified in section 1).
  213.  
  214.  
  215.  b) Using an advanced option
  216.    Include in  the "advanced options file" for this selector:
  217.       SET ENCRYPT method
  218.           or
  219.       SET ENCRYPT 0     (to override any !ENCRYPT special directive)
  220.  
  221.    For example:
  222.         SET ENCRYPT SRE_BFC
  223.  
  224.    If you do not specify a method, then the default method (as specified by
  225.    the DEFAULT_ENCRYPTION parameter) will be used.
  226.  
  227.    Note that the "advanced options file" may be from a wildcarded entry, 
  228.    in ACCESS.IN, that matches the selector. Please see ADV_OPTS.DOC
  229.    for further dicussion of advanced options files.
  230.   
  231.  
  232. Note: for a discussion of how to specify a custom algorithim, 
  233.          please see section III.
  234.  
  235.  
  236. ** II.4) Providing client-side decryption tools
  237.  
  238. After the server sends the encrypted response, the client has to
  239. have some way of decrypting it.  The default
  240. methods offer different means for accomplishing this 
  241. decryption.
  242.  
  243. II.4a) SRE_A and SRE_B commonalities
  244.  
  245. The SRE_A and SRE_B methods use a similar "randomization" technique:
  246.  
  247. a) SRE-http generates a "nonce", consisting of the time and the client's
  248.    ip address.
  249. b) The client's "shared-secret" password is appended to this nonce -- the
  250.    result is the "encryption key" (this assumes that that client has 
  251.    a ?ENCRYPT:password "secret privilege")
  252. c) An MD5 hash is generated from this encryption key.  A verifier is
  253.    extracted from this hash. In addition, a random number seed
  254.    is also extracted from the hash.
  255. d) The random number seed is used to generate a series of random numbers.
  256.    These are used to randomize the response.
  257. e) This randomized response is sent to the client.
  258.  
  259. To decrypt the response, the client must replicate these steps, using
  260. the nonce (which is included in the response), and her shared-secret password,
  261. to generate an MD5 hash from which the random number seed is extracted.
  262.  
  263. SRE_A and SRE_B use different strategies to enable this client side
  264. decryption:
  265.  
  266.   SRE_A)  An external program is run, which decrypts the response
  267.           and either writes the decrypted response to a file, or
  268.           displays it in a new browser window
  269.   SRE_B)  The encrypted response is embedded in an html document containing a
  270.           javascript program. This javascript program will ask the
  271.           client for her password, decrypt the file, and then
  272.           display this decrypted response in a new window.
  273.  
  274.  
  275. II.4b) SRE_A
  276.  
  277. SRE_A requires an external program. In particular, the DE_SREA.CMD program
  278. (which is installed in the GoServe data directory) can be used by clients
  279. who have rexx interpreters on their machine -- basically, OS/2
  280. clients who are using NetScape.  
  281.  
  282. Although it can be run in a stand-alone mode, DE_SREA.CMD should be installed as 
  283. a NetScape plugin. DE_SREA.CMD contains detailed installation instructions on
  284. how to do this. Basically, the client should:
  285.  a) copy DE_SREA.CMD to an applications directory; say, D:\OS2\APPS
  286.  b) add a plug-in to netscape, using:
  287.      mimetype: application/x-encrypt_SRE_A
  288.      application: cmd.exe /c "D:\OS2\APPS\DE_SREA.CMD PWD:my_secret "
  289.         where my_secret is the client's "shared-secret"
  290.  
  291. After this installation, NetScape will call DE_SREA whenever a response has 
  292. the mimetype of application/x-encrypt_SRE_A.  DE_SREA will display some 
  293. info on the response, decrypt it, and then ask whether the response 
  294. should be displayed in a new NetScape window or whether it should be saved 
  295. to a file.
  296.  
  297. II.4c) SRE_B
  298. SRE_B requires a javascript capable browser.  
  299. SRE_B has the advantage of simplicity -- you do NOT need to distribute (and
  300. instruct clients in the installation) of an operating system specific plug-in.
  301. The disadvantage is that it is much slower then SRE_A (about 10x slower).
  302. SRE_B uses the ENC_SREB.RSP file (which should be located in the, possibly
  303. host-specific, data directory) to create this javascript containing response. 
  304. You can customize this "response" file, just be careful about non-changeable
  305. code!
  306.  
  307.  
  308. II.4d) SRE_BF and SRE_BFC
  309.  
  310. The SRE_BF and SRE_BFC "BlowFish" methods require that the client have
  311. some kind of BlowFish executable.  There may be plugins for NetScape, IE,
  312. etc.that will run BlowFish for the client.  Lacking that, the DE_SREBF.CMD
  313. REXX program can be used to facilitate (on OS/2, or other REXX capable
  314. machines) the use of BlowFish.
  315.  
  316. For details on DE_SREBF.CMD, please see the comments in DE_SREBF.CMD.
  317.  
  318.                         ------------------
  319.  
  320. III) Custom encryption
  321.  
  322. If desired, you can write your own encryption procedure (say, a Java based
  323. procedure based on PGP). To incorporate this into SRE-http, the following
  324. step are required:
  325.  
  326. a) Create (and load) a macrospace procecdure named SREF_CUSTOM_ENCRYPT. 
  327.    If you are implementing more then one custom procecure, SREF_CUSTOM_ENCRYPT
  328.    will need to implement all the various encryption algoritims (or call an
  329.    appropriate set of procedures).
  330.  
  331. b) This procedure should return the following (seperated by '0d0a'x):
  332.     i) the mime-type
  333.    ii) the content encoding
  334.   iii) the encrypted response
  335.  
  336.   That is, the following will be used to parse the reponse:
  337.        parse var stuff mimetype (crlf) content_encoding (crlf) stuff
  338.  
  339.   For example, SRE_A returns:
  340.         'application/x-encrypt_SRE_A'||crlf||'Encrypt_SRE_A'||crlf||response
  341.  where:
  342.       cflf='0a0a'x
  343.       response is the encrypted response (which might contain may crlfs)
  344.  
  345. c) You'll need to arrange a mechanism (i.e.; a seperate plug in, or embedded
  346.    code) that will help the client decrypt the response.
  347.  
  348.  
  349.                         ------------------
  350.  
  351.  
  352. IV) Encrpyting FORMS submitted by clients.
  353.  
  354. In order to allow clients to submit encrypted information, SRE-http
  355. provides a javascript based procedure that will encrypt elements in
  356. an HTML form. These encrypted elements will be then be sent to
  357. the server, and the server will then decrypt them for further
  358. processing.
  359.  
  360. This is a several step process:
  361.    1) Include (using an INCLUDE ssi) the ENC_RESP.RSP javascript procedures
  362.       in an HTML document that contains a FORM (with elements you wish
  363.       to encrypt).
  364.    2) specify a hidden element with name="nonce"
  365.       and a hidden element with name="verify"     
  366.    3) Using a TEXT element, get a "shared-secret" password, and then 
  367.       call the comp_md5 javascript procedure to generate an encryption key
  368.    4) Specify some hidden elements that will contain the encrypted variables
  369.    5) Include some non-hidden form elements (such as TEXT, TEXTAREA, and SELECT), 
  370.       and encrypt their values using  do_encrypt javascript procedure
  371.    6) clear the raw (unencrypted) variables (that is, the raw versions
  372.       of the variables you encrypted in step 5) using the clear_fields
  373.       javascript procedure
  374.    7) Submit the form -- the script on the server will have to
  375.       decrypt (using SREF_FORM_DECRYPT) the encrypted
  376.       variables (that were set in 4 and 5)
  377.  
  378. ENC_TEST.RSP contains further details on each of these steps.
  379.  
  380. Notes:
  381.  
  382.   *  ENC_TEST.HTM and ENC_TEST.CMD demonstrate SRE-http's 
  383.      client-side encryption of form elements.
  384.  
  385.   *  The encryption algorithim used is essentially the same as SRE_B --
  386.      it uses a 40 bit key, hence can not be considered secure against
  387.      sophisicated attack.
  388.  
  389.                         ------------------
  390.  
  391. V) Comparing the default encryption algorithims
  392.  
  393. None of the several encryption algorithims are perfect. The
  394. following lists their strengths and weaknesses. Note that in
  395. all cases, clients requesting encyrpted resources must be
  396. "registered" -- which will require some parallel means of
  397. communicating passwords and other client-specific attributes.
  398.  
  399. SRE_A:
  400.    Speed: Moderate -- adequate for responses less then 25k.
  401.    Security: Moderate (40 bit) -- will not stop determined/well-equipped
  402.              crackers
  403.    Limitations: None
  404.    Client-side ease of use: Somewhat demanding.
  405.                    Client must obtain and install the DE_SREA.CMD
  406.                    program; which requires REXX. 
  407.    Recommendation: best used when you know your clients are OS/2 users.
  408.         
  409. SRE_B:
  410.    Speed: Slow  -- adequate for responses less then 5k.
  411.    Security: Moderate (40 bit) -- will not stop determined/well-equipped
  412.              crackers
  413.    Limitations: None
  414.    Client-side ease of use: Fairly easy.  Client has to have a 
  415.                    javascript enabled browser.
  416.    Recommendation: best used to return short responses to a variety
  417.                    of cients.
  418.  
  419. SRE_BF and SRE_BFC:
  420.    Speed: Fast  -- large (>100k) responses are quickly encrypted and
  421.                    decrypted
  422.    Security: Stronge (128+ bit) -- with adequately long "shared-secrets"
  423.              (say, 10 or so characters), will probably stop all but the
  424.              most sophisticated crackers.
  425.    Limitations: Export restrictions mean that both servers and clients
  426.                 are responsible for obtaining blowfish executables. 
  427.                 Howver, this is not difficult to do, they can readily be
  428.                 found on the WWW.
  429.    Client-side ease of use: Mediocre. Client must obtain an operating
  430.                             system specific version of BlowFish, and be 
  431.                             satisified with saving responses to a disk file.
  432.                             However, 
  433.                               * BlowFish is gaining acceptance, and there may be
  434.                                 BlowFish capable plug-ins for the major
  435.                                 browsers in the near future. Also,
  436.                               * the DE_SREBF program can be used (by clients
  437.                                 with REXX capable machines) to decrypt & display
  438.                                 SRE_BF and SRE_BFC encrypted files.
  439.    Recommendation: best used when security is important, and clients
  440.                    are capable of obtaining and using BlowFish executables.
  441.                    
  442.    Note: SRE_BF and SRE_BFC differ only in that SRE_BFC will compress
  443.          before encrypting. This is a very nice feature, but
  444.          may not be supported by all implementation of BlowFish.
  445.  
  446.  
  447. Vi) Notes
  448.  
  449.   * PUBLIC_URLS are NEVER encrypted.
  450.  
  451.   * For more information on BlowFish, see 
  452.         http://www.counterpane.com/blowfish.html
  453.     
  454.   
  455.  
  456.