----------------------- Lab #02 for CST8165 due February 11, 2008 (Week 6) ----------------------- -Ian! D. Allen - idallen@idallen.ca - www.idallen.com Remember - knowing how to find out an answer is more important than memorizing the answer. Learn to fish! RTFM! (Read The Fine Manual) Global weight: 4% of your total mark this term. Interim submission: Submit what you have done so far in lab on February 4. Due date: before 16h00 Monday, February 11. Interim submissions in Week 5: You will submit whatever progress you have made on this assignment before the end of your weekly lab period in Week 5. The deliverables for this exercise are to be submitted online in the Linux Lab T127 using the "cstsubmit" method described in the exercise description, below. No paper; no email; no FTP. Late-submission date: I will accept without penalty exercises that are submitted late but before 16h00 on Tuesday, February 12. After that late-submission date, the exercise is worth zero marks. Exercises submitted by the *due date* will be marked online and your marks will be sent to you by email after the late-submission date. You will submit whatever progress you have made in-lab on February 4. The program does not have to work. Submit whatever you have done. If you have code that works at the interim submission lab, I am available to pre-test your code and check for bugs. Exercise Synopsis and Objectives: 1. Review the pseudocode and sample code for a simple TCP/IP client. 2. Create a simple TCP/IP connect() port scanner client "from scratch". 3. Test it thoroughly. Coding and submission standards: - provide File Headers (Program Headers) using my Assignment Label - provide Function Headers documenting arguments and return values - use Block Comments (see programming_style.txt) - error messages must have the four-part format from programming_style.txt Where to work: Submissions must make, compile, and run cleanly in the T127 Linux Lab, though you are free to work on them anywhere you like. Since this course has no textbook, use the Internet instead: Background tutorial on using client sockets: The Sockets Tutorial: http://www.cs.rpi.edu/academics/courses/fall96/sysprog/sockets/sock.html (alternate: http://www.linuxhowtos.org/C_C++/socket.htm ) Beej also has a line-by-line socket programming tutorial here: http://beej.us/guide/bgnet/ The simple client code is here: http://beej.us/guide/bgnet/output/html/singlepage/bgnet.html#simpleclient Another client: http://linux.omnipotent.net/article.php?article_id=5424 Warning: You are creating a port scanner. Do *NOT* scan any ports outside of the Linux Lab unless you have permission! You risk blacklisting the entire College IP address if you scan ports out on the Internet. Part I - design the program and test suite ------------------------------------------ Design a TCP/IP subnet open port connection scanner and a test suite to test it. The command line calling sequence looks like this: ./scanner startIP endIP startPort endPort For example: $ ./scanner 10.50.15.101 10.50.15.131 1 65535 $ ./scanner 192.168.1.1 192.168.2.255 80 80 The program will try to connect() to the given TCP ports on all the IP addresses that lie between the given arguments (inclusive). For each IP address in the range that has at least one open port, it will report which ports are open (which connect() calls succeeded) for that IP address. No data will be output for addresses with no ports open. For a successfully opened port, your program will send a single newline to the port and then close only the writing half of the connection (using the shutdown() system call). You will read whatever response comes back. If no response comes back within a few seconds (configurable), skip that port and move on to the next one. If a response comes back, translate the response into printable characters and display it on standard output. Indicate which host and port it came from. Your program must not block for more than a few seconds (configurable) on any I/O operation to the remote system. The program must validate all input arguments and issue proper four-part error messages on detected errors (see programming_style.txt). Hint: port numbers are 16-bit unsigned numbers. Your test suite document named "README.txt" must document the tests that will be used (including the tests of input validation). Part II - code your design -------------------------- Code your design using the low-level C language system call functions socket() and connect(). You may implement your scanner design based on code taken from the Internet; however, you are responsible for understanding your design and knowing how to write the code from scratch. You must be able to explain exactly how the scanner operates (the detailed pseudocode) and how the code works (the implementation). You must be able to design and write the code from scratch (e.g. on a test or exam). You must credit the source of the used code in your program and your documentation. Failure to credit will result in charges of plagiarism and/or academic fraud. Credit your sources! This is not a group project. You may not base your code on code written by other students. Do your own design and implementation work. You must improve the quality of any imported code to document it and fix any indentation errors and bad choices of variable names. One quick way to fix program layout is the command "indent -kr -i8 *.c"; but, you may want to add more options to treat comments differently. Review: http://lxr.linux.no/source/Documentation/CodingStyle You will find these routines useful: inet_ntop, inet_aton (Be sure to avoid obsolete and deprecated functions here!) As an application programmer, what control does your application have over the lower-level TCP/IP layers in Unix/Linux? - you can set options on the sockets you open that affect the TCP/IP stack - "man 7 socket" setsockopt(2) and getsockopt(2) - SO_KEEPALIVE - SO_RCVTIMEO and SO_SNDTIMEO (useful in port scanning) - SO_BINDTODEVICE - SO_REUSEADDR (you already used this in an earlier lab) - SO_DONTROUTE - SO_BROADCAST - SO_LINGER - SO_PRIORITY The SO_SNDTIMEO and SO_RCVTIMEO can be used in a port scanner to reduce the amount of time that the program waits for a reply from a blocked port (a port that issues no ICMP "connection refused" error), or from a machine that does not exist, or from a port that is open but doesn't send any data. Part III - The Tests - README.txt, testing.txt -------------------- Do not scan ports outside the Linux Lab! Prove that your program works for all command line inputs. Show how each error message can be triggered. Use the README.txt file (use that exact name) to document clearly your choice of test cases and results. Use the testing.txt file (use that exact name) for any actual documentation of test runs. Remember that you can use netcat to open ports in "listen" mode, to test that your program finds these open ports. Capturing the tests using a script session ------------------------------------------ 1) Start a "script" session (man script) using my script cover and with output file "testing.txt": $ ~alleni/bin/script testing.txt This will save your terminal command lines and output into the given file name. Make sure you use my cover script, as shown above. Note: Your output file "testing.txt" will not contain the full results of your script session until you exit the subshell started by the script command. When you exit the subshell, script will tell you the name of the output file. See the next few steps: 2) Test your program, using the test plan you designed above. 3) Exit the script session subshell. Script will tell you the name of your script output file: $ exit Script done, file is testing.txt $ less testing.txt You may now examine your saved script session. 4) In a file named "README.txt", summarize briefly the results of your testing. If anything did not work properly, document which tests failed. If everything worked, say so. 5) Submit the files using the exact file names given below. Make sure you submit *all* the files needed to compile your scanner! Submission ---------- A. At the top of each and every submitted file, as comments, create an Exterior Assignment Submission label following the directions from last week's lab. Every file must have a label; use comments as needed. B. For material you copy from other sources, credit the author and source, following the directions from last week's lab. C. Submit all your source files for marking as Exercise 02 using the following *single* cstsubmit command line: $ ~alleni/bin/cstsubmit 02 \ README.txt testing.txt Makefile scanner.c \ ...other source and header files as needed... See last week's lab for details on using cstsubmit. All file names must be spelled *exactly* as given above. Always submit *all* files any time you submit. Incorrect and past-cut-off-time submissions are worth zero marks. P.S. Did you spell all the assignment label fields and file names correctly?