--- /dev/null
+/*
+
+ silcmessage.h
+
+ Author: Pekka Riikonen <priikone@silcnet.org>
+
+ Copyright (C) 1997 -2002 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
+ the Free Software Foundation; version 2 of the License.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+*/
+
+/****h* silccore/SILC Message Interface
+ *
+ * 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.
+ *
+ ***/
+
+#ifndef SILCMESSAGE_H
+#define SILCMESSAGE_H
+
+/****s* silccore/SilcMessageAPI/SilcMessagePayload
+ *
+ * NAME
+ *
+ * typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
+ *
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Message Payload and is allocated
+ * by silc_message_payload_parse and given as argument usually
+ * to all silc_message_* functions. It is freed by the
+ * silc_message_payload_free function.
+ *
+ ***/
+typedef struct SilcMessagePayloadStruct *SilcMessagePayload;
+
+/****d* silccore/SilcMessageAPI/SilcMessageFlags
+ *
+ * NAME
+ *
+ * typedef SilcUInt16 SilcMessageFlags;
+ *
+ * DESCRIPTION
+ *
+ * The message flags type definition and the message flags. The
+ * message flags are used to indicate some status of the message.
+ *
+ * SOURCE
+ */
+typedef SilcUInt16 SilcMessageFlags;
+
+/* The message flags */
+#define SILC_MESSAGE_FLAG_NONE 0x0000 /* No flags */
+#define SILC_MESSAGE_FLAG_AUTOREPLY 0x0001 /* Automatically replied */
+#define SILC_MESSAGE_FLAG_NOREPLY 0x0002 /* Send no reply to this */
+#define SILC_MESSAGE_FLAG_ACTION 0x0004 /* Action message */
+#define SILC_MESSAGE_FLAG_NOTICE 0x0008 /* Notice message */
+#define SILC_MESSAGE_FLAG_REQUEST 0x0010 /* A request */
+#define SILC_MESSAGE_FLAG_SIGNED 0x0020 /* Message is signed */
+#define SILC_MESSAGE_FLAG_REPLY 0x0040 /* A reply */
+#define SILC_MESSAGE_FLAG_DATA 0x0080 /* MIME object */
+#define SILC_MESSAGE_FLAG_UTF8 0x0100 /* UTF-8 string */
+#define SILC_MESSAGE_FLAG_RESERVED 0x0200 /* to 0x0800 */
+#define SILC_MESSAGE_FLAG_PRIVATE 0x1000 /* to 0x8000 */
+/***/
+
+/****f* silccore/SilcMessageAPI/silc_message_payload_decrypt
+ *
+ * SYNOPSIS
+ *
+ * bool silc_message_payload_decrypt(unsigned char *data,
+ * size_t data_len,
+ * bool private_message,
+ * bool static_key,
+ * SilcCipher cipher,
+ * SilcHmac hmac,
+ * bool check_mac);
+ *
+ * DESCRIPTION
+ *
+ * Decrypt Message Payload indicated by `data'. If the payload is
+ * channel message then `private_message' is FALSE, and if it is
+ * private message it is TRUE. If the private message key is static
+ * (pre-shared key) then protocol dictates that the IV is present
+ * and `static_key' must be set to TRUE. If the key is not static
+ * (Key Agreement was done for the key) then it MUST be FALSE. For
+ * channel messages the `static_key' is ignored.
+ *
+ * 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
+ * circumstances. The `cipher' is used to decrypt the payload. If
+ * `check_mac' is FALSE then MAC is not verified.
+ *
+ ***/
+bool silc_message_payload_decrypt(unsigned char *data,
+ size_t data_len,
+ bool private_message,
+ bool static_key,
+ SilcCipher cipher,
+ SilcHmac hmac,
+ bool check_mac);
+
+/****f* silccore/SilcMessageAPI/silc_message_payload_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcMessagePayload
+ * silc_message_payload_parse(unsigned char *payload,
+ * SilcUInt32 payload_len,
+ * bool private_message,
+ * bool static_key,
+ * SilcCipher cipher,
+ * SilcHmac hmac);
+ *
+ * DESCRIPTION
+ *
+ * Parses Message Payload returning new payload structure. This also
+ * decrypts the payload and checks the MAC. If the payload is
+ * channel message then `private_message' is FALSE, and if it is
+ * private message it is TRUE. If the private message key is static
+ * (pre-shared key) then protocol dictates that the IV is present
+ * and `static_key' must be set to TRUE. If the key is not static
+ * (Key Agreement was done for the key) then it MUST be FALSE. For
+ * channel messages the `static_key' is ignored.
+ *
+ * If the `hmac' is no provided then the MAC of the channel message is
+ * not verified. If the message is private message and `cipher' is NULL
+ * then this assumes that the packet was decrypted with session keys
+ * (no private message key) and this merely decodes the payload.
+ *
+ ***/
+SilcMessagePayload
+silc_message_payload_parse(unsigned char *payload,
+ SilcUInt32 payload_len,
+ bool private_message,
+ bool static_key,
+ SilcCipher cipher,
+ SilcHmac hmac);
+
+/****f* silccore/SilcMessageAPI/silc_message_payload_encrypt
+ *
+ * SYNOPSIS
+ *
+ * bool silc_message_payload_encrypt(unsigned char *data,
+ * SilcUInt32 data_len,
+ * unsigned char *iv,
+ * SilcUInt32 iv_len,
+ * SilcCipher cipher,
+ * SilcHmac hmac);
+ *
+ * DESCRIPTION
+ *
+ * This function is used to encrypt the Messsage Payload which is
+ * 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 `data_len' bytes for the MAC which is appended to the data.
+ *
+ * This is usually used by the Message Payload interface itself but can
+ * be called by the appliation if separate encryption process is required.
+ * For example server might need to call this directly in some
+ * circumstances. The `cipher' is used to encrypt the payload and `hmac'
+ * to compute the MAC for the payload.
+ *
+ ***/
+bool silc_message_payload_encrypt(unsigned char *data,
+ SilcUInt32 data_len,
+ unsigned char *iv,
+ SilcUInt32 iv_len,
+ SilcCipher cipher,
+ SilcHmac hmac);
+
+/****f* silccore/SilcMessageAPI/silc_message_payload_encode
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
+ * const unsigned char *data,
+ * SilcUInt32 data_len,
+ * bool generate_iv,
+ * bool private_message,
+ * SilcCipher cipher,
+ * SilcHmac hmac,
+ * SilcRng rng);
+ *
+ * DESCRIPTION
+ *
+ * Encodes a Message Payload into a buffer and returns it. This is
+ * used to encode channel messages and private messages into a packet.
+ * If `private_message' is FALSE then this encodes channel message, if
+ * it is TRUE this encodes private message. If `private_message' is
+ * TRUE then `generate_iv' MUST be FALSE if the private message key
+ * `cipher' is not static key (pre-shared key). If it is static key
+ * then protocol dictates that IV must be present in the Message Payload
+ * and `generate_iv' must be TRUE. The caller must know whether the key
+ * is static or not for private messages. If the key was generated with
+ * Key Agreement protocol then `generate_iv' is always FALSE. For
+ * channel messages `generate_iv' is always set to TRUE value.
+ *
+ * The `cipher' is the cipher used to encrypt the message and `hmac'
+ * is used to compute the MAC for the payload. If encoding private
+ * message that will be encrypted with session keys (no private message
+ * key) then `cipher' and `hmac' is NULL and this merely encodes the
+ * payload buffer, and the caller must encrypt the packet later.
+ *
+ * If `rng' is NULL then global RNG is used, if non-NULL then the
+ * `rng' is used (for IV and padding generation).
+ *
+ ***/
+SilcBuffer silc_message_payload_encode(SilcMessageFlags flags,
+ const unsigned char *data,
+ SilcUInt32 data_len,
+ bool generate_iv,
+ bool private_message,
+ SilcCipher cipher,
+ SilcHmac hmac,
+ SilcRng rng);
+
+/****f* silccore/SilcMessageAPI/silc_message_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_message_payload_free(SilcMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Free's Message Payload and all data in it.
+ *
+ ***/
+void silc_message_payload_free(SilcMessagePayload payload);
+
+/****f* silccore/SilcMessageAPI/silc_message_get_flags
+ *
+ * SYNOPSIS
+ *
+ * SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Returns the message flags from the payload.
+ *
+ ***/
+SilcMessageFlags silc_message_get_flags(SilcMessagePayload payload);
+
+/****f* silccore/SilcMessageAPI/silc_message_get_data
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *
+ * silc_message_get_data(SilcMessagePayload payload,
+ * SilcUInt32 *data_len);
+ *
+ * DESCRIPTION
+ *
+ * Return the data in the payload, that is, the actual message data.
+ * The caller must not free it.
+ *
+ ***/
+unsigned char *silc_message_get_data(SilcMessagePayload payload,
+ SilcUInt32 *data_len);
+
+/****f* silccore/SilcMessageAPI/silc_message_get_mac
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *
+ * silc_message_get_mac(SilcMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the MAC of the payload. The caller must already know the
+ * length of the MAC. The caller must not free the MAC.
+ *
+ ***/
+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);
+
+/****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;
+
+/****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 SILC_MESSAGE_FLAG_SIGNED 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.
+ *
+ ***/
+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,
+ * bool include_public_key);
+ *
+ * DESCRIPTION
+ *
+ * Encodes the SILC_MESSAGE_FLAG_SIGNED 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 `include_public_key' is
+ * TRUE 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.
+ *
+ ***/
+SilcBuffer
+silc_message_signed_payload_encode(const unsigned char *message_payload,
+ SilcUInt32 message_payload_len,
+ SilcPublicKey public_key,
+ SilcPrivateKey private_key,
+ SilcHash hash,
+ bool include_public_key);
+
+/****f* silccore/SilcMessageAPI/silc_message_signed_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_message_signed_payload_free(SilcMessageSignedPayload sig);
+ *
+ * DESCRIPTION
+ *
+ * Frees the SILC_MESSAGE_FLAG_SIGNED 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);
+ *
+ * DESCRIPTION
+ *
+ * This routine can be used to verify the signature found in
+ * SILC_MESSAGE_FLAG_SIGNED Payload. 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);
+
+/****f* silccore/SilcMessageAPI/silc_message_signed_get_public_key
+ *
+ * SYNOPSIS
+ *
+ * SilcPublicKey
+ * silc_message_signed_get_public_key(SilcMessageSignedPayload sig);
+ *
+ * DESCRIPTION
+ *
+ * Returns the public key from the SILC_MESSAGE_FLAG_SIGNED Payload
+ * or NULL if it does not include public key. The caller must free
+ * the returned public key.
+ *
+ ***/
+SilcPublicKey
+silc_message_signed_get_public_key(SilcMessageSignedPayload sig);
+
+#endif /* SILCMESSAGE_H */
projects / silc.git / blobdiff