1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883
|
Network Working Group L. Daigle
Request for Comments: 2967 Thinking Cat Enterprises
Category: Informational R. Hedberg
Catalogix
October 2000
TISDAG - Technical Infrastructure for
Swedish Directory Access Gateways
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Abstract
The strength of the TISDAG (Technical Infrastructure for Swedish
Directory Access Gateways) project's DAG proposal is that it defines
the necessary technical infrastructure to provide a single-access-
point service for information on Swedish Internet users. The
resulting service will provide uniform access for all information --
the same level of access to information (7x24 service), and the same
information made available, irrespective of the service provider
responsible for maintaining that information, their directory service
protocols, or the end-user's client access protocol.
Table of Contents
1.0 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Project Goal. . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Executive Summary of Technical Study Result . . . . . . . . . 5
1.3 Document Overview . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.0 Requirements. . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 End-User Requirements . . . . . . . . . . . . . . . . . . . . 8
2.2 WDSPs Requirements. . . . . . . . . . . . . . . . . . . . . . 8
2.3 DAG-System Requirements . . . . . . . . . . . . . . . . . . . 9
3.0 Functional Specification. . . . . . . . . . . . . . . . . . . 9
3.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 The DAG Core. . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3 Client Interface. . . . . . . . . . . . . . . . . . . . . . . 11
3.3.1 Acceptable User Input . . . . . . . . . . . . . . . . . . . 12
Daigle & Hedberg Informational [Page 1]
RFC 2967 TISDAG October 2000
Supported Query Types. . . . . . . . . . . . . . . . . . . . . 12
Matching Semantics . . . . . . . . . . . . . . . . . . . . . . 12
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3.2 Data Output Spec. . . . . . . . . . . . . . . . . . . . . . 14
Schema Definition. . . . . . . . . . . . . . . . . . . . . . . 14
Referral Definition. . . . . . . . . . . . . . . . . . . . . . 14
Error conditions . . . . . . . . . . . . . . . . . . . . . . . 14
3.4 Directory Server Interface. . . . . . . . . . . . . . . . . . 14
4.0 Architecture. . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1 Software Components . . . . . . . . . . . . . . . . . . . . . 15
4.1.1 Internal Communications . . . . . . . . . . . . . . . . . . 15
4.1.2 Referral Index. . . . . . . . . . . . . . . . . . . . . . . 15
4.1.3 DAG-CAPs. . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1.4 DAG-SAPs. . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 Important Architectural Notes . . . . . . . . . . . . . . . . 17
4.2.1 2 Distinct Functions: Referrals and Chaining . . . . . . . 17
4.2.2 Limited Query and Response Semantics. . . . . . . . . . . . 17
4.2.3 Visibility. . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.4 Richness of Query semantics . . . . . . . . . . . . . . . . 18
4.2.5 N+M Protocol Mappings . . . . . . . . . . . . . . . . . . . 18
4.2.6 DAG-CAPs and DAG-SAPs are completely independent of each
other. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.7 The Role of the DAG-CAP . . . . . . . . . . . . . . . . . . 18
4.2.8 The Role of the DAG-SAP . . . . . . . . . . . . . . . . . . 19
4.2.9 DAG/IP is internal. . . . . . . . . . . . . . . . . . . . . 19
4.2.10 Expectations . . . . . . . . . . . . . . . . . . . . . . . 19
4.2.11 Future Extensions. . . . . . . . . . . . . . . . . . . . . 19
5.0 Software Specifications . . . . . . . . . . . . . . . . . . . 19
5.1 Notational Convention . . . . . . . . . . . . . . . . . . . . 19
5.2 DAG-CAP Basics. . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.1 Functionality . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.3 Error handling. . . . . . . . . . . . . . . . . . . . . . . 21
5.2.4 Pruning of results. . . . . . . . . . . . . . . . . . . . . 22
5.3 DAG-SAP Basics. . . . . . . . . . . . . . . . . . . . . . . . 22
5.3.1 Functionality . . . . . . . . . . . . . . . . . . . . . . . 22
5.3.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . 23
5.3.3 Error handling. . . . . . . . . . . . . . . . . . . . . . . 23
5.3.4 Pruning of results. . . . . . . . . . . . . . . . . . . . . 23
5.3.5 Constraint precedence . . . . . . . . . . . . . . . . . . . 23
5.4 The Referral Index. . . . . . . . . . . . . . . . . . . . . . 24
5.4.1 Architecture. . . . . . . . . . . . . . . . . . . . . . . . 24
5.4.2 Interactions with WDSPs (CIP) . . . . . . . . . . . . . . . 24
5.4.3 Index Object Format . . . . . . . . . . . . . . . . . . . . 24
5.4.4 DAG-Internal I/O. . . . . . . . . . . . . . . . . . . . . . 24
5.4.5 The Index Server. . . . . . . . . . . . . . . . . . . . . . 24
5.4.6 Configuration . . . . . . . . . . . . . . . . . . . . . . . 25
5.4.7 Security. . . . . . . . . . . . . . . . . . . . . . . . . . 25
Daigle & Hedberg Informational [Page 2]
RFC 2967 TISDAG October 2000
5.5 Mail (SMTP) DAG-CAP . . . . . . . . . . . . . . . . . . . . . 25
5.5.1 Mail DAG-CAP Input. . . . . . . . . . . . . . . . . . . . . 26
5.5.2 Translation from Mail query to DAG/IP . . . . . . . . . . . 28
Querying the Referral Index. . . . . . . . . . . . . . . . . . 28
Querying a DAG-SAP . . . . . . . . . . . . . . . . . . . . . . 29
5.5.3 Chaining queries in Mail DAG-CAP. . . . . . . . . . . . . . 31
5.5.4 Expression of results in Mail DAG-CAP . . . . . . . . . . . 31
5.5.5 Expression of Errors in Mail DAG-CAP. . . . . . . . . . . . 31
5.6 Web (HTTP) DAG-CAP. . . . . . . . . . . . . . . . . . . . . . 32
5.6.1 Web DAG-CAP Input . . . . . . . . . . . . . . . . . . . . . 32
5.6.2 Translation from Web query to DAG/IP. . . . . . . . . . . . 33
Querying a DAG-SAP Directly. . . . . . . . . . . . . . . . . . 33
Querying the Referral Index. . . . . . . . . . . . . . . . . . 33
Querying a DAG-SAP . . . . . . . . . . . . . . . . . . . . . . 35
5.6.3 Chaining queries in Web DAG-CAP . . . . . . . . . . . . . . 36
5.6.4 Expression of results in Web DAG-CAP. . . . . . . . . . . . 36
text/html results. . . . . . . . . . . . . . . . . . . . . . . 36
application/whoispp-response Results . . . . . . . . . . . . . 37
5.6.5 Expression of Errors in Web DAG-CAP . . . . . . . . . . . . 37
Standard Errors. . . . . . . . . . . . . . . . . . . . . . . . 38
5.7 Whois++ DAG-CAP . . . . . . . . . . . . . . . . . . . . . . . 38
5.7.1 Whois++ DAG-CAP Input . . . . . . . . . . . . . . . . . . . 38
5.7.2 Translation from Whois++ query to DAG/IP. . . . . . . . . . 39
Querying the Referral Index. . . . . . . . . . . . . . . . . . 39
Querying a DAG-SAP . . . . . . . . . . . . . . . . . . . . . . 39
5.7.3 Chaining in Whois++ DAG-CAP . . . . . . . . . . . . . . . . 40
5.7.4 Expression of results in Whois++. . . . . . . . . . . . . . 41
5.7.5 Expression of Errors in Whois++ DAG-CAP . . . . . . . . . . 41
5.8 LDAPv2 DAG-CAP. . . . . . . . . . . . . . . . . . . . . . . . 42
5.8.1 LDAPv2 DAG-CAP Input. . . . . . . . . . . . . . . . . . . . 42
5.8.2 Translation from LDAPv2 query to DAG/IP . . . . . . . . . . 44
Querying the Referral Index. . . . . . . . . . . . . . . . . . 44
Querying a DAG-SAP . . . . . . . . . . . . . . . . . . . . . . 46
5.8.3 Chaining queries in LDAPv2 DAG-CAP. . . . . . . . . . . . . 48
5.8.4 Expression of results in LDAPv2 . . . . . . . . . . . . . . 48
5.8.5 Expression of Errors in LDAPv2 DAG-CAP. . . . . . . . . . . 48
5.9 LDAPv3 DAG-CAP. . . . . . . . . . . . . . . . . . . . . . . . 50
5.9.1 LDAPv3 DAG-CAP Input. . . . . . . . . . . . . . . . . . . . 50
5.9.2 Translation from LDAPv3 query to DAG/IP . . . . . . . . . . 51
Querying the Referral Index. . . . . . . . . . . . . . . . . . 51
Querying a DAG-SAP . . . . . . . . . . . . . . . . . . . . . . 54
5.9.3 Chaining queries in LDAPv3 DAG-CAP. . . . . . . . . . . . . 55
5.9.4 Expression of results in LDAPv3 . . . . . . . . . . . . . . 55
5.9.5 Expression of Errors in LDAPv3 DAG-CAP. . . . . . . . . . . 56
5.10 Whois++ DAG-SAP. . . . . . . . . . . . . . . . . . . . . . . 57
5.10.1 Input. . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.10.2 Translation from DAG/IP to Whois++ query . . . . . . . . . 58
5.10.3 Translation of Whois++ results to DAG/IP . . . . . . . . . 58
Daigle & Hedberg Informational [Page 3]
RFC 2967 TISDAG October 2000
5.11 LDAPv2 DAG-SAP . . . . . . . . . . . . . . . . . . . . . . . 59
5.11.1 Input. . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.11.2 Translation from DAG/IP to LDAPv2 query. . . . . . . . . . 59
5.11.3 Translation of LDAPv2 results to DAG/IP. . . . . . . . . . 61
5.12 LDAPv3 DAG-SAP . . . . . . . . . . . . . . . . . . . . . . . 62
5.12.1 Input. . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.12.2 Translation from DAG/IP to LDAPv3 query. . . . . . . . . . 62
5.12.3 Translation of LDAPv3 results to DAG/IP. . . . . . . . . . 64
5.13 Example Queries. . . . . . . . . . . . . . . . . . . . . . . 64
5.13.1 A Whois++ Query. . . . . . . . . . . . . . . . . . . . . . 65
What the Whois++ DAG-CAP Receives. . . . . . . . . . . . . . . 65
What the Whois++ DAG-CAP sends to the Referral Index . . . . . 65
What the Whois++ DAG-CAP Sends to an LDAP DAG-SAP. . . . . . . 65
5.13.2 An LDAP Query. . . . . . . . . . . . . . . . . . . . . . . 66
What the LDAP DAG-CAP Receives . . . . . . . . . . . . . . . . 66
5.13.3 What the LDAP DAG-CAP sends to the Referral Index. . . . . 67
What the LDAP DAG-CAP Sends to a Whois++ DAG-SAP . . . . . . . 67
What the LDAP DAG-CAP Sends to an LDAP DAG-SAP . . . . . . . . 68
6.0 Service Specifications. . . . . . . . . . . . . . . . . . . . 68
6.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.2 WDSP Participation. . . . . . . . . . . . . . . . . . . . . . 69
6.3 Load Distribution . . . . . . . . . . . . . . . . . . . . . . 69
6.4 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 72
7.0 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.1 Information credibility . . . . . . . . . . . . . . . . . . . 73
7.2 Unauthorized access . . . . . . . . . . . . . . . . . . . . . 73
8.0 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 74
Appendix A - DAG Schema Definitions . . . . . . . . . . . . . . . 75
A.1 DAG Personal Information Schema (DAGPERSON Schema). . . . . . 76
A.2 DAG Organizational Role Information Schema (DAGORGROLE
Schema). . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix B - Schema Mappings for Whois++ and LDAP . . . . . . . . 77
B.1 LDAP and the DAG Schemas. . . . . . . . . . . . . . . . . . . 78
B.2 Whois++ and the DAG Schemas . . . . . . . . . . . . . . . . . 81
Appendix C - DAG-Internal Protocol (DAG/IP) . . . . . . . . . . . 82
C.1 A word on the choice of DAG/IP. . . . . . . . . . . . . . . . 83
C.2 DAG/IP Input and Output -- Overview . . . . . . . . . . . . . 83
C.3 BNF for DAG/IP input and output . . . . . . . . . . . . . . . 83
C.3.1 The DAG/IP Input Grammar. . . . . . . . . . . . . . . . . . 84
C.3.2 The DAG/IP Response Grammar . . . . . . . . . . . . . . . . 87
C.4 DAG/IP Response Messages. . . . . . . . . . . . . . . . . . . 89
Appendix D - DAG/IP Response Messages Mapping . . . . . . . . . . 93
Appendix E - DAG CIP Usage. . . . . . . . . . . . . . . . . . . . 95
E.1 CIP Index Object. . . . . . . . . . . . . . . . . . . . . . . 95
E.2 CIP Index Object Creation . . . . . . . . . . . . . . . . . . 97
E.3 CIP Index Object Sharing. . . . . . . . . . . . . . . . . . . 98
E.3.1 Registration of Servers . . . . . . . . . . . . . . . . . . 98
E.3.2 Transmission of Objects . . . . . . . . . . . . . . . . . .100
Daigle & Hedberg Informational [Page 4]
RFC 2967 TISDAG October 2000
Appendix F - Summary of Technical Survey Results. . . . . . . . .100
Appendix G - Useful References. . . . . . . . . . . . . . . . . .102
Bibliography. . . . . . . . . . . . . . . . . . . . . . . . . . .102
Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . . .104
Full Copyright Statement. . . . . . . . . . . . . . . . . . . . .105
List of Tables
Table 3.1 DAG-supported queries . . . . . . . . . . . . . . . . .12
Table 5.1 Allowable Whois++ Queries . . . . . . . . . . . . . . .38
Table A.1 DAGPERSON schema attributes . . . . . . . . . . . . . .76
Table A.2 DAGORGROLE schema attributes. . . . . . . . . . . . . .77
Table B.1 Canonical DAGPERSON schema & LDAP inetorgPerson
attributes . . . . . . . . . . . . . . . . . . . . . . . . . .79
Table B.2 Reasonable Approximations for LDAP organizationalRole
attributes . . . . . . . . . . . . . . . . . . . . . . . . . .79
Table B.3 Canonical mappings for LDAP organizationalRole
attributes . . . . . . . . . . . . . . . . . . . . . . . . . .81
Table B.4 Canonical DAGPERSON schema & Whois++ USER attributes. .81
Table B.5 Canonical mappings for Whois++ ORGROLE attributes . . .82
Table C.1 List of system response codes . . . . . . . . . . . . .90
Table D.1 LDAPv2/v3 resultcodes to DAG/IP response codes
mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Table D.2 Mapping from DAG/IP response codes to LDAPv2/v3
resultcodes. . . . . . . . . . . . . . . . . . . . . . . . . .94
Table D.3 Mapping between DAG/IP and Whois++ response codes . . .94
Table F.1 Summary of TISDAG Survey Results: Queries . . . . . . 101
Table F.2 Summary of TISDAG Survey Results: Operational
Information. . . . . . . . . . . . . . . . . . . . . . . . . 101
1.0 Introduction
1.1 Project Goal
The overarching goal of this project is to develop the necessary
technical infrastructure to provide a single-access-point service for
searching for whitepages information on Swedish Internet users. The
service must be uniform for all information -- the same level of
access to information (7x24 service), and the same whitepages
information made available, irrespective of the service provider
responsible for maintaining that information.
1.2 Executive Summary of Technical Study Result
The strength of the TISDAG project's DAG proposal is that it defines
the necessary technical infrastructure to provide a single-access-
point service for information on Swedish Internet users. The
resulting service will provide uniform access for all information --
Daigle & Hedberg Informational [Page 5]
RFC 2967 TISDAG October 2000
the same level of access to information (7x24 service), and the same
information made available, irrespective of the service provider
responsible for maintaining that information, their directory service
protocols, or the end-user's client access protocol.
Instead of requiring centralized mirroring of complete information
records from Swedish directory service providers, the DAG system uses
a well-defined index object summary of that data, updated at the
directory service provider's convenience. When an end-user queries
the DAG, the referral information is used (by the end-user's
software, or by a module within the DAG, as appropriate) to complete
the final query directly at the directory service provider's system.
This ensures that the end-user gets the most up-to-date complete
information, and promotes the directory service provider's main
interest: its service. The architecture of the DAG itself is very
modular; support for future protocols can be added in the operational
system.
1.3 Document Overview
This document is broken into 5 major sections:
Requirements: As a service, the DAG system will have several
different types of users. In order to be successful, those users'
needs (requirements) must be met. This in turn defines certain
constraints, or system requirements, that must be met. This section
aims to capture the baseline requirement assumptions to be addressed
by the system, and thus lays the groundwork on which the rest of the
proposed system is built.
Functional Specification Overview: Working from the users'
requirements, specific technologies and functionality details are
outlined to architect a system that will meet the stated
requirements. This includes a conceptual architecture for the
system. While the Requirements section outlines the needs the
different users have for the eventual DAG system, implementing and
providing the eventual service will entail constraints or conditions
that need to be met in order to be able to participate in the overall
system.
Architecture: Once the system has been defined conceptually, a
proposed software architecture is specified to produce the desired
functionality and meet the stated requirements.
Software Specifications: This section provides the specifications for
software components to meet the architecture described above.
Daigle & Hedberg Informational [Page 6]
RFC 2967 TISDAG October 2000
Service Specifications: Once the software has been designed, the
success of the DAG system will rest on its operational
characteristics. Details of service requirements are given in this
section.
1.4 Terminology
DAG-CAP: Client Access Point -- point of communication between
client-access software and the DAG system.
DAG-System: The Directory Access Gateway system resulting from the
TISDAG project. A collection of infrastructural software and
services for the purpose of providing unified access to Swedish
whitepages information.
DAG/IP: DAG-Internal Protocol -- communication protocol used between
software components of the DAG.
End-User: People performing White Pages searches and look-ups (via
various forms of client software).
DAG-SAP: Service Access Point -- point of communication between the
DAG and WDSP software.
WDSP: Whitepages Directory Service Provider -- ISPs, companies, or
other interested entities.
Whitepages Information: Collected information coordinates for
individual people. This typically includes (but is not limited to) a
person's name, and e-mail address.
2.0 Requirements
There are 2 primary classes of users for the proposed Whitepages
directory access gateway:
- End-users
- WDSPs
As outlined below, needs of each of these user classes imposes a set
of constraints on the design of the DAG system itself. Some of the
requirements shown below are assumed starting criteria for the DAG
service; others have been derived from data collected in the
Technical Survey or other expertise input.
Daigle & Hedberg Informational [Page 7]
RFC 2967 TISDAG October 2000
2.1 End-User Requirements
The End-User is to be provided with a specific set of search types:
Name
Name + Organization
Role + Organization
Name + Locality
Name + Organization + Locality
Role + Organization + Locality
The search results will, if available, include the following
information for each "hit":
- Full name
- E-mail address
- Role
- Organization
- Locality
- Full address
- Telephone numbers
Access to the service must be available through reasonable and
current protocols -- such that directory-service-aware software can
make use of it seamlessly, and there are no reasonable technological
impediments to making this service useful to all Swedish Internet
users.
Following on that, its responses are expected to be timely; a
standard search should not take more time than the average access to
a web-server.
2.2 WDSPs Requirements
Given that the WDSPs that participate in this service are already in
the business of providing a service of whitepages information, they
have certain requirements that must be respected in order to make
this a successful and useful service to all concerned.
The DAG system must provide reasonable assurances of data integrity
for WDSPs; the information the End-User sees should correspond
directly to that provided by the WDSPs. The DAG system should be
non-preferential in providing whitepages information -- the service
is to the End-User, and the source of whitepages information should
not influence the search and information presentation processes.
Daigle & Hedberg Informational [Page 8]
RFC 2967 TISDAG October 2000
The DAG system must be able to reflect information updates within a
reasonable time after receipt from WDSPs; on the flip side, while the
DAG system will function best with regular updates from WDSPs, the
update and participation overhead for WDSPs should be held within
reasonable bounds of what the WDSP should do to support regular
access to its information.
Furthermore, given that WDSPs provide directory service information
with an eye to value-added service, wherever possible End-Users
should be redirected to the WDSP responsible for individual directory
service entries for final and further information.
2.3 DAG-System Requirements
In order to address the requirements of End-Users and WDSPs, the DAG
system itself has certain design constraints that must be taken into
account.
The system must be implementable/operational by Dec 31/98 -- which
implies that it must be designed and constructed with already extant
technologies.
The System will have certain requirements for participation -- e.g.,
7x24 WDSP availability.
In terms of scaling, the system should be able to handle 8M records
at the outset, with a view to handling larger information systems in
the future.
The system must also be capable of extension to other, related
applications (e.g., serving security certificate information).
3.0 Functional Specification
In the TISDAG pilotservice we have decided to apply some limitations
as to what is specified for the DAG/IP. These limitations are
presented in this text in the following manner:
TISDAG: This is a TISDAG comment
3.1 Overview
The conceptual environment of the DAG system can be described in
three major components:
- client access software for end-users
- the DAG system core
- WDSP directory service software
Daigle & Hedberg Informational [Page 9]
RFC 2967 TISDAG October 2000
This is illustrated in Figure 3.1
The DAG (Directory Access Gateway) is the infrastructural core of the
service; it maintains the necessary data and transformation
facilities to permit the smooth connection of diverse directory
service Client Software to the existing WDSPs' directory servers.
The key challenges in designing this portion of the system are:
Quantity of data -- the quantity of whitepages information that will
be made available, and diversity of its sources (different WDSPs)
introduce challenges in terms of finding a structure that will allow
efficient searching, and facilitate the timeliness of updating the
necessary information.
Multiplicity of access protocols -- in order to support the use of
existing whitepages-aware software with a minimum of perturbation,
the DAG system will have to present a uniform face in several
different access protocols, each with its own information search and
representation paradigm.
This specification will outline the following areas:
- the functioning of the DAG core itself
- the interface between the DAG core and End-Users' Directory Service
Access software
- the interface between the DAG core and Directory Services Servers
3.2 The DAG Core
In order to reduce the quantity of data the DAG itself must maintain,
and to keep the maintenance of the whitepages information as close as
possible to the source of information (the WDSPs themselves), the DAG
will only maintain index information and will use "query routing" to
efficiently refer End-User queries to WDSPs for search refinement and
retrieval of information. Although originally developed for the
Whois++ protocol, query routing is being pursued in a protocol-
independent fashion in the IETF's FIND WG, so the choice of this
approach does not limit the selection and support of whitepages
access protocols.
The DAG will look after pursuing queries for access protocols that do
not support referral mechanisms. In order to achieve the support of
multiple access protocols and differing data paradigms, the DAG will
be geared to specifically support a limited set of whitepages
queries.
Daigle & Hedberg Informational [Page 10]
RFC 2967 TISDAG October 2000
+---------+ @
+ ->| | -+-
/|Protocol| | |
/ | / +---------+ / \
/ | "B"
+ | /
| |<-
+-------+ | |
O | | | |
-+- | |<--------->| |
| | | Protocol | |
/ \ | | "A" | |<-
+-------+ | |Protocol
| | \
+ | "A" +---------+ @
\ | \ | | -+-
\ | ->| | |
\| +---------+ / \
+
The
End Client DAG Directory Directory
Users Software System Server Service
Core Software Providers
Figure 3.1 The role of the DAG system
3.3 Client Interface
The DAG will respond to End-User queries in
- e-mail (SMTP)
- WWW (HTTP)
- LDAPv2
- Whois++
- LDAPv3
The DAG will provide responses including the agreed-upon data. For
access protocols that can handle referrals, responses will be data
and/or referrals in that query protocol. These are Whois++ and
LDAPv3. N.B.: the LDAPv3 proposal defines a referral as a URL; no
limitation is placed on the access protocol. However it cannot be
assumed that all clients will be able to handle all access protocols,
so only referrals to LDAPv3 servers will be returned.
Daigle & Hedberg Informational [Page 11]
RFC 2967 TISDAG October 2000
3.3.1 Acceptable User Input
User Input is defined in terms of
- Searchable Attributes
- Matching semantics
- Character sets
These, in conjunction with the DAG schema, defined in Appendix A,
form the basis of the required query expression. Individual queries
are discussed in more detail in the Client Access Point (DAG-CAP)
component descriptions for supported protocols.
Supported Query Types
The DAG system is designed to support fragment-matching queries on a
limited set of data attributes -- "Name", "Organizational Role",
"Organization", and "Locality". The selected permissible query
combinations of attributes are listed in Table 3.1. From the table
it can be seen that not all combinations of the three attributes are
supported -- only those that are needed for the desired
functionality.
Symbol Description
------- -----------
N Name
NL Name + Locality
NO Name + Organization
NOL Name + Organization + Locality
RO Role + Organization
ROL Role + Organization + Locality
Table 3.1 DAG-supported queries
The RO and ROL queries are separated from the rest as they are
searches for "virtual" persons -- roles within an organization (e.g.,
president, or customer service desk) for which one might want to find
contact information.
Matching Semantics
As befits the individual client query protocols, more string matching
expressions may be provided. The basic semantics of the DAG expect
the following to be available in all client access software (as
relevant):
Daigle & Hedberg Informational [Page 12]
RFC 2967 TISDAG October 2000
- Full word, exact match
- Word substring match (E.g., "cat" would match "scatter")
- Case-sensitive and case-insensitive matching
TISDAG: LDAP/X.500, supports case-sensitivity as such but some of
the most used attributes, such as the commonName attribute, are
defined in the standard to be of the case-insensitive
attributetypes. The impact on the DAG system is that even if the
index collected from a LDAP/X.500 server might have upper and
lower case letters in the tokens, they can not be handled as such
since that would be inferring meaning in something which is
natively regarded as meaningless. The conclusion of the above is
that The Referral Index should be case-insensitive and case-
sensitivity should be supported by the SAPs if the native access
protocol supports it.
Character Sets
Wherever possible, the DAG System supports and promotes the use of
Unicode Version 2.0 for character sets (see [21]) specifically the
UTF-8 encoding (see Appendix A.2 of [21] or [20]) Accommodation is
made, where necessary, to support the deployed base of existing
software.
Specifically:
DAG/IP: All internal communications using the DAG/IP are carried out
in UTF-8.
TISDAG: not just UTF-8, but UTF-8 based on composed UNICODE
version 2 character encodings.
DAG-CAP input: Where specific access protocols permit selection of
character sets, DAG-CAPs must support UTF-8. They may additionally
support other anticipated character set encodings.
DAG-SAP communications with WDSPs: Where specific access protocols
permit selection of character sets, DAG-SAPs must support UTF-8 and
use UTF-8 whenever the remote WDSP supports it. They may
additionally support other character set encodings.
CIP Index Objects: The Index Objects supplied by the WDSPs to the DAG
system shall contain data encoded in UTF-8.
TISDAG: The same limitation as for DAG/IP, that is the basic data
should be UTF-8 encoded composed UNICODE version 2 character
encodings.
Daigle & Hedberg Informational [Page 13]
RFC 2967 TISDAG October 2000
3.3.2 Data Output Spec
Schema Definition
The schema used for the DAG service is defined in Appendix A. This
is a very basic information schema, intended to carry the necessary
information for the DAG service, and not more. Although generic
"whitepages" schema definitions do exist the more sophisticated and
detailed the information presentation, the more difficult it is to
map the schema seamlessly across protocols of different paradigms.
Thus, the "KISS" ("Keep it simple, sir") principle seems appropriate
here.
Individual DAG-CAPs define how they express this schema.
Referral Definition
For client access protocols that make use of the concept of
referrals, DAG-CAP definitions will define the expression of
referrals in those protocols. The DAG/IP defines the expression of
referrals (see Appendix C).
Error conditions
Each DAG-CAP may provide more detailed error messages, but will
define minimally the support for the following error conditions:
- unrecognized query
- too many hits
Apart from these errors, the DAG-CAP may choose to refuse a query by
redirecting the end-user to a different DAG-CAP of the same protocol.
3.4 Directory Server Interface
The DAG will use the Common Indexing Protocol (CIP) server-server
protocol to obtain updated index objects from WDSPs. For query-
routing purposes, WDSPs are expected to provide Whois++, LDAPv2 or
LDAPv3 interface to their data (although their preferred access may
be something completely different). N.B.: In the responses from the
technical survey, all respondents currently provide access to their
service in one of these protocols.
In order to provide a useful and uniform service, WDSPs are expected
to provide 7x24 access to their whitepages information. WDSPs are
also expected to implement operations, administration, maintenance,
and provisioning processes designed to minimize service down time for
both planned and unplanned administration and maintenance activities.
Daigle & Hedberg Informational [Page 14]
RFC 2967 TISDAG October 2000
4.0 Architecture
4.1 Software Components
The conceptual architecture of the DAG is represented in Figure 4.1.
General architectural specifications are described below, followed by
individual component specifications Sections 5.5 through 5.12.
4.1.1 Internal Communications
Communications between components of the DAG will be by TCP/IP
connections, using the DAG-Internal Protocol (DAG/IP). DAG/IP is
used by DAG-CAPs to communicate with the Referral Index and DAG-SAPs.
Thus, the DAG/IP defines
- the DAG-CAPs' range of query ability in the Referral Index (to
gather referrals in response to the end-user's requests)
- the responses (and their formats) of the Referral Index to the
DAG-CAP requests
- the DAG-CAPs' range of query ability to the DAG-SAPs for pursuing
referrals when the DAG-CAP needs to do chaining for the client
access software
- the responses (and their formats) of the DAG-SAPs to the DAG-CAPs.
The detail of the planned DAG/IP is given in Appendix C. The detail
of the DAG-CAP--Referral Index and DAG-CAP--DAG-SAP interactions is
given in the definitions of individual DAG-CAPs and DAG-SAPs, below
(Sections 5.5 through 5.12).
4.1.2 Referral Index
The Referral Index is responsible for maintaining the index of WDSP
information, and providing a list of reasonable referrals in response
to DAG-CAP search requests. These "referrals" provide pointers to
identify WDSPs that may have information that matches the end-user's
query.
4.1.3 DAG-CAPs
Individual DAG-CAPs are responsible for providing a particular client
access protocol interface to the DAG service. DAG-CAPs receive end-
user queries in a particular query access protocol, convert the
request into a query for the Referral Index ( i.e., expressed in
DAG/IP), and then convert the Referral Index's response into a form
that is appropriate for the client access protocol. This may mean
passing back the referrals directly, calling on DAG-SAPs to do the
work of translating the referral into results ("chaining"), or a
combination of both.
Daigle & Hedberg Informational [Page 15]
RFC 2967 TISDAG October 2000
+-------------------------------------+
|+====+ |
HTTP <-->+| |<------+ (Full chaining) |
|| | | |
|+====+ | |
| | +----+|
| | Referral-->| ||
| | Result <--| |+<--> Whois++
| | +----+|
|+====+ | |
SMTP <-->+| |<------+ (Full chaining) |
|| | | |
|+====+ | |
| | +----+|
| | Referral-->| ||
| | Result <--| |+<--> LDAPv2
| | +----+|
|+====+ | |
Whois++<-->+| |<------+ (Chain LDAPv2/3) |
|| | | |
|+====+ | |
| | +----+|
| | Referral-->| ||
| | Result <--| |+<--> LDAPv3
| | +----+|
|+====+ | |
LDAPv2 <-->+| |<------+ (Full chaining) |
|| | | |
|+====+ | |
| | |
|+====+ | |
LDAPv3 <-->+| |<------+ (Chain Whois++) |
|| | | |
|+====+ | |
| | |
| v |
| +-----------------------+ |
| | Referral Index |<---------------> Common
| | | | Indexing Protocol
| +-----------------------+ | (CIP)
+-------------------------------------+
All internal communications are in DAG/IP.
Figure 4.1 Conceptual Architecture of the DAG
Daigle & Hedberg Informational [Page 16]
RFC 2967 TISDAG October 2000
4.1.4 DAG-SAPs
Individual DAG-SAPs are called upon (by DAG-CAPs) to take DAG-
generated referrals and pursue them -- issuing the indicated query at
the specified WDSP service. Results from individual WDSPs are
converted back into DAG/IP-specific format for the DAG-CAP that made
the request. Each DAG-SAP is responsible for handling referrals to
WDSPs of a particular protocol (e.g., LDAPv2, Whois++, etc).
4.2 Important Architectural Notes
This section notes some of the thinking that has driven the
architectural and software design specification for the DAG system.
This helps to provide the context in which to understand the software
specifications that follow, and should give clues for the eventual
extension of the DAG system. This section also acts, in some ways,
as an FAQ (Frequently Asked Questions) section, as the content is
shaped by questions received during the tech spec development phase.
It attempts to illuminate context that may not otherwise be apparent
on a first reading of the software specifications.
4.2.1 2 Distinct Functions: Referrals and Chaining
At all times, it must be kept in mind that the primary function of
the DAG system is to provide users with referrals to WDSP services
that may have the information they seek. Since it is the case that
not all supported client protocols can handle referrals, the DAG
system also provides a chaining service to pursue referrals that the
user's client software cannot handle itself. This chaining service
does attempt to match the user's query against data from WDSPs, but
this is to be seen as a secondary, or support function of the DAG
system. In the perfect future, all access protocols will be able to
handle all referrals!
4.2.2 Limited Query and Response Semantics
The DAG system does not attempt to be a chameleon, or the ultimate
whitepages query service. It focuses on providing referrals for
information on the limited number of query types outlined in the
functional specifications of the DAG service. This makes the DAG
system a good place to start a search, but refinements and detailed
inquiries are beyond its scope.
4.2.3 Visibility
Given the limited query syntax of the DAG system it will not always
be possible to exactly match a query posed to a CAP into a query
posed to a SAP. This will have the effect that for instance a LDAPv2
Daigle & Hedberg Informational [Page 17]
RFC 2967 TISDAG October 2000
client that issues a query to the DAG system which by the DAG system
is chained to a LDAP server might not get the same results as if the
client where directly connected to the server in question.
4.2.4 Richness of Query semantics
Even the limited query syntax of the DAG system is capable of
expressing queries that might NOT be possible to represent in the
access protocols to the WDSPs. In these cases the DAG-SAP either can
refuse the query or try to emulate it.
4.2.5 N+M Protocol Mappings
As part of the chaining service offered by the DAG system, a certain
amount of mapping between protocols is required -- in theoretical
terms, there are "N" allowable end-user query access protocols, and
"M" supported WDSP server protocols. The architecture of the
software is constructed to use a single internal protocol (the
DAG/IP) and data schema, providing a common language between all
components. Without this, each input protocol module (DAG-CAP) would
have to be constructed to be able to handle every WDSP protocol --
NxM protocol mappings. This would make the system complex, and
difficult to expand to include new protocols in future.
4.2.6 DAG-CAPs and DAG-SAPs are completely independent of each other
For the above reasons, the DAG-CAP and DAG-SAP modules are intended
to be completely independent of each other. A DAG-SAP responds to a
query that is posed to it in the DAG/IP, without regard to the
protocol of the DAG-CAP that passed the query.
4.2.7 The Role of the DAG-CAP
Thus, the DAG-CAP is responsible for using the DAG/IP to obtain
referral information and, where necessary, chained responses. Where
necessary, it performs adjustments to accommodate the differences in
semantics between the DAG/IP and its native protocol. This might
involved doing post-filtering of the results returned by the DAG-SAPs
since the query issued in DAG/IP to the DAG-SAP might be "broader"
then the original query.
Thus, the DAG-CAP "knows" only 2 protocols: its native protocol, and
the DAG/IP.
Daigle & Hedberg Informational [Page 18]
RFC 2967 TISDAG October 2000
4.2.8 The Role of the DAG-SAP
Similarly, the DAG-SAP is responsible for responding to DAG/IP
queries by contacting the designated WDSP server. Where necessary,
it performs adjustments to accommodate the differences in semantics
between the DAG/IP and its native protocol. These adjustments might
mean that, as a consequence, the DAG-SAP will receive results that do
not match the original query. In such cases the DAG-SAP should
attempt to do post-pruning in order to reduce the mismatch between
the original query and the results returned.
Thus, the DAG-SAP "knows" only 2 protocols: its native protocol, and
the DAG/IP.
4.2.9 DAG/IP is internal
No module outside of the DAG system should be aware of the DAG/IP's
construction. End-users use the query protocols supported by DAG-
CAPs; WDSPs are contacted using the query protocols supported in the
DAG-SAPs.
4.2.10 Expectations
The expectation is that the DAG system, although defined as a single
construct, will operate by running modules on several different,
perhaps widely distributed (in terms of geography and ownership),
computers. For this reason, the DAG/IP specified in such a way that
it will operate on inter-machine communications.
4.2.11 Future Extensions
The DAG system architecture was constructed with a specific view to
extensibility. At any time, an individual component may be improved
(e.g., the Mail DAG-CAP may be given a different query interface)
without disrupting the system.
Additionally, future versions of the DAG system may support other
access protocols -- for end-users, and for WDSPs.
5.0 Software Specifications
5.1 Notational Convention
It is always a challenge to accurately represent text protocol in a
printed document; when is a new line a "newline", and when is it an
effect of the text formatter?
Daigle & Hedberg Informational [Page 19]
RFC 2967 TISDAG October 2000
In order to be adequately illustrated, this document includes many
segments of protocol grammars, sample data, and sample input/output
in a text protocol. In order to distinguish newlines that are
significant in a protocol, the symbol
<NL>
is used. For example,
This is an example of a very long line of input. There is only one
newline in it (at the end), in spite of the fact that this document
shows it spanning several lines of text.<NL>
5.2 DAG-CAP Basics
5.2.1 Functionality
Every DAG-CAP must support the full range of DAG queries, as defined
in 3.3.1.
Each DAG-CAP accepts queries in its native protocol. Individual
DAG-CAP definitions define the expected expression of the DAG queries
in the native protocol.
The DAG-CAP is then responsible for:
- converting that expression into a query in the DAG/IP to obtain
relevant referrals from the Referral Index. This might mean that
parts of the original query are disregarded (e.g., if the query
included attributes not supported by the DAG application, or if the
query algebra was not supported by the DAG application);
- returning referrals in the client's native protocol, where
possible;
- expressing the client query to the necessary DAG-SAPs, given the
limitations mentioned above, to chain those referrals not usefully
expressible in the client's native protocol;
- possibly doing post-filtering on the DAG-SAP results; and
- converting the collected DAG-SAP results for expression in the
client's native protocol (and schema, where applicable).
Each DAG-CAP defines the nature of the interaction with the end-user
(e.g., synchronous or asynchronous, etc). Additionally, each DAG-CAP
must be able to carry out the following, in order to permit load-
limiting and load-balancing in the DAG system:
- direct the client to a different DAG-CAP of the same type (for
load-balancing)
Daigle & Hedberg Informational [Page 20]
RFC 2967 TISDAG October 2000
- decline to return results because too many referrals were generated
(to discourage data-mining). Ideally, this should include the
generation of a message to refine the query in order to produce a
more manageable number of referrals/replies.
DAG-CAPs must be capable of accepting and respecting DAG-SAP service
referrals (for DAG-SAP load-sharing).
In protocols that permit it, the DAG-CAP should indicate to the end-
user which services were unavailable for chaining referrals (i.e., to
indicate there were parts of the search that could not be completed,
and information might be missing).
TISDAG: Any CAP that receives commands other than queries, like
help, answers those on its own. A CAP should not pass any system
command on to the RI.
5.2.2 Configuration
It must be possible to change the expected address of the DAG-CAP by
configuration of the software (i.e., host and port, e-mail address,
etc).
For DAG-CAPs that need to access DAG-SAPs for query chaining, for
each type (protocol) of DAG-SAP that is needed, the DAG-CAP must be
configurable in terms of:
- at least one known DAG-SAP of every necessary protocol to contact
- for each DAG-SAP, the host and port of the DAG-SAP software
The DAG-CAPs must also be configurable in terms of a maximum number
of referrals to handle for a user transaction (i.e., to prevent data
mining, the DAG-CAP will refuse to reply if the query is too general
and too many hits are generated at the Referral Index).
The DAG-CAP must be configurable in terms of alternate DAG-CAPs of
the same type to which the end-user software may be directed if this
one is too busy.
5.2.3 Error handling
Apart from error conditions arising from the operation of the DAG-CAP
itself, DAG-CAPs are responsible for communicating error conditions
occurring elsewhere in the system that affect the outcome of the
user's query (e.g., in the DAG-RI, or in one or more DAG-SAPs).
Daigle & Hedberg Informational [Page 21]
RFC 2967 TISDAG October 2000
If the DAG-CAP sends a query to the DAG-RI and receives an error
message, it should attempt to match the the received DAG errorcode
into its native access protocol's error codes. The same action is
appropriate when the DAG-CAP is "chaining" the query to one DAG-SAP.
There are also occasions when the DAG-CAP may have to combine
multiple errorcodes into a single expression to the user. When the
DAG-CAP is "chaining" the query through DAG-SAPs to one or more
WDSPs, situations can arise when there is a mix of responsecodes from
the DAG-SAPs. If this happens, the DAG-CAP should try to forward
information to the end-user software that is as specific as possible,
for instance which of the WDSPs has not been able to fulfill the
query and why.
See Appendix D for more information concerning error condition
message mappings.
5.2.4 Pruning of results
Since there is no perfect match between the query syntaxes of the DAG
system on one hand and the different access protocols that the DAG-
CAPs and DAG-SAPs supports on the other, there will be situations
where the results a DAG-CAP has to collect is "broader" then what
would have been the case if there had been a perfect match. This
might have adverse effects on the system to the extent that
administrative limits will "unnecessary" be exceeded on WDSPs or that
the collected results exceeds the sizelimit of the DAG-CAP.
Since the DAG-CAP is the only part of the DAG system that actually
knows what the original query was, the DAG-CAP can prune the results
received from the DAG-SAPs in such a way that the results presented
to the client better matches the original question.
5.3 DAG-SAP Basics
5.3.1 Functionality
Every DAG-SAP must support the full range of DAG queries, as defined
in 3.3.1. Results must be complete DAG schemas expressed in well-
formed DAG/IP result formats (see Appendix C). Each DAG-SAP accepts
queries in DAG/IP and converts them to the native schema and protocol
for which it is designed to proxy.
The DAG-SAP is then responsible for
- converting the query into the native schema and protocol of the
WDSP to which the referral points. (If the query is not
representable in the native protocol, it must return an error
Daigle & Hedberg Informational [Page 22]
RFC 2967 TISDAG October 2000
message. If it is emulatable, the DAG-SAP can attempt emulate it
by posing a related query to the WDSP and post-pruning the results
received);
- contacting that WDSP, using the host, port, and protocol
information provided in the referral;
- negotiating the query with the remote WDSP;
- accepting results from the WDSP, possibly doing post-filtering on
the result set; and
- conveying the results back to the calling DAG-CAP using the DAG/IP
and its schema.
Note that this implicitly means that the DAG-SAP is responsible for
chaining and pursuing any referrals it receives from WDSP services.
The DAG-SAP returns only search results to the DAG-CAP that called
it.
5.3.2 Configuration
DAG-SAPs must be configurable to accept connections only from
recognized DAG components.
DAG-SAPs that have service limits must be configurable to redirect
DAG-CAPs to alternate DAG-SAPs of the same type when necessary.
5.3.3 Error handling
A DAG-SAP must translate error codes received from a WDSP server to
DAG error codes according to Appendix D.
5.3.4 Pruning of results
Since it might not be possible to exactly map a DAG query into a
query in the access protocol supported by the a DAG-SAP, the DAG-SAP
should try to translate it into a more general query (or if necessary
into a set of queries). If so, the DAG-SAP must then prune the
result set received before furthering it to the DAG-CAP.
5.3.5 Constraint precedence
Some constraints, search and case, can appear both as local and
global constraints. If this happens in a query then the local
constraint specification overrides the global. For a query like the
following:
fn=leslie;search=exact and org=think:search=substring
the resulting search constraint for "fn=leslie" will be "exact" while
it for "org=think" will be "substring".
Daigle & Hedberg Informational [Page 23]
RFC 2967 TISDAG October 2000
5.4 The Referral Index
5.4.1 Architecture
The Referral Index contains (only) information necessary to deliver
referrals to DAG-CAPs based on the query types supported by the DAG
itself. The Referral Index creates an index over these objects so
that it can respond to DAG-CAP queries using the DAG/IP. The
information is drawn directly from interactions with participating
WDSPs' software, using the Common Indexing Protocol (CIP).
5.4.2 Interactions with WDSPs (CIP)
WDSPs that wish to participate in the DAG system must register
themselves (see Section 5.4.6). Once registered, the Referral Index
will interact with the WDSPs using the Common Indexing Protocol as
defined in [1], using the Index Object defined in Section 5.4.3.
5.4.3 Index Object Format
The CIP index object type is based on the Tagged Index Object as
defined in [12]. Appendix E details the expected content of the
index objects as they are to be provided by the WDSPs.
TISDAG: The tokens in the Tagged Index Object should be UTF-8
encoded composed UNICODE version 2 character encoding.
5.4.4 DAG-Internal I/O
The Referral Index interacts with the rest of the DAG internal
modules (DAG-CAPs) by listening for queries and responding in the
DAG/IP (defined in Appendix C).
5.4.5 The Index Server
The Referral Index must index the necessary attributes of the CIP
index object in order to respond to queries of the form described in
Table 3.1.
The semantics of the chosen CIP object (defined in Appendix E) are
such that a referral to a WDSP server is sent back if (and only if)
- the index object of the WDSP contains all the tokens of the query,
in the attributes specified, according to the logic of the DAG/IP
query, and
- all of those tokens are found with a common tag.
Daigle & Hedberg Informational [Page 24]
RFC 2967 TISDAG October 2000
This means that a query for the name "Fred Flintstone" (2 tokens)
will yield a referral to a server that has a record for "Fred Amadeus
Flintstone", but not to a WDSP with 2 differently tagged records, for
"Fred Amadeus" and "Julie Flintstone". Depending on the access
protocol being used and the original end-user query, the referral to
the WDSP with "Fred Amadeus Flintstone" may yield a successful
result, or it may not. But, it is known that the other WDSP would
not have yielded successful searches. That is, the referral approach
may yield false-positive results, but will not miss appropriate
WDSPs.
5.4.6 Configuration
The Referral Index must provide the ability to register interested
WDSPs, as outlined in Appendix E.
The Referral Index must be able to configure the port for DAG/IP
communications. Also, it must be configurable to recognize only
registered DAG-CAPs.
5.4.7 Security
The Referral Index will accept queries only from recognized
(registered) DAG-CAPs. This will reduce "denial of service" attack
types, but is also a reflection on the fact that the Referral Index
uses the DAG/IP, (i.e., internal) protocol, which should not be
exposed to non-DAG software.
The Referral Index must be able to use authenticated communication to
receive data from WDSPs (see Appendix E).
5.5 Mail (SMTP) DAG-CAP
This is the default Mail DAG-CAP. More sophisticated ones could
certainly be written -- e.g., for pretty-printed output, or for
handling different philosophies of case-matching.
This DAG-CAP has been designed on the assumption that mail queries
will be human-generated (i.e., using a mail program/text editor), as
opposed to being queries formulated by software agents. The input
grammar should therefore be simple and liberal in acceptance of
variations of whitespace formatting.
Daigle & Hedberg Informational [Page 25]
RFC 2967 TISDAG October 2000
5.5.1 Mail DAG-CAP Input
Mail DAG-CAP input is expected to be a regular or MIME-encoded (see
[9] and [10]) SMTP mail message, sent to an advertised mail address.
The mail DAG-CAP parses the message and replies to it with a MIME-
encoded message containing the results of the DAG search.
One query is accepted per e-mail message -- text after a single valid
query has been read is simply ignored.
The body of the query message must follow the syntax defined below.
Note that all input control terms ("type=", "name=" etc) are shown in
lower case for convenience, but could be upper case or mixed case on
input.
mailquery = [mnl] [controls] mnl terms mnl
controls = [msp] "searchtype" [msp] "=" [msp]
( matchtype /
casetype /
matchtype msp casetype /
casetype msp matchtype /
<nothing> )
matchtype = "substring" / "exact"
; default: substring
casetype = "ignore" / "sensitive"
; default: ignore
terms = n / n-l / n-o / n-o-l / r-o / r-o-l
n = n-term
n-l = ( n-term l-term / l-term n-term)
n-o = ( n-term o-term / o-term n-term )
n-o-l = ( n-term o-term l-term /
n-term l-term o-term /
l-term n-term o-term /
l-term o-term n-term /
o-term l-term n-term /
o-term n-term l-term )
r-o = ( r-term o-term / o-term r-term )
r-o-l = ( r-term o-term l-term /
r-term l-term o-term /
l-term o-term r-term /
l-term r-term o-term /
o-term l-term r-term /
o-term r-term l-term )
n-term = [msp] "name" [msp] "=" [msp] string mnl
o-term = [msp] "org" [msp] "=" [msp] string mnl
Daigle & Hedberg Informational [Page 26]
RFC 2967 TISDAG October 2000
l-term = [msp] "loc" [msp] "=" [msp] string mnl
r-term = [msp] "role" [msp] "=" [msp] string mnl
string = <US-ASCII or quoted-printable encoded
ISO-8859-1 or UTF-8 except nl and sp>
msp = 1*(sp)
sp = " "
mnl = 1*(nl)
nl = <linebreak>
The following are valid mail queries:
Example 1:
searchtype = <NL>
name = thinking cat<NL>
Example 2:
searchtype = exact ignore<NL>
name=thinking cat<NL>
Example 3:
role=thinking cat<NL>
org =space colonization<NL>
Example 4:
name=thinking cat <NL>
<NL>
<NL>
My signature line follows here in the most annoying
fashion <NL>
Note that the following are not acceptable queries:
Example 5:
searchtype= exact substring <NL>
name = thinking cat <NL>
Example 6:
name=thinking cat org= freedom fighters anonymous<NL>
Daigle & Hedberg Informational [Page 27]
RFC 2967 TISDAG October 2000
In Example 5, two conflicting searchtypes are given. In Example 6,
no linebreak follows the n-term.
5.5.2 Translation from Mail query to DAG/IP
Querying the Referral Index
A key element of translating from the Mail DAG-CAP input into the
DAG/IP query format is to "tokenize" the input terms into single
token elements for the DAG/IP query. For example, the n-term
name= thinking cat<NL>
is tokenized into 2 n-tokens:
thinking
cat
which are then mapped into the following in the DAG/IP query (dag-n-
terms):
FN=thinking and FN=cat<NL>
The same is true for all r-terms, l-terms and o-terms. The primary
steps in translating the mail input into a DAG/IP query are:
translate quoted-printable encoding, if necessary
translate base64 encoding, if necessary
tokenize the strings for each term
construct the DAG/IP query from the resulting components, as
described in more detail below
DAG/IP constraints are constructed from the searchtype information in
the query.
dag-matchtype = "search=" <matchtype> /
"search=substring" ; if matchtype not
; specified
dag-casetype = "case=ignore" / ; if casetype not
; specified or
; casetype=ignore
"case=consider" ; if casetype=sensitive
constraints = ":" dag-matchtype ";" dag-casetype
The terms for the DAG/IP query are constructed from the tokenized
strings from the mail input.
Daigle & Hedberg Informational [Page 28]
RFC 2967 TISDAG October 2000
dag-n-terms = "FN=" n-token 0*( " and FN=" n-token)
dag-o-terms = "ORG=" o-token 0*( " and ORG=" o-token)
dag-l-terms = "LOC=" l-token 0*( " and LOC=" l-token)
dag-r-terms = "ROLE=" r-token 0*( " and ROLE=" r-token)
This means that the relevant DAG/IP queries are formulated as one of
two types:
dagip-query = ( ( ( n-query / nl-query / no-query /
nol-query ) [" and template=DAGPERSON"]":"
dag-matchtype ";" dag-casetype) /
( ( ro-query / rol-query )
[" and template=DAGORGROLE"]":"
dag-matchtype ";" dag-casetype) )
n-query = dag-n-terms
nl-query = dag-n-terms " and " dag-l-terms
no-query = dag-n-terms " and " dag-o-terms
nol-query = dag-n-terms " and " dag-o-terms " and "
dag-l-terms
ro-query = dag-r-terms " and " dag-o-terms
rol-query = dag-r-terms " and " dag-o-terms " and "
dag-l-terms
The examples given earlier are then translated as follows.
Example 1:
FN=thinking and FN=cat:search=substring;case=ignore<NL>
Example 2:
FN=thinking and FN=cat:search=exact;case=ignore<NL>
Example 3:
ROLE=thinking and ROLE=cat and ORG=space and
ORG=colonization:search=substring;case=ignore<NL>
Querying a DAG-SAP
In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP),
the DAG/IP query must include information about the target WDSP
server. This information is drawn from the Referral Index SERVER-
TO-ASK referral information, and is appended to the query as
specified in Appendix C):
Daigle & Hedberg Informational [Page 29]
RFC 2967 TISDAG October 2000
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
where the response from the Referral Index included:
"# SERVER-TO-ASK " serverhandle nl
" Server-info: " serverinfo nl
" Host-Name: " hostname nl
" Host-Port: " number nl
" Protocol: " prot nl
" Source-URI: " source nl
" Charset: " charset nl
"# END" nl
and the "quoted-hostname" and "quoted-serverinfo" are obtained from
"hostname" and "serverinfo" respectively, by quoting the DAG/IP
special characters.
For example, the referral
# SERVER-TO-ASK dagsystem01<NL>
Server-info: o=thinkingcat, c=se<NL>
Host-Name: thinkingcat.com<NL>
Host-Port: 2839<NL>
Protocol: ldapv2<NL>
Source-URI: http://www.thinkcat.com
Charset: T.61<NL>
# END<NL>
would yield the addition
:host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\
c\=se;charset=T\.61
in its query to an LDAPv2 DAG-SAP.
(N.B.: See Appendix C for further definitions of the terms used in
the SERVER-TO-ASK response).
Note that it is the DAG-SAP's responsibility to extract these terms
from the query and use them to identify the WDSP server to be
contacted. See the individual DAG-SAP definitions, below.
Daigle & Hedberg Informational [Page 30]
RFC 2967 TISDAG October 2000
5.5.3 Chaining queries in Mail DAG-CAP
The Mail DAG-CAP has to chain all referrals -- to the Whois++ DAG-
SAP, LDAPv2 DAG-SAP, or LDAPv3 DAG-SAP as appropriate for the
referral.
5.5.4 Expression of results in Mail DAG-CAP
The results message is sent to the "Reply-To:" address of the
originating mail, if available (see [4] for appropriate
interpretation of mail originator headers). The original query is
repeated, along with the message-id. The remainder of the body of
the mail message is the concatenation of responses from the DAG-SAP
calls, each result having the WDSP's SOURCE URI (from the referral)
appended to it, and the system messages also having been removed.
At the end of the message, the WDSP servers that failed to respond
(i.e., the DAG-SAP handling the referral returned the "% 403
Information Unavailable" message) are listed with their server-info.
5.5.5 Expression of Errors in Mail DAG-CAP
If the mail DAG-CAP receives a message that is not parsable using the
query grammar described above, it returns an explanatory message to
the query mail's reply address saying that the query could not be
interpreted, and giving a description of valid queries.
If the number of referrals sent by the Referral Index is greater than
the pre-determined maximum (for detecting data-mining efforts, or
otherwise refusing over-general queries, such as "FN=svensson"), the
mail DAG-CAP will send an explanatory message to the query mail's
reply address describing the "over-generalized query" problem,
suggesting the user resubmit a more precise query, and describing the
list of valid query types.
If the mail DAG-CAP receives several different result codes from the
DAG-SAPs it should represent those in an appropriate manner in the
response message.
A mail DAG-CAP may redirect a connection to another mail DAG-CAP for
reasons of load-balancing. This is done simply by forwarding the
mail query to the address of the alternate mail DAG-CAP.
Daigle & Hedberg Informational [Page 31]
RFC 2967 TISDAG October 2000
5.6 Web (HTTP) DAG-CAP
5.6.1 Web DAG-CAP Input
The web DAG-CAP provides its interface via standard HTTP protocol.
The general expectation is that the web DAG-CAP will provide a form
page with radio buttons to select "substring or exact match" and
"consider case or ignore case". Other information (about name, role,
organization, locality) is solicited as free-form text.
The DAG-CAP receives queries via an HTTP "post" method (the outcome
of the form action for the page described above, or generated
elsewhere). The rest of this section describes the variables that
are to be expressed in that post. The actual layout of the page and
most user interface issues are left to the discretion of the builder.
Note that the Web DAG-CAP may be called upon to provide responses in
different content encoding, and must therefore address the "Accept-
Encoding:" request header in the HTTP connection.
Although the Web protocol, HTTP, is not itself capable of handling
referrals, through the use of two extra variables this client is
given the option of requesting referral information and then pursuing
individual referrals through the Web DAG-CAP itself, as a proxy for
those referrals. This is handled through the extra "control
variables" to request referrals only, and to indicate when the
transaction is a continuation of a previous query to pursue a
referral.
There has been call to have a "machine-readable" version of the
search output. As HTML is geared towards visual layout, user agents
that intend to do something with the results other than present them
in an HTML browser have few cues to use to extract the relevant
information from the HTML page. Also, "minor" visual changes,
accomplished with extensive HTML updates, can disrupt user agents
that were built to blindly parse the original HTML. Therefore,
provision has been made to return "raw" format results. These are
requested by specifying "Accept-Content: application/whoispp-
response" in the request header of the HTTP message to the HTTP
DAG-CAP.
Daigle & Hedberg Informational [Page 32]
RFC 2967 TISDAG October 2000
The variables that are expected are:
transaction = "new" / "chain" ; default is "new". This
; should not be user-settable. It is used
; in constructed URLs
resulttype = "all" / "referrals" ; default is "all"
matchtype = "substring" / "exact"
casetype = "case ignore" / "case sensitive"
n-term = string
o-term = string
l-term = string
r-term = string
host-term = string
port-term = string
servinfo-term = string
prot-term = string ; the protocol of the referral
string = <UNICODE-2-0-UTF-8> / <UNICODE-1-1-UTF-8> /
<ISO-8859-1>
5.6.2 Translation from Web query to DAG/IP
Querying a DAG-SAP Directly
If the transaction variable is "chain", the information in the POST
is used to pursue a particular referral, not do a search of the
Referral Index. The appropriate DAG-SAP (deduced from the prot-term)
is contacted and issued the query directly.
Results from this type of query are always full results (i.e., not
referrals).
Querying the Referral Index
A key element of translating from the Web DAG-CAP input into the
DAG/IP query format is to "tokenize" the input terms into single
token elements for the DAG/IP query. For example, the n-term
name= thinking cat
is tokenized into 2 n-tokens:
thinking
cat
which are then mapped into the following in the DAG/IP query (dag-n-
terms):
FN=thinking and FN=cat
Daigle & Hedberg Informational [Page 33]
RFC 2967 TISDAG October 2000
The same is true for the r-term, l-term and o-term.
The primary steps in translating the HTTP input into a DAG/IP query
are:
translate encodings, if necessary
tokenize the strings for each term
construct the DAG/IP query from the resulting components, as
described in more detail below
DAG/IP constraints are constructed from the searchtype information in
the query.
dag-matchtype = "search=" <matchtype> /
"search=substring" ; if matchtype not
; specified
dag-casetype = "case=ignore" / ; if casetype not
; specified or
; casetype="case ignore"
"case=consider" ; if casetype=
; "case sensitive"
constraints = ":" dag-matchtype ";" dag-casetype
The terms for the DAG/IP query are constructed from the tokenized
strings from the HTTP post input.
dag-n-terms = "FN=" n-token 0*( " and FN=" n-token)
dag-o-terms = "ORG=" o-token 0*( " and ORG=" o-token)
dag-l-terms = "LOC=" l-token 0*( " and LOC=" l-token)
dag-r-terms = "ROLE=" r-token 0*( " and ROLE=" r-token)
This means that the relevant DAG/IP queries are formulated as one of
two types:
dagip-query = ( ( ( n-query / nl-query / no-query / nol-query )
[" and template=DAGPERSON"]":" dag-matchtype
";" dag-casetype) /
( ( ro-query / rol-query )
[" and template=DAGORGROLE"]":" dag-matchtype
";" dag-casetype) )
n-query = dag-n-terms
Daigle & Hedberg Informational [Page 34]
RFC 2967 TISDAG October 2000
nl-query = dag-n-terms " and " dag-l-terms
no-query = dag-n-terms " and " dag-o-terms
nol-query = dag-n-terms " and " dag-o-terms " and "
dag-l-terms
ro-query = dag-r-terms " and " dag-o-terms
rol-query = dag-r-terms " and " dag-o-terms " and "
dag-l-terms
Querying a DAG-SAP
In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP),
the DAG/IP query must include information about the target WDSP
server. This information is drawn from the Referral Index SERVER-
TO-ASK referral information, and is appended to the query as
specified in Appendix C:
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
where the response from the Referral Index included:
"# SERVER-TO-ASK " serverhandle <NL>
" Server-info: " serverinfo <NL>
" Host-Name: " hostname <NL>
" Host-Port: " number <NL>
" Protocol: " prot <NL>
" Source-URI: " source <NL>
" Charset: " charset <NL>
"# END" <NL>
and the "quoted-hostname" and "quoted-serverinfo" are obtained from
"hostname" and "serverinfo" respectively, by quoting the DAG/IP
special characters.
For example, the referral
# SERVER-TO-ASK dagsystem01<NL>
Server-info: o=thinkingcat, c=se<NL>
Host-Name: thinkingcat.com<NL>
Host-Port: 2839<NL>
Protocol: ldapv2<NL>
Source-URI: http://www.thinkingcat.com
Charset: T.61<NL>
# END<NL>
would yield the addition
Daigle & Hedberg Informational [Page 35]
RFC 2967 TISDAG October 2000
:host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\
c\=se;charset=T\.61
in its query to an LDAPv2 DAG-SAP
(N.B.: See Appendix C for further definitions of the terms used in
the SERVER-TO-ASK response).
Note that it is the DAG-SAP's responsibility to extract these terms
from the query and use them to identify the WDSP server to be
contacted. See the individual DAG-SAP definitions, below.
5.6.3 Chaining queries in Web DAG-CAP
If the resulttype was "all", all of the referrals received from the
Referral Index are chained using the appropriate DAG-SAPs. If only
referrals were requested, the Referral Index results are returned.
5.6.4 Expression of results in Web DAG-CAP
text/html results
The default response encoding is text/html. If the resulttype was
"all", the content of the chaining responses from the DAG-SAPs,
without the system messages, is collated into a single page response,
one result entry per demarcated line ( e.g., bullet item). The FN or
ROLE value should be presented first and clearly. The SOURCE URI for
each WDSP referral should be presented as an HREF for each of the
WDSPs results.
At the end of the message, the WDSP servers that failed to respond
(i.e., the DAG-SAP handling the referral returned the "% 403
Information Unavailable" message) are listed with their server-info.
If, however, the resulttype was "referrals", the results from the
Referral Index are returned as HREF URLs to the Web DAG-CAP itself,
with the necessary information to carry out the query (including the
"HOST=", etc, for the referral).
For example, if the original query:
n-term="thinking cat"
resulttype="referrals"
drew the following referral from the Referral Index:
# SERVER-TO-ASK DAG-Serverhandle<NL>
Server-Info: c=se, o=tce<NL>
Daigle & Hedberg Informational [Page 36]
RFC 2967 TISDAG October 2000
Host-Name: answers.tce.com<NL>
Host-Port: 1111<NL>
Protocol: ldapv3<NL>
Source-URI: http://some.service.se/
Charset: UTF-8<NL>
# END<NL>
the response would be an HTML page with an HREF HTTP "POST" URL to
the Web DAG-CAP with the following variables set:
n-term="thinking cat"
transaction="chain"
servinfo-term="c=se, o=tce"
host-term="answers.tce.com"
port-term="1111"
prot-term="ldapv3"
The Source-URI should be established in the response as its own HREF
URI.
application/whoispp-response Results
If Accept-Encoding: " HTTP request header had the value
"application/whoispp-response", the content of the HTTP response will
be constructed in the same syntax and attribute mapping as for the
Whois++ DAG-CAP.
If the resulttype was "all", all the referrals will have been chained
by the Web DAG-CAP, and the response will include only full data
records.
If the resulttype was "referrals", then all referrals are passed
directly back in a single response, in correct Whois++ referral
format (conveniently, this is how they are formulated in the DAG/IP).
Note that this will include referrals to LDAP-based services as well
as Whois++ servers.
5.6.5 Expression of Errors in Web DAG-CAP
A Web DAG-CAP may redirect a connection to another web DAG-CAP for
reasons of load-balancing. This is done simply by using an HTTP
redirect.
Daigle & Hedberg Informational [Page 37]
RFC 2967 TISDAG October 2000
Standard Errors
If the web DAG-CAP receives a message that is not parsable using the
query grammar described above, it sends an explanatory HTML page
saying that the query could not be interpreted, and giving a
description of valid queries.
If the number of referrals sent by the Referral Index is greater than
the pre-determined maximum (for detecting data-mining efforts, or
otherwise refusing over-general queries, such as "FN=svensson"), the
web DAG-CAP will send a page with an explanatory message describing
the "over-generalized query" problem, suggesting the user resubmit a
more precise query, and describing the list of valid query types.
If the web DAG-CAP receives more than one result code from the DAG-
SAPs, it must represent them all in a appropriate manner in the
response.
application/whoispp-response Errors
An invalid query is responded to with a simple text response with the
error: "% 500 Syntax Error".
If too many referrals are generated from the Referral Index, the
simple text response will have the message "% 503 Query too general".
5.7 Whois++ DAG-CAP
TISDAG: The system commands polled-for/-by should elicit the empty
set as a return value until we better understand the implications
of doing otherwise.
5.7.1 Whois++ DAG-CAP Input
Input to the Whois++ DAG-CAP follows the Whois++ standard ([6]).
Minimally, the Whois++ DAG-CAP must support the following queries:
Query Type Expression in Whois++
----------- ------------------------------------
N One or more "name=" and
template=USER
NL One or more "name=" and
One or more "address-locality=" and template=USER
NO One or more "name=" and
one or more "organization-name=" and template=USER
Daigle & Hedberg Informational [Page 38]
RFC 2967 TISDAG October 2000
NOL One or more "name=" and
one or more "organization-name=" and
one or more "address-locality=" and template=USER
RO One or more "org-role=" and
one or more "organization-name=" and template=ORGROLE
ROL One or more "org-role=" and
one or more "organization-name=" and
one or more "address-locality=" and template=ORGROLE
Table 5.1 Allowable Whois++ Queries
The following constraints must be supported for queries:
"search=" (substring / exact)
"case=" (ignore / consider)
If no constraints are defined in a query the default is exact and
ignore. For example,
FN=foo and loc=kista and fn=bar<NL>
is a perfectly valid Whois++ NL query for "Foo Bar" in "Kista".
5.7.2 Translation from Whois++ query to DAG/IP
Querying the Referral Index
The Whois++ DAG-CAP formulates a DAG/IP query by forwarding the
search terms received (as defined in Table 5.1).
For example, the above query would be expressed as:
FN=foo and LOC=kista and FN=bar and template=DAGPERSON<NL>
Querying a DAG-SAP
In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP),
the DAG/IP query must include information about the target WDSP
server. This information is drawn from the Referral Index SERVER-
TO-ASK referral information, and is appended to the query as
specified in appendix C:
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
Daigle & Hedberg Informational [Page 39]
RFC 2967 TISDAG October 2000
where the response from the Referral Index included:
"# SERVER-TO-ASK " serverhandle<NL>
" Server-info: " serverinfo<NL>
" Host-Name: " hostname<NL>
" Host-Port: " number<NL>
" Protocol: " prot<NL>
" Source-URI: " source<NL>
" Charset: " charset<NL>
"# END"<NL>
and the "quoted-hostname" and "quoted-serverinfo" are obtained from
"hostname" and "serverinfo" respectively, by quoting the DAG/IP
special characters.
For example, the referral
# SERVER-TO-ASK dagsystem01<NL>
Server-info: o=thinkingcat, c=se<NL>
Host-Name: thinkingcat.com<NL>
Host-Port: 2839<NL>
Protocol: ldapv2<NL>
Source-URI: http://www.thinkingcat.com/
Charset: T.61<NL>
# END<NL>
would yield the addition
:host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\
c\=se;charset=T\.61
in its query to an LDAPv2 DAG-SAP.
(N.B.: See Appendix C for further definitions of the terms used in
the SERVER-TO-ASK response).
Note that it is the DAG-SAP's responsibility to extract these terms
from the query and use them to identify the WDSP server to be
contacted. See the individual DAG-SAP definitions, below.
5.7.3 Chaining in Whois++ DAG-CAP
The Whois++ DAG-CAP relies on DAG-SAPs to chain any non-Whois++
referrals (currently, the LDAPv2 and LDAPv3 DAG-SAPs).
Daigle & Hedberg Informational [Page 40]
RFC 2967 TISDAG October 2000
5.7.4 Expression of results in Whois++
Results are expressed in Whois++ by collating the DAG/IP results
received from DAG-SAPs (using the FULL response), and using the
template and attribute mappings defined in Appendix B. For each
result from a given referral, the SOURCE attribute is added, with the
value of the SOURCE-URI from the referral.
Any referrals to other Whois++ servers provided by the Referral Index
are sent directly to the Whois++ client as follows:
server-to-ask = "# SERVER-TO-ASK " DAG-Serverhandle<NL>
" Server-Handle: " SERVER-INFO<NL>
" Host-Name: " HOST<NL>
" Host-Port: " PORT<NL>
" Protocol: " PROTOCOL<NL>
"# END"<NL>
where SERVER-INFO, HOST, PORT, PROTOCOL are drawn from the referral
provided in the DAG/IP, and the SOURCE-URI information is lost.
5.7.5 Expression of Errors in Whois++ DAG-CAP
As appropriate, the Whois++ DAG-CAP will express operational errors
following the Whois++ standard. There are 4 particular error
conditions of the DAG system that the DAG-CAP will handle as
described below.
When the Whois++ DAG-CAP receives a query that it cannot reply to
within the (data) constraints of the DAG, it sends an error message
and closes the connection. The error message includes
% 502 Search expression too complicated<NL>
If the number of referrals sent by the Referral Index is greater than
the pre-determined maximum (for detecting data-mining efforts, or
otherwise refusing over-general queries, such as "FN=svensson"), the
Whois++ DAG-CAP will send an error message and close the connection.
The error message includes
% 503 Query too general<NL>
(N.B.: this is different from the "Too many hits" reply, which does
send partial results.)
Daigle & Hedberg Informational [Page 41]
RFC 2967 TISDAG October 2000
A Whois++ DAG-CAP may redirect a connection to another Whois++ DAG-
CAP for reasons of load-balancing. This is expressed to the end-user
client software using the SERVER-TO-ASK response with appropriate
information to reach the designated alternate DAG-CAP.
If a Whois++ DAG-CAP receives several different response codes from
DAG-SAPs it should try to represent them all in the response to the
end-user client.
The proposed mapping between DAG/IP response codes and Whois++
response codes are given in Appendix D.
5.8 LDAPv2 DAG-CAP
5.8.1 LDAPv2 DAG-CAP Input
Input to the LDAPv2 DAG-CAP follows the LDAPv2 standard ([19]).
Minimally, the LDAPv2 DAG-CAP must support the following queries
(adapted from the ASN.1 grammar of the standard):
BindRequest ::=
[APPLICATION 0] SEQUENCE {
version INTEGER (1 .. 127),
name LDAPDN,
authentication CHOICE {
simple [0] OCTET STRING,
krbv42LDAP [1] OCTET STRING,
krbv42DSA [2] OCTET STRING
}
}
BindResponse ::= [APPLICATION 1] LDAPResult
SearchRequest ::=
[APPLICATION 3] SEQUENCE {
baseObject "dc=se",
scope wholeSubtree (2),
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3)
},
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
attrsOnly BOOLEAN,
filter Filter,
Daigle & Hedberg Informational [Page 42]
RFC 2967 TISDAG October 2000
attributes SEQUENCE OF AttributeType
}
Filter ::=
CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter
}
SubstringFilter ::=
SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
initial [0] LDAPString,
any [1] LDAPString,
final [2] LDAPString
}
}
Queries against attributes in the prescribed LDAP standard schema
(see Appendix B) are accepted.
N.B., this is a minimal set of supported queries, to achieve the
basic DAG-defined queries. An LDAP DAG-CAP may choose to support
more complex queries than this, if it undertakes to do the
translation from the DAG/IP to the LDAPv2 client in a way that
responds to the semantics of those queries.
TISDAG: Since LDAPv2 didn't specify any characterset but relied
on X.500 to do so, in practice several different charactersets are
in use in Sweden today. That the LDAPv2 CAP has no way of knowing
which characterset that are in use by a connecting client is a
problem that the TISDAG project can not solve.
Users of the DAG system will have to configure their specific
client according to information on the TISDAG web page. That page
provides very specific information (including port number) that
can be given to LDAPv2 users. The LDAP DAG-CAP listening on the
default port (389) will be the LDAPv3 one.
Daigle & Hedberg Informational [Page 43]
RFC 2967 TISDAG October 2000
5.8.2 Translation from LDAPv2 query to DAG/IP
Querying the Referral Index
The essential stratagem for mapping LDAP queries into DAG/IP Referral
Index queries is to tokenize the string-oriented LDAP
AttributeValueAssertions or SubstringFilters and construct an
appropriate DAG/IP token-oriented query in the DAG/IP. This will
generalize the LDAP query and yield false-positive referrals, but
should not miss any appropriate referrals.
There are 3 particular cases to be considered:
equalityMatch queries
substring queries
combination equalityMatch and substring queries
TISDAG: If the LDAP filter contains a cn-term and no objectclass
specification it is unclear if the search is for a person or a
role. When this happens the DAG query should cover all bases and
map the query into a query for both people and roles.
EqualityMatch queries can be handled by simply tokenizing the
AttributeValueAssertions, making one DAG/IP query term per token
(using the appropriate DAGSchema attribute) and carrying out an
exact match in the DAG/IP.
Consider the following example, represented in the ASCII
expression of LDAP Filters as described in [13]):
(& (cn=Foo Bar)(objectclass=inetOrgPerson))
This query can be represented in the DAG/IP as
FN="Foo" and FN="Bar":search=exact<NL>
N.B.
The search is set up to be "case=ignore" (the DAG/IP's default)
because the relevant LDAP schema attributes are all derivatives
of the "name" attribute element, which is defined to have a case
insensitive match.
If no objectclass were defined the query in DAG/IP would have
been
(FN="Foo" and FN="bar") or (ROLE="Foo" and ROLE="bar"):search=exact
Daigle & Hedberg Informational [Page 44]
RFC 2967 TISDAG October 2000
inetOrgPerson is used as the objectclass in this and the following
examples, although person or organizationalPerson could also have
been used.
This query will yield false-positive referrals; the original
LDAP query should only match against records for which the "cn"
attribute is exactly the phrase "Foo Bar", whereas the DAG/IP
query will yield referrals any WDSP containing records that
include the two tokens "foo" and "bar" in any order.
For example, this DAG/IP query will yield referrals to WDSPs
with records including:
cn: Bar Foo
cn: Le Bar Foo
cn: Foo Bar AB
LDAP substring queries must also be tokenized in order to construct a
DAG/IP query. The additional point to bear in mind is that LDAP
substring expressions are directed at phrases, which obscure
potential token boundaries. Consequently, all points between
substring components must be considered as potential token
boundaries.
Thus, the LDAP query
(& (cn=black) (o=c*t) (objectclass=inetOrgPerson))
could be expressed as a DAG/IP query with 3 tokens, in a substring
search:
FN=black and ORG=c and ORG=t:search=substring<NL>
This query will yield false-positive results as the tokenized query
does not preserve the order of appearance in the LDAP substring, and
it doesn't preserve phrase-boundaries. That is,
ORG=c and ORG=t:search=substring
will match
tabacco
which is not a match by the LDAP query semantics.
Combined EqualityMatch and Substring queries need special attention.
When an LDAP query includes both EqualityMatch components and
substring filter components, the DAG/IP query to the Referral Index
Daigle & Hedberg Informational [Page 45]
RFC 2967 TISDAG October 2000
can be constructed by following the same mechanisms of tokenization,
but the whole search will become a substring search, as the DAG/IP
defines only search types across the entire query for Referral Index
queries.
Thus,
(& (cn=Foo Bar) (o=c*t) (objectclass=inetOrgPerson))
can be expressed as
FN=Foo and FN=Bar and ORG=c and ORG=t:search=substring<NL>
Alternatively, the LDAP DAG-CAP could conduct two separate queries
and take the intersection (the logical "AND") of the two sets of
referrals returned by the Referral Index.
Note that DAG/IP can accept phrases for searches -- the query
FN=Foo\ bar<NL> (note the escaped space)
is perfectly valid. However, it would match only those things which
have been tokenized in a way that preserves the space, which is the
empty set in the case of the data stored here.
Querying a DAG-SAP
It is never invalid to use the same substantive query to a DAG-SAP as
was used to obtain referral information from the Referral Index.
However, the over-generalization of these queries may yield excessive
numbers of results, and will necessitate some pruning of results in
order to match the returned results against the semantics of the
original LDAP query. It is the LDAP DAG-CAP that is responsible for
this pruning, as it is the recipient of the original query, and
responsible for responding to its semantics.
In concrete terms, when making the DAG/IP query which is to be sent
to a DAG-SAP the above mentioned queries are still valid queries,
but an alternative finer-grained query is also possible, namely:
FN=foo and FN=bar and ORG=c;search=lstring and ORG=t;search=tstring
Particularly in the case of the LDAPv2 DAG-CAP, however, there will
be cause to use LDAP(v2/v3) DAG-SAPs. Since these DAG-SAPs also deal
in phrase-oriented data, a less-over-generalized query can be passed
to them:
FN=Foo\ Bar:search=exact<NL>
Daigle & Hedberg Informational [Page 46]
RFC 2967 TISDAG October 2000
In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP),
the DAG/IP query must include information about the target WDSP
server. This information is drawn from the Referral Index SERVER-
TO-ASK referral information, and is appended to the query as
specified in Appendix C:
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
where the response from the Referral Index included:
"# SERVER-TO-ASK " serverhandle<NL>
" Server-info: " serverinfo<NL>
" Host-Name: " hostname<NL>
" Host-Port: " number<NL>
" Protocol: " prot<NL>
" Source-URI: " source<NL>
" Charset: " charset<NL>
"# END<NL>
and the "quoted-hostname" and "quoted-serverinfo" are obtained from
"hostname" and "serverinfo" respectively, by quoting the DAG/IP
special characters.
For example, the referral
# SERVER-TO-ASK dagsystem01<NL>
Server-info: o=thinkingcat, c=se<NL>
Host-Name: thinkingcat.com<NL>
Host-Port: 2839<NL>
Protocol: ldapv2<NL>
Source-URI: http://www.thinkingcat.com <NL>
Charset: T.61<NL>
# END<NL>
would yield the addition
:host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\
c\=se;charset=T\.61
in its query to an LDAPv2 DAG-SAP.
(N.B.: See Appendix C for further definitions of the terms used in
the SERVER-TO-ASK response).
Note that it is the DAG-SAP's responsibility to extract these terms
from the query and use them to identify the WDSP server to be
contacted. See the individual DAG-SAP definitions, below.
Daigle & Hedberg Informational [Page 47]
RFC 2967 TISDAG October 2000
5.8.3 Chaining queries in LDAPv2 DAG-CAP
The LDAPv2 DAG-CAP relies on DAG-SAPs to resolve every referral.
5.8.4 Expression of results in LDAPv2
As described above, results from DAG-SAPs will have to be post-
processed in cases where the original query was generalized for
expression in DAG/IP.
Acceptable results are expressed in the LDAP search response:
SearchResponse ::=
CHOICE {
entry [APPLICATION 4] SEQUENCE {
objectName LDAPDN,
attributes SEQUENCE OF SEQUENCE
{
AttributeType,
SET OF AttributeValue
}
},
resultCode [APPLICATION 5] LDAPResult
}
where
LDAPDN = DN / "cn=" (FN/ROLE) [",o="ORG] ",dc=se"
attributes = <all attributes mapped from DAG schema, and
"objectClass = inetOrgPerson",
"objectClass = top",
"objectClass = person" or
"objectClass = organizationalRole", as
appropriate, and "labeledURI = <SOURCE-URI>"
for each result from a given referral>
(Where DN,FN,ORG and ROLE are the values from the DAG schema).
I.e., where available, the entry's true DN is used; otherwise (e.g.,
for data coming from Whois++ servers), a reasonable facsimile is
constructed.
5.8.5 Expression of Errors in LDAPv2 DAG-CAP
As appropriate, the LDAPv2 DAG-CAP will express system responses
following the LDAPv2 standard.
Daigle & Hedberg Informational [Page 48]
RFC 2967 TISDAG October 2000
Appendix D gives the proposed mapping between DAG/IP response codes
and LDAPv2 resultcodes.
There are 4 particular error conditions of the DAG system that the
DAG-CAP will handle as described below.
When the LDAPv2 DAG-CAP receives a query that it cannot reply to
within the (data) constraints of the DAG queries, it sends an error
message and closes the connection. The error message includes the
LDAPv2 resultCode:
noSuchAttribute (for incorrect schema attributes)
inappropriateMatching (when a match type other than those
supported is used, e.g. approxMatch)
unwillingToPerform (when the query is not one of the
defined types)
If the number of referrals sent by the Referral Index is greater than
the pre-determined maximum (for detecting data-mining efforts, or
otherwise refusing over-general queries, such as "FN=svensson"), the
LDAPv2 DAG-CAP will send an error message. The error message
includes one of the following resultCodes:
sizeLimitExceeded
timeLimitExceeded
An LDAPv2 DAG-CAP may redirect a connection to another LDAPv2 DAG-CAP
for reasons of load-balancing. This is expressed to the end-user
client software using the "umich referral" convention to direct the
client software to an alternate DAG-CAP by passing the URL in an
error message.
Since a LDAPv2 DAG-CAP only can send one resultcode back to a client;
If a LDAPv2 DAG-CAP receives several different result codes from the
DAG-SAPs it will have to construct a resultmessage that to some
extent represents the combination of those. It is proposed that in
these cases the following actions are taken:
- All the response codes are collected
- Each response code are translated into the corresponding LDAPv2
resultcode.
- A resultcode is chosen to represent the collected response on the
following grounds:
If "success" is the only resultcode represented after these
steps the return that result code.
If apart from "success" there is one other resultcode represented
return that other resultcode.
Daigle & Hedberg Informational [Page 49]
RFC 2967 TISDAG October 2000
If apart from "success" there are two or more resultcodes
represented return the resultcode "other".
5.9 LDAPv3 DAG-CAP
5.9.1 LDAPv3 DAG-CAP Input
Input to the LDAPv3 DAG-CAP follows the LDAPv3 definition (currently
defined in [17]). Minimally, the LDAPv3 DAG-CAP must support the
following queries (adapted from the ASN.1 grammar of the standard):
BindRequest ::= [APPLICATION 0] SEQUENCE {
version INTEGER (1 .. 127),
name LDAPDN,
authentication AuthenticationChoice }
AuthenticationChoice ::= CHOICE {
simple [0] OCTET STRING,
-- 1 and 2 reserved
sasl [3] SaslCredentials }
SaslCredentials ::= SEQUENCE {
mechanism LDAPString,
credentials OCTET STRING OPTIONAL }
BindResponse ::= [APPLICATION 1] SEQUENCE {
COMPONENTS OF LDAPResult,
serverSaslCreds [7] OCTET STRING OPTIONAL }
SearchRequest ::= [APPLICATION 3] SEQUENCE {
baseObject c=se,
scope wholeSubtree (2) },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3) },
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
typesOnly BOOLEAN,
filter Filter,
attributes AttributeDescriptionList }
Daigle & Hedberg Informational [Page 50]
RFC 2967 TISDAG October 2000
Filter ::= CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter }
SubstringFilter ::= SEQUENCE {
type AttributeDescription,
-- at least one must be present
substrings initial [0] LDAPString,
substrings any [1] LDAPString,
substrings final [2] LDAPString}
Queries against attributes in the proscribed LDAP standard schema
(see Appendix B) are accepted.
N.B., this is a minimal set of supported queries, to achieve the
basic DAG-defined queries. An LDAP DAG-CAP may choose to support
more complex queries than this, if it undertakes to do the
translation from the DAG/IP to the LDAPv3 client in a way that
responds to the semantics of those queries.
5.9.2 Translation from LDAPv3 query to DAG/IP
Querying the Referral Index
The essential stratagem for mapping LDAP queries into DAG/IP Referral
Index queries is to tokenize the string-oriented LDAP
AttributeValueAssertions or SubstringFilters and construct an
appropriate DAG/IP token-oriented query in the DAGschema. This will
generalize the LDAP query and yield false-positive referrals, but
should not miss any appropriate referrals.
There are 3 particular cases to be considered:
equalityMatch queries
substring queries
combination equalityMatch and substring queries
TISDAG: If the LDAP filter contains a cn-term and no objectclass
specification it is unclear if the search is for a person or a
role. When this happens the DAG query should cover all bases and
map the query into a query for both people and roles.
Daigle & Hedberg Informational [Page 51]
RFC 2967 TISDAG October 2000
EqualityMatch queries can be handled by simply tokenizing the
AttributeValueAssertions, making one DAG/IP query term per token
(using the appropriate DAGSchema attribute) and carrying out an exact
match in the DAG/IP.
Consider the following example, represented in the ASCII expression
of LDAP Filters as described in [13]):
(& (cn=Foo Bar)(objectclass=person))
This query can be represented in the DAG/IP as
FN="Foo" and FN="Bar":search=exact<NL>
N.B.
The search is set up to be "case=ignore" (the DAG/IP's default)
because the relevant LDAP schema attributes are all derivatives of
the "name" attribute element, which is defined to have a case
insensitive match.
If no objectclass where defined the query in DAG/IP would have been
(FN="Foo" and FN="bar") or ( ROLE="Foo" and ROLE="bar"):search=exact
Although person is used as objectclass in this and the following
examples, inetOrgPerson or organizationalPerson could also have been
used.
This query will yield false-positive referrals; the original LDAP
query should only match against records for which the "cn" attribute
is exactly the phrase "Foo Bar", whereas the DAG/IP query will yield
referrals any WDSP containing records that include the two tokens
"foo" and "bar" in any order.
For example, this DAG/IP query will yield referrals to WDSPs with
records including:
cn: Bar Foo
cn: Le Bar Foo
cn: Foo Bar AB
LDAP substring queries must also be tokenized in order to construct a
DAG/IP query. The additional point to bear in mind is that LDAP
substring expressions are directed at phrases, which obscure
potential token boundaries. Consequently, all points between
substring components must be considered as potential token
boundaries.
Daigle & Hedberg Informational [Page 52]
RFC 2967 TISDAG October 2000
Thus, the LDAP query
(& (cn=black) o=c*t) (objectclass=person))
should be expressed as a DAG/IP query with 3 tokens, in a substring
search:
FN=black and ORG=c and ORG=t:search=substring<NL>
This query will yield false-positive results as the tokenized query
does not preserve the order of appearance in the LDAP substring, and
it doesn't preserve phrase-boundaries. That is,
ORG=c and ORG=t:search=substring
will match
tabacco
which is not a match by the LDAP query semantics.
Combined EqualityMatch and Substring queries need special attention.
When an LDAP query includes both EqualityMatch components and
substring filter components, the DAG/IP query to the Referral Index
can be constructed by following the same mechanisms of tokenization,
but the whole search will become a substring search, as the DAG/IP
defines search types across the entire query.
Thus,
(& (cn=Foo Bar) (o=c*t) (objectclass=person))
can be expressed as
FN=Foo and FN=Bar and ORG=c and ORG=t:search=substring<NL>
Alternatively, the LDAP DAG-CAP could conduct two separate queries
and take the intersection (the logical "AND") of the two sets of
referrals returned by the Referral Index.
Note that DAG/IP can accept phrases for searches -- the query
FN=Foo\ bar<NL> (note the escaped space)
is perfectly valid. However, it would match only those things which
have been tokenized in a way that preserves the space, which is the
empty set in the case of the data stored here.
Daigle & Hedberg Informational [Page 53]
RFC 2967 TISDAG October 2000
Querying a DAG-SAP
It is never invalid to use the same substantive query to a DAG-SAP as
was used to obtain referral information from the Referral Index.
However, the over-generalization of these queries may yield excessive
numbers of results, and will necessitate some pruning of results in
order to match the returned results against the semantics of the
original LDAP query. It is the LDAP DAG-CAP that is responsible for
this pruning, as it is the recipient of the original query, and
responsible for responding to its semantics.
In concrete terms, when making the DAG/IP query which is to be sent
to a DAG-SAP the above mentioned queries are still valid queries,
but an alternative finer-grained query is also possible, namely:
FN=foo and FN=bar and ORG=c;search=lstring and ORG=t;search=tstring
In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP),
the DAG/IP query must include information about the target WDSP
server. This information is drawn from the Referral Index SERVER-
TO-ASK referral information, and is appended to the query as
specified in Appendix C):
"host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
where the response from the Referral Index included:
"# SERVER-TO-ASK " serverhandle <NL>
" Server-info: " serverinfo<NL>
" Host-Name: " hostname<NL>
" Host-Port: " number<NL>
" Protocol: " prot<NL>
" Source-URI: " source<NL>
" Charset: " charset<NL>
"# END"<NL>
and the "quoted-hostname" and "quoted-serverinfo" are obtained from
"hostname" and "serverinfo" respectively, by quoting the DAG/IP
special characters.
For example, the referral
# SERVER-TO-ASK dagsystem01<NL>
Server-info: o=thinkingcat, c=se<NL>
Host-Name: thinkingcat.com<NL>
Host-Port: 2839<NL>
Protocol: ldapv2<NL>
Source-URI:http://www-thinkingcat.se/
Daigle & Hedberg Informational [Page 54]
RFC 2967 TISDAG October 2000
Charset: T.61<NL>
# END<NL>
would yield the addition
:host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\
c\=se;charset=T\.61
in its query to an LDAPv2 DAG-SAP.
(N.B.: See Appendix C for further definitions of the terms used in
the SERVER-TO-ASK response).
Note that it is the DAG-SAP's responsibility to extract these terms
from the query and use them to identify the WDSP server to be
contacted. See the individual DAG-SAP definitions, below.
5.9.3 Chaining queries in LDAPv3 DAG-CAP
The LDAPv3 DAG-CAP relies on DAG-SAPs to resolve all referrals except
those to LDAPv3 servers (i.e., Whois++ referrals, currently).
5.9.4 Expression of results in LDAPv3
As described above, results from DAG-SAPs will have to be post-
processed in cases where the original query was generalized for
expression in DAG/IP. Acceptable results are expressed in LDAPv3
messages containing search result entries (see the standard for more
detail):
SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
objectName LDAPDN,
attributes PartialAttributeList }
PartialAttributeList ::= SEQUENCE OF SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
-- at least one LDAPURL element must be present
SearchResultDone ::= [APPLICATION 5] LDAPResult
where
LDAPDN = DN / "cn=" (FN/ROLE) [",o=" ORG] ",dc=se"
Daigle & Hedberg Informational [Page 55]
RFC 2967 TISDAG October 2000
attributes = <all attributes mapped from the DAG schema, and
"objectClass = inetOrgPerson",
"objectClass = person",
"objectClass = top" or
"objectClass = organizationalRole", as
appropriate, and "labeledURI = <SOURCE-URI>"
for each result from a given referral>
LDAPResult = success
(Where DN, FN, ROLE, and ORG are the values from the DAG schema).
I.e., where available, the entry's true DN is used; otherwise (e.g.,
for data coming from Whois++ servers), a reasonable facsimile is
constructed.
Referral URLs are constructed from the DAG/IP's SERVER-TO-ASK
information as follows:
refurl = "ldap://" HOST [":" PORT] "/" (SERVER-INFO / "dc=se")
The intention is that WDSPs using LDAPv3 servers will provide an
appropriate LDAPDN for their server in the SERVER-INFO. Clients are
then expected to repeat their query at the server designated by this
URL (i.e., the refURL does not include the query).
5.9.5 Expression of Errors in LDAPv3 DAG-CAP
As appropriate, the LDAPv3 DAG-CAP will express operational errors
following the LDAPv3 standard. There are 4 particular error
conditions of the DAG system that the DAG-CAP will handle as
described below.
When the LDAPv3 DAG-CAP receives a query that it cannot reply to
within the (data) constraints of the DAG queries, it sends an error
message and closes the connection. The error message includes the
LDAPv3 resultCode
noSuchAttribute (for incorrect schema attributes chosen)
inappropriateMatching (when a match type other than those
supported is used e.g., approxMatch)
unwillingToPerform (when the query is not one of the defined
types)
If the number of referrals sent by the Referral Index is greater than
the pre-determined maximum (for detecting data-mining efforts, or
otherwise refusing over-general queries, such as "FN=svensson"), the
LDAPv3 DAG-CAP will send an error message. The error message
includes the following resultCode:
Daigle & Hedberg Informational [Page 56]
RFC 2967 TISDAG October 2000
adminLimitExceeded
An LDAPv3 DAG-CAP may redirect a connection to another LDAPv3 DAG-CAP
for reasons of load-balancing. In this case, the LDAPv3 DAG-CAP
sends a result message including only
SearchResultReference ::= [APPLICATION 19] AltURL
SearchResultDone ::= referral
where
AltURL = "ldap://" <althostport> ":" <altbase>
Since a LDAPv3 DAG-CAP only can send one resultcode back to a client;
If a LDAPv3 DAG-CAP receives several different result codes from the
DAG-SAPs it will have to construct a resultmessage that to some
extent represents the combination of those. It is proposed that in
these cases the following actions are taken:
- All the response codes are collected
- Each response code are translated into the corresponding LDAPv3
resultcode.
- A resultcode is chosen to represent the collected response on the
following grounds:
If "success" is the only resultcode represented after these steps
the return that result code.
If apart from "success" there is one other resultcode represented
return that other resultcode.
If apart from "success" there are two or more resultcodes
represented return the resultcode "other".
5.10 Whois++ DAG-SAP
5.10.1 Input
The Whois++ DAG-SAP expects valid DAG/IP communications. Queries
must include referral information (see below) and search terms that
conform to the DAG-allowed query types (e.g., not searches for
organization alone, etc).
The referral information is added to the end of the DAG-SAP query, as
defined in the DAG-CAP definition sections:
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
Daigle & Hedberg Informational [Page 57]
RFC 2967 TISDAG October 2000
5.10.2 Translation from DAG/IP to Whois++ query
The HOST and PORT information are used to make a TCP/IP-based
connection to the remote (presumed) Whois++ server. The query
expressed to the remote Whois++ server is the remainder of the DAG/IP
query the Whois++ DAG-SAP received, with the following template ID
translations:
template=DAGPERSON becomes template=USER
and
template=DAGROLE becomes template=ORGROLE
Additional mappings for attributes are defined in Appendix B.
Note that the search types used in the DAG/IP are not all required by
the Whois++ syntax. Therefore, some Whois++ WDSPs may be using
servers that do not support searches other than "exact" and "lstring"
(the search types required by the Whois++ protocol standard). The
Whois++ DAG-CAP may
- send the DAG/IP query as constructed (e.g., with
"search=substring"), and pass back the "% 502 Search expression too
complicated" from the WDSP's server,
- translate the DAG/IP query into a construct using only these
search types (which will yield incomplete results, as not all
queries are expressible with those search types),
- attempt to ascertain what search types are supported by the
remote server and reformulate using them (e.g., regular
expressions). This would work, but would entail an excessively
complicated Whois++ DAG-SAP, and might not yield any better results
if the remote server doesn't support any optional search types.
5.10.3 Translation of Whois++ results to DAG/IP
Any referrals that the remote WDSP server returns are pursued,
following the usual Whois++ (client) fashion, by the Whois++ DAG-SAP.
If it is not possible to establish a Whois++ session with the remote
server, or if the session is interrupted, before results are
received, the DAG-SAP will itself return no results and an error
message, including
% 403 Information Unavailable<NL>
Daigle & Hedberg Informational [Page 58]
RFC 2967 TISDAG October 2000
If the remote server issues any other Whois++ error message and does
not yield any results, the remote server's error message will be
included in the DAG-SAP's own error message; no results will be
returned.
If results are successfully received from the remote server, they
will be expressed using the DAG/IP -- essentially passing through
all FULL response information received from the remote server, mapped
into the DAGSchema using the mappings defined in Appendix A.
5.11 LDAPv2 DAG-SAP
5.11.1 Input
The LDAPv2 DAG-SAP expects valid DAG/IP communications. Queries must
include referral information (see below) and search terms that
conform to the DAG-allowed query types (e.g., not searches for
organization alone, etc).
The referral information is added to the end of the DAG-SAP query, as
defined in the DAG-CAP definition sections (as additional terms in
the DAG/IP query):
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
5.11.2 Translation from DAG/IP to LDAPv2 query
The HOST and PORT information are used to make a TCP/IP-based
connection to the remote (presumed) LDAPv2 server. The DAG-SAP will
establish a connection with the remote server, following standard
LDAPv2 message exchanges.
The search request itself will be constructed from the DAG/IP query
(without the HOST, SERVER-INFO and PORT terms) as follows:
SearchRequest ::=
[APPLICATION 3] SEQUENCE {
baseObject LDAPDN, -- from the DAG/IP query
scope baseObject (0) },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3)
},
sizeLimit INTEGER (0 .. maxInt),
Daigle & Hedberg Informational [Page 59]
RFC 2967 TISDAG October 2000
timeLimit INTEGER (0 .. maxInt),
attrsOnly FALSE
filter Filter,
attributes SEQUENCE OF AttributeType
-- all DAGschema attributes
equivalents in the defined
standard LDAP schema
}
Filter ::=
CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
substrings [4] SubstringFilter,
}
SubstringFilter
SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
substrings initial [0] LDAPString,
substrings any [1] LDAPString,
substrings final [2] LDAPString}
}
where and, or and not filters are constructed to preserve the logic
of the DAG/IP query.
For the purposes of matching token-based DAG/IP queries to reasonable
LDAP queries, all searches should be passed to the LDAP WDSP as
substring searches. The WDSP results must then be pruned to respect
token boundaries, where necessary.
So, for example, the DAG/IP query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=substring<NL>
would be sent to the designated LDAP WDSP as
(& (fn=*Foo Bar*) (o=*Thinking Cat*) (objectclass=person))
Interestingly, the query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=exact<NL>
would also be sent to the designated LDAP WDSP as
Daigle & Hedberg Informational [Page 60]
RFC 2967 TISDAG October 2000
(& (fn=*Foo Bar*) (o=*Thinking Cat*) (objectclass=person))
but the WDSPs returned results would have to be pruned to remove any
results that had non-tokenizing characters on either side of "Foo
Bar" and "Thinking Cat".
The final consideration for mapping DAG/IP queries into LDAP queries
is the issue of character case. In LDAP, individual attribute
syntaxes define the consideration of case. All of the attributes
used here are case-insensitive in their definitions. Therefore, all
LDAP WDSP queries are inherently case-insensitive; if the DAG/IP
query calls for a case-sensitive match, the LDAP DAG-SAP will have to
do pruning of the results from the DAG-SAP.
5.11.3 Translation of LDAPv2 results to DAG/IP
If it is not possible to establish an LDAPv2 session with the remote
server, or if the session is interrupted before results are received,
or if the remote server issues any kind of error message and produces
no result, the DAG-SAP will itself return no results and an error
message, including
% 403 Information Unavailable<NL>
If results are successfully received from the remote server, the
attributes and values that are provided for each result message will
be incorporated into the DAG/IP result, according to the schema
mappings laid out in Appendix B.
One particular adjustment must be done to accommodate differences
between LDAP and the DAG/IP. The attributes on which searches are
keyed ("cn", "l", and "o" in the LDAP schemas) are all defined as
being case-insensitive for equality matching. Thus, if the DAG/IP
query includes the constraint "case=consider", the results from the
remote server must be post-processed to remove any wrong-cased ones.
TISDAG: The serverhandle and localhandle in the DAG/IP response
should be constructed as follows:
serverhandle is: <hostname-without-periods><port> (because
server DN's are not enforceably unique). E.g., a
services.bunyip.com server on 7778 would
become servicesbunyipcom7778.
localhandle is: the RDN (relative distinguished name), with
spaces replaced by "_". E.g., cn=leslie_daigle
Daigle & Hedberg Informational [Page 61]
RFC 2967 TISDAG October 2000
5.12 LDAPv3 DAG-SAP
5.12.1 Input
The LDAPv3 DAG-SAP expects valid DAG/IP communications. Queries must
include referral information (see below) and search terms that
conform to the DAG-allowed query types (e.g., not searches for
organization alone, etc).
The referral information is added to the end of the DAG-SAP query, as
defined in the DAG-CAP definition sections:
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
5.12.2 Translation from DAG/IP to LDAPv3 query
The HOST and PORT information are used to make a TCP/IP-based
connection to the remote (presumed) LDAPv3 server. The DAG-SAP will
establish a connection with the remote server, following standard
LDAPv3 message exchanges.
The search request itself will be constructed from the DAG/IP query
(without the HOST, SERVER-INFO and PORT terms) as follows:
SearchRequest ::=
[APPLICATION 3] SEQUENCE {
baseObject LDAPDN, -- from the DAG/IP query
scope baseObject (0) },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3)
},
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
attrsOnly FALSE
filter Filter,
attributes SEQUENCE OF AttributeType
-- all DAGschema attributes equivalents in
the defined standard LDAP schema
}
Filter ::=
CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
Daigle & Hedberg Informational [Page 62]
RFC 2967 TISDAG October 2000
not [2] Filter,
substrings [4] SubstringFilter,
}
SubstringFilter
SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
substrings initial [0] LDAPString,
substrings any [1] LDAPString,
substrings final [2] LDAPString}
}
where and, or and not filters are constructed to preserve the logic
of the DAG/IP query.
For the purposes of matching token-based DAG/IP queries to reasonable
LDAP queries, all searches should be passed to the LDAP WDSP as
substring searches. The WDSP results must then be pruned to respect
token boundaries, where necessary.
So, for example, the DAG/IP query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=substring<NL>
would be sent to the designated LDAP WDSP as
(&(fn=*Foo Bar*)(o=*Thinking Cat*)(objectClass=person))
Interestingly, the query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=exact<NL>
would also be sent to the designated LDAP WDSP as
(&(fn=*Foo Bar*)(o=*Thinking Cat*)(objectClass=person))
but the WDSP's returned results would have to be pruned to remove any
results that had non-tokenizing characters on either side of "Foo
Bar" and "Thinking Cat".
The final consideration for mapping DAG/IP queries into LDAP queries
is the issue of character case. In LDAP, individual attribute
syntaxes define the consideration of case. All of the attributes
used here are case-insensitive in their definitions. Therefore, all
LDAP WDSP queries are inherently case-insensitive; if the DAG/IP
query calls for a case-sensitive match, the LDAP DAG-SAP will have to
do pruning of the results from the DAG-SAP.
Daigle & Hedberg Informational [Page 63]
RFC 2967 TISDAG October 2000
5.12.3 Translation of LDAPv3 results to DAG/IP
Any referrals that the remote WDSP server returns are pursued,
following the usual LDAPv3 (client) fashion, by the LDAPv3 DAG-SAP.
If it is not possible to establish an LDAPv3 session with the remote
server, or if the session is interrupted before results are received,
or if the remote server issues any kind of error message and produces
no result, the DAG-SAP will itself return no results and an error
message, including
% 403 Information Unavailable<NL>
If results are successfully received from the remote server, the
attributes and values that are provided for each result message will
be incorporated into the DAG/IP result, which will be expressed using
the DAG/IP and schema mappings as outlined in Appendix A.
One particular adjustment must be done to accommodate differences
between LDAP and the DAG/IP. The attributes on which searches are
keyed ("cn", "l", and "o" in the LDAP schemas) are all defined as
being case-insensitive for equality matching. Thus, if the DAG/IP
query includes the constraint "case=consider", the results from the
remote server must be post-processed to remove any wrong-cased ones.
TISDAG: The serverhandle and localhandle in the DAG/IP response
should be constructed as follows:
- serverhandle is: <hostname-without-periods><port> (because
server DN's are not enforceably unique). E.g., a
services.bunyip.com server on 7778 would become
servicesbunyipcom7778.
- localhandle is: the RDN (relative distinguished name), with
spaces replaced by "_". E.g., cn=leslie_daigle
5.13 Example Queries
The following sample end-user queries illustrate some of the more
delicate steps of query/schema semantics translations in the DAG
system.
N.B.: the data presented in these examples is often senseless,
provided only to serve as illustrations of matching on word-ordering,
case sensitivity, etc.
Daigle & Hedberg Informational [Page 64]
RFC 2967 TISDAG October 2000
5.13.1 A Whois++ Query
What the Whois++ DAG-CAP Receives
In this example, the Whois++ DAG-CAP receives the following query:
name=thinking and name=cat:search=exact;case=consider<NL>
The expected answer can be described as:
Any USER templates that contain the tokens "thinking" and "cat" in a
name attribute.
For example:
Different records:
name: the thinking cat
name: sublime cat thinking
or a single record with 2 or more name attributes
name: thinking felines
name: erudite cat
but not
name: Thinking Cat Enterprises
This last record would not match because the query called for case
sensitivity, and the case of the name attribute's value does not
match the query.
What the Whois++ DAG-CAP sends to the Referral Index
After schema translation, this is sent to the Referral Index as:
fn=thinking and fn=cat:search=exact<NL>
What the Whois++ DAG-CAP Sends to an LDAP DAG-SAP
Note that the Whois++ DAG-CAP will never interact with a Whois++
DAG-SAP as the Whois++ referrals returned by the Referral Index are
passed directly back to the Whois++ client.
The Whois++ DAG-CAP should send the same substantive query to the
DAG-SAP as it sent to the Referral Index, except that it can include
the case sensitivity constraint:
Daigle & Hedberg Informational [Page 65]
RFC 2967 TISDAG October 2000
fn=thinking and fn=cat:search=exact;case=consider<NL>
which will be translated by the DAG-SAP into an LDAP query of the
form:
(&(cn=*thinking*)(cn=*cat*)(objectclass=inetOrgPerson))
which will match a record with:
cn: Thinking
cn: Cat
(i.e., 2 different cn attributes, with the 2 values; LDAP defines
case sensitivity matching by the schema attribute definition).
or a record with:
cn: I wish I had a thinking dog and a singing cat
The first record should be pruned by the LDAP DAG-SAP, in order to
respect the semantics of the DAG/IP query.
5.13.2 An LDAP Query
What the LDAP DAG-CAP Receives
In this example, the LDAP DAG-CAP receives the following query
(using RFC1960 notation):
(& (cn=th*c*t) (o=green groceries) (objectClass=person))
What the LDAP user is looking for, with this query, is all records
within the "green groceries" organization that have a cn attribute
starting with "th", ending with "t", and having a "c" somewhere in
the middle.
cn values that would match this include:
cn: thinkingcat
cn: Thinking Cat
cn: The Black Cat
cn: Thick Mat
Daigle & Hedberg Informational [Page 66]
RFC 2967 TISDAG October 2000
5.13.3 What the LDAP DAG-CAP sends to the Referral Index
The LDAP DAG-CAP must formulate a token-based query to the Referral
Index that will not inadvertently exclude records that would match.
The first challenge lies in the fact that the "*" characters in the
LDAP string-based query can cover token-boundaries.
A suitable query to the Referral Index would be:
FN=th AND FN=C AND FN=T AND ORG=green AND
ORG=groceries:search=substring<NL>
This will generate some false positive referrals, directing the query
to WDSPs containing records with the following attribute values (the
match letters are in capitals for ease of identification):
cn: wiTH three blaCk poTs
o: peaGREEN and cyan GROCERIES
o: GROCERIES are GREENer than electronics
Alternative approaches include breaking the original query into
several queries to the referral index in such a way that the DAG-CAP
can use only those referrals that appear in all the Referral Index
responses. However, this is
overkill -- the purpose of the Referral Index is to give direction on
where there may be more information
difficult to code into the DAG-CAP in a general way -- it has to
identify, by LDAP query type, when and how to do so
likely to generate Referral Index queries that are complex and time-
consuming to process.
What the LDAP DAG-CAP Sends to a Whois++ DAG-SAP
The LDAP DAG-CAP may send the same query to a Whois++ DAG-SAP as it
sent to the Referral Index. False positives here mean results that
are not expected as a match by the LDAP client. The LDAP DAG-CAP
should prune these results from the information returned by the
Whois++ DAG-SAP.
Or it might rewrite the query into:
FN=th;search=lstring AND FN=C;search=substring AND
FN=T;search=tstring AND ORG=green AND ORG=groceries:case=ignore<NL>
Daigle & Hedberg Informational [Page 67]
RFC 2967 TISDAG October 2000
What the LDAP DAG-CAP Sends to an LDAP DAG-SAP
As an architectural principle, it is never wrong to send the same
query to a DAG-SAP as was formulated for the Referral Index. It is
also noteworthy to keep in memory that all DAG-SAPs are handled equal
by all DAG-CAPs therefore a LDAP DAG-CAP will not need to send a
different query to a LDAP DAG-SAP then it would to any other DAG-SAP.
So in this case the LDAP DAP-CAP could either send the same query to
the LDAP DAG-SAP as it sent to the Referral Index or it could send
the augmented version that is allowed to be use with the DAG-SAPs,
namely:
FN=th;search=lstring AND FN=C;search=substring AND
FN=T;search=tstring AND ORG=green\ groceries:case=ignore<NL>
Note that this will be translated, by the LDAP DAG-SAP, into a query
of the form
(&(cn=*th*)(cn=*c*)(cn=*t*)(o=*green groceries*)
(objectClass=person))
which is still more general than the original query.
Note the translation from "FN=th;search=lstring" into "cn=*th*".
This is necessary, as the DAG/IP lstring constraint is based on
tokens, whereas "cn=th*" refers to the beginning of the attribute's
value (phrase, not token). The DAG-SAP should therefore prune out
any results that include things like "oTHer plaCes for visiTors" in
order to match the semantics of the DAG/IP query it received.
The DAG-CAP should then prune those results to match the semantics of
the original LDAP query.
6.0 Service Specifications
6.1 Overview
To satisfy the requirements laid out for the TISDAG project, the
software built for the DAG system must be able to meet the following
service specifications:
- primary designated DAG-CAPs of all types (but not necessarily
secondary ones set up for load-balancing) must be available to
provide service or redirect queries on a 7x24 basis.
Daigle & Hedberg Informational [Page 68]
RFC 2967 TISDAG October 2000
- in general, responses to queries should be available in under 10
seconds; very generalized queries (i.e., when the user truly cannot
specify enough information to focus the search) can be deferred to
take much longer (having results is more important than having a
quick answer)
- the data provided from each WDSP should be updated in the DAG at
least once every 7 days
6.2 WDSP Participation
WDSPs who wish to participate in the DAG system do so by providing
DAG-compatible access to their service, where DAG-compatible means:
- access in (exactly) one of LDAPv2, LDAPv3, or Whois++
- 7x24 service for responding to referrals generated in the DAG
core (minimally) weekly updates of the index object describing the
information their service indexes
- use of USER and ROLE templates for Whois++ servers
- use of inetorgperson and organizationalrole objectclasses for
LDAP servers
To participate, WDSPs must register each DAG-compliant server with
the DAG system, providing details for each data set that it covers:
- the host, port and protocol of the server
- an identifier for the dataset
- a URL for the service of preference for accessing the data
(preferred source)
- protocol-specific information
- administrative contact information
- CIP object exchange information
Note that any WDSP wishing to make data available through the DAG
system but unable to support these requirements may provide
information through an agreement with a third-party which does meet
these requirements. Thus, data can be replicated between cooperating
WDSPs. The DAG referral index does not claim ownership of personal
information; it directs queries to services that do, by whatever
agreements with whichever relevant parties. Note that, in this case,
the SOURCE-URI may direct end-users to the WDSP's existing services,
not the service of the third party.
6.3 Load Distribution
It is anticipated that the DAG system will be quite popular, and
measures must be available to distribute the load of answering
queries.
Daigle & Hedberg Informational [Page 69]
RFC 2967 TISDAG October 2000
The DAG system is presented as a conceptual whole, made up of several
component parts -- DAG-CAPs, DAG-SAPs and the Referral Index. Each
of these component parts must be replicable, and service must be
shared between replicas.
It may be interesting to consider allowing large-scale service
providers (large companies, ISPs) the ability to mirror the Referral
Index or provide alternate DAG-CAPs/DAG-SAPs for their
personnel/customers. Policies and possibilities for doing that are
beyond the scope of this report; however, the software architecture
has been designed to support such activity.
Figure 6.1 shows that individual components of the DAG system may
each run on non-co-located server hardware, connected by TCP/IP
networks. These components can be replicated as needed.
Daigle & Hedberg Informational [Page 70]
RFC 2967 TISDAG October 2000
+====+
| | DAG-CAP (Client Access Point)
| |
+====+
+----+
| | DAG-SAP (Service Access Point)
| |
+----+
+====+
HTTP <-->| |
| | +----+
+====+ | |<--> Whois++
| |
+====+ +----+
SMTP <-->| |
| | +----+
+====+ | |<--> LDAPv2
| |
+====+ +----+
Whois++<-->| |
| |
+====+ +----+
| |<--> LDAPv3
| |
+----+
| |<--> LDAPv3
| |
+----+
| |<--> LDAPv3
| |
+====+ +----+
LDAPv2 <-->| |
| |
+====+
+====+
LDAPv3 <-->| |
| |
+====+
+------------------------+
| Referral Index |<--> Common Indexing Protocol
| | (CIP)
+------------------------+
+------------------------+
| Referral Index |
| |
+------------------------+
Figure 6.1 Distributable nature of DAG components
Daigle & Hedberg Informational [Page 71]
RFC 2967 TISDAG October 2000
Thus, the software built to this specification must be configurable
to permit the following actions:
- DAG-CAP software must be able to handle or redistribute the primary
load. Depending on the DAG-CAP software, this may be handled by
having multiple processes attending to incoming queries, or the
DAG-CAP at the primary address for the protocol may be nothing more
than a reflector that redirects incoming queries to the address of
the least-loaded server at the moment.
- This is particularly necessary in synchronous connection protocols,
such as Whois++ and LDAP, where the goal is to minimize the amount
of time a requesting client is connected to the well-advertised
address port.
- DAG-CAP software must be able to direct referrals to different
DAG-SAPs of the same protocol type.
- DAG-CAP software must be able to detect overly general queries
(i.e., have some metric to decide that the number of referrals
generated by the Referral Index is too great).
- DAG-SAPs must be able to redirect DAG-CAP queries at their
discretion, or just refuse service because of loading (therefore
DAG-CAPs must also be able to find other DAG-SAPs)
6.4 Extensibility
The DAG system has been designed to allow for extensibility in
certain key areas:
It is possible to add new DAG-CAPs and DAG-SAPs transparently.
Beyond replicating the software of existing DAG-CAPs, new
implementations for particular protocols (e.g., building a more
elaborate mail-based query system), or implementations for altogether
different protocols (e.g., PH) can be added by adhering to the basic
principles of DAG-CAPs and DAG-SAPs defined in the software
specification. The new DAG-CAP is responsible for the translation of
queries into DAG/IP (post-processing results, if necessary) and
results in the new protocol. No other part of the DAG system is
affected.
More functionality may be added to the DAG system service (e.g.,
adding security certificate references to the schema of returned
information) by updating the DAG schema.
Depending on how the load on the service goes, it may be interesting
to consider reducing the number of queries that are chained for
protocols that inherently can handle the concept of pursuing
referrals. Specifically, LDAPv3 and Whois++ both handle referrals,
but the current system calls for chaining LDAPv3 (and LDAPv2)
referrals for the Whois++ DAG-CAP, and vice versa. Alternatively,
Daigle & Hedberg Informational [Page 72]
RFC 2967 TISDAG October 2000
"virtual" DAG-CAPs could be established for each participating WDSP
for each protocol the WDSP doesn't support, and referrals to those
DAG-CAPs could be given to the calling client. For example, a
Whois++ client would be given a Whois++ referral to the virtual
Whois++ DAG-CAP for a WDSP that supports only LDAP. The importance
of having one virtual DAG-CAP per WDSP is that the point of
connection is the only way to distinguish which WDSP the Whois++
client thought it was connecting to.
7.0 Security
7.1 Information credibility
Security, in the context of "read-only" directory services, is
primarily concerned with maintaining data integrity as it passes from
an originating server to the end-user making an inquiry. That is,
some server(s) hold correct user information, and a client accessing
a directory service should be certain that whichever servers that the
information has to pass through before reaching the client, it
receives a true representation of the original information.
The DAG system as such MUST be completely invisible as the mediator
of the information from the WDSPs to the querying directory access
client. The only possible modifications that can appear is
translations from one characterset into another. Hopefully, this
does not alter the meaning of the information.
7.2 Unauthorized access
In keeping with the public nature of the proposed TISDAG service, the
DAG system does not provide any access control system beyond
components' configuration to accept connections from recognized other
components. For more detailed access control, it is up to the
connected WDSPs to apply the access control.
Since the DAG system only supports searching and retrieving
information, no updates can occur through the DAG client access
points.
Security in updates (CIP index objects) is provided by encryption and
signature of objects from registered WDSPs.
Daigle & Hedberg Informational [Page 73]
RFC 2967 TISDAG October 2000
8.0 Acknowledgments
This work came from ideas originally put forward by Patrik Faltstrom.
The TISDAG project was supported by the Swedish KK Foundation.
Thanks to especially to Jens Lundstrom, Thommy Eklof, Bjorn Larsson
and Sandro Mazzucato for their comments on draft versions of this
document.
Daigle & Hedberg Informational [Page 74]
RFC 2967 TISDAG October 2000
Appendix A - DAG Schema Definitions
The DAG makes use of 2 information schemas -- the DAGPERSON schema
for information about specific people, and the DAGORGROLE schema for
organizational roles that may or may not be job positions occupied by
people at any given time (e.g., an organization's president, customer
service desk, etc).
This appendix defines the schemas in terms of the attributes used
within the DAG/IP. Mappings to the standard LDAP and Whois++ object
classes and templates (respectively) are described in Appendix B.
Because the role of the DAG schemas is to act as an intermediary
between information provided in different access protocols, with
different underlying schema paradigms, the attributes in the schema
are identified as being required or optional. The required
attributes are so designated because they are involved in the DAG
search types and/or the minimal returned response. They have defined
mappings in the selected access protocols. The optional attributes
have proposed mappings in those protocols.
It is important to note that the DAG/IP is constructed to carry any
alternative attribute information that may be provided by a given
WDSP; individual DAG-SAPs and DAG-CAPs may choose to pass along,
interpret, or ignore any attributes not defined in this appendix.
Additionally, note that the order of attributes in the DAG/IP is
significant, which means that it is possible to use one attribute to
carry the information describing the type of subsequent ones (e.g.,
see the "ADR-TYPE" attribute below).
Finally, attributes may be repeated. For example, this schema
structure can carry multiple phone numbers of different types for
one person.
Daigle & Hedberg Informational [Page 75]
RFC 2967 TISDAG October 2000
A.1 DAG Personal Information Schema (DAGPERSON Schema)
Attribute Designation Specific Description
--------- ----------- -------------------------------------
FN Required Free-text representation of full name
EMAIL Required Internet e-mail address
LOC Required Locality -- geographic region
ORG Required Person's organization
ADR-TYPE Optional Type of address that follows
("org", "home", "org-postal",
"home-postal", "unqualified")
ADR Optional Full address
ADR-STREET Optional Street address component
ADR-ROOM Optional Suite or room number component
ADR-CITY Optional City name
ADR-STATE Optional Region of address
ADR-COUNTRY Optional Country
ADR-CODE Optional Postal code component
TEL-TYPE Optional Type of telephone number (
"work", "home", "mobile",
"fax" ,"pager", "unqualified")
in the following attribute
TEL Optional A phone number for the person
SOURCE Optional The WDSP's preferred access to
their service -- a URL
DN Optional Entry's "distinguished name"
(for LDAP)
Table A.1 DAGPERSON schema attributes
Daigle & Hedberg Informational [Page 76]
RFC 2967 TISDAG October 2000
A.2 DAG Organizational Role Information Schema (DAGORGROLE Schema)
Attribute Designation Specific Description
--------- ----------- ---------------------
ROLE Required Name of organizational role
EMAIL Required E-mail address associated with role
ORG Required Name of organization
LOC Required Locality -- geographic region
TEL-TYPE Optional Type of telephone number
in the TEL attribute immediately
following("org" or "fax")
TEL Optional Phone number
FN Optional Full name of current role occupant
SOURCE Optional The WDSP's preferred access to their
service -- a URL
DN Optional Entry's "distinguished name" (for LDAP)
Table A.2 DAGORGROLE schema attributes
Appendix B - Schema Mappings for Whois++ and LDAP
The DAG/IP makes use of two specific schemas, as defined above.
However, schemas particular to access protocols need to be handled in
order to appropriately address incoming user queries, and chaining
queries to WDSPs. The recognized standard schemas are:
- the USER template for Whois++ ([8])
- the ORGROLE template for Whois++ ([8])
- the inetOrgperson objectclass for LDAP ([16])
- the organizationalrole objectclass for LDAP ([18])
The DAG/IP schemas were developed based on the information that the
TISDAG project requirements wish to return in results, in conjunction
with information about standard schemas used in the basic WDSP access
protocols (LDAPv2/v3 and Whois++). However, particularly in the case
of address information, the schemas used for those protocols allow
for considerable scope of information representation. In practice,
this means that different WDSPs may choose to use different sub-parts
of the schema, or even implement local customizations.
Therefore, Appendix A outlines a very basic schema that can carry all
the necessary information. The basic DAG-CAPs and DAG-SAPs are
designed to work to that information structure. This appendix
outlines the expected behaviour for DAG-SAPs mapping into the DAG/IP
schema, and DAG-CAPs extracting information to pass along to client
software after a chaining operation has returned results.
Daigle & Hedberg Informational [Page 77]
RFC 2967 TISDAG October 2000
B.1 LDAP and the DAG Schemas
The only time information is carried in the DAG schemas is when a
DAG-SAP is returning information (obtained from WDSPs' servers) to a
DAG-CAP using the DAG/IP. The "canonical" mappings between standard
LDAP object classes (inetorgPerson, defined in [16] and
organizationalRole, defined in [18] and the DAGPERSON schema and
DAGORGROLE schema are defined such that information passed from an
LDAP DAG-SAP to an LDAP DAG-CAP (e.g., in the case of an LDAPv3 DAG-
SAP returning information chained for an LDAPv2 DAG-CAP) will be
mapped into the same attributes as it was extracted.
However, the representation of some attributes (such as address) is
truly widely varied between protocol paradigms. The goal with the
"reasonable approximation" mappings that are provided is to give
DAG-CAPs a basic mechanism for communicating information drawn from
non-LDAP DAG-SAP sources. The mappings may not be perfect, but they
will convey the information to the end-user in some LDAP-
understandable fashion, which is the goal of this project's effort.
The canonical mappings for the LDAP inetorgPerson object class and
the DAGPERSON schema are given in Table B.1. A few reasonable
approximation mappings follow in Table B.2. Beyond that, DAG-SAPs
may pass along any additional attributes in the DAG/IP, and DAG-CAPs
may elect to forward or interpret any that are recognizable (e.g.,
the sn ("surname") attribute is not listed here, but a DAG-SAP might
return that in the DAG/IP, and a DAG-CAP, recognizing the string
representation, could elect to include it in its LDAP response to the
client).
DAGPERSON Attribute LDAP inetorgPerson attribute
------------------- ----------------------------
FN cn
EMAIL mail
LOC l
ORG o
ADR-TYPE=org
ADR-STREET street
ADR-ROOM roomNumber
ADR-STATE st
ADR-COUNTRY c
ADR-TYPE=org-postal
ADR postalAddress
ADR-ROOM postOfficeBox
ADR-CODE postalCode
Daigle & Hedberg Informational [Page 78]
RFC 2967 TISDAG October 2000
ADR-TYPE=home-postal
ADR homePostalAddress
TEL-TYPE=work
TEL telephoneNumber
TEL-TYPE=home
TEL homePhone
TEL-TYPE=fax
TEL facsimileTelephoneNumber
TEL-TYPE=mobile
TEL mobile
TEL-TYPE=pager
TEL pager
DN dn
SOURCE labeledURI
Table B.1 Canonical DAGPERSON schema & LDAP inetorgPerson attributes
DAGROLE Attribute LDAP organizationalRole attribute
----------------------- ---------------------------------
ADR-TYPE=unqualified
ADR street
ADR-STREET street
ADR-ROOM room
ADR-STATE st
ADR-COUNTRY c
TEL-TYPE=unqualified
TEL telephoneNumber
Table B.2 Reasonable Approximations for LDAP organizationalRole
attributes
Daigle & Hedberg Informational [Page 79]
RFC 2967 TISDAG October 2000
For example, consider the following LDAP record information, in LDIF
[11] format:
dn: cn=Barbara Jensen, ou=Product Development, o=Ace Industry,
c=US
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetorgperson
cn: Barbara Jensen
cn: Barbara J Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
telephonenumber: +1 408 5551212
description: A big sailing fan
This would validly be carried in the DAGPERSON schema as follows:
DN: cn=Barbara Jensen, ou=Product Development, o=Ace Industry,
c=US
FN: Barbara Jensen
FN: Barbara J Jensen
FN: Babs Jensen
SN: Jensen
TEL-TYPE: work
TEL: +1 408 5551212
The canonical mappings for the LDAP organizationalRole object class
and the DAGORGROLE schema are given in Table B.3 .Beyond that, DAG-
SAPs may elect to send along any attributes, and DAG-CAPs may
interpret any that are recognizable. N.B., the organizationalRole
class does not include provision for inclusion of an e-mail address.
This mapping rather blithely assumes the availability of the mail
attribute as defined for inetorgPerson.
Daigle & Hedberg Informational [Page 80]
RFC 2967 TISDAG October 2000
DAGORGROLE Attribute LDAP organizationalRole attribute
-------------------- ---------------------------------
ROLE cn
EMAIL mail
ORG o
LOC l
TEL-TYPE=org
TEL telephoneNumber
TEL-TYPE=fax
TEL facsimileNumber
FN roleOccupant
DN dn
SOURCE labeledURI
Table B.3 Canonical mappings for LDAP organizationalRole attributes
B.2 Whois++ and the DAG Schemas
The "canonical" mappings between standard Whois++ templates as
defined in [8] and the DAGPERSON schema and DAGORGROLE schema are
defined in Tables B.4 and B.5. Beyond that, DAG-SAPs may pass along
any additional attributes in the DAG/IP, and DAG-CAPs may elect to
forward or interpret any that are recognizable.
DAGPERSON Attribute Whois++ USER template attribute
------------------- -------------------------------
FN name
EMAIL email
LOC address-locality
ORG organization-name
ADR-TYPE=unqualified
ADR address
ADR-TYPE=org
ADR organization-address
ADR-STREET organization-address-street
ADR-ROOM organization-address-room
ADR-CITY organization-address-city
ADR-STATE organization-address-state
ADR-COUNTRY organization-address-country
ADR-CODE organization-address-zip-code
Daigle & Hedberg Informational [Page 81]
RFC 2967 TISDAG October 2000
ADR-TYPE=home address-type=home
ADR address
ADR-STREET address-street
ADR-ROOM address-room
ADR-CITY address-city
ADR-STATE address-state
ADR-COUNTRY address-country
ADR-CODE address-zip-code
TEL-TYPE=work phone-type=work
TEL phone
TEL-TYPE=home phone-type=home
TEL phone
TEL-TYPE=fax
TEL fax
TEL-TYPE=mobile
TEL cellular
TEL-TYPE=pager
TEL pager
Table B.4 Canonical DAGPERSON schema & Whois++ USER attributes
DAGORGROLE Attribute Whois++ ORGROLE attribute
-------------------- -------------------------
ROLE org-role
EMAIL email
ORG organization-name
LOC organization-address-locality
FN name
TEL-TYPE=org
TEL phone
TEL-TYPE=fax
TEL fax
Table B.5 Canonical mappings for Whois++ ORGROLE attributes
Appendix C - DAG-Internal Protocol (DAG/IP)
The DAG-Internal Protocol (DAG/IP) is currently defined as a
derivative of the query-interaction protocol of Whois++ as laid out
in RFC1835 ([6]).
Daigle & Hedberg Informational [Page 82]
RFC 2967 TISDAG October 2000
C.1 A word on the choice of DAG/IP
The use of the DAG/IP is strictly internal to the DAG system. In
that regard, it is possible make use of any query language, or define
a new one.
The Whois++ protocol was selected as the basis of the DAG/IP for
several reasons:
- it has the power and flexibility to convey all necessary queries
- it is a simple, text-based protocol; clients need not implement the
full functionality of the protocol in order to carry out minimal
queries
- the power of the full-fledge directory service query protocol will
give DAG-CAP writers the ability to express more sophisticated
queries if desired (e.g., to produce more intricate "intelligent"
matching of spellings, common character substitutions, etc).
- the text-based, delimited attribute results expression facilitates
optional inclusion of extra data supplied by WDSPs -- DAG-CAPs can
easily ignore any unknown information and continue to interpret the
rest of the result information.
Also, the use of an existing protocol leverages the experience and
time of the creators of the protocol -- hammering out such elusive
and yet necessary details as handling line-endings, quoting special
characters, etc.
There is a freely-available test suite of tools for testing servers'
Whois++ protocol conformance (for the Referral Index, and for DAG-
SAPs). Send mail to digger-info@bunyip.com for further information.
C.2 DAG/IP Input and Output -- Overview
Input interactions in DAG/IP are as defined in RFC1835, "Architecture
of the WHOIS++ service" ([6]), sections 2.2 and 2.3. Section C.3 of
this document adapts the grammar used in more recent descriptions of
the Whois++ protocol to illustrate the syntax of the DAG/IP.
DAG/IP output will be a subset of what is defined in RFC1835, section
2.4, except that referral responses ("SERVER-TO-ASK") contain more
information.
C.3 BNF for DAG/IP input and output
The following sections are adapted from the Whois++ grammar. For
discussion of the semantic intent of the query protocol, and other
matters, see Whois++ RFC 1835 [6].
Daigle & Hedberg Informational [Page 83]
RFC 2967 TISDAG October 2000
C.3.1 The DAG/IP Input Grammar
The following grammar, which uses the Augmented BNF (ABNF) notation
as defined in [5], defines the set of acceptable DAG/IP input.
N.B.: As outlined in the ABNF definition, rule names and string
literals are in the US-ASCII character set, and are case-insensitive.
Also, when a character is written explicitly in the grammar, as for
example ";", it represents the byte value of that character in all of
the allowed character sets in their encodings used in this protocol.
Specifically in UNICODE, ";" means the character U+003B, which when
encoding the character in UTF-8 will generate the byte value 0x3B
which is then used in the DAG/IP protocol.
dagip-command = ( system-command [":" "hold"]
/ ri-query
/ sap-query ) nl
ri-query = ri-terms [":" globalcnstrnts]
sap-query = sap-terms [":" [sapcnstrnts][ ":" wdspinfo]]
system-command = "constraints"
/ "describe"
/ "commands"
/ "polled-by"
/ "polled-for"
/ "version"
/ "list"
/ "show" [1*sp datastring]
/ "help" [1*sp datastring]
/ "<NL>" [string]
ri-terms = ri-and-expr *(1*sp "or" 1*sp ri-and-expr)
ri-and-expr = ri-basic-expr *(1*sp "and" 1*sp ri-basic-
expr)
ri-basic-expr = ["not" 1*sp] ri-term / ( "(" ri-terms ")" )
ri-term = generalterm / specificterm / combinedterm
sap-terms = sap-and-expr *(1*sp "or" 1*sp sap-and-expr)
sap-and-expr = sap-basic-expr *(1*sp "and" 1*sp
sap-basic-expr)
sap-basic-expr = ["not" 1*sp] sap-term / ( "(" sap-terms ")" )
Daigle & Hedberg Informational [Page 84]
RFC 2967 TISDAG October 2000
sap-term = ( generalterm / specificterm / combinedterm)
localcnstrnts
generalterm = datastring
TISDAG: Since the DAG system only supports certain attribute
combinations in its queries, (Table 3.1). The use of generalterm
may lead to unexpected behaviour and is therefore deprecated.
CAPs should therefore not use it even if it is in the protocol.
specificterm = specificname "=" datastring
specificname = "handle" / "value"
combinedterm = attributename "=" datastring
sapcnstrnts = sapcnstrnt *(";" sapcnstrnt)
sapcnstrnt = localcnstrnt / globalcnstrnt
localcnstrnts = [";search=" sap-searchvalue] [";case="
sap-casevalue]
localcnstrnt = "search=" sap-searchvalue / "case="
sap-casevalue
;N.B.: in the case where local and global constraints
; conflict, local constraints take precedence
; and overrides the global constraint
sap-searchvalue = "tstring" / searchvalue
sap-casevalue = "consider" / "ignore"
globalcnstrnts = globalcnstrnt *(";" globalcnstrnt)
globalcnstrnt = "search" "=" searchvalue
/ opt-globalcnst
opt-globalcnst = "hold"
/ "case" "=" casevalue
/ "maxfull" "=" 1*digit
/ "maxhits" "=" 1*digit
/ "language" "=" language
/ "incharset" "=" characterset
/ "ignore" "=" attributename
/ "include" "=" attributename
Daigle & Hedberg Informational [Page 85]
RFC 2967 TISDAG October 2000
; N.B.: If an attribute is named both with the "include" and "ignore"
; constraints, the attribute is to be included in the result, but the
; system message must be "% 112 Requested constraint not fulfilled".
language = <The language code defined in RFC1766>
characterset = "UNICODE-2-0-UTF-8"
searchvalue = "exact" / "substring" / "lstring"
casevalue = "ignore" / "consider"
wdspinfo = attrValAss *( ";" attrValAss )
attrValAss = attributename "=" datastring
TISDAG: Within the boundaries of the TISDAG project it has been
decided that the only permitted attributes for wdspinfo are
"host","port","server-info" and "charset". Regarding "charset"
the values for this attribute are defined to be one of "UTF-8",
"ISO8859-1","T\.61" or "US-ASCII".
datastring = 1*data-elt
attributename = 1*(<%d32-126 except specialbyte>)
; omit 127, which is DEL
data-elt = "\" specialbyte / normalbyte
normalbyte = <%d32-255, except specialbyte>
specialbyte = " " / tab / "=" / "," / ":" / ";" / "\" /
"*" / "." / "(" / ")" / "[" / "]" / "^" /
"$" / "!" / "<NL>"
number = 1*digit
digit = "0" / "1" / "2" / "3" / "4" /
"5" / "6" / "7" / "8" / "9"
tab = %d09
sp = %d32 ; space
nl = %d13 %d10 ; CR LF
Daigle & Hedberg Informational [Page 86]
RFC 2967 TISDAG October 2000
NOTE: Spaces (sp) that are significant to a query must be escaped.
The following characters, when significant to the query, may be
preceded and/or followed by a single space:
: ; , ( ) = !
C.3.2 The DAG/IP Response Grammar
The following grammar, which uses the Augmented BNF (ABNF) notation
as defined in RFC2234 (see [5]),
N.B.: As outlined in the ABNF definition, rule names and string
literals are in the US-ASCII character set, and are case-insensitive.
Also, when a character is written explicitely in the grammar, as for
example ";", it represents the byte value of that character in all of
the allowed character sets in their encodings used in this protocol.
Specifically in UNICODE, ";" means the character U+003B which when
encoding the character in UTF-8 will generate the byte value 0x3B
which is then used in the DAG/IP protocol.
server-resp = goodmessage mnl output mnl endmessage
/ badmessage nl endmessageclose
output = 0*(full-record / server-to-ask)
full-record = "# FULL " template " " serverhandle " "
localhandle system-nl
1*fulldata
"# END" system-nl
TISDAG: serverhandle is:
- Whois++, whatever the server-handle on the record returned by
the WDSP.
- LDAP, <hostname-without-periods><port> (because server DN's are
not enforceably unique). E.g., a services.bunyip.com server on
7778 would become servicesbunyipcom7778.
localhandle is:
- Whois++: the localhandle on the record returned by the WDSP
- LDAP, it is the RDN (relative distinguished name), with spaces
replaced by "_". E.g., cn=leslie_daigle
server-to-ask = "# SERVER-TO-ASK " serverhandle system-nl
server-to-askdata
"# END" system-nl
fulldata = " " attributename ": " attributevalue
system-nl
Daigle & Hedberg Informational [Page 87]
RFC 2967 TISDAG October 2000
server-to-ask-data = " Server-Info: " serverinfo system-nl
" Host-Name: " hostname system-nl
" Host-Port: " number system-nl
" Protocol: " prot system-nl
" Source-URI: " source system-nl
" Charset: " characterset system-nl
attributename = r-string
attributevalue = longstring
template = <%d32-%d255 except specialbyte>
serverhandle = <%d32-%d255 except specialbyte>
localhandle = <%d32-%d255 except specialbyte>
serverinfo = string
hostname = string
prot = string ; currently one of "ldapv2"
; "ldapv3" "whois++"
characterset = "UTF-8" / "T.61" / "ISO8859-1" / "US-ASCII"
source = string
longstring = string 0*( nl ( "+" / "-" ) string )
string = 0*(%d32-255)
r-string = 0*(<%d32-126 except specialbyte>)
; omit 127 which is DEL
specialbyte = ":" / " "
mnl = 1*system-nl
system-nl = nl [ 1*(message nl) ]
nl = %d13 %d10 ; CR and LF
message = [1*( messagestart "-" string nl)]
messagestart " " string nl
messagestart = "% " digit digit digit
Daigle & Hedberg Informational [Page 88]
RFC 2967 TISDAG October 2000
goodmessage = [1*( goodmessagestart "-" string nl)]
goodmessagestart " " string nl
goodmessagestart= "% 200"
badmessage = [1*( badmessagestart "-" string nl)]
badmessagestart " " string nl
badmessagestart = "% 5" digit digit
endmessage = endmessageclose / endmessagecont
endmessageclose = [endmessagestart " " string nl]
byemessage
endmessagecont = endmessagestart " " string nl
endmessagestart = "% 226"
byemessage = byemessagestart " " string nl
byemessagestart = "% 203"
number = 1*( digit )
digit = "0" / "1" / "2" / "3" / "4" / "5" / "6" /
"7" / "8" / "9"
C.4 DAG/IP Response Messages
The following list and discussion of response codes is derived from
the Whois++ protocol definition, RFC1835 ([6]).
A system message begins with a '%', followed by a space and a three
digit number, a space, and an optional text message. The line
message must be no more than 81 bytes long, including the terminating
CR LF pair. There is no limit to the number of system messages that
may be generated.
A multiline system message have a hyphen instead of a space in column
6, immediately after the numeric response code in all lines, except
the last one, where the space is used.
Example 1
% 200 Command okay
Example 2
Daigle & Hedberg Informational [Page 89]
RFC 2967 TISDAG October 2000
% 220-Welcome to
% 220-the Whois++ server
% 220 at ACME inc.
The client is not expected to parse the text part of the response
message except when receiving reply 600 or 601, in which case the
text part is in the former case the name of a character set that will
be used by the server in the rest of the response, and in the latter
case when it specifies what language the attribute value is in. The
valid values for characters sets is specified in the "characterset"
list in the BNF listing in Appendix C.
The theory of reply codes is described in Appendix E in STD 10,
RFC821 ([15]).
System response code Description
---------------------------- ------------------------------
110 Too many hits The number of matches exceeded
the value specified by the
maxhits constraint. Server
will still reply with as many
records as "maxhits" allows.
111 Requested constraint not One or more constraints in query
supported is not implemented, but the
search is still done.
112 Requested constraint not One or more constraints in query
fulfilled has unacceptable value and was
therefore not used, but the
search is still done.
200 Command Ok Command accepted and executed.
The client must wait for a
transaction end system message.
201 Command Completed Command accepted and executed.
successfully
203 Bye Server is closing connection
Daigle & Hedberg Informational [Page 90]
RFC 2967 TISDAG October 2000
204 Overgeneralized The server could not exactly
match the DAG query into its
native access protocol. The
resulting native query was
"looser".
220 Service Ready Greeting message. Server is
accepting commands.
226 Transaction complete End of data. All responses to
query are sent.
401 Service not available
402 Search expression
too complicated
403 Information Unavailable When a remote service is not
(currently) available.
404 Time out
500 Syntax error
502 Search expression too This message is sent when the
complicated server is not able to resolve a
query (i.e. when a client sent a
regular expression that is too
deeply nested).
503 Query to general This is like the "too many hits"
situation, but the server does
not send along any results. This
message is used to deflect data
mining.
505 Operations error Permanent operations error
600 <token> Subsequent attribute values are
encoded in the character set
specified by <token>.
601 <token> Subsequent attribute values are
in the language specified by
<token>.
Daigle & Hedberg Informational [Page 91]
RFC 2967 TISDAG October 2000
601 DEF Subsequent attribute values are
default values, i.e. they should
be used for all languages not
specified by "601 <token>" since
last "601 ANY" message.
601 ANY Subsequent attribute values are
for all languages.
Table C.1 List of system response codes
Daigle & Hedberg Informational [Page 92]
RFC 2967 TISDAG October 2000
Appendix D - DAG/IP Response Messages Mapping
LDAPv2/v3 DAG/IP
--------------------------------------- ---------------------
success (0) v2&v3 200 Command Ok
operationsError (1) v2&v3 505 Operations error
protocolError (2) v2&v3 505 Operations error
timeLimitExceeded (3) v2&v3 404 Timeout
sizeLimitExceeded (4) v2&v3 110 To many hits
compareFalse (5) v2&v3 200 OK
compareTrue (6) v2&v3 200 OK
authMethodNotSupported (7) v2&v3 505 Operations error
strongAuthRequired (8) v2&v3 505 Operations error
referral (10) v3 200 OK
adminLimitExceeded (11) v3 110 Too many hits
unavailableCriticalExtension (12) v3 505 Operations error
confidentialityRequired (13) v3 505 Operations error
saslBindInProgress (14) v3 N.A.
noSuchAttribute (16) v2&v3 200 OK
undefinedAttributeType (17) v2&v3 500 Syntax error
inappropriateMatching (18) v2&v3 500 Syntax error
constraintViolation (19) v2&v3 111 Requested constraint
not supported
attributeOrValueExists (20) v2&v3 200 OK
invalidAttributeSyntax (21) v2&v3 500 Syntax error
noSuchObject (32) v2&v3 200 OK
aliasProblem (33) v2&v3 505 Operations error
invalidDNSyntax (34) v2&v3 500 Syntax error
isLeaf (35) v2 N.A.
aliasDereferencingProblem (36) v2&v3 505 Operations error
inappropriateAuthentication (48) v2&v3 500 Syntax error
invalidCredentials (49) v2&v3 403 Information Unavailable
insufficientAccessRights (50) v2&v3 403 Information Unavailable
busy (51) v2&v3 403 Information Unavailable
unavailable (52) v2&v3 401 Service not available
unwillingToPerform (53) v2&v3 505 Operations error
loopDetect (54) v2&v3 505 Operations error
namingViolation (64) v2&v3 N.A.
objectClassViolation (65) v2&v3 N.A.
notAllowedOnNonLeaf (66) v2&v3 N.A.
notAllowedOnRDN (67) v2&v3 N.A.
entryAlreadyExists (68) v2&v3 N.A.
objectClassModsProhibited (69) v2&v3 N.A.
affectsMultipleDSAs (71) v3 N.A.
other (80) v2&v3 403 Information Unavailable
Table D.1 LDAPv2/v3 resultcodes to DAG/IP response codes
mapping
Daigle & Hedberg Informational [Page 93]
RFC 2967 TISDAG October 2000
DAG/IP LDAP v2/v3
--------------------------------------- --------------------------
110 Too many hits sizeLimitExceeded (4)
111 Requested constraint not supported constraintViolation (19)
112 Requested constraint not fullfilled constraintViolation (19)
200 Command Ok Success (0)
201 Command Completed successfully N.A.
203 Bye N.A.
204 Overgeneralized N.A.
220 Service Ready N.A.
226 Transaction complete N.A.
401 Service not available unavailable (52)
402 Search expression too complicated unwillingToPerform (53)
403 Information Unavailable busy (51)
404 Time out timeLimitExceeded (3)
405 Operations error operationsError (1)
500 Syntax error protocolError (2)
502 Search expression too complicated unwillingToPerform (53)
503 Query to general unwillingToPerform (53)
505 Operations error operationsError (1)
600 <token> N.A.
601 <token> N.A.
601 DEF N.A.
601 ANY N.A.
Table D.2 Mapping from DAG/IP response codes to LDAPv2/v3 resultcodes
DAG/IP Whois++
-------------------------------------- -----------------------------
110 Too Many hits 110 Too Many hits
111 Requested constraint not supported 111 Requested constraint not
supported
112 Requested constraint not fullfilled 112 Requested constraint not
fullfilled
200 Command Ok 200 Command Ok
201 Command Completed successfully 201 Command Completed
successfully
401 Service not available 401 Service not available
403 Information Unavailable 403 Information not available
404 Timeout 404 Timeout
405 Operations error 405 Operations error
500 Syntax error 500 Syntax error
502 Search expression too complicated 502 Search expression too
complicated
503 Query to general 506 Query to general
505 Operations error 505 Operations error
Table D.3 Mapping between DAG/IP and Whois++ response codes
Daigle & Hedberg Informational [Page 94]
RFC 2967 TISDAG October 2000
Appendix E - DAG CIP Usage
E.1 CIP Index Object
The CIP object used by the DAG system is based on the Tagged Index
Object as defined in [12]. The grammar, adapted from that Work in
Progress, for the specific object used by the DAG is as follows:
index-object = 0*(io-part SEP) io-part
io-part = header SEP schema-spec SEP index-info
header = version-spec SEP update-type SEP this-update SEP
last-update context-size
version-spec = "version:" *SPACE "x-tagged-index-1"
update-type = "updatetype:" *SPACE ( "total" |
( "incremental" [*SPACE "tagbased"|"uniqueIDbased" ])
this-update = "thisupdate:" *SPACE TIMESTAMP
last-update = [ "lastupdate:" *SPACE TIMESTAMP SEP]
context-size = [ "contextsize:" *SPACE 1*DIGIT SEP]
schema-spec = "BEGIN IO-Schema" SEP 1*(schema-line SEP)
"END IO-Schema"
schema-line = attribute-name ":" token-type
token-type = "TOKEN"
index-info = full-index | incremental-index
full-index = "BEGIN Index-Info" SEP 1*(index-block SEP)
"END Index-Info"
incremental-index = 1*(add-block | delete-block | update-block)
add-block = "BEGIN Add Block" SEP 1*(index-block SEP)
"END Add Block"
delete-block = "BEGIN Delete Block" SEP 1*(index-block SEP)
"END Delete Block"
update-block = "BEGIN Update Block" SEP
0*(old-index-block SEP)
1*(new-index-block SEP)
"END Update Block"
old-index-block = "BEGIN Old" SEP 1*(index-block SEP)
"END Old"
new-index-block = "BEGIN New" SEP 1*(index-block SEP)
"END New"
index-block = first-line 0*(SEP cont-line)
first-line = attr-name ":" *SPACE taglist "/" attr-value
cont-line = "-" taglist "/" attr-value
taglist = tag 0*("," tag) | "*"
tag = 1*DIGIT ["-" 1*DIGIT]
attr-value = 1*(UTF8)
attr-name = dag-searchattr / "objectclass"
dag-searchattr = "FN" / "LOC" / "ROLE" / "ORG"
TIMESTAMP = 1*DIGIT
NAMECHAR = DIGIT | UPPER | LOWER | "-" | ";" | "."
Daigle & Hedberg Informational [Page 95]
RFC 2967 TISDAG October 2000
SPACE = <ASCII space, %x20>;
SEP = (CR LF) | LF
CR = <ASCII CR, carriage return, %x0D>;
LF = <ASCII LF, line feed, %x0A>;
DIGIT = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
"8" | "9"
UPPER = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
"I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
"Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
"Y" | "Z"
LOWER = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
"i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
"q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
"y" | "z"
US-ASCII-SAFE = %x01-09 / %x0B-0C / %x0E-7F
;; US-ASCII except CR, LF, NUL
UTF8 = US-ASCII-SAFE / UTF8-1 / UTF8-2 / UTF8-3
/ UTF8-4 / UTF8-5
UTF8-CONT = %x80-BF
UTF8-1 = %xC0-DF UTF8-CONT
UTF8-2 = %xE0-EF 2UTF8-CONT
UTF8-3 = %xF0-F7 3UTF8-CONT
UTF8-4 = %xF8-FB 4UTF8-CONT
UTF8-5 = %xFC-FD 5UTF8-CONT
N.B.: The only tokenization type permitted is "TOKEN". While the
Tagged Index Object memo permits the use of "FULL" (i.e., the entire
value of the attribute is preserved as a single token), that has the
danger of yielding a unique token for every record. Studies in the
growth of centroid sizes as a function of number of records (see
[14]) demonstrate that such unique tokens (e.g., phone numbers) are
to be avoided. While storing tag information requires some number of
extra bytes of storage per token index entry, using unique tokens
causes the number of token entries in the index to continue to grow
linearly with the number of records, thereby affecting search
efficiency.
Note also that tags are to be applied to the data on a per entry
level. Thus, if two index lines in the same index object contain the
same tag, then it is always the case that those two lines refer back
to the same "record" in the directory. In LDAP terminology, the two
lines would refer back to the same directory object.
Daigle & Hedberg Informational [Page 96]
RFC 2967 TISDAG October 2000
Additionally if two index lines in the same index object contain
different tags, then it is always the case that those two lines refer
back to different records in the directory.
The attribute "objectclass" is used to denote the record/object types
in the data summarized in this index object.
Values for the objectclass attribute should be restricted to:
dagperson or dagrole, the two DAG schema object types.
E.2 CIP Index Object Creation
WDSPs are expected to create index objects following the general
principles outlined in the Whois++ protocol documentation (creation
of centroids) and the Tagged Index Object documentation ([12]).
Following the syntax described above, the index object contains token
information for each attribute in the DAGSchema:
- a list of all the unique tokens (strings delimited by the specified
characters) that appear in the WDSP database for the attribute
- for each token in that list, which records the token appears in
So, for example,
Record #1:
FN: Foo Bar
ORG: The Snack Bar
Record #2:
FN: Bar Smith
ORG: Snack Shack
yields (conceptually) the following information for the attribute FN:
Foo (1), Bar (1,2), Smith (2)
and the following information for the attribute ORG:
The (1), Snack (1, 2), Bar (1), Shack (2)
Note that the record numbers here are used simply as tags or virtual
record identifiers to indicate when 2 tokens appear in the same
record. The record identifiers are not used for any part of any
query to the WDSP.
Daigle & Hedberg Informational [Page 97]
RFC 2967 TISDAG October 2000
There is some discussion as to whether the use of the same record tag
for all attributes makes it too easy to "decompile" the index object;
i.e., reconstruct a WDSPs data based on re-ordering the tokens
associated with each attribute and tag number. However, we are
dealing only with the search attributes here, which is a minimal
subset of the quantity of data held by the WDSP. The conclusion is
then that the improved efficiency given by using the same tag numbers
across attributes outweighs the (remote) possibility of information
reconstruction.
This would yield the index object:
version: x-tagged-index-1
update-type: total
this-update: 855938804
last-update:
context-size:
BEGIN IO-Schema
objectclass: TOKEN
FN: TOKEN
ORG: TOKEN
END IO-Schema
BEGIN Index-Info
objectclass: */dagperson
FN: 1/Foo
-1,2/Bar
-2/Smith
ORG: 1/The
-1,2/Snack
-1/Bar
-2/Shack
End Index-Info
TISDAG: Within the project it has been decided to base consistency
between updates on consistent tags. This means that if the
update-type is "incremental" the specifier must be "tagbased".
E.3 CIP Index Object Sharing
E.3.1 Registration of Servers
It is beyond the scope of this document to define how WDSP servers
shall be registered with the DAG Referral Index. Such a procedure
must be defined, and the following information established for each
WDSP dataset (adapted from the Tagged Index Object specification,
[12]):
Daigle & Hedberg Informational [Page 98]
RFC 2967 TISDAG October 2000
dsi: An OID which uniquely identifies the subtree and scope of the
dataset for which the index object is created.
base-uri: One or more URI's which will form the base of any referrals
created based upon the index object that is governed by this
agreement. For example, for LDAP the base-uri would specify (among
other items): the LDAP host, the base object to which this index
object refers (e.g., c=SE), and the scope of the index object
(e.g., single container).
supplier: The hostname and listening port number of the supplier
server, as well as any alternative servers holding that same naming
contexts, in case the supplier is unavailable.
source-uri: The URI of the WDSP's preferred source of directory
service information. This might be, for instance, an HTTP-based
service.
consumeraddr: This is a URI of the "mailto:" form, with the RFC 822
email address of the consumer server.
updateinterval: The maximum duration in seconds between occurrences
of the supplier server generating an update. If the consumer
server has not received an update from the supplier server after
waiting this long since the previous update, it is likely that the
index information is now out of date. A typical value for a server
with frequent updates would be 604800 seconds, or every week.
attributeNamespace: Every set of index servers that together wants to
support a specific usage of indices, has to agree on which
attributenames to use in the index objects. The participating
directory servers also has to agree on the mapping from local
attributenames to the attributenames used in the index. Since one
specific index server might be involved in several such sets, it
has to have some way to connect a update to the proper set of
indexes. One possible solution to this would be to use different
DSIs.
consistencybase: How consistency of the index is maintained over
incremental updates:
complete - every change or delete concerning one object has to
contain all tokens connected to that object. This method must be
supported by any server who wants to comply with this standard
tagbased - starting at a full update every incremental update
referring back to this full updated has to maintain state-
information regarding tags, such that a object within the
original database is assigned the same tagnumber every time.
This method is optional.
Daigle & Hedberg Informational [Page 99]
RFC 2967 TISDAG October 2000
uniqueID - every object in the Dataset has to have a unique value
for a specific attribute in the index. A example of such a
attribute could be the distinguishedName attribute. This method
is also optional.
securityoption: Whether and how the supplier server should sign and
encrypt the update before sending it to the consumer server.
Options for this version of the DAG service are "none": the update
is sent in plaintext "PGP/MIME": the update is digitally signed and
encrypted using PGP (see [7]). PGP/MIME is recommended.
security credentials: The long-term cryptographic credentials used
for key exchange and authentication of the consumer and supplier
servers, if a security option was selected. For "PGP/MIME", this
will be the trusted public keys of both servers.
E.3.2 Transmission of Objects
CIP Index Objects are sent to the DAG Referral Index by MIME-encoded
SMTP, following the Common Indexing Protocol specification (see [2]
and [3]).
Appendix F - Summary of Technical Survey Results
As part of the TISDAG project, a technical survey was carried out --
announced on the tisdag@swip.net mailing list, all Swedish WDSPs (and
potential WDSPs) were encouraged to fill out and submit the WWW-based
survey form (see http://tisdag.sunet.se/tisdag-survey.html).
The survey was carried out in May, 1997. Response was not as good as
had been hoped -- in the end, 5 WDSPs participated. We had hoped for
more responses than this, in order to have a concrete sense of
directory service providers' current and planned status. However,
informal "hallway" conversations with a few people at
Interoperabilitet'97 in Sollentuna suggest that, while people see the
TISDAG project as an important and timely step, they don't
necessarily have an immediate understanding of how it will impact
them, and what they can/should contribute. So, the results can be
seen as informational, though not a definitive statement of the whole
directory service picture in Sweden.
Interesting things to note from these results include the fact that,
although there were only 5 respondents, these are clearly significant
players -- 4 expect to have more than 100 000 records to contribute
by 12 months from now. There were no real surprises in terms of the
supported protocols or search types.
Daigle & Hedberg Informational [Page 100]
RFC 2967 TISDAG October 2000
Table E.1 summarizes information from the survey concerning types of
queries currently supported by WDSPs, and planned for the next 12
months. Note that, at the time of the survey, the requirement of
searching by ROLE had not been proposed, so the survey did not
specifically ask if WDSPs supported both the DAGPERSON schema
protocol-equivalents (i.e., USER template in Whois++ and
inetorgperson objectclass in LDAP). In the table, the column
"Complete info?" describes whether or not the WDSP currently returns
at least as much information as is required for a DAG reply.
Resp Search Types Complete info? Access Protocols Access Protocols
(now) (12 months)
---- ------------ -------------- ---------------- ----------------
1 NOL Except ROLE Whois++ Whois++
2 N,NO,NL,NOL Except ROLE LDAPv2,DAP,PH, LDAPv2,LDAPv3,DAP,
HTTP,Gopher PH,HTTP,Gopher
3 N,NL,NOL Except ROLE LDAPv2,DAP,HTTP LDAPv2,LDAPv3,DAP,
HTTP
4 N,NO,NL,NOL Except ROLE Whois++,HTTP LDAPv3,Whois++,
HTTP,E-mail
5 N,NO,NL,NOL Except ROLE LDAPv2,Whois LDAPv2,LDAPv3,
Whois++,HTTP Whois,Whois++,PH,
Finger,HTTP
Table F.1 Summary of TISDAG Survey Results: Queries
Resp # of Records (now) # of Records (12 months) Character Sets
----- ------------------ ------------------------ --------------
1 94 280 120 000 - 130 000 ISO-8859-1
2 88 000 100 000 ISO-8859-1
3 N/A 100 000 T.61 (Telex)
4 150 000 250 000 ISO-8859-1
UTF-8 UNICODE
5 4 300 10 000 ISO-8859-1
Table F.2 Summary of TISDAG Survey Results: Operational Information
Daigle & Hedberg Informational [Page 101]
RFC 2967 TISDAG October 2000
Appendix G - Useful References
N.B.: The following is a collection of Internet standards documents
(RFCs) and Internet-Drafts from which the material in this report was
drawn. Internet-Drafts are works-in-progress, and are not meant to
be cited. Where they are used in this document, references are to
the text contained in the Internet-Draft; i.e., they are not meant to
imply standards, so much as useful starting points for the work of
this project.
Electronic copies of the version of the Internet-Drafts documents
that were used in preparing this report are available from the
project web page, http://tisdag.sunet.se.
Bibliography
[1] Allen, J. and M. Mealling, "The Architecture of the Common
Indexing Protocol", RFC 2651, August 1999.
[2] Allen, J. and M. Mealing, "MIME Object Definitions for the
Common Indexing Protocol (CIP)", RFC 2652, August 1999.
[3] Allen, J. and P. Leach, "CIP Transport Protocols", RFC 2653,
August 1999.
[4] Crocker, D., "Standard for the Format of ARPA Internet Text
Messages", STD 11, RFC 822, August 1982.
[5] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF",
RFC 2234, November 1997.
[6] Deutsch, P., Schoultz, R., Falstrom, P. and C. Weider,
"Architecture of the WHOIS++ Service", RFC 1835, July 1995.
[7] Elkins, M., "MIME Security with Pretty Good Privacy (PGP)", RFC
2015, October 1996.
[8] Patrik Faltstrom, Martin Hamilton, Leslie L. Daigle, "WHOIS++
templates", Work in Progress.
[9] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Interent Message Bodies",
RFC 2045, November 1996.
[10] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, November
1996.
Daigle & Hedberg Informational [Page 102]
RFC 2967 TISDAG October 2000
[11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical
Specification", RFC 2849, June 2000.
[12] Hedberg, R., Greenblatt, B., Moats, R. and M. Wahl, "A Tagged
Index Object for use in the Common Indexing Protocol", RFC 2654,
August 1999.
[13] Howes, R., "A String Representation of LDAP Search Filters", RFC
1960, June 1996.
[14] Paul Panotzki, "Complexity of the Common Indexing Protocol:
Predicting Search Times in Index Server Meshes", Master's
Thesis, KTH, September 1996.
[15] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
August 1982.
[16] Smith, M., "Definition of the inetOrgPerson Object Class", RFC
2798, April 2000.
[17] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
[18] Wahl, M., "A summary of the X.500(96) User Schema for use with
LDAPv3", RFC 2256, December 1997.
[19] Yeong, W., Howes, T. and S. Kille, "Lightweight Directory Access
Protocol", RFC 1777, March 1995.
[20] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
2279, January 1998.
[21] The Unicode Consortium, "The Unicode Standard -- Version 2.0",
Addison-Wesley, 1996.
Daigle & Hedberg Informational [Page 103]
RFC 2967 TISDAG October 2000
Authors' Addresses
Leslie L. Daigle
Thinking Cat Enterprises
EMail: leslie@thinkingcat.com
Roland Hedberg
Catalogix
Jegerveien 25
0777 Oslo
Norway
Phone: +47 23 08 29 96
EMail: Roland@catalogix.se
Daigle & Hedberg Informational [Page 104]
RFC 2967 TISDAG October 2000
Full Copyright Statement
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Daigle & Hedberg Informational [Page 105]
|