ibe_help.txt

Help for IBE programs
Ben Lynn (blynn@cs.stanford.edu)

INTRODUCTION

Two binaries are provided, one to generate system parameters, and the other
to perform IBE operations.

QUICKSTART

The default configuration should be fine.
Encrypt messages to yourself by typing

ibe encrypt ID

where ID is your email address. (Throughout this section, ID will always
be your email address.)
It uses standard input/output, so you can encrypt a file by typing
something like:

ibe encrypt ID < plain.txt > cipher.txt

By now it is evident what the main advantage of IBE is: there is no need
to generate/retrieve a public key in order to encrypt.

Next, retrieve your private key share by typing:

ibe request ID

You'll be asked to make up a password.
Soon you should receive an email from the private key generator to that
address. Save it to a file "keyshare". Then type:

ibe combine ID keyshare

You'll need the password you just made up for this to work, and it will
then ask you for another password.
Now you can decrypt the message you encrypted to yourself by typing:

ibe decrypt ID < cipher.txt

(You'll need to enter the password for your private key which you concocted
in the previous step.)

You should also be able to decrypt the message sent to you on the IBE
homepage (in the Try IBE section).

DETAILS

Configure the system parameters generator, gen, by editing gen.cnf.
If run, it will output a file containing new system parameters and secret
shares for PKG's to use.

Configure ibe by editing ibe.cnf. To use the program, type

ibe <command> <args>

on the command-line. At the moment the commands are:

encrypt

    Once system parameters are available (they can be generated by the gen
    program or obtained elsewhere), the encrypt command can be used (recall
    in an IBE scheme, any string is a public key). So for example, typing:

    ibe encrypt Alice

    will encrypt the standard input using the public key "Alice".
    The ciphertext is printed on standard output.

request

    The request command requests the private key for a given ID.
    For example,

    ibe request Bob@foo.bar

    will send the server(s) (configured in ibe.cnf) requests for parts of
    Bob's private key. They will be emailed to the address provided on the
    command-line (i.e. the ID).

combine

    The combine command combines files given out by private key generators into
    a private key. For example, if Bob has received the file "file" from a PKG,
    and only one file is needed to make a private key (this depends on the
    system parameters), he can type

    ibe combine Bob@foo.bar file

    to recover his private key. If there were more than one file, he types

    ibe combine Bob@foo.bar file1 file2 ...

decrypt

    Once the private key has been recovered (it is saved to a file
    automatically; the filename is read from the config file),
    the decrypt command may be used as follows:

    ibe decrypt Alice

    It takes the ciphertext on standard input and outputs the corresponding
    plaintext on standard output.

extract_share
    
    This simulates what a PKG would do. If you have run gen to obtain
    a master share, then run

    ibe extract_share Alice mastersharefile

    to obtain a key share for Alice corresponding to the given master share.
    These key shares can be combined with the combine command to construct
    a private key.

key_from_master_shares

    This is intended for testing only; in real life, the master shares should
    never reside on the same server. Type

    ibe key_from_master_shares Alice mastersharefile1 mastersharefile2 ...

    to recover Alice's private key.

imratio

    The imratio command is a benchmarking tool, which was used to find the
    relative cost of inversions and multiplications. It is not needed by the
    end user, but I'm interested in what values various machines report for
    the I/M ratios.