i2pcontrol-expansion | Proposals

Обзор ========

Данное предложение добавляет новую информацию в API i2pcontrol, обеспечивая большую гибкость. Эта информация включает: добавление, удаление, получение и изменение записей в адресных книгах и скрытых сервисах. Также в рамках данного предложения предоставляется дополнительная информация о вашем маршрутизаторе, например, о пирах, новостях, netDb и другое.

Мотивация ==========

Причиной данного предложения является обеспечение большей гибкости в API I2P для реализации и управления административным интерфейсом I2P приложениями. Предоставление такой информации через i2pcontrol позволяет пользователям создавать более сложные приложения и обеспечивает лучшую поддержку удалённого управления.

Дизайн ======

Когда пользователи взаимодействуют с API i2pcontrol, они смогут получать доступ к новым конечным точкам, предоставляющим информацию, упомянутую выше. Например, API i2pcontrol предоставит новые методы TunnelManager и AddressBook, которые позволят пользователям вводить параметры для создания, удаления, получения и изменения туннелей и адресных книг. Кроме того, у уже существующего метода RouterInfo появятся новые параметры для предоставления информации о маршрутизаторе.

Последствия для безопасности =====================

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

Спецификация API и методы ===========================

Все запросы следуют структуре JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "method": "MethodName",
  "params": {
    // method-specific parameters
  },
  "id": 1
}

Метод - RouterInfo ——————-

Ниже приведены новые параметры для метода RouterInfo и возвращаемые ими значения:

i2p.router.news - возвращает все записи новостей маршрутизатора.
i2p.router.id - возвращает хэш маршрутизатора в виде строки Base64 или null.
i2p.router.clockskew - возвращает среднее отклонение часов пиров или null.
i2p.router.info - возвращает сериализованный RouterInfo в виде строки Base64 или null.
i2p.router.logs - возвращает недавние сообщения журнала маршрутизатора.
i2p.router.logs.clear - очищает буфер журнала маршрутизатора и возвращает "success".
i2p.router.net.total.received.bytes — возвращает общее количество принятых байтов с момента запуска. (взято из i2pd)
i2p.router.net.total.sent.bytes — возвращает общее количество отправленных байтов с момента запуска. (взято из i2pd)
i2p.router.net.total.transit.bytes — возвращает общее количество транзитных байтов, пересылаемых с момента запуска. (взято из i2pd)
i2p.router.net.bw.transit.15s — возвращает среднюю пропускную способность транзита за 15 секунд (байт/сек). (взято из i2pd)
i2p.router.net.tunnels.shareratio - возвращает коэффициент обмена туннелями.
i2p.router.net.tunnels.participating.info - возвращает информацию об участвующих туннелях.
i2p.router.net.tunnels.i2ptunnel - возвращает информацию о настроенных контроллерах I2PTunnel (краткая статистика по всем).
i2p.router.net.tunnels.exploratory.inbound - возвращает количество исследовательских входящих туннелей.
i2p.router.net.tunnels.exploratory.outbound - возвращает количество исследовательских исходящих туннелей.
i2p.router.net.tunnels.exploratory.info.list - возвращает список информации об исследовательских туннелях.
i2p.router.net.tunnels.client.inbound - возвращает количество клиентских входящих туннелей.
i2p.router.net.tunnels.client.outbound - возвращает количество клиентских исходящих туннелей.
i2p.router.net.tunnels.client.info.list - возвращает список информации о клиентских туннелях.
i2p.router.net.status.v6 - возвращает код состояния IPv6-сети. (заимствовано из i2pd)
i2p.router.net.error - возвращает код ошибки IPv4-сети. (заимствовано из i2pd)
i2p.router.net.error.v6 - возвращает код ошибки IPv6-сети. (заимствовано из i2pd)
i2p.router.net.testing - возвращает, находится ли IPv4-сеть в состоянии тестирования (0 или 1). (заимствовано из i2pd)
i2p.router.net.testing.v6 - возвращает, находится ли IPv6-сеть в состоянии тестирования (0 или 1). (заимствовано из i2pd)
i2p.router.net.tunnels.successrate — возвращает недавний процент успешного создания туннелей (%). (заимствовано из i2pd)
i2p.router.net.tunnels.totalsuccessrate — возвращает общий процент успешного создания туннелей с момента запуска (%). (заимствовано из i2pd)
i2p.router.net.tunnels.queue — возвращает размер очереди запросов на создание туннелей. (заимствовано из i2pd)
i2p.router.net.tunnels.tbmqueue — возвращает размер очереди сообщений создания туннелей (Tunnel Build Message). (заимствовано из i2pd)
i2p.router.netdb.peers - возвращает список известных хешей пиров.
i2p.router.netdb.activepeers.info - возвращает сериализованные данные RouterInfo для активных пиров.
i2p.router.netdb.ntcp.limit - возвращает лимит подключений NTCP.
i2p.router.netdb.ssu.limit - возвращает лимит подключений SSU.
i2p.router.netdb.bannedpeers - возвращает список заблокированных пиров с деталями блокировки.
i2p.router.netdb.activepeers.list - возвращает хеши активных пиров.
i2p.router.netdb.peers.list - возвращает хеши известных пиров.
i2p.router.netdb.peers.info - возвращает сериализованные данные RouterInfo для известных пиров.
i2p.router.netdb.activepeers.stats - возвращает статистику по активным пирам.
i2p.router.addressbook.private.list - возвращает записи из приватной адресной книги.
i2p.router.addressbook.local.list - возвращает записи из локальной адресной книги.
i2p.router.addressbook.router.list - возвращает записи из адресной книги роутера.
i2p.router.addressbook.published.list - возвращает опубликованные записи адресной книги.
i2p.router.addressbook.subscriptions - возвращает путь к файлу подписок и его записи.
i2p.router.addressbook.config - возвращает путь к конфигурационному файлу адресной книги и его записи.

Пример:

{
    "jsonrpc": "2.0",
    "method": "RouterInfo",
    "params": {
        "i2p.router.id": "",
    },
    "id": 1
}

Возврат:

{
    "jsonrpc": "2.0",
    "result": "{ data }",
    "id": 1
}

Метод - AddressBook ——————–

Для метода AddressBook требуется три параметра/аргумента для удаления и добавления записей в адресную книгу:

Type — соответствует типу адресной книги:
- private
- local
- router
- published
Hostname — соответствует имени хоста или доменному имени, связанному с записью в адресной книге.
Destination — соответствует назначению, связанному с записью в адресной книге.
Delete — этот параметр является необязательным и используется для удаления записи из адресной книги. Если параметр не указан, метод добавит новую запись в адресную книгу.

Пример:

{
  "jsonrpc": "2.0",
  "method": "AddressBook",
  "params": {
    "Type": "private",
    "Hostname": "example.i2p",
    "Destination": "exampleDestinationString",
    "Delete": "" <--- this parameter is optional
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "success": true or false,        
  "message": "Deleted/Added (hostname) in (address book type) address book" OR "Failed to delete/add (hostname) to (address book type) address book",
  "id": 1
}

Для редактирования AddressBookSubscriptions:

SetSubscriptions - этот параметр используется для установки подписок для записи в адресной книге. В качестве аргумента он принимает список строк.

Пример:

{
  "jsonrpc": "2.0",
  "method": "AddressBook",
  "params": {
    "SetSubscriptions": ["notbob.i2p", "helloworld.i2p", ...]
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "success": true,
  "message": "Successfully modified: /path/to/subscriptions.txt"
}

Для редактирования AddressBookConfig:

SetConfig — этот параметр используется для установки конфигурации записи в адресной книге.

Принимает в качестве аргумента объект JSON, содержащий параметры конфигурации.

Доступные/распространённые параметры конфигурации:

subscriptions — файл, содержащий список URL-адресов подписок.
update_delay — интервал обновления в часах.
published_addressbook — путь к опубликованной адресной книге.
router_addressbook — путь к адресной книге маршрутизатора.
local_addressbook — путь к локальной адресной книге.
private_addressbook — путь к приватной адресной книге.
proxy_port — порт eepProxy.
proxy_host — имя хоста eepProxy.
should_publish — следует ли обновлять опубликованную адресную книгу.
etags — файл, содержащий etag-идентификаторы URL-адресов подписок.
last_modified — файл, содержащий временные метки последнего изменения URL-адресов подписок.
log — путь к файлу журнала.
theme — тема оформления.

Пример:

{
  "jsonrpc": "2.0",
  "method": "AddressBook",
  "params": {
    "SetConfig": {
      "subscriptions": "subscriptions.txt",
      "update_delay": "12",
      "published_addressbook": "../eepsite/docroot/hosts.txt",
      "router_addressbook": "hosts.txt",
      "local_addressbook": "../userhosts.txt",
      "private_addressbook": "../privatehosts.txt",
      "proxy_port": "4444",
      "proxy_host": "127.0.0.1",
      "should_publish": "true",
      "etags": "etags.txt",
      "last_modified": "last_modified.txt",
      "log": "log.txt",
      "theme": "light"
    }
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Successfully modified: /path/to/config.txt"
  },
  "id": 1
}

Метод - TunnelManager ——–

Метод TunnelManager используется для создания, редактирования, получения, запуска, остановки, перезапуска и удаления контроллеров I2PTunnel.

Обязательные параметры:

Name - имя туннеля. Это идентификатор туннеля.
Action - действие, которое необходимо выполнить:
- create.
- edit
- get
- start
- stop
- restart
- delete

Дополнительные параметры:

All - булево значение, указывает, нужно ли применить действие ко всем туннелям. Допустимо только для действий start, stop и restart.

Поддерживаемые типы туннелей для create:

client
httpclient
ircclient
socks
socksirc
connectclient
streamrclient
server
httpserver
httpbidirserver
ircserver
streamrserver

Общие параметры для создания/редактирования туннелей:

Type - тип туннеля. Обязателен для create.
NewName - необязательное новое имя при редактировании.
Port - локальный порт прослушивания.
TargetHost или Host - целевой хост для серверных туннелей.
TargetPort - целевой порт для серверных туннелей.
TargetDestination или Destination - назначение для клиентских туннелей, которым оно требуется.
StartOnLoad - булево значение, должен ли туннель запускаться при загрузке.
Description - описание туннеля.
ReachableBy - интерфейс/адрес, на котором прослушивает туннель.
Shared - булево значение, должен ли быть клиентский туннель общим.
UseSSL - булево значение, включить SSL, где поддерживается.
TunnelLength - длина туннеля, от 0 до 3.
TunnelVariance - вариативность туннеля, от -2 до 2.
TunnelQuantity - количество туннелей, от 1 до 6.
TunnelBackupQuantity - количество резервных туннелей, от 0 до 3.
SigType - тип ключа подписи.
EncType - тип шифрования.
CustomOptions - пользовательские параметры туннеля.

Параметры клиентского прокси:

ProxyList
UseOutproxyPlugin
ProxyAuth
ProxyUsername
ProxyPassword
OutproxyAuth
OutproxyUsername
OutproxyPassword
OutproxyType
SSLProxies
JumpList

Параметры управления клиентом:

ConnectDelay
Profile
DelayOpen
Reduce
ReduceCount
ReduceTime
Close
CloseTime
NewDest
PersistentClientKey
PrivKeyFile

Параметры фильтрации HTTP-клиента:

AllowUserAgent
AllowReferer
AllowAccept
AllowInternalSSL

Параметры сервера:

WebsiteHostname или SpoofedHost
BlockAccessInProxies
BlockUserAgents
UserAgents
UniqueLocalAddressPerClient
BlockReferers
MultiHoming
AccessOption
AccessList
FilterFilePath
MaxConcurrentConns
ClientPerMinute
ClientPerHour
ClientPerDay
TotalInPerMinute
TotalInPerHour
TotalInPerDay
PostLimit
PostLimitTime
PerClientPeriod
TotalPeriod
TotalBanTime

Параметры LeaseSet:

EncryptLeaseSet - один из:
- disable
- encrypted (aes)
- blinded
- blinded with lookup password
- encrypted (psk)
- encrypted with lookup password (psk)
- encrypted with per-user key (psk)
- encrypted with lookup password and per-user key (psk)
- encrypted with per-user key (dh)
- encrypted with lookup password and per-user key (dh)
OptionalLookup
LeaseSetClientAuths

Пример создания:

{
  "jsonrpc": "2.0",
  "method": "TunnelManager",
  "params": {
    "Name": "example-client",
    "Action": "create",
    "Type": "client",
    "Port": 7656,
    "TargetDestination": "exampleDestinationString",
    "StartOnLoad": false,
    ....
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success - created tunnel example-client" OR "error - { error message }",
    "results": [ {/* information about where persistent keys are stored */} ]
  },
  "id": 1
}

Пример редактирования:

{
  "jsonrpc": "2.0",
  "method": "TunnelManager",
  "params": {
    "Name": "example-client",
    "Action": "edit",
    "NewName": "renamed-client",
    "Port": 7657,
    "TargetDestination": "newDestinationString",
    "StartOnLoad": true
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success - edited tunnel example-client" OR "error - { error message }"
  },
  "id": 1
}

Пример получения:

{
  "jsonrpc": "2.0",
  "method": "TunnelManager",
  "params": {
    "Name": "example-client",
    "Action": "get"
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success - options for example-client" OR "error - { error message }",
    "info": {
      "client": true,
      "status": "running",
      "persistentClientKey": false,
      "offlineKeys": false,
      "targetDestination": "exampleDestinationString",
      "localDestination": "exampleBase64Destination",
      "destination": "exampleBase64Destination",
      "destinationB32": "example.b32.i2p",
      "rawConfig": {
        "name": "example-client",
        "type": "client"
      }
    }
  },
  "id": 1
}

Примеры запуска, остановки, перезапуска и удаления. Они имеют одинаковую структуру, просто с разными параметрами Action:

{
  "jsonrpc": "2.0",
  "method": "TunnelManager",
  "params": {
    "Name": "example-client",
    "Action": "start"
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success - starting tunnel example-client" OR "error - { error message }"
  },
  "id": 1
}

Метод - ClientServicesInfo (адаптировано из i2pd) ————————————————-

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

Поддерживаемые параметры:

I2PTunnel - возвращает отображение настроенных имён туннелей на их адреса, разделённое на подобъекты client и server.
HTTPProxy - возвращает состояние включённости HTTP-прокси и его адрес.
SOCKS - возвращает состояние включённости SOCKS-прокси и его адрес.
SAM - возвращает состояние включённости моста SAM и информацию об активных сессиях.
BOB - возвращает состояние включённости моста BOB. (Устарело в Java I2P; всегда возвращает false.)
I2CP - возвращает состояние включённости сервера I2CP.

Пример:

{
  "jsonrpc": "2.0",
  "method": "ClientServicesInfo",
  "params": {
    "I2PTunnel": "",
    "SAM": ""
  },
  "id": 1
}

Возврат:

{
  "jsonrpc": "2.0",
  "result": {
    "I2PTunnel": {
      "client": {"my-client": {"address": "example.b32.i2p"}},
      "server": {"my-server": {"address": "example.b32.i2p", "port": 8080}}
    },
    "SAM": {
      "enabled": true,
      "sessions": {}
    }
  },
  "id": 1
}

Совместимость =============

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

Реализация ==============

Java I2P ——–

Это предложение еще не реализовано в Java I2P, однако код доступен в репозитории i2p.plugins.i2pcontrol в рамках запроса на слияние #6 . Это сделано для того, чтобы разрешить тестирование и разработку новых методов без влияния на существующий код. После готовности кода к использованию в продакшене он будет включен в основной репозиторий I2P в каталог i2pcontrol.

i2pd —-

Методы и параметры, помеченные как “(заимствовано из i2pd)”, реализованы в i2pd и не изменяются в данном предложении. Расширения i2pd не потребуют модификации в рамках данного предложения. Части, не отмеченные таким образом, в i2pd не реализованы.

go-i2p ——

go-i2p стремится реализовать это предложение, чтобы включить и улучшить своё приложение консоли маршрутизатора. В будущем оно примет и реализует данное предложение.

emissary ——–

Вероятность внедрения в Emissary на данный момент неизвестна, однако Emissary, вероятно, получит выгоду от данного предложения теми же способами, что и go-i2p.

Производительность ===========

Ожидается отсутствие влияния на производительность.

Опрос сообщества