docs/linux_debugging_ssl.md

   1 # Debuggin SSL on Linux
   2
   3 To help anyone looking at the SSL code, here are a few tips I've found handy.
   4
   5 [TOC]
   6
   7 ## Building your own NSS
   8
   9 In order to use a debugger with the NSS library, it helps to build NSS yourself.
  10 Here's how I did it:
  11
  12 First, read
  13 [Network Security Services](http://www.mozilla.org/projects/security/pki/nss/nss-3.11.4/nss-3.11.4-build.html)
  14 and/or
  15 [Build instructions](https://developer.mozilla.org/En/NSS_reference/Building_and_installing_NSS/Build_instructions).
  16
  17 Then, to build the most recent source tarball:
  18
  19 ```shell
  20 cd $HOME
  21 wget ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_RTM/src/nss-3.12-with-nspr-4.7.tar.gz
  22 tar -xzvf nss-3.12-with-nspr-4.7.tar.gz
  23 cd nss-3.12/
  24 cd mozilla/security/nss/
  25 make nss_build_all
  26 ```
  27
  28 Sadly, the latest release, 3.12.2, isn't available as a tarball, so you have to
  29 build it from cvs:
  30
  31 ```shell
  32 cd $HOME
  33 mkdir nss-3.12.2
  34 cd nss-3.12.2
  35 export CVSROOT=:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot
  36 cvs login
  37 cvs co -r NSPR_4_7_RTM NSPR
  38 cvs co -r NSS_3_12_2_RTM NSS
  39 cd mozilla/security/nss/
  40 make nss_build_all
  41 ```
  42
  43 ## Linking against your own NSS
  44
  45 Sadly, I don't know of a nice way to do this; I always do
  46
  47     hammer --verbose net > log 2>&1
  48
  49 then grab the line that links my app and put it into a shell script link.sh,
  50 and edit it to include the line
  51
  52     DIR=$HOME/nss-3.12.2/mozilla/dist/Linux2.6_x86_glibc_PTH_DBG.OBJ/lib
  53
  54 and insert a `-L$DIR` right before the `-lnss3`.
  55
  56 Note that hammer often builds the app in one, deeply buried, place, then copies
  57 it into Hammer for ease of use. You'll probably want to make your `link.sh` do
  58 the same thing.
  59
  60 Then, after a source code change, do the usual `hammer net` followed by
  61 `sh link.sh`.
  62
  63 Then, to run the resulting app, use a script like
  64
  65 ## Running against your own NSS
  66
  67 Create a script named `run.sh` like this:
  68
  69 ```sh
  70 #!/bin/sh
  71 set -x
  72 DIR=$HOME/nss-3.12.2/mozilla/dist/Linux2.6_x86_glibc_PTH_DBG.OBJ/lib
  73 export LD_LIBRARY_PATH=$DIR
  74 "$@"
  75 ```
  76
  77 Then run your app with
  78
  79     sh run.sh Hammer/foo
  80
  81 Or, to debug it, do
  82
  83     sh run.sh gdb Hammer/foo
  84
  85 ## Logging
  86
  87 There are several flavors of logging you can turn on.
  88
  89 *   `SSLClientSocketNSS` can log its state transitions and function calls using
  90     `base/logging.cc`.  To enable this, edit `net/base/ssl_client_socket_nss.cc`
  91     and change `#if 1` to `#if 0`. See `base/logging.cc` for where the output
  92     goes (on Linux, it's usually stderr).
  93
  94 *   `HttpNetworkTransaction` and friends can log its state transitions using
  95     `base/trace_event.cc`. To enable this, arrange for your app to call
  96     `base::TraceLog::StartTracing()`. The output goes to a file named
  97     `trace...pid.log` in the same directory as the executable (e.g.
  98     `Hammer/trace_15323.log`).
  99
 100 *   `NSS` itself can log some events. To enable this, set the environment
 101     variables `SSLDEBUGFILE=foo.log SSLTRACE=99 SSLDEBUG=99` before running
 102     your app.
 103
 104 ## Network Traces
 105
 106 http://wiki.wireshark.org/SSL describes how to decode SSL traffic. Chromium SSL
 107 unit tests that use `net/base/ssl_test_util.cc` to set up their servers always
 108 use port 9443 with `net/data/ssl/certificates/ok_cert.pem`, and port 9666 with
 109 `net/data/ssl/certificates/expired_cert.pem` This makes it easy to configure
 110 Wireshark to decode the traffic: do
 111
 112 Edit / Preferences / Protocols / SSL, and in the "RSA Keys List" box, enter
 113
 114     127.0.0.1,9443,http,<path to ok_cert.pem>;127.0.0.1,9666,http,<path to expired_cert.pem>
 115
 116 e.g.
 117
 118     127.0.0.1,9443,http,/home/dank/chromium/src/net/data/ssl/certificates/ok_cert.pem;127.0.0.1,9666,http,/home/dank/chromium/src/net/data/ssl/certificates/expired_cert.pem
 119
 120 Then capture all tcp traffic on interface lo, and run your test.
 121
 122 ## Valgrinding NSS
 123
 124 Read https://developer.mozilla.org/en/NSS_Memory_allocation and do
 125
 126     export NSS_DISABLE_ARENA_FREE_LIST=1
 127
 128 before valgrinding if you want to find where a block was originally allocated.
 129
 130 If you get unsymbolized entries in NSS backtraces, try setting:
 131
 132     export NSS_DISABLE_UNLOAD=1
 133
 134 (Note that if you use the Chromium valgrind scripts like
 135 `tools/valgrind/chrome_tests.sh` or `tools/valgrind/valgrind.sh` these will both
 136 be set automatically.)
 137
 138 ## Support forums
 139
 140 If you have nonconfidential questions about NSS, check
 141 [the newsgroup](http://groups.google.com/group/mozilla.dev.tech.crypto).
 142 The NSS maintainer monitors that group and gives good answers.