OpenSER модуль permissions

Обзор.

Маршрутизация вызовов.

Этот модуль может использоваться для определения прав на возможность совершения того или иного вызова. Правила для разрешения или запрещения вызовов хранятся в обычных текстовых файлах конфигурации, наподобие файлов: hosts.allow и hosts.deny, которые использует tcpd.

При вызове функции allow_routing, она попытается найти правило, которое бы соответствовало указанным полям сообщения.

OpenSER - может разветвлять сообщение по нескольким направлениям, и одно сообщение может быть отправлено одновременно по различным адресам. При проверке наличия прав на маршрутизацию, должны быть проверены все адресаты и, если один из них не имеет соответствующих прав, то пересылка сообщения производиться не будет.

Проверка полномочий производиться следующим образом, проверка заканчивается на первом совпадении:

Создается набор пар в форме: (From, R-URI для ответвления (branch) номер 1), (From, R-URI для ответвления 2), и т.д.
Маршрутизация сообщения разрешается, если все пары проходят проверку в файле allow.
Иначе, маршрутизация будет запрещена, если хотя бы одна пара из созданного набора подпадает под правило из файла deny.
Иначе, маршрутизация сообщения разрешается.

Если не существует какого-либо файла для проверки доступа, то он будет рассматриваться как, если бы он был пустым файлом. Таким образом, проверку доступа можно выключить, если не создавать вообще фалов с правилами для маршрутизации сообщений.

Заголовочное поле "From" и поля "Request-URI" всегда проверяются при помощи регулярных выражений! Для информации о синтаксисе смотри файл с примерами: config/permissions.allow.

Проверка прав доступа для регистрации.

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

Основное назначение этой функциональности - это запрещение попыток регистрации с "запрещенных" IP адресов. Например, когда злоумышленник регистрирует "пользователя", который содержит IP адрес PSTN шлюза, он имел бы возможность обойти проверку авторизации, которую производит SIP прокси сервер. Это является нежелательным моментом, и поэтому, попытки регистрации IP адреса PSTN шлюза должны быть запрещены. В файлах: config/register.allow и config/register.deny Вы сможете найти примеры конфигураций.

Функция для проверки возможности регистрации имеет имя - allow_register, и алгоритм ее работы очень схож с алгоритмом проверки прав на маршрутизацию сообщений, который был описан в предыдущем разделе. С одним лишь различием в том, как создаются пары, которые участвуют в проверке.

Вместо заголовочного поля "From" используется поле "To", потому что заголовочное поле "To" в сообщении REGISTER содержит URI регистрируемой персоны. Вместо Request-URI для ответвлений, функция использует заголовочное поле "Contact".

Таким образом, пары, используемые для проверки, будут выглядеть следующим образом: (To, Contact 1), (To, Contact 2), (To, Contact 3), и т.д.

Алгоритм поиска совпадений совпадает с тем, который используется для проверки прав на маршрутизацию сообщений.

Проверка прав доступа для URI.

Этот модуль может использоваться, для контроля прохождения сообщения адресату, основываясь на значении URI, сохраненного в псевдопеременной. Правила с правами доступа хранятся в обычных текстовых файлах, наподобие: hosts.allow и hosts.deny, которые использует tcpd.

При вызове функции allow_uri, она пытается найти соответствующее правило, которое соответствовало бы указанному значению сообщения.
Проверка полномочий производиться следующим образом, проверка заканчивается на первом совпадении:

Создается пара: (From URI, URI сохраненное в псевдопеременной).
Маршрутизация сообщения разрешается, если пара проходит проверку в файле allow.
Иначе, маршрутизация будет запрещена, если пара подпадает под правило из файла deny.
Иначе, маршрутизация сообщения разрешается.

Если не существует какого-либо файла проверки доступа, то этот случай будет рассматриваться так, если бы он был пустым файлом. Таким образом, проверку доступа можно выключить, если не создавать вообще фалов с правилами для проверки прав доступа.

Пара From URI и URI, сохраненное в псевдопеременной, всегда проверяются при помощи регулярных выражений! Для информации о синтаксисе смотри файл с примерами: config/permissions.allow.

Проверка прав доступа для адреса.

Этот модуль может использоваться, для контроля прохождения сообщения адресату, основываясь на том, совпадает ли адрес (IP адрес и номер порта) с любой из IP подсетей, которые хранится в кэшируемой базе данных сервера openser. Номер порта 0 в этой базе подразумевает любой порт. Адрес IP и порт для проверки может быть взят из самого запроса (allow_source_address) или передан в виде аргумента с именем псевдопеременной (allow_address).

Адреса, сохраненные в кэшируемой базе данных, могут группироваться в одну или несколько групп, с определенным идентификатором (целое число без знака). Идентификатор группы может использоваться как параметр функции allow_source_address или указываться отдельной функцией set_address_group для последующих вызовов функции allow_address.

Доверяемые Запросы (Trusted Requests)

Этот модуль может использоваться для определения того, каким поступившим запросам мы можем доверять без проверки авторизации.

Когда вызывается функция allow_trusted, она пытается найти правило, которое подходило бы для поступившего запроса. Правило содержит следующие поля: <IP адрес источника, транспортный протокол, регулярное выражение>.

Запрос будет принят, если существует правило в котором:

IP адрес источника совпадает с адресом запроса.
Транспортный протокол имеет значение "any" или совпадает с протоколом, по которому поступил запрос.
Регулярное выражение является пустой строкой (зн. NULL в базе данных) или совпадает с полем "From URI" запроса.

В противном случае запрос будет отклонен.

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

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

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

Нет.

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

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

Нет.

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

default_allow_file (string)

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

Значение, по умолчанию: "permissions.allow".

Пример использования параметра default_allow_file:
...
modparam("permissions", "default_allow_file", "/etc/permissions.allow")
...

default_deny_file (string)

Файл, по умолчанию, в котором ищутся запрещающие правила для функций, не имеющих параметров. Если Вы не укажете полный путь, то будет использоваться путь относительно директории, где находиться основной конфигурационный файл.

Значение, по умолчанию: "permissions.deny".

Пример использования параметра default_deny_file:
...
modparam("permissions", "default_deny_file", "/etc/permissions.deny")
...

check_all_branches (integer)

Если параметр установлен в единицу, тогда функция allow_routing будет проверять поля Request-URI для всех возможных ответвлений в маршруте (branches) (поведение по умолчанию). В противном случае, будет проверяться значение Request-URI только для первого ответвления (branch).

exclaim

Не меняйте значение этого параметра в ноль, если Вы точно не уверены в последствиях!

Значение, по умолчанию: 1.

Пример использования параметра check_all_branches:
...
modparam("permissions", "check_all_branches", 0)
...

allow_suffix (string)

Суффикс (расширение), который будет добавлен к базовой части имени файла, при формировании названия файла, содержащего allow-правила, при использовании версий функций allow_routing или allow_register с одним параметром.

Суффикс должен определяться вместе с ведущей точкой.

Значение, по умолчанию: ".allow".

Пример использования параметра allow_suffix:
...
modparam("permissions", "allow_suffix", ".allow")
...

deny_suffix (string)

Суффикс (расширение), который будет добавлен к базовой части имени файла, при формировании названия файла, содержащего deny-правила, при использовании версий функций allow_routing или allow_register с одним параметром.

Суффикс должен определяться вместе с ведущей точкой.

Значение, по умолчанию: ".deny".

Пример использования параметра deny_suffix:
...
modparam("permissions", "deny_suffix", ".deny")
...

db_url (string)

Параметр используется для определения URL для доступа к базе данных, в которой хранятся правила доступа, используемые функцией allow_trusted.

Значение, по умолчанию: "NULL".

Пример использования параметра db_url:
...
modparam("permissions", "db_url", "mysql://openser:pass@db_host/openser")
...

address_table (string)

Имя таблицы в базе данных, содержащей информацию о IP подсетях, которая используется функциями by allow_address и allow_source_address.

Значение, по умолчанию: "address".

Пример использования параметра address_table:
...
modparam("permissions", "address_table", "addr")
...

grp_col (string)

Имя колонки в таблице address, содержащее идентификатор группы для подсетей.

Значение, по умолчанию: "grp".

Пример использования параметра grp_col:
...
modparam("permissions", "grp_col", "group_id")
...

ip_addr_col (string)

Имя колонки в таблице address, содержащее IP адрес подсети.

Значение, по умолчанию: "ip_addr".

Пример использования параметра ip_addr_col:
...
modparam("permissions", "ip_addr_col", "ip_address")
...

mask_col (string)

Имя колонки в таблице address, содержащее длину маски подсети. Возможные значения: 0-32.

Значение, по умолчанию: "mask".

Пример использования параметра mask_col:
...
modparam("permissions", "mask_col", "subnet_length")
...

port_col (string)

Имя колонки в таблице address, содержащее номер порта адреса.

Значение, по умолчанию: "port"

Пример использования параметра port_col:
...
modparam("permissions", "port_col", "prt")
...

db_mode (integer)

Режим работы с базой данных. 0 - подразумевает отсутствие кэширование, 1 - включает кэширование. Предназначено только для функции allow_trusted.

Значение, по умолчанию: 0 (кэширование отключено).

Пример использования параметра db_mode:
...
modparam("permissions", "db_mode", 1)
...

trusted_table (string)

Имя таблицы в базе данных, содержащей правила доступа, используемые функцией allow_register.

Значение, по умолчанию: "trusted".

Пример использования параметра trusted_table:
...
modparam("permissions", "trusted_table", "pbx")
...

source_col (string)

Имя колонки в таблице trusted_table, содержащей IP адрес источника для проверки IP адреса источника принятого запроса.

Значение, по умолчанию: "src_ip".

Пример использования параметра source_col:
...
modparam("permissions", "source_col", "source_ip_address")
...

proto_col (string)

Имя колонки в таблице trusted_table, содержащей название транспортного протокола для проверки протокола принятого запроса. Возможные значения, которые может содержать эта колонка, следующие: "any", "udp", "tcp", "tls", "sctp", и "none". Значение "any" соответствует всем протоколам, "none" - не одному из них.

Значение, по умолчанию: "proto".

Пример использования параметра proto_col:
...
modparam("permissions", "proto_col", "transport")
...

from_col (string)

Имя колонки в таблице trusted_table, содержащей регулярное выражение для проверки URI в поле From.

Значение, по умолчанию: "from_pattern".

Пример использования параметра from_col:
...
modparam("permissions", "from_col", "regexp")
...

tag_col (string)

Имя колонки в таблице trusted_table, содержащей строку, которая будет помещена в peer_tag AVP , если peer_tag AVP определена и запрос подошел под данное правило.

Значение, по умолчанию: "tag".

Пример использования параметра tag_col:
...
modparam("permissions", "tag_col", "peer_tag")
...

peer_tag_avp (string)

Определение для AVP, в которой будет помещено значение peer_tag. Если данный параметр определен, значение AVP будет устанавливаться равным полю tag, если оно содержит не нулевое значение, как побочный эффект работы функции allow_trusted() для найденного соответствия записи запросу.

Значение, по умолчанию: "undefined".

Пример использования параметра peer_tag_avp:
...
modparam("permissions", "peer_tag_avp", "i:707")
...

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

allow_routing()

Функция возвращает true, если все пара, которые были сконструированы согласно разделу Маршрутизация вызовов, прошли проверку на наличие прав доступа, согласно файлам конфигурации. Эта функция использует файлы конфигурации, по умолчанию, заданные параметрами default_allow_file и default_deny_file.

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

Пример использования функции allow_routing:
...
if (allow_routing()) {
t_relay();
};
...

allow_routing(basename)

Функция возвращает true, если все пара, которые были сконструированы согласно разделу Маршрутизация вызовов, прошли проверку на наличие прав доступа, согласно файлам конфигурации, имена которых конструируются согласно заданному параметру.

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

basename - Базовая часть имени файла, из которого имена для allow и deny файлов создаются путем добавления суффиксов, которые указаны в параметрах: allow_suffix и deny_suffix.

Если в параметре указан не полный абсолютный путь, тогда подразумевается, что указан путь к файлам относительно директории, где располагается основной файл конфигурации сервера.

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

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

allow_routing(allow_file,deny_file)

Функция возвращает true, если все пара, которые были сконструированы согласно разделу Маршрутизация вызовов, прошли проверку на наличие прав доступа, согласно файлам конфигурации, имена которых указаны в качестве параметров.

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

allow_file - файл, содержащий правила allow.
deny_file - файл, содержащий правила deny.

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

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

Пример использования функции allow_routing(allow_file, deny_file):
...
if (allow_routing("rules.allow", "rules.deny")) {
t_relay();
};
...

allow_register(basename)

Функция возвращает true, если все пара, которые были сконструированы согласно разделу Проверка прав доступа для регистрации, прошли проверку на наличие прав доступа, согласно файлам конфигурации, имена которых конструируются согласно заданному параметру.

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

basename - Базовая часть имени файла, из которого имена для allow и deny файлов создаются путем добавления суффиксов, которые указаны в параметрах: allow_suffix и deny_suffix.

Пример использования функции allow_register(basename):
...
if (method=="REGISTER") {
if (allow_register("register")) {
save("location");
break;
} else {
sl_send_reply("403", "Forbidden");
};
};
...

allow_register(allow_file, deny_file)

Функция возвращает true, если все пара, которые были сконструированы согласно разделу Проверка прав доступа для регистрации, прошли проверку на наличие прав доступа, согласно файлам конфигурации, имена которых указаны в качестве параметров.

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

allow_file - файл, содержащий правила allow.
deny_file - файл, содержащий правила deny.

Пример использования функции allow_register(allow_file, deny_file):
...
if (method=="REGISTER") {
if (allow_register("register.allow", "register.deny")) {
save("location");
break;
} else {
sl_send_reply("403", "Forbidden");
};
};
...

allow_uri(basename, pseudo-variable)

Функция возвращает true, если все пара, которые были сконструированы согласно разделу Проверка прав доступа для URI, прошли проверку на наличие прав доступа, согласно файлам конфигурации, имена которых конструируются согласно заданному параметру.

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

basename - Базовая часть имени файла, из которого имена для allow и deny файлов создаются путем добавления суффиксов, которые указаны в параметрах: allow_suffix и deny_suffix.

pseudo-variable - любая псевдопеременная, определенная в OpenSER.

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

Пример использования функции allow_uri(basename, pseudo-variable):
...
if (allow_uri("basename", "$rt")) { // Проверка Refer-To URI
t_relay();
};
if (allow_uri("basename", "$avp(i:705)") { // Проверка URI, сохраненного в $avp(i:705)
t_relay();
};
...

set_address_group(group_id)

Функция устанавливает значения для группы, которая будет использоваться последующими вызовами функции allow_address, в целое беззнаковое число, указанное в аргументе. Аргументом может быть строка с числом или имя псевдопеременной.

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

Пример использования функции set_address_group(group_id):
...
// Установка идентификатора группы для проверки подсетей в 1.
set_address_group("1");
// Установка идентификатора группы для проверки подсетей в значение из псевдопеременной i:100.
set_address_group("$avp(i:100)");
...

allow_address(ip_addr_pv, port_pv)

Функция возвращает true, если пара IP адрес/порт, получаемые из псевдопеременных указанных в качестве аргумента, и, возможно указанный ранее, идентификатор группы адресов найден в таблице IP подсетей, кэшируемой таблице адресов. Запись в кэшируемой таблице с номером порта равным нулю подразумевает любой порт.

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

Пример использования функции allow_address(ip_addr_pv, port_pv):
...

// Проверка пары address/port источника запроса
if (!allow_address("$si", "$sp")) {
sl_send_reply("403", "Forbidden");
};
// Проверка пары address/port сохраненных в avp i:704/i:705
if (!allow_address("$avp(i:704)", "$avp(i:705)") {
sl_send_reply("403", "Forbidden");
};
...

allow_source_address(group_id)

Эквивалент вызова функций: set_address_group(group_id); allow_address("$si", "$sp"), но работает быстрее.

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

Пример использования функции allow_source_address(group_id):
...

// Проверка пары address/port источника запроса
if (!allow_source_address("0")) {
sl_send_reply("403", "Forbidden");
};
...

allow_trusted()

Функция производит проверку, основываясь на адресе источника запроса, транспортном протоколе и URI в поле From. Если запрос входит в доверительный (trusted) список адресов для которых не требуется авторизация, функция возвращает 1 (Алгоритм проверки описан в разделе Доверяемые Запросы), иначе - возвращает "-1". Если найдено совпадение и определено значение peer_tag_avp, функция добавит значение ненулевого поля tag найденного совпадения в AVP: peer_tag_avp.

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

Пример использования функции allow_trusted():
...
if (allow_trusted()) {
t_relay();
};
...