Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2005 Pekka Riikonen
+ Copyright (C) 1997 - 2006 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
* DESCRIPTION
*
* The SILC secure binary packet protocol interface, provides interface for
- * sending and receiving SILC packets. The interface provides a packet engine,
- * that can be used to receive packets from packet streams, and routines
- * for sending all kinds of SILC packets.
+ * sending and receiving SILC packets. The interface provides a packet
+ * engine, that can be used to receive packets from packet streams, and
+ * routines for sending all kinds of SILC packets.
*
* The packet engine and packet stream are thread safe. They can be safely
* used in multi threaded environment.
SILC_PACKET_ERR_WRITE, /* Error while writing */
SILC_PACKET_ERR_MAC_FAILED, /* Packet MAC check failed */
SILC_PACKET_ERR_DECRYPTION_FAILED, /* Packet decryption failed */
+ SILC_PACKET_ERR_UNKNOWN_SID, /* Unknown SID (with IV included) */
SILC_PACKET_ERR_MALFORMED, /* Packet is malformed */
SILC_PACKET_ERR_NO_MEMORY, /* System out of memory */
} SilcPacketError;
* To read packets you will receive the packet receive callback from
* packet engine. Destroy the stream with silc_packet_stream_destroy.
*
- * If you need to send only one type of SILC packets, then it is possible
- * to create SILC Packet Streamer with silc_packet_streamer_create, which
- * can be used with silc_stream_read and silc_stream_write.
- *
* The SilcPacketStream is thread safe. Same context can be safely used
* in multi threaded environment.
*
***/
void silc_packet_stream_set_router(SilcPacketStream stream);
-/****f* silccore/SilcPacketAPI/silc_packet_streamer_create
+/****f* silccore/SilcPacketAPI/silc_packet_stream_set_iv_included
*
* SYNOPSIS
*
- * SilcStream silc_packet_streamer_create(SilcPacketStream stream,
- * SilcPacketType packet_type,
- * SilcPacketFlags packet_flags);
+ * void silc_packet_stream_set_iv_included(SilcPacketStream stream);
*
* DESCRIPTION
*
- * This function can be used to create a SILC Packet Streamer that will
- * stream only one type of packet indicated by `packet_type' with packet
- * flags `packet_flags'. This is special purpose function as usually
- * multiple different types of packets need to be sent in application.
- * There are cases however when creating streamer is simpler and more
- * efficient. Cases such as file transfer stream or other data streams
- * that only send and receive one type of packet. While it would be
- * possible to use silc_packet_send function to send packets it is
- * more efficient to create the SILC Packet Streamer and use the
- * silc_stream_read and silc_stream_write functions.
- *
- * The encryption and decryption keys, and other information will be
- * retrieved from the packet stream indicated by `stream', which must be
- * created before creating the streamer.
- *
- * NOTES
- *
- * The packet type that is assocated with the packet stream `stream' will
- * only be available through the returned SilcStream. That packet type
- * will not be delivered to the packet callbacks. To return to the
- * normal operation destroy the streamer silc_packet_streamer_destroy.
- *
- ***/
-SilcStream silc_packet_streamer_create(SilcPacketStream stream,
- SilcPacketType packet_type,
- SilcPacketFlags packet_flags);
-
-/****f* silccore/SilcPacketAPI/silc_packet_streamer_destroy
- *
- * SYNOPSIS
- *
- * void silc_packet_streamer_destroy(SilcStream stream);
+ * Sets an IV Included property for the stream indicated by `stream'.
+ * This means that the IV used in the encryption will be included in
+ * the resulted ciphertext. This makes it possible to send and receive
+ * packets on unreliable network transport protocol, such as UDP/IP.
+ * This must be called if the underlaying stream in the `stream' is UDP
+ * stream.
*
- * DESCRIPTION
- *
- * Destroys the created packet streamer. Use this function only for
- * stream created with silc_packet_streamer_create. The packet type
- * that was associated with the streamer can be received in the packet
- * callbacks after the streamer is destroyed.
+ * When this is set to the stream the silc_packet_set_sid must be called
+ * to set new Security ID. The Security ID will be included with the IV
+ * in the ciphertext.
*
***/
-void silc_packet_streamer_destroy(SilcStream stream);
+void silc_packet_stream_set_iv_included(SilcPacketStream stream);
/****f* silccore/SilcPacketAPI/silc_packet_stream_get_stream
*
SilcIdType src_id_type, const void *src_id,
SilcIdType dst_id_type, const void *dst_id);
+/****f* silccore/SilcPacketAPI/silc_packet_set_sid
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_set_sid(SilcPacketStream stream, SilcUInt8 sid);
+ *
+ * DESCRIPTION
+ *
+ * Sets new Security ID to the packet stream indicated by `stream'. This
+ * is called only if the IV Included property was set to the stream
+ * by calling silc_packet_stream_set_iv_included. This function sets
+ * new Security ID to the stream which is then included in the ciphertext
+ * of a packet. The `sid' must be 0 when it is set for the very first
+ * time and must be increased by one after each rekey. This function must
+ * be called every time new keys are added to the stream after a rekey.
+ *
+ * If this function is called when the IV Included property has not been
+ * set to the stream the `sid' will be ignored. Returns FALSE if the
+ * IV Included has not been set, TRUE otherwise.
+ *
+ ***/
+SilcBool silc_packet_set_sid(SilcPacketStream stream, SilcUInt8 sid);
+
/****f* silccore/SilcPacketAPI/silc_packet_send
*
* SYNOPSIS
* Same as silc_packet_send but with this function different sending
* parameters can be sent as argument. This function can be used to
* set specific IDs, cipher and HMAC to be used in packet sending,
- * instead of the ones saved in the `stream'.
+ * instead of the ones saved in the `stream'. If any of the extra
+ * pointers are NULL, default values set to the stream will apply.
*
***/
SilcBool silc_packet_send_ext(SilcPacketStream stream,
const unsigned char *data, SilcUInt32 data_len,
SilcCipher cipher, SilcHmac hmac);
+/****f* silccore/SilcPacketAPI/silc_packet_wait
+ *
+ * SYNOPSIS
+ *
+ * void *silc_packet_wait_init(SilcPacketStream stream, ...);
+ *
+ * DESCRIPTION
+ *
+ * Initializes a packet waiter for the packet stream `stream' and
+ * for the variable argument list of packet types. The function
+ * silc_packet_wait can be used to block the thread until a packet
+ * has been received. This function is used to initialize the waiting
+ * and to give the list of packet types that caller wish to receive.
+ * The variable argument list must end with -1. To receive all
+ * packets use SILC_PACKET_ANY. Returns a context that must be given
+ * to the silc_packet_wait function as argument. Returns NULL on
+ * error. To uninitialize the waiting call silc_packet_wait_uninit.
+ *
+ * NOTES
+ *
+ * Note that packets may be available immediately after calling this
+ * function and they will be buffered, until silc_packet_wait is called.
+ *
+ * EXAMPLE
+ *
+ * void *waiter;
+ *
+ * // Will wait for private message packets
+ * waiter = silc_packet_wait_init(stream,
+ * SILC_PACKET_PRIVATE_MESSAGE, -1);
+ *
+ *
+ ***/
+void *silc_packet_wait_init(SilcPacketStream stream, ...);
+
+/****f* silccore/SilcPacketAPI/silc_packet_wait
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_wait_uninit(void *waiter, SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Uninitializes the waiting context. This may be called also from
+ * another thread while other thread is waiting for packets. This will
+ * inform the waiting thread to stop waiting.
+ *
+ ***/
+void silc_packet_wait_uninit(void *waiter, SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_wait
+ *
+ * SYNOPSIS
+ *
+ * int silc_packet_wait(void *waiter, int timeout,
+ * SilcPacket *return_packet)
+ *
+ * DESCRIPTION
+ *
+ * A special function that can be used to wait for a packet to arrive.
+ * This function will block the calling process or thread until either
+ * a packet is received into the `return_packet' pointer or the specified
+ * timeout value `timeout', which is in milliseconds, will expire. If
+ * the timeout is 0, no timeout exist. Before calling this function the
+ * silc_packet_wait_init must be called. The caller is responsible for
+ * freeing the returned packet with silc_packet_free.
+ *
+ * This function can be used for example from a thread that wants to
+ * block until SILC packet has been received.
+ *
+ * Returns 1 when packet was received, 0 if timeout occurred and -1 if
+ * error occurred.
+ *
+ * EXAMPLE
+ *
+ * static int foo_read_data(FooContext c)
+ * {
+ * SilcPacket packet;
+ * void *waiter;
+ * ...
+ *
+ * // Will wait for private message packets
+ * if (c->initialized == FALSE) {
+ * waiter = silc_packet_wait_init(stream,
+ * SILC_PACKET_PRIVATE_MESSAGE, -1);
+ * c->initialized = TRUE;
+ * }
+ *
+ * ...
+ * // Wait here until private message packet is received
+ * if ((silc_packet_wait(waiter, 0, &packet)) < 0)
+ * return -1;
+ *
+ * ... process packet ...
+ *
+ * return 1;
+ * }
+ *
+ ***/
+int silc_packet_wait(void *waiter, int timeout, SilcPacket *return_packet);
+
/****f* silccore/SilcPacketAPI/silc_packet_free
*
* SYNOPSIS
projects / silc.git / blobdiff