From 7221935e61f3214d1a8b079ce3efd2c5974b429d Mon Sep 17 00:00:00 2001 From: Pekka Riikonen Date: Tue, 20 Feb 2007 20:37:18 +0000 Subject: [PATCH] updates. --- lib/doc/LIBINDEX | 7 +++- lib/silcasn1/DIRECTORY | 22 +++++++++++++ lib/silccore/README | 69 ++++++++++++++++++++++++++++++++++++++++ lib/silcserver/DIRECTORY | 17 ---------- lib/silcskr/DIRECTORY | 20 ++++++++++++ lib/silcutil/DIRECTORY | 4 +-- lib/silcutil/silcfsm_i.h | 2 +- 7 files changed, 120 insertions(+), 21 deletions(-) create mode 100644 lib/silcasn1/DIRECTORY create mode 100644 lib/silccore/README delete mode 100644 lib/silcserver/DIRECTORY create mode 100644 lib/silcskr/DIRECTORY diff --git a/lib/doc/LIBINDEX b/lib/doc/LIBINDEX index ebecb16c..f4a661b3 100644 --- a/lib/doc/LIBINDEX +++ b/lib/doc/LIBINDEX @@ -10,6 +10,12 @@ Version: @VERSION@
Copyright © 1997 - 2007 The SILC Project
Updated: @DATE@ +


+NOTE: This is reference manual of alpha version of SILC Toolkit 1.1 and +the reference may be incomplete, inaccurate and document nonexistent APIs. +The APIs provided by alpha versions of SILC Toolkit 1.1 may not be stable yet. + +


Welcome to the SILC Toolkit Reference Manual. The manual is a complete developer guide and reference for the SILC application programmer. The manual @@ -25,7 +31,6 @@ Toolkit sources, and the documentation is constantly evolving. New versions of the Toolkit always delivers the latest version of this reference manual.


-
  • What's new in Toolkit 1.1
  • Porting from Toolkit 1.0 to 1.1
  • Introduction to the Manual
  • Programming Conventions
    diff --git a/lib/silcasn1/DIRECTORY b/lib/silcasn1/DIRECTORY new file mode 100644 index 00000000..9cc71681 --- /dev/null +++ b/lib/silcasn1/DIRECTORY @@ -0,0 +1,22 @@ + + +SILC ASN.1 Library +
    +Directory: lib/silcasn1/ +
    +Library: libsilc.a, libsilc.lib +

    +Introduction + +

    +SILC Abstract Syntax Notation One (ASN.1) Library provides interface for +efficient ASN.1 encoder and decoder. The library also provides BER/DER +encoder and decoder. + +

    +@LINKS@ diff --git a/lib/silccore/README b/lib/silccore/README new file mode 100644 index 00000000..1ac9cc1f --- /dev/null +++ b/lib/silccore/README @@ -0,0 +1,69 @@ +The SILC Core Library + +This library contains the implementation of various SILC protocol packet +payloads and other routines. It also implements the SILC Packet Engine. + + +The SILC Packet Engine + +The SILC Packet engine (silcpacket.[ch]) is the heart of sending and +receiving SILC packets. The engine works in single thread but is thread +safe and has the notion of per-thread contexts for optimized processing. +The per-thread processing is actually per-scheduler, but in reality multiple +schedulers are run only when they are used in threads. + +The packet engine has a lock (engine->lock) that protects various engine +wide data. Currently this includes SILC Packet freelist, which could +perhaps later be in the per-thread SilcPacketEngineContext context. The +engine also keeps list of all streams (SilcPacketStream) that has been +added to the engine. + +The SilcPacketStream contains all stream related data, including encryption +and decryption keys, IDs, and outgoing buffer. The outgoing buffer is +per-stream so that data can be sent in multiple pieces from the outbuffer +if writing would block. Incoming buffer is not in stream context unless +it is necessary. The incoming buffer is in the per-thread context which +actually has a list of incoming buffers. If reading blocks for the given +stream, that incoming buffer is given to the SilcPacketStream context from +the list of buffers. When data is again available for that stream it is +read into the buffer the stream already has. Other stream will read to +the per-thread buffer, unless they would block also. The stream also +has a lock (stream->lock) because application can modify various data in +the stream. + +The packet callback has packet callbacks that is used to deliver the read +packet to application. The callbacks also deliver error and end of stream +status to application. It is also possible to attach additional packet +callbacks to stream so that there may be multiple receivers for one packet. +In the callback application may decide whether it wants to take the packet +or whether to pass it for the next receiver. The callbacks can be added +with priority. + + +Locking in packet engine + +Currently the engine lock is used only when the packet free list is accessed, +or new stream is added or removed. The packet free list, however, is +accessed for all incoming packets. Application free's the packet context so +the lock must later be acquired be putting the unused packet context back +to the free list. It might be possible to later put the packet free list to +per-thread context. + +Stream lock is taken everytime data is read from the underlaying stream or +sent to the underlaying stream. In principal it would be possible to read +without locking, because we use per-thread incoming buffers but in reality +many platforms would not suppots reading and writing to the same underlaying +stream (effectively socket) at the same time. And even if they would, some +rare race conditions with closing the stream might occur. One way of dealing +with this would be to make sure that any stream used with SilcPacketStream +must itself be thread-safe. In that case the locking would move to the +underlaying stream. + +When reading data from stream, the lock is held during reading and during +data processing. The lock is released when the packet is dispatched to +a packet callback. + +When sending packet the lock is acquired only when actually accessing the +outgoing buffer and writing to the stream. This includes encryption. This +means that if two threads send to same stream the encryption is not in +parallel. diff --git a/lib/silcserver/DIRECTORY b/lib/silcserver/DIRECTORY deleted file mode 100644 index c92412f6..00000000 --- a/lib/silcserver/DIRECTORY +++ /dev/null @@ -1,17 +0,0 @@ - - -SILC Server Library -
    -Directory: lib/server/ -
    -Library: libsilcserver.a, libsilcserver.lib -

    -Introduction - -

    -@LINKS@ diff --git a/lib/silcskr/DIRECTORY b/lib/silcskr/DIRECTORY new file mode 100644 index 00000000..943b0cbb --- /dev/null +++ b/lib/silcskr/DIRECTORY @@ -0,0 +1,20 @@ + + +SILC Key Repository Library +
    +Directory: lib/silcskr/ +
    +Library: libsilc.a, libsilc.lib +

    +Introduction + +

    +SILC Key Repository (SKR) Library can be used to store and retrieve public +keys and certificates. + +

    +@LINKS@ diff --git a/lib/silcutil/DIRECTORY b/lib/silcutil/DIRECTORY index 83b11975..00394a1e 100644 --- a/lib/silcutil/DIRECTORY +++ b/lib/silcutil/DIRECTORY @@ -1,7 +1,7 @@