Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2006 Pekka Riikonen
+ Copyright (C) 1997 - 2007 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
*
* This interface includes the implementation of the Message Payload that
- * is used to send private messages and channel messages.
- *
- * This interface defines also the SILC_MESSAGE_FLAG_SIGNED Payload,
- * which defines how channel messages and private messages can be digitally
- * signed. This interface provides the payload parsing, encoding,
- * signature computing and signature verification routines.
+ * is used to send private messages and channel messages. The interface
+ * is also able to automatically provide digital signature in the messages
+ * if it is requested. Message digital signatures may also be verified with
+ * this interface.
*
***/
*
* NAME
*
- * typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
+ * typedef struct SilcMessagePayloadObject
+ * *SilcMessagePayload, SilcMessagePayloadStruct;
*
*
* DESCRIPTION
* silc_message_payload_free function.
*
***/
-typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
-
-/****s* silccore/SilcMessageAPI/SilcMessageSignedPayload
- *
- * NAME
- *
- * typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
- *
- *
- * DESCRIPTION
- *
- * This context represents the SILC_MESSAGE_FLAG_SIGNED Payload which
- * is used with channel messages and private messages to indicate that
- * the message is digitally signed. This payload may include the
- * message sender's public key and it includes the digital signature.
- * This payload MUST NOT be used in any other context except with
- * channel and private message sending and reception.
- *
- ***/
-typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload;
+typedef struct SilcMessagePayloadObject
+ *SilcMessagePayload, SilcMessagePayloadStruct;
/****d* silccore/SilcMessageAPI/SilcMessageFlags
*
* SilcBool static_key,
* SilcCipher cipher,
* SilcHmac hmac,
+ * unsigned char *sender_id,
+ * SilcUInt32 sender_id_len,
+ * unsigned char *receiver_id,
+ * SilcUInt32 receiver_id_len,
* SilcBool check_mac);
*
* DESCRIPTION
* (Key Agreement was done for the key) then it MUST be FALSE. For
* channel messages the `static_key' is ignored.
*
+ * The `sender_id' and `receiver_id' are the IDs from the packet header
+ * of the packet where this message payload was received.
+ *
* This is usually used by the Message Payload interface itself but can
* be called by the appliation if separate decryption process is required.
* For example server might need to call this directly in some
SilcBool static_key,
SilcCipher cipher,
SilcHmac hmac,
+ unsigned char *sender_id,
+ SilcUInt32 sender_id_len,
+ unsigned char *receiver_id,
+ SilcUInt32 receiver_id_len,
SilcBool check_mac);
/****f* silccore/SilcMessageAPI/silc_message_payload_parse
* SilcBool private_message,
* SilcBool static_key,
* SilcCipher cipher,
- * SilcHmac hmac);
+ * SilcHmac hmac,
+ * unsigned char *sender_id,
+ * SilcUInt32 sender_id_len,
+ * unsigned char *receiver_id,
+ * SilcUInt32 receiver_id_len,
+ * SilcStack stack,
+ * SilcBool no_allocation,
+ * SilcMessagePayload message);
*
* DESCRIPTION
*
* then this assumes that the packet was decrypted with session keys
* (no private message key) and this merely decodes the payload.
*
+ * The `sender_id' and `receiver_id' are the IDs from the packet header
+ * of the packet where this message payload was received.
+ *
+ * If the `message' is non-NULL then that pre-allocated context is
+ * used in parsing. Same context is returned. Otherwise new context
+ * is allocated and returned. If the `stack' is non-NULL then memory
+ * is allocated from that stack. If `no_allocation' is TRUE then the
+ * `message' must be provided and data is merely parsed and referenced
+ * from `payload' and will become invalid when `payload' invalidates.
+ * If `no_allocation' is TRUE the routine does not do any allocations.
+ *
***/
SilcMessagePayload
silc_message_payload_parse(unsigned char *payload,
SilcBool private_message,
SilcBool static_key,
SilcCipher cipher,
- SilcHmac hmac);
+ SilcHmac hmac,
+ unsigned char *sender_id,
+ SilcUInt32 sender_id_len,
+ unsigned char *receiver_id,
+ SilcUInt32 receiver_id_len,
+ SilcStack stack,
+ SilcBool no_allocation,
+ SilcMessagePayload message);
/****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
*
* SilcUInt32 data_len,
* SilcUInt32 true_len,
* unsigned char *iv,
- * SilcUInt32 iv_len,
+ * SilcID *sender_id,
+ * SilcID *receiver_id,
* SilcCipher cipher,
* SilcHmac hmac);
*
* the `data' and `data_len'. The `data_len' is the data length which
* is used to create MAC out of. The `data' MUST have additional space
* after `true_len' bytes for the MAC which is appended to the data.
+ * The `sender_id' is the ID message sender and `receiver_id' is ID of
+ * message receiver.
*
* This is usually used by the Message Payload interface itself but can
* be called by the appliation if separate encryption process is required.
SilcUInt32 data_len,
SilcUInt32 true_len,
unsigned char *iv,
- SilcUInt32 iv_len,
+ SilcID *sender_id,
+ SilcID *receiver_id,
SilcCipher cipher,
SilcHmac hmac);
* SilcRng rng,
* SilcPublicKey public_key,
* SilcPrivateKey private_key,
- * SilcHash hash);
+ * SilcHash hash,
+ * SilcID *sender_id,
+ * SilcID *receiver_id,
+ * SilcBuffer buffer);
*
* DESCRIPTION
*
* be included in the message. The `private_message' and `hash' MUST
* be provided. The `hash' SHOULD be SHA1.
*
+ * The `sender_id' is the ID message sender and `receiver_id' is ID of
+ * message receiver.
+ *
+ * If the `buffer' is non-NULL then the payload will be encoded into
+ * that buffer. The same buffer is returned. Otherwise new buffer is
+ * allocated and returned. The `buffer' will be automatically enlarged
+ * if the payload does not fit to it.
+ *
***/
SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
const unsigned char *data,
SilcRng rng,
SilcPublicKey public_key,
SilcPrivateKey private_key,
- SilcHash hash);
+ SilcHash hash,
+ SilcID *sender_id,
+ SilcID *receiver_id,
+ SilcBuffer buffer);
/****f* silccore/SilcMessageAPI/silc_message_payload_free
*
***/
unsigned char *silc_message_get_mac(SilcMessagePayload payload);
-/****f* silccore/SilcMessageAPI/silc_message_get_iv
- *
- * SYNOPSIS
- *
- * unsigned char *
- * silc_message_get_iv(SilcMessagePayload payload);
- *
- * DESCRIPTION
- *
- * Return the IV of the payload. The caller must already know the
- * length of the IV. The caller must not free the IV.
- *
- ***/
-unsigned char *silc_message_get_iv(SilcMessagePayload payload);
-
-/****f* silccore/SilcMessageAPI/silc_message_get_signature
- *
- * SYNOPSIS
- *
- * SilcMessageSignedPayload
- * silc_message_get_signature(SilcMessagePayload payload);
- *
- * DESCRIPTION
- *
- * Returns the pointer to the signature of the message if the
- * SILC_MESSAGE_FLAG_SIGNED was set. If the flag is set and this
- * function returns NULL then error had occurred and the signature
- * could not be retrieved from the message.
- *
- * The caller SHOULD verify the signature by calling the
- * silc_message_signed_verify function. Caller must not free the
- * returned payload pointer.
- *
- ***/
-SilcMessageSignedPayload
-silc_message_get_signature(SilcMessagePayload payload);
-
-/****f* silccore/SilcMessageAPI/silc_message_signed_payload_parse
- *
- * SYNOPSIS
- *
- * SilcMessageSignedPayload
- * silc_message_signed_payload_parse(const unsigned char *data,
- * SilcUInt32 data_len);
- *
- * DESCRIPTION
- *
- * Parses the SilcMessageSignedPayload Payload from the `data' of
- * length of `data_len' bytes. The `data' must be payload without
- * the actual message payload. Returns the parsed payload or NULL
- * on error. Caller must free the returned payload. Application
- * usually does not need to call this since the function
- * silc_message_payload_parse calls this automatically for signed
- * messages.
- *
- ***/
-SilcMessageSignedPayload
-silc_message_signed_payload_parse(const unsigned char *data,
- SilcUInt32 data_len);
-
-/****f* silccore/SilcMessageAPI/silc_message_signed_payload_encode
- *
- * SYNOPSIS
- *
- * SilcBuffer
- * silc_message_signed_payload_encode(const unsigned char *message_payload,
- * SilcUInt32 message_payload_len,
- * SilcPublicKey public_key,
- * SilcPrivateKey private_key,
- * SilcHash hash);
- *
- * DESCRIPTION
- *
- * Encodes the SilcMessageSignedPayload Payload and computes the
- * digital signature. The `message_payload' is the message data that
- * is used in the signature computation. The encoding of the buffer
- * is specified in the SILC protocol. If `public_key' is provided
- * then the public key included in the payload. The `private_key'
- * is used to produce the signature. This function returns the encoded
- * payload with the signature or NULL on error. Caller must free the
- * returned buffer. The `hash' SHOULD be SHA-1 hash function.
- *
- * Application usually does not need to call this since the function
- * silc_message_payload_encode calls this automatically if the caller
- * wants to sign the message.
- *
- ***/
-SilcBuffer
-silc_message_signed_payload_encode(const unsigned char *message_payload,
- SilcUInt32 message_payload_len,
- SilcPublicKey public_key,
- SilcPrivateKey private_key,
- SilcHash hash);
-
-/****f* silccore/SilcMessageAPI/silc_message_signed_payload_free
- *
- * SYNOPSIS
- *
- * void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
- *
- * DESCRIPTION
- *
- * Frees the SilcMessageSignedPayload Payload.
- *
- ***/
-void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
-
/****f* silccore/SilcMessageAPI/silc_message_signed_verify
*
* SYNOPSIS
*
- * int silc_message_signed_verify(SilcMessageSignedPayload sig,
- * SilcMessagePayload message,
- * SilcPublicKey remote_public_key,
- * SilcHash hash);
+ * SilcAuthResult
+ * silc_message_signed_verify(SilcMessagePayload message,
+ * SilcPublicKey remote_public_key,
+ * SilcHash hash);
*
* DESCRIPTION
*
- * This routine can be used to verify the signature found in
- * SilcMessageSignedPayload Payload. This returns SILC_AUTH_OK if the
- * signature verification was successful.
+ * This routine can be used to verify the digital signature from the
+ * message indicated by `message'. The signature is present only if
+ * the SILC_MESSAGE_FLAG_SIGNED is set in the message flags. This
+ * returns SILC_AUTH_OK if the signature verification was successful.
*
***/
-int silc_message_signed_verify(SilcMessageSignedPayload sig,
- SilcMessagePayload message,
- SilcPublicKey remote_public_key,
- SilcHash hash);
+SilcAuthResult silc_message_signed_verify(SilcMessagePayload message,
+ SilcPublicKey remote_public_key,
+ SilcHash hash);
/****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
*
* SYNOPSIS
*
* SilcPublicKey
- * silc_message_signed_get_public_key(SilcMessageSignedPayload sig,
+ * silc_message_signed_get_public_key(SilcMessagePayload payload,
* const unsigned char **pk_data,
* SilcUInt32 *pk_data_len);
*
* DESCRIPTION
*
- * Returns the decoded SilcPublicKey from the SilcMessageSignedPayload
- * Payload or NULL if it does not include public key. The caller must
- * free the returned public key pointer. This also returns the raw
- * public key (before decoding) into `pk_data' and `pk_data_len' if
- * they are provided. The caller must not free these pointers.
+ * Returns the decoded SilcPublicKey from the message payload or NULL
+ * if it does not include public key. The caller must free the returned
+ * public key pointer. This also returns the raw public key (before
+ * decoding) into `pk_data' and `pk_data_len' if they are provided. The
+ * caller must not free these pointers.
*
***/
SilcPublicKey
-silc_message_signed_get_public_key(SilcMessageSignedPayload sig,
+silc_message_signed_get_public_key(SilcMessagePayload payload,
const unsigned char **pk_data,
SilcUInt32 *pk_data_len);
+#include "silcmessage_i.h"
+
#endif /* SILCMESSAGE_H */