X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilccore%2Fsilcmessage.h;h=7dc136efeca6905d369e058764ff5aadc86c6d46;hp=e003e029ee1a52623182896bca5ebea7c9febbc9;hb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;hpb=054c9b2c9b21c3cbe87e53c0e0bacb2bff918e68 diff --git a/lib/silccore/silcmessage.h b/lib/silccore/silcmessage.h index e003e029..7dc136ef 100644 --- a/lib/silccore/silcmessage.h +++ b/lib/silccore/silcmessage.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 1997 -2002 Pekka Riikonen + 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 @@ -51,6 +51,25 @@ ***/ 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; + /****d* silccore/SilcMessageAPI/SilcMessageFlags * * NAME @@ -77,21 +96,22 @@ typedef SilcUInt16 SilcMessageFlags; #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 */ +#define SILC_MESSAGE_FLAG_ACK 0x0200 /* ACK messages */ +#define SILC_MESSAGE_FLAG_RESERVED 0x0400 /* to 0x1000 */ +#define SILC_MESSAGE_FLAG_PRIVATE 0x2000 /* to 0x8000 */ /***/ /****f* silccore/SilcMessageAPI/silc_message_payload_decrypt * * SYNOPSIS * - * bool silc_message_payload_decrypt(unsigned char *data, + * SilcBool silc_message_payload_decrypt(unsigned char *data, * size_t data_len, - * bool private_message, - * bool static_key, + * SilcBool private_message, + * SilcBool static_key, * SilcCipher cipher, * SilcHmac hmac, - * bool check_mac); + * SilcBool check_mac); * * DESCRIPTION * @@ -110,13 +130,13 @@ typedef SilcUInt16 SilcMessageFlags; * `check_mac' is FALSE then MAC is not verified. * ***/ -bool silc_message_payload_decrypt(unsigned char *data, +SilcBool silc_message_payload_decrypt(unsigned char *data, size_t data_len, - bool private_message, - bool static_key, + SilcBool private_message, + SilcBool static_key, SilcCipher cipher, SilcHmac hmac, - bool check_mac); + SilcBool check_mac); /****f* silccore/SilcMessageAPI/silc_message_payload_parse * @@ -125,8 +145,8 @@ bool silc_message_payload_decrypt(unsigned char *data, * SilcMessagePayload * silc_message_payload_parse(unsigned char *payload, * SilcUInt32 payload_len, - * bool private_message, - * bool static_key, + * SilcBool private_message, + * SilcBool static_key, * SilcCipher cipher, * SilcHmac hmac); * @@ -150,8 +170,8 @@ bool silc_message_payload_decrypt(unsigned char *data, SilcMessagePayload silc_message_payload_parse(unsigned char *payload, SilcUInt32 payload_len, - bool private_message, - bool static_key, + SilcBool private_message, + SilcBool static_key, SilcCipher cipher, SilcHmac hmac); @@ -159,8 +179,9 @@ silc_message_payload_parse(unsigned char *payload, * * SYNOPSIS * - * bool silc_message_payload_encrypt(unsigned char *data, + * SilcBool silc_message_payload_encrypt(unsigned char *data, * SilcUInt32 data_len, + * SilcUInt32 true_len, * unsigned char *iv, * SilcUInt32 iv_len, * SilcCipher cipher, @@ -171,7 +192,7 @@ silc_message_payload_parse(unsigned char *payload, * 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. + * after `true_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. @@ -180,8 +201,9 @@ silc_message_payload_parse(unsigned char *payload, * to compute the MAC for the payload. * ***/ -bool silc_message_payload_encrypt(unsigned char *data, +SilcBool silc_message_payload_encrypt(unsigned char *data, SilcUInt32 data_len, + SilcUInt32 true_len, unsigned char *iv, SilcUInt32 iv_len, SilcCipher cipher, @@ -194,11 +216,14 @@ bool silc_message_payload_encrypt(unsigned char *data, * SilcBuffer silc_message_payload_encode(SilcMessageFlags flags, * const unsigned char *data, * SilcUInt32 data_len, - * bool generate_iv, - * bool private_message, + * SilcBool generate_iv, + * SilcBool private_message, * SilcCipher cipher, * SilcHmac hmac, - * SilcRng rng); + * SilcRng rng, + * SilcPublicKey public_key, + * SilcPrivateKey private_key, + * SilcHash hash); * * DESCRIPTION * @@ -219,19 +244,27 @@ bool silc_message_payload_encrypt(unsigned char *data, * 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). * + * The `public_key', `private_key' and `hash' are provided only if the + * flags includes SILC_MESSAGE_FLAG_SIGNED, in which case the message + * will be digitally signed. If `public_key' is non-NULL then it will + * be included in the message. The `private_message' and `hash' MUST + * be provided. The `hash' SHOULD be SHA1. + * ***/ SilcBuffer silc_message_payload_encode(SilcMessageFlags flags, const unsigned char *data, SilcUInt32 data_len, - bool generate_iv, - bool private_message, + SilcBool generate_iv, + SilcBool private_message, SilcCipher cipher, SilcHmac hmac, - SilcRng rng); + SilcRng rng, + SilcPublicKey public_key, + SilcPrivateKey private_key, + SilcHash hash); /****f* silccore/SilcMessageAPI/silc_message_payload_free * @@ -306,24 +339,27 @@ unsigned char *silc_message_get_mac(SilcMessagePayload payload); ***/ unsigned char *silc_message_get_iv(SilcMessagePayload payload); -/****s* silccore/SilcMessageAPI/SilcMessageSignedPayload +/****f* silccore/SilcMessageAPI/silc_message_get_signature * - * NAME - * - * typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload; + * SYNOPSIS * + * SilcMessageSignedPayload + * silc_message_get_signature(SilcMessagePayload payload); * * 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. + * 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. * ***/ -typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload; +SilcMessageSignedPayload +silc_message_get_signature(SilcMessagePayload payload); /****f* silccore/SilcMessageAPI/silc_message_signed_payload_parse * @@ -335,10 +371,13 @@ typedef struct SilcMessageSignedPayloadStruct *SilcMessageSignedPayload; * * DESCRIPTION * - * Parses the SILC_MESSAGE_FLAG_SIGNED Payload from the `data' of + * 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. + * 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 @@ -354,18 +393,22 @@ silc_message_signed_payload_parse(const unsigned char *data, * SilcUInt32 message_payload_len, * SilcPublicKey public_key, * SilcPrivateKey private_key, - * bool include_public_key); + * SilcHash hash); * * DESCRIPTION * - * Encodes the SILC_MESSAGE_FLAG_SIGNED Payload and computes the + * 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 `include_public_key' is - * TRUE then the public key included in the payload. The `private_key' + * 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. + * 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 @@ -373,8 +416,7 @@ 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); + SilcHash hash); /****f* silccore/SilcMessageAPI/silc_message_signed_payload_free * @@ -384,7 +426,7 @@ silc_message_signed_payload_encode(const unsigned char *message_payload, * * DESCRIPTION * - * Frees the SILC_MESSAGE_FLAG_SIGNED Payload. + * Frees the SilcMessageSignedPayload Payload. * ***/ void silc_message_signed_payload_free(SilcMessageSignedPayload sig); @@ -401,7 +443,7 @@ void silc_message_signed_payload_free(SilcMessageSignedPayload sig); * DESCRIPTION * * This routine can be used to verify the signature found in - * SILC_MESSAGE_FLAG_SIGNED Payload. This returns SILC_AUTH_OK if the + * SilcMessageSignedPayload Payload. This returns SILC_AUTH_OK if the * signature verification was successful. * ***/ @@ -415,16 +457,22 @@ int silc_message_signed_verify(SilcMessageSignedPayload sig, * SYNOPSIS * * SilcPublicKey - * silc_message_signed_get_public_key(SilcMessageSignedPayload sig); + * silc_message_signed_get_public_key(SilcMessageSignedPayload sig, + * unsigned char **pk_data, + * SilcUInt32 *pk_data_len); * * 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. + * 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. * ***/ SilcPublicKey -silc_message_signed_get_public_key(SilcMessageSignedPayload sig); +silc_message_signed_get_public_key(SilcMessageSignedPayload sig, + unsigned char **pk_data, + SilcUInt32 *pk_data_len); #endif /* SILCMESSAGE_H */