stun/stunagent.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2008 Collabora Ltd.
   5  * (C) 2008 Nokia Corporation. All rights reserved.
   6  *  Contact: Youness Alaoui
   7  *
   8  * The contents of this file are subject to the Mozilla Public License Version
   9  * 1.1 (the "License"); you may not use this file except in compliance with
  10  * the License. You may obtain a copy of the License at
  11  * http://www.mozilla.org/MPL/
  12  *
  13  * Software distributed under the License is distributed on an "AS IS" basis,
  14  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  15  * for the specific language governing rights and limitations under the
  16  * License.
  17  *
  18  * The Original Code is the Nice GLib ICE library.
  19  *
  20  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  21  * Corporation. All Rights Reserved.
  22  *
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of the
  25  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  26  * case the provisions of LGPL are applicable instead of those above. If you
  27  * wish to allow use of your version of this file only under the terms of the
  28  * LGPL and not to allow others to use your version of this file under the
  29  * MPL, indicate your decision by deleting the provisions above and replace
  30  * them with the notice and other provisions required by the LGPL. If you do
  31  * not delete the provisions above, a recipient may use your version of this
  32  * file under either the MPL or the LGPL.
  33  */
  34
  35 #ifndef _STUN_AGENT_H
  36 #define _STUN_AGENT_H
  37
  38
  39 #ifdef _WIN32
  40 #include "win32_common.h"
  41 #else
  42 #include <stdint.h>
  43 #include <stdbool.h>
  44 #endif
  45
  46
  47 #include <sys/types.h>
  48
  49 typedef struct stun_agent_t StunAgent;
  50
  51 #include "stunmessage.h"
  52
  53 typedef enum {
  54   STUN_COMPATIBILITY_RFC3489,
  55   STUN_COMPATIBILITY_RFC5389,
  56   STUN_COMPATIBILITY_WLM2009,
  57   STUN_COMPATIBILITY_LAST = STUN_COMPATIBILITY_WLM2009
  58 } StunCompatibility;
  59
  60
  61 typedef enum {
  62   /* The message is validated */
  63   STUN_VALIDATION_SUCCESS,
  64   /* This is not a valid STUN message */
  65   STUN_VALIDATION_NOT_STUN,
  66   /* The message seems to be valid but incomplete */
  67   STUN_VALIDATION_INCOMPLETE_STUN,
  68   /* The message does not have the cookie or the fingerprint
  69    * while the agent needs it with its usage */
  70   STUN_VALIDATION_BAD_REQUEST,
  71   /* The message is valid but unauthorized with no username and message-integrity
  72      attributes. A BAD_REQUEST error must be generated */
  73   STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST,
  74   /* The message is valid but unauthorized as the username/password do not match.
  75      An UNAUTHORIZED error must be generated */
  76   STUN_VALIDATION_UNAUTHORIZED,
  77   /* The message is valid but this is a response/error that doesn't match
  78    * a previously sent request */
  79   STUN_VALIDATION_UNMATCHED_RESPONSE,
  80   /* The message is valid but contains one or more unknown comprehension
  81    * attributes. stun_agent_build_unknown_attributes_error should be called */
  82   STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE,
  83   /* The message is valid but contains one or more unknown comprehension
  84    * attributes. This is a response, or error, or indication message
  85    * and no error response should be sent */
  86   STUN_VALIDATION_UNKNOWN_ATTRIBUTE,
  87 } StunValidationStatus;
  88
  89
  90 #define STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS         0x0001
  91 #define STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS          0x0002
  92 #define STUN_AGENT_USAGE_USE_FINGERPRINT                0x0004
  93 #define STUN_AGENT_USAGE_ADD_SOFTWARE                   0x0008
  94 #define STUN_AGENT_USAGE_IGNORE_CREDENTIALS             0x0010
  95 #define STUN_AGENT_USAGE_NO_INDICATION_AUTH             0x0020
  96 #define STUN_AGENT_USAGE_FORCE_VALIDATER                0x0040
  97
  98
  99 typedef struct {
 100   StunTransactionId id;
 101   StunMethod method;
 102   uint8_t *key;
 103   size_t key_len;
 104   uint8_t long_term_key[16];
 105   bool long_term_valid;
 106   bool valid;
 107 } StunAgentSavedIds;
 108
 109 struct stun_agent_t {
 110   StunCompatibility compatibility;
 111   StunAgentSavedIds sent_ids[STUN_AGENT_MAX_SAVED_IDS];
 112   uint16_t *known_attributes;
 113   uint32_t usage_flags;
 114 };
 115
 116 typedef struct {
 117   uint8_t *username;
 118   size_t username_len;
 119   uint8_t *password;
 120   size_t password_len;
 121 } stun_validater_data;
 122
 123
 124 typedef bool (*StunMessageIntegrityValidate) (StunAgent *agent,
 125     StunMessage *message, uint8_t *username, uint16_t username_len,
 126     uint8_t **password, size_t *password_len, void *user_data);
 127
 128 bool stun_agent_default_validater (StunAgent *agent,
 129     StunMessage *message, uint8_t *username, uint16_t username_len,
 130     uint8_t **password, size_t *password_len, void *user_data);
 131
 132 void stun_agent_init (StunAgent *agent, const uint16_t *known_attributes,
 133     StunCompatibility compatibility, uint32_t usage_flags);
 134 StunValidationStatus stun_agent_validate (StunAgent *agent, StunMessage *msg,
 135     const uint8_t *buffer, size_t buffer_len,
 136     StunMessageIntegrityValidate validater, void * validater_data);
 137 bool stun_agent_init_request (StunAgent *agent, StunMessage *msg,
 138     uint8_t *buffer, size_t buffer_len, StunMethod m);
 139 bool stun_agent_init_indication (StunAgent *agent, StunMessage *msg,
 140     uint8_t *buffer, size_t buffer_len, StunMethod m);
 141 bool stun_agent_init_response (StunAgent *agent, StunMessage *msg,
 142     uint8_t *buffer, size_t buffer_len, const StunMessage *request);
 143 bool stun_agent_init_error (StunAgent *agent, StunMessage *msg,
 144     uint8_t *buffer, size_t buffer_len, const StunMessage *request,
 145     StunError err);
 146 size_t stun_agent_build_unknown_attributes_error (StunAgent *agent,
 147     StunMessage *msg, uint8_t *buffer, size_t buffer_len,
 148     const StunMessage *request);
 149 size_t stun_agent_finish_message (StunAgent *agent, StunMessage *msg,
 150    const uint8_t *key, size_t key_len);
 151
 152 #endif /* _STUN_AGENT_H */