README.code

   1 README.code
   2 Info for hackers of pssh.
   3
   4
   5 ## Compilation ##
   6
   7 pssh is built using prc-tools, PilRC 3.0, and Peal on Mac OS X.
   8 pssh can probably be built on any platform supported by prc-tools.
   9 It probably cannot be built with CodeWarrior without significant porting
  10 work (multi-segment support, in particular).
  11
  12 pssh uses prc-tools to compile code.
  13     http://prc-tools.sourceforge.net/
  14     http://www.zenonez.com/prctoolsx/  (binaries for Mac OS X)
  15
  16 pssh uses PilRC 3.0 or later to build resources.
  17     http://sourceforge.net/projects/pilrc/
  18     http://zenonez.com/prctoolsx/PilRC-3.1.dmg.gz (binaries for Mac OS X)
  19
  20 pssh requires Peal to link and load ARM code.
  21     http://www.sealiesoftware.com/peal/
  22
  23 pssh requires libc.a and libgcc.a built as Thumb code with ARM
  24 interworking enabled. Current versions of prc-tools do not provide
  25 them. Instructions for building them from prc-tools 2.3 are available
  26 on request (gparker-pssh@sealiesoftware.com), or use:
  27     http://www.sealiesoftware.com/pssh/dist/libc.a
  28     http://www.sealiesoftware.com/pssh/dist/libgcc.a
  29
  30
  31 To build:
  32
  33 1. Set up your directories as follows:
  34
  35    libc.a
  36    libgcc.a
  37    peal/
  38        ...
  39    pssh-source/
  40        README.code
  41        ...
  42
  43 2. In directory peal/postlink, run `make` if you have not already.
  44    This builds Peal's postlinker.
  45
  46 3. In directory pssh-source, run `make`. This builds pssh's m68K
  47    code, ARM code, and resources, generating pssh.prc.
  48
  49 If you see build messages like "warning: interworking not enabled",
  50 "thumb call to arm", and "internal error: dangerous error",
  51 then your libc.a or libgcc.a isn't set up right. pssh.prc will crash
  52 if you try to run it.
  53
  54
  55 WARNING: pssh's Makefile does NOT handle all dependencies like
  56 changed .h files. Use `make clean` as necessary.
  57
  58
  59 ## Directories ##
  60 Note: some of these directories have components under the arm/ directory.
  61
  62 crypto: Basic cryptographic algorithms
  63 crypto/openssl: Cryptography algorithms from OpenSSL
  64 crypto/rand: Fortuna random number generator
  65 crypto/sha2: SHA256 algorithm by Aaron Gifford
  66
  67 data: Manipulation and display of data in Palm OS databases
  68
  69 forms: Event handlers and other form code
  70
  71 rsrc: Palm OS resource descriptions and font data
  72 rsrc/pssh.rsrc: Palm OS Constructor mockups of some forms (not actually used)
  73
  74 ssh: SSH 2 protocol
  75 ssh/openssh: SSH 2 code from OpenSSH
  76
  77 util: Miscellaneous utility code and headers
  78 util/oem: Headers from various SDKs like palmOne and Sony
  79
  80 vt100: Terminal emulator from PuTTY
  81
  82
  83 ## SSH 2 protocol code ##
  84
  85 Palm OS programs are event-driven. OpenSSH's ssh client is not.
  86 To prevent blocking in socket I/O, much of OpenSSH's protocol code
  87 was rewritten as follows.
  88
  89 ssh.c
  90 The highest-level wrapper around an SSH 2 session and its associated
  91 terminal emulator. All manipulation from outside goes through here.
  92
  93 packetizer.c
  94 SSH 2 binary packet protocol. Handles socket I/O, version check,
  95 encryption, decryption, MAC check, padding. Sends unencrypted packet
  96 payloads to the transport layer.
  97
  98 transport.c
  99 SSH 2 transport protocol. Handles algorithm negotiation and key exchange.
 100 Sends other data to the connection layer.
 101
 102 connection.c
 103 SSH 2 connection protocol. Handles authentication and stream data.
 104 Sends stream data to the terminal emulator.
 105
 106 The packetizer, transport, and connection layers are each a state machine
 107 whose states are generally defined by blocking network operations. This
 108 allows program control to return to the main event loop when waiting for
 109 packets to arrive.