int prefixLength = prefix != null ? prefix.length() : 0;
int suffixLength = suffix != null ? suffix.length() : 0;
StringBuilder sb = new StringBuilder(prefixLength + principal.length() + suffixLength);
if (prefixLength > 0) {
    sb.append(prefix);
}
sb.append(principal);            // <-- inserted verbatim
if (suffixLength > 0) {
    sb.append(suffix);
}
return sb.toString();

يُقسَّم القالب مرة واحدة، عند وقت التهيئة، حول الرمز `{0}`
(`setUserDnTemplate`، الأسطر 181–200)، إلى `prefix` و`suffix`. عند وقت المصادقة
يُدمَج الـ principal بينهما. **لا يُطبَّق أي ترميز في أي نقطة.** لا يوجد
أي مساعد تهريب في أي مكان ضمن `org/apache/shiro/realm/ldap/`.

### 3.2 الثابت الذي افتُرض لكن لم يُفرَض قط

تتعامل الشيفرة المحيطة مع ناتج `getUserDn` باعتباره Distinguished Name جيد التكوين —
إذ يُمرَّر مباشرة إلى `LdapContextFactory.getLdapContext(...)` ومن هناك إلى JNDI كـ
bind DN. وهذا لا يكون سليماً إلا إذا كان الـ principal المُستبدَل *قيمة سمة واحدة*.

لا يمكن لدمج النصوص فرض ذلك. تحجز RFC 2253 (و RFC 4514) الرموز
`,` `+` `"` `\` `<` `>` `;` `=`، و`#` البادئة، والمسافات البيضاء البادئة/اللاحقة كبنية
نحوية داخل الـ DN. وعندما يظهر أي منها في الـ principal فإنها تُقرأ من قِبَل المحلِّل
كبنية، لا كمحتوى. الثابت — *"يشغل الـ principal قيمة RDN واحدة بالضبط"* —
افتُرض من قِبَل كل مستهلك لاحق ولم يفرضه أيٌّ منهم.

### 3.3 تدفق التنفيذ، من نقطة الدخول إلى العيب```
  submitted credentials (username, password)
        │
        ▼
  DefaultLdapRealm.doGetAuthenticationInfo(AuthenticationToken)        [line 292]
        │
        ▼
  DefaultLdapRealm.getLdapPrincipal(AuthenticationToken)               [line 338]
        │   principal instanceof String ?
        │       ├── no  ──► return principal unchanged   ── NOT AFFECTED (e.g. X.509)
        │       └── yes ──┐
        ▼                 │
  DefaultLdapRealm.getUserDn(String)                                   [line 227]
        │   prefix == null && suffix == null ?
        │       ├── yes ──► return principal unchanged   ── NOT AFFECTED ("principal IS the DN")
        │       └── no  ──┐
        ▼                 │
  prefix + principal + suffix          ◄── DEFECT: unencoded concatenation  [line 246]
        │
        ▼
  LdapContextFactory.getLdapContext(userDn, credentials)
        │
        ▼
  JNDI bind against the directory using the constructed DN

هذا هو التحميل الزائد **المُعامَل** `DirContext.search(String, String, Object[], SearchControls)`.
يُمرَّر اسم المستخدم كـ *وسيطة* عامل تصفية، ولا يُدمج أبدًا في سلسلة
عامل التصفية. وفقًا لوثائق JDK 8 `javax.naming.directory.DirContext`، حرفيًا:

> "عند استبدال وسيطة عامل تصفية ذات قيمة نصية بمتغير، يُفسَّر عامل التصفية
> كما لو أن السلسلة أُعطيت مكان المتغير، مع أي أحرف
> ذات دلالة خاصة داخل عوامل التصفية (مثل `'*'`) بعد تهريبها وفقًا
> لقواعد RFC 2254."

يقوم مزوّد JNDI بعملية التهريب. والسجل التاريخي لذلك موجود في إعلان
الحقل نفسه.

**المصدر: `core/src/main/java/org/apache/shiro/realm/ldap/AbstractLdapRealm.java`، الأسطر 88–89**```java
    //SHIRO-115 - prevent potential code injection:
    protected String searchFilter = "(&(objectClass=*)(userPrincipalName={0}))";

    SearchControls searchCtls = new SearchControls();
    searchCtls.setSearchScope(SearchControls.SUBTREE_SCOPE);

    String userPrincipalName = username;
    if (principalSuffix != null && !userPrincipalName.toLowerCase(Locale.ROOT).endsWith(principalSuffix.toLowerCase(Locale.ROOT))) {
        userPrincipalName += principalSuffix;
    }

    Object[] searchArguments = new Object[]{userPrincipalName};

    NamingEnumeration answer = ldapContext.search(searchBase, searchFilter, searchArguments, searchCtls);

يصل اسم المستخدم إلى الدليل باسم `searchArguments[0]`، وليس كنص مُدرج في
`searchFilter`. يتم حل الرمز `{0}` في الفلتر بواسطة مزوّد JNDI، وليس بواسطة
Shiro.

يمرّر `ActiveDirectoryRealm` في السطر 108 اسم المستخدم الخام إلى
`getLdapContext(username, password)`. تصبح تلك القيمة مدخلاً واحداً لبيئة JNDI
`SECURITY_PRINCIPAL`؛ فهي لا تُستبدل في قالب ولا يُبنى منها DN، وبالتالي فهي خارج
آلية هذا العيب.

**تم التحقق منها تجريبياً مقابل خادم دليل حيّ.** لم يُؤخذ تهريب JNDI
على الثقة: بل لوحظ على الشبكة. تم تجهيز خادم LDAP داخل العملية
(`InMemoryDirectoryServer` من UnboundID) بمعترض
`InMemoryOperationInterceptor` يسجّل فلتر كل طلب بحث يستقبله،
وتم إصدار `searchFilter` الافتراضي الخاص بـ Shiro عبر نفس استدعاء JNDI المُعامَل المستخدم
بواسطة `ActiveDirectoryRealm`، مع وسيط مُصمَّم:```
filter template : (&(objectClass=*)(userPrincipalName={0}))
argument passed : *)(uid=jsmith
server received : (&(objectClass=*)(userPrincipalName=\2a\29\28uid=jsmith))

يصل عنصر التحكم إلى الخادم وقد تغيّرت بنيته — أُضيف شرط ثالث واختُصر اختبار `userPrincipalName` إلى محرف بديل. أما الصيغة ذات المعاملات فلا تصل. وهذا يؤكد، بالملاحظة لا بالعقد، أن مسار `searchFilter` غير متأثر.

---

## 4. خطوات إعادة الإنتاج التفصيلية

حتمية، انطلاقًا من نسخة نظيفة. دليل العمل هو جذر المستودع في كل ما يلي.

### 4.1 المتطلبات المسبقة

| المتطلب | القيمة المستخدمة |
|---|---|
| JDK | **8** — يضبط الفرع `jdk.version` على 1.8. أُنتجت النتائج أدناه باستخدام Zulu 1.8.0_432 (arm64). وجّه `JAVA_HOME` إلى تثبيت JDK 8 قبل تشغيل أي أمر في هذا القسم: |
| البناء | Apache Maven، يتطلب الوصول إلى الشبكة (POM الأب `org.apache:apache:38`) |
| الأساس | `origin/1.13.x` |
| الإعداد | `userDnTemplate = uid={0},ou=users,dc=mycompany,dc=com` |
| خادم الدليل | **غير مطلوب للفقرات §4.3-§4.4** — العيب في بناء DN، قبل أي استدعاء شبكي، لذا تحاكي تلك الخطوات `LdapContextFactory`. إضافة إلى ذلك، تعيد §4.5 إنتاج المسار كاملًا مقابل خادم LDAP **حقيقي** عبر HTTP. |

ضبط `JAVA_HOME` على تثبيت JDK 8:```bash
# macOS
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

# Linux (path varies by distribution and vendor)
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

# Windows (cmd)
set JAVA_HOME=C:\Program Files\Zulu\zulu-8

### 4.3 مراقبة العيب مباشرةً

هذا هو المُشغِّل الأدنى، بمعزل عن بناء Shiro. اكتب `Repro.java` في دليل مؤقت:```java
import javax.naming.ldap.LdapName;

public class Repro {
    // reproduces DefaultLdapRealm.getUserDn line-for-line
    static String getUserDn(String prefix, String principal, String suffix) {
        StringBuilder sb = new StringBuilder(prefix.length() + principal.length() + suffix.length());
        sb.append(prefix);
        sb.append(principal);
        sb.append(suffix);
        return sb.toString();
    }

    public static void main(String[] args) throws Exception {
        String prefix = "uid=";
        String suffix = ",ou=users,dc=mycompany,dc=com";

        String benign = getUserDn(prefix, "jsmith", suffix);
        System.out.println("benign : " + benign + "  -> RDNs=" + new LdapName(benign).size());

        String crafted = getUserDn(prefix, "jsmith,ou=admins", suffix);
        System.out.println("crafted: " + crafted + "  -> RDNs=" + new LdapName(crafted).size());
    }
}

المخرجات المرصودة:```
benign : uid=jsmith,ou=users,dc=mycompany,dc=com  -> RDNs=4
crafted: uid=jsmith,ou=admins,ou=users,dc=mycompany,dc=com  -> RDNs=5

يتوقف البناء عند `Apache Shiro :: Core` مع فشل اختبارات الإثبات — راجع §6.1 للحصول على
المخرجات الكاملة المسجلة:```
DefaultLdapRealmTest   Tests run: 16, Failures: 4, Errors: 0, Skipped: 0
JndiLdapRealmTest      Tests run: 16, Failures: 4, Errors: 0, Skipped: 0

#### 4.5.1 البناء المتأثر

**الطلب**```http
POST /login HTTP/1.1
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded

username=jsmith%2Cou%3Dadmins&password=adminpass

**Bind DN الذي استقبله الدليل**```
uid=jsmith,ou=admins,ou=users,dc=mycompany,dc=com

## التثبيت

### المتطلبات الأساسية

- Python 3.8 أو أحدث
- pip (مدير حزم Python)
- Git (اختياري، للتثبيت من المصدر)

### التثبيت عبر pip

```bash
pip install pycryptodome

git clone https://github.com/example/crypto-tool.git
cd crypto-tool
pip install -r requirements.txt

python -c "import Crypto; print(Crypto.__version__)"

from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes

key = get_random_bytes(32)
cipher = AES.new(key, AES.MODE_GCM)
ciphertext, tag = cipher.encrypt_and_digest(b"secret message")

python crypto-tool.py -k 0123456789abcdef0123456789abcdef -i plaintext.txt -o encrypted.bin

python crypto-tool.py -d -k 0123456789abcdef0123456789abcdef -i encrypted.bin -o decrypted.txt

from crypto_tool import Cipher, Hash

cipher = Cipher(algorithm="AES-256-GCM")
encrypted = cipher.encrypt(data, key)
hash_value = Hash.sha256(data)

crypto:
  algorithm: AES-256-GCM
  key_size: 32
  log_level: INFO
``````http
HTTP/1.1 200 OK

تسجيلات الدخول العادية دون تغيير — الصف 1 يُصادق بشكل مطابق على كلا البنيتين، مع استلام الدليل `uid=jsmith,ou=users,dc=mycompany,dc=com`.

استخدم كلا التشغيلين نفس أداة الاختبار ونفس بيانات الاختبار؛ فقط `shiro-core` على مسار الفئات (classpath) اختلف. تم التأكد من الفئة التي حُمِّلت فعلياً باستخدام `-verbose:class` لكل تشغيل.

---

## 5. تفاصيل المعالجة وكود المعالجة

### 5.1 الإصلاح الأساسي

قم بترميز الـ principal كقيمة سمة DN واحدة قبل الاستبدال، باستخدام مُرمِّز RFC 2253 الخاص بـ JDK، وهو `javax.naming.ldap.Rdn.escapeValue`. هذه هي نفس الآلية التي يستخدمها JDK لبناء الأسماء، لذا فإن مخرجاته متوافقة بحكم البناء مع المحلل الذي يستهلكها.

**الملف:** `core/src/main/java/org/apache/shiro/realm/ldap/DefaultLdapRealm.java````diff
@@ -35,6 +35,7 @@ import org.slf4j.LoggerFactory;
 import javax.naming.AuthenticationNotSupportedException;
 import javax.naming.NamingException;
 import javax.naming.ldap.LdapContext;
+import javax.naming.ldap.Rdn;
 
 /**
  * An LDAP {@link org.apache.shiro.realm.Realm Realm} implementation utilizing Sun's/Oracle's
@@ -239,11 +240,14 @@ public class DefaultLdapRealm extends AuthorizingRealm {
 
         int prefixLength = prefix != null ? prefix.length() : 0;
         int suffixLength = suffix != null ? suffix.length() : 0;
-        StringBuilder sb = new StringBuilder(prefixLength + principal.length() + suffixLength);
+        //the principal is a single attribute value within the resulting name, so it is encoded
+        //to keep any characters that are significant in a Distinguished Name within that value:
+        String value = Rdn.escapeValue(principal);
+        StringBuilder sb = new StringBuilder(prefixLength + value.length() + suffixLength);
         if (prefixLength > 0) {
             sb.append(prefix);
         }
-        sb.append(principal);
+        sb.append(value);
         if (suffixLength > 0) {
             sb.append(suffix);
         }

مخرجات الفشل المُلتقطة — هذا هو الدليل، وهو غير قابل للاسترداد بمجرد تطبيق الإصلاح:```
testGetUserDnPreservesTemplateStructure:238
  User DN gained or lost components relative to the template:
  uid=jsmith,ou=admins,ou=users,dc=mycompany,dc=com
  expected:<4> but was:<5>

testGetUserDnPreservesTemplateStructureForReservedCharacters:262
  Component count changed for principal [jsmith,ou=admins]:
  uid=jsmith,ou=admins,ou=users,dc=mycompany,dc=com
  expected:<4> but was:<5>

testGetUserDnEncodesSubstitutedValue:280
  expected:<uid=jsmith[\,ou\]=admins,ou=users,dc=...>
   but was:<uid=jsmith[,ou]=admins,ou=users,dc=...>

testUserDnTemplateSubstitutionPreservesStructure:300
  Unexpected method call
    LdapContextFactory.getLdapContext("uid=jsmith,ou=admins,ou=users,dc=mycompany,dc=com", ...)
  expected:
    LdapContextFactory.getLdapContext("uid=jsmith\,ou\=admins,ou=users,dc=mycompany,dc=com", ...)
    expected: 1, actual: 0

جميع اختبارات الإثبات الأربعة تمر الآن على كلا الصنفين. إعادة تشغيل §4.3 مع الإصلاح المطبق
تُنتج `RDNs=4` للهوية المُصمَّمة.

### 6.3 الاختبارات المُضافة

**الملف:** `core/src/test/java/org/apache/shiro/realm/ldap/DefaultLdapRealmTest.java`
(+124 سطرًا، 0 حذف). لأن `JndiLdapRealmTest extends DefaultLdapRealmTest`، فإن كل
اختبار أدناه يُنفَّذ ضد **كلا** الصنفين — 10 عمليات تنفيذ من 5 دوال.

| الاختبار | ما يتحقق منه | خط الأساس |
|---|---|---|
| `testGetUserDnLeavesOrdinaryPrincipalUnchanged` | هوية عادية تُنتج الـ DN المتوقع بالضبط، 4 RDNs، القيمة سليمة. يحمي من الإفراط في الترميز. | **ناجح** (حارس) |
| `testGetUserDnPreservesTemplateStructure` | بالنسبة لـ `jsmith,ou=admins` لا يزال الـ DN يحتوي على 4 مكونات والهوية تبقى كقيمة سمة واحدة. | فاشل |
| `testGetUserDnPreservesTemplateStructureForReservedCharacters` | الأمر ذاته، عبر جميع الهويات العشر ذات الأحرف المحجوزة؛ كما يفشل الاختبار إذا لم يكن الـ DN اسمًا جيد التكوين. | فاشل |
| `testGetUserDnEncodesSubstitutedValue` | القيمة المُستبدَلة مُرمَّزة بحيث تعود ذهابًا وإيابًا إلى الهوية المُقدَّمة. | فاشل |
| `testUserDnTemplateSubstitutionPreservesStructure` | من البداية إلى النهاية عبر `getAuthenticationInfo`: الـ DN المُسلَّم إلى `LdapContextFactory` يحتفظ ببنية القالب. | فاشل |

**ملاحظة تصميمية.** تُحلِّل التأكيدات البنيوية النتيجة باستخدام `javax.naming.ldap.LdapName`
وتقارن عدد المكونات وقيمة الورقة العائدة ذهابًا وإيابًا، بدلًا من تأكيد سلسلة مُرمَّزة متوقعة.
وبالتالي تتحقق الاختبارات من الخاصية المطلوبة الفعلية ولا تفترض مسبقًا أن `Rdn.escapeValue` هو
التنفيذ — أي مُرمِّز صحيح بديل سيظل ينجح.

الأمر:```bash
mvn -B clean verify

**BUILD SUCCESS — 907 اختبارًا، 0 إخفاقات، 0 أخطاء، 3 متخطاة، عبر المفاعل الكامل.**
كل بوابة نشطة في هذه التشغيلة: اختبارات الوحدة (surefire)، اختبارات التكامل (failsafe)،
تدقيق ترخيص Apache RAT، maven-enforcer، و japicmp.

| البوابة | النتيجة |
|---|---|
| اختبارات الوحدة، المفاعل الكامل | **907 تشغيل، 0 إخفاقات، 0 أخطاء، 3 متخطاة** |
| وحدة `core` وحدها | **321 تشغيل، 0 إخفاقات، 0 أخطاء، 0 متخطاة** |
| اختبارات LDAP (`DefaultLdapRealmTest` + `JndiLdapRealmTest`) | **32 تشغيل، 0 إخفاقات** |
| اختبارات التكامل (failsafe) | شُغّلت عبر المفاعل، لا إخفاقات |
| تدقيق ترخيص Apache RAT | غير معتمد: 0، غير معروف: 0 |
| maven-enforcer | لا انتهاكات |
| japicmp | لم يُبلَّغ عن أي عدم توافق |

التخطيات الثلاث هي `@Ignore`s موجودة مسبقًا في وحدات غير مرتبطة بهذا التغيير؛ `core` — الوحدة الوحيدة التي مُسّت — لا تتخطى شيئًا.

## المراجع

- سجل CVE (MITRE API): `https://cveawg.mitre.org/api/cve/CVE-2026-49268`
- الإعلان الأصلي: `https://lists.apache.org/thread/svszql3od8td7hn6conyj2oq70v53b5s`
- تقارير أمان Apache Shiro: `https://shiro.apache.org/security-reports.html`
- RFC 2253 / RFC 4514 — التمثيل النصي لـ LDAP للأسماء المميزة (Distinguished Names)
- RFC 4515 — التمثيل النصي لمرشح بحث LDAP

## التواصل

مؤلف أبحاث ومعالجة الثغرات الأمنية: Jinwoo Hwang ([https://JinwooHwang.com](https://jinwoohwang.com/))