auth.h 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  1. /*
  2. * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
  3. * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
  4. *
  5. * This program is free software; you can redistribute it and/or modify
  6. * it under the terms of the GNU General Public License as published by
  7. * the Free Software Foundation; either version 2 of the License, or
  8. * (at your option) any later version.
  9. *
  10. * This program is distributed in the hope that it will be useful,
  11. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. * GNU General Public License for more details.
  14. *
  15. * You should have received a copy of the GNU General Public License
  16. * along with this program; if not, write to the Free Software
  17. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18. */
  19. #ifndef __PJ_TURN_SRV_AUTH_H__
  20. #define __PJ_TURN_SRV_AUTH_H__
  21. #include <pjnath.h>
  22. /**
  23. * Initialize TURN authentication subsystem.
  24. *
  25. * @return PJ_SUCCESS on success.
  26. */
  27. PJ_DECL(pj_status_t) pj_turn_auth_init(const char *realm);
  28. /**
  29. * Shutdown TURN authentication subsystem.
  30. */
  31. PJ_DECL(void) pj_turn_auth_dinit(void);
  32. /**
  33. * This function is called by pj_stun_verify_credential() when
  34. * server needs to challenge the request with 401 response.
  35. *
  36. * @param user_data Should be ignored.
  37. * @param pool Pool to allocate memory.
  38. * @param realm On return, the function should fill in with
  39. * realm if application wants to use long term
  40. * credential. Otherwise application should set
  41. * empty string for the realm.
  42. * @param nonce On return, if application wants to use long
  43. * term credential, it MUST fill in the nonce
  44. * with some value. Otherwise if short term
  45. * credential is wanted, it MAY set this value.
  46. * If short term credential is wanted and the
  47. * application doesn't want to include NONCE,
  48. * then it must set this to empty string.
  49. *
  50. * @return The callback should return PJ_SUCCESS, or
  51. * otherwise response message will not be
  52. * created.
  53. */
  54. PJ_DECL(pj_status_t) pj_turn_get_auth(void *user_data,
  55. pj_pool_t *pool,
  56. pj_str_t *realm,
  57. pj_str_t *nonce);
  58. /**
  59. * This function is called to get the password for the specified username.
  60. * This function is also used to check whether the username is valid.
  61. *
  62. * @param msg The STUN message where the password will be
  63. * applied to.
  64. * @param user_data Should be ignored.
  65. * @param realm The realm as specified in the message.
  66. * @param username The username as specified in the message.
  67. * @param pool Pool to allocate memory when necessary.
  68. * @param data_type On return, application should fill up this
  69. * argument with the type of data (which should
  70. * be zero if data is a plaintext password).
  71. * @param data On return, application should fill up this
  72. * argument with the password according to
  73. * data_type.
  74. *
  75. * @return The callback should return PJ_SUCCESS if
  76. * username has been successfully verified
  77. * and password was obtained. If non-PJ_SUCCESS
  78. * is returned, it is assumed that the
  79. * username is not valid.
  80. */
  81. PJ_DECL(pj_status_t) pj_turn_get_password(const pj_stun_msg *msg,
  82. void *user_data,
  83. const pj_str_t *realm,
  84. const pj_str_t *username,
  85. pj_pool_t *pool,
  86. pj_stun_passwd_type *data_type,
  87. pj_str_t *data);
  88. /**
  89. * This function will be called to verify that the NONCE given
  90. * in the message can be accepted. If this callback returns
  91. * PJ_FALSE, 438 (Stale Nonce) response will be created.
  92. *
  93. * @param msg The STUN message where the nonce was received.
  94. * @param user_data Should be ignored.
  95. * @param realm The realm as specified in the message.
  96. * @param username The username as specified in the message.
  97. * @param nonce The nonce to be verified.
  98. *
  99. * @return The callback MUST return non-zero if the
  100. * NONCE can be accepted.
  101. */
  102. PJ_DECL(pj_bool_t) pj_turn_verify_nonce(const pj_stun_msg *msg,
  103. void *user_data,
  104. const pj_str_t *realm,
  105. const pj_str_t *username,
  106. const pj_str_t *nonce);
  107. #endif /* __PJ_TURN_SRV_AUTH_H__ */