/*
- silcauth.h
-
+ silcauth.h
+
Author: Pekka Riikonen <priikone@silcnet.org>
-
- Copyright (C) 2001 Pekka Riikonen
-
+
+ Copyright (C) 2001 - 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; either version 2 of the License, or
- (at your option) any later version.
-
+ 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
*/
-/****h* silccore/SilcAuthAPI
+/****h* silccore/SILC Authentication Interface
*
* DESCRIPTION
*
* used by client to agree on key material usually with another client
* in the network.
*
+ * 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 SILCAUTH_H
#define SILCAUTH_H
-/****s* silccore/SilcAuthAPI/SilcAuthPayload
- *
- * NAME
- *
- * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
- *
- *
- * DESCRIPTION
- *
- * This context is the actual Authentication Payload and is allocated
- * by silc_auth_payload_parse and given as argument usually to all
- * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
- * function.
- *
- ***/
-typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
-
-/****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
- *
- * NAME
- *
- * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
- *
- * DESCRIPTION
- *
- * This context is the actual Key Agreement Payload and is allocated
- * by silc_key_agreement_payload_parse and given as argument usually to all
- * silc_key_agreement_* functions. It is freed by the function
- * silc_key_agreement_payload_free.
- *
- ***/
-typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
-
/****d* silccore/SilcAuthAPI/SilcAuthMethod
*
* NAME
#define SILC_AUTH_FAILED 1
/***/
-/* Prototypes */
+/****s* silccore/SilcAuthAPI/SilcAuthPayload
+ *
+ * NAME
+ *
+ * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
+ *
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Authentication Payload and is allocated
+ * by silc_auth_payload_parse and given as argument usually to all
+ * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
+ * function.
+ *
+ ***/
+typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
/****f* silccore/SilcAuthAPI/silc_auth_payload_parse
*
*
* Encodes authentication payload into buffer and returns it.
* The `random_data' is provided only if doing public key authentication.
- * The `auth_data' is the actual authentication data.
+ * The `auth_data' is the actual authentication data. If the
+ * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
+ * argument SHOULD be UTF-8 encoded, if not library will attempt to
+ * encode it.
*
***/
SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
*
* DESCRIPTION
*
- * Get the authentication data. The caller must not free the data.
+ * Get the authentication data. The caller must not free the data. If
+ * the authentication method is passphrase, then the returned string
+ * is UTF-8 encoded passphrase.
*
***/
unsigned char *silc_auth_get_data(SilcAuthPayload payload,
*
* SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
* SilcPrivateKey private_key,
+ * SilcRng rng,
* SilcHash hash,
* const void *id,
* SilcIdType type);
* and the actual authentication data. Returns NULL on error and the
* encoded Authentication Payload on success.
*
+ * The `private_key' is used to sign the payload. The `public_key', the
+ * and the `id' is encoded in the payload and signed. If the `rng' is
+ * NULL then global RNG is used, if non-NULL then `rng' is used as
+ * random number generator. Also random number is encoded in the
+ * payload before signing it with `private_key'.
+ *
***/
SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
SilcPrivateKey private_key,
- SilcHash hash,
+ SilcRng rng, SilcHash hash,
const void *id, SilcIdType type);
/****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
* Verifies the authentication data directly from the Authentication
* Payload. Supports all authentication methods. If the authentication
* method is passphrase based then the `auth_data' and `auth_data_len'
- * are the passphrase and its length. If the method is public key
- * authentication then the `auth_data' is the SilcPublicKey and the
- * `auth_data_len' is ignored.
+ * are the passphrase and its length. The passphrase MUST be UTF-8
+ * encoded. If the method is public key authentication then the
+ * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
*
***/
bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
* Verifies the authentication data directly from the Authentication
* Payload. Supports all authentication methods. If the authentication
* method is passphrase based then the `auth_data' and `auth_data_len'
- * are the passphrase and its length. If the method is public key
- * authentication then the `auth_data' is the SilcPublicKey and the
- * `auth_data_len' is ignored.
+ * are the passphrase and its length. The passphrase MUST be UTF-8
+ * encoded. If the method is public key authentication then the
+ * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
*
***/
-bool silc_auth_verify_data(const unsigned char *payload, SilcUInt32 payload_len,
+bool silc_auth_verify_data(const unsigned char *payload,
+ SilcUInt32 payload_len,
SilcAuthMethod auth_method, const void *auth_data,
SilcUInt32 auth_data_len, SilcHash hash,
const void *id, SilcIdType type);
+/****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
+ *
+ * NAME
+ *
+ * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Key Agreement Payload and is allocated
+ * by silc_key_agreement_payload_parse and given as argument usually to all
+ * silc_key_agreement_* functions. It is freed by the function
+ * silc_key_agreement_payload_free.
+ *
+ ***/
+typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
+
/****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
*
* SYNOPSIS
***/
SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
+/****s* silccore/SilcAuthAPI/SilcSignedPayload
+ *
+ * NAME
+ *
+ * typedef struct SilcSignedPayloadStruct *SilcSignedPayload;
+ *
+ *
+ * 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 SilcSignedPayloadStruct *SilcSignedPayload;
+
+/****f* silccore/SilcAuthAPI/silc_signed_payload_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcSignedPayload silc_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.
+ *
+ ***/
+SilcSignedPayload silc_signed_payload_parse(const unsigned char *data,
+ SilcUInt32 data_len);
+
+/****f* silccore/SilcAuthAPI/silc_signed_payload_encode
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer
+ * silc_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_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/SilcAuthAPI/silc_signed_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_signed_payload_free(SilcSignedPayload sig);
+ *
+ * DESCRIPTION
+ *
+ * Frees the SILC_MESSAGE_FLAG_SIGNED Payload.
+ *
+ ***/
+void silc_signed_payload_free(SilcSignedPayload sig);
+
+/****f* silccore/SilcAuthAPI/silc_signed_payload_verify
+ *
+ * SYNOPSIS
+ *
+ * int silc_signed_payload_verify(SilcSignedPayload sig,
+ * bool channel_message,
+ * void *message_payload,
+ * SilcPublicKey remote_public_key,
+ * SilcHash hash);
+ *
+ * DESCRIPTION
+ *
+ * This routine can be used to verify the signature found in
+ * SILC_MESSAGE_FLAG_SIGNED Payload. The `remote_public_key' is the
+ * sender's public key and is used in the verification. If the
+ * `channel_message' is TRUE then `message_payload' must include the
+ * SilcChannelMessagePayload. If it is FALSE then it must include
+ * SilcPrivateMessagePayload. This returns SILC_AUTH_OK if the
+ * signature verification was successful.
+ *
+ ***/
+int silc_signed_payload_verify(SilcSignedPayload sig,
+ bool channel_message,
+ void *message_payload,
+ SilcPublicKey remote_public_key,
+ SilcHash hash);
+
+/****f* silccore/SilcAuthAPI/silc_signed_payload_get_public_key
+ *
+ * SYNOPSIS
+ *
+ * SilcPublicKey silc_signed_payload_get_public_key(SilcSignedPayload 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_signed_payload_get_public_key(SilcSignedPayload sig);
+
#endif
projects / silc.git / blobdiff