USC CSD Home
 

Electronic Submission Using Bistro - CSCI 531, Spring 2013

 
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 class homework 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 homework 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):
    bsubmit upload -email YOUR_EMAIL -event EVENT_ID -file FILE_TO_UPLOAD
YOUR_EMAIL is the e-mail address where you would like to receive a notification e-mail when one of your submissions is downloaded for grading. EVENT_ID is a globally unique identifier for an upload event; it is usually a long string of alphanumeric characters. FILE_TO_UPLOAD is usually a .tar.gz file (if you are not familiar with UNIX, this is similar to a .zip file on a PC) which is what you are submitting to the server.
 
Sample Outputs
If you get a message looking like the following 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) The timestamped upload ticket (which has been successfully verified) for
    ( 2) this submission has been placed in "23.bti" in the following directory:
    ( 3)     ~/.bistro/tickets/bourbon.usc.edu_80_1291227186_12
    ( 4) A copy of your submission has been placed in "23.dat" in the
    ( 5) following directory:
    ( 6)     ~/.bistro/tickets/bourbon.usc.edu_80_1291227186_12
    ( 7) The timestamp (time at the server) is '01Jan2011-12:31:05'.
    ( 8) The receipt (which has been successfully verified) for this submission
    ( 9) has been placed in "bourbon.usc.edu_80_1291227186_18.bri"
    (10) in the following directory:
    (11)     ~/.bistro/tickets/bourbon.usc.edu_80_1291227186_12
    (12) The encrypted submission has been placed in
    (13) "bourbon.usc.edu_80_1291227186_23" in the following directory:
    (14)     ~/.bistro/commits/bourbon.usc.edu_80_1291227186_12

Lines (1) through (3) gives the location of the ticket (or the upload ticket) you got from the server. Lines (4) through (6) gives the location of a copy of your submission. Line (7) tells you if your submission has made the deadline. Lines (8) through (11) gives the location of the receipt you got from the server. Lines (12) through (14) 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 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 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.
 
Copy of All Your Submissions
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. 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.)
 
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.
 

[Last updated Sat Sep 19 2020]    [Please see copyright regarding copying.]