* Create new packet stream and use the `stream' as underlaying stream.
* Usually the `stream' would be a socket stream, but it can be any
* stream. After this function returns, packets can immediately be
- * sent to or received from the stream.
+ * sent to and received from the stream.
*
* NOTES
*
SilcSchedule schedule,
SilcStream stream);
+/****f* silccore/SilcPacketAPI/silc_packet_stream_add_remote
+ *
+ * SYNOPSIS
+ *
+ * SilcPacketStream silc_packet_stream_add_remote(SilcPacketStream stream,
+ * const char *remote_ip,
+ * SilcUInt16 remote_port,
+ * SilcPacket packet);
+ *
+ * DESCRIPTION
+ *
+ * This function is used to add remote receivers in packet stream `stream'
+ * that has UDP/IP socket stream as the underlaying stream. This function
+ * cannot be used with other type of streams. This returns new packet
+ * stream context that can be used to send to and receive packets from
+ * the specified remote IP and remote port, or NULL on error. The `stream'
+ * is the actual stream that is used to send and receive the data.
+ *
+ * When the parent `stream' receives packets from remote IP address
+ * and port that does not have its own remote packet stream, it returns
+ * the packet to the packet callback set for `stream'. The sender's
+ * IP address and port can then be retrieved by using the
+ * silc_packet_get_sender function and to create new packet stream by
+ * calling this function. After that, all packets from that IP address
+ * and port will be received by the new packet stream.
+ *
+ * If the `packet' is non-NULL it will be injected into the new packet
+ * stream as soon as the scheduler associated with `stream' schedules
+ * new tasks. It can be used to inject an incoming packet to the stream.
+ *
+ * This interface is for connectionless UDP streams. If it is possible
+ * to create connected stream it should be done for performance reasons.
+ *
+ * EXAMPLE
+ *
+ * // Create parent packet stream, it can receive packets from anywhere
+ * listener = silc_net_udp_connect("0.0.0.0", 500, NULL, 0, schedule);
+ * parent = silc_packet_stream_create(engine, schedule, listener);
+ *
+ * ...
+ * // Received a packet to the parent stream, get the sender information.
+ * silc_packet_get_sender(packet, &ip, &port);
+ *
+ * // Create new packet stream for this remote location.
+ * remote = silc_packet_stream_add_remote(parent, ip, port, packet);
+ *
+ ***/
+SilcPacketStream silc_packet_stream_add_remote(SilcPacketStream stream,
+ const char *remote_ip,
+ SilcUInt16 remote_port,
+ SilcPacket packet);
+
/****f* silccore/SilcPacketAPI/silc_packet_stream_destroy
*
* SYNOPSIS
* DESCRIPTION
*
* Destroy packet stream and the underlaying stream. This will also
- * send end of stream to the underlaying stream.
+ * close and destroy the underlaying stream.
*
***/
void silc_packet_stream_destroy(SilcPacketStream stream);
* SYNOPSIS
*
* void silc_packet_stream_set_stream(SilcPacketStream packet_stream,
- * SilcStream stream,
- * SilcSchedule schedule);
+ * SilcStream stream);
*
* DESCRIPTION
*
* This function may be used to change the underlaying stream in the
* packet stream indicated by `packet_stream'. Note that the old
* stream will not be used after calling this function. The caller is
- * responsible destroying the old stream.
+ * responsible destroying the old stream. The `stream' will use
+ * the same scheduler as the `packet_stream'.
*
***/
void silc_packet_stream_set_stream(SilcPacketStream packet_stream,
- SilcStream stream,
- SilcSchedule schedule);
+ SilcStream stream);
/****f* silccore/SilcPacketAPI/silc_packet_stream_get_stream
*
SilcPacketCallbacks *callbacks,
void *callback_context);
+/****f* silccore/SilcPacketAPI/silc_packet_get_sender
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_stream_is_udp(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Returns TRUE if the packet stream indicated by `stream' is using
+ * UDP transport.
+ *
+ ***/
+SilcBool silc_packet_stream_is_udp(SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_get_sender
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_get_sender(SilcPacket packet,
+ * const char **sender_ip,
+ * SilcUInt16 *sender_port);
+ *
+ * DESCRIPTION
+ *
+ * Returns the packet sender's IP address and port from UDP packet
+ * indicated by `packet'. This can be called only from the packet
+ * callback to retrieve the information of the packet's sender. Returns
+ * FALSE if the information is not available.
+ *
+ ***/
+SilcBool silc_packet_get_sender(SilcPacket packet,
+ const char **sender_ip,
+ SilcUInt16 *sender_port);
+
/****f* silccore/SilcPacketAPI/silc_packet_stream_ref
*
* SYNOPSIS
***/
void *silc_packet_get_context(SilcPacketStream stream);
-/****f* silccore/SilcPacketAPI/silc_packet_set_ciphers
+/****f* silccore/SilcPacketAPI/silc_packet_set_keys
*
* SYNOPSIS
*
- * void silc_packet_set_ciphers(SilcPacketStream stream, SilcCipher send,
- * SilcCipher receive);
+ * void silc_packet_set_keys(SilcPacketStream stream, SilcCipher send_key,
+ * SilcCipher receive_key, SilcHmac send_hmac,
+ * SilcHmac receive_hmac, SilcBool rekey);
*
* DESCRIPTION
*
- * Set ciphers to be used to encrypt sent packets, and decrypt received
- * packets. This can be called multiple times to change the ciphers.
- * In this case if old cipher is set it will be freed. If ciphers are
- * not set packets will not be encrypted or decrypted.
- *
- ***/
-void silc_packet_set_ciphers(SilcPacketStream stream, SilcCipher send,
- SilcCipher receive);
-
-/****f* silccore/SilcPacketAPI/silc_packet_get_ciphers
+ * Set ciphers and HMACs to be used to encrypt sent packets, and decrypt
+ * received packets. This can be called multiple times to change the
+ * ciphers and HMACs.
*
- * SYNOPSIS
- *
- * SilcBool silc_packet_get_ciphers(SilcPacketStream stream,
- * SilcCipher *send,
- * SilcCipher *receive);
- *
- * DESCRIPTION
- *
- * Returns the pointers of current ciphers from the `stream'. Returns
- * FALSE if ciphers are not set.
- *
- ***/
-SilcBool silc_packet_get_ciphers(SilcPacketStream stream, SilcCipher *send,
- SilcCipher *receive);
-
-/****f* silccore/SilcPacketAPI/silc_packet_set_hmacs
- *
- * SYNOPSIS
- *
- * void silc_packet_set_hmacs(SilcPacketStream stream, SilcHmac send,
- * SilcHmac receive);
- *
- * DESCRIPTION
+ * If the `rekey' is TRUE this function will send SILC_PACKET_REKEY_DONE
+ * to the `stream' and will set the new keys. If it is FALSE the keys
+ * are changed but the packet is not changed.
*
- * Set HMACs to be used to create MACs for sent packets and to check
- * MAC for received packets. This can be called multiple times to change
- * the HMACs. In this case if old HMAC is set it will be freed. If
- * HMACs are not set MACs are not generated or verified for packets.
+ * When changing keys the old cipher and HMACs will be freed. If the keys
+ * are not set at all, packets will not be encrypted or decrypted.
*
***/
-void silc_packet_set_hmacs(SilcPacketStream stream, SilcHmac send,
- SilcHmac receive);
+SilcBool silc_packet_set_keys(SilcPacketStream stream, SilcCipher send_key,
+ SilcCipher receive_key, SilcHmac send_hmac,
+ SilcHmac receive_hmac, SilcBool rekey);
-/****f* silccore/SilcPacketAPI/silc_packet_get_hmacs
+/****f* silccore/SilcPacketAPI/silc_packet_get_keys
*
* SYNOPSIS
*
- * SilcBool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
- * SilcHmac *receive);
+ * SilcBool silc_packet_get_keys(SilcPacketStream stream,
+ * SilcCipher *send_key,
+ * SilcCipher *receive_key,
+ * SilcHmac *send_hmac,
+ * SilcHmac *receive_hmac);
*
* DESCRIPTION
*
- * Returns the pointers of current HMACs from the `stream'. Returns
- * FALSE if HMACs are not set.
+ * Returns the pointers of current ciphers and HMACs from the `stream'.
+ * Returns FALSE if keys are not set.
*
***/
-SilcBool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
- SilcHmac *receive);
+SilcBool silc_packet_get_keys(SilcPacketStream stream,
+ SilcCipher *send_key, SilcCipher *receive_key,
+ SilcHmac *send_hmac, SilcHmac *receive_hmac);
/****f* silccore/SilcPacketAPI/silc_packet_set_ids
*
* DESCRIPTION
*
* Send `data' of length of `data_len' to the packet stream indicated by
- * `stream'. If ciphers and HMACs were set using silc_packet_set_ciphers
- * and silc_packet_set_hmacs the packet will be encrypted and MAC will be
- * computed for it. If silc_packet_set_ids was used to set source and
- * destination ID for the packet stream those IDs are used in the
- * packet. If IDs have not been set and they need to be provided then
- * silc_packet_send_ext function should be used. Otherwise, the packet
- * will not have IDs set at all. Returns FALSE if packet could not be
- * sent.
+ * `stream'. If ciphers and HMACs were set using silc_packet_set_keys
+ * the packet will be encrypted and MAC will be computed for it. If
+ * silc_packet_set_ids was used to set source and destination ID for the
+ * packet stream those IDs are used in the packet. If IDs have not been
+ * set and they need to be provided then silc_packet_send_ext function
+ * should be used. Otherwise, the packet will not have IDs set at all.
+ * Returns FALSE if packet could not be sent.
*
***/
SilcBool silc_packet_send(SilcPacketStream stream,
projects / silc.git / blobdiff