Спецификация обновления программного обеспечения

Обзор

I2P использует простую, но безопасную систему автоматического обновления программного обеспечения. Консоль router периодически загружает файл новостей с настраиваемого I2P URL. Существует жестко заданный резервный URL, указывающий на сайт проекта, на случай если основной хост новостей проекта станет недоступен.

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

Router может опционально загрузить или загрузить и установить новую версию, если он настроен для этого.

Спецификация файла старых новостей

Этот формат заменен форматом новостей su3 начиная с релиза 0.9.17.

Файл news.xml может содержать следующие элементы:

<i2p.news date="$Date: 2010-01-22 00:00:00 $" />
<i2p.release version="0.7.14" date="2010/01/22" minVersion="0.6" />

Параметры в записи i2p.release следующие. Все ключи нечувствительны к регистру. Все значения должны быть заключены в двойные кавычки.

date : Дата выпуска версии router. Не используется. Формат не указан.

minJavaVersion : Минимальная версия Java, необходимая для запуска текущей версии. Начиная с релиза 0.9.9.

minVersion : Минимальная версия router’а, необходимая для обновления до текущей версии. Если router старше этой версии, пользователь должен (вручную?) сначала обновиться до промежуточной версии. По состоянию на версию 0.9.9.

su3Clearnet : Один или несколько HTTP URL-адресов, где файл обновления .su3 может быть найден в clearnet (не-I2P). Несколько URL-адресов должны быть разделены пробелом или запятой. Начиная с релиза 0.9.9.

su3SSL : Один или несколько HTTPS URL, где файл обновления .su3 может быть найден в обычной сети (не-I2P). Несколько URL должны быть разделены пробелом или запятой. Начиная с версии 0.9.9.

sudTorrent : Магнитная ссылка для .sud (не pack200) торрента обновления. Начиная с релиза 0.9.4.

su2Torrent : Магнитная ссылка для .su2 (pack200) торрента обновления. Начиная с версии 0.9.4.

su3Torrent : Магнитная ссылка для .su3 (новый формат) торрента обновления. Начиная с версии 0.9.9.

version : Обязательно. Последняя доступная версия router.

Элементы могут быть включены внутри XML-комментариев для предотвращения интерпретации браузерами. Элемент i2p.release и версия являются обязательными. Все остальные элементы являются опциональными. ПРИМЕЧАНИЕ: Из-за ограничений парсера весь элемент должен находиться на одной строке.

Спецификация файла обновления

Начиная с версии 0.9.9, подписанный файл обновления с именем i2pupdate.su3 будет использовать формат файла “su3”, описанный ниже. Утвержденные подписчики релизов будут использовать 4096-битные RSA ключи. X.509 сертификаты открытых ключей для этих подписчиков распространяются в установочных пакетах router. Обновления могут содержать сертификаты для новых, утвержденных подписчиков и/или содержать список сертификатов для удаления при отзыве.

Спецификация старого файла обновления

Этот формат устарел начиная с версии 0.9.9.

Подписанный файл обновления, традиционно называемый i2pupdate.sud, представляет собой обычный zip-файл с добавленным в начало 56-байтовым заголовком. Заголовок содержит:

• 40-байтовая DSA подпись
• 16-байтовая версия I2P в UTF-8, дополненная нулями в конце при необходимости

Подпись покрывает только zip-архив - не добавленную версию. Подпись должна соответствовать одному из DSA SigningPublicKey , настроенных в router, который имеет жестко заданный по умолчанию список ключей текущих менеджеров релизов проекта.

Для целей сравнения версий поля версии содержат [0-9]*, разделители полей — ‘-’, ‘_’ и ‘.’, все остальные символы игнорируются.

Начиная с версии 0.8.8, версия также должна быть указана в комментарии zip-файла в кодировке UTF-8, без завершающих нулей. Обновляющий router проверяет, что версия в заголовке (не покрытая подписью) соответствует версии в комментарии zip-файла, который покрыт подписью. Это предотвращает подделку номера версии в заголовке.

Загрузка и установка

Router сначала загружает заголовок файла обновления с одного из настраиваемого списка I2P URL-адресов, используя встроенный HTTP-клиент и прокси, и проверяет, что версия новее. Это предотвращает проблему с серверами обновлений, которые не имеют последнего файла. Затем router загружает полный файл обновления. Router проверяет, что версия файла обновления новее перед установкой. Он также, конечно, проверяет подпись и проверяет, что комментарий zip-файла соответствует версии заголовка, как объяснено выше.

Zip-файл извлекается и копируется в “i2pupdate.zip” в конфигурационном каталоге I2P (~/.i2p в Linux).

Начиная с версии 0.7.12, router поддерживает распаковку Pack200. Файлы внутри zip-архива с суффиксом .jar.pack или .war.pack прозрачно распаковываются в .jar или .war файлы. Файлы обновлений, содержащие .pack файлы, традиционно именуются с суффиксом ‘.su2’. Pack200 сжимает файлы обновлений примерно на 60%.

Начиная с версии 0.8.7, router будет удалять файлы libjbigi.so и libjcpuid.so, если zip-архив содержит файл lib/jbigi.jar, чтобы новые файлы извлекались из jbigi.jar.

Начиная с версии 0.8.12, если zip-архив содержит файл deletelist.txt, router удалит файлы, перечисленные в нем. Формат следующий:

• Одно имя файла на строку
• Все имена файлов указываются относительно каталога установки; абсолютные пути не допускаются, файлы не могут начинаться с “..”
• Комментарии начинаются с ‘#’

Router затем удалит файл deletelist.txt.

Спецификация файла SU3

Данная спецификация используется для обновлений router начиная с релиза 0.9.9, данных reseed начиная с релиза 0.9.14, плагинов начиная с релиза 0.9.15, и новостного файла начиная с релиза 0.9.17.

Проблемы с предыдущим форматом .sud/.su2

• Нет магического числа или флагов
• Нет способа указать сжатие, pack200 или нет, или алгоритм подписи
• Версия не покрывается подписью, поэтому она принудительно требуется в комментарии zip-файла (для файлов router) или в файле plugin.config (для плагинов)
• Подписант не указан, поэтому верификатор должен попробовать все известные ключи
• Формат подпись-перед-данными требует двух проходов для генерации файла

Цели

• Исправить вышеуказанные проблемы
• Мигрировать на более безопасный алгоритм подписи
• Сохранить информацию о версии в том же формате и смещении для совместимости с существующими проверщиками версий
• Одноэтапная проверка подписи и извлечение файла

Спецификация

Детали подписи

Подпись покрывает весь заголовок, начиная с байта 0, и до конца содержимого. Мы используем необработанные подписи. Вычислите хеш данных (используя тип хеша, определяемый типом подписи в байтах 8-9) и передайте его в “необработанную” функцию подписи или проверки (например, “NONEwithRSA” в Java).

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

Длины подписей для различных типов подписей приведены в спецификации Signature . При необходимости дополните подпись ведущими нулями. См. страницу с деталями криптографии для параметров различных типов подписей.

Примечания

Тип контента указывает домен доверия. Для каждого типа контента клиенты поддерживают набор сертификатов открытых ключей X.509 для сторон, которым доверено подписывать данный контент. Могут использоваться только сертификаты для указанного типа контента. Сертификат находится по идентификатору подписавшего. Клиенты должны проверять, что тип контента соответствует ожидаемому для приложения.

Все значения представлены в сетевом порядке байтов (big endian).

Для реализации Raw RSA подписей на Python, совместимых с Java “NONEwithRSA”, см. эту статью на Stack Overflow .

Спецификация файла обновления router SU3

Подробности SU3

• Тип содержимого SU3: 1 (ОБНОВЛЕНИЕ РОУТЕРА)
• Тип файла SU3: 0 (ZIP)
• Версия SU3: Версия router

Файлы jar и war в zip больше не сжимаются с помощью pack200, как было задокументировано выше для файлов “su2”, поскольку современные среды выполнения Java больше не поддерживают это.

Примечания

• Для релизов версия SU3 является “базовой” версией router, например “0.9.20”.
• Для сборок разработки, которые поддерживаются начиная с релиза 0.9.20, версия SU3 является “полной” версией router, например “0.9.20-5” или “0.9.20-5-rc”. См. RouterVersion.java в исходном коде I2P .

Спецификация файла SU3 Reseed

Начиная с версии 0.9.14, данные reseed доставляются в формате файла “su3”.

Цели

• Подписанные файлы с сильными подписями и доверенными сертификатами для предотвращения атак “человек посередине”, которые могут загрузить жертв в отдельную недоверенную сеть.
• Использование формата файлов su3, уже используемого для обновлений и плагинов
• Единый сжатый файл для ускорения пересеивания, которое было медленным при загрузке 200 файлов

Спецификация

1. Файл должен называться “i2pseeds.su3”. Начиная с версии 0.9.42, запрашивающая сторона должна добавлять строку запроса “?netid=2” к URL запроса, предполагая текущий идентификатор сети 2. Это может использоваться для предотвращения межсетевых соединений. Тестовые сети должны устанавливать другой идентификатор сети. См. предложение 147 для подробностей.
2. Файл должен находиться в том же каталоге, что и router info на веб-сервере.
3. router сначала попытается получить (URL индекса)/i2pseeds.su3; если это не удастся, он получит URL индекса, а затем получит отдельные файлы router info, найденные в ссылках.

Детали SU3

• SU3 Content Type: 3 (RESEED)
• SU3 File Type: 0 (ZIP)
• SU3 Version: Секунды с начала эпохи, в ASCII (date +%s). НЕ переполняется в 2038 или 2106 году.
• Файлы информации о router в zip-файле должны находиться на “верхнем уровне”. В zip-файле нет директорий.
• Файлы информации о router должны быть названы “routerInfo-(44-символьный base 64 router hash).dat”, как в старом механизме reseed. Должен использоваться алфавит I2P base 64.

Примечания

• Предупреждение: Известно, что несколько reseed недоступны через IPv6. Рекомендуется принудительно использовать или отдавать предпочтение IPv4.
• Предупреждение: Некоторые reseed используют самоподписанные сертификаты CA. Реализации должны либо импортировать и доверять этим CA при reseed, либо исключить самоподписанные reseed из списка reseed.
• Ключи подписи reseed распространяются в реализации как самоподписанные X.509 сертификаты с ключами RSA-4096 (тип подписи 6). Реализации должны проверять действительные даты в сертификатах.

Спецификация файлов плагинов SU3

Начиная с версии 0.9.15, плагины могут быть упакованы в формате файлов “su3”.

Детали SU3

• SU3 Content Type: 2 (PLUGIN)
• SU3 File Type: 0 (ZIP) - См. спецификацию плагина для подробностей.
• SU3 Version: Версия плагина, должна соответствовать указанной в plugin.config.

Файлы jar и war в архиве не должны сжиматься с помощью pack200, как описано выше для файлов “su2”, поскольку современные среды выполнения Java больше не поддерживают это.

Спецификация файла новостей SU3

Начиная с версии 0.9.17, новости доставляются в формате файла “su3”.

Цели

• Подписанные новости с надежными подписями и доверенными сертификатами
• Использование формата файлов su3, уже применяемого для обновлений, reseeding и плагинов
• Стандартный формат XML для использования со стандартными парсерами
• Стандартный формат Atom для использования со стандартными программами чтения и генерации лент
• Очистка и проверка HTML перед отображением в консоли
• Подходит для простой реализации на Android и других платформах без HTML-консоли

Подробности SU3

• SU3 Content Type: 4 (NEWS)
• SU3 File Type: 1 (XML) или 3 (XML.GZ)
• SU3 Version: Секунды с начала эпохи, в ASCII (date +%s). НЕ сбрасывается в 2038 или 2106 году.
• File Format: XML или сжатый gzip XML, содержащий RFC 4287 (Atom) XML Feed. Кодировка должна быть UTF-8.

Подробности Atom Feed

Используются следующие элементы <feed>:

<entry> : Новостная запись. См. ниже.

<i2p:release> : Метаданные обновления I2P. См. ниже.

<i2p:revocations> : Отзывы сертификатов. См. ниже.

<i2p:blocklist> : Данные списка блокировки. См. ниже.

<updated> : Обязательно. Временная метка для ленты (соответствующая RFC 4287 раздел 3.3 и RFC 3339 ).

Подробности записи Atom

Каждый элемент Atom <entry> в новостной ленте может быть обработан и отображен в консоли router. Используются следующие элементы:

<author> : Необязательный. Содержит <name> - Имя автора записи.

<content> : Обязательный. Содержимое, должно быть type=“xhtml”. XHTML будет очищен с помощью белого списка разрешенных элементов и черного списка запрещенных атрибутов. Клиенты могут игнорировать элемент, или содержащую его запись, или всю ленту при обнаружении элемента, не входящего в белый список.

<link> : Необязательно. Ссылка для дополнительной информации.

<summary> : Необязательно. Краткое описание, подходящее для всплывающей подсказки.

<title> : Обязательно. Заголовок новостной записи.

<updated> : Обязательное. Временная метка для этой записи (соответствующая RFC 4287 раздел 3.3 и RFC 3339 ).

Подробности Atom i2p:release

В ленте должен быть как минимум один элемент <i2p:release>. Каждый содержит следующие атрибуты и сущности:

date (атрибут) : Обязательный. Временная метка для данной записи (соответствующая RFC 4287 раздел 3.3 и RFC 3339 ). Дата также может быть в сокращенном формате yyyy-mm-dd (без ‘T’); это формат “full-date” в RFC 3339. В этом формате время считается 00:00:00 UTC для любой обработки.

minJavaVersion (атрибут) : Если присутствует, минимальная версия Java, необходимая для запуска текущей версии.

minVersion (атрибут) : Если присутствует, минимальная версия router’а, необходимая для обновления до текущей версии. Если router старше указанной версии, пользователь должен (вручную?) сначала обновиться до промежуточной версии.

<i2p:version> : Обязательный. Последняя доступная версия router.

<i2p:update> : Файл обновления (один или более). Должен содержать как минимум один дочерний элемент. - type (атрибут): “sud”, “su2”, или “su3”. Должен быть уникальным среди всех элементов <i2p:update>. - <i2p:clearnet>: Прямые ссылки для загрузки из внешней сети (ноль или более). href (атрибут): Стандартная clearnet http-ссылка. - <i2p:clearnetssl>: Прямые ссылки для загрузки из внешней сети (ноль или более). href (атрибут): Стандартная clearnet https-ссылка. - <i2p:torrent>: Magnet-ссылка внутри сети. href (атрибут): Magnet-ссылка. - <i2p:url>: Прямые ссылки для загрузки внутри сети (ноль или более). href (атрибут): Внутрисетевая http-ссылка .i2p.

Подробности отзывов Atom i2p:revocations

Этот элемент является необязательным, и в ленте может быть не более одного элемента <i2p:revocations>. Эта функция поддерживается начиная с версии 0.9.26.

Сущность <i2p:revocations> содержит одну или несколько сущностей <i2p:crl>. Сущность <i2p:crl> содержит следующие атрибуты:

updated (атрибут) : Обязательный. Временная метка для данной записи (соответствующая RFC 4287 раздел 3.3 и RFC 3339 ). Дата также может быть в сокращённом формате yyyy-mm-dd (без ‘T’); это формат “full-date” в RFC 3339. В этом формате время считается 00:00:00 UTC для любой обработки.

id (атрибут) : Обязательный. Уникальный идентификатор для создателя данного CRL.

(содержимое сущности) : Обязательно. Стандартный список отозванных сертификатов (CRL), закодированный в base 64 с переносами строк, начинающийся строкой ‘—–BEGIN X509 CRL—–’ и заканчивающийся строкой ‘—–END X509 CRL—–’. См. RFC 5280 для получения дополнительной информации о CRL.

Детали Atom i2p:blocklist

Этот элемент является необязательным, и в ленте может быть не более одного элемента <i2p:blocklist>. Эта функция запланирована к реализации в выпуске 0.9.28.

Сущность <i2p:blocklist> содержит одну или несколько сущностей <i2p:block> или <i2p:unblock>, сущность “updated” и атрибуты “signer” и “sig”:

signer (атрибут) : Обязательный. Уникальный идентификатор (UTF-8) для публичного ключа, используемого для подписи данного списка блокировки.

sig (атрибут) : Обязательный. Подпись в формате code:b64sig, где code — это номер типа подписи в ASCII, а b64sig — это подпись, закодированная в base 64 (алфавит I2P). См. ниже спецификацию данных для подписи.

<updated> : Обязательно. Временная метка для списка блокировки (соответствующая RFC 4287 раздел 3.3 и RFC 3339 ). Дата также может быть в усеченном формате yyyy-mm-dd (без ‘T’); это формат “full-date” в RFC 3339. В этом формате время считается 00:00:00 UTC для любой обработки.

<i2p:block> : Необязательный, разрешены множественные записи. Одна запись, либо буквальный IPv4 или IPv6 адрес, либо 44-символьный base 64 хеш router (алфавит I2P). IPv6 адреса могут быть в сокращенном формате (содержащем “::”). Поддержка записей с сетевой маской, например x.y.0.0/16, необязательна. Поддержка имен хостов необязательна.

<i2p:unblock> : Необязательный, допускается несколько сущностей. Тот же формат, что и у <i2p:block>.

Спецификация подписи: Для генерации данных, которые должны быть подписаны или верифицированы, объедините следующие данные в кодировке ASCII: Обновленная строка, за которой следует символ новой строки (ASCII 0x0a), затем каждая запись блока в порядке получения с символом новой строки после каждой, затем каждая запись разблокировки в порядке получения с символом новой строки после каждой.

Спецификация файла списка блокировки

TBD, не реализовано, см. предложение 130. Обновления списка блокировки доставляются в файле новостей, см. выше.

Будущая работа

• Механизм обновления router является частью веб-консоли router. В настоящее время не предусмотрено обновление встроенного router без консоли router.

Ссылки

• [CRYPTO-SIG] Криптография - Подписи
• [I2P-SRC] Исходный код I2P
• [PLUGIN] Спецификация плагинов
• [Python] Сырые подписи Python RSA
• [RFC-3339] RFC 3339 - Дата и время
• [RFC-4287] RFC 4287 - Формат синдикации Atom
• [RFC-5280] RFC 5280 - Списки отзыва сертификатов
• [Signature] Тип подписи
• [SigningPublicKey] Тип SigningPublicKey