توسيع I2PControl | Proposals

نظرة عامة

يُقدِّم هذا الاقتراح معلومات جديدة إلى واجهة برمجة تطبيقات i2pcontrol، مما يتيح مرونة أكبر. تشمل هذه المعلومات: إضافة وحذف واسترجاع وتعديل دفاتر العناوين والخدمات المخفية. كما يُقدِّم هذا الاقتراح مزيدًا من المعلومات حول جهاز التوجيه الخاص بك، مثل الأقران (peers) والأخبار (news) وقاعدة البيانات الشبكية (netdb) والمزيد.

الدافع

حالة الاستخدام لهذا الاقتراح هي إنشاء واجهة وحدة تحكم موحدة وبسيطة يمكن مشاركتها عبر كل تنفيذات الراوتر مع مجموعة البروتوكولات القياسية لشبكة i2p. وبشكل أساسي، يتيح هذا الاقتراح تجربة أكثر بديهية وسهولة في الاستخدام للمستخدمين عبر شبكة I2P.

ستسمح هذه المقترح أيضًا بمزيد من المرونة في واجهة برمجة تطبيقات I2P (I2P API) لتمكين التطبيقات من تنفيذ واجهة إدارية لـ I2P وإدارتها. ويكمن السماح لـ i2pcontrol بالوصول إلى مثل هذه المعلومات في تمكين المستخدمين من إنشاء تطبيقات أكثر تقدمًا وتقديم دعم أفضل للإدارة عن بُعد.

التصميم

عندما يتفاعل المستخدمون مع واجهة برمجة تطبيقات i2pcontrol، سيكونون قادرين على الوصول إلى نقاط نهاية جديدة توفر المعلومات المذكورة أعلاه. على سبيل المثال، ستُعرض عبر واجهة برمجة تطبيقات i2pcontrol طرق جديدة هي TunnelManager وAddressBook التي تسمح للمستخدمين بإدخال معلمات لإنشاء النفق وحذفه واسترجاعه وتعديله، وكذلك دفاتر العناوين. بالإضافة إلى ذلك، ستتضمن الطريقة الموجودة مسبقًا RouterInfo معلمات جديدة لعرض معلومات حول الراوتر.

الآثار الأمنية

لا توجد تداعيات أمنية إضافية متوقعة من هذا الاقتراح، لأن المعلومات التي يتم الكشف عنها يمكن الوصول إليها بالفعل من خلال وسائل أخرى. ومع ذلك، من المهم التأكد من وجود آليات مصادقة وتفويض مناسبة للوصول إلى واجهة برمجة تطبيقات i2pcontrol، لمنع الوصول غير المصرح به إلى المعلومات الحساسة أو التحكم في الموجه.

مواصفات واجهة برمجة التطبيقات والأساليب

جميع الطلبات تتبع هيكل JSON-RPC 2.0:

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

الطريقة - معلومات_الراوتر (الدالات المسترجعة)

أدناه توجد المعاملات الجديدة لطريقة RouterInfo وما تُرجعه:

i2p.router.news - يُرجع جميع إدخالات أخبار الموجه. نوع الإرجاع - String
i2p.router.id - يُرجع تجزئة الموجه كسلسلة Base64، أو null. نوع الإرجاع - String
i2p.router.clockskew - يُرجع متوسط انحراف ساعة الند، أو null. نوع الإرجاع - long
i2p.router.info - يُرجع معلومات الموجه (RouterInfo) بعد تسلسلها كسلسلة Base64، أو null. نوع الإرجاع - String
i2p.router.logs - يُرجع رسائل السجل الأخيرة للموجه. نوع الإرجاع - List<String>
i2p.router.logs.clear - يُفرغ ذاكرة تخزين السجل الخاصة بالموجه ويُرجع "success". نوع الإرجاع - String
i2p.router.net.total.received.bytes - تُرجع إجمالي البايتات المستلمة منذ بدء التشغيل. (مُستلهم من i2pd) نوع القيمة المُعادة - long
i2p.router.net.total.sent.bytes - تُرجع إجمالي البايتات المرسلة منذ بدء التشغيل. (مُستلهم من i2pd) نوع القيمة المُعادة - long
i2p.router.net.total.transit.bytes - تُرجع إجمالي البايتات العابرة التي تم توجيهها منذ بدء التشغيل. (مُستلهم من i2pd) نوع القيمة المُعادة - long
i2p.router.net.bw.transit.15s - تُرجع متوسط عرض النطاق الترددي العابر على مدى 15 ثانية (بايت/ثانية). (مُستلهم من i2pd) نوع القيمة المُعادة - long
i2p.router.net.tunnels.shareratio - يُرجع نسبة مشاركة النفق. نوع القيمة المُعادة - double
i2p.router.net.tunnels.participating.info - يُرجع معلومات النفق المشارك. نوع القيمة المُعادة - List<Map<String, Object>>
i2p.router.net.tunnels.i2ptunnel - يُرجع معلومات وحدة تحكم I2PTunnel المُهيأة (إحصائيات سريعة للجميع). نوع القيمة المُعادة - List<Map<String, Object>>
i2p.router.net.tunnels.exploratory.inbound - يُرجع عدد الأنفاق الاستكشافية الواردة. نوع القيمة المُعادة - int
i2p.router.net.tunnels.exploratory.outbound - يُرجع عدد الأنفاق الاستكشافية الصادرة. نوع القيمة المُعادة - int
i2p.router.net.tunnels.exploratory.info.list - يُرجع قائمة معلومات الأنفاق الاستكشافية. نوع القيمة المُعادة - List<Map<String, Object>>
i2p.router.net.tunnels.client.inbound - يُرجع عدد الأنفاق العميلة الواردة. نوع القيمة المُعادة - int
i2p.router.net.tunnels.client.outbound - يُرجع عدد الأنفاق العميلة الصادرة. نوع القيمة المُعادة - int
i2p.router.net.tunnels.client.info.list - يُرجع قائمة معلومات الأنفاق العميلة. نوع القيمة المُعادة - List<Map<String, Object>>
i2p.router.net.status.v6 - يُرجع رمز حالة الشبكة IPv6. (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.net.error - يُرجع رمز خطأ الشبكة IPv4. (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.net.error.v6 - يُرجع رمز خطأ الشبكة IPv6. (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.net.testing - يُرجع ما إذا كانت الشبكة IPv4 في حالة اختبار (0 أو 1). (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.net.testing.v6 - يُرجع ما إذا كانت الشبكة IPv6 في حالة اختبار (0 أو 1). (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.net.tunnels.successrate - يُرجع معدل نجاح إنشاء النفق الأخير (بالمئة). (مُعتمد من i2pd) نوع القيمة المرجعة - double
i2p.router.net.tunnels.totalsuccessrate - يُرجع معدل نجاح إنشاء النفق الكلي منذ بدء التشغيل (بالمئة). (مُعتمد من i2pd) نوع القيمة المرجعة - double
i2p.router.net.tunnels.queue - يُرجع حجم طابور طلبات إنشاء النفق. (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.net.tunnels.tbmqueue - يُرجع حجم طابور رسالة إنشاء النفق (Tunnel Build Message). (مُعتمد من i2pd) نوع القيمة المرجعة - int
i2p.router.netdb.peers - يُرجع قائمة ببصمات الأقران المعروفة. نوع القيمة المرجعة - List<String>
i2p.router.netdb.activepeers.info - يُرجع بيانات RouterInfo بشكل متسلسل للأقران النشطين. نوع القيمة المرجعة - List<String>
i2p.router.netdb.ntcp.limit - يُرجع الحد الأقصى لاتصالات NTCP. نوع القيمة المرجعة - int
i2p.router.netdb.ssu.limit - يُرجع الحد الأقصى لاتصالات SSU. نوع القيمة المرجعة - int
i2p.router.netdb.bannedpeers - يُرجع قائمة الأقران المحظورين مع تفاصيل الحظر. نوع القيمة المرجعة - Map<String, Map<String, Object>>
i2p.router.netdb.activepeers.list - يُرجع بصمات الأقران النشطين. نوع القيمة المرجعة - List<String>
i2p.router.netdb.peers.list - يُرجع بصمات الأقران المعروفة. نوع القيمة المرجعة - List<String>
i2p.router.netdb.peers.info - يُرجع بيانات RouterInfo بشكل متسلسل للأقران المعروفة. نوع القيمة المرجعة - List<String>
i2p.router.netdb.activepeers.stats - يُرجع إحصائيات الأقران النشطين. نوع القيمة المرجعة - List<Map<String, Object>>
i2p.router.addressbook.private.list - يُرجع إدخالات دفتر العناوين الخاصة. نوع الإرجاع - List<Map<String, String>>
i2p.router.addressbook.local.list - يُرجع إدخالات دفتر العناوين المحلية. نوع الإرجاع - List<Map<String, String>>
i2p.router.addressbook.router.list - يُرجع إدخالات دفتر عناوين الراوتر. نوع الإرجاع - List<Map<String, String>>
i2p.router.addressbook.published.list - يُرجع إدخالات دفتر العناوين المنشورة. نوع الإرجاع - List<Map<String, String>>
i2p.router.addressbook.subscriptions - يُرجع مسار ملف الاشتراكات والإدخالات. نوع الإرجاع - Map<String, Object>
i2p.router.addressbook.config - يُرجع مسار تهيئة دفتر العناوين والإدخالات. نوع الإرجاع - Map<String, Object>

مثال:

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

إرجاع:

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

الطريقة - دفتر العناوين (المحددات)

بالنسبة لطريقة 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
}

لتحرير اشتراكات دفتر العناوين:

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 - ملف يحتوي على etags لعناوين 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
}

الطريقة - مدير النفق (1 طريقة جلب معلَمة، والبقية طرق تعيين)

يُستخدم أسلوب 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
}

استرجاع المثال (الوظيفة فقط للحصول على البيانات) يُعيد - Map<String, Object> (معلومات) وString (الحالة):

{
  "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
}

التوافق

يجب الحفاظ على التوافق مع واجهة برمجة تطبيقات i2pcontrol الحالية، حيث يتم إضافة الأساليب والمعطيات الجديدة بطريقة لا تتعارض مع الوظائف الحالية. يجب أن تستمر التطبيقات الحالية التي تستخدم واجهة برمجة تطبيقات i2pcontrol في العمل دون الحاجة إلى أي تعديل، في حين يمكن للتطبيقات الجديدة الاستفادة من المعلومات والقدرات الإضافية التي يوفرها هذا الاقتراح.

التنفيذ

Java I2P

لم يتم تنفيذ هذا الاقتراح بعد في Java I2P، لكن الكود متاح حاليًا في مستودع i2p.plugins.i2pcontrol ضمن طلب الدمج #6 . تم ذلك للسماح باختبار وتطوير الطرق الجديدة دون التأثير على الكود الحالي. وسيتم دمج التحديث لاحقًا في المستودع الرئيسي لمشروع I2P ضمن الدليل i2pcontrol بمجرد أن يصبح الكود جاهزًا للاستخدام الإنتاجي.

i2pd

الطرق والمتغيرات المُشار إليها بـ “(مُعتمدة من i2pd)” مُنفَّذة في i2pd وغير مُعدَّلة في هذا الاقتراح. لن تتطلب امتدادات i2pd أي تعديل كجزء من هذا الاقتراح. الأجزاء غير المُشار إليها في هذا الاقتراح غير مُنفَّذة في i2pd.

go-i2p

يُحفَّز go-i2p على متابعة هذا الاقتراح من أجل تمكين وتحسين تطبيق وحدة تحكم الموجه الخاص به. وسيعتمد هذا الاقتراح وينفذه في المستقبل.

emissary

احتمال اعتماد هذا الاقتراح في إيميساري غير معروف في الوقت الحالي، ولكن من المرجح أن يستفيد إيميساري من هذا الاقتراح بالطرق نفسها التي يستفيد بها غو-آي2بي.

الأداء

لا يتوقع أي تأثير على الأداء.

نظرة عامة

الدافع

التصميم

الآثار الأمنية

مواصفات واجهة برمجة التطبيقات والأساليب

الطريقة - معلومات_الراوتر (الدالات المسترجعة)

الطريقة - دفتر العناوين (المحددات)

الطريقة - مدير النفق (1 طريقة جلب معلَمة، والبقية طرق تعيين)

الطريقة - ClientServicesInfo (مُعتمدة من i2pd)

التوافق

التنفيذ

Java I2P

i2pd

go-i2p

emissary

الأداء

استطلاع المجتمع