docs/linux_debugging_ssl.md

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