What Is Bistro?
Bistro is a scalable and secure system for uploading data through the Internet. It is under development at the University of Southern California under the direction of Professor Leana Golubchik.

Bistro uses a client-sever architecture. The purpose of this document is to describe how the client submission software (bsubmit) works with the Bistro server.

The Bistro Server
One of the features we use in Bistro for programming assignment submissions is that the Bistro serve can give secure timestamps. The timestamps a Bistro server issues is secure because it is digitally signed by the Bistro server and this digital signature cannot be forged and can be digitally verified.
The Client Submission Software
The client submission software (bsubmit) uses various cryptographics techniques in submitting a piece of data (i.e., a programming assignment submission) to a Bistro server. It does this in the following steps.
  • The user runs the client submission software (bsubmit) and specifies an e-mail address for receiving notifications that a submission has been successfully collected for grading.

    Please note that you will not get an e-mail from the server for every submission.

  • Bsubmit also applies a one-way-hash function to a submission to produce a message digest for the submission. The one-way-hash function it uses has the property that another submission which is slightly different (e.g., different by a single bit) from the original submission will generate a completely different message digest. Effectively, the hash value is like a digital fingerprint of your submission.

  • The client submission software (bsubmit) sends the message digest to a Bistro server and the server issues a digitally signed secure timestamp (known as a ticket). Bsubmit verifies that the ticket has a good digital signature and reports the time (time on the server) on the ticket This way, the user can know if the submission made the deadline. This ticket is your proof that your submission has made the deadline.

  • The ticket and a copy of the submitted data are stored somewhere in the .bistro subdirectory of the user's home directory. The locations of the ticket and the copy of the submission are reported to the user by bsubmit.

  • Bsubmit then encrypts and upload the data to the Bistro server that issued the timestamp. The server decrypts and re-applly the one-way-hash function to verify that the message digest of the submitted data matches what it got earlier on. If it matches, the server generates a receipt and returns it to bsubmit. Bsubmit stores the receipt and report the location of the receipt to the user.

  • The data sits on the server until the instructor (or the TA) collectes them (after the deadline). Since you can make multiple submissions, a notification e-mail will be sent to you letting you know which submission was downloaded for grading.

  • There can be no dispute whether a submission has made the deadline or not. Even if a submission which has made the deadline but somehow got lost at a later time, the user can simply e-mail the copy of the submission along with the ticket, stored in the user's ~/.bistro directory to the instructor.

    Since the server has a copy of the message digest of the submission, the instructor can easily verifies if the ticket is valid and the submission was original.

The syntax of running bsubmit is (bold face text must be entered exactly):
    ~csci551b/bin/bsubmit command [OPTIONS]
where command can be either config, upload, or records.

Currently, the only configurable parameter is the user's e-mail address. If you like all notifications to be e-mailed to johndoe@usc.edu, you can configure bsubmit to remember your e-mail address by running:

    ~csci551b/bin/bsubmit config -set email=johndoe@usc.edu
For the upload command, possible options are:
    -event event_id
    -file file_to_upload
    -email your_email_address
The event_id is an identifier for a upload event; it is usually a long string of alphanumeric characters. The file_to_upload is usually a .tar.gz file which is what you are submitting to the server. You can override the e-mail address you have specified with the config command previously using the -email option.

For the records command, the only possible option is:

    -event event_id
where event_id is an identifier for a upload event.
Sample Outputs
If you get the following message:
    Cannot start bsubmit without your e-mail address.
    Please run bsubmit with '-email'.
This means that you have not configure your e-mail address. Simply do:
    ~csci551b/bin/bsubmit config -set email=you@yourdomain
the try again.

If you get the following message when you run bsubmit for the first time:

    unable to load 'random state'
    This means that the random number generator has not been seeded
    with much random data.
    Consider setting the RANDFILE environment variable to point at a file that
    'random' data can be kept in (the file will be overwritten).
    27743:error:24064064:random number generator:SSLEAY_RAND_BYTES:PRNG not
    seeded:md_rand.c:538:
    10365 semi-random bytes loaded
Don't worry, the random number generator is automatically initialized in bsubmit. You should only see this message once.

A normal submission should look something like:

    ( 1) Verification Successful
    ( 2)     The timestamped upload ticket (which has been successfully verified) for
    ( 3)     this submission has been placed in 24.bti in the following directory:
    ( 4)         ~/.bistro/tickets/bourbon.usc.edu_9996_999033362_2
    ( 5)     A copy of your submission has been placed in 24.dat in the
    ( 6)     following directory:
    ( 7)         ~/.bistro/tickets/bourbon.usc.edu_9996_999033362_2
    ( 8)     The timestamp (time at the server) is '29Aug2001-14:24:57'.
    ( 9) Verification Successful
    (10)     The receipt (which has been successfully verified) for this submission
    (11)     has been placed in bourbon.usc.edu_9996_999033362_15.bri
    (12)     in the following directory:
    (13)         ~/.bistro/tickets/bourbon.usc.edu_9996_999033362_2
    (14)     The encrypted submission has been placed in
    (15)     bourbon.usc.edu_9996_999033362_24 in the following directory:
    (16)         ~/.bistro/commits/bourbon.usc.edu_9996_999033362_2

Lines (1) and (9) says that some digital signatures have been verified (these two lines may or may not appear in the output). Lines (2) through (4) gives the location of the ticket (or the upload ticket). Lines (5) through (7) gives the location of the copy of the submission. Line (8) tells you if your submission has made the deadline. Lines (10) through (13) gives the location of the receipt. Lines (14) through (16) gives the location of an encrypted copy of your submission (you will not be able to decrypt this file because you don't have the decryption keys).

A typical ticket (which is a text file that you can open with a text editor) looks like the following:

    MIME-Version: 1.0
    Content-Type: multipart/signed ;
        protocol="application/x-pkcs7-signature" ;
        micalg=sha1 ;
        boundary="----B3D7DE4A3A337FD8C0DAC10F10512AA1"

    This is an S/MIME signed message

    ------B3D7DE4A3A337FD8C0DAC10F10512AA1^M
    [ticket]
    format_version=1.0
    type=simple
    ticket_id=24
    evid=bourbon.usc.edu_9996_999033362_2
    user_email=bill.cheng@acm.org
    client_ip=128.8.10.52
    hash_algorithm=sha1
    hash_value=24ba6f82b6b6b12abb553dd6c688b04891dfeea8
    random_value=f4220de784cd1d617af1bdc72fbf1504eabcecab
    file_size=3679
    file_name=/tmp_mnt/home/fcmsc420wc/wc42003/out.ps.gz
    userid=wc42003
    server_id=bourbon.usc.edu_9996_999033362
    server_time=999109497
    server_time_string=29Aug2001-14:24:57

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ; Do NOT delete this file.  This ticket file is PROOF ;
    ; that your submission with the above hash value was  ;
    ; received by the server at the time indicated by the ;
    ; server_time_string above.  Also, please do NOT      ;
    ; alter this file.                                    ;
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

    ------B3D7DE4A3A337FD8C0DAC10F10512AA1
    Content-Type: application/x-pkcs7-signature; name="smime.p7s"
    Content-Transfer-Encoding: base64
    Content-Disposition: attachment; filename="smime.p7s"

    MIAGCSqGSIb3DQEHAqCAMIICGwIBATELMAkGBSsOAwIaBQAwgAYJKoZIhvcNAQcB
    AAAxggH4MIIB9AIBATCBnTCBlzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1EMQsw
    CQYDVQQHEwJDUDEMMAoGA1UEChMDVU1EMSAwHgYDVQQLExdCaXN0cm8tMjhBdWcy
    MDAxLXJvb3RjYTEbMBkGA1UEAxMSYm91cmJvbi5jcy51bWQuZWR1MSEwHwYJKoZI
    hvcNAQkBFhJ3aWxsaWFtQGNzLnVtZC5lZHUCAQIwCQYFKw4DAhoFAKCBsTAYBgkq
    hkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0wMTA4MjkxODI0
    NTdaMCMGCSqGSIb3DQEJBDEWBBTa/47BM2Rb26wvDh/ecNs8ZpCA4DBSBgkqhkiG
    9w0BCQ8xRTBDMAoGCCqGSIb3DQMHMA4GCCqGSIb3DQMCAgIAgDANBggqhkiG9w0D
    AgIBQDAHBgUrDgMCBzANBggqhkiG9w0DAgIBKDANBgkqhkiG9w0BAQEFAASBgC63
    3xyFrBhTdXPwKwJExcA6MvPbhiXfdvXxwamdn20Mw/Kh7Esv3DmUQYIhYNaehrsF
    AQWB0H6Atbriod06kksIQfZ5T3tbg/89FO2QWX2dRuIKuHyji47HwcNZMpf+7A2M
    Dsn8jDtX+6M+e3ZsqlGTB5eE1WvKUXz9NcqW7HwwAAAAAA==

    ------B3D7DE4A3A337FD8C0DAC10F10512AA1--
    
The top section of the ticket is just a header and the last section of the ticket is a digital signature. The middle part contains the information about the submission and the timestamp. A few things to note:
  • The hash_algorithm is the name of the one-way-hash function.
  • The hash_value is the message digest.
  • The server_time_string is the timestamp.

A receipt (which is also a text file that you can open with a text editor) also has a header and a digital signature. The middle part of a receipt looks like the following:

    [receipt]
    format_version=1.0
    type=simple
    receipt_id=15
    long_ticket_id=bourbon.usc.edu_9996_999033362_24
    evid=bourbon.usc.edu_9996_999033362_2
    user_email=bill.cheng@acm.org
    client_ip=128.8.10.52
    hash_algorithm=sha1
    enc_file_hash_value=f00540eb3643e77c2f91d607b20f7e0080bbed16
    encrypted_file_size=5670
    server_id=bourbon.usc.edu_9996_999033362
    server_time=999109497
    server_time_string=29Aug2001-14:24:57

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ; Do NOT delete this file.  This receipt file is      ;
    ; PROOF that your encrypted submission with the above ;
    ; hash value was received by a server (identified by  ;
    ; server_id above) at the time indicated by the       ;
    ; server_time_string above.  Also, please do NOT      ;
    ; alter this file.                                    ;
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    
The content of the receipt is not so important! If you do not get a receipt from the server, something may be wrong. If this happens often, please send a bug report.
On nunki.usc.edu, a copy of each of your submission is placed in your:
    ~/.bistro/tickets/EVID
directory where EVID is the event ID that corresponds to your submissions (which is mentioned inside a box at the bottom of every programming assignment spec). Change directory into that directory and do:
    grep "server_time_string=" *.bti
to see the timestamps of all your submissions. This will tell you which ticket file (a .bti file) corresponds to which submission. Then the corresponding .dat file in the same directory is an exact copy of your submission. (So, if you have submitted a .tar.gz file, this file will be in the .tar.gz format.)

Please be VERY CAREFUL when you are in that directory (or any directory in ~/.bistro)! If you accidentically delete or change any files there, you may have lost some very important information.

You can also run the following command to get a summary of your submissions for a particular event:

    ~csci551b/bin/bsubmit records -event event_id
The event_id is the string you used right after the "-event" commandline argument of the bsubmit command you used to make a submission (which you can find at the bottom of each programming assignment spec).
Bugs?
The Bistro system is under development. If you see anything that looks like a bug, please send e-mail to Bill Cheng with a detailed description.