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 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.

    ~csci551b/bin/bsubmit command [OPTIONS]

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

    -event event_id
    -file file_to_upload
    -email your_email_address

For the records command, the only possible option is:

    -event event_id

    Cannot start bsubmit without your e-mail address.
    Please run bsubmit with '-email'.

    ~csci551b/bin/bsubmit config -set email=you@yourdomain

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

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 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.                                    ;
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    

    ~/.bistro/tickets/EVID

    grep "server_time_string=" *.bti

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