Модуль сервера SER - auth


Это основной модуль, который сам по себе не предоставляет все необходимые для авторизации функции, но предоставляет функции, которые необходимы другим модулям, использующимся для авторизации (так же известные, как backend для авторизации).

Мы решили разделить код для авторизации по нескольким модулям, по той причине, что на данный момент имеется уже несколько модулей авторизации (сейчас поддерживается авторизация с использованием баз данных и с помощью сервер radius).
Это позволяет нам создавать различные программные пакеты, которые может инсталлировать пользователь и загрузить только ту часть функций, которые ему необходимы. Это также позволяет нам избежать лишних зависимостей между скомпилированными программными пакетами.

Зависимости от других модулей.


Этот модуль имеет зависимости от следующих модулей (другими словами, ниже перечисленные модули должны быть загружены до загрузки этого модуля):

  • SER module sl: Модуль поддержи статусонезависимых сообщений.


Зависимости от внешних библиотек и приложений.


Следующие библиотеки или приложения должны быть установлены перед использованием OpenSER с этим модулем:

Нет.


Экспортируемые параметры.


secret (string)

Строка для Secret фазы.

По умолчанию: случайно сгенерированная строка.

Пример использования параметра secret:
modparam("auth", "secret", "johndoessecretphrase")


nonce_expire (integer)

Параметр Nonce имеет ограниченное время жизни. По истечении заданного периода времени, значение параметра nonce считается некорректным. Этот механизм используется для защиты от атак ответными сообщениями. Данные дайджест авторизации, содержащие просроченное значение параметра nonce, будут считаться некорректными, но для данного пользовательского агента будет начат новый процесс дайджест авторизации. при этом новые данные для дайджест авторизации, отправляемые пользователю, будут содержать такие же параметры, как и в предыдущей попытке, для указания на то, что агенту не нужно спрашивать пользователя его имя пользователя и пароль, он должен рассчитать новый ответ дайджест авторизации, используя существующее имя пользователя и пароль (и новое значение nonce).

Значение указывается в секундах, по умолчанию: 300 секунд.

Пример использования параметра nonce_expire:
modparam("auth", "nonce_expire", 600) # Установка времени жизни параметра nonce в 600 сек.


rpid_prefix (string)

Префикс, который будет добавляться к заголовочному полю Remote-Party-ID спереди, для значения URI, которое будет возвращено с radius сервера или из базы данных.

По умолчанию: "".

Пример использования параметра rpid_prefix:
modparam("auth", "rpid_prefix", "Whatever <")


rpid_suffix (string)

Суффикс, который будет добавляться к заголовочному полю Remote-Party-ID сзади, для значения URI, которое будет возвращено с radius сервера или из базы данных.

По умолчанию: ";party=calling;id-type=subscriber;screen=yes".

Пример использования параметра rpid_suffix:
modparam("auth", "rpid_suffix", "@1.2.3.4>")


realm_prefix (string)

Значение префикса, которое автоматически будет отрезаться от поля realm. Как альтернатива SRV записям (не все SIP клиенты поддерживают SRV записи), для главного домена может быть задан поддомен для обслуживания SIP протокола (например, sip.mydomain.net, который указывает на тот же IP адрес, что и SRV запись домена mydomain.net). Для того, чтобы проигнорировать этот префикс в имени домена, установим значение realm_prefix в значение - "sip." тогда, при авторизации, использование поддомена sip.mydomain.net будет эквивалентно использованию имени домена mydomain.net .

Значение, по умолчанию: пустая строка.

Пример использования параметра realm_prefix:
modparam("auth", "realm_prefix", "sip.")


rpid_avp (string)

Полная спецификация AVP, которая будет принимать значение поля RPID. Она используется для передачи значения RPID из backend модулей (auth_db или auth_radius) или из скрипта для функций авторизации: append_rpid_hf и is_rpid_user_e164.

Если указана нулевая строка, все функции, работающие RPID, будут завершаться с ошибкой при их вызове.

Значение, по умолчанию: "$avp(s:rpid)".

Пример использования параметра rpid_avp:
modparam("auth", "rpid_avp", "$avp(i:13)")



Экспортируемые функции


www_challenge(realm, qop)

Эта функция запускает процесс дайджест авторизации пользовательского агента. Она формирует заголовочное полк "WWW-Authorize", содержащее данные, необходимые для дайджест авторизации, потом помещает это заголовочное поле в ответное сообщение на запрос, который в данный момент обрабатывается и отправляет его. При получении этого ответа, пользовательский агент должен рассчитать ответ дайджест авторизации и повторить запрос. Для дополнительной информации о дайджест авторизации обратитесь к RFC2617.

Значения параметров следующие:

  • realm - Realm, это обычная строка, которую пользовательский агент должен предоставить пользователю, на основании которой он должен принять решение, какое имя пользователя и пароль нужно использовать. Обычно, это имя домена машины, на котором запущен сервер.

Если используется пустая строка (""), тогда сервер сгенерирует это поле, основываясь на данных из поступившего запроса. В случае сообщения REGISTER, будет использоваться доменная часть из поля "To" (т.к. это заголовочное поле представляет пользователя, который желает зарегистрироваться), для всех остальных сообщений будет использоваться доменная часть из поля "From".

Сорока может содержать псевдопеременные.

  • qop - Значение этого параметра может быть "1" или "0". Если установлен в 1, тогда сервер поместит параметр qop в данные дайджест авторизации. Если установлено в 0, тогда сервер не будет помещать параметр qop в данные дайджест авторизации. Очень рекомендуется использование параметра qop, однако, до сих пор существуют пользовательские агенты, которые не могут должным образом обработать параметр qop, для таких случаев, и предназначена эта установка. С другой стороны, есть и такие пользовательские агенты, которые не могут нормально обрабатывать запрос на авторизацию без этого параметра.

Эта функция может использоваться из блока REQUEST_ROUTE.

Пример использования функции www_challenge:
...
if (www_authorize("siphub.net", "subscriber")) {
www_challenge("siphub.net", "1");
};
...


proxy_challenge(realm, qop)

Эта функция запускает процесс дайджест авторизации пользовательского агента на прокси сервере. Она формирует заголовочное полк "Proxy-Authorize", содержащее данные, необходимые для дайджест авторизации, потом помещает это заголовочное поле в ответное сообщение на запрос, который в данный момент обрабатывается и отправляет его. При получении этого ответа, пользовательский агент должен рассчитать ответ дайджест авторизации и повторить запрос. Для дополнительной информации о дайджест авторизации обратитесь к RFC2617.

Значения параметров следующие:

  • realm - Realm, это обычная строка, которую пользовательский агент должен предоставить пользователю, на основании которой он должен принять решение, какое имя пользователя и пароль нужно использовать. Обычно, это имя домена машины, на котором запущен сервер.

Если используется пустая строка (""), тогда сервер сгенерирует это поле, основываясь на данных из поступившего запроса. Для этих целей будет использоваться доменная часть из заголовочного поля "From".

Сорока может содержать псевдопеременные.

  • qop - Значение этого параметра может быть "1" или "0". Если установлен в 1, тогда сервер поместит параметр qop в данные дайджест авторизации. Если установлено в 0, тогда сервер не будет помещать параметр qop в данные дайджест авторизации. Очень рекомендуется использование параметра qop, однако, до сих пор существуют пользовательские агенты, которые не могут должным образом обработать параметр qop, для таких случаев, и предназначена эта установка. С другой стороны, есть и такие пользовательские агенты, которые не могут нормально обрабатывать запрос на авторизацию без этого параметра.

Эта функция может использоваться из блока REQUEST_ROUTE.

Пример использования функции proxy_challenge:
...
if (!proxy_authorize("", "subscriber)) {
proxy_challenge("", "1"); # Realm будет автоматически сгенерирован
};
...


consume_credentials()

Эта функция удаляет уже проверенные данные дайджест авторизации из сообщения, которое в данный момент обрабатывается сервером. Этим достигается то, что при последующей пересылке этого сообщения далее, оно уже не будет содержать данных авторизации, которые предназначались нашему серверу. При этом гарантируется, что прокси сервер не покажет информацию, содержащую данные авторизации, последующим агентам, через которые оно пройдет, а также само сообщение станет немного короче. Эта функция должна использоваться после функций www_authorize или proxy_authorize.

Эта функция может использоваться из блока REQUEST_ROUTE.

Пример использования функции consume_credentials:
...
if (www_authorize("", "subscriber)) {
consume_credentials();
};
...


is_rpid_user_e164()

Функция проверяет, может ли SIP URI, полученный из базы данных или radius сервера, потенциально использоваться в заголовочном поле Remote-Party-ID, и содержит E164 номер (дополненное до 15 цифр) в части имени пользователя. Проверка будет неудачной, если SIP URI не существует (т.е. radius сервер или база данных не предоставила такие данные).

Эта функция может использоваться из блока REQUEST_ROUTE.

Пример использования функции is_rpid_user_e164:
...
if (is_rpid_user_e164()) {
# что-нибудь тут делаем....
};
...


append_rpid_hf()

Функция добавляет к сообщению заголовок Remote-Party-ID, который представляет собой заголовочное поле: 'Remote-Party-ID: ', далее, сохраненное значение SIP URI, полученное из базы данных или с radius сервера, и заканчивается значением параметра radius_rpid_suffix этого модуля. Функция ничего не делает, если не существует сохраненного значения SIP URI.

Эта функция может использоваться из блоков REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Пример использования функции append_rpid_hf:
...
append_rpid_hf(); # Добавляем заголовочное поле Remote-Party-ID
...


append_rpid_hf(prefix, suffix)

Назначение функции аналогично append_rpid_hf() (без параметров). С одним лишь различием, что она принимает два параметра - префикс и суффикс, которые добавляются к заголовочному полю Remote-Party-ID. Функция игнорирует значения параметров rpid_prefix и rpid_suffix.

Значения параметров следующие:

  • prefix - Префикс для Remote-Party-ID URI. Эта строка добавляется до тела заголовочного поля, сразу до значения в URI.

  • suffix - Суффикс для заголовочного поля Remote-Party-ID. Эта строка добавляется в конце этого заголовочного поля. Она может использоваться, например, в целях установки различных параметров для URI.

Эта функция может использоваться из блоков REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Пример использования функции append_rpid_hf(prefix, suffix):
...
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes"); # Добавляем заголовочное поле Remote-Party-ID
...


Ссылки по теме