Обработка обратных вызовов авторизации во время компиляции

int sqlite3_set_authorizer(
  sqlite3*,
  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  void *pUserData
);

Эта процедура регистрирует обратный вызов авторизации в определенном соединении с базой данных, указанном в первом аргументе. Обратный вызов авторизации вызывается при компиляции SQL-запросов с помощью sqlite3_prepare() или его вариантов sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16(), sqlite3_prepare16_v2() и sqlite3_prepare16_v3(). В различные моменты процесса компиляции, при создании логики для выполнения различных действий, обратный вызов авторизации вызывается, чтобы определить, разрешены ли эти действия. Обратный вызов авторизации должен возвращать SQLITE_OK, чтобы разрешить действие, SQLITE_IGNORE, чтобы запретить конкретное действие, но позволить продолжить компиляцию SQL-запроса, или SQLITE_DENY, чтобы отклонить весь SQL-запрос с ошибкой. Если обратный вызов авторизации возвращает значение, отличное от SQLITE_IGNORE, SQLITE_OK или SQLITE_DENY, то вызов sqlite3_prepare_v2() или эквивалентный вызов, который вызвал обратный вызов авторизации, завершится с сообщением об ошибке.

Когда обратный вызов возвращает SQLITE_OK, это означает, что запрашиваемая операция разрешена. Когда обратный вызов возвращает SQLITE_DENY, вызов sqlite3_prepare_v2() или эквивалентный вызов, который вызвал обратный вызов авторизации, завершится с сообщением об ошибке, объясняющим, что доступ запрещен.

Первый параметр обратного вызова авторизации — копия третьего параметра интерфейса sqlite3_set_authorizer(). Второй параметр обратного вызова — целочисленный код действия, который указывает конкретное действие, которое необходимо авторизовать. Третий по шестой параметры обратного вызова — либо указатели NULL, либо завершающиеся нулём строки, содержащие дополнительные сведения об авторизуемом действии. Приложения должны быть готовы к встрече с указателем NULL в любом из третьих по шестой параметров обратного вызова авторизации.

Если код действия равен SQLITE_READ, а обратный вызов возвращает SQLITE_IGNORE, то подготовленное утверждение (prepared statement) создается таким образом, чтобы заменить значение NULL в столбце таблицы, который был бы прочитан, если бы был возвращён SQLITE_OK. Возврат SQLITE_IGNORE может использоваться для отказа недоверенному пользователю доступа к отдельным столбцам таблицы. Когда к таблице обращаются с помощью SELECT, но значения столбцов из этой таблицы не извлекаются (например, в запросе "SELECT count(*) FROM tab"), то обратный вызов авторизации SQLITE_READ вызывается один раз для этой таблицы со именем столбца, которое является пустой строкой. Если код действия равен SQLITE_DELETE, а обратный вызов возвращает SQLITE_IGNORE, то операция DELETE выполняется, но оптимизация truncate отключается, и все строки удаляются по отдельности.

Авторизатор используется при подготовке SQL-запросов из недоверенного источника, чтобы убедиться, что SQL-запросы не пытаются получить доступ к данным, к которым у них нет доступа, или не пытаются выполнить вредоносные запросы, повреждающие базу данных. Например, приложение может разрешить пользователю вводить произвольные SQL-запросы для обработки базой данных. Но приложение не хочет, чтобы пользователь мог произвольно изменять базу данных. Тогда можно установить авторизатор во время подготовки введённого пользователем SQL, который запрещает всё, кроме SELECT-запросов.

Приложения, которым нужно обрабатывать SQL-запросы из недоверенных источников, также могут рассмотреть возможность снижения лимитов ресурсов с помощью sqlite3_limit() и ограничения размера базы данных с помощью max_page_count PRAGMA в дополнение к использованию авторизатора.

Одновременно в соединении с базой данных может быть только один авторизатор. Каждый вызов sqlite3_set_authorizer перезаписывает предыдущий вызов. Авторизатор отключается путём установки обратного вызова NULL. По умолчанию авторизатор отключён.

Обратный вызов авторизатора не должен выполнять никаких действий, которые изменят соединение с базой данных, которое вызвало обратный вызов авторизатора. Обратите внимание, что sqlite3_prepare_v2() и sqlite3_step() оба изменяют свои соединения с базой данных в том смысле, который указан в этом абзаце.

При использовании sqlite3_prepare_v2() для подготовки оператора, оператор может быть повторно подготовлен во время sqlite3_step() из-за изменения схемы. Следовательно, приложение должно обеспечить, чтобы правильный обратный вызов авторизатора оставался активным во время sqlite3_step().

Обратите внимание, что обратный вызов авторизатора вызывается только во время sqlite3_prepare() или его вариантов. Авторизация не выполняется во время оценки оператора в sqlite3_step(), за исключением случаев, упомянутых в предыдущем абзаце, когда sqlite3_step() вызывает sqlite3_prepare_v2() для повторной подготовки оператора после изменения схемы.

См. также списки объектов, констант и функций.