Инструменты разработчика · Генератор UUID
Что делает строку UUID правильно сформированной и чего не может знать программа проверки
· Как это работает
uuid криптография API-интерфейс браузера
Прописные буквы, фигурные скобки, урна: префиксы и отсутствующие дефисы — все это появляется при реальном вводе. Этот пост определяет каноническую форму, показывает, что должен принять снисходительный валидатор, и отделяет правильность от существования.
400, который должен был быть 404 — насколько небрежная проверка UUID приводит к запутанным ошибкам API
Конечная точка API получает идентификатор от клиента: {12345678-90AB-CDEF-1234-567890ABCDEF}. Код проверки проверяет, соответствует ли он /[0-9a-f]{32}/, и отклоняет его как недействительный. Клиент получает 400 неверный запрос, где имелось в виду 404 Not Found. Идентификатор имеет правильный формат — это допустимый UUID в формате фигурных скобок, — но валидатор слишком строгий. И наоборот, конечная точка, которая принимает любую шестнадцатеричную строку символов 32 (без дефисов), примет 123456789012345678901234567890123456, проанализирует ее как допустимую и пропустит опечатку. RFC 9562 определяет каноническое текстовое представление, но реальные входные данные поступают в пяти различных форматах, и валидатор, который принимает только каноническую форму, отклонит 1 до 5 процентов ввода с благими намерениями.
Каноническая текстовая форма — 32 строчные шестнадцатеричные цифры в 8-4-4-4-12, ровно 36 символов, как указано в стандарте для вывода.
Каноническая текстовая форма представляет собой 32 строчные шестнадцатеричные цифры в пяти группах, разделенных дефисами: 8-4-4-4-12. Представлено как 550e8400-e29b-41d4-a716-446655440000. Стандарт требует использования нижнего регистра для вывода; при вводе рекомендуется использовать сопоставление без учета регистра. Эта форма однозначна, разбивается на байты одинаково на каждой платформе и является тем, что каждая библиотека UUID выводит по умолчанию. Если вы создаете новый UUID из CSPRNG, каноническая форма — это то, что вы должны создать, и то, что производит ToolAcre. Реальные входные данные отклоняются предсказуемым образом. Идентификаторы в верхнем регистре (550E8400-E29B-41D4-A716-446655440000) распространены в системах, в которых по умолчанию используется верхний регистр; они представляют одни и те же байты и должны быть приняты после нормализации к нижнему регистру.
Варианты, которые вы встретите в дикой природе — шестнадцатеричный регистр заглавных букв, {braces}, префикс urn:uuid: и формы без дефисов из 32, которые стандарт разрешает принимать.
Форма в фигурных скобках ({550e8400-e29b-41d4-a716-446655440000}) — это стандартный вывод модуля uuid Python и систем Microsoft; удаление фигурных скобок дает действительную каноническую форму. Префикс URN (urn:uuid:550e8400-e29b-41d4-a716-446655440000) определяется RFC 8141 для унифицированных имен ресурсов; удаление схемы и удаление префикса-идентификатора оставляет каноническую форму. Форма без дефиса (550e8400e29b41d4a716446655440000) представляет собой 32 шестнадцатеричных цифр без структуры; это допустимые байты, но теряется группировка 8-4-4-4-12, которая делает версии и варианты читабельными. Все эти варианты соответствуют одному и тому же 128-битному значению. RFC 9562 в разделе 3 указано, что на входе принимаются варианты SHOULD в верхнем регистре. Это не запрещает другие варианты; он говорит, что на выходе будет использоваться каноническая строчная форма MUST.
Разумность версии и варианта — следует ли отклонять UUID, третья группа которого начинается с 0 или чья четвертая группа начинается с f.
Правильно сформированный валидатор должен: принимать каноническую форму 8-4-4-4-12 в нижнем или верхнем регистре; принять варианты в скобках и urn:, удалив их и проверив основную форму; принимать шестнадцатеричные строки из 32 без дефиса и форматировать их как канонические для сравнения; отклонять строки с неправильным количеством шестнадцатеричных цифр или нешестнадцатеричных символов. Наиболее распространенной ошибкой является отказ от ввода заглавных букв или фигурных скобок, поскольку валидатор был написан вручную и соответствовал только канонической форме. Проверка работоспособности версии и варианта может выявить опечатки. Если третья группа начинается с 0 или 9, UUID недействителен или зарезервирован; если четвертая группа начинается с e или f, вариант не RFC 9562.
Рабочий пример: шесть строк-кандидатов проходят строгую и мягкую проверку с указанием причин, по которым каждая из них прошла или не прошла.
Снисходительный валидатор принимает эти значения; строгий валидатор может их отклонить. Правильно сформированная проверка ToolAcre выполняет строгую проверку: она подтверждает каноническую форму символов 36 с тире в нужных местах, проверяет шестнадцатеричные цифры в каждой позиции и проверяет, находятся ли биты версии и варианта в допустимом диапазоне. Он не проверяет, существует ли UUID в вашей базе данных или что он создан из криптографически безопасного источника; это отдельные проверки, выполняемые логикой вашего приложения. Хорошо сформированный – это не то же самое, что настоящий. Строка UUID, которая правильно анализируется в соответствии с ее формой, может не идентифицировать ни одну строку в вашей базе данных.
Хорошо сформированный — не настоящий — почему синтаксически совершенный UUID может не существовать в ваших данных и почему средство проверки никогда не должно быть вашим уровнем авторизации
А UUID который имеет идеальную форму, мог быть угадан или скопирован неправильно. Проверка формата — это первые ворота; проверки существования и проверки авторизации — вторая и третья. Выполнение поиска в базе данных для каждого ввода с недопустимым форматом является расточительным; отклонение ввода неверного формата до запроса к базе данных экономит время. ToolAcre стандартные выходы генератора 36-символьные UUID; если вы создаете свой собственный валидатор, примите варианты braceed и urn: для соответствия реальным входным данным и отклоняйте строки, которые не соответствуют основным правилам формы, прежде чем запрашивать вашу базу данных. Реализация строгого валидатора требует регулярных выражений и обработки крайних случаев. Каноническая форма проста: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i (без учета регистра). В фигурных скобках добавляются фигурные скобки: /^\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}$/i. Вариант urn: добавляет схему: /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.
Чего это не касается — нормализацию идентификаторов для хранения и выбор типа столбца, что является отдельными решениями.
Единственное регулярное выражение, обрабатывающее все варианты, менее читабельно, но возможно. Большинство валидаторов сначала нормализуют: удаляют фигурные скобки и префикс urn:, преобразуют в нижний регистр, а затем сопоставляют каноническому шаблону. Биты версии и варианта можно проверить после сопоставления с образцом, проверив позицию 14 и позицию 19, как описано в статье 403. Грамотная обработка недопустимых входных данных является частью разработки проверки. Когда клиент отправляет неверный формат UUID, не раскрывайте шаблон регулярного выражения или внутренние правила проверки в сообщении об ошибке. Верните явную ошибку: «Неверный формат UUID. Ожидается формат 8-4-4-4-12, например 550e8400-e29b-41d4-a716-446655440000 " Не пытайтесь исправить ввод; попросите клиента отправить заявку повторно.
Вывод: проверяйте форму заранее, ищите существование отдельно — проверка ToolAcre подтверждает форму в браузере, прежде чем вы прикоснетесь к базе данных.
Некоторые системы регистрируют неверный ввод для аудита безопасности (обнаружения попыток внедрения или атак, связанных с путаницей формата). Валидатор ToolAcre отклоняет неканонические формы с четким сообщением об ошибке и не пытается выполнить автоисправление. Почему каноническая форма важна для совместимости: если одна система хранит UUID в шестнадцатеричном виде без дефиса, а другая — как каноническую 8-4-4-4-12, сравнение их на равенство требует нормализации. Прописные и строчные буквы требуют сравнения без учета регистра. Закрепленный или голый требует зачистки. Эти различия усложняют массовые операции (импорт, миграцию, сравнение). Стандартные инструменты, выводящие каноническую форму, уменьшают трение. Генератор ToolAcre всегда выводит каноническую форму нижнего регистра из 36 символов; когда вы импортируете UUID из других систем, нормализуйте их до этой формы в процессе ETL, чтобы обеспечить согласованность.