RxBlFish Manual: Difference between revisions

From OS2World.Com Wiki
Jump to navigation Jump to search
No edit summary
mNo edit summary
Line 1: Line 1:
By [[Michal Necasek]] and [[Daniel Hellerstein]] - 25 Feb 2003.
''By [[Michal Necasek]] and [[Daniel Hellerstein]]'' - 25 Feb 2003.
 


RxBlFish: An OS/2 REXX interface to BlowFish
RxBlFish: An OS/2 REXX interface to BlowFish


==Summary:==
==Summary:==
BlowFish is a very powerful encryption tool. RxBlFish provides  an OS/2 REXX interfact to BlowFish -- with RxBlFish, you can use REXX to encrypt strings and files.
BlowFish is a very powerful encryption tool. RxBlFish provides  an OS/2 REXX interfact to BlowFish - with RxBlFish, you can use REXX to encrypt strings and files.
 
NOTE: This is an update version 1.01 (released in 1999) -- it fixes a serious bug that occurs when changing keys under a single process.


NOTE: This is an update version 1.01 (released in 1999) - it fixes a serious bug that occurs when changing keys under a single process.


==I. Requirements==
==I. Requirements==
To use RxBlFish, you must have version 1.62 (or above) of BlowFish for OS/2. In particular, you need ENCRYPT.DLL  from  version 1.62 (or above).


To use RxBlFish, you must have version 1.62 (or above) of BlowFish for OS/2.
Due to U.S. export regulations, we can not include ENCRYPT.DLL in this distribution. You'll have to obtain it yourself.
In particular, you need ENCRYPT.DLL  from  version 1.62 (or above).
 
Due to U.S. export regulations, we can not include ENCRYPT.DLL in this
distribution. You'll have to obtain it yourself.


* U.S. users can find BlowFish for OS/2 on hobbes (http://www.hobbes.nmsu, search for Blowfish).
* U.S. users can find BlowFish for OS/2 on hobbes (http://www.hobbes.nmsu, search for Blowfish).
Line 22: Line 17:
**http://www.mirror.ac.uk/sites/hobbes.nmsu.edu/pub/os2/util/encrypt/bfish163.zip and
**http://www.mirror.ac.uk/sites/hobbes.nmsu.edu/pub/os2/util/encrypt/bfish163.zip and
**ftp://ftp.flashnet.it/pub/hobbes.nmsu.edu/pub/os2/util/encrypt/bfish163.zip
**ftp://ftp.flashnet.it/pub/hobbes.nmsu.edu/pub/os2/util/encrypt/bfish163.zip
                        
                        
==II. Installation==
==II. Installation==
a) Unzip RXBLFISH.ZIP to an empty temporary directory.
a) Unzip RXBLFISH.ZIP to an empty temporary directory.


Line 32: Line 25:
c) Copy RXBLFISH.DLL and ENCRYPT.DLL to a directory in your LIBPATH. For example, to x:\OS2\DLL (where x: is your boot drive).
c) Copy RXBLFISH.DLL and ENCRYPT.DLL to a directory in your LIBPATH. For example, to x:\OS2\DLL (where x: is your boot drive).
    
    
That's it -- except for writing a REXX program that calls the procedures in RXBLFISH... as described below.
That's it - except for writing a REXX program that calls the procedures in RXBLFISH... as described below.
 
 
                     
==III. Usage==
==III. Usage==
RXBLFISH contains the following procedures:
RXBLFISH contains the following procedures:
 
rxBfGetVersion  Get the "version number"
  rxBfGetVersion  Get the "version number"
rxBfSetVeration  Set the "version number"
  rxBfSetVeration  Set the "version number"
rxBfInitialise  Initialise an encryption key
  rxBfInitialise  Initialise an encryption key
rxBfEncrypt      Encrypt a string or a file
  rxBfEncrypt      Encrypt a string or a file
rxBfDecrypt      Decrypt a string or a file
  rxBfDecrypt      Decrypt a string or a file
 
To load these functions, you can use:
To load these functions, you can use:
call RxFuncAdd 'rxBfGetVersion', 'RXBLFISH', 'rxBfGetVersion'
call RxFuncAdd 'rxBfSetVersion', 'RXBLFISH', 'rxBfSetVersion'
call RxFuncAdd 'rxBfInitialise', 'RXBLFISH', 'rxBfInitialise'
call RxFuncAdd 'rxBfEncrypt',    'RXBLFISH', 'rxBfEncrypt'
call RxFuncAdd 'rxBfDecrypt',    'RXBLFISH', 'rxBfDecrypt'
Note that you MUST have ENCRYPT.DLL in LIBPATH (or in the default directory) - these RXBLFISH procedures call procedures in ENCRYPT.DLL, but they do NOT elegantly detect if ENCRYPT.DLL is not available.


  call RxFuncAdd 'rxBfGetVersion', 'RXBLFISH', 'rxBfGetVersion'
Before using rxBfEncrypt or rxBfDecrypt, you must "initialise" a key (using rxBfInitialise).
  call RxFuncAdd 'rxBfSetVersion', 'RXBLFISH', 'rxBfSetVersion'
  call RxFuncAdd 'rxBfInitialise', 'RXBLFISH', 'rxBfInitialise'
  call RxFuncAdd 'rxBfEncrypt',    'RXBLFISH', 'rxBfEncrypt'
  call RxFuncAdd 'rxBfDecrypt',    'RXBLFISH', 'rxBfDecrypt'
 
Note that you MUST have ENCRYPT.DLL in LIBPATH (or in the default directory)-- these RXBLFISH procedures call procedures in ENCRYPT.DLL, but they do NOT elegantly detect if ENCRYPT.DLL is not available.
 
Before using rxBfEncrypt or rxBfDecrypt, you must "initialise"
a key (using rxBfInitialise).


===III.a Description of procedures===
===III.a Description of procedures===
====rxBfSetVersion:  Set the "version number"====
====rxBfSetVersion:  Set the "version number"====
Syntax:   
Syntax:   
    status=rxBfSetVersion(nn)
status=rxBfSetVersion(nn)
Sets the "version number".
Sets the "version number".
  A non-zero return value indicates an error.
A non-zero return value indicates an error.


====rxBfGetVersion:  Get the "version number"====
====rxBfGetVersion:  Get the "version number"====
Syntax:   
Syntax:   
    status=rxBfSetVersion(nn)
status=rxBfSetVersion(nn)
Gets the "version number" (as was set by rxBfSetVersion)
Gets the "version number" (as was set by rxBfSetVersion)
    
    
====rxBfInitialise: Initialise a key====
====rxBfInitialise: Initialise a key====
Syntax:   
Syntax:
    status=rxBfInitialise(keyvalue)
  status=rxBfInitialise(keyvalue)
where
where
    keyvalue: a string containing an encryption key.
keyvalue: a string containing an encryption key.
 
For example:
For example:
call rxBfInitialise('the key')
    call rxBfInitialise('the key')
Note that this string can be of any length (though it has not been tested with strings greater then 80 characters long).


Note that this string can be of any length (though it has not been tested with strings greater then 80 characters long).
====rxBfEncrypt: Encrypt a string or a file====
====rxBfEncrypt:     Encrypt a string or a file====
Syntax:
Syntax:
      enc_stuff=rxBfEncrypt(file_or_string[,fileflag])
enc_stuff=rxBfEncrypt(file_or_string[,fileflag])
where:
where:
    fileflag is optional.  
fileflag is optional.
 
 
      fileflag=1 : file_or_string is interpreted as a file name.  
fileflag=1 : file_or_string is interpreted as a file name.
                    The file will be encrypted, with results saved
              The file will be encrypted, with results saved
                    back to file_or_string. That is, the file specified
              back to file_or_string. That is, the file specified
                    in file_or_string will be overwritten.
              in file_or_string will be overwritten.
                    A non-zero value of enc_stuff signal an error.
              A non-zero value of enc_stuff signal an error.
        fileflag=a file name (relative or fully qualified),
fileflag=a file name (relative or fully qualified),
                    The encrypted results are written to fileflag.  
            The encrypted results are written to fileflag.  
                    Thus, the file specified in file_or_string will NOT
            Thus, the file specified in file_or_string will NOT
                    be overwritten.
            be overwritten.
                    A non-zero value of enc_stuff signal an error.
            A non-zero value of enc_stuff signal an error.
        If fileflag is not specified
If fileflag is not specified File_or_string  is used as is, with results returned (to enc_stuff).
                    File_or_string  is used as is, with results  
                    returned (to enc_stuff).
   
   
Examples:
Examples:
      encstring = rxBfEncrypt("This is a test string to demo Blowfish encryption.")
encstring = rxBfEncrypt("This is a test string to demo Blowfish encryption.")
      encstring = rxBfEncrypt('foobar.txt',1)
encstring = rxBfEncrypt('foobar.txt',1)
      status = rxBfEncrypt('foobar.txt','foobar.enc')
status = rxBfEncrypt('foobar.txt','foobar.enc')
 
Note that you MUST call rxBfInitialise before calling rxBfEncrypt.     
Note that you MUST call rxBfInitialise before calling rxBfEncrypt.     


====rxBfDecrypt: Decrypt a string or a file====
====rxBfDecrypt: Decrypt a string or a file====
Syntax:
Syntax:
      dec_stuff=rxBfDecrypt(file_or_string[,fileflag])
dec_stuff=rxBfDecrypt(file_or_string[,fileflag])
where:
where:
 
fileflag is optional.  
    fileflag is optional.  
fileflag=1 : file_or_string is interpreted as a file name.  
        fileflag=1 : file_or_string is interpreted as a file name.  
              The file will be decrypted, with results saved
                    The file will be decrypted, with results saved
              back to file_or_string. That is, the file specified
                    back to file_or_string. That is, the file specified
              in file_or_string will be overwritten.
                    in file_or_string will be overwritten.
fileflag=a file name (relative or fully qualified),
        fileflag=a file name (relative or fully qualified),
          The decrypted results are written to fileflag.  
                    The decrypted results are written to fileflag.  
          Thus, the file specified in file_or_string will NOT
                    Thus, the file specified in file_or_string will NOT
          be overwritten.
                    be overwritten.
          A non-zero value of enc_stuff signal an error.
                    A non-zero value of enc_stuff signal an error.
If fileflag is not specified File_or_string  is used as is, with results returned (to dec_stuff).
        If fileflag is not specified
                    File_or_string  is used as is, with results  
                    returned (to dec_stuff).


==IV. Example==
==IV. Example==
<PRE>
<PRE>
call rxBfSetVersion(162)
call rxBfSetVersion(162)
Line 157: Line 131:
==V. Possible future changes==
==V. Possible future changes==
* support for compression
* support for compression
* a load procedure  
* a load procedure
 
 
 


[[Category:Software]]
[[Category:Software]]

Revision as of 23:37, 26 December 2017

By Michal Necasek and Daniel Hellerstein - 25 Feb 2003.

RxBlFish: An OS/2 REXX interface to BlowFish

Summary:

BlowFish is a very powerful encryption tool. RxBlFish provides an OS/2 REXX interfact to BlowFish - with RxBlFish, you can use REXX to encrypt strings and files.

NOTE: This is an update version 1.01 (released in 1999) - it fixes a serious bug that occurs when changing keys under a single process.

I. Requirements

To use RxBlFish, you must have version 1.62 (or above) of BlowFish for OS/2. In particular, you need ENCRYPT.DLL from version 1.62 (or above).

Due to U.S. export regulations, we can not include ENCRYPT.DLL in this distribution. You'll have to obtain it yourself.

II. Installation

a) Unzip RXBLFISH.ZIP to an empty temporary directory.

b) Obtain the latest version of the BlowFish (for OS/2) ENCRYPT.DLL (say, by obtaining bfish163.zip and unzipping bfish163 to an empty temporary directory)

c) Copy RXBLFISH.DLL and ENCRYPT.DLL to a directory in your LIBPATH. For example, to x:\OS2\DLL (where x: is your boot drive).

That's it - except for writing a REXX program that calls the procedures in RXBLFISH... as described below.

III. Usage

RXBLFISH contains the following procedures:

rxBfGetVersion   Get the "version number"
rxBfSetVeration  Set the "version number"
rxBfInitialise   Initialise an encryption key
rxBfEncrypt      Encrypt a string or a file
rxBfDecrypt      Decrypt a string or a file

To load these functions, you can use:

call RxFuncAdd 'rxBfGetVersion', 'RXBLFISH', 'rxBfGetVersion'
call RxFuncAdd 'rxBfSetVersion', 'RXBLFISH', 'rxBfSetVersion'
call RxFuncAdd 'rxBfInitialise', 'RXBLFISH', 'rxBfInitialise'
call RxFuncAdd 'rxBfEncrypt',    'RXBLFISH', 'rxBfEncrypt'
call RxFuncAdd 'rxBfDecrypt',    'RXBLFISH', 'rxBfDecrypt'

Note that you MUST have ENCRYPT.DLL in LIBPATH (or in the default directory) - these RXBLFISH procedures call procedures in ENCRYPT.DLL, but they do NOT elegantly detect if ENCRYPT.DLL is not available.

Before using rxBfEncrypt or rxBfDecrypt, you must "initialise" a key (using rxBfInitialise).

III.a Description of procedures

rxBfSetVersion: Set the "version number"

Syntax:

status=rxBfSetVersion(nn)

Sets the "version number".

A non-zero return value indicates an error.

rxBfGetVersion: Get the "version number"

Syntax:

status=rxBfSetVersion(nn)

Gets the "version number" (as was set by rxBfSetVersion)

rxBfInitialise: Initialise a key

Syntax:

status=rxBfInitialise(keyvalue)

where

keyvalue: a string containing an encryption key.

For example:

call rxBfInitialise('the key')

Note that this string can be of any length (though it has not been tested with strings greater then 80 characters long).

rxBfEncrypt: Encrypt a string or a file

Syntax:

enc_stuff=rxBfEncrypt(file_or_string[,fileflag])

where:

fileflag is optional.
fileflag=1 : file_or_string is interpreted as a file name.
             The file will be encrypted, with results saved
             back to file_or_string. That is, the file specified
             in file_or_string will be overwritten.
             A non-zero value of enc_stuff signal an error.
fileflag=a file name (relative or fully qualified),
           The encrypted results are written to fileflag. 
           Thus, the file specified in file_or_string will NOT
           be overwritten.
           A non-zero value of enc_stuff signal an error.

If fileflag is not specified File_or_string is used as is, with results returned (to enc_stuff).

Examples:

encstring = rxBfEncrypt("This is a test string to demo Blowfish encryption.")
encstring = rxBfEncrypt('foobar.txt',1)
status = rxBfEncrypt('foobar.txt','foobar.enc')

Note that you MUST call rxBfInitialise before calling rxBfEncrypt.

rxBfDecrypt: Decrypt a string or a file

Syntax:

dec_stuff=rxBfDecrypt(file_or_string[,fileflag])

where:

fileflag is optional. 
fileflag=1 : file_or_string is interpreted as a file name. 
             The file will be decrypted, with results saved
             back to file_or_string. That is, the file specified
             in file_or_string will be overwritten.
fileflag=a file name (relative or fully qualified),
         The decrypted results are written to fileflag. 
         Thus, the file specified in file_or_string will NOT
         be overwritten.
         A non-zero value of enc_stuff signal an error.

If fileflag is not specified File_or_string is used as is, with results returned (to dec_stuff).

IV. Example

call rxBfSetVersion(162)
say  rxBfGetVersion()

call rxBfInitialise('the key')

rc = rxBfEncrypt("This is a test string to show that the Blowfish encryption really works.")
say rc

rc = rxBfDecrypt(rc)
say "rxBFDecrypt status: " rc

rc = rxBfEncrypt('test.txt', 1)
say "rxBFEncrypt (of test.txt) status:" rc
rc = rxBfDecrypt('test.txt', 1)
say "rxBfDecrypt (of test.txt) status: " rc

rc = rxBfEncrypt('test.txt', 'test.enc')
say "Encrypt test.txt to test.enc, status=" rc
rc = rxBfDecrypt('test.enc', 'test.dec')
say "Decrypt test.enc, save results in test.dec. Status=" rc

V. Possible future changes

  • support for compression
  • a load procedure