freeswan/klips/doc/klipsNGreq/klips1structure.tex

   1 \section{Current KLIPS input/output structure}
   2
   3 \subsection{output: ipsec\_tunnel\_start\_xmit}
   4
   5 \begin{enumerate}
   6         \item gather private information
   7         \item clone skb if necessary
   8         \item verify that packet is IPv4
   9         \item compute hard header length
  10         \item decrement TTL
  11         \item lookup in erouting table
  12         \item UDP port 500 exception
  13         \item start encapsulation loop
  14         \begin{enumerate}
  15                 \item check for DROP or missing eroute
  16                 \item check for REJECT eroute
  17                 \item check for PASS eroute
  18                 \item check for HOLD eroute
  19                 \item check for TRAP eroute, signal PF\_KEY, swap to HOLD eroute
  20                 \item acquire lock for walking tdb chain
  21                 \item calculate headroom required for chain
  22                 \begin{enumerate}
  23                         \item check if SA is in larval, drop
  24                         \item check if SA is dead, drop
  25                         \item check if replay overflowed, expire SA
  26                         \item check if lifetime counters have overflowed, expire SA
  27                         \item switch on protocol type, to calculate headroom size.
  28                         \begin{enumerate}
  29                                 \item if ESP switch on protocol type to calculate tailroom size.
  30                         \end{enumerate}
  31                 \end{enumerate}
  32
  33                 \item calculate mtudiff, send ICMP fragment needed. Mark ``note2''
  34
  35                 \item hack MSS if desired
  36
  37                 \item copy upper (layer 2) header to safety if it was present
  38
  39                 \item check if data fits in existing skb, else expand.
  40                 \item apply grouped transforms
  41                 \begin{enumerate}
  42                         \item apply disaster of \#ifdefs.
  43                         \item switch by protocol type, calculate headroom for this stage
  44                         \begin{enumerate}
  45                                 \item if ESP, then switch by cipher get headroom
  46                                 \item if ESP, then switch by hash to get tailroom
  47                         \end{enumerate}
  48                         \item double check (not in NDEBUG) if there is enough headroom
  49                         \item push the data ahead
  50                         \item double check (not in NDEBUG) if there is enough tailroom
  51                         \item extend the data behind
  52                         \item see if packet has become too long (bigger than 64K)
  53                         \item finally move the plaintext as appropriate
  54                         \item switch on protocol type
  55                         \item case: ESP
  56                         \begin{enumerate}
  57                                 \item switch on cipher type, prepare IV
  58                                 \item prepare self-describing padding
  59                                 \item switch on cipher type, do encryption
  60                                 \item switch on cipher type, update IV
  61                                 \item switch on hash type, do authentication
  62                         \end{enumerate}
  63                         \item case: AH
  64                         \begin{enumerate}
  65                                 \item prep replay info, headroom
  66                                 \item switch on hash type, do authentication
  67                         \end{enumerate}
  68                         \item case: IPIP, apply encap
  69                         \item case: IPCOMP
  70                         \begin{enumerate}
  71                                 \item call skb\_compress
  72                                 \item do some debugging
  73                         \end{enumerate}
  74                         \item recalculate header checksum
  75                 \end{enumerate}
  76                 \item lookup eroute by new outer header, if we found
  77                         something and the src/dst have changed
  78         \end{enumerate}
  79         \item send ICMP if packet has become too big
  80         \item re-apply link layer header if there was one.
  81         \item attempt to re-route the packet
  82         \item drop packet if new route leads to us again.
  83         \item do connection tracking
  84         \item do netfilter localout output call
  85         \item call ip\_send or IP\_SEND depending on kernel version
  86 \end{enumerate}
  87
  88 \subsubsection{Comments upon problems/limitations of transmit}
  89
  90 \subsection{input: ipsec\_rcv}
  91
  92 \begin{enumerate}
  93         \item increment module use count
  94         \item verify skb and data is not NULL
  95         \item verify hard header length
  96         \item clone (COW) if necessary
  97         \item a number of poorly documented ``assertions''
  98         \item verify protocol number against packet and against protocol structure
  99         \item verify that protocol is AH, COMP or ESP.
 100         \item lookup each ipsecX device to determine which one has been bound
 101                 to the receiving device. Grab ipsecprv device info.
 102         \item if no device found, warn, but do not die
 103         \item begin decap loop
 104                 \begin{enumerate}
 105                 \item lock tdb if this is first time through
 106                 \item verify that length is appropriate multiple if ESP
 107                 \item switch on protocol type, grab SPI value from appropriate place
 108                 \item format sa with satoa. (not found in code)
 109                 \item if AH, then determine AH header length, find next protocol value, and
 110                         verify against expected length of AH header.
 111                 \item get spin lock if required
 112                 \item if IPCOMP
 113                 \begin{enumerate}
 114                         \item check if IPCOMP is out most header, (not yet supported)
 115                         \item advance the tdb pointer and, if doing inbound policy
 116                                 check, then check SPI value. Complain if not matched.
 117                         \item decompress packet, reset ip header pointer to new
 118                                 value, loop (via continue)
 119                 \end{enumerate}
 120                 \item lookup tdb based upon SA. \code{gettdb}
 121                 \item complain if no tdb
 122                 \item if doing inbound policy check
 123                 \begin{enumerate}
 124                         \item check that outer source matches one on packet.
 125                         \item check that this tdb is the expected next from
 126                                 previous. (forward check)
 127                         \item check that this tdb expects to be attached to
 128                                 previous. (reverse check)
 129                 \end{enumerate}
 130                 \item check if tdb state is larval, skip
 131                 \item check if tdb state is dead, complain
 132                 \item check lifetime (bytes - soft/hard, addtime - soft/hard, usetime -
 133                         soft/hard, packet count - soft/hard). Expire TDB,
 134                         tell pfkey if limit exceeded.
 135                 \item pick authlen, switch on auth type (MD5, SHA1)
 136                 \item switch on protocol type (ESP, AH only) and set up authenticator
 137                 \item check sequence number to see if replay window rolled, if so expire
 138                 \item check out replay window, dropping if it is a replay
 139                 \item verify authenticator, check if there was
 140                         authentication, switch on type
 141                 \begin{enumerate}
 142                         \item MD5, call MD5Update and friends, checking if
 143                                 ESP or AH was involved
 144                         \item SHA1, call SHA1Update and friends, checking if ESP or
 145                                 AH was involved
 146                         \item none, do nothing
 147                 \end{enumerate}
 148                 \item check authenticator for NULL (which would imply not AH
 149                         or ESP above)
 150                 \item compare authenticator against hash, complain if failed
 151                 \item update the replay window
 152                 \item switch on protocol type
 153                 \begin{enumerate}
 154                         \item if ESP
 155                         \begin{enumerate}
 156                                 \item switch on encryption algorithm
 157                                 \begin{itemize}
 158                                         \item if 3DES, then find IV and set header length
 159                                         \item otherwise, fail
 160                                 \end{itemize}
 161                                 \item locate ciphertext based upon header length
 162                                 \item switch on encryption algorithm
 163                                 \begin{itemize}
 164                                         \item if 3DES, verify data length
 165                                                 multiple of 8 and decrypt.
 166                                         \item no otherwise clause
 167                                 \end{itemize}
 168                                 \item find next header type
 169                                 \item find padding
 170                                 \item verify padding
 171                         \end{enumerate}
 172                         \item if AH, do nothing
 173                 \end{enumerate}
 174                 \item update protocol number in header (why?)
 175                 \item switch on protocol type
 176                 \begin{enumerate}
 177                         \item if ESP, the memmove as appropriate for ESP,
 178                                 skb\_pull() to compact, and then skb\_trim.
 179                         \item if AH, then memmove as appropriate for AH, skb\_pull().
 180                 \end{enumerate}
 181                 \item update skb pointers to parts of packet.
 182                 \item nuke any options that skb knew about, or skb->proto\_priv (2.2+)
 183         \end{enumerate}
 184         \begin{enumerate}
 185                 \item recalculate the header checksum
 186                 \item set the sbk protocol type to IP over ethernet
 187                 \item advance tdb pointers
 188                 \item if doing inbound policy check
 189                 \begin{enumerate}
 190                         \item verify that backward policy agrees with forward policy
 191                         \item check if next protocol field is not one we know about
 192                         \begin{enumerate}
 193                                 \item complain that policy was not complete
 194                         \end{enumerate}
 195                 \end{enumerate}
 196                 \item update ipcomp ratio counters if IPCOMP was involved, but this
 197                         stage is not IPCOMP
 198                 \item update the lifetime values in bytes, packets, and last used
 199                         time.
 200                 \item loop again if ESP, AH or IPCOMP
 201         \end{enumerate}
 202
 203         \item if original chain was IPCOMP, then advance tdb chain once (Why?)
 204         \item if there is one last tdb
 205         \begin{enumerate}
 206                 \item verify that last protocol type was IPIP (no transport
 207                         supported here)
 208                 \item if doing inbound policy checks
 209                 \begin{enumerate}
 210                         \item advance tdbnext with inext, and complain if
 211                                 non-NULL. (i.e. check that this was last tdb)
 212                         \item verify source IP address matches tdb source
 213                 \end{enumerate}
 214                 \item update lifetimes for this tdb
 215                 \item if skb data len is too small for header length,
 216                         complain
 217                 \item pull up new header into skb
 218                 \item advance ip pointer to inner header
 219                 \item update raw header pointer
 220                 \item zero protocol options
 221                 \item update layer 2 protocol info to IP over Ethernet
 222                 \item reset checksum info
 223         \end{enumerate}
 224         \item if we are doing EROUTE checking (i.e. tunnel exit checking)
 225         \begin{enumerate}
 226                 \item setup for look up by src/dst in eroute table, checking
 227                         for IPIP header.
 228 %               didn't we already advance ipp above? why are we looking in
 229 %               a tunnel that we didn't make?
 230                 \item lock eroute table, lookup eroute
 231                 \item record info we need and unlock
 232                 \item if we found what we need, then lock, and lookup policy
 233                         information by new said block.
 234                 \item if no tdb found, then we drop packet
 235                 \item walk policy\_tdb chain, look for last one
 236                 \item compare against tdb that we just used, complain if not
 237                         the same.
 238         \end{enumerate}
 239         \item unlock tbd
 240         \item update stats if appropriate
 241         \item release packet destination
 242         \item if there was a layer 2, copy it back into place
 243         \item do inbound policy checks if it was IPCOMP
 244 % WHY HERE?
 245         \item do connection tracking
 246         \item drop packet back into bottom half queue
 247 \end{enumerate}
 248
 249 \subsubsection{Comments upon problems/limitations of receive}
 250
 251 \section{KLIPS1 static structure}
 252
 253 \begin{figure}
 254 \includegraphics[height=6in,width=6in]{diagrams/klips1_tdb.eps}
 255 \label{KLIPS1 structures}
 256 \end{figure}
 257
 258 \subsection{klips1 radij}
 259
 260 The \code{radij} module is an adaptation of the BSD \code{radix.c} code. It
 261 has been consistently renamed to as to coexist with \code{radix.c}. It
 262 implements a netmask aware patricia tree on blocks of data.
 263
 264 An explanation explains that the pronounciation is almost the same since the
 265 ``j'' is to be pronounced like the Greek chi.
 266
 267 \subsection{klips1 eroute}
 268
 269 An eroute entry describes an entry in the security policy database. The
 270 \code{eroute} currently only includes selectors for source and destination address.
 271
 272 \subsection{klips1 tdbh}
 273
 274 This is an array of pointers to \code{struct tdb} structures. It serves as
 275 a root for chained hash buckets. It is an open hash.
 276
 277 These are managed by the code in \code{ipsec\_xform.c}. These provide a
 278 mapping from a \code{struct sa\_id} to a \code{struct tdb} based upon SPI,
 279 protocol and destination address.
 280
 281 The entries in each bucket are linked together using the \code{tdb\_hnext}
 282 field.
 283
 284 \subsection{klips1 tdb}
 285
 286 This structure represents all the information associated with a single
 287 transform. In the case that multiple transforms may be chained together, they
 288 are chained together using \code{tdb\_inext} and \code{tdb\_onext}. The ``i''
 289 and ``o'' are short for inner and outer. Thinking of the resulting packet as
 290 an onion, these pointers describe transforms towards the {\bf i}nner and {\bf
 291 o}uter directions.
 292
 293 \subsection{klips1 md5\_ctx}
 294
 295 This stores the key context for the MD5 authentication routines. This
 296 structure is different from the \code{MD5\_CTX}, in that this is the HMAC
 297 version and contains an inner and outer \code{MD5\_CTX}.
 298
 299 \subsection{klips1 sha1\_ctx}
 300
 301 This block is not shown in the diagram, but serves an analogous function to
 302 \code{md5\_ctx}.
 303
 304 \subsection{klips1 des\_eks}
 305
 306 This block contains a DES key schedule (this is not equivalent to a DES key,
 307 but has been scheduled already). Note that this is really a container
 308 and is assumed to be of the proper size. The DES routines actually take a
 309 \code{des\_cblock} as input.
 310
 311
 312
 313
 314
 315
 316
 317
 318