Merge pull request #67 from colmmacc/master

colmmacc · colmmacc · commit ebacbf628cca · 2015-04-03T15:03:17.000-07:00
Docs fixes: remove example server, spare parenthesis, add s2n_init/s2n_cleanup
diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md
@@ -114,7 +114,7 @@ we do:
 
     GUARD(s2n_foo());
     GUARD(s2n_bar());
-    GUARD(s2n_baz()));
+    GUARD(s2n_baz());
 
 This pattern leads to a linear control flow, where the main body of a function describes everything that happens in a regular, "*happy*" case. Any deviation is usually a fatal error and we exit the function. This is safe because s2n rarely allocates resources, and so has nothing to clean up on error. 
 
diff --git a/docs/USAGE-GUIDE.md b/docs/USAGE-GUIDE.md
@@ -176,6 +176,24 @@ failure. When an s2n function returns a failure, s2n_errno will be set to a valu
 corresponding to the error. This error value can be translated into a string 
 explaining the error by calling s2n_strerror(s2n_errno, "EN"); 
 
+## Initialization and teardown
+
+### s2n\_init
+
+    int s2n_init();
+
+**s2n_init** initializes the s2n library and should be called once in your application,
+before any other s2n functions are called. Failure to call s2n_init() will result
+in errors from other s2n functions.
+
+### s2n\_cleanup
+
+    int s2n_cleanup();
+
+**s2n_cleanup** cleans up any internal resources used by s2n. This function should be
+called from each thread or process that is created subsequent to calling **s2n_init**
+when that thread or process is done calling other s2n functions.
+
 ## Configuration-oriented functions
 
 ### s2n\_config\_new
@@ -452,7 +470,7 @@ connection. **s2n_recv** will return the number of bytes read and also return
             break;
         }
         bytes_read += r;
-    } while (more); 
+    } while (more);
 
 ### s2n_shutdown
 
@@ -463,197 +481,5 @@ connection. **s2n_recv** will return the number of bytes read and also return
 
 # Examples
 
-To understand the API it may be easiest to see examples in action.
-
-## Example server
-
-This example server reads a single HTTP request (over HTTPS) and then responds with a trivial HTML response.
-
-    #include <sys/types.h>
-    #include <sys/socket.h>
-    #include <sys/ioctl.h>
-    #include <sys/poll.h>
-    #include <netdb.h>
-
-    #include <stdlib.h>
-    #include <unistd.h>
-    #include <string.h>
-    #include <stdio.h>
-
-    #include <errno.h>
-
-    #include <s2n.h>
-
-    static char certificate[] =
-    "-----BEGIN CERTIFICATE-----\n"
-    "MIIDLjCCAhYCCQDL1lr6N8/gvzANBgkqhkiG9w0BAQUFADBZMQswCQYDVQQGEwJB\n"
-    "VTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0\n"
-    "cyBQdHkgTHRkMRIwEAYDVQQDEwlsb2NhbGhvc3QwHhcNMTQwNTEwMTcwODIzWhcN\n"
-    "MjQwNTA3MTcwODIzWjBZMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0\n"
-    "ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMRIwEAYDVQQDEwls\n"
-    "b2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDIltaUmHg+\n"
-    "G7Ida2XCtEQx1YeWDX41U2zBKbY0lT+auXf81cT3dYTdfJblb+v4CTWaGNofogcz\n"
-    "ebm8B2/OF9F+WWkKAJhKsTPAE7/SNAdi4Eqv4FfNbWKkGb4xacxxb4PH2XP9V3Ch\n"
-    "J6lMSI3V68FmEf4kcEN14V8vufIC5HE/LT4gCPDJ4UfUUbAgEhSebT6r/KFYB5T3\n"
-    "AeDc1VdnaaRblrP6KwM45vTs0Ii09/YrlzBxaTPMjLGCKa8JMv8PW2R0U9WCqHmz\n"
-    "BH+W3Q9xPrfhCInm4JWob8WgM1NuiYuzFB0CNaQcdMS7h0aZEAVnayhQ96/Padpj\n"
-    "KNE0Lur9nUxbAgMBAAEwDQYJKoZIhvcNAQEFBQADggEBAGRV71uRt/1dADsMD9fg\n"
-    "JvzW89jFAN87hXCRhTWxfXhYMzknxJ5WMb2JAlaMc/gTpiDiQBkbvB+iJe5AepgQ\n"
-    "WbyxPJNtSlA9GfKBz1INR5cFsOL27VrBoMYHMaolveeslc1AW2HfBtXWXeWSEF7F\n"
-    "QNgye8ZDPNzeSWSI0VyK2762wsTgTuUhHAaJ45660eX57+e8IvaM7xOEfBPDKYtU\n"
-    "0a28ZuhvSr2akJtGCwcs2J6rs6I+rV84UktDxFC9LUezBo8D9FkMPLoPKKNH1dXR\n"
-    "6LO8GOkqWUrhPIEmfy9KYes3q2ZX6svk4rwBtommHRv30kPxnnU1YXt52Ri+XczO\n"
-    "wEs=\n"
-    "-----END CERTIFICATE-----\n";
-    
-    static char private_key[] =
-    "-----BEGIN RSA PRIVATE KEY-----\n"
-    "MIIEpAIBAAKCAQEAyJbWlJh4PhuyHWtlwrREMdWHlg1+NVNswSm2NJU/mrl3/NXE\n"
-    "93WE3XyW5W/r+Ak1mhjaH6IHM3m5vAdvzhfRfllpCgCYSrEzwBO/0jQHYuBKr+BX\n"
-    "zW1ipBm+MWnMcW+Dx9lz/VdwoSepTEiN1evBZhH+JHBDdeFfL7nyAuRxPy0+IAjw\n"
-    "yeFH1FGwIBIUnm0+q/yhWAeU9wHg3NVXZ2mkW5az+isDOOb07NCItPf2K5cwcWkz\n"
-    "zIyxgimvCTL/D1tkdFPVgqh5swR/lt0PcT634QiJ5uCVqG/FoDNTbomLsxQdAjWk\n"
-    "HHTEu4dGmRAFZ2soUPevz2naYyjRNC7q/Z1MWwIDAQABAoIBAHrkryLrJwAmR8Hu\n"
-    "grH/b6h4glFUgvZ43jCaNZ+RsR5Cc1jcP4i832Izat+26oNUYRrADyNCSdcnxLuG\n"
-    "cuF5hkg6zzfplWRtnJ8ZenR2m+/gKuIGOMULN1wCyZvMjg0RnVNbzsxwPfj+K6Mo\n"
-    "8H0Xq621aFc60JnwMjkzWyqaeyeQogn1pqybuL6Dm2huvN49LR64uHuDUStTRX33\n"
-    "ou1fVWXOJ1kealYPbRPj8pDa31omB8q5Cf8Qe/b9anqyi9CsP17QbVg9k2IgoLlj\n"
-    "agqOc0u/opOTZB4tqJbqsIdEhc5LD5RUkYJsw00Iq0RSiKTfiWSPyOFw99Y9Act0\n"
-    "cbIIxEECgYEA8/SOsQjoUX1ipRvPbfO3suV1tU1hLCQbIpv7WpjNr1kHtngjzQMP\n"
-    "dU/iriUPGF1H+AxJJcJQfCVThV1AwFYVKb/LCrjaxlneZSbwfehpjo+xQGaNYG7Q\n"
-    "1vQuBVejuYk/IvpZltQOdm838DjvYyWDMh4dcMFIycXxEg+oHxf/s+8CgYEA0n4p\n"
-    "GBuLUNx9vv3e84BcarLaOF7wY7tb8z2oC/mXztMZpKjovTH0PvePgI5/b3KQ52R0\n"
-    "8zXHVX/4lSQVtCuhOVwKOCQq97/Zhlp5oTTShdQ0Qa1GQRl5wbTS6hrYEWSi9AQP\n"
-    "BVUPZ+RIcxx00DfBNURkId8xEpvCOmvySN8sUlUCgYAtXmHbEqkB3qulwRJGhHi5\n"
-    "UGsfmJBlwSE6wn9wTdKStZ/1k0o1KkiJrJ2ffUzdXxuvSbmgyA5nyBlMSBdurZOp\n"
-    "+/0qtU4abUQq058OC1b2KEryix/nuzQjha25WJ8eNiQDwUNABZfa9rwUdMIwUh2g\n"
-    "CHG5Mnjy7Vjz3u2JOtFXCQKBgQCVRo1EIHyLauLuaMINM9HWhWJGqeWXBM8v0GD1\n"
-    "pRsovQKpiHQNgHizkwM861GqqrfisZZSyKfFlcynkACoVmyu7fv9VoD2VCMiqdUq\n"
-    "IvjNmfE5RnXVQwja+668AS+MHi+GF77DTFBxoC5VHDAnXfLyIL9WWh9GEBoNLnKT\n"
-    "hVm8RQKBgQCB9Skzdftc+14a4Vj3NCgdHZHz9mcdPhzJXUiQyZ3tYhaytX9E8mWq\n"
-    "pm/OFqahbxw6EQd86mgANBMKayD6B1Id1INqtXN1XYI50bSs1D2nOGsBM7MK9aWD\n"
-    "JXlJ2hwsIc4q9En/LR3GtBaL84xTHGfznNylNhXi7GbO1wNMJuAukA==\n"
-    "-----END RSA PRIVATE KEY-----\n";
-
-    static char dhparams[] =
-    "-----BEGIN DH PARAMETERS-----\n"
-    "MIIBCAKCAQEAy1+hVWCfNQoPB+NA733IVOONl8fCumiz9zdRRu1hzVa2yvGseUSq\n"
-    "Bbn6k0FQ7yMED6w5XWQKDC0z2m0FI/BPE3AjUfuPzEYGqTDf9zQZ2Lz4oAN90Sud\n"
-    "luOoEhYR99cEbCn0T4eBvEf9IUtczXUZ/wj7gzGbGG07dLfT+CmCRJxCjhrosenJ\n"
-    "gzucyS7jt1bobgU66JKkgMNm7hJY4/nhR5LWTCzZyzYQh2HM2Vk4K5ZqILpj/n0S\n"
-    "5JYTQ2PVhxP+Uu8+hICs/8VvM72DznjPZzufADipjC7CsQ4S6x/ecZluFtbb+ZTv\n"
-    "HI5CnYmkAwJ6+FSWGaZQDi8bgerFk9RWwwIBAg==\n"
-    "-----END DH PARAMETERS-----\n";
-
-    static char response[] =
-    "HTTP/1.0 200 OK\r\n"
-    "Content-Length: 34\r\n"
-    "Connection: close\r\n"
-    "Content-Type: text/html; charset=utf-8\r\n\r\n"
-    "<html><h1>Hello World!</h1></html>";
-
-    void usage()
-    {
-        fprintf(stderr, "usage: example_https_server ip port\n");
-        fprintf(stderr, " host: hostname or IP address to listen on\n");
-        fprintf(stderr, " port: hostname or IP address to listen on\n");
-
-        exit(1);
-    }
-
-    int main(int argc, const char *argv[])
-    {
-        struct addrinfo hints, *ai;
-        int r, sockfd = 0;
-        int more;
-
-        if (argc != 3) {
-            usage();
-        }
-
-        if (memset(&hints, 0, sizeof(hints)) != &hints) {
-            fprintf(stderr, "memset error: %s\n", strerror(errno));
-            return -1;
-        }
-
-        hints.ai_family = AF_UNSPEC;
-        hints.ai_socktype = SOCK_STREAM;
-
-        if ((r = getaddrinfo(argv[1], argv[2], &hints, &ai)) != 0) {
-            fprintf(stderr, "error: %s\n", gai_strerror(r));
-            return -1;
-        }
-
-        if ((sockfd = socket(ai->ai_family, ai->ai_socktype,
-                             ai->ai_protocol)) == -1) {
-            exit(1);
-        }
-
-        r = 1;
-        if (setsockopt(sockfd, SOL_SOCKET, SO_REUSEADDR, &r, sizeof(int)) < 0) {
-            exit(1);
-        }
-
-        if (bind(sockfd, ai->ai_addr, ai->ai_addrlen) < 0) {
-            exit(1);
-        }
-
-        if (listen(sockfd, 1) == -1) {
-            exit(1);
-        }
-        struct s2n_config *config = s2n_config_new();
-        if (!config) {
-            fprintf(stderr, "Error getting new s2n config: '%s'\n", s2n_strerror(s2n_errno, "EN"));
-            exit(1);
-        }
-
-        if (s2n_config_add_cert_chain_and_key(config, "_default_", certificate, 
-                                              private_key) < 0) {
-            fprintf(stderr, "Error getting certificate/key: '%s'\n", s2n_strerror(s2n_errno, "EN"));
-            exit(1);
-        }
-
-        if (s2n_config_add_dhparams(config, dhparams) < 0) {
-            fprintf(stderr, "Error adding DH parameters: '%s'\n", s2n_strerror(s2n_errno, "EN"));
-            exit(1);
-        }
-
-        struct s2n_connection *conn = s2n_connection_new(S2N_SERVER);
-
-        if (s2n_connection_set_config(conn, config) < 0) {
-            fprintf(stderr, "Error setting configuration: '%s'\n", s2n_strerror(s2n_errno, "EN"));
-            exit(1);
-        }
-
-        int fd;
-        while ((fd = accept(sockfd, ai->ai_addr, &ai->ai_addrlen)) > 0) {
-            if (s2n_connection_set_fd(conn, fd) < 0) {
-                fprintf(stderr, "Error setting file descriptor: '%s'\n", s2n_strerror(s2n_errno, "EN"));
-                exit(1);
-            }
-
-            if (s2n_negotiate(conn, &more) < 0) {
-                fprintf(stderr, "Error negotiating: '%s'\n", s2n_strerror(s2n_errno, "EN"));
-                s2n_connection_wipe(conn);
-                continue;
-            }
-
-            if (s2n_get_server_name(conn)) {
-                printf("Got connection with server name: '%s'\n",
-                       s2n_get_server_name(conn));
-            }
-            else {
-                printf("Got connection with no server name\n");
-            }
-
-            if (s2n_send(conn, response, sizeof(response), &more) < 0) {
-                s2n_connection_wipe(conn);
-                continue;
-            }
-
-            s2n_shutdown(conn, &more);
-            s2n_connection_wipe(conn);
-        }
-        
-        return 0;
-    }
+To understand the API it may be easiest to see examples in action. s2n's [bin/](https://github.com/awslabs/s2n/blob/master/bin/) directory
+includes an example client (s2nc) and server (s2nd)..
