File: shishi.texi

package info (click to toggle)
shishi 1.0.0-1
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 22,144 kB
  • ctags: 7,865
  • sloc: ansic: 61,153; sh: 12,212; yacc: 1,219; makefile: 1,164; perl: 624; sed: 16
file content (5283 lines) | stat: -rw-r--r-- 203,748 bytes parent folder | download
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
\input texinfo   @c -*- mode: texinfo; coding: us-ascii; -*-
@c This file is part of Shishi.
@c See below for copyright and license.

@setfilename shishi.info
@include version.texi
@settitle GNU Shishi @value{VERSION}
@finalout

@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg fn

@copying
This manual is last updated @value{UPDATED} for version
@value{VERSION} of Shishi.

Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Simon Josefsson.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying

@dircategory GNU utilities
@direntry
* shishi: (shishi).		A Kerberos 5 implementation
@end direntry

@dircategory GNU Libraries
@direntry
* libshishi: (shishi).		Library implementing Kerberos 5.
@end direntry

@titlepage
@title Shishi
@subtitle Kerberos 5 implementation for the GNU system
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Simon Josefsson
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Shishi
@insertcopying
@end ifnottex

@menu
* Introduction::                How to use this manual.
* User Manual::                 Using Shishi as end-user.
* Administration Manual::       Administrating server aspects of Shishi.
* Reference Manual::            Detailed description of config files, etc.
* Programming Manual::          Calling Shishi from a programming language.
* Acknowledgements::            Whom to blame.

Appendices

* Criticism of Kerberos::       Why you maybe shouldn't use Kerberos.
* Protocol Extensions::         Description of protocol extensions used.
* Copying Information::         How you can copy and share Shishi.

Indices

* Function and Data Index::     Index of functions, variables and data types.
* Concept Index::               Index of concepts and programs.
@end menu


@c **********************************************************
@c ********************  Introduction  **********************
@c **********************************************************
@node Introduction
@chapter Introduction

Shishi is an implementation of the Kerberos 5 network authentication
system, as specified in RFC 4120.  Shishi can be used to authenticate
users in distributed systems.

Shishi contains a library ('libshishi') that can be used by
application developers to add support for Kerberos 5.  Shishi contains
a command line utility ('shishi') that is used by users to acquire and
manage tickets (and more).  The server side, a Key Distribution
Center, is implemented by 'shishid'.  Of course, a manual documenting
usage aspects as well as the programming API is included.

Shishi currently supports AS/TGS exchanges for acquiring tickets,
pre-authentication, the AP exchange for performing client and server
authentication, and SAFE/PRIV for integrity/privacy protected
application data exchanges.

Shishi is internationalized; error and status messages can be
translated into the users' language; user name and passwords can be
converted into any available character set (normally including
ISO-8859-1 and UTF-8) and also be processed using an experimental
Stringprep profile.

Most, if not all, of the widely used encryption and checksum types are
supported, such as 3DES, AES, ARCFOUR and HMAC-SHA1.

Shishi is developed for the GNU/Linux system, but runs on over 20
platforms including most major Unix platforms and Windows, and many
kind of devices including iPAQ handhelds and S/390 mainframes.

Shishi is free software licensed under the GNU General Public License
version 3.0 or later.

@menu
* Getting Started::
* Features and Status::
* Overview::
* Cryptographic Overview::
* Supported Platforms::
* Getting help::
* Commercial Support::
* Downloading and Installing::
* Bug Reports::
* Contributing::
@end menu

@node Getting Started
@section Getting Started

This manual documents the Shishi application and library programming
interface.  All commands, functions and data types provided by Shishi
are explained.

The reader is assumed to possess basic familiarity with network
security and the Kerberos 5 security system.

This manual can be used in several ways.  If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application.  Forward references are included where
necessary.  Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library.  Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up those parts
of the interface which are unclear.

@node Features and Status
@section Features and Status

Shishi might have a couple of advantages over other packages doing a
similar job.

@table @asis
@item It's Free Software
Anybody can use, modify, and redistribute it under the terms of the GNU
General Public License version 3.0 (@pxref{GNU GPL}) or later.

@item It's thread-safe
The library uses no global variables.

@item It's internationalized
It handles non-ASCII username and passwords and user visible strings
used in the library (error messages) can be translated into the users'
language.

@item It's portable
It should work on all Unix like operating systems, including Windows.

@end table

Shishi is far from feature complete, it is not even a full RFC 1510
implementation yet.  However, some basic functionality is implemented.
A few implemented feature are mentioned below.

@itemize @bullet

@item Initial authentication (AS) from raw key or password.
This step is typically used to acquire a ticket granting ticket and,
less commonly, a server ticket.

@item Subsequent authentication (TGS).
This step is typically used to acquire a server ticket, by
authenticating yourself using the ticket granting ticket.

@item Client-Server authentication (AP).
This step is used by clients and servers to prove to each other who
they are, using negotiated tickets.

@item Integrity protected communication (SAFE).
This step is used by clients and servers to exchange integrity
protected data with each other.  The key is typically agreed on using
the Client-Server authentication step.

@item Ticket cache, supporting multiple principals and realms.
As tickets have a life time of typically several hours, they are
managed in disk files.  There can be multiple ticket caches, and each
ticket cache can store tickets for multiple clients (users), servers,
encryption types, etc.  Functionality is provided for locating the
proper ticket for every use.

@item Most standard cryptographic primitives.
The believed most secure algorithms are supported
(@pxref{Cryptographic Overview}).

@item Telnet client and server.
This is used to remotely login to other machines, after authenticating
yourself with a ticket.

@item PAM module.
This is used to login locally on a machine.

@item KDC addresses located using DNS SRV RRs.

@item Modularized low-level crypto interface.
Currently Gnulib and Libgcrypt are supported.  If you wish to add
support for another low-level cryptographic library, you only have to
implement a few APIs for DES, AES, MD5, SHA1, HMAC, etc. Look at
@file{gl/gc-gnulib.c} or @file{gl/gc-libgcrypt.c} as a starting
pointer.

@end itemize

The following table summarize what the current objectives are (i.e.,
the todo list) and an estimate on how long it will take to implement
the feature, including some reasonable startup-time to get familiar
with Shishi in general.  If you like to start working on anything,
please let me know so work duplication can be avoided.

@itemize @bullet

@item Parse @file{/etc/krb5.keytab} to extract keys to use for telnetd etc (week)

@item Cross-realm support (week).

@item PKINIT (use libksba, weeks)

@item Finish GSSAPI support via GSSLib (weeks)
Shishi will not support GSSLib natively, but a separate project
``GSSLib'' is under way to produce a generic GSS implementation, and
it will use Shishi to implement the Kerberos 5 mechanism.

@item Port to cyclone (cyclone need to mature first)

@item Modularize ASN.1 library so it can be replaced (days).
Almost done, all ASN.1 functionality is found in lib/asn1.c, although
the interface is rather libtasn1 centric.

@item KDC (initiated, weeks)

@item LDAP backend for Shisa.

@item Set/Change password protocol (weeks?)

@item Port applications to use Shishi (indefinite)

@item Finish server-realm stuff

@item Improve documentation

@item Improve internationalization

@item Add AP-REQ replay cache (week).

@item Study benefits by introducing a PA-TGS-REP.
This would provide mutual authentication of the KDC in a way that is
easier to analyze.  Currently the mutual authentication property is
only implicit from successful decryption of the KDC-REP and the 4 byte
nonce.

@item GUI applet for managing tickets.
This is supported via the ticket-applet, of which a Shishi port is
published on the Shishi home page.

@item Authorization library (months?)
The shishi_authorized_p() is not a good solution, better would be to
have a generic and flexible authorization library.  Possibly based on
S-EXP's in tickets?  Should support non-Kerberos uses as well, of
course.

@item Proof read manual.

@item X.500 support, including DOMAIN-X500-COMPRESS.
I will accept patches that implement this, if it causes minimal
changes to the current code.

@end itemize

@node Overview
@section Overview

This section describes RFC 1510 from a protocol point of
view@footnote{The text is a lightly adapted version of the
introduction section from RFC 1510 by J. Kohl and C. Neuman, September
1993, copyright likely owned by the RFC 1510 authors or some
contributor.}.

Kerberos provides a means of verifying the identities of principals,
(e.g., a workstation user or a network server) on an open
(unprotected) network.  This is accomplished without relying on
authentication by the host operating system, without basing trust on
host addresses, without requiring physical security of all the hosts
on the network, and under the assumption that packets traveling along
the network can be read, modified, and inserted at will. (Note,
however, that many applications use Kerberos' functions only upon the
initiation of a stream-based network connection, and assume the
absence of any "hijackers" who might subvert such a connection.  Such
use implicitly trusts the host addresses involved.)  Kerberos performs
authentication under these conditions as a trusted third- party
authentication service by using conventional cryptography, i.e.,
shared secret key.  (shared secret key - Secret and private are often
used interchangeably in the literature.  In our usage, it takes two
(or more) to share a secret, thus a shared DES key is a secret key.
Something is only private when no one but its owner knows it.  Thus,
in public key cryptosystems, one has a public and a private key.)

The authentication process proceeds as follows: A client sends a
request to the authentication server (AS) requesting "credentials" for
a given server.  The AS responds with these credentials, encrypted in
the client's key.  The credentials consist of 1) a "ticket" for the
server and 2) a temporary encryption key (often called a "session
key").  The client transmits the ticket (which contains the client's
identity and a copy of the session key, all encrypted in the server's
key) to the server.  The session key (now shared by the client and
server) is used to authenticate the client, and may optionally be used
to authenticate the server.  It may also be used to encrypt further
communication between the two parties or to exchange a separate
sub-session key to be used to encrypt further communication.

The implementation consists of one or more authentication servers
running on physically secure hosts.  The authentication servers
maintain a database of principals (i.e., users and servers) and their
secret keys. Code libraries provide encryption and implement the
Kerberos protocol.  In order to add authentication to its
transactions, a typical network application adds one or two calls to
the Kerberos library, which results in the transmission of the
necessary messages to achieve authentication.

The Kerberos protocol consists of several sub-protocols (or
exchanges).  There are two methods by which a client can ask a
Kerberos server for credentials.  In the first approach, the client
sends a cleartext request for a ticket for the desired server to the
AS. The reply is sent encrypted in the client's secret key. Usually
this request is for a ticket-granting ticket (TGT) which can later be
used with the ticket-granting server (TGS).  In the second method, the
client sends a request to the TGS.  The client sends the TGT to the
TGS in the same manner as if it were contacting any other application
server which requires Kerberos credentials.  The reply is encrypted in
the session key from the TGT.

Once obtained, credentials may be used to verify the identity of the
principals in a transaction, to ensure the integrity of messages
exchanged between them, or to preserve privacy of the messages.  The
application is free to choose whatever protection may be necessary.

To verify the identities of the principals in a transaction, the
client transmits the ticket to the server.  Since the ticket is sent
"in the clear" (parts of it are encrypted, but this encryption doesn't
thwart replay) and might be intercepted and reused by an attacker,
additional information is sent to prove that the message was
originated by the principal to whom the ticket was issued.  This
information (called the authenticator) is encrypted in the session
key, and includes a timestamp.  The timestamp proves that the message
was recently generated and is not a replay.  Encrypting the
authenticator in the session key proves that it was generated by a
party possessing the session key.  Since no one except the requesting
principal and the server know the session key (it is never sent over
the network in the clear) this guarantees the identity of the client.

The integrity of the messages exchanged between principals can also be
guaranteed using the session key (passed in the ticket and contained
in the credentials).  This approach provides detection of both replay
attacks and message stream modification attacks.  It is accomplished
by generating and transmitting a collision-proof checksum (elsewhere
called a hash or digest function) of the client's message, keyed with
the session key.  Privacy and integrity of the messages exchanged
between principals can be secured by encrypting the data to be passed
using the session key passed in the ticket, and contained in the
credentials.

@node Cryptographic Overview
@section Cryptographic Overview

Shishi implements several of the standard cryptographic primitives.
In this section we give the names of the supported encryption suites,
and some notes about them, and their associated checksum suite.

Statements such as ``it is weak'' should be read as meaning that there
is no credible security analysis of the mechanism available, and/or
that should an attack be published publicly, few people would likely
be surprised.  Also keep in mind that the key size mentioned is the
actual key size, not the effective key space as far as a brute force
attack is concerned.

As you may infer from the descriptions, there is currently no
encryption algorithm and only one checksum algorithm that inspire
great confidence in its design.  Hopefully this will change over time.

@cindex DES
@cindex 3DES
@cindex AES
@cindex ARCFOUR

@table @code

@item NULL

@code{NULL} is a dummy encryption suite for debugging.  Encryption and
decryption are identity functions.  No integrity protection.  It is
weak.  It is associated with the @code{NULL} checksum.

@item arcfour-hmac
@itemx arcfour-hmac-exp

@code{arcfour-hmac-*} are a proprietary stream cipher with 56 bit
(@code{arcfour-hmac-exp}) or 128 bit (@code{arcfour-hmac}) keys, used
in a proprietary way described in an expired IETF draft
@file{draft-brezak-win2k-krb-rc4-hmac-04.txt}.  Deriving keys from
passwords is supported, and is done by computing a message digest
(MD4) of a 16-bit Unicode representation of the ASCII password, with
no salt.  Data is integrity protected with a keyed hash (HMAC-MD5),
where the key is derived from the base key in a creative way.  It is
weak.  It is associated with the @code{arcfour-hmac-md5} checksum.

@item des-cbc-none

@code{des-cbc-none} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
derived from passwords by an obscure application specific algorithm.
It is weak, because it offers no integrity protection.  This is
typically only used by RFC 1964 GSS-API implementations (which try to
protect integrity using an ad-hoc solution).  It is associated with
the @code{NULL} checksum.

@item des-cbc-crc

@code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode, using the key as IV (@pxref{Key as
initialization vector}).  The keys can be derived from passwords by an
obscure application specific algorithm.  Data is integrity protected
with an unkeyed but encrypted @code{CRC32}-like checksum.  It is
weak. It is associated with the @code{rsa-md5-des} checksum.

@item des-cbc-md4

@code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
derived from passwords by an obscure application specific algorithm.
Data is integrity protected with an unkeyed but encrypted MD4 hash.
It is weak. It is associated with the @code{rsa-md4-des} checksum.

@item des-cbc-md5

@code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
derived from passwords by an obscure application specific algorithm.
Data is integrity protected with an unkeyed but encrypted MD5 hash.
It is weak.  It is associated with the @code{rsa-md5-des} checksum.
This is the strongest RFC 1510 interoperable encryption mechanism.

@item des3-cbc-none

@code{des3-cbc-none} is DES encryption and decryption with three 56
bit keys (effective key size 112 bits) and 8 byte blocks in CBC mode.
The keys can be derived from passwords by the same algorithm as
@code{des3-cbc-sha1-kd}.  It is weak, because it offers no integrity
protection.  This is typically only used by GSS-API implementations
(which try to protect integrity using an ad-hoc solution) for
interoperability with some existing Kerberos GSS implementations.  It
is associated with the @code{NULL} checksum.

@item des3-cbc-sha1-kd

@code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
bit keys (effective key size 112 bits) and 8 byte blocks in CBC mode.
The keys can be derived from passwords by a algorithm based on the
paper "A Better Key Schedule For DES-like Ciphers"
@footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
Uri Blumenthal and Steven M. Bellovin (it is not clear if the
algorithm, and the way it is used, is used by any other protocols,
although it seems unlikely).  Data is integrity protected with a keyed
SHA1 hash in HMAC mode.  It has no security proof, but is assumed to
provide adequate security in the sense that knowledge on how to crack
it is not known to the public.  Note that the key derivation function
is not widely used outside of Kerberos, hence not widely studied.  It
is associated with the @code{hmac-sha1-des3-kd} checksum.

@item aes128-cts-hmac-sha1-96
@itemx aes256-cts-hmac-sha1-96

@code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
AES encryption and decryption with 128 bit and 256 bit key,
respectively, and 16 byte blocks in CBC mode with Cipher Text
Stealing.  Cipher Text Stealing means data length of encrypted data is
preserved (pure CBC add up to 7 pad characters).  The keys can be
derived from passwords with RSA Laboratories PKCS#5 Password Based Key
Derivation Function
2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
which is allegedly provably secure in a random oracle model.  Data is
integrity protected with a keyed SHA1 hash, in HMAC mode, truncated to
96 bits.  There is no security proof, but the schemes are assumed to
provide adequate security in the sense that knowledge on how to crack
them is not known to the public.  Note that AES has yet to receive the
test of time, and the AES cipher encryption mode (CBC with Ciphertext
Stealing, and a non-standard IV output) is not widely standardized
(hence not widely studied).  It is associated with the
@code{hmac-sha1-96-aes128} and @code{hmac-sha1-96-aes256} checksums,
respectively.

@end table

The protocol do not include any way to negotiate which checksum
mechanisms to use, so in most cases the associated checksum will be
used.  However, checksum mechanisms can be used with other encryption
mechanisms, as long as they are compatible in terms of key format etc.
Here are the names of the supported checksum mechanisms, with some
notes on their status and the compatible encryption mechanisms.  They
are ordered by increased security as perceived by the author.

@table @code

@item NULL

@code{NULL} is a dummy checksum suite for debugging.  It provides no
integrity.  It is weak.  It is compatible with the @code{NULL}
encryption mechanism.

@item arcfour-hmac-md5

@code{arcfour-hmac-md5} is a keyed HMAC-MD5 checksum computed on a MD5
message digest, in turn computed on a four byte message type indicator
concatenated with the application data.  (The @code{arcfour}
designation is thus somewhat misleading, but since this checksum
mechanism is described in the same document as the @code{arcfour}
encryption mechanisms, it is not a completely unnatural designation.)
It is weak.  It is compatible with all encryption mechanisms.

@item rsa-md4

@code{rsa-md4} is a unkeyed MD4 hash computed over the message.  It is
weak, because it is unkeyed.  However applications can, with care, use
it non-weak ways (e.g., by including the hash in other messages that
are protected by other means).  It is compatible with all encryption
mechanisms.

@item rsa-md4-des

@code{rsa-md4-des} is a DES CBC encryption of one block of random data
and a unkeyed MD4 hash computed over the random data and the message
to integrity protect.  The key used is derived from the base protocol
key by XOR with a constant.  It is weak. It is compatible with the
@code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
mechanisms.

@item rsa-md5

@code{rsa-md5} is a unkeyed MD5 hash computed over the message.  It is
weak, because it is unkeyed.  However applications can, with care, use
it non-weak ways (e.g., by including the hash in other messages that
are protected by other means).  It is compatible with all encryption
mechanisms.

@item rsa-md5-des

@code{rsa-md5-des} is a DES CBC encryption of one block of random data
and a unkeyed MD5 hash computed over the random data and the message
to integrity protect.  The key used is derived from the base protocol
key by XOR with a constant.  It is weak.  It is compatible with the
@code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
mechanisms.

@item hmac-sha1-des3-kd

@code{hmac-sha1-des3-kd} is a keyed SHA1 hash in HMAC mode computed
over the message.  The key is derived from the base protocol by the
simplified key derivation function (similar to the password key
derivation functions of @code{des3-cbc-sha1-kd}, which does not appear
to be widely used outside Kerberos and hence not widely studied).  It
has no security proof, but is assumed to provide good security.  The
weakest part is likely the proprietary key derivation function.  It is
compatible with the @code{des3-cbc-sha1-kd} encryption mechanism.

@item hmac-sha1-96-aes128
@itemx hmac-sha1-96-aes256

@code{hmac-sha1-96-aes*} are keyed SHA1 hashes in HMAC mode computed
over the message and then truncated to 96 bits.  The key is derived
from the base protocol by the simplified key derivation function
(similar to the password key derivation functions of
@code{aes*-cts-hmac-sha1-96}, i.e., PKCS#5).  It has no security
proof, but is assumed to provide good security.  It is compatible with
the @code{aes*-cts-hmac-sha1-96} encryption mechanisms.

@end table

Several of the cipher suites have long names that can be hard to
memorize.  For your convenience, the following short-hand aliases
exists.  They can be used wherever the full encryption names are used.

@table @code

@item arcfour

Alias for @code{arcfour-hmac}.

@item des-crc

Alias for @code{des-cbc-crc}.

@item des-md4

Alias for @code{des-cbc-md4}.

@item des-md5
@itemx des

Alias for @code{des-cbc-md5}.

@item des3
@itemx 3des

Alias for @code{des3-cbc-sha1-kd}.

@item aes128

Alias for @code{aes128-cts-hmac-sha1-96}.

@item aes
@itemx aes256

Alias for @code{aes256-cts-hmac-sha1-96}.

@end table

@node Supported Platforms
@section Supported Platforms

Shishi has at some point in time been tested on the following
platforms.  Online build reports for each platforms and Shishi version
is available at @url{http://autobuild.josefsson.org/shishi/}.

@enumerate

@item Debian GNU/Linux 3.0 (Woody)
@cindex Debian

GCC 2.95.4 and GNU Make. This is the main development platform.
@code{alphaev67-unknown-linux-gnu}, @code{alphaev6-unknown-linux-gnu},
@code{arm-unknown-linux-gnu}, @code{armv4l-unknown-linux-gnu},
@code{hppa-unknown-linux-gnu}, @code{hppa64-unknown-linux-gnu},
@code{i686-pc-linux-gnu}, @code{ia64-unknown-linux-gnu},
@code{m68k-unknown-linux-gnu}, @code{mips-unknown-linux-gnu},
@code{mipsel-unknown-linux-gnu}, @code{powerpc-unknown-linux-gnu},
@code{s390-ibm-linux-gnu}, @code{sparc-unknown-linux-gnu},
@code{sparc64-unknown-linux-gnu}.

@item Debian GNU/Linux 2.1
@cindex Debian

GCC 2.95.4 and GNU Make. @code{armv4l-unknown-linux-gnu}.

@item Tru64 UNIX
@cindex Tru64

Tru64 UNIX C compiler and Tru64 Make. @code{alphaev67-dec-osf5.1},
@code{alphaev68-dec-osf5.1}.

@item SuSE Linux 7.1
@cindex SuSE

GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
@code{alphaev67-unknown-linux-gnu}.

@item SuSE Linux 7.2a
@cindex SuSE Linux

GCC 3.0 and GNU Make. @code{ia64-unknown-linux-gnu}.

@item SuSE Linux
@cindex SuSE Linux

GCC 3.2.2 and GNU Make.  @code{x86_64-unknown-linux-gnu} (AMD64
Opteron ``Melody'').

@item RedHat Linux 7.2
@cindex RedHat

GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
@code{alphaev67-unknown-linux-gnu}, @code{ia64-unknown-linux-gnu}.

@item RedHat Linux 8.0
@cindex RedHat

GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.

@item RedHat Advanced Server 2.1
@cindex RedHat Advanced Server

GCC 2.96 and GNU Make. @code{i686-pc-linux-gnu}.

@item Slackware Linux 8.0.01
@cindex RedHat

GCC 2.95.3 and GNU Make. @code{i686-pc-linux-gnu}.

@item Mandrake Linux 9.0
@cindex Mandrake

GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.

@item IRIX 6.5
@cindex IRIX

MIPS C compiler, IRIX Make. @code{mips-sgi-irix6.5}.

@item AIX 4.3.2
@cindex AIX

IBM C for AIX compiler, AIX Make.  @code{rs6000-ibm-aix4.3.2.0}.

@c @item Microsoft Windows 2000 (Cygwin)
@c @cindex Windows
@c
@c GCC 3.2, GNU make. @code{i686-pc-cygwin}.

@item HP-UX 11
@cindex HP-UX

HP-UX C compiler and HP Make. @code{ia64-hp-hpux11.22},
@code{hppa2.0w-hp-hpux11.11}.

@item SUN Solaris 2.8
@cindex Solaris

Sun WorkShop Compiler C 6.0 and SUN Make. @code{sparc-sun-solaris2.8}.

@item NetBSD 1.6
@cindex NetBSD

GCC 2.95.3 and GNU Make. @code{alpha-unknown-netbsd1.6},
@code{i386-unknown-netbsdelf1.6}.

@item OpenBSD 3.1 and 3.2
@cindex OpenBSD

GCC 2.95.3 and GNU Make. @code{alpha-unknown-openbsd3.1},
@code{i386-unknown-openbsd3.1}.

@item FreeBSD 4.7 and 4.8
@cindex FreeBSD

GCC 2.95.4 and GNU Make. @code{alpha-unknown-freebsd4.7},
@code{alpha-unknown-freebsd4.8}, @code{i386-unknown-freebsd4.7},
@code{i386-unknown-freebsd4.8}.

@item MacOS X 10.2 Server Edition
@cindex MacOS X

GCC 3.1 and GNU Make. @code{powerpc-apple-darwin6.5}.

@item Cross compiled to uClinux/uClibc on Motorola Coldfire.
@cindex Motorola Coldfire
@cindex uClinux
@cindex uClibc

GCC 3.4 and GNU Make @code{m68k-uclinux-elf}.

@end enumerate

If you use Shishi on, or port Shishi to, a new platform please report
it to the author (@pxref{Bug Reports}).

@node Getting help
@section Getting help

A mailing list where users of Shishi may help each other exists, and
you can reach it by sending e-mail to @email{help-shishi@@gnu.org}.
Archives of the mailing list discussions, and an interface to manage
subscriptions, is available through the World Wide Web at
@url{http://lists.gnu.org/mailman/listinfo/help-shishi}.

@node Commercial Support
@section Commercial Support

Commercial support is available for users of Shishi.  The kind of
support that can be purchased may include:

@itemize

@item Implement new features.
Such as support for some optional part of the Kerberos standards,
e.g. PKINIT, hardware token authentication.

@item Port Shishi to new platforms.
This could include porting Shishi to an embedded platforms that may
need memory or size optimization.

@item Integrate Kerberos 5 support in your existing project.

@item System design of components related to Kerberos 5.

@end itemize

If you are interested, please write to:

@verbatim
Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org
@end verbatim

If your company provides support related to Shishi and would like to
be mentioned here, contact the author (@pxref{Bug Reports}).

@node Downloading and Installing
@section Downloading and Installing
@cindex Installation
@cindex Download

The package can be downloaded from several places, including:

@url{ftp://alpha.gnu.org/pub/gnu/shishi/}

The latest version is stored in a file, e.g.,
@samp{shishi-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
indicate the highest version number.

The package is then extracted, configured and built like many other
packages that use Autoconf.  For detailed information on configuring
and building it, refer to the @file{INSTALL} file that is part of the
distribution archive.

Here is an example terminal session that download, configure, build
and install the package.  You will need a few basic tools, such as
@samp{sh}, @samp{make} and @samp{cc}.

@example
$ wget -q ftp://alpha.gnu.org/pub/gnu/shishi/shishi-@value{VERSION}.tar.gz
$ tar xfz shishi-@value{VERSION}.tar.gz
$ cd shishi-@value{VERSION}/
$ ./configure
...
$ make
...
$ make install
...
@end example

After this you should be prepared to continue with the user,
administration or programming manual, depending on how you want to use
Shishi.

A few @code{configure} options may be relevant, summarized in the
table.

@table @code

@item --disable-des
@itemx --disable-3des
@itemx --disable-aes
@itemx --disable-md
@itemx --disable-null
@itemx --disable-arcfour
Disable a cryptographic algorithm at compile time.  Usually it is
better to disable algorithms during run-time with the configuration
file, but this allows you to reduce the code size slightly.

@item --disable-starttls
Disable the experimental TLS support for KDC connections.  If you do
not use a Shishi KDC, this support is of no use so you could safely
disable it.

@item --without-stringprep
Disable internationalized string processing.

@end table

For the complete list, refer to the output from @code{configure
--help}.

@node Bug Reports
@section Bug Reports
@cindex Reporting Bugs

If you think you have found a bug in Shishi, please investigate it and
report it.

@itemize @bullet

@item Please make sure that the bug is really in Shishi, and
preferably also check that it hasn't already been fixed in the latest
version.

@item You have to send us a test case that makes it possible for us to
reproduce the bug.

@item You also have to explain what is wrong; if you get a crash, or
if the results printed are not good and in that case, in what way.
Make sure that the bug report includes all information you would need
to fix this kind of bug for someone else.

@end itemize

Please make an effort to produce a self-contained report, with
something definite that can be tested or debugged.  Vague queries or
piecemeal messages are difficult to act on and don't help the
development effort.

If your bug report is good, we will do our best to help you to get a
corrected version of the software; if the bug report is poor, we won't
do anything about it (apart from asking you to send better bug
reports).

If you think something in this manual is unclear, or downright
incorrect, or if the language needs to be improved, please also send a
note.

Send your bug report to:

@center @samp{bug-shishi@@josefsson.org}

@node Contributing
@section Contributing
@cindex Contributing
@cindex Hacking

If you want to submit a patch for inclusion -- from solve a typo you
discovered, up to adding support for a new feature -- you should
submit it as a bug report (@pxref{Bug Reports}).  There are some
things that you can do to increase the chances for it to be included
in the official package.

Unless your patch is very small (say, under 10 lines) we require that
you assign the copyright of your work to the Free Software Foundation.
This is to protect the freedom of the project.  If you have not
already signed papers, we will send you the necessary information when
you submit your contribution.

For contributions that doesn't consist of actual programming code, the
only guidelines are common sense.  Use it.

For code contributions, a number of style guides will help you:

@itemize @bullet

@item Coding Style.
Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
standards}).

If you normally code using another coding standard, there is no
problem, but you should use @samp{indent} to reformat the code
(@pxref{top, GNU Indent,, indent}) before submitting your work.

@item Use the unified diff format @samp{diff -u}.

@item Return errors.
The only valid reason for ever aborting the execution of the program
is due to memory allocation errors, but for that you should call
@samp{shishi_xalloc_die} to allow the application to recover if it
wants to.

@item Design with thread safety in mind.
Don't use global variables.  Don't even write to per-handle global
variables unless the documented behaviour of the function you write is
to write to the per-handle global variable.

@item Avoid using the C math library.
It causes problems for embedded implementations, and in most
situations it is very easy to avoid using it.

@item Document your functions.
Use comments before each function headers, that, if properly
formatted, are extracted into Texinfo manuals and GTK-DOC web pages.

@item Supply a ChangeLog and NEWS entries, where appropriate.

@end itemize

@c **********************************************************
@c ********************  User Manual  **********************
@c **********************************************************
@node User Manual
@chapter User Manual
@cindex End-user Shishi usage

Usually Shishi interacts with you to get some initial authentication
information like a password, and then contacts a server to receive a
so called ticket granting ticket.  From now on, you rarely interacts
with Shishi directly.  Applications that needs security services
instruct the Shishi library to use the ticket granting ticket to get
new tickets for various servers.  An example could be if you log on to
a host remotely via @samp{telnet}.  The host usually requires
authentication before permitting you in.  The @samp{telnet} client
uses the ticket granting ticket to get a ticket for the server, and
then use this ticket to authenticate you against the server (typically
the server is also authenticated to you).  You perform the initial
authentication by typing @command{shishi} at the prompt.  Sometimes it
is necessary to supply options telling Shishi what your principal name
(user name in the Kerberos realm) or realm is.  In the example, I
specify the client name @code{simon@@JOSEFSSON.ORG}.

@example
$ shishi simon@@JOSEFSSON.ORG
Enter password for `simon@@JOSEFSSON.ORG':
simon@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:44:49 2003
Endtime:        Fri Aug 15 05:01:29 2003
Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   INITIAL (512)
$ 
@end example

As you can see, Shishi also prints a short description of the ticket
received.

A logical next step is to display all tickets you have received (by
the way, the tickets are usually stored as text in
@file{~/.shishi/tickets}).  This is achieved by typing @command{shishi
--list}.

@example
$ shishi --list
Tickets in `/home/jas/.shishi/tickets':
                                                                                
jas@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:49:46 2003
Endtime:        Fri Aug 15 05:06:26 2003
Server:         krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
Ticket flags:   INITIAL (512)
                                                                                
jas@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:49:46 2003
Starttime:      Fri Aug 15 04:49:49 2003
Endtime:        Fri Aug 15 05:06:26 2003
Server:         host/latte.josefsson.org key des-cbc-md5 (3)
Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
                                                                                
2 tickets found.
$
@end example

As you can see, I had a ticket for the server
@samp{host/latte.josefsson.org} which was generated by
@samp{telnet}:ing to that host.

If, for some reason, you want to manually get a ticket for a specific
server, you can use the @command{shishi --server-name} command.
Normally, however, the application that uses Shishi will take care of
getting a ticket for the appropriate server, so you normally wouldn't
need this command.

@example
$ shishi --server-name=user/billg --encryption-type=des-cbc-md4
jas@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:49:46 2003
Starttime:      Fri Aug 15 04:54:33 2003
Endtime:        Fri Aug 15 05:06:26 2003
Server:         user/billg key des-cbc-md4 (2)
Ticket key:     des-cbc-md4 (2) protected by des-cbc-md5 (3)
$
@end example

As you can see, I acquired a ticket for @samp{user/billg} with a
@samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key
specified with the @samp{--encryption-type} parameter.

To wrap up this introduction, lets see how you can remove tickets.
You may want to do this if you leave your terminal for lunch or
similar, and don't want someone to be able to copy the file and then
use your credentials.  Note that this only destroy the tickets
locally, it does not contact any server and tell it that these
credentials are no longer valid.  So if someone stole your ticket
file, you must contact your administrator and have them reset your
account, simply using this parameter is not sufficient.

@example
$ shishi --server-name=imap/latte.josefsson.org --destroy
1 ticket removed.
$ shishi --server-name=foobar --destroy
No tickets removed.
$ shishi --destroy
3 tickets removed.
$
@end example

Since the @samp{--server-name} parameter takes a long to type, it is
possible to type the server name directly, after the client name.  The
following example demonstrate a AS-REQ followed by a TGS-REQ for a
specific server (assuming you did not have any tickets from the
start).

@example
$ src/shishi simon@@latte.josefsson.org imap/latte.josefsson.org
Enter password for `simon@@latte.josefsson.org':
simon@@latte.josefsson.org:
Acquired:       Wed Aug 27 17:21:06 2003
Expires:        Wed Aug 27 17:37:46 2003
Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE (12)
$
@end example

Refer to the reference manual for all available parameters
(@pxref{Parameters for shishi}).  The rest of this section contains
description of more specialized usage modes that can be ignored by
most users.

@section Proxiable and Proxy Tickets

At times it may be necessary for a principal to allow a service to
perform an operation on its behalf. The service must be able to take
on the identity of the client, but only for a particular purpose. A
principal can allow a service to take on the principal's identity for
a particular purpose by granting it a proxy.

The process of granting a proxy using the proxy and proxiable flags is
used to provide credentials for use with specific services. Though
conceptually also a proxy, users wishing to delegate their identity in
a form usable for all purpose MUST use the ticket forwarding mechanism
described in the next section to forward a ticket-granting ticket.

The PROXIABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
When set, this flag tells the ticket-granting server that it is OK to
issue a new ticket (but not a ticket-granting ticket) with a different
network address based on this ticket. This flag is set if requested by
the client on initial authentication. By default, the client will
request that it be set when requesting a ticket-granting ticket, and
reset when requesting any other ticket.

This flag allows a client to pass a proxy to a server to perform a
remote request on its behalf (e.g. a print service client can give the
print server a proxy to access the client's files on a particular file
server in order to satisfy a print request).

In order to complicate the use of stolen credentials, Kerberos tickets
are usually valid from only those network addresses specifically
included in the ticket[4]. When granting a proxy, the client MUST
specify the new network address from which the proxy is to be used, or
indicate that the proxy is to be issued for use from any address.

The PROXY flag is set in a ticket by the TGS when it issues a proxy
ticket.  Application servers MAY check this flag and at their option
they MAY require additional authentication from the agent presenting
the proxy in order to provide an audit trail.

Here is how you would acquire a PROXY ticket for the service
@samp{imap/latte.josefsson.org}:

@example
$ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
Enter password for `jas@@JOSEFSSON.ORG':
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:02:35 2003
Starttime:      Mon Sep  8 20:02:36 2003
Endtime:        Tue Sep  9 04:02:35 2003
Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   PROXY (16)
$
@end example

As you noticed, this asked for your password.  The reason is that
proxy tickets must be acquired using a proxiable ticket granting
ticket, which was not present.  If you often need to get proxy
tickets, you may acquire a proxiable ticket granting ticket from the
start:

@example
$ shishi --proxiable
Enter password for `jas@@JOSEFSSON.ORG':
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:04:27 2003
Endtime:        Tue Sep  9 04:04:27 2003
Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   PROXIABLE INITIAL (520)
@end example

Then you should be able to acquire proxy tickets based on that ticket
granting ticket, as follows:

@example
$ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:04:27 2003
Starttime:      Mon Sep  8 20:04:32 2003
Endtime:        Tue Sep  9 04:04:27 2003
Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   PROXY (16)
$
@end example

@section Forwardable and Forwarded Tickets

Authentication forwarding is an instance of a proxy where the service
that is granted is complete use of the client's identity. An example
where it might be used is when a user logs in to a remote system and
wants authentication to work from that system as if the login were
local.

The FORWARDABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
The FORWARDABLE flag has an interpretation similar to that of the
PROXIABLE flag, except ticket-granting tickets may also be issued with
different network addresses. This flag is reset by default, but users
MAY request that it be set by setting the FORWARDABLE option in the AS
request when they request their initial ticket-granting ticket.

This flag allows for authentication forwarding without requiring the
user to enter a password again. If the flag is not set, then
authentication forwarding is not permitted, but the same result can
still be achieved if the user engages in the AS exchange specifying
the requested network addresses and supplies a password.

The FORWARDED flag is set by the TGS when a client presents a ticket
with the FORWARDABLE flag set and requests a forwarded ticket by
specifying the FORWARDED KDC option and supplying a set of addresses
for the new ticket. It is also set in all tickets issued based on
tickets with the FORWARDED flag set. Application servers may choose to
process FORWARDED tickets differently than non-FORWARDED tickets.

If addressless tickets are forwarded from one system to another,
clients SHOULD still use this option to obtain a new TGT in order to
have different session keys on the different systems.

Here is how you would acquire a FORWARDED ticket for the service
@samp{host/latte.josefsson.org}:

@example
$ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
Enter password for `jas@@JOSEFSSON.ORG':
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:07:11 2003
Starttime:      Mon Sep  8 20:07:12 2003
Endtime:        Tue Sep  9 04:07:11 2003
Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   FORWARDED (4)
$
@end example

As you noticed, this asked for your password.  The reason is that
forwarded tickets must be acquired using a forwardable ticket granting
ticket, which was not present.  If you often need to get forwarded
tickets, you may acquire a forwardable ticket granting ticket from the
start:

@example
$ shishi --forwardable
Enter password for `jas@@JOSEFSSON.ORG':
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:08:53 2003
Endtime:        Tue Sep  9 04:08:53 2003
Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   FORWARDABLE INITIAL (514)
$
@end example

Then you should be able to acquire forwarded tickets based on that
ticket granting ticket, as follows:

@example
$ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:08:53 2003
Starttime:      Mon Sep  8 20:08:57 2003
Endtime:        Tue Sep  9 04:08:53 2003
Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   FORWARDED (4)
$
@end example


@c **********************************************************
@c ****************  Administration Manual  *****************
@c **********************************************************
@node Administration Manual
@chapter Administration Manual

Here you will learn how to set up, run and maintain the Shishi
Kerberos server.  Kerberos is incompatible with the standard Unix
@file{/etc/passwd} password database@footnote{And besides, Shishi is
intended to work on non-Unix platforms as well.}, therefor the first
step will be to create a Kerberos user database.  Shishi's user
database system is called Shisa.  Once Shisa is configured, you can
then start the server and begin issuing Kerberos tickets to your
users.  The Shishi server is called @file{shishid}.  After getting the
server up and running, we discuss how you can set up multiple Kerberos
servers, to increase availability or offer load-balancing.  Finally,
we include some information intended for developers, that will enable
you to customize Shisa to use an external user database, such as a
LDAP server or SQL database.

@menu
* Introduction to Shisa::       Explanation of the Shishi user database.
* Configuring Shisa::           Define the user database in Shisa.
* Using Shisa::                 How to add realms and principals to database.
* Starting Shishid::            Issue Kerberos tickets to your users.
* Configuring DNS for KDC::     Placing the KDC address in DNS is useful.
* Kerberos via TLS::            How to setup Shishi to use TLS.
* Multiple servers::            High availability and load-balancing.
* Developer information::       Writing your own Shisa database backend.
@end menu

@node Introduction to Shisa
@section Introduction to Shisa

The user database part of Shishi is called Shisa.  The Shisa library
is independent of the core Shishi library.  Shisa is responsible for
storing the name of your realms, the name of your principals (users),
accounting information for the users (i.e., when each account start to
be valid and when it expire), and the cryptographic keys each user
have.  Some Kerberos internal data can also be stored, such as the key
version number, the last dates for when various ticket requests were
made, the cryptographic salt, string-to-key parameters and password
for each user.  Not all information need to be stored.  For example,
in some situations it is prudent to leave the password field empty, so
that somebody who manage to steal the user database will only be able
to compromise your system, and not other systems were your user may
have re-used the same password.  On the other hand, you may already
store the password in your customized database, in which case being
able to change it via the Shisa interface can be useful.

Shisa is a small (a few thousand lines of C code) standalone
library.  Shisa does not depend on the Shishi library.  Because a user
database with passwords may be useful for other applications as well
(e.g., GNU SASL), it may be separated into its own
project later on.  You should keep this in mind, so that you don't
consider writing a Shisa backend for your own database a purely Shishi
specific project.  You may, for example, chose to use the Shisa
interface in your own applications to have a simple interface to your
user database.  Your experience and feedback is appreciated if you
chose to explore this.

Note that the Shisa database does not expose everything you may want
to know about a user, such as its full human name, telephone number or
even the user's login account name or home directory.  It only store
what is needed to authenticate a peer claiming to be an entity.  Thus
it does not make sense to replace your current user database or
@file{/etc/passwd} with data derived from the Shisa database.
Instead, it is intended that you write a Shisa backend that export
@i{some} of the information stored in your user database.  You may be
able to replace some existing functionality, such as the password
field in @file{/etc/passwd} with a Kerberos PAM module, but there is
no requirement for doing so.

@node Configuring Shisa
@section Configuring Shisa

The configuration file for Shisa is typically stored in
@file{/usr/local/etc/shishi/shisa.conf}.  You do not have to configure
this file, the defaults should be acceptable to first-time users.  The
file is used to define where you user database reside, and some
options such as making the database read-only or whether errors
detected when accessing the database should be ignored.  (The latter
may be useful if the server is a remote LDAP server that may
be unavailable, and you want to fail over to a local copy of the
database.)

The default will store the user database using directories and files,
rooted by default in @file{/usr/local/var/shishi}.  You may use
standard file permission settings to control access to the directory
hierarchy.  It is strongly recommended to restrict access to the
directory.  Storing the directory on local storage (i.e., hard disk or
removal media) is recommended.  We discourage placing the database on
a network file system, but realize it can be useful in some situations
(@pxref{Multiple servers}).

See the reference manual (@pxref{Shisa Configuration}) for the details
of the configuration file.  Again, you are not expected to need to
modify anything unless you are an experienced Shishi administrator.

@node Using Shisa
@section Using Shisa

There is a command line interface to the Shisa library, aptly named
@file{shisa}.  You will use this tool to add, remove and change
information stored in the database about realms, principals and keys.
The tool can also be used to ``dump'' all information in the database,
for backup or debugging purposes.  (Currently the output format cannot
be read by any tool, but functionality to do this will be added in the
future, possibly as a read-only file-based Shisa database backend.)

The reference manual (@pxref{Parameters for shisa}) explains all
parameters, but here we will give you a walk-through of the typical
uses of the tool.

Installing Shishi usually create a realm with two principals; one
ticket granting ticket for the realm, and one host key for the server.
This is what you typically need to get started, but it doesn't serve
our purposes.  So we start by removing the principals and the realm.
To do that, we need to figure out the name of the realm.  The
@samp{--list} or @samp{--dump} parameters can be used for this.  (Most
``long'' parameters, like @samp{--dump}, have shorter names as well,
in this case @samp{-d}, @ref{Parameters for shisa}).

@example
jas@@latte:~$ shisa -d
latte
        krbtgt/latte
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                        Salt lattekrbtgt/latte.
        host/latte
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                        Salt lattehost/latte.
jas@@latte:~$
@end example

The realm names are printed at column 0, the principal names are
indented with one @samp{TAB} character (aka @samp{\t} or ASCII 0x09
Horizontal Tabulation), and the information about each principal are
indented with two @samp{TAB} characters.  The above output means that
there is one realm @samp{latte} with two principals;
@samp{krbtgt/latte} (which is used to authenticate Kerberos ticket
requests) and @samp{host/latte} (used to authenticate host-based
applications like Telnet).  They were created during @samp{make
install} on a host called @samp{latte}.

If the installation did not create a default database for you, you
might get an error similar to the following.

@example
jas@@latte:~$ shisa -d
shisa: Cannot initialize `file' database backend.
Location `/usr/local/var/shishi' and options `N/A'.
shisa: Initialization failed:
Shisa database could not be opened.
jas@@latte:~$
@end example

This indicate the database do not exist.  For a file database, you can
create it by simply creating the directory, as follows.  Note the
access permission change with @samp{chmod}.  Typically the @samp{root}
user would own the files, but as these examples demonstrate, setting
up a Kerberos server does not require root access.  Indeed, it may be
prudent to run all Shishi applications as a special non-@samp{root}
user, and have all Shishi related files owned by that user, so that
any security vulnerabilities does not lead to a system compromise.
(However, if the user database is stolen, system compromises of other
systems may be possible if you use, e.g., Kerberos Telnet.)

@example
jas@@latte:~$ mkdir /usr/local/var/shishi
jas@@latte:~$ chmod go-rwx /usr/local/var/shishi
@end example

Back to the first example, where you have a realm @samp{latte} with
some principals.  We want to remove the realm to demonstrate how you
create the realm from scratch.  (Of course, you can have more than one
realm in the database, but for this example we assume you want to set
up a realm named the same as Shishi guessed you would name it, so the
existing realm need to be removed first.)  The @samp{--remove} (short
form @samp{-r}) parameter is used for this purpose, as follows.

@example
jas@@latte:~$ shisa -r latte host/latte
Removing principal `host/latte@@latte'...
Removing principal `host/latte@@latte'...done
jas@@latte:~$ shisa -r latte krbtgt/latte
Removing principal `krbtgt/latte@@latte'...
Removing principal `krbtgt/latte@@latte'...done
jas@@latte:~$ shisa -r latte
Removing realm `latte'...
Removing realm `latte'...done
jas@@latte:~$
@end example

You may be asking yourself ``What if the realm has many more
principals?''.  If you fear manual labor (or a small @samp{sed}
script, recall the format of @samp{--list}?), don't worry, there is a
@samp{--force} (short form @samp{-f}) flag.  Use with care.  Here is a
faster way to do the above:

@example
jas@@latte:~$ shisa -r latte -f
Removing principal `krbtgt/latte@@latte'...
Removing principal `krbtgt/latte@@latte'...done
Removing principal `host/latte@@latte'...
Removing principal `host/latte@@latte'...done
Removing realm `latte'...
Removing realm `latte'...done
jas@@latte:~$
@end example

You should now have a working, but empty, Shisa database.  Let's set
up the realm manually, step by step.  The first step is to decide on
name for your realm.  The full story is explained elsewhere
(@pxref{Realm and Principal Naming}) but the short story is to take
your DNS domain name and translate it to upper case.  For
example, if your organization uses @code{example.org} it is a good
idea to use @code{EXAMPLE.ORG} as the name of your Kerberos realm.
We'll use @code{EXAMPLE.ORG} as the realm name in these examples.
Let's create the realm.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG
Adding realm `EXAMPLE.ORG'...
Adding realm `EXAMPLE.ORG'...done
jas@@latte:~$
@end example

Currently, there are no properties associated with entire realms.  In
the future, it may be possible to set a default realm-wide password
expiry policy or similar.  Each realm normally have one principal that
is used for authenticating against the ``ticket granting service'' on
the Kerberos server with a ticket instead of using the password.  This
is used by the user when she acquire a ticket for servers.  This
principal must look like @samp{krbtgt/REALM} (@pxref{krbtgt,,Name of
the TGS}).  Let's create it.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG krbtgt/EXAMPLE.ORG
Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...
Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...done
jas@@latte:~$
@end example

Now that wasn't difficult, although not very satisfying either.  What
does adding a principal mean?  The name is created, obviously, but it
also mean setting a few values in the database.  Let's view the entry
to find out which values.

@example
jas@@latte:~$ shisa -d
EXAMPLE.ORG
        krbtgt/EXAMPLE.ORG
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                        Salt EXAMPLE.ORGkrbtgt/EXAMPLE.ORG.
jas@@latte:~$
@end example

To use host based security services like SSH or Telnet with
Kerberos, each host must have a key shared between the host and the
KDC.  The key is typically stored in
@file{/usr/local/etc/shishi/shishi.keys}.  We assume your server is
called @samp{mail.example.org} and create the principal.  To
illustrate a new parameter, we also set the specific algorithm to use
by using the @samp{--encryption-type} (short form @samp{-E})
parameter.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG host/mail.example.org -E des3
Adding principal `host/mail.example.org@@EXAMPLE.ORG'...
Adding principal `host/mail.example.org@@EXAMPLE.ORG'...done
jas@@latte:~$
@end example

To export the key, there is another Shisa parameter @samp{--keys} that
will print the key in a format that is recognized by Shishi.  Let's
use it to print the host key.

@example
jas@@latte:~$ shisa -d --keys EXAMPLE.ORG host/mail.example.org
EXAMPLE.ORG
        host/mail.example.org
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype des3-cbc-sha1-kd (0x10, 16).
-----BEGIN SHISHI KEY-----
Keytype: 16 (des3-cbc-sha1-kd)
Principal: host/mail.example.org
Realm: EXAMPLE.ORG
 
iQdA8hxdvOUHZNliZJv7noM02rXHV8gq
-----END SHISHI KEY-----
                        Salt EXAMPLE.ORGhost/mail.example.org.
jas@@latte:~$
@end example

So to set up the host, simply redirect output to the host key file.

@example
jas@@latte:~$ shisa -d --keys EXAMPLE.ORG \
     host/mail.example.org > /usr/local/etc/shishi/shishi.keys
jas@@latte:~$
@end example

The next logical step is to create a principal for some user, so you
can use your password to get a Ticket Granting Ticket via the
Authentication Service (AS) from the KDC, and then use the Ticket
Granting Service (TGS) from the KDC to get a ticket for a specific
host, and then send that ticket to the host to authenticate yourself.
Creating this end-user principle is slightly different from the
earlier steps, because you want the key to be derived from a password
instead of being a random key.  The @samp{--password} parameter
indicate this.  This make the tool ask you for the password.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG simon --password
Password for `simon@@EXAMPLE.ORG':
Adding principal `simon@@EXAMPLE.ORG'...
Adding principal `simon@@EXAMPLE.ORG'...done
jas@@latte:~$
@end example

The only special thing about this principal now is that it has a
@code{password} field set in the database.

@example
jas@@latte:~$ shisa -d EXAMPLE.ORG simon --keys
EXAMPLE.ORG
        simon
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
-----BEGIN SHISHI KEY-----
Keytype: 18 (aes256-cts-hmac-sha1-96)
Principal: simon
Realm: EXAMPLE.ORG
 
Ja7ciNtrAI3gtodLaVDQ5zhcH58ffk0kS5tGAM7ILvM=
-----END SHISHI KEY-----
                        Salt EXAMPLE.ORGsimon.
                        Password foo.
jas@@latte:~$
@end example

You should now be ready to start the KDC, which is explained in the
next section (@pxref{Starting Shishid}), and get tickets as explained
earlier (@pxref{User Manual}).

@node Starting Shishid
@section Starting Shishid

The Shishi server, or Key Distribution Center (KDC), is called
Shishid.  Shishid is responsible for listening on UDP and TCP ports
for Kerberos requests.  Currently it can handle initial ticket
requests (Authentication Service, or AS), typically authenticated with
keys derived from passwords, and subsequent ticket requests (Ticket
Granting Service, or TGS), typically authenticated with the key
acquired during an AS exchange.

Currently there is very little configuration available, the only
variables are which ports the server should listen on and an optional
user name to @code{setuid} into after successfully listening to the
ports.

By default, Shishid listens on the @samp{kerberos} service port
(typically translated to 88 via @file{/etc/services}) on the UDP and
TCP transports via IPv4 and (if your machine support it) IPv6 on all
interfaces on your machine.  Here is a typical startup.

@example
latte:/home/jas/src/shishi# /usr/local/sbin/shishid
Initializing GNUTLS...
Initializing GNUTLS...done
Listening on IPv4:*:kerberos/udp...done
Listening on IPv4:*:kerberos/tcp...done
Listening on IPv6:*:kerberos/udp...failed
socket: Address family not supported by protocol
Listening on IPv6:*:kerberos/tcp...failed
socket: Address family not supported by protocol
Listening on 2 ports...
@end example

Running as root is not recommended.  Any security problem in shishid
and your host may be compromised.  Therefor, we recommend using the
@samp{--setuid} parameter, as follows.

@example
latte:/home/jas/src/shishi# /usr/local/sbin/shishid --setuid=jas
Initializing GNUTLS...
Initializing GNUTLS...done
Listening on IPv4:*:kerberos/udp...done
Listening on IPv4:*:kerberos/tcp...done
Listening on IPv6:*:kerberos/udp...failed
socket: Address family not supported by protocol
Listening on IPv6:*:kerberos/tcp...failed
socket: Address family not supported by protocol
Listening on 2 ports...
User identity set to `jas' (22541)...
@end example

An alternative is to run shishid on an alternative port as a
non-privileged user.  To continue the example of setting up the
@code{EXAMPLE.ORG} realm as a non-privileged user from the preceding
section, we start the server listen on port 4711 via UDP on IPv4.

@example
jas@@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/udp
Initializing GNUTLS...
Initializing GNUTLS...done
Listening on *:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on *:4711/tcp socket 4
@end example

If you have set up the Shisa database as in the previous example, you
can now acquire tickets as follows.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
   simon@@EXAMPLE.ORG
Enter password for `simon@@EXAMPLE.ORG':
simon@@EXAMPLE.ORG:
Authtime:       Fri Dec 12 01:41:01 2003
Endtime:        Fri Dec 12 01:57:41 2003
Server:         krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE RENEWABLE INITIAL (12)
jas@@latte:~$
@end example

The output from Shishid on a successful invocation would look like:

@example
shishid: Has 131 bytes from *:4711/udp on socket 4
shishid: Processing 131 from *:4711/udp on socket 4
shishid: Trying AS-REQ
shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for *:4711/udp on socket 4
shishid: Sending 511 bytes to *:4711/udp socket 4 via UDP
shishid: Listening on *:4711/udp socket 4
@end example

You may use the '-v' parameter for Shishid and Shishi to generate more
debugging information.

To illustrate what an application, such as the Shishi patched versions
of GNU lsh or Telnet from GNU InetUtils, would do
when contacting the host @samp{mail.example.org} we illustrate using
the TGS service as well.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
   simon@@EXAMPLE.ORG host/mail.example.org
simon@@EXAMPLE.ORG:
Authtime:       Fri Dec 12 01:46:54 2003
Endtime:        Fri Dec 12 02:03:34 2003
Server:         host/mail.example.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE (45398796)
jas@@latte:~$
@end example

This conclude our walk-through of setting up a new Kerberos realm
using Shishi.  It is quite likely that one or more steps failed, and
if so we encourage you to debug it and submit a patch, or at least
report it as a problem.  Heck, even letting us know if you got this
far would be of interest.  @xref{Bug Reports}.

@node Configuring DNS for KDC
@section Configuring DNS for KDC

Making sure the configuration files on all hosts running Shishi
clients include the addresses of your server is tedious.  If the
configuration files do not mention the KDC address for a realm, Shishi
will try to look up the information from DNS.  In order for Shishi to
find that information, you need to add the information to DNS.  For
this to work well, you need to set up a DNS zone with the same name as
your Kerberos realm.  The easiest is if you own the publicly visible
DNS name, such as @samp{example.org} if your realm is
@samp{EXAMPLE.ORG}, but you can set up an internal DNS server with the
information for your realm only.  If this is done, you do not need to
keep configuration files updated for the KDC addressing information.

@subsection DNS vs. Kerberos - Case Sensitivity of Realm Names

In Kerberos, realm names are case sensitive.  While it is strongly
encouraged that all realm names be all upper case this recommendation
has not been adopted by all sites.  Some sites use all lower case
names and other use mixed case.  DNS on the other hand is case
insensitive for queries but is case preserving for responses to TXT
queries.  Since "MYREALM", "myrealm", and "MyRealm" are all different
it is necessary that only one of the possible combinations of upper
and lower case characters be used.  This restriction may be lifted in
the future as the DNS naming scheme is expanded to support non-ASCII
names.

@subsection Overview - KDC location information

KDC location information is to be stored using the DNS SRV RR [RFC
2052].  The format of this RR is as follows:

Service.Proto.Realm TTL Class SRV Priority Weight Port Target

The Service name for Kerberos is always "_kerberos".

The Proto can be either "_udp", "_tcp", or "_tls._tcp".  If these SRV
records are to be used, a "_udp" record MUST be included.  If the
Kerberos implementation supports TCP transport, a "_tcp" record MUST
be included.  When using "_tcp" with "_kerberos", this indicates a
"raw" TCP connection without any additional encapsulation.  A
"_tls._tcp" record MUST be specified for all Kerberos implementations
that support communication with the KDC across TCP sockets
encapsulated using TLS [RFC2246] (@pxref{STARTTLS protected KDC exchanges}).

The Realm is the Kerberos realm that this record corresponds to.

TTL, Class, SRV, Priority, Weight, and Target have the standard
meaning as defined in RFC 2052.

As per RFC 2052 the Port number should be the value assigned to
"kerberos" by the Internet Assigned Number Authority (88).

@subsection Example - KDC location information

These are DNS records for a Kerberos realm ASDF.COM.  It has two
Kerberos servers, kdc1.asdf.com and kdc2.asdf.com.  Queries should be
directed to kdc1.asdf.com first as per the specified priority.
Weights are not used in these records.

@example
_kerberos._udp.ASDF.COM.        IN      SRV     0 0 88 kdc1.asdf.com.
_kerberos._udp.ASDF.COM.        IN      SRV     1 0 88 kdc2.asdf.com.
_kerberos._tcp.ASDF.COM.        IN      SRV     0 0 88 kdc1.asdf.com.
_kerberos._tcp.ASDF.COM.        IN      SRV     1 0 88 kdc2.asdf.com.
_kerberos._tls._tcp.ASDF.COM.   IN      SRV     0 0 88 kdc1.asdf.com.
_kerberos._tls._tcp.ASDF.COM.   IN      SRV     1 0 88 kdc2.asdf.com.
@end example

@subsection Security considerations

As DNS is deployed today, it is an unsecure service.  Thus the infor-
mation returned by it cannot be trusted.

Current practice for REALM to KDC mapping is to use hostnames to
indicate KDC hosts (stored in some implementation-dependent location,
but generally a local config file).  These hostnames are vulnerable
to the standard set of DNS attacks (denial of service, spoofed
entries, etc).  The design of the Kerberos protocol limits attacks of
this sort to denial of service.  However, the use of SRV records does
not change this attack in any way.  They have the same vulnerabilities
that already exist in the common practice of using hostnames for
KDC locations.

Implementations SHOULD provide a way of specifying this information
locally without the use of DNS.  However, to make this feature
worthwhile a lack of any configuration information on a client should
be interpretted as permission to use DNS.

@node Kerberos via TLS
@section Kerberos via TLS
@cindex GNUTLS
@cindex TLS
@cindex STARTTLS

If Shishi is built with support for GNUTLS, the messages exchanged
between clients and Shishid can be protected with TLS.  TLS is only
available over TCP connections.  A full discussion of the features TLS
have is out of scope here, but in short it means the communication is
integrity and privacy protected, and that users can use OpenPGP, X.509
or SRP (i.e., any mechanism supported by TLS) to authenticate
themselves to the Kerberos server.  For details on the implementation,
@xref{STARTTLS protected KDC exchanges}.

@subsection Setting up TLS resume
@cindex tls resume

Resuming earlier TLS session is supported and enabled by default.
This improves the speed of the TLS handshake, because results from
earlier negotiations can be re-used.  Currently the TLS resume
database is stored in memory (in constract to storing it on disk), in
both the client and in the server.  Because the server typically runs
for a long time, this is not a problem for that side.  The client is
typically not a long-running process though; the client usually is
invoked as part of applications like @samp{telnet} or @samp{login}.
However, because each use of the client library typically result in a
ticket, which is stored on disk and re-used by later processes, this
is likely not a serious problem because the number of different
tickets required by a user is usually quite small.  For the client,
TLS resume is typically only useful when you perform an initial
authentication (using a password) followed by a ticket request for a
service, in the same process.

You can configure the server, @samp{shishid} to never use TLS resume,
or to increase or decrease the number of distinct TLS connections that
can be resumed before they are garbage collected, see the
@samp{--resume-limit} parameter (@pxref{Parameters for shishid}).

@subsection Setting up Anonymous TLS
@cindex anonymous tls
@cindex Diffie Hellman key exchange

Anonymous TLS is the simplest to set up and use.  In fact, only the
client need to be informed that your KDC support TLS.  This can be
done in the configuration file with the @samp{/tls} parameter for
@samp{kdc-realm} (@pxref{realm-kdc,, Shishi Configuration}), or by
placing the KDC address in DNS using the @samp{_tls} SRV record
(@pxref{Configuring DNS for KDC}).

Let's start Shishid, listening on a TCP socket.  TLS require TCP.  TCP
sockets are automatically upgraded to TLS if the client request it.

@example
jas@@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/tcp
Initializing GNUTLS...done
Listening on IPv4:*:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on IPv4:*:4711/tcp socket 4
@end example

Let's use the client to talk with it, using TLS.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls \
    simon@@EXAMPLE.ORG
Enter password for `simon@@EXAMPLE.ORG':
simon@@EXAMPLE.ORG:
Authtime:       Tue Dec 16 05:20:47 2003
Endtime:        Tue Dec 16 05:37:27 2003
Server:         krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE (12)
jas@@latte:~$
@end example

On success, the server will print the following debug information.

@example
shishid: Accepted socket 6 from socket 4 as IPv4:*:4711/tcp peer 127.0.0.1
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 4 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying STARTTLS
shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `Anon DH', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
shishid: TLS anonymous authentication with 1024 bit Diffie-Hellman
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 131 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Processing 131 from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying AS-REQ
shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Sending 511 bytes to IPv4:*:4711/tcp peer 127.0.0.1 socket 6 via TLS
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Peer IPv4:*:4711/tcp peer 127.0.0.1 disconnected on socket 6
shishid: Closing IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Listening on IPv4:*:4711/tcp socket 4
@end example

@subsection Setting up X.509 authenticated TLS
@cindex X.509 authentication
@cindex authenticated tls
@cindex client authentication
@cindex server authentication
@cindex certificate authority (CA)

Setting up X.509 authentication is slightly more complicated than
anonymous authentication.  You need a X.509 certificate authority
(CA) that can generate certificates for your Kerberos server
and Kerberos clients.  It is often easiest to setup the CA
yourself.  Managing a CA can be a daunting task, and we only
give the bare essentials to get things up and running.  We suggest
that you study the relevant literature.  As a first step beyond this
introduction, you may wish to explore more secure forms of key storage
than storing them unencrypted on disk.

The following three sections describe how you create the CA,
KDC certificate, and client certificates.  You can use any tool you
like for this task, as long as they generate X.509 (PKIX) certificates
in PEM format and RSA keys in PKCS#1 format.  Here we use
@file{certtool} that come with GNUTLS, which is widely
available.  We conclude by discussing how you use these certificates
in the KDC and in the Shishi client.

@subsubsection Create a Kerberos Certificate Authority

First create a CA key.

@example
jas@@latte:~$ certtool --generate-privkey \
   --outfile /usr/local/etc/shishi/shishi.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@@latte:~$
@end example

Then create the CA certificate.  Use whatever details you
prefer.

@example
jas@@latte:~$ certtool --generate-self-signed \
   --load-privkey /usr/local/etc/shishi/shishi.key \
   --outfile /usr/local/etc/shishi/shishi.cert
Generating a self signed certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example CA
Organizational unit name:
Locality name:
State or province name:
Common name: CA
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
 
 
Activation/Expiration time.
The generated certificate will expire in (days): 180
 
 
Extensions.
Does the certificate belong to an authority? (Y/N): y
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
 
 
X.509 certificate info:
 
Version: 3
Serial Number (hex): 00
Validity:
        Not Before: Sun Dec 21 10:59:00 2003
        Not After: Fri Jun 18 11:59:00 2004
Subject: C=SE,O=Shishi Example CA,CN=CA
Subject Public Key Info:
        Public Key Algorithm: RSA
 
X.509 Extensions:
        Basic Constraints: (critical)
                CA:TRUE
 
Is the above information ok? (Y/N): y
 
 
Signing certificate...
jas@@latte:~$
@end example

@subsubsection Create a Kerberos KDC Certificate

First create the key for the KDC.

@example
jas@@latte:~$ certtool --generate-privkey \
   --outfile /usr/local/etc/shishi/shishid.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@@latte:~$
@end example

Then create actual KDC certificate, signed by the CA
certificate created in the previous step.

@example
jas@@latte:~$ certtool --generate-certificate \
   --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
   --load-ca-privkey /usr/local/etc/shishi/shishi.key \
   --load-privkey /usr/local/etc/shishi/shishid.key \
   --outfile /usr/local/etc/shishi/shishid.cert
Generating a signed certificate...
Loading CA's private key...
Loading CA's certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example KDC
Organizational unit name:
Locality name:
State or province name:
Common name: KDC
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
 
 
Activation/Expiration time.
The generated certificate will expire in (days): 180
 
 
Extensions.
Does the certificate belong to an authority? (Y/N): n
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
 
 
X.509 certificate info:
 
Version: 3
Serial Number (hex): 00
Validity:
        Not Before: Sun Dec 21 11:02:00 2003
        Not After: Fri Jun 18 12:02:00 2004
Subject: C=SE,O=Shishi Example KDC,CN=KDC
Subject Public Key Info:
        Public Key Algorithm: RSA
 
X.509 Extensions:
        Basic Constraints: (critical)
                CA:FALSE
 
Is the above information ok? (Y/N): y
 
 
Signing certificate...
jas@@latte:~$
@end example

@subsubsection Create a Kerberos Client Certificate

First create the key for the client.

@example
jas@@latte:~$ certtool --generate-privkey \
   --outfile ~/.shishi/client.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@@latte:~$
@end example

Then create the client certificate, signed by the CA.  An
alternative would be to have the KDC sign the client certificates.

@example
jas@@latte:~$ certtool --generate-certificate \
   --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
   --load-ca-privkey /usr/local/etc/shishi/shishi.key \
   --load-privkey ~/.shishi/client.key \
   --outfile ~/.shishi/client.certs
Generating a signed certificate...
Loading CA's private key...
Loading CA's certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example Client
Organizational unit name:
Locality name:
State or province name:
Common name: Client
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
 
 
Activation/Expiration time.
The generated certificate will expire in (days): 180
 
 
Extensions.
Does the certificate belong to an authority? (Y/N): n
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
 
 
X.509 certificate info:
 
Version: 3
Serial Number (hex): 00
Validity:
        Not Before: Sun Dec 21 11:04:00 2003
        Not After: Fri Jun 18 12:04:00 2004
Subject: C=SE,O=Shishi Example Client,CN=Client
Subject Public Key Info:
        Public Key Algorithm: RSA
 
X.509 Extensions:
        Basic Constraints: (critical)
                CA:FALSE
 
Is the above information ok? (Y/N): y
 
 
Signing certificate...
jas@@latte:~$
@end example

@subsubsection Starting KDC with X.509 authentication support

The KDC need the CA certificate (to verify client
certificates) and the server certificate and key (to authenticate
itself to the clients).  See elsewhere (@pxref{Parameters for
shishid}) for the entire description of the parameters.

@example
jas@@latte:~$ shishid -l *:4711/tcp \
   --x509cafile /usr/local/etc/shishi/shishi.cert \
   --x509certfile /usr/local/etc/shishi/shishid.cert \
   --x509keyfile /usr/local/etc/shishi/shishid.key
Initializing GNUTLS...
Parsed 1 CAs...
Loaded server certificate/key...
Generating Diffie-Hellman parameters...
Initializing GNUTLS...done
Listening on *:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on *:4711/tcp socket 4
@end example

Then acquire tickets as usual.  In case you wonder how shishi finds
the client certificate and key, the filenames used above when
generating the client certificates happen to be the default filenames
for these files.  So it pick them up automatically.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls' \
   simon@@EXAMPLE.ORG
Enter password for `simon@@EXAMPLE.ORG':
simon@@EXAMPLE.ORG:
Authtime:       Sun Dec 21 11:15:47 2003
Endtime:        Sun Dec 21 11:32:27 2003
Server:         krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE RENEWABLE HWAUTHENT TRANSITEDPOLICYCHECKED OKASDELEGATE (12)
jas@@latte:~$
@end example

Here is what the server would print.

@example
shishid: Accepted socket 6 from socket 4 as *:4711/tcp peer 127.0.0.1
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 4 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying STARTTLS
shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `RSA', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
shishid: TLS client certificate `C=SE,O=Shishi Example Client,CN=Client', issued by `C=SE,O=Shishi Example CA,CN=CA', serial number `00', MD5 fingerprint `a5:d3:1f:58:76:e3:58:cd:2d:eb:f7:45:a2:4b:52:f9:', activated `Sun Dec 21 11:04:00 2003', expires `Fri Jun 18 12:04:00 2004', version #3, key RSA modulus 1024 bits, currently EXPIRED
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 131 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Processing 131 from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying AS-REQ
shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Sending 511 bytes to *:4711/tcp peer 127.0.0.1 socket 6 via TLS
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Peer *:4711/tcp peer 127.0.0.1 disconnected on socket 6
shishid: Closing *:4711/tcp peer 127.0.0.1 socket 6
shishid: Listening on *:4711/tcp socket 4
@end example


@node Multiple servers
@section Multiple servers
@cindex remote databases
@cindex LDAP
@cindex SQL

@cindex NFS
@cindex IPSEC
@cindex rsync
Setting up multiple servers is as easy as replicating the user
database.  Since the default @samp{file} user database is stored in
the normal file system, you can use any common tools to replicate a
file system.  Network file system like NFS (properly secured
by, e.g., a point-to-point symmetrically encrypted IPSEC
connection) and file synchronizing tools like @samp{rsync} are typical
choices.

@cindex master server
@cindex secondary server
The secondary server should be configured just like the master server.
If you use the @samp{file} database over NFS you do not have
to make any modifications.  If you use, e.g., a cron job to
@samp{rsync} the directory every hour or so, you may want to add a
@samp{--read-only} flag to the Shisa @samp{db} definition
(@pxref{Shisa Configuration}).  That way, nobody will be lured into
creating or changing information in the database on the secondary
server, which only would be overwritten during the next
synchronization.

@example
db --read-only file /usr/local/var/backup-shishi
@end example

@cindex concurrent writers
The @samp{file} database is designed so it doesn't require file
locking in the file system, which may be unreliable in some network
file systems or implementations.  It is also designed so that multiple
concurrent readers and writers may access the database without causing
corruption.

@strong{Warning:} The last paragraph is currently not completely
accurate.  There may be race conditions with concurrent writers.  None
should cause infinite loops or data loss.  However, unexpected results
might occur if two writers try to update information about a principal
simultaneous.

If you use a remote LDAP server or SQL database to
store the user database, and access it via a Shisa backend, you have
make sure your Shisa backend handle concurrent writers properly.  If
you use a modern SQL database, this probably is not a
concern.  If it is a problem, you may be able to work around it by
implementing some kind of synchronization or semaphore mechanism.  If
all else sounds too complicated, you can set up the secondary servers
as @samp{--read-only} servers, although you will lose some
functionality (like changing passwords via the secondary server, or
updating timestamps when the last ticket request occurred).

One function that is of particular use for users with remote databases
(be it LDAP or SQL) is the ``database override''
feature.  Using this you can have the security critical principals
(such as the ticket granting ticket) stored on local file system
storage, but use the remote database for user principals.  Of course,
you must keep the local file system storage synchronized between all
servers, as before.  Here is an example configuration.

@example
db --read-only file /var/local/master
db ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
@end example

This instruct the Shisa library to access the two databases
sequentially, for each query using the first database that know about
the requested principal.  If you put the @samp{krbtgt/REALM} principal
in the local @samp{file} database, this will override the
LDAP interface.  Naturally, you can have as many @samp{db}
definition lines as you wish.

@cindex High Availability
Users with remote databases can also investigate a so called @i{High
Availability} mode.  This is useful if you wish to have your Kerberos
servers be able to continue to operate even when the remote database
is offline.  This is achieved via the @samp{--ignore-errors} flag in
the database definition.  Here is a sample configuration.

@example
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --read-only file /var/cache/ldap-copy
@end example

This instruct the Shisa library to try the LDAP backend
first, but if it fails, instead of returning an error, continue to try
the operation on a read only local @samp{file} based database.  Of
course, write requests will still fail, but it may be better than
halting the server completely.  To make this work, you first need to
set up a cron job on a, say, hourly basis, to make a copy of the
remote database and store it in the local file database.  That way,
when the remote server goes away, fairly current information will
still be available locally.

@cindex fail over
If you also wish to experiment with read-write fail over, here is an
idea for the configuration.

@example
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --ignore-errors --read-only file /var/cache/ldap-copy
db file /var/cache/local-updates
@end example

This is similar to the previous, but it will ignore errors reading and
writing from the first two databases, ultimately causing write
attempts to end up in the final @samp{file} based database.  Of
course, you would need to create tools to feed back any local updates
made while the remote server was down.  It may also be necessary to
create a special backend for this purpose, which can auto create
principals that are used.

We finish with an example that demonstrate all the ideas presented.

@example
db --read-only file /var/local/master
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --ignore-errors --read-only file /var/cache/ldap-copy
db file /var/cache/local-updates
@end example

@node Developer information
@section Developer information

The Programming API for Shisa is described below (@pxref{Kerberos
Database Functions}); this section is about extending Shisa, and
consequently Shishi, to use your own user database system.  You may
want to store your Kerberos user information on an LDAP database
server, for example.

Adding a new backend is straight forward.  You need to implement the
backend API function set, add the list of API functions to
@file{db/db.c} and possibly also add any library dependencies to the
Makefile.

The simplest way to write a new backend is to start from the existing
@samp{file} based database, in @file{db/file.c}, and modify the entry
points as needed.

Note that the current backend API will likely change before it is
frozen.  We may describe it in detail here when it has matured.
However, currently it is similar to the external Shisa API
(@pxref{Kerberos Database Functions}).

There should be no need to modify anything else in the Shisa library,
and certainly not in the Shishi library or the @file{shishid} server.

Naturally, we would appreciate if you would send us your new backend,
if you believe it is generally useful (@pxref{Bug Reports}).

@c **********************************************************
@c ****************  Reference Manual  **********************
@c **********************************************************
@node Reference Manual
@chapter Reference Manual

This chapter discuss the underlying assumptions of Kerberos, contain a
glossary to Kerberos concepts, give you background information on
choosing realm and principal names, and describe all parameters and
configuration file syntaxes for the Shishi tools.

@menu
* Environmental Assumptions::   Kerberos 5 assumptions about your system.
* Glossary of terms::           Glossary of Kerberos related terminology.
* Realm and Principal Naming::  How to name your realm and principals.
* Shishi Configuration::        Explains the Core Shishi configuration file.
* Shisa Configuration::         Explains the Shisa database definition file.
* Parameters for shishi::       Command line parameters for 'shishi'.
* Parameters for shishid::      Command line parameters for 'shishid'.
* Parameters for shisa::        Command line parameters for 'shisa'.
* Environment variables::       Overriding compile-time defaults at run-time.
* Date input formats::          Details of the understood date formats.
@end menu

@node Environmental Assumptions
@section Environmental Assumptions

Kerberos imposes a few assumptions on the environment in which it can
properly function:

@itemize @bullet

@item
"Denial of service" attacks are not solved with Kerberos. There
are places in the protocols where an intruder can prevent an
application from participating in the proper authentication steps.
Detection and solution of such attacks (some of which can appear
to be not-uncommon "normal" failure modes for the system) is
usually best left to the human administrators and users.
@item
Principals MUST keep their secret keys secret. If an intruder
somehow steals a principal's key, it will be able to masquerade as
that principal or impersonate any server to the legitimate
principal.
@item
"Password guessing" attacks are not solved by Kerberos. If a user
chooses a poor password, it is possible for an attacker to
successfully mount an offline dictionary attack by repeatedly
attempting to decrypt, with successive entries from a dictionary,
messages obtained which are encrypted under a key derived from the
user's password.
@item
Each host on the network MUST have a clock which is "loosely
synchronized" to the time of the other hosts; this synchronization
is used to reduce the bookkeeping needs of application servers
when they do replay detection. The degree of "looseness" can be
configured on a per-server basis, but is typically on the order of
5 minutes. If the clocks are synchronized over the network, the
clock synchronization protocol MUST itself be secured from network
attackers.
@item
Principal identifiers are not recycled on a short-term basis. A
typical mode of access control will use access control lists
(ACLs) to grant permissions to particular principals. If a stale
ACL entry remains for a deleted principal and the principal
identifier is reused, the new principal will inherit rights
specified in the stale ACL entry. By not re-using principal
identifiers, the danger of inadvertent access is removed.
@end itemize

@node Glossary of terms
@section Glossary of terms

@table @asis
@item Authentication
@cindex Authentication
Verifying the claimed identity of a principal.

@item Authentication header
@cindex Authentication header
A record containing a Ticket and an Authenticator to be presented
to a server as part of the authentication process.

@item Authentication path
@cindex Authentication path
A sequence of intermediate realms transited in the authentication
process when communicating from one realm to another.

@item Authenticator
@cindex Authenticator
A record containing information that can be shown to have been
recently generated using the session key known only by the client
and server.

@item Authorization
@cindex Authorization
The process of determining whether a client may use a service,
which objects the client is allowed to access, and the type of
access allowed for each.

@item Capability
@cindex Capability
A token that grants the bearer permission to access an object or
service. In Kerberos, this might be a ticket whose use is
restricted by the contents of the authorization data field, but
which lists no network addresses, together with the session key
necessary to use the ticket.

@item Ciphertext
@cindex Ciphertext
The output of an encryption function. Encryption transforms
plaintext into ciphertext.

@item Client
@cindex Client
A process that makes use of a network service on behalf of a user.
Note that in some cases a Server may itself be a client of some
other server (e.g. a print server may be a client of a file
server).

@item Credentials
@cindex Credentials
A ticket plus the secret session key necessary to successfully use
that ticket in an authentication exchange.

@item Encryption Type (etype)
@cindex Encryption Type (etype)
When associated with encrypted data, an encryption type identifies
the algorithm used to encrypt the data and is used to select the
appropriate algorithm for decrypting the data.  Encryption type
tags are communicated in other messages to enumerate algorithms
that are desired, supported, preferred, or allowed to be used for
encryption of data between parties.  This preference is combined
with local information and policy to select an algorithm to be
used.

@item KDC
@cindex KDC
Key Distribution Center, a network service that supplies tickets
and temporary session keys; or an instance of that service or the
host on which it runs. The KDC services both initial ticket and
ticket-granting ticket requests. The initial ticket portion is
sometimes referred to as the Authentication Server (or service).
The ticket-granting ticket portion is sometimes referred to as the
ticket-granting server (or service).

@item Kerberos
@cindex Kerberos
The name given to the Project Athena's authentication service, the
protocol used by that service, or the code used to implement the
authentication service.  The name is adopted from the three-headed
dog which guards Hades.

@item Key Version Number (kvno)
@cindex Key Version Number (kvno)
A tag associated with encrypted data identifies which key was used
for encryption when a long lived key associated with a principal
changes over time.  It is used during the transition to a new key
so that the party decrypting a message can tell whether the data
was encrypted using the old or the new key.

@item Plaintext
@cindex Plaintext
The input to an encryption function or the output of a decryption
function. Decryption transforms ciphertext into plaintext.

@item Principal
@cindex Principal
A named client or server entity that participates in a network
communication, with one name that is considered canonical.

@item Principal identifier
@cindex Principal identifier
The canonical name used to uniquely identify each different
principal.

@item Seal
@cindex Seal
To encipher a record containing several fields in such a way that
the fields cannot be individually replaced without either
knowledge of the encryption key or leaving evidence of tampering.

@item Secret key
@cindex Secret key
An encryption key shared by a principal and the KDC, distributed
outside the bounds of the system, with a long lifetime. In the
case of a human user's principal, the secret key MAY be derived
from a password.

@item Server
@cindex Server
A particular Principal which provides a resource to network
clients.  The server is sometimes referred to as the Application
Server.

@item Service
@cindex Service
A resource provided to network clients; often provided by more
than one server (for example, remote file service).

@item Session key
@cindex Session key
A temporary encryption key used between two principals, with a
lifetime limited to the duration of a single login "session".  In
the Kerberos system, a session key is generated by the KDC.  The
session key is distinct from the sub-session key, described next..

@item Sub-session key
@cindex Sub-session key
A temporary encryption key used between two principals, selected
and exchanged by the principals using the session key, and with a
lifetime limited to the duration of a single association. The sub-
session key is also referred to as the subkey.

@item Ticket
@cindex Ticket
@cindex Kerberos Ticket
A record that helps a client authenticate itself to a server; it
contains the client's identity, a session key, a timestamp, and
other information, all sealed using the server's secret key. It
only serves to authenticate a client when presented along with a
fresh Authenticator.
@end table

@node Realm and Principal Naming
@section Realm and Principal Naming

This section contains the discussion on naming realms and principals
from the Kerberos specification.

@subsection Realm Names

Although realm names are encoded as GeneralStrings and although a
realm can technically select any name it chooses, interoperability
across realm boundaries requires agreement on how realm names are to
be assigned, and what information they imply.

To enforce these conventions, each realm MUST conform to the
conventions itself, and it MUST require that any realms with which
inter-realm keys are shared also conform to the conventions and
require the same from its neighbors.

Kerberos realm names are case sensitive. Realm names that differ only
in the case of the characters are not equivalent. There are presently
three styles of realm names: domain, X500, and other. Examples of
each style follow:

@example
     domain:   ATHENA.MIT.EDU
       X500:   C=US/O=OSF
      other:   NAMETYPE:rest/of.name=without-restrictions
@end example

Domain syle realm names MUST look like domain names: they consist of
components separated by periods (.) and they contain neither colons
(:) nor slashes (/). Though domain names themselves are case
insensitive, in order for realms to match, the case must match as
well. When establishing a new realm name based on an internet domain
name it is recommended by convention that the characters be converted
to upper case.

X.500 names contain an equal (=) and cannot contain a colon (:)
before the equal. The realm names for X.500 names will be string
representations of the names with components separated by slashes.
Leading and trailing slashes will not be included. Note that the
slash separator is consistent with Kerberos implementations based on
RFC1510, but it is different from the separator recommended in
RFC2253.

Names that fall into the other category MUST begin with a prefix that
contains no equal (=) or period (.) and the prefix MUST be followed
by a colon (:) and the rest of the name. All prefixes must be
assigned before they may be used. Presently none are assigned.

The reserved category includes strings which do not fall into the
first three categories. All names in this category are reserved. It
is unlikely that names will be assigned to this category unless there
is a very strong argument for not using the 'other' category.

These rules guarantee that there will be no conflicts between the
various name styles. The following additional constraints apply to
the assignment of realm names in the domain and X.500 categories: the
name of a realm for the domain or X.500 formats must either be used
by the organization owning (to whom it was assigned) an Internet
domain name or X.500 name, or in the case that no such names are
registered, authority to use a realm name MAY be derived from the
authority of the parent realm. For example, if there is no domain
name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can
authorize the creation of a realm with that name.

This is acceptable because the organization to which the parent is
assigned is presumably the organization authorized to assign names to
its children in the X.500 and domain name systems as well. If the
parent assigns a realm name without also registering it in the domain
name or X.500 hierarchy, it is the parent's responsibility to make
sure that there will not in the future exist a name identical to the
realm name of the child unless it is assigned to the same entity as
the realm name.

@subsection Principal Names

As was the case for realm names, conventions are needed to ensure
that all agree on what information is implied by a principal name.
The name-type field that is part of the principal name indicates the
kind of information implied by the name. The name-type SHOULD be
treated only as a hint to interpreting the meaning of a name. It is
not significant when checking for equivalence. Principal names that
differ only in the name-type identify the same principal. The name
type does not partition the name space. Ignoring the name type, no
two names can be the same (i.e. at least one of the components, or
the realm, MUST be different). The following name types are defined:

@example
name-type      value   meaning

NT-UNKNOWN        0  Name type not known
NT-PRINCIPAL      1  Just the name of the principal as in DCE, or for users
NT-SRV-INST       2  Service and other unique instance (krbtgt)
NT-SRV-HST        3  Service with host name as instance (telnet, rcommands)
NT-SRV-XHST       4  Service with host as remaining components
NT-UID            5  Unique ID
NT-X500-PRINCIPAL 6  Encoded X.509 Distingished name [RFC 2253]
NT-SMTP-NAME      7  Name in form of SMTP email name (e.g. user@@foo.com)
NT-ENTERPRISE    10   Enterprise name - may be mapped to principal name
@end example

When a name implies no information other than its uniqueness at a
particular time the name type PRINCIPAL SHOULD be used. The principal
name type SHOULD be used for users, and it might also be used for a
unique server. If the name is a unique machine generated ID that is
guaranteed never to be reassigned then the name type of UID SHOULD be
used (note that it is generally a bad idea to reassign names of any
type since stale entries might remain in access control lists).

If the first component of a name identifies a service and the
remaining components identify an instance of the service in a server
specified manner, then the name type of SRV-INST SHOULD be used. An
example of this name type is the Kerberos ticket-granting service
whose name has a first component of krbtgt and a second component
identifying the realm for which the ticket is valid.

If the first component of a name identifies a service and there is a
single component following the service name identifying the instance
as the host on which the server is running, then the name type SRV-
HST SHOULD be used. This type is typically used for Internet services
such as telnet and the Berkeley R commands. If the separate
components of the host name appear as successive components following
the name of the service, then the name type SRV-XHST SHOULD be used.
This type might be used to identify servers on hosts with X.500 names
where the slash (/) might otherwise be ambiguous.

A name type of NT-X500-PRINCIPAL SHOULD be used when a name from an
X.509 certificate is translated into a Kerberos name. The encoding of
the X.509 name as a Kerberos principal shall conform to the encoding
rules specified in RFC 2253.

A name type of SMTP allows a name to be of a form that resembles a
SMTP email name. This name, including an "@@" and a domain name, is
used as the one component of the principal name.

A name type of UNKNOWN SHOULD be used when the form of the name is
not known. When comparing names, a name of type UNKNOWN will match
principals authenticated with names of any type. A principal
authenticated with a name of type UNKNOWN, however, will only match
other names of type UNKNOWN.

Names of any type with an initial component of 'krbtgt' are reserved
for the Kerberos ticket granting service. @xref{krbtgt,, Name of the
TGS}, for the form of such names.

@subsubsection Name of server principals

The principal identifier for a server on a host will generally be
composed of two parts: (1) the realm of the KDC with which the server
is registered, and (2) a two-component name of type NT-SRV-HST if the
host name is an Internet domain name or a multi-component name of
type NT-SRV-XHST if the name of the host is of a form such as X.500
that allows slash (/) separators. The first component of the two- or
multi-component name will identify the service and the latter
components will identify the host. Where the name of the host is not
case sensitive (for example, with Internet domain names) the name of
the host MUST be lower case. If specified by the application protocol
for services such as telnet and the Berkeley R commands which run
with system privileges, the first component MAY be the string 'host'
instead of a service specific identifier.

@subsubsection Name of the TGS
@anchor{krbtgt}

The principal identifier of the ticket-granting service shall be
composed of three parts: (1) the realm of the KDC issuing the TGS
ticket (2) a two-part name of type NT-SRV-INST, with the first part
"krbtgt" and the second part the name of the realm which will accept
the ticket-granting ticket. For example, a ticket-granting ticket
issued by the ATHENA.MIT.EDU realm to be used to get tickets from the
ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting
ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets
from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "MIT.EDU") (name).

@subsection Choosing a principal with which to communicate

The Kerberos protocol provides the means for verifying (subject to
the assumptions in @ref{Environmental Assumptions}) that the entity with which one communicates
is the same entity that was registered with the KDC using the claimed
identity (principal name). It is still necessary to determine whether
that identity corresponds to the entity with which one intends to
communicate.

When appropriate data has been exchanged in advance, this
determination may be performed syntactically by the application based
on the application protocol specification, information provided by
the user, and configuration files. For example, the server principal
name (including realm) for a telnet server might be derived from the
user specified host name (from the telnet command line), the "host/"
prefix specified in the application protocol specification, and a
mapping to a Kerberos realm derived syntactically from the domain
part of the specified hostname and information from the local
Kerberos realms database.

One can also rely on trusted third parties to make this
determination, but only when the data obtained from the third party
is suitably integrity protected while resident on the third party
server and when transmitted.  Thus, for example, one should not rely
on an unprotected domain name system record to map a host alias to
the primary name of a server, accepting the primary name as the party
one intends to contact, since an attacker can modify the mapping and
impersonate the party with which one intended to communicate.

Implementations of Kerberos and protocols based on Kerberos MUST NOT
use insecure DNS queries to canonicalize the hostname components of
the service principal names.  In an environment without secure name
service, application authors MAY append a statically configured
domain name to unqualified hostnames before passing the name to the
security mechanisms, but should do no more than that.  Secure name
service facilities, if available, might be trusted for hostname
canonicalization, but such canonicalization by the client SHOULD NOT
be required by KDC implementations.

Implementation note: Many current implementations do some degree of
canonicalization of the provided service name, often using DNS even
though it creates security problems. However there is no consistency
among implementations about whether the service name is case folded
to lower case or whether reverse resolution is used. To maximize
interoperability and security, applications SHOULD provide security
mechanisms with names which result from folding the user-entered name
to lower case, without performing any other modifications or
canonicalization.

@subsection Principal Name Form

Principal names consist of a sequence of strings, which is often
tedious to parse.  Therefor, Shishi often uses a ``printed'' form of
principal which embed the entire principal name string sequence, and
optionally also the realm, into one string.  The format is taken from
the Kerberos 5 GSS-API mechanism (RFC 1964).

The elements included within this name representation are as follows,
proceeding from the beginning of the string:

@enumerate
@item
One or more principal name components; if more than one
principal name component is included, the components are
separated by `/`.  Arbitrary octets may be included within
principal name components, with the following constraints and
special considerations:
@enumerate a
@item
Any occurrence of the characters `@@` or `/` within a
name component must be immediately preceded by the `\`
quoting character, to prevent interpretation as a component
or realm separator.
@item
The ASCII newline, tab, backspace, and null characters
may occur directly within the component or may be
represented, respectively, by `\n`, `\t`, `\b`, or `\0`.
@item
If the `\` quoting character occurs outside the contexts
described in (1a) and (1b) above, the following character is
interpreted literally.  As a special case, this allows the
doubled representation `\\` to represent a single occurrence
of the quoting character.
@item
An occurrence of the `\` quoting character as the last
character of a component is illegal.
@end enumerate
@item
Optionally, a `@@` character, signifying that a realm name
immediately follows. If no realm name element is included, the
local realm name is assumed.  The `/` , `:`, and null characters
may not occur within a realm name; the `@@`, newline, tab, and
backspace characters may be included using the quoting
conventions described in (1a), (1b), and (1c) above.
@end enumerate

@node Shishi Configuration
@section Shishi Configuration
@cindex configuration file

The valid configuration file tokens are described here.  The user
configuration file is typically located in
@file{~/.shishi/shishi.conf} (compare @samp{shishi
--configuration-file}) and the system configuration is typically
located in @file{/usr/local/etc/shishi/shishi.conf} (compare
@samp{shishi --system-configuration-file}).  If the first non white
space character of a line is a '#', the line is ignored.  Empty lines
are also ignored.

All tokens are valid in both the system and the user configuration
files, and have the same meaning.  However, as the system file is
supposed to apply to all users on a system, it would not make sense to
use some tokens in that file.  For example, the
@samp{default-principal} is rarely useful in a system configuration
file.

@subsection @samp{default-realm}
Specify the default realm, by default the hostname of the host is
used.  E.g.,

@example
default-realm JOSEFSSON.ORG
@end example

@subsection @samp{default-principal}

Specify the default principal, by default the login username is
used. E.g.,

@example
default-principal jas
@end example

@subsection @samp{client-kdc-etypes}

Specify which encryption types client asks server to respond in during
AS/TGS exchanges. List valid encryption types, in preference order.
Supported algorithms include aes256-cts-hmac-sha1-96,
aes128-cts-hmac-sha1-96, des3-cbc-sha1-kd, des-cbc-md5, des-cbc-md4,
des-cbc-crc and null.  This option also indicates which encryption
types are accepted by the client when receiving the response.  Note
that the preference order is not cryptographically protected, so a man
in the middle can modify the order without being detected.  Thus, only
specify encryption types you trust completely here. The default only
includes aes256-cts-hmac-sha1-96, as suggested by RFC1510bis.  E.g.,

@example
client-kdc-etypes=aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5
@end example

@subsection @samp{verbose}, @samp{verbose-asn1}, @samp{verbose-noise}, @samp{verbose-crypto}, @samp{verbose-crypto-noise}

Enable verbose library messages.  E.g.,

@example
verbose
verbose-noise
@end example

@subsection @samp{realm-kdc}
@anchor{realm-kdc}

Specify KDC addresses for realms.  Value is
@samp{REALM,KDCADDRESS[/TRANSPORT][,KDCADDRESS[/TRANSPORT]...]}.

KDCADDRESS is the hostname or IP address of KDC.

Optional TRANSPORT is ``udp'' for UDP, ``tcp'' for TCP, and ``tls''
for TLS connections.  By default UDP is tried first, and TCP used as a
fallback if the KRB_ERR_RESPONSE_TOO_BIG error is received.

If not specified, Shishi tries to locate the KDC using SRV RRs,
which is recommended.  This option should normally only be
used during experiments, or to access badly maintained realms.

@example
realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org
@end example

@subsection @samp{server-realm}

Specify realm for servers. Value is
@samp{REALM,SERVERREGEXP[,SERVERREGEXP...]}.

SERVERREGEXP is a regular expression matching servers in the realm.
The first match is used.  E.g.,

@example
server-realm=JOSEFSSON.ORG,.josefsson.org
@end example

Note: currently not used.

@subsection @samp{kdc-timeout}, @samp{kdc-retries}

How long shishi waits for a response from a KDC before continuing to
next KDC for realm.  The default is 5 seconds.  E.g.,

@example
kdc-timeout=10
@end example

How many times shishi sends a request to a KDC before giving up.  The
default is 3 times.  E.g.,

@example
kdc-retries=5
@end example

@subsection @samp{stringprocess}

How username and passwords entered from the terminal, or taken from
the command line, are processed.

"none": no processing is used.

"stringprep": convert from locale charset to UTF-8 and process using
              experimental RFC 1510 stringprep profile.

It can also be a string indicating a character set supported by
iconv via libstringprep, in which case data is converted from locale
charset into the indicated character set. E.g., UTF-8, ISO-8859-1,
KOI-8, EBCDIC-IS-FRISS are supported on GNU systems.  On some systems
you can use "locale -m" to list available character sets.  By default,
the "none" setting is used which is consistent with RFC 1510 that is
silent on the issue.  In practice, however, converting to UTF-8
improves interoperability.

E.g.,

@example
stringprocess=UTF-8
@end example

@subsection @samp{ticket-life}
Specify default ticket life time.

The string can be in almost any common format.  It can contain month
names, time zones, `am' and `pm', `yesterday', `ago', `next', etc.
@xref{Date input formats}, for the long story.

As an extra feature, if the time specified by your string correspond
to a time during the last 24 hours, an extra day is added to it.  This
allows you to specify relative times such as "17:00" to always mean
the next 17:00, even if your system clock happens to be 17:30.

The default is 8 hours.

E.g.,

@example
#ticket-life=8 hours
#ticket-life=1 day
ticket-life=17:00
@end example

@subsection @samp{renew-life}

Specify how long a renewable ticket should remain renewable.

See ticket-life for the syntax.  The extra feature that handles
negative values within the last 2 hours is not active here.

The default is 7 days.

E.g.,

@example
#renew-life=1 week
#renew-life=friday 17:00
renew-life=sunday
@end example

@node Shisa Configuration
@section Shisa Configuration
@cindex database definition
@cindex specifying user database
@cindex user database definition

The configuration file for Shisa is typically stored in
@file{/usr/local/etc/shishi/shisa.conf}.  If the first non white space
character of a line is a '#', the line is ignored.  Empty lines are
also ignored.

@subsection @samp{db}

Currently the only configuration options available is the @code{db}
token that define the databases to use.  The syntax is:

@example
db [OPTIONS] <TYPE> [LOCATION] [PARAMETERS ...]
@end example

Specify the data sources for Kerberos 5 data.  Multiple entries,
even of the same data source type, are allowed.  The data sources
are accessed in the same sequence as they are defined here.  If an
entry is found in one data source, it will be used for the
operations, without searching the remaining data sources.  Valid
OPTIONS include:

@example
--read-only       No data is written to this data source.
--ignore-errors   Ignore failures in this backend.
@end example

The default (when the configuration file is empty) uses one "file"
data source (see below), but for a larger installation you may want to
combine several data sources.  Here is an example.

@example
db --read-only file /var/local/master
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --read-only file /var/cache/ldap-copy
@end example

This demonstrate how you can store critical principals on local disk
(the first entry, /var/local/master) that will always be found without
looking in the LDAP directory.  The critical principals could be,
e.g., krbtgt/EXAMPLE.ORG.  The second entry denote a LDAP server that
could hold user principals.  As you can see, Shisa will not let the
caller know about errors with the LDAP source (they will be logged,
however).  Instead, if for instance the LDAP server has crashed, Shisa
would continue and read from the /var/cache/ldap-copy file source.
That file source may have been set up to contain a copy of the data in
the LDAP server, perhaps made on an hourly basis, so that your server
will be able to serve recent data even in case of a crash.  Any
updates or passwords change requests will however not be possible
while the LDAP server is inaccessible, to reduce the problem of
synchronizing data back into the LDAP server once it is online again.

Currently only the "file" data source is supported, and denote a
data source that use the standard file system for storage.

Valid syntaxes for the "file" database:

@example
db file PATH
@end example

Examples:

@example
db file /var/shishi
db file /usr/share/shishi read-only
@end example

If no @samp{db} tokens are present, the default will be:

@example
db file /usr/local/var/shishi
@end example

@node Parameters for shishi
@section Parameters for shishi

If no command is given, Shishi try to make sure you have a ticket
granting ticket for the default realm, and then display it.

Mandatory arguments to long options are mandatory for short options
too.

@example
Usage: shishi [OPTIONS]... [CLIENT [SERVER]]...
 
  -h, --help                              Print help and exit
  -V, --version                           Print version and exit
 
Commands:
  -d, --destroy                           Destroy tickets in local cache,
                                            limited by any --client-name or
                                            --server-name.  (default=off)
  -l, --list                              List tickets in local cache, limited
                                            by any --client-name and
                                            --server-name.  (default=off)
  -r, --renew                             Renew ticket.  Use --server-name to
                                            specify ticket, default is the
                                            most recent renewable ticket
                                            granting ticket for the default
                                            realm.  (default=off)
 
Flags:
      --forwardable                       Get a forwardable ticket, i.e., one
                                            that can be used to get forwarded
                                            tickets.  (default=off)
      --forwarded                         Get a forwarded ticket.  (default=
                                            off)
      --proxiable                         Get a proxiable ticket, i.e., one
                                            that can be used to get proxy
                                            tickets.  (default=off)
      --proxy                             Get a proxy ticket.  (default=off)
      --renewable                         Get a renewable ticket.  (default=
                                            off)
 
Options:
      --client-name=NAME                  Client name. Default is login
                                            username.
  -E, --encryption-type=ETYPE,[ETYPE...]  Encryption types to use.  ETYPE is
                                            either registered name or integer.
                                             Valid values include 'aes128',
                                            'aes256', 'aes' (same as
                                            'aes256'), '3des', 'des-md5',
                                            'des-md4', 'des-crc', 'des' (same
                                            as 'des-md5'), and 'arcfour'.
  -e, --endtime=STRING                    Specify when ticket validity should
                                            expire.  The time syntax may be
                                            relative (to the start time), such
                                            as '20 hours', or absolute, such
                                            as '2001-02-03 04:05:06 CET'. The
                                            default is 8 hours after the start
                                            time.
      --realm=STRING                      Set default realm.
      --renew-till=STRING                 Specify renewable life of ticket.
                                            Implies --renewable.  Accepts same
                                            time syntax as --endtime.  If
                                            --renewable is specified, the
                                            default is 1 week after the start
                                            time.
      --server-name=NAME                  Server name. Default is
                                            'krbtgt/REALM' where REALM is
                                            client realm.
  -s, --starttime=STRING                  Specify when ticket should start to
                                            be valid.  Accepts same time
                                            syntax as --endtime. The default
                                            is to become valid immediately.
      --ticket-granter=NAME               Service name in ticket to use for
                                            authenticating request. Only for
                                            TGS. Defaults to
                                            'krbtgt/REALM@@REALM' where REALM
                                            is client realm.
 
Other options:
      --configuration-file=FILE           Read user configuration from FILE.
  -c, --ticket-file=FILE                  Read tickets from FILE.
  -o, --library-options=STRING            Parse STRING as a configuration file
                                            statement.
  -q, --quiet                             Don't produce any diagnostic output.
                                              (default=off)
      --system-configuration-file=FILE    Read system configuration from FILE.
      --ticket-write-file=FILE            Write tickets from FILE.  Default is
                                            to write them back to where they
                                            were read from.
  -v, --verbose                           Produce verbose output.
                                              (default=off)
@end example

@node Parameters for shishid
@section Parameters for shishid

If no parameters are specified, @samp{shishid} listens on the defaults
interfaces and answers incoming requests using the keys in the default
key file.

Mandatory arguments to long options are mandatory for short options
too.

@example
Usage: shishid [OPTIONS]...

  -h, --help                    Print help and exit
  -V, --version                 Print version and exit

Commands:
  -l, --listen=[FAMILY:]ADDR:PORT/TYPE
                                Sockets to listen for queries on.  Family is
                                  `IPv4' or `IPv6', if absent the family is
                                  decided by gethostbyname(ADDR). An address of
                                  `*' indicates all addresses on the local
                                  host. The default is `*:kerberos/udp,
                                  *:kerberos/tcp'.
  -u, --setuid=NAME             After binding socket, set user identity.

TLS settings:
      --no-tls                  Disable TLS support  (default=off)
      --x509cafile=FILE         X.509 certificate authorities used to verify
                                  client certificates, in PEM format.
      --x509certfile=FILE       X.509 server certificate, in PEM format.
      --x509crlfile=FILE        X.509 certificate revocation list to check for
                                  revoked client certificates, in PEM format.
      --x509keyfile=FILE        X.509 server certificate key, in PEM format.
      --resume-limit=SHORT      Keep track of up to this many TLS sessions for
                                  resume purposes (0 to disable TLS resume).
                                  (default=`50')

Other options:
  -c, --configuration-file=FILE Use specified configuration file.
  -v, --verbose                 Produce verbose output.
                                  Use multiple times to increase amount of
                                  information.
  -q, --quiet                   Don't produce any diagnostic output.
                                    (default=off)
@end example

@node Parameters for shisa
@section Parameters for shisa

The purpose of @samp{shisa} is to manipulate information stored in the
Kerberos 5 database used by Shishi.

Mandatory arguments to long options are mandatory for short options
too.

@example
Usage: shisa [OPTIONS]... [REALM [PRINCIPAL]]...

  -h, --help                         Print help and exit
  -V, --version                      Print version and exit
 
Operations:
  -a, --add                          Add realm or principal to database.
  -d, --dump                         Dump entries in database.
  -n, --key-add                      Add new key to a principal in database.
      --key-remove                   Remove a key from a principal in
                                       database.
  -l, --list                         List entries in database.
  -m, --modify                       Modify principal entry in database.
  -r, --remove                       Remove realm or principal from database.
 
Parameters:
  -f, --force                        Allow removal of non-empty realms.
                                         (default=off)
      --enabled                      Only dump or list enabled principals.
                                         (default=off)
      --disabled                     Only dump or list disabled principals.
                                         (default=off)
      --keys                         Print cryptographic key and password in
                                       hostkey format.  (default=off)
 
Values:
  -E, --encryption-type=STRING       Override default key encryption type.
                                       Valid values include 'aes128',
                                       'aes256', 'aes' (same as 'aes256'),
                                       '3des', 'des-md5', 'des-md4',
                                       'des-crc', 'des' (same as 'des-md5'),
                                       and 'arcfour'.
      --key-version=NUMBER           Version of key.
      --password[=STRING]            Derive key from this password.
      --random                       Use a random key.  (default)
      --salt=STRING                  Use specified salt for deriving key.
                                       Defaults to concatenation of realm and
                                       (unwrapped) principal name.
      --string-to-key-parameter=HEX  Encryption algorithm specific parameter
                                       for password derivation.  Currently
                                       only the AES algorithm can utilize
                                       this, where it is interpreted as the
                                       iteration count of the PKCS#5 PBKDF2
                                       key deriver.
 
Other options:
  -c, --configuration-file=FILE      Use specified configuration file.
  -o, --library-options=STRING       Parse string as configuration file
                                       statement.
  -v, --verbose                      Produce verbose output.
                                         (default=off)
  -q, --quiet                        Don't produce any diagnostic output.
                                         (default=off)
@end example

@node Environment variables
@section Environment variables

A few of the compile-time defaults may be overridden at run-time by
using environment variables.  The following variables are supported.

@itemize @bullet

@item @env{SHISHI_CONFIG}
Specify the location of the default system configuration file.  Used
by the Shishi library.  If not specified, the default is specified at
compile-time and is usually @file{$prefix/etc/shishi.conf}.

@item @env{SHISHI_HOME}
Specify the user specific directory for configuration files, ticket
cache, etc.  Used by the Shishi library.  If not specified, it is
computed as @code{$HOME/.shishi}.

@item @env{SHISHI_USER}
Specify the default principal user name.  Used by the Shishi library.
If not specified, it is taken from the environment variable
@env{USER}.

@item @env{SHISHI_TICKETS}
Specify the file name of the ticket cache.  Used by the Shishi
library.  If not specified, it will be @code{$SHISHI_HOME/tickets}, or
@code{$HOME/.shishi/tickets} if @code{$SHISHI_HOME} is not specified.

@end itemize

@lowersections
@include getdate.texi
@raisesections

@c **********************************************************
@c ***************  Programming Manual  *********************
@c **********************************************************
@node Programming Manual
@chapter Programming Manual
@cindex Application Programming Interface (API)

This chapter describes all the publicly available functions in the
library.

@menu
* Preparation::                 What you should do before using the library.
* Initialization Functions::    Creating library handle, configuration file.
* Ticket Set Functions::        High-level ticket management functions.
* AP-REQ and AP-REP Functions:: Client/Server authentication functions.
* SAFE and PRIV Functions::     Client/Server session data functions.
* Ticket Functions::            Medium-level ticket manipulation functions.
* AS Functions::                Medium-level initial authentication functions.
* TGS Functions::               Medium-level authentication functions.
* Ticket (ASN.1) Functions::    Low-level Ticket functions.
* AS/TGS Functions::            Low-level KDC functions; AS and TGS.
* Authenticator Functions::     Low-level authenticator functions.
* KRB-ERROR Functions::         Low-level KRB-ERROR functions.
* Cryptographic Functions::     Low-level cryptographic functions.
* X.509 Functions::             Utility functions for X.509 support.
* Utility Functions::           Utilities for use in the global context.
* ASN.1 Functions::             Perform low-level ASN.1 manipulations.
* Error Handling::              Error codes and such.
* Examples::                    Example code.
* Kerberos Database Functions:: The Shisa generic database interface.
* Generic Security Service::    If you want to use the GSS API instead.
@end menu

@node Preparation
@section Preparation

To use `Libshishi', you have to perform some changes to your sources
and the build system.  The necessary changes are small and explained
in the following sections.  At the end of this chapter, it is
described how the library is initialized, and how the requirements of
the library are verified.

A faster way to find out how to adapt your application for use with
`Libshishi' may be to look at the examples at the end of this manual
(@pxref{Examples}).

@menu
* Header::
* Initialization::
* Version Check::
* Building the source::
* Autoconf tests::
@end menu

@node Header
@subsection Header

All interfaces (data types and functions) of the library are defined
in the header file `shishi.h'.  You must include this in all programs
using the library, either directly or through some other header file,
like this:

@example
#include <shishi.h>
@end example

The name space of `Libshishi' is @code{shishi_*} for function names,
@code{Shishi*} for data types and @code{SHISHI_*} for other symbols.  In
addition the same name prefixes with one prepended underscore are
reserved for internal use and should never be used by an application.

@node Initialization
@subsection Initialization

`Libshishi' must be initialized before it can be used.  The library is
initialized by calling @code{shishi_init} (@pxref{Initialization
Functions}).  The resources allocated by the initialization process
can be released if the application no longer has a need to call
`Libshishi' functions, this is done by calling @code{shishi_done}.

In order to take advantage of the internationalisation features in
`Libshishi', such as translated error messages, the application must
set the current locale using @code{setlocale} before initializing
`Libshishi'.

@node Version Check
@subsection Version Check

It is often desirable to check that the version of `Libshishi' used is
indeed one which fits all requirements.  Even with binary
compatibility new features may have been introduced but due to problem
with the dynamic linker an old version is actually used.  So you may
want to check that the version is okay right after program startup.

@include texi/version.c.texi

The normal way to use the function is to put something similar to the
following early in your @code{main}:

@example
  if (!shishi_check_version (SHISHI_VERSION))
    @{
      printf ("shishi_check_version failed:\n"
              "Header file incompatible with shared library.\n");
      exit (EXIT_FAILURE);
    @}
@end example

@node Building the source
@subsection Building the source
@cindex Compiling your application

If you want to compile a source file including the `shishi.h' header
file, you must make sure that the compiler can find it in the
directory hierarchy.  This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the @option{-I} option).

However, the path to the include file is determined at the time the
source is configured.  To solve this problem, `Libshishi' uses the
external package @command{pkg-config} that knows the path to the
include file and other configuration options.  The options that need
to be added to the compiler invocation at compile time are output by
the @option{--cflags} option to @command{pkg-config shishi}.  The
following example shows how it can be used at the command line:

@example
gcc -c foo.c `pkg-config shishi --cflags`
@end example

Adding the output of @samp{pkg-config shishi --cflags} to the
compilers command line will ensure that the compiler can find the
`Libshishi' header file.

A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search path
(via the @option{-L} option).  For this, the option @option{--libs} to
@command{pkg-config shishi} can be used.  For convenience, this option
also outputs all other options that are required to link the program
with the `Libshishi' libararies (in particular, the @samp{-lshishi}
option).  The example shows how to link @file{foo.o} with the `Libshishi'
library to a program @command{foo}.

@example
gcc -o foo foo.o `pkg-config shishi --libs`
@end example

Of course you can also combine both examples to a single command by
specifying both options to @command{pkg-config}:

@example
gcc -o foo foo.c `pkg-config shishi --cflags --libs`
@end example

@node Autoconf tests
@subsection Autoconf tests
@cindex Autoconf tests
@cindex Configure tests

If you work on a project that uses Autoconf (@pxref{top, GNU
Autoconf,, autoconf}) to help find installed libraries, the
suggestions in the previous section are not the entire story.  There
are a few methods to detect and incorporate Shishi into your Autoconf
based package.  The preferred approach, is to use Libtool in your
project, and use the normal Autoconf header file and library tests.

@subsubsection Autoconf test via @samp{pkg-config}

If your audience is a typical GNU/Linux desktop, you can often assume
they have the @samp{pkg-config} tool installed, in which you can use
its Autoconf M4 macro to find and set up your package for use with
Shishi.  The following illustrate this scenario.

@example
AC_ARG_ENABLE(kerberos_v5,
	AC_HELP_STRING([--disable-kerberos_v5],
                       [don't use the KERBEROS_V5 mechanism]),
	kerberos_v5=$enableval)
if test "$kerberos_v5" != "no" ; then
	PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
			[kerberos_v5=yes],
                        [kerberos_v5=no])
	if test "$kerberos_v5" != "yes" ; then
		kerberos_v5=no
		AC_MSG_WARN([shishi not found, disabling Kerberos 5])
	else
		kerberos_v5=yes
		AC_DEFINE(USE_KERBEROS_V5, 1,
                          [Define to 1 if you want Kerberos 5.])
	fi
fi
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos_v5)
@end example

@subsubsection Standalone Autoconf test using Libtool

If your package uses Libtool(@pxref{top, GNU Libtool,, libtool}), you
can use the normal Autoconf tests to find the Shishi library and rely
on the Libtool dependency tracking to include the proper dependency
libraries (e.g., Libidn).  The following illustrate this scenario.

@example
AC_CHECK_HEADER(shishi.h,
	AC_CHECK_LIB(shishi, shishi_check_version,
		[kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
		kerberos5=no),
	kerberos5=no)
AC_ARG_ENABLE(kerberos5,
	AC_HELP_STRING([--disable-kerberos5],
                       [disable Kerberos 5 unconditionally]),
	kerberos5=$enableval)
if test "$kerberos5" != "no" ; then
	AC_DEFINE(USE_KERBEROS_V5, 1,
		  [Define to 1 if you want Kerberos 5.])
else
	AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
fi
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos5)
@end example

@subsubsection Standalone Autoconf test

If your package does not use Libtool, as well as detecting the Shishi
library as in the previous case, you must also detect whatever
dependencies Shishi requires to work (e.g., libidn).  Since the
dependencies are in a state of flux, we do not provide an example and
we do not recommend this approach, unless you are experienced
developer.

@node Initialization Functions
@section Initialization Functions

@include texi/init.c.texi
@include texi/cfg.c.texi


@node Ticket Set Functions
@section Ticket Set Functions

A ``ticket set'' is, as the name implies, a collection of tickets.
Functions are provided to read tickets from file into a ticket set, to
query number of tickets in the set, to extract a given ticket from the
set, to search the ticket set for tickets matching certain criterium,
to write the ticket set to a file, etc.  High level functions for
performing a initial authentication (@pxref{AS Functions}) or
subsequent authentication (@pxref{TGS Functions}) and storing the new
ticket in the ticket set are also provided.

To manipulate each individual ticket, @xref{Ticket Functions}.  For
low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.

@include texi/tkts.c.texi


@node AP-REQ and AP-REP Functions
@section AP-REQ and AP-REP Functions

The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
client and servers to prove to each other who they are.  The
structures contain auxilliary information, together with an
authenticator (@pxref{Authenticator Functions}) which is the real
cryptographic proof.  The following illustrates the AP-REQ and AP-REP
ASN.1 structures.

@verbatim
AP-REQ		::= [APPLICATION 14] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (14),
	ap-options	[2] APOptions,
	ticket		[3] Ticket,
	authenticator	[4] EncryptedData {Authenticator,
				{ keyuse-pa-TGSReq-authenticator
				  | keyuse-APReq-authenticator }}
}

AP-REP		::= [APPLICATION 15] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (15),
	enc-part	[2] EncryptedData {EncAPRepPart,
				{ keyuse-EncAPRepPart }}
}

EncAPRepPart	::= [APPLICATION 27] SEQUENCE {
	ctime		[0] KerberosTime,
	cusec		[1] Microseconds,
	subkey		[2] EncryptionKey OPTIONAL,
	seq-number	[3] UInt32 OPTIONAL
}
@end verbatim

@include texi/ap.c.texi
@include texi/apreq.c.texi
@include texi/aprep.c.texi
@include texi/encapreppart.c.texi


@node SAFE and PRIV Functions
@section SAFE and PRIV Functions

The ``KRB-SAFE'' is an ASN.1 structure used by application client and
servers to exchange integrity protected data.  The integrity
protection is keyed, usually with a key agreed on via the AP exchange
(@pxref{AP-REQ and AP-REP Functions}).  The following illustrates the
KRB-SAFE ASN.1 structure.

@verbatim
   KRB-SAFE        ::= [APPLICATION 20] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (20),
           safe-body       [2] KRB-SAFE-BODY,
           cksum           [3] Checksum
   }

   KRB-SAFE-BODY   ::= SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress,
           r-address       [5] HostAddress OPTIONAL
   }
@end verbatim

@include texi/safe.c.texi

The ``KRB-PRIV'' is an ASN.1 structure used by application client and
servers to exchange confidential data.  The confidentiality is keyed,
usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
AP-REP Functions}).  The following illustrates the KRB-PRIV ASN.1
structure.

@verbatim
   KRB-PRIV        ::= [APPLICATION 21] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (21),
                           -- NOTE: there is no [2] tag
           enc-part        [3] EncryptedData -- EncKrbPrivPart
   }

   EncKrbPrivPart  ::= [APPLICATION 28] SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress -- sender's addr --,
           r-address       [5] HostAddress OPTIONAL -- recip's addr
   }
@end verbatim

@include texi/priv.c.texi


@node Ticket Functions
@section Ticket Functions

A Ticket is an ASN.1 structured that can be used to authenticate the
holder to services.  It contain an encrypted part, which the ticket
holder cannot see, but can be encrypted by the service, and various
information about the user and service, including an encryption key to
use for the connection.  @xref{Ticket (ASN.1) Functions}, for more
details on the ASN.1 structure of a ticket.

@include texi/tkt.c.texi


@node AS Functions
@section AS Functions

The Authentication Service (AS) is used to get an initial ticket using
e.g. your password.  The following illustrates the AS-REQ and AS-REP
ASN.1 structures.

@verbatim
-- Request --

AS-REQ		::= KDC-REQ {10}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP		::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart	::= [APPLICATION 25] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}
@end verbatim

@include texi/as.c.texi


@node TGS Functions
@section TGS Functions

The Ticket Granting Service (TGS) is used to get subsequent tickets,
authenticated by other tickets (so called ticket granting tickets).
The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.

@verbatim
-- Request --

TGS-REQ		::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

TGS-REP		::= KDC-REP {13, EncTGSRepPart,
			{ keyuse-EncTGSRepPart-sesskey
			  | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncTGSRepPart	::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}
@end verbatim

@include texi/tgs.c.texi


@node Ticket (ASN.1) Functions
@section Ticket (ASN.1) Functions

@xref{Ticket Functions}, for an high-level overview of tickets.  The
following illustrates the Ticket and EncTicketPart ASN.1 structures.

@verbatim
Ticket          ::= [APPLICATION 1] SEQUENCE {
        tkt-vno         [0] INTEGER (5),
        realm           [1] Realm,
        sname           [2] PrincipalName,
        enc-part        [3] EncryptedData -- EncTicketPart
}

-- Encrypted part of ticket
EncTicketPart   ::= [APPLICATION 3] SEQUENCE {
        flags                   [0] TicketFlags,
        key                     [1] EncryptionKey,
        crealm                  [2] Realm,
        cname                   [3] PrincipalName,
        transited               [4] TransitedEncoding,
        authtime                [5] KerberosTime,
        starttime               [6] KerberosTime OPTIONAL,
        endtime                 [7] KerberosTime,
        renew-till              [8] KerberosTime OPTIONAL,
        caddr                   [9] HostAddresses OPTIONAL,
        authorization-data      [10] AuthorizationData OPTIONAL
}
@end verbatim

@include texi/ticket.c.texi
@include texi/encticketpart.c.texi

@node AS/TGS Functions
@section AS/TGS Functions

The Authentication Service (AS) is used to get an initial ticket using
e.g. your password.  The Ticket Granting Service (TGS) is used to get
subsequent tickets using other tickets.  Protocol wise the procedures
are very similar, which is the reason they are described together.
The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
ASN.1 structures.  Most of the functions use the mnemonic ``KDC''
instead of either AS or TGS, which means the function operates on both
AS and TGS types.  Only where the distinction between AS and TGS is
important are the AS and TGS names used.  Remember, these are
low-level functions, and normal applications will likely be satisfied
with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
Functions}) interface.

@verbatim
-- Request --

AS-REQ		::= KDC-REQ {10}
TGS-REQ		::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP		::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
TGS-REP		::= KDC-REP {13, EncTGSRepPart,
			{ keyuse-EncTGSRepPart-sesskey
			  | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart	::= [APPLICATION 25] EncKDCRepPart
EncTGSRepPart	::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}
@end verbatim

@include texi/kdc.c.texi
@include texi/kdcreq.c.texi
@include texi/kdcrep.c.texi
@include texi/enckdcreppart.c.texi


@node Authenticator Functions
@section Authenticator Functions

An ``Authenticator'' is an ASN.1 structure that work as a proof that
an entity owns a ticket.  It is usually embedded in the AP-REQ
structure (@pxref{AP-REQ and AP-REP Functions}), and you most likely
want to use an AP-REQ instead of a Authenticator in normal
applications.  The following illustrates the Authenticator ASN.1
structure.

@verbatim
Authenticator	::= [APPLICATION 2] SEQUENCE  {
	authenticator-vno	[0] INTEGER (5),
	crealm			[1] Realm,
	cname			[2] PrincipalName,
	cksum			[3] Checksum OPTIONAL,
	cusec			[4] Microseconds,
	ctime			[5] KerberosTime,
	subkey			[6] EncryptionKey OPTIONAL,
	seq-number		[7] UInt32 OPTIONAL,
	authorization-data	[8] AuthorizationData OPTIONAL
}
@end verbatim

@include texi/authenticator.c.texi


@node KRB-ERROR Functions
@section KRB-ERROR Functions

The ``KRB-ERROR'' is an ASN.1 structure that can be returned, instead
of, e.g., KDC-REP or AP-REP, to indicate various error conditions.
Unfortunately, the semantics of several of the fields are ill
specified, so the typically procedure is to extract ``e-text'' and/or
``e-data'' and show it to the user.  The following illustrates the
KRB-ERROR ASN.1 structure.

@verbatim
KRB-ERROR       ::= [APPLICATION 30] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (30),
        ctime           [2] KerberosTime OPTIONAL,
        cusec           [3] Microseconds OPTIONAL,
        stime           [4] KerberosTime,
        susec           [5] Microseconds,
        error-code      [6] Int32,
        crealm          [7] Realm OPTIONAL,
        cname           [8] PrincipalName OPTIONAL,
        realm           [9] Realm -- service realm --,
        sname           [10] PrincipalName -- service name --,
        e-text          [11] KerberosString OPTIONAL,
        e-data          [12] OCTET STRING OPTIONAL
}
@end verbatim

@include texi/krberror.c.texi

@node Cryptographic Functions
@section Cryptographic Functions

Underneath the high-level functions described earlier, cryptographic
operations are happening.  If you need to access these cryptographic
primitives directly, this section describes the functions available.

Most cryptographic operations need keying material, and cryptographic
keys have been isolated into it's own data structure
@code{Shishi_key}.  The following illustrates it's contents, but note
that you cannot access it's elements directly but must use the
accessor functions described below.

@verbatim
struct Shishi_key
{
  int type;    /* RFC 1510 encryption integer type */
  char *value; /* Cryptographic key data */
  int version; /* RFC 1510 ``kvno'' */
};
@end verbatim

All functions that operate on this data structure are described now.

@include texi/key.c.texi

Applications that run uninteractively may need keying material.  In
these cases, the keys are stored in a file, a file that is normally
stored on the local host.  The file should be protected from
unauthorized access.  The file is in ASCII format and contains keys as
outputed by @code{shishi_key_print}.  All functions that handle these
keys sets are described now.

@include texi/keys.c.texi

The previous functions require that the filename is known.  For some
applications, servers, it makes sense to provide a system default.
These key sets used by server applications are known as ``hostkeys''.
Here are the functions that operate on hostkeys (they are mostly
wrappers around generic key sets).

@include texi/hostkeys.c.texi

After creating the key structure, it can be used to encrypt and
decrypt data, calculate checksum on data etc.  All available functions
are described now.

@include texi/crypto.c.texi

An easier way to use encryption and decryption if your application
repeatedly calls, e.g., @code{shishi_encrypt_ivupdate}, is to use the
following functions.  They store the key, initialization vector, etc,
in a context, and the encryption and decryption operations update the
IV within the context automatically.

@include texi/crypto-ctx.c.texi

Also included in Shishi is an interface to the really low-level
cryptographic primitives.  They map directly on the underlying
cryptographic library used (i.e., Gnulib or Libgcrypt) and is used
internally by Shishi.

@include texi/low-crypto.c.texi


@node X.509 Functions
@section X.509 Functions

The functions described in this section are used by the STARTTLS
functionality, see @ref{Kerberos via TLS}.

@include texi/pki.c.texi


@node Utility Functions
@section Utility Functions

@include texi/realm.c.texi
@include texi/principal.c.texi
@include texi/authorize.c.texi
@include texi/gztime.c.texi
@include texi/password.c.texi
@include texi/resolv.c.texi


@node ASN.1 Functions
@section ASN.1 Functions

@include texi/asn1.c.texi


@node Error Handling
@section Error Handling
@cindex Error Handling

Most functions in `Libshishi' are returning an error if they fail.
For this reason, the application should always catch the error
condition and take appropriate measures, for example by releasing the
resources and passing the error up to the caller, or by displaying a
descriptive message to the user and cancelling the operation.

Some error values do not indicate a system error or an error in the
operation, but the result of an operation that failed properly.

@menu
* Error Values::                A list of all error values used.
* Error Functions::             Error handling related functions.
@end menu

@node Error Values
@subsection Error Values

Errors are returned as an @code{int}.  Except for the SHISHI_OK case,
an application should always use the constants instead of their
numeric value.  Applications are encouraged to use the constants even
for SHISHI_OK as it improves readability.  Possible values are:

@table @code
@item SHISHI_OK
This value indicates success.  The value of this error is guaranteed
to always be @code{0} so you may use it in boolean constructs.

@include shishi-api-error-labels.texi

@end table

@node Error Functions
@subsection Error Functions

@include texi/error.c.texi

@node Examples
@section Examples
@cindex Examples

This section will be extended to contain walk-throughs of example code
that demonstrate how `Shishi' is used to write your own applications
that support Kerberos 5.  The rest of the current section consists of
some crude hints for the example client/server applications that is
part of Shishi, taken from an email but saved here for lack of a
better place to put it.

There are two programs: 'client' and 'server' in src/.

The client output an AP-REQ, waits for an AP-REP, and then simply
reads data from stdin.

The server waits for an AP-REQ, parses it and prints an AP-REP, and
then read data from stdin.

Both programs accept a Kerberos server name as the first command line
argument.  Your KDC must know this server, since the client tries to
get a ticket for it (first it gets a ticket granting ticket for the
default username), and you must write the key for the server into
/usr/local/etc/shishi.keys on the Shishi format, e.g.:

@example
-----BEGIN SHISHI KEY-----
Keytype: 16 (des3-cbc-sha1-kd)
Principal: sample/latte.josefsson.org
Realm: JOSEFSSON.ORG
 
8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
-----END SHISHI KEY-----
@end example

You must extract the proper encryption key from the KDC in some way.
(This part will be easier when Shishi include a KDC, a basic one isn't
far away, give me a week or to.)

The intention is that the data read, after the authentication phase,
should be protected using KRB_SAFE (see RFC) but I haven't added this
yet.

@node Kerberos Database Functions
@section Kerberos Database Functions
@cindex Shisa API
@cindex Database interface

Shisa is a separate and standalone library from Shishi
(@pxref{Introduction to Shisa}).  If you only wish to manipulate the
information stored in the Kerberos user database used by Shishi, you
do not need to link or use the Shishi library at all.  However, you
may find it useful to combine the two libraries.

For two real world examples on using the Shisa library, refer to
@file{src/shisa.c} (Shisa command line tool) and @file{src/kdc.c}
(part of Shishid server).

Shisa uses two @samp{struct}s to carry information.  The first,
@code{Shisa_principal}, is used to hold information about principals.
The struct does not contain pointers to strings etc, so the library
assumes the caller is responsible for allocating and deallocating the
struct itself.  Each such struct is (uniquely) identified by the
combination of principal name and realm name.

@example
struct Shisa_principal
@{
  int isdisabled;
  uint32_t kvno;
  time_t notusedbefore;
  time_t lastinitialtgt;      /* time of last initial request for a TGT */
  time_t lastinitialrequest;  /* time of last initial request */
  time_t lasttgt;             /* time of issue for the newest TGT used */
  time_t lastrenewal;         /* time of the last renewal */
  time_t passwordexpire;      /* time when the password will expire */
  time_t accountexpire;       /* time when the account will expire. */
@};
typedef struct Shisa_principal Shisa_principal;
@end example

The second structure is called @code{Shisa_key} and hold information
about cryptographic keys.  Because the struct contain pointers, and
the caller cannot know how many keys a principal have, the Shisa
library manages memory for the struct.  The library allocate the
structs, and the pointers within them.  The caller may deallocate
them, but it is recommended to use @code{shisa_key_free} or
@code{shisa_keys_free} instead.  Note that each principal may have
multiple keys.

@example
struct Shisa_key
@{
  uint32_t kvno;
  int32_t etype;
  int priority;
  char *key;
  size_t keylen;
  char *salt;
  size_t saltlen;
  char *str2keyparam;
  size_t str2keyparamlen;
  char *password;
@};
typedef struct Shisa_key Shisa_key;
@end example

Shisa is typically initialized by calling @code{shisa_init}, and
deinitialized (when the application no longer need to use Shisa,
typically when it shuts down) by calling @code{shisa_done}, but here
are the complete (de)initialization interface functions.

@include texi/setup.c.texi

The default configuration file is typically read automatically by
calling @code{shisa_init}, but if you wish to manually access the
Shisa configuration file functions, here is the complete interface.

@include texi/config.c.texi

The core part of the Shisa interface follows.  The typical procedure
is to use @code{shisa_principal_find} to verify that a specific
principal exists, and to extract some information about it, and then
use @code{shisa_keys_find} to get the cryptographic keys for the
principal, usually suppliying some hints as to which of all keys you
are interested in (e.g., key version number and encryption algorithm
number).

@include texi/core.c.texi

Error handling is similar to that for Shishi in general (@pxref{Error
Handling}), i.e., you invoke @code{shisa_strerror} on the integer
return value received by some function, if the return value is
non-zero.  Below is the complete interface.

@include texi/err.c.texi

@node Generic Security Service
@section Generic Security Service
@cindex Generic Security Service
@cindex GSS-API
@cindex GSSLib

As an alternative to the native Shishi programming API, it is possible
to program Shishi through the Generic Security Services (GSS) API.
The advantage of using GSS-API in your security application, instead
of the native Shishi API, is that it will be easier to port your
application between different Kerberos 5 implementations, and even
beyond Kerberos 5 to different security systems, that support GSS-API.
In the free software world, however, almost the only widely used
security system that supports GSS-API is Kerberos 5, so the last
advantage is somewhat academic.  But if you are porting applications
using GSS-API for other Kerberos 5 implementations, or want a more
mature and stable API than the native Shishi API, you may find using
Shishi's GSS-API interface compelling.  Note that GSS-API only offer
basic services, for more advanced uses you must use the native API.

Since the GSS-API is not specific to Shishi, it is distributed
independently from Shishi.  Further information on the GSS project can
be found at @url{http://www.gnu.org/software/gss/}.

@c **********************************************************
@c *******************  Acknowledgements  *******************
@c **********************************************************
@node Acknowledgements
@chapter Acknowledgements

Shishi uses Libtasn1 by Fabio Fiorina, Libgcrypt and Libgpg-error by
Werner Koch, Libidn by Simon Josefsson, cvs2cl by Karl Fogel, and gdoc
by Michael Zucchi.

Several GNU packages simplified development considerably, those
packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
CVS, Texinfo, Help2man and Emacs.

Several people reported bugs, sent patches or suggested improvements,
see the file THANKS.

Nicolas Pouvesle wrote the section about the Kerberos rsh/rlogin
protocol.

This manual borrows text from the Kerberos 5 specification.

@c **********************************************************
@c *******************  Appendices  *************************
@c **********************************************************

@node Criticism of Kerberos
@appendix Criticism of Kerberos

The intention with this section is to discuss various problems with
Kerberos 5, so you can form a conscious decision how to deploy and use
Shishi correctly in your organization.  Currently the issues below are
condensed, and mostly serve as a reminder for the author to elaborate
on them.

No encryption scheme with security proof.

No standardized API, and GSS mechanism lack important functionality.

Lack of authorization system.  (krb5_kuserok())

Host to realm mapping relies on insecure DNS or static configuration
files.

Informational model and user database administration.

Non-formal specification.  Unclear on the etype to use for session
keys (etype in request or database?).  Unclear on how to populate some
``evident'' fields (e.g., cname in tickets for AS-REQ, or crealm,
cname, realm, sname, ctime and cusec in KRB-ERROR).  Unclear error
code semantics (e.g., logic for when to use S_PRINCIPAL_UNKNOWN
absent).  Some KRB-ERROR fields are required, but can't be usefully
populated in some situations, and no guidance is given on what they
should contain.

RFC 1510/1510bis incompatibilities.  NULL enctype removed without
discussion, and it is still used by some 1964 GSSAPI implementations.
KRB_SAFE text (3.4.1) says the checksum is generated using the session
or sub-session key, which contradicts itself (compare section 3.2.6)
and also RFC 1510, which both allow the application to define the key.
Verification of KRB_SAFE now require the key to be compatible with the
(sub-)session key, in 1510 the only requirement was that it was
collision proof.

Problems with RFC 1510bis.  Uses bignum INTEGER for TYPED-DATA and
AD-AND-OR.

Problems with crypto specification.  It uses the word ``random'' many
times, but there is no discussion on the randomness requirements.
Practical experience indicate it is impossible to use true randomness
for all ``random'' fields, and no implementation does this.  A post by
Don Davis on the ietf-krb-wg list tried to provide insight, but the
information was never added to the specification.

@node Protocol Extensions
@appendix Protocol Extensions

This appendix specifies the non-standard protocol elements implemented
by Shishi.  By nature of being non-standard, everything described here
is experimental.  Comments and feedback is appreciated.

@menu
* STARTTLS protected KDC exchanges::	How Shishi talks to KDC protected by TLS.
* Telnet encryption with AES-CCM::      Integrity and privacy protected telnet.
* Kerberized rsh and rlogin::           Description of KCMD protocol.
* Key as initialization vector::        Some cryptography discussion.
* The Keytab Binary File Format::       Format of keytab files.
* The Credential Cache Binary File Format:: Format of ccache files.
@end menu

@node STARTTLS protected KDC exchanges
@section STARTTLS protected KDC exchanges

Shishi is able to ``upgrade'' TCP communications with the KDC to use
the Transport Layer Security (TLS) protocol.  The TLS protocol offers
integrity and privacy protected exchanges.  TLS also offers
authentication using username and passwords, X.509 certificates, or
OpenPGP certificates.  Kerberos 5 claims to offer some of these
features, although it is not as rich as the TLS protocol.  An
inconclusive list of the motivation for using TLS is given below.

@itemize @bullet

@item Server authentication of the KDC to the client.
In traditional Kerberos 5, KDC authentication is only proved as a side
effect that the KDC knows your encryption key (i.e., your password).

@item Client authentication against KDC.
Kerberos 5 assume the user knows a key (usually in the form of a
password).  Sometimes external factors make this hard to fulfill.  In
some situations, users are equipped with smart cards with a RSA
authentication key.  In others, users have a OpenPGP client on their
desktop, with a public OpenPGP key known to the server.  In some
situations, the policy may be that password authentication may only be
done through SRP.

@item Kerberos exchanges are privacy protected.
Part of many Kerberos packets are transfered without privacy
protection (i.e., encryption).  That part contains information, such
as the client principal name, the server principal name, the
encryption types supported by the client, the lifetime of tickets,
etc.  Revealing such information is, in some threat models, considered
a problem.  Thus, this enables ``anonymity''.

@item Prevents downgrade attacks affecting encryption types.
The encryption type of the ticket in KDC-REQ are sent in the clear in
Kerberos 5.  This allows an attacker to replace the encryption type
with a compromised mechanisms, e.g. 56-bit DES.  Since clients in
general cannot know the encryption types other servers support, it is
difficult for the client to detect if there was a man-in-the-middle or
if the remote server simply did not support a stronger mechanism.
Clients may chose to refuse 56-bit DES altogether, but in some
environments this leads to operational difficulties.

@item TLS is well-proved and the protocol is studied by many parties.
This is an advantage in network design, where TLS is often already
assumed as part of the solution since it is used to protect HTTP,
IMAP, SMTP etc.  In some threat models, the designer prefer to reduce
the number of protocols that can hurt the overall system security if
they are compromised.

@end itemize

Other reasons for using TLS exists.

@subsection TCP/IP transport with TLS upgrade (STARTTLS)

RFC 1510bis requires Kerberos servers (KDCs) to accept TCP requests.
Each request and response is prefixed by a 4 octet integer in network
byte order, indicating the length of the packet.  The high bit of the
length was reserved for future expansion, and servers that do not
understand how to interpret a set high bit must return a
@code{KRB-ERROR} with a @code{KRB_ERR_FIELD_TOOLONG} and close the TCP
stream.

The TCP/IP transport with TLS upgrade (STARTTLS) uses this reserved
bit as follows.  First we define a new extensible typed hole for
Kerberos 5 messages, because we used the only reserved bit.  It is
thus prudent to offer future extensions on our proposal.  Secondly we
reserve two values in this new typed hole, and described how they are
used to implement STARTTLS.

@subsection Extensible typed hole based on reserved high bit

When the high bit is set, the remaining 31 bits of the 4 octets are
treated as an extensible typed hole, and thus form a 31 bit integer
enumerating various extensions.  Each of the values indicate a
specific extended operation mode, two of which are used and defined
here, and the rest are left for others to use.  If the KDC do not
understand a requested extension, it MUST return a @code{KRB-ERROR}
with a @code{KRB_ERR_FIELD_TOOLONG} value (prefixed by the 4 octet
length integer, with the high bit clear, as usual) and close the TCP
stream.

Meaning of the 31 lower bits in the 4 octet field, when the high bit
is set:

@verbatim
 0               RESERVED.
 1               STARTTLS requested by client.
 2               STARTTLS request accepted by server.
 3...2147483647  AVAILABLE for registration (via bug-shishi@josefsson.org).
 2147483648      RESERVED.
@end verbatim

@subsection STARTTLS requested by client (extension mode 1)

When this is sent by the client, the client is requesting the server
to start TLS negotiation on the TCP stream.  The client MUST NOT start
TLS negotiation immediately.  Instead, the client wait for either a
KRB-ERROR (sent normally, prefixed by a 4 octet length integer)
indicating the server do not understand the set high bit, or 4 octet
which is to interpreted as an integer in network byte order, where the
high bit is set and the remaining 31 bit are interpreted as an integer
specifying the ``STARTTLS request accepted by server''.  In the first
case, the client infer that the server do not understand (or wish to
support) STARTTLS, and can re-try using normal TCP, if unprotected
Kerberos 5 exchanges are acceptable to the client policy.  In the
latter case, it should invoke TLS negotiation on the stream.  If any
other data is received, the client MUST close the TCP stream.

@subsection STARTTLS request accepted by server (extension mode 2)

This 4 octet message should be sent by the server when it has received
the previous 4 octet message.  The message is an acknowledgment of the
client's request to initiate STARTTLS on the channel.  The server MUST
then invoke a TLS negotiation.

@subsection Proceeding after successful TLS negotiation

If the TLS negotiation ended successfully, possibly also considering
client or server policies, the exchange within the TLS protected
stream is performed like normal UDP Kerberos 5 exchanges, i.e., there
is no TCP 4 octet length field before each packet.  Instead each
Kerberos packet MUST be sent within one TLS record, so the application
can use the TLS record length as the Kerberos 5 packet length.

@subsection Proceeding after failed TLS negotiation

If the TLS negotiation fails, possibly due to client or server policy
(e.g., inadequate support of encryption types in TLS, or lack of
client or server authentication) the entity that detect the failure
MUST disconnected the connection.  It is expected that any error
messages that explain the error condition is transfered by TLS.

@subsection Interaction with KDC addresses in DNS

Administrators for a KDC may announce the KDC address by placing SRV
records in DNS for the realm, as described in
@file{draft-ietf-krb-wg-krb-dns-locate-03.txt}.  That document mention
TLS, but do not reference any work that describe how KDCs uses TLS.
Until further clarified, consider the TLS field in that document to
refer to implementation supporting this STARTTLS protocol.

@subsection Using TLS authentication logic in Kerberos

The server MAY consider the authentication performed by the TLS
exchange as sufficient to issue Kerberos 5 tickets to the client,
without requiring, e.g., pre-authentication.  However, it is not an
error to require or use pre-authentication as well.

The client may also indicate that it wishes to use TLS both for
authentication and data protection by using the @samp{NULL} encryption
type in its request.  The server can decide from its local policy
whether or not issuing tickets based solely on TLS authentication, and
whether @samp{NULL} encryption within TLS, is acceptable or not.  This
mode is currently under investigation.

@subsection Security considerations

Because the initial token is not protected, it is possible for an
active attacker to make it appear to the client that the server do not
support this extension.  It is up to client configuration to disallow
non-TLS connections, if this vulnerability is deemed unacceptable.
For interoperability, we suggest the default behaviour should be to
allow automatic fallback to TCP or UDP.

The security considerations of both TLS and Kerberos 5 are inherited.
Using TLS for authentication and/or data protection together with
Kerberos alter the authentication logic fundamentally.  Thus, it may
be that even if the TLS and Kerberos 5 protocols and implementations
were secure, the combination of TLS and Kerberos 5 described here
could be insecure.

No channel bindings are provided in the Kerberos messages.  It is an
open question whether, and how, this should be fixed.

@node Telnet encryption with AES-CCM
@section Telnet encryption with AES-CCM

This appendix describe how Shishi use the Advanced Encryption Standard
(AES) encryption algorithm in Counter with CBC-MAC mode (RFC 3610)
with the telnet encryption option (RFC 2946).

@subsection Command Names and Codes

@verbatim
Encryption Type

      AES_CCM             12

Suboption Commands

      AES_CCM_INFO         1
      AES_CCM_INFO_OK      2
      AES_CCM_INFO_BAD     3
@end verbatim

@subsection Command Meanings

@verbatim
   IAC SB ENCRYPT IS AES_CCM AES_CCM_INFO <M> <L> <nonce> IAC SE
@end verbatim

The sender of this command select desired M and L parameters, and
nonce, as described in RFC 3610, and sends it to the other side of the
connection.  The parameters and the nonce are sent in clear text.
Only the side of the connection that is WILL ENCRYPT may send the
AES_CCM_INFO command.

@verbatim
   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_BAD IAC SE
@end verbatim

The sender of this command reject the parameters received in the
AES_CCM_INFO command.  Only the side of the connection that is DO
ENCRYPT may send the AES_CCM_INFO_BAD command.  The command MUST be
sent if the nonce field length does not match the selected value for
L.  The command MAY be sent if the receiver do not accept the
parameters for reason such as policy.  No capability is provided to
negotiate these parameters.

@verbatim
   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_OK IAC SE
@end verbatim

The sender of this command accepts the parameters received in the
AES_CCM_INFO command.  Only the side of the connection that is DO
ENCRYPT may send the AES_CCM_INFO_BAD command.  The command MUST NOT
be sent if the nonce field length does not match the selected value
for L.

@subsection Implementation Rules

Once a AES_CCM_INFO_OK command has been received, the WILL ENCRYPT
side of the connection should do keyid negotiation using the ENC_KEYID
command.  Once the keyid negotiation has successfully identified a
common keyid, then START and END commands may be sent by the side of
the connection that is WILL ENCRYPT.  Data will be encrypted using the
AES-CCM algorithm, with the negotiated nonce and parameters M and L.
After each successful encryption and decryption, the nonce is treated
as an integer in network byte order, and incremented by one.

If encryption (decryption) is turned off and back on again, and the
same keyid is used when re-starting the encryption (decryption), the
intervening clear text must not change the state of the encryption
(decryption) machine.  In particular, the AES-CCM nonce must not be
re-set.

If a START command is sent (received) with a different keyid, the
encryption (decryption) machine must be re-initialized immediately
following the end of the START command with the new key and the
parameters sent (received) in the last AES_CCM_INFO command.

If a new AES_CCM_INFO command is sent (received), and encryption
(decryption) is enabled, the encryption (decryption) machine must be
re-initialized immediately following the end of the AES_CCM_INFO
command with the new nonce and parameters, and the keyid sent
(received) in the last START command.

If encryption (decryption) is not enabled when a AES_CCM_INFO command
is sent (received), the encryption (decryption) machine must be re-
initialized after the next START command, with the keyid sent
(received) in that START command, and the nonce and parameters sent
(received) in this AES_CCM_INFO command.

At all times MUST each end make sure that a AES-CCM nonce is not used
twice under the same encryption key.  The rules above help accomplish
this in an interoperable way.

@subsection Integration with the AUTHENTICATION telnet option

<<This section is slightly complicated.  Can't we simplify this?>>

As noted in the telnet ENCRYPTION option specifications, a keyid value
of zero indicates the default encryption key, as might be derived from
the telnet AUTHENTICATION option.  If the default encryption key
negotiated as a result of the telnet AUTHENTICATION option contains
less than 32 bytes (corresponding to two 128 bit keys), then the
AES_CCM option MUST NOT be offered or used as a valid telnet
encryption option.  Furthermore, depending on policy for key lengths,
the AES_CCM option MAY be disabled if the default encryption key
contain less than 48 bytes (for two 192 bit keys), or less than 64
bytes (for two 256 bit keys), as well.

The available encrypt key data is divided on two halves, where the
first half is used to encrypt data sent from the server (decrypt data
received by the client), and the second half is used to encrypt data
sent from the client (decrypt data received by the server).

Note that the above algorithm assumes that the AUTHENTICATION
mechanism generate keying material suitable for AES-CCM as used in
this specification.  This is not necessarily true in general, but we
specify this behaviour as the default since it is true for most
authentication systems in popular use today.  New telnet
AUTHENTICATION mechanisms may specify alternative methods for
determining the keys to be used for this cipher suite in their
specification, if the session key negotiated by that authentication
mechanism is not a DES key and and where this algorithm may not be
safely used.

Kerberos 5 authentication clarification: The key used to encrypt data
from the client to the server is taken from the sub-session key in the
AP-REQ.  The key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REP.  If mutual
authentication is not negotiated, the key used to encrypt data from
the client to the server is taken from the session key in the ticket,
and the key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REQ.  Leaving the AP-REQ
sub-key field empty MUST disable the AES_CCM option.

@subsection Security Considerations

The protocol must be properly and securely implemented.  For example,
an implementation should not be vulnerable to various
implementation-specific attacks such as buffer overflows or
side-channel analysis.

We wish to repeat the suggestion from RFC 2946, to investigate in a
STARTTLS approach for Telnet encryption (and also authentication),
when the security level provided by this specification is not
adequate.

@subsubsection Telnet Encryption Protocol Security Considerations

The security consideration of the Telnet encryption protocol are
inherited.

It should be noted that the it is up to the authentication protocol
used, if any, to bind the authenticity of the peers to a specific
session.

The Telnet encryption protocol does not, in general, protect against
possibly malicious downgrading to any mutually acceptable, but not
preferred, encryption type.  This places a requirement on each peer to
only accept encryption types it trust fully.  In other words, the
Telnet encryption protocol do not guarantee that the strongest
mutually acceptable encryption type is always selected.

@subsubsection AES-CCM Security Considerations

The integrity and privacy claims are inherited from AES-CCM.  In
particular, the implementation must make sure a nonce is not used more
than once together with the same key.

Furthermore, the encryption key is assumed to be random, i.e., it
should not be possible to guess it with probability of success higher
than guessing any uniformly selected random key.  RFC 1750 gives an
overview of issues and recommendations related to randomness.

@subsection Acknowledgments

This document is based on the various Telnet Encryption RFCs (RFC
2946, RFC 2947, RFC 2948, RFC 2952 and RFC 2953).

@node Kerberized rsh and rlogin
@section Kerberized rsh and rlogin

This appendix describe the KCMDV0.2 protocol used in shishi patched
version of inetutils. The KCMD protocol was developped by the MIT
Kerberos team for kerberized rsh an rlogin programs. Differences
between rlogin an rsh will be explained, like those between v0.1 and
v0.2 of the protocol for compatibility reasons.
It is possible that some parts of this document are not in conformity
with original KCMD protocol because there is no official specification
about it. However, it seems that shishi implementation is compatible
with MIT's one.

@strong{Warning:} If you are seriously considering using Kerberos rsh
or rlogin, instead of more robust remote access protocols such as
SSH, you may first want to explore
@url{http://www.cs.berkeley.edu/~hildrum/kerberos/} and the full paper
at @url{http://www.cs.berkeley.edu/~hildrum/043.pdf}.

@subsection Establish connection

First the client should establish a TCP connection with the
server. Default ports are 543 (klogin), 544 (kshell), 2105 (eklogin).
eklogin is the same as klogin but with encryption. Their is no longer
ekshell port because encrypted and normal connection use the same port
(kshell).
Kshell need a second connection for stderr. The client should send a
null terminated string that represent the port of this second
connection.
Klogin and eklogin does not use a second connection for stderr so the
client must send a null byte to the server.
Contrary to classic rsh/rlogin, server must not check if the client
port is in the range 0-1023. 

@subsection Kerberos identification

When connections are established, first thing to do is to indicate
kerberos authentication must be used.
So the client will send a string to indicate it will used kerberos
5. It will call a length-string "strl" the couple (lenght of the string
strl, null terminated string strl). Length of the string is an int32
(32bits int) in MSB order (for the network).
So the client send this length-string strl :

@verbatim
   KRB5_SENDAUTH_V1.0
@end verbatim

After that the client must indicate which version of the protocol it
will used by sending this length-string strl :

@verbatim
   KCMDV0.2
@end verbatim

It can be V0.1 for older versions.
If indentification from client is good, server will send a null
byte (0x00). Else if authentication message is wrong, server send byte
0x01, else if protocol version message is wrong server send byte 0x02.

@subsection Kerberos authentication

When client is indentified, kerberos authentication can begin. The
client must send an AP-REQ to the server. AP-REQ authenticator must
have a subkey (only for KCMDV0.2) and a checksum.
Authenticator checksum is created on following string :

@example
"serverport:""terminaltype""remoteusername"
@end example

for example :

@example
543:linux/38400user
@end example

remoteusername corresponds to the identity of the client on remote machine.

AP-REQ is sended in der encoded format. The length (int32) of der
encoded AP-REQ is sended in network format (MSB), following by the der
encoded AP-REQ.
If all is correct, server send a null int32 (MSB format but like it is
null it is not important).
KCMD protocol use mutual authentication, so server must now send and
AP-REP : (in32 lenght in MSB of der encoded AP-REP)(der encoded
AP-REP).

Now server and client are partially authenticated.

@subsection Extended authentication

Client must now send 3 different null terminated strings (without
lenght) :

@itemize
@item remote user name (user identity on remote machine)
@item terminal type for rlogin or command for rsh
@item local user name (user identity on client machine)
@end itemize

example for rsh :

@example
"rname\0"
"cat /usr/local/etc/shishi.conf"
"lname\0"
@end example

Server must verify that checksum in AP-REQ authenticator is correct by
computing a new hash like client has done.

Server must verify that principal (in AP-REQ) has right to log in on
the remote user account.
For the moment shishi only check if remote user name is equal to
principal. A more complex authorization code is planned.
Look at the end to know how MIT/Heimdal do to check authorization.

If all is correct server send a null byte, else an error message
string (null terminated string) is sent. User read the first byte. If
it is equal to zero, authentication is correct and is logged on the
remote host. Else user can read the error messsage send by the server.

@subsection Window size

For rlogin protocol, when authentication is complete, the server can
optionnaly send a message to ask for window terminal size of
user. Then the user can respond but it is not an obligation.

In KCMDV0.1 server send an urgent TCP message (MSG_OOB) with one byte
:

@example
TIOCPKT_WINDOW = 0x80
@end example

In KCMDV0.2 server does not send an urgent message but write on the
socket 5 bytes :

@example
'\377', '\377', 'o', 'o', TIOCPKT_WINDOW
@end example

If encryption is enabled (eklogin) server must send this 5 bytes
encrypted.

Client can answer in both protocol version with :
       
@example
'\377', '\377', 's', 's', "struct winsize"
@end example

The winsize structure is filled with corresponding setting to client's
terminal.
If encryption is enabled this answer must be send encrypted.

@subsection End of authentication

The "classic" rsh/rlogin can be used now.


@subsection Encryption

Encryption mode is used when a connection with eklogin is established.
Encryption with krsh can be used too. Before, there was a specific port
for that (ekshell), but now to indicate that encryption must be used with
krsh, client must add "-x " before the command when it send it between
remote user name and local user name.
When the client compute the checksum for AP-REQ authenticator the "-
x" must not be included.

Encryption in KCMDV0.2 is not the same as in KCMDV0.1. 
KCMDV0.1 uses ticket session key as encryption key, and use standard
Kerberos encryption functions. This protocol only supports des-cbc-crc,
des-cbc-md4, des-cbc-md5 and does not use initialisation vectors.

For example on each encryption/decryption calls, the following
prototype kerberos function should be used :
	 
@example
kerberos_encrypt (key, keyusage, in, out)  (or decrypt)
@end example

KCMDV0.2 can be used with all kerberos encryption modes (des, 3des,
aes, arcfour) and use AP-REQ authenticator subkey. In opposite to
KCMDV0.1 initialisation vectors are used. All encryptions/descryptions
must be made using a cryptographic context (for example to use the
updated iv, or sbox) :

@example
kerberos_init(ctx, iv, key, keyusage)
kerberos_encrypt (ctx, in, out)
@end example

For both protocols, keyusage id for des-cbc-md5, des-cbc-md4,
des-cbc-crc and des3-cbc-sha1 (for KCMDV0.2) :
	
@example    
keyusage = 1026
@end example

For other KCMDV0.2 modes keyusage is different for each
encryption/decryption usage.
To understand, eklogin use 1 socket. It encrypts data (output 1) to
send and decrypts (input 1) received data.
Kshell use 2 sockets (1 for transmit data, 1 for stderr). So there are
four modes :
     
@verbatim
   transmit  : input  1 
	       output 1

   stderr    : input  2
	       output 2
@end verbatim

There is a keyusage for each modes. The keyusage must correspond on
client and server side. For example in klogin client input 1 keyusage
will be server output 1 keyusage.

@multitable @columnfractions .15 .15 .15
@item I/O @tab Client @tab Server
@item intput 1 @tab 1028 @tab 1030
@item output 1 @tab 1030 @tab 1028
@item intput 2 @tab 1032 @tab 1034
@item output 2 @tab 1034 @tab 1032
@end multitable

Those keyusages must be used with AES and ARCFOUR modes.

KCMDV0.2 uses IV (initialisation vector). Like for keyusage, client IV
must correspond to server IV. IV size is equal to key type,
blocksize. All bytes of IV must be initialised to :

@multitable @columnfractions .15 .15 .15
@item I/O @tab Client @tab Server
@item intput 1 @tab 0 @tab 1
@item output 1 @tab 1 @tab 0
@item intput 2 @tab 2 @tab 3
@item output 2 @tab 3 @tab 2
@end multitable

ARCFOUR mode does not use IV. However, like it is said before, a context
must be used to keep the updated sbox.

Normal message with klogin and kshell are sent like that :

@example
(int 32 lenght of message in MSB order)
(message)
@end example

In encrypted mode it is a bit different :

@example
(int 32 length of unencrypted message in MSB order)
(encrypted message)
@end example

In KCMDV0.2 encrypted message is create like that :

@example
encrypt (
(int 32 length of message in MSB order)
(message)
)
@end example

A check on message size can be made in second version of the protocol.

@subsection  KCMDV0.3


This part only gives possible ways to extend KCMD protocol. Does not
take that as must have in KCMD implementation.

Extensions of KCMV0.2 could be made. For example kshell supposes there
are no files with name "-x *". I think the same thing can be supposed
with terminal name for klogin. So client could add "-x " to terminal
type it sends to server to indicate it will use encryption. Like that
there will be only one port for klogin/eklogin : 543.

In encrypted mode kshell send command in clear on the network, this
could be considered as insecure as user have decided to use
encryption.
This is not really a problem for klogin because it just sends terminal
type.

In encrypted mode, klogin and kshell clients could only send "-x" as
command or terminal type.
After that encryption is activated, and the client could send terminal
type or command encrypted.
The server will send the null byte to say that all is correct, or
error message in encrypted form.

@subsection MIT/Heimdal authorization

This part describes how MIT/Heimdal version check authorization of the
user to log in on the remote machine.

Authorization check is made by looking if the file .k5login exists on
the account of the remote user.
If this file does not exist, remote user name must be the same as
principal in AP-REQ to valid authorization.
Else if this file exists, check first verify that remote user or root
are the owner of .k5login.
If it is not the case, the check fails.
If it is good, check reads each line of that file and compare each
readed name to principal.
If principal is found in .k5login, authorization is valid, else user
is not allowed to connect on remote host with the specified remote
user name (that can be the same as principal).

So someone (for example user "user1") can remote log into "user2"
account if .k5login is present in user2 home dir and this file is owned
by user2 or root and user1 name is present in this file.

@node Key as initialization vector
@section Key as initialization vector

The @code{des-cbc-crc} algorithm (@pxref{Cryptographic Overview}) uses
the DES key as the initialization vector.  This is problematic in
general (see below@footnote{The post is copyrighted by David Wagner,
included here with permission, the canonical location is
@url{http://www.cs.berkeley.edu/~daw/my-posts/key-as-iv-broken}}), but
may be mitigated in Kerberos by the CRC checksum that is also
included.

@verbatim
From daw@espresso.CS.Berkeley.EDU Fri Mar  1 13:32:34 PST 1996
Article: 50440 of sci.crypt
Path: agate!daw
From: daw@espresso.CS.Berkeley.EDU (David A Wagner)
Newsgroups: sci.crypt
Subject: Re: DES-CBC and Initialization Vectors
Date: 29 Feb 1996 21:48:16 GMT
Organization: University of California, Berkeley
Lines: 31
Message-ID: <4h56v0$3no@agate.berkeley.edu>
References: <4h39li$33o@gaia.ns.utk.edu>
NNTP-Posting-Host: espresso.cs.berkeley.edu

In article <4h39li$33o@gaia.ns.utk.edu>,
Nair Venugopal <venu@mars.utcc.utk.edu> wrote:
> Is there anything wrong in using the key as the I.V. in DES-CBC mode?

Yes, you're open to a chosen-ciphertext attack which recovers the key.

Alice is sending stuff DES-CBC encrypted with key K to Bob.  Mary is an
active adversary in the middle.  Suppose Alice encrypts some plaintext
blocks P_1, P_2, P_3, ... in DES-CBC mode with K as the IV, and sends off
the resulting ciphertext
	A->B: C_1, C_2, C_3, ...
where each C_j is a 8-byte DES ciphertext block.  Mary wants to discover
the key K, but doesn't even know any of the P_j's.  She replaces the above
message by
	M->B: C_1, 0, C_1
where 0 is the 8-byte all-zeros block.  Bob will decrypt under DES-CBC,
recovering the blocks
	Q_1, Q_2, Q_3
where
	Q_1 = DES-decrypt(K, C_1) xor K = P_1
	Q_2 = DES-decrypt(K, C_2) xor C_1 = (some unimportant junk)
	Q_3 = DES-decrypt(K, C_1) xor 0 = P_1 xor K
Bob gets this garbage-looking message Q_1,Q_2,Q_3 which Mary recovers
(under the chosen-ciphertext assumption: this is like a known-plaintext
attack, which isn't too implausible).  Notice that Mary can recover K by
	K = Q_1 xor Q_3;
so after this one simple active attack, Mary gets the key back!

So, if you must use a fixed IV, don't use the key-- use 0 or something
like that.  Even better, don't use a fixed IV-- use the DES encryption
of a counter, or something like that.
@end verbatim

@node The Keytab Binary File Format
@section The Keytab Binary File Format

The keytab file format is described in the file @file{keytab.txt},
included in verbatim below.

@verbatiminclude keytab.txt

@node The Credential Cache Binary File Format
@section The Credential Cache Binary File Format

The credential cache file format is described in the file
@file{keytab.txt}, included in verbatim below.

@verbatiminclude ccache.txt

@node Copying Information
@appendix Copying Information

@menu
* GNU Free Documentation License::   License for copying this manual.
* GNU GPL::                          License for copying the programs.
@end menu

@node GNU Free Documentation License
@appendixsec GNU Free Documentation License

@cindex FDL, GNU Free Documentation License

@include fdl-1.3.texi

@node GNU GPL
@appendixsec GNU General Public License
@cindex GPL, GNU General Public License
@cindex License, GNU GPL

@include gpl-3.0.texi

@node Function and Data Index
@unnumbered Function and Data Index

@printindex fn

@node Concept Index
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye