aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/security/chapter.xml
blob: df1fa9b1d064f82c3877ac0de3c951deb788aa49 (plain) (blame)
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
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="security">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Matthew</firstname>
	<surname>Dillon</surname>
	<contrib>Much of this chapter has been taken from the
	  security(7) manual page by </contrib>
      </author>
    </authorgroup>
  </chapterinfo>

  <title>Security</title>

  <indexterm><primary>security</primary></indexterm>

  <sect1 id="security-synopsis">
    <title>Synopsis</title>

    <para>This chapter provides a basic introduction to system
      security concepts, some general good rules of thumb, and some
      advanced topics under &os;.  Many of the topics covered here
      can be applied to system and Internet security in general.
      Securing a system is imperative to protect data, intellectual
      property, time, and much more from the hands of hackers and the
      like.</para>

    <para>&os; provides an array of utilities and mechanisms to
      protect the integrity and security of the system and
      network.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>Basic &os; system security concepts.</para>
      </listitem>

      <listitem>
	<para>The various crypt mechanisms available in &os;.</para>
      </listitem>

      <listitem>
	<para>How to set up one-time password authentication.</para>
      </listitem>

      <listitem>
	<para>How to configure <acronym>TCP</acronym> Wrappers for use
	  with &man.inetd.8;.</para>
      </listitem>

      <listitem>
	<para>How to set up <application>Kerberos</application> on
	  &os;.</para>
      </listitem>

      <listitem>
	<para>How to configure IPsec and create a
	  <acronym>VPN</acronym>.</para>
      </listitem>

      <listitem>
	<para>How to configure and use
	  <application>OpenSSH</application> on &os;.</para>
      </listitem>

      <listitem>
	<para>How to use filesystem <acronym>ACL</acronym>s.</para>
      </listitem>

      <listitem>
	<para>How to use <application>portaudit</application> to
	  audit third party software packages installed from the
	  Ports Collection.</para>
      </listitem>

      <listitem>
	<para>How to utilize &os; security advisories.</para>
      </listitem>

      <listitem>
	<para>What Process Accounting is and how to enable it on
	  &os;.</para>
      </listitem>

      <listitem>
	<para>Understand the resource limits database and
	  how to utilize it to control user resources.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Understand basic &os; and Internet concepts.</para>
      </listitem>
    </itemizedlist>

    <para>Additional security topics are covered elsewhere in this
      Handbook.  For example, Mandatory Access Control is discussed in
      <xref linkend="mac"/> and Internet firewalls are discussed in
      <xref linkend="firewalls"/>.</para>
  </sect1>

  <sect1 id="security-intro">
    <title>Introduction</title>

    <para>Security is a function that begins and ends with the system
      administrator.  While &os; provides some inherent security, the
      job of configuring and maintaining additional security
      mechanisms is probably one of the single largest undertakings of
      the sysadmin.</para>

    <para>System security also pertains to dealing with various forms
      of attack, including attacks that attempt to crash, or otherwise
      make a system unusable, but do not attempt to compromise the
      <username>root</username> account.  Security concerns can be
      split up into several categories:</para>

    <orderedlist>
      <listitem>
	<para>Denial of service attacks.</para>
      </listitem>

      <listitem>
	<para>User account compromises.</para>
      </listitem>

      <listitem>
	<para>Root compromise through accessible services.</para>
      </listitem>

      <listitem>
	<para>Root compromise via user accounts.</para>
      </listitem>

      <listitem>
	<para>Backdoor creation.</para>
      </listitem>
    </orderedlist>

    <indexterm>
      <primary>DoS attacks</primary>
      <see>Denial of Service (DoS)</see>
    </indexterm>
    <indexterm>
      <primary>security</primary>
      <secondary>DoS attacks</secondary>
      <see>Denial of Service (DoS)</see>
    </indexterm>
    <indexterm><primary>Denial of Service (DoS)</primary></indexterm>

    <para>A Denial of Service <acronym>DoS</acronym> attack is an
      action that deprives the machine of needed resources.
      Typically, <acronym>DoS</acronym> attacks are brute-force
      mechanisms that attempt to crash or otherwise make a machine
      unusable by overwhelming its services or network stack.  Attacks
      on servers can often be fixed by properly specifying options to
      limit the load the servers incur on the system under adverse
      conditions.  Brute-force network attacks are harder to deal
      with.  This type of attack may not be able to take the machine
      down, but it can saturate the Internet connection.</para>

    <indexterm>
      <primary>security</primary>
      <secondary>account compromises</secondary>
    </indexterm>

    <para>A user account compromise is more common than a
      <acronym>DoS</acronym> attack.  Many sysadmins still run
      unencrypted services, meaning that users logging into the
      system from a remote location are vulnerable to having their
      password sniffed.  The attentive sysadmin analyzes the remote
      access logs looking for suspicious source addresses and
      suspicious logins.</para>

    <para>In a well secured and maintained system, access to a user
      account does not necessarily give the attacker access to
      <username>root</username>.  Without <username>root</username>
      access, the attacker cannot generally hide his tracks and may,
      at best, be able to do nothing more than mess with the user's
      files or crash the machine.  User account compromises are common
      because users tend not to take the precautions that sysadmins
      take.</para>

    <indexterm>
      <primary>security</primary>
      <secondary>backdoors</secondary>
    </indexterm>

    <para>There are potentially many ways to break
      <username>root</username>:  the attacker may know the
      <username>root</username> password, the attacker may exploit a
      bug in a service which runs as <username>root</username>, or the
      attacker may know of a bug in a SUID-root program.  An attacker
      may utilize a program known as a backdoor to search for
      vulnerable systems, take advantage of unpatched exploits to
      access a system, and hide traces of illegal activity.</para>

    <para>Security remedies should always be implemented with a
      multi-layered <quote>onion peel</quote> approach and can be
      categorized as follows:</para>

    <orderedlist>
      <listitem>
	<para>Secure <username>root</username> and staff
	  accounts.</para>
      </listitem>

      <listitem>
	<para>Secure <username>root</username>&ndash;run servers
	  and SUID/SGID binaries.</para>
      </listitem>

      <listitem>
	<para>Secure user accounts.</para>
      </listitem>

      <listitem>
	<para>Secure the password file.</para>
      </listitem>

      <listitem>
	<para>Secure the kernel core, raw devices, and
	  filesystems.</para>
      </listitem>

      <listitem>
	<para>Quick detection of inappropriate changes made to the
	  system.</para>
      </listitem>

      <listitem>
	<para>Paranoia.</para>
      </listitem>
    </orderedlist>

    <para>The next section covers these items in greater depth.</para>
  </sect1>

  <sect1 id="securing-freebsd">
    <title>Securing &os;</title>

    <indexterm>
      <primary>security</primary>
      <secondary>securing &os;</secondary>
    </indexterm>

    <para>This section describes methods for securing a &os; system
      against the attacks that were mentioned in the <link
	linkend="security-intro">previous section</link>.</para>

    <sect2 id="securing-root-and-staff">
      <title>Securing the <username>root</username> Account</title>

      <indexterm>
	<primary>&man.su.1;</primary>
      </indexterm>

      <para>Most
	systems have a password assigned to the
	<username>root</username> account.  Assume that this password
	is <emphasis>always</emphasis> at risk of being compromised.
	This does not mean that the password should be disabled as the
	password is almost always necessary for console access to the
	machine.  However, it should not be possible to use this
	password outside of the console or possibly even with
	&man.su.1;.  For example, setting the entries in
	<filename>/etc/ttys</filename> to <literal>insecure</literal>
	prevents <username>root</username> logins to the specified
	terminals.  In &os;, <username>root</username> logins using
	&man.ssh.1; are disabled by default as
	<literal>PermitRootLogin</literal> is set to
	<literal>no</literal> in
	<filename>/etc/ssh/sshd_config</filename>.  Consider every
	access method as services such as FTP often fall through the
	cracks.  Direct <username>root</username> logins should only
	be allowed via the system console.</para>

      <indexterm>
	<primary><groupname>wheel</groupname></primary>
      </indexterm>

      <para>Since a sysadmin needs access to
	<username>root</username>, additional password verification
	should be configured.  One method is to add appropriate user
	accounts to <groupname>wheel</groupname> in
	<filename>/etc/group</filename>.  Members of
	<groupname>wheel</groupname> are allowed to &man.su.1; to
	<username>root</username>.  Only those users who actually need
	to have <username>root</username> access should be placed in
	<groupname>wheel</groupname>.  When using Kerberos for
	authentication, create a <filename>.k5login</filename> in
	the home directory of <username>root</username> to allow
	&man.ksu.1; to be used without having to place anyone in
	<groupname>wheel</groupname>.</para>

      <para>To lock an account completely, use &man.pw.8;:</para>

      <screen>&prompt.root; <userinput>pw lock <replaceable>staff</replaceable></userinput></screen>

      <para>This will prevent the specified user from logging in using
	any mechanism, including &man.ssh.1;.</para>

      <para>Another method of blocking access to accounts would be to
	replace the encrypted password with a single
	<quote><literal>*</literal></quote> character.  This character
	would never match the encrypted password and thus blocks user
	access.  For example, the entry for the following
	account:</para>

      <programlisting>foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>

      <para>could be changed to this using &man.vipw.8;:</para>

      <programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>

      <para>This prevents <username>foobar</username> from logging in
	using conventional methods.  This method for access
	restriction is flawed on sites using
	<application>Kerberos</application> or in situations where the
	user has set up keys with &man.ssh.1;.</para>

      <para>These security mechanisms assume that users are logging
	in from a more restrictive server to a less restrictive
	server.  For example, if the server is running network
	services, the workstation should not be running any.  In
	order for a workstation to be reasonably secure, run zero or
	as few services as possible and run a password-protected
	screensaver.  Of course, given physical access to any system,
	an attacker can break any sort of security.  Fortunately,
	many break-ins occur remotely, over a network, from people who
	do not have physical access to the system.</para>

      <para>Using Kerberos provides the ability to disable or change
	the password for a user in one place, and have it immediately
	affect all the machines on which the user has an account.  If
	an account is compromised, the ability to instantly change the
	associated password on all machines should not be underrated.
	Additional restrictions can be imposed with Kerberos:  a
	Kerberos ticket can be configured to timeout and the Kerberos
	system can require that the user choose a new password after a
	configurable period of time.</para>
    </sect2>

    <sect2>
      <title>Securing Root-run Servers and SUID/SGID Binaries</title>

      <indexterm>
	<primary>sandboxes</primary>
      </indexterm>
      <indexterm>
	<primary>&man.sshd.8;</primary>
      </indexterm>

      <para>The prudent sysadmin only enables required services and is
	aware that third party servers are often the most bug-prone.
	Never run a server that has not been checked out carefully.
	Think twice before running any service as
	<username>root</username> as many daemons can be run as a
	separate service account or can be started in a
	<firstterm>sandbox</firstterm>.  Do not activate insecure
	services such as &man.telnetd.8; or &man.rlogind.8;.</para>

      <para>Another potential security hole is SUID-root and SGID
	binaries.  Most of these binaries, such as &man.rlogin.1;,
	reside in <filename class="directory">/bin</filename>,
	<filename class="directory">/sbin</filename>, <filename
	  class="directory">/usr/bin</filename>, or <filename
	  class="directory">/usr/sbin</filename>.  While nothing is
	100% safe, the system-default SUID and SGID binaries can be
	considered reasonably safe.  It is recommended to restrict
	SUID binaries to a special group that only staff can access,
	and to delete any unused SUID binaries.  SGID binaries can be
	almost as dangerous.  If an intruder can break an SGID-kmem
	binary, the intruder might be able to read
	<filename>/dev/kmem</filename> and thus read the encrypted
	password file, potentially compromising user accounts.
	Alternatively, an intruder who breaks group
	<literal>kmem</literal> can monitor keystrokes sent through
	ptys, including ptys used by users who login through secure
	methods.  An intruder that breaks the
	<groupname>tty</groupname> group can write to almost any
	user's tty.  If a user is running a terminal program or
	emulator with a keyboard-simulation feature, the intruder can
	potentially generate a data stream that causes the user's
	terminal to echo a command, which is then run as that
	user.</para>
    </sect2>

    <sect2 id="secure-users">
      <title>Securing User Accounts</title>

      <para>User accounts are usually the most difficult to secure.
	Be vigilant in the monitoring of user accounts.  Use of
	&man.ssh.1; and Kerberos for user accounts requires extra
	administration and technical support, but provides a good
	solution compared to an encrypted password file.</para>
    </sect2>

    <sect2>
      <title>Securing the Password File</title>

      <para>The only sure fire way is to star out as many passwords as
	possible and use &man.ssh.1; or Kerberos for access to those
	accounts.  Even though the encrypted password file
	(<filename>/etc/spwd.db</filename>) can only be read by
	<username>root</username>, it may be possible for an intruder
	to obtain read access to that file even if the attacker cannot
	obtain root-write access.</para>

      <para>Security scripts should be used to check for and report
	changes to the password file as described in the <link
	  linkend="security-integrity">Checking file integrity</link>
	section.</para>
    </sect2>

    <sect2>
      <title>Securing the Kernel Core, Raw Devices, and
	Filesystems</title>

      <para>Most modern kernels have a packet sniffing device driver
	built in.  Under &os; it is called
	<devicename>bpf</devicename>.  This device is needed for DHCP,
	but can be removed in the custom kernel configuration file of
	systems that do not provide or use DHCP.</para>

      <indexterm>
	<primary>&man.sysctl.8;</primary>
      </indexterm>

      <para>Even if <devicename>bpf</devicename> is disabled,
	<filename>/dev/mem</filename> and
	<filename>/dev/kmem</filename> are still problematic.  An
	intruder can still write to raw disk devices.  An enterprising
	intruder can use &man.kldload.8; to install his own
	<devicename>bpf</devicename>, or another sniffing device, on a
	running kernel.  To avoid these problems, run the kernel at a
	higher security level, at least security level 1.</para>

      <para>The security level of the kernel can be set in a variety
	of ways.  The simplest way of raising the security level of a
	running kernel is to set
	<varname>kern.securelevel</varname>:</para>

      <screen>&prompt.root; <userinput>sysctl kern.securelevel=<replaceable>1</replaceable></userinput></screen>

      <para>By default, the &os; kernel boots with a security level of
	-1.  This is called <quote>insecure mode</quote> because
	immutable file flags may be turned off and all devices may be
	read from or written to.  The security level will remain at -1
	unless it is altered, either by the administrator or by
	&man.init.8;, because of a setting in the startup scripts.
	The security level may be raised during system startup by
	setting
	<varname>kern_securelevel_enable</varname> to
	<literal>YES</literal> in <filename>/etc/rc.conf</filename>,
	and the value of <varname>kern_securelevel</varname> to the
	desired security level.</para>

      <para>Once the security level is set to 1 or a higher value, the
	append-only and immutable files are honored, they cannot be
	turned off, and access to raw devices is denied.  Higher
	levels restrict even more operations.  For a full description
	of the effect of various security levels, refer to
	&man.security.7; and &man.init.8;.</para>

      <note>
	<para>Bumping the security level to 1 or higher may cause a
	  few problems to <application>&xorg;</application>, as access
	  to <filename>/dev/io</filename> will be blocked, or to the
	  installation of &os; built from source as
	  <maketarget>installworld</maketarget> needs to temporarily
	  reset the append-only and immutable flags of some files.
	  In the case of <application>&xorg;</application>, it may be
	  possible to work around this by starting &man.xdm.1; early
	  in the boot process, when the security level is still low
	  enough.  Workarounds may not be possible for all secure
	  levels or for all the potential restrictions they enforce.
	  A bit of forward planning is a good idea.  Understanding the
	  restrictions imposed by each security level is important as
	  they severely diminish the ease of system use.  It will also
	  make choosing a default setting much simpler and prevent any
	  surprises.</para>
      </note>

      <para>If the kernel's security level is raised to 1 or a higher
	value, it may be useful to set the <literal>schg</literal>
	flag on critical startup binaries, directories, script files,
	and  everything that gets run up to the point where the
	security level is set.  A less strict compromise is to run
	the system at a higher security level but skip setting the
	<literal>schg</literal> flag.  Another possibility is to
	mount <filename class="directory">/</filename> and <filename
	  class="directory">/usr</filename> read-only.  It should be
	noted that being too draconian about what is permitted may
	prevent detection of an intrusion.</para>
    </sect2>

    <sect2 id="security-integrity">
      <title>Checking File Integrity</title>

      <para>One can only protect the core system configuration and
	control files so much before the convenience factor rears its
	ugly head.  For example, using &man.chflags.1; to set the
	<literal>schg</literal> bit on most of the files in <filename
	  class="directory">/</filename> and <filename
	  class="directory">/usr</filename> is probably
	counterproductive, because while it may protect the files, it
	also closes an intrusion detection window.  Security measures
	are useless or, worse, present a false sense of security, if
	potential intrusions cannot be detected.  Half the job of
	security is to slow down, not stop, an attacker, in order to
	catch him in the act.</para>

      <para>The best way to detect an intrusion is to look for
	modified, missing, or unexpected files.  The best way to look
	for modified files is from another, often centralized,
	limited-access system.  Writing security scripts on the
	extra-security limited-access system makes them mostly
	invisible to potential attackers.  In order to take maximum
	advantage, the limited-access box needs significant access to
	the other machines, usually either through a read-only
	<acronym>NFS</acronym> export or by setting up
	&man.ssh.1; key-pairs.  Except for its network traffic,
	<acronym>NFS</acronym> is the least visible method, allowing
	the administrator to monitor the filesystems on each client
	box virtually undetected.  If a limited-access server is
	connected to the client boxes through a switch, the
	<acronym>NFS</acronym> method is often the better choice.  If
	a limited-access server is connected to the client boxes
	through several layers of routing, the <acronym>NFS</acronym>
	method may be too insecure and &man.ssh.1; may be the better
	choice.</para>

      <para>Once a limited-access box has been given at least read
	access to the client systems it is supposed to monitor, create
	the monitoring scripts.  Given an <acronym>NFS</acronym>
	mount, write scripts out of simple system utilities such as
	&man.find.1; and &man.md5.1;.  It is best to physically
	&man.md5.1; the client system's files at least once a day, and
	to test control files such as those found in <filename
	  class="directory">/etc</filename> and <filename
	  class="directory">/usr/local/etc</filename> even more often.
	When mismatches are found, relative to the base md5
	information the limited-access machine knows is valid, it
	should alert the sysadmin.  A good security script will also
	check for inappropriate SUID binaries and for new or deleted
	files on system partitions such as <filename
	  class="directory">/</filename> and <filename
	  class="directory">/usr</filename>.</para>

      <para>When using &man.ssh.1; rather than <acronym>NFS</acronym>,
	writing the security script is more difficult.  For example,
	&man.scp.1; is needed to send the scripts to the client box in
	order to run them.  The &man.ssh.1; client on the client box
	may already be compromised.  Using &man.ssh.1; may be
	necessary when running over insecure links, but it is harder
	to deal with.</para>

      <para>A good security script will also check for changes to
	hidden configuration files, such as
	<filename>.rhosts</filename> and
	<filename>.ssh/authorized_keys</filename>, as these files
	might fall outside the purview of the
	<literal>MD5</literal> check.</para>

      <para>For a large amount of user disk space, it may take too
	long to run through every file on those partitions.  In this
	case, consider setting mount flags to disallow SUID binaries
	by using <literal>nosuid</literal> with &man.mount.8;.  Scan
	these partitions at least once a week, since the objective is
	to detect a break-in attempt, whether or not the attempt
	succeeds.</para>

      <para>Process accounting (see &man.accton.8;) is a relatively
	low-overhead feature of &os; which might help as a
	post-break-in evaluation mechanism.  It is especially useful
	in tracking down how an intruder broke into a system, assuming
	the file is still intact after the break-in has
	occurred.</para>

      <para>Finally, security scripts should process the log files,
	and the logs themselves should be generated in as secure a
	manner as possible and sent to a remote syslog server.  An
	intruder will try to cover his tracks, and log files are
	critical to the sysadmin trying to track down the time and
	method of the initial break-in.  One way to keep a permanent
	record of the log files is to run the system console to a
	serial port and collect the information to a secure machine
	monitoring the consoles.</para>
    </sect2>

    <sect2>
      <title>Paranoia</title>

      <para>A little paranoia never hurts.  As a rule, a sysadmin can
	add any number of security features which do not affect
	convenience and can add security features that
	<emphasis>do</emphasis> affect convenience with some added
	thought.  More importantly, a security administrator should
	mix it up a bit.  If recommendations, such as those mentioned
	in this section, are applied verbatim, those methodologies are
	given to the prospective attacker who also has access to this
	document.</para>
    </sect2>

    <sect2>
      <title>Denial of Service Attacks</title>

      <indexterm>
	<primary>Denial of Service (DoS)</primary>
      </indexterm>

      <para>A <acronym>DoS</acronym> attack is typically a packet
	attack.  While there is not much one can do about spoofed
	packet attacks that saturate a network, one can generally
	limit the damage by ensuring that the attack cannot take down
	servers by:</para>

      <orderedlist>
	<listitem>
	  <para>Limiting server forks.</para>
	</listitem>

	<listitem>
	  <para>Limiting springboard attacks such as ICMP response
	    attacks and ping broadcasts.</para>
	</listitem>

	<listitem>
	  <para>Overloading the kernel route cache.</para>
	</listitem>
      </orderedlist>

      <para>A common <acronym>DoS</acronym> attack scenario is to
	force a forking server to spawn so many child processes that
	the host system eventually runs out of memory and file
	descriptors, and then grinds to a halt.  There are several
	options to &man.inetd.8; to limit this sort of attack.  It
	should be noted that while it is possible to prevent a machine
	from going down, it is not generally possible to prevent a
	service from being disrupted by the attack.  Read
	&man.inetd.8; carefully and pay specific attention to
	<option>-c</option>, <option>-C</option>, and
	<option>-R</option>.  Spoofed IP attacks will circumvent
	<option>-C</option> to &man.inetd.8;, so typically a
	combination of options must be used.  Some standalone servers
	have self-fork-limitation parameters.</para>

      <para><application>Sendmail</application> provides
	<option>-OMaxDaemonChildren</option>, which tends to work
	better than trying to use
	<application>Sendmail</application>'s load limiting options
	due to the load lag.  Specify a
	<literal>MaxDaemonChildren</literal> when starting
	<application>Sendmail</application> which is high enough to
	handle the expected load, but not so high that the computer
	cannot handle that number of
	<application>Sendmail</application> instances.  It is prudent
	to run <application>Sendmail</application> in queued mode
	using <option>-ODeliveryMode=queued</option> and to run the
	daemon (<command>sendmail -bd</command>) separate from the
	queue-runs (<command>sendmail -q15m</command>).  For
	real-time delivery, run the queue at a much lower interval,
	such as <option>-q1m</option>, but be sure to specify a
	reasonable <literal>MaxDaemonChildren</literal> to prevent
	cascade failures.</para>

      <para>&man.syslogd.8; can be attacked directly and it is
	strongly recommended to use
	<option>-s</option> whenever possible, and
	<option>-a</option> otherwise.</para>

      <para>Be careful with connect-back services such as
	reverse-identd, which can be attacked directly.  The
	reverse-ident feature of
	<application>TCP Wrappers</application> is not recommended for
	this reason.</para>

      <para>It is recommended to protect internal services from
	external access by firewalling them at the border routers.
	This is to prevent saturation attacks from outside the LAN,
	not so much to protect internal services from network-based
	<username>root</username> compromise.  Always configure an
	exclusive firewall which denies everything by default except
	for traffic which is explicitly allowed.  The range of port
	numbers used for dynamic binding in &os; is controlled by
	several <varname>net.inet.ip.portrange</varname>
	&man.sysctl.8; variables.</para>

      <para>Another common <acronym>DoS</acronym> attack, called a
	springboard attack, causes the server to generate responses
	which overloads the server, the local network, or some other
	machine.  The most common attack of this nature is the
	<emphasis>ICMP ping broadcast attack</emphasis>.  The attacker
	spoofs ping packets sent to the LAN's broadcast address with
	the source IP address set to the machine to attack.  If the
	border routers are not configured to drop ping packets sent to
	broadcast addresses, the LAN generates sufficient responses to
	the spoofed source address to saturate the victim, especially
	when the attack is against several dozen broadcast addresses
	over several dozen different networks at once.  A second
	common springboard attack constructs packets that generate
	ICMP error responses which can saturate a server's incoming
	network and cause the server to saturate its outgoing network
	with ICMP responses.  This type of attack can crash the
	server by running it out of memory, especially if the server
	cannot drain the ICMP responses it generates fast enough.  Use
	the &man.sysctl.8; variable
	<literal>net.inet.icmp.icmplim</literal> to limit these
	attacks.  The last major class of springboard attacks is
	related to certain internal &man.inetd.8; services such as the
	UDP echo service.  An attacker spoofs a UDP packet with a
	source address of server A's echo port and a destination
	address of server B's echo port, where server A and B on the
	same LAN.  The two servers bounce this one packet back and
	forth between each other.  The attacker can overload both
	servers and the LAN by injecting a few packets in this manner.
	Similar problems exist with the
	<application>chargen</application> port.  These inetd-internal
	test services should remain disabled.</para>

      <para>Spoofed packet attacks may be used to overload the kernel
	route cache.  Refer to the
	<varname>net.inet.ip.rtexpire</varname>,
	<varname>rtminexpire</varname>, and
	<varname>rtmaxcache</varname> &man.sysctl.8; parameters.  A
	spoofed packet attack that uses a random source IP will cause
	the kernel to generate a temporary cached route in the route
	table, viewable with <command>netstat -rna | fgrep
	  W3</command>.  These routes typically timeout in 1600
	seconds or so.  If the kernel detects that the cached route
	table has gotten too big, it will dynamically reduce the
	<varname>rtexpire</varname> but will never decrease it to less
	than <varname>rtminexpire</varname>.  This creates two
	problems:</para>

      <orderedlist>
	<listitem>

	  <para>The kernel does not react quickly enough when a
	    lightly loaded server is suddenly attacked.</para>
	</listitem>

	<listitem>
	  <para>The <varname>rtminexpire</varname> is not low enough
	    for the kernel to survive a sustained attack.</para>
	</listitem>
      </orderedlist>

      <para>If the servers are connected to the Internet via a T3 or
	better, it may be prudent to manually override both
	<varname>rtexpire</varname> and <varname>rtminexpire</varname>
	via &man.sysctl.8;.  Never set either parameter to zero
	as this could crash the machine.  Setting both parameters to 2
	seconds should be sufficient to protect the route table from
	attack.</para>
    </sect2>

    <sect2>
      <title>Access Issues with Kerberos and &man.ssh.1;</title>

      <indexterm><primary>&man.ssh.1;</primary></indexterm>

      <para>There are a few issues with both Kerberos and &man.ssh.1;
	that need to be addressed if they are used.  Kerberos is an
	excellent authentication protocol, but there are bugs in the
	kerberized versions of &man.telnet.1; and &man.rlogin.1; that
	make them unsuitable for dealing with binary streams.  By
	default, Kerberos does not encrypt a session unless
	<option>-x</option> is used whereas  &man.ssh.1; encrypts
	everything.</para>

      <para>While &man.ssh.1; works well, it forwards encryption keys
	by default.  This introduces a security risk to a user who
	uses &man.ssh.1; to access an insecure machine from a secure
	workstation.  The keys themselves are not exposed, but
	&man.ssh.1; installs a forwarding port for the duration of the
	login.  If an attacker has broken <username>root</username> on
	the insecure machine, he can utilize that port to gain access
	to any other machine that those keys unlock.</para>

      <para>It is recommended that &man.ssh.1; is used in combination
	with Kerberos whenever possible for staff logins and
	&man.ssh.1; can be compiled with Kerberos support.  This
	reduces reliance on potentially exposed <acronym>SSH</acronym>
	keys while protecting passwords via Kerberos.  Keys should
	only be used for automated tasks from secure machines as this
	is something that Kerberos is unsuited to.  It is recommended
	to either turn off key-forwarding in the
	<acronym>SSH</acronym> configuration, or to make use
	of <literal>from=IP/DOMAIN</literal> in
	<filename>authorized_keys</filename> to make the key only
	usable to entities logging in from specific machines.</para>
    </sect2>
  </sect1>

  <sect1 id="crypt">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Bill</firstname>
	  <surname>Swingle</surname>
	  <contrib>Parts rewritten and updated by </contrib>
	</author>
      </authorgroup>
      <!-- 21 Mar 2000 -->
    </sect1info>

    <title>DES, Blowfish, MD5, SHA256, SHA512, and Crypt</title>

    <indexterm>
      <primary>security</primary>
      <secondary>crypt</secondary>
    </indexterm>

    <indexterm><primary>crypt</primary></indexterm>
    <indexterm><primary>Blowfish</primary></indexterm>
    <indexterm><primary>DES</primary></indexterm>
    <indexterm><primary>MD5</primary></indexterm>
    <indexterm><primary>SHA256</primary></indexterm>
    <indexterm><primary>SHA512</primary></indexterm>

    <para>Every user on a &unix; system has a password associated with
      their account.  In order to keep these passwords secret, they
      are encrypted with a <quote>one-way hash</quote>, as they can
      be easily encrypted but not decrypted.  The operating system
      itself does not know the password.  It only knows the
      <emphasis>encrypted</emphasis> form of the password.  The only
      way to get the <quote>plain-text</quote> password is by a brute
      force search of the space of possible passwords.</para>

    <para>Originally, the only secure way to encrypt passwords in
      &unix; was based on the Data Encryption Standard
      (<acronym>DES</acronym>).  Since the source code for
      <acronym>DES</acronym> could not be exported outside the US,
      &os; had to find a way to both comply with US law and retain
      compatibility with other &unix; variants that used
      <acronym>DES</acronym>.  The solution was MD5 which is believed
      to be more secure than <acronym>DES</acronym>.</para>

    <sect2>
      <title>Recognizing the Crypt Mechanism</title>

      <para>Currently the library supports <acronym>DES</acronym>,
	MD5, Blowfish, SHA256, and SHA512 hash functions.  To identify
	which encryption method &os; is set up to use, examine the
	encrypted passwords in
	<filename>/etc/master.passwd</filename>.  Passwords encrypted
	with the MD5 hash are longer than those encrypted with the
	<acronym>DES</acronym> hash and begin with the characters
	<literal>&dollar;1&dollar;</literal>.  Passwords starting with
	<literal>&dollar;2a&dollar;</literal> are encrypted with the
	Blowfish hash function.  <acronym>DES</acronym> password
	strings do not have any particular identifying
	characteristics, but they are shorter than MD5 passwords, and
	are coded in a 64-character alphabet which does not include
	the <literal>&dollar;</literal> character, so a relatively
	short string which does not begin with a dollar sign is very
	likely a <acronym>DES</acronym> password.  Both SHA256 and
	SHA512 begin with the characters
	<literal>&dollar;6&dollar;</literal>.</para>

      <para>The password format used for new passwords is controlled
	by the <literal>passwd_format</literal> login capability in
	<filename>/etc/login.conf</filename>, which takes values of
	<literal>des</literal>, <literal>md5</literal>,
	<literal>blf</literal>, <literal>sha256</literal> or
	<literal>sha512</literal>.  Refer to &man.login.conf.5; for
	more information about login capabilities.</para>
    </sect2>
  </sect1>

  <sect1 id="one-time-passwords">
    <title>One-time Passwords</title>

    <indexterm><primary>one-time passwords</primary></indexterm>
    <indexterm>
      <primary>security</primary>
      <secondary>one-time passwords</secondary>
    </indexterm>

    <para>By default, &os; includes support for One-time Passwords In
      Everything (<acronym>OPIE</acronym>), which uses the MD5 hash by
      default.</para>

    <para>There are three different types of passwords.  The first is
      the usual &unix; style or Kerberos password.  The second is the
      one-time password which is generated by &man.opiekey.1; and
      accepted by &man.opiepasswd.1; and the login prompt.  The final
      type of password is the <quote>secret password</quote> used by
      &man.opiekey.1;, and sometimes &man.opiepasswd.1;, to generate
      one-time passwords.</para>

    <para>The secret password has nothing to do with the &unix;
      password.  They can be the same, but this is not recommended.
      <acronym>OPIE</acronym> secret passwords are not limited to 8
      characters like old &unix; passwords<footnote><para>Under &os;
	  the standard login password may be up to 128 characters in
	  length.</para></footnote>.  Passwords of six or seven word
      long phrases are fairly common.  For the most part, the
      <acronym>OPIE</acronym> system operates completely independently
      of the &unix; password system.</para>

    <para>Besides the password, there are two other pieces of data
      that are important to <acronym>OPIE</acronym>.  One is the
      <quote>seed</quote> or <quote>key</quote>, consisting of two
      letters and five digits.  The other is the <quote>iteration
	count</quote>, a number between 1 and 100.
      <acronym>OPIE</acronym> creates the one-time password by
      concatenating the seed and the secret password, applying the MD5
      hash as many times as specified by the iteration count, and
      turning the result into six short English words.  These six
      English words are the one-time password.  The authentication
      system (primarily PAM) keeps track of the last one-time password
      used, and the user is authenticated if the hash of the
      user-provided password is equal to the previous password.
      Because a one-way hash is used, it is impossible to generate
      future one-time passwords if a successfully used password is
      captured.  The iteration count is decremented after each
      successful login to keep the user and the login program in sync.
      When the iteration count gets down to 1,
      <acronym>OPIE</acronym> must be reinitialized.</para>

    <para>There are a few programs involved in this process.
      &man.opiekey.1; accepts an iteration count, a seed, and a secret
      password, and generates a one-time password or a consecutive
      list of one-time passwords.  In addition to initializing
      <acronym>OPIE</acronym>, &man.opiepasswd.1; is used to change
      passwords, iteration counts, or seeds.  It takes either a secret
      passphrase, or an iteration count, seed, and a one-time
      password.  The relevant credential files in
      <filename>/etc/opiekeys</filename> are examined by
      &man.opieinfo.1; which prints out the invoking user's current
      iteration count and seed.</para>

    <para>There are four different sorts of operations.  The first is
      to use &man.opiepasswd.1; over a secure connection to set up
      one-time-passwords for the first time, or to change the password
      or seed.  The second operation is to use &man.opiepasswd.1; over
      an insecure connection, in conjunction with &man.opiekey.1; over
      a secure connection, to do the same.  The third is to use
      &man.opiekey.1; to log in over an insecure connection.  The
      fourth is to use &man.opiekey.1; to generate a number of keys
      which can be written down or printed out to carry to insecure
      locations in order to make a connection to anywhere.</para>

    <sect2>
      <title>Secure Connection Initialization</title>

      <para>To initialize <acronym>OPIE</acronym> for the first time,
	execute &man.opiepasswd.1;:</para>

      <screen>&prompt.user; <userinput>opiepasswd -c</userinput>
[grimreaper] ~ $ opiepasswd -f -c
Adding unfurl:
Only use this method from the console; NEVER from remote. If you are using
telnet, xterm, or a dial-in, type ^C now or exit with no password.
Then run opiepasswd without the -c parameter.
Using MD5 to compute responses.
Enter new secret pass phrase:
Again new secret pass phrase:

ID unfurl OTP key is 499 to4268
MOS MALL GOAT ARM AVID COED</screen>

      <para>At the <prompt>Enter new secret pass phrase:</prompt> or
	<prompt>Enter secret password:</prompt> prompt, enter a
	password or phrase.  This is not the login password as this
	password is used to generate the one-time login keys.  The
	<quote>ID</quote> line gives the parameters of the instance:
	the login name, iteration count, and seed.  When logging in,
	the system will remember these parameters and display them,
	meaning that they do not have to be memorized.  The last line
	gives the particular one-time password which corresponds to
	those parameters and the secret password.  At the next login,
	this one-time password is the one to use.</para>
    </sect2>

    <sect2>
      <title>Insecure Connection Initialization</title>

      <para>To initialize or change the secret password over an
	insecure connection, a secure connection is needed to some
	place where &man.opiekey.1; can be run.  This might be a shell
	prompt on a trusted machine.  An iteration count is needed,
	where 100 is probably a good value, and the seed can either be
	specified or the randomly-generated one used.  On the insecure
	connection, the machine being initialized, use
	&man.opiepasswd.1;:</para>

      <screen>&prompt.user; <userinput>opiepasswd</userinput>

Updating unfurl:
You need the response from an OTP generator.
Old secret pass phrase:
	otp-md5 498 to4268 ext
	Response: GAME GAG WELT OUT DOWN CHAT
New secret pass phrase:
	otp-md5 499 to4269
	Response: LINE PAP MILK NELL BUOY TROY

ID mark OTP key is 499 gr4269
LINE PAP MILK NELL BUOY TROY</screen>

      <para>To accept the default seed, press <keycap>Return</keycap>.
	Before entering an access password, move over to the secure
	connection and give it the same parameters:</para>

      <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
Using the MD5 algorithm to compute response.
Reminder: Do not use opiekey from telnet or dial-in sessions.
Enter secret pass phrase:
GAME GAG WELT OUT DOWN CHAT</screen>

      <para>Switch back over to the insecure connection, and copy
	the generated one-time password over to the relevant
	program.</para>
    </sect2>

    <sect2>
      <title>Generating a Single One-time Password</title>

      <para>After initializing <acronym>OPIE</acronym> and logging in,
	a prompt like this will be displayed:</para>

      <screen>&prompt.user; <userinput>telnet example.com</userinput>
Trying 10.0.0.1...
Connected to example.com
Escape character is '^]'.

FreeBSD/i386 (example.com) (ttypa)

login: <userinput>&lt;username&gt;</userinput>
otp-md5 498 gr4269 ext
Password: </screen>

      <para>The <acronym>OPIE</acronym> prompts provides a useful
	feature.  If <keycap>Return</keycap> is pressed at the
	password prompt, the prompt will turn echo on and display
	what is typed.  This can be useful when attempting to type in
	a password by hand from a printout.</para>

      <indexterm><primary>MS-DOS</primary></indexterm>
      <indexterm><primary>Windows</primary></indexterm>
      <indexterm><primary>MacOS</primary></indexterm>

      <para>At this point, generate the one-time password to answer
	this login prompt.  This must be done on a trusted system
	where it is safe to run &man.opiekey.1;.  There are versions
	of this command for &windows;, &macos; and &os;.  This command
	needs the iteration count and the seed as command line
	options.  Use cut-and-paste from the login prompt on the
	machine being logged in to.</para>

      <para>On the trusted system:</para>

      <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
Using the MD5 algorithm to compute response.
Reminder: Do not use opiekey from telnet or dial-in sessions.
Enter secret pass phrase:
GAME GAG WELT OUT DOWN CHAT</screen>

      <para>Once the one-time password is generated, continue to log
	in.</para>
    </sect2>

    <sect2>
      <title>Generating Multiple One-time Passwords</title>

      <para>Sometimes there is no access to a trusted machine or
	secure connection.  In this case, it is possible to use
	&man.opiekey.1; to generate a number of one-time passwords
	beforehand.  For example:</para>

      <screen>&prompt.user; <userinput>opiekey -n 5 30 zz99999</userinput>
Using the MD5 algorithm to compute response.
Reminder: Do not use opiekey from telnet or dial-in sessions.
Enter secret pass phrase: <userinput>&lt;secret password&gt;</userinput>
26: JOAN BORE FOSS DES NAY QUIT
27: LATE BIAS SLAY FOLK MUCH TRIG
28: SALT TIN ANTI LOON NEAL USE
29: RIO ODIN GO BYE FURY TIC
30: GREW JIVE SAN GIRD BOIL PHI</screen>

      <para>The <option>-n 5</option> requests five keys in sequence,
	and <option>30</option> specifies what the last iteration
	number should be.  Note that these are printed out in
	<emphasis>reverse</emphasis> order of use.  The really
	paranoid might want to write the results down by hand;
	otherwise, print the list.  Each line shows both the iteration
	count and the one-time password.  Scratch off the passwords as
	they are used.</para>
    </sect2>

    <sect2>
      <title>Restricting Use of &unix; Passwords</title>

      <para><acronym>OPIE</acronym> can restrict the use of &unix;
	passwords based on the IP address of a login session.  The
	relevant file is <filename>/etc/opieaccess</filename>, which
	is present by default.  Refer to &man.opieaccess.5; for more
	information on this file and which security considerations to
	be aware of when using it.</para>

      <para>Here is a sample <filename>opieaccess</filename>:</para>

      <programlisting>permit 192.168.0.0 255.255.0.0</programlisting>

      <para>This line allows users whose IP source address (which is
	vulnerable to spoofing) matches the specified value and mask,
	to use &unix; passwords at any time.</para>

      <para>If no rules in <filename>opieaccess</filename> are
	matched, the default is to deny non-<acronym>OPIE</acronym>
	logins.</para>
    </sect2>
  </sect1>

  <sect1 id="tcpwrappers">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>TCP Wrappers</title>

    <indexterm><primary>TCP Wrappers</primary></indexterm>

    <para><acronym>TCP</acronym> Wrappers extends the abilities of
      <xref linkend="network-inetd"/> to provide support for every
      server daemon under its control.  It can be configured
      to provide logging support, return messages to connections, and
      permit a daemon to only accept internal connections.  While some
      of these features can be provided by implementing a firewall,
      <acronym>TCP</acronym> Wrappers adds an extra layer of
      protection and goes beyond the amount of control a firewall can
      provide.</para>

    <para><acronym>TCP</acronym> Wrappers should not be considered a
      replacement for a properly configured firewall.
      <acronym>TCP</acronym> Wrappers should be used in conjunction
      with a firewall and other security enhancements.</para>

    <sect2>
      <title>Initial Configuration</title>

      <para>To enable <acronym>TCP</acronym> Wrappers in &os;, ensure
	the &man.inetd.8; server is started from
	<filename>/etc/rc.conf</filename> with
	<option>-Ww</option>.  Then, properly configure
	<filename>/etc/hosts.allow</filename>.</para>

      <note>
	<para>Unlike other implementations of <acronym>TCP</acronym>
	  Wrappers, the use of <filename>hosts.deny</filename> has
	  been deprecated.  All configuration options should be placed
	  in <filename>/etc/hosts.allow</filename>.</para>
      </note>

      <para>In the simplest configuration, daemon connection policies
	are set to either be permitted or blocked depending on the
	options in <filename>/etc/hosts.allow</filename>.  The default
	configuration in &os; is to allow a connection to every daemon
	started with &man.inetd.8;.</para>

      <para>Basic configuration usually takes the form of
	<literal>daemon : address : action</literal>, where
	<literal>daemon</literal> is the daemon which &man.inetd.8;
	started, <literal>address</literal> is a valid hostname,
	<acronym>IP</acronym> address, or an IPv6 address enclosed in
	brackets ([&nbsp;]), and <literal>action</literal> is
	either <literal>allow</literal> or <literal>deny</literal>.
	<acronym>TCP</acronym> Wrappers uses a first rule match
	semantic, meaning that the configuration file is scanned in
	ascending order for a matching rule.  When a match is found,
	the rule is applied and the search process stops.</para>

      <para>For example, to allow <acronym>POP</acronym>3 connections
	via the <filename role="package">mail/qpopper</filename>
	daemon, the following lines should be appended to
	<filename>hosts.allow</filename>:</para>

      <programlisting># This line is required for POP3 connections:
qpopper : ALL : allow</programlisting>

      <para>After adding this line, &man.inetd.8; needs to be
	restarted:</para>

	<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
    </sect2>

    <sect2>
      <title>Advanced Configuration</title>

      <para><acronym>TCP</acronym> Wrappers provides advanced options
	to allow more control over the way connections are handled.
	In some cases, it may be appropriate to return a comment to
	certain hosts or daemon connections.  In other cases, a log
	entry should be recorded or an email sent to the
	administrator.  Other situations may require the use of a
	service for local connections only.  This is all possible
	through the use of configuration options known as
	<literal>wildcards</literal>, expansion characters and
	external command execution.</para>

      <sect3>
	<title>External Commands</title>

	<para>Suppose that a situation occurs where a connection
	  should be denied yet a reason should be sent to the
	  individual who attempted to establish that connection.  That
	  action is possible with <option>twist</option>.  When a
	  connection attempt is made, <option>twist</option> executes
	  a shell command or script.  An example exists in
	  <filename>hosts.allow</filename>:</para>

	<programlisting># The rest of the daemons are protected.
ALL : ALL \
	: severity auth.info \
	: twist /bin/echo "You are not welcome to use %d from %h."</programlisting>

	<para>In this example, the message <quote>You are not allowed
	    to use <literal>daemon</literal> from
	    <literal>hostname</literal>.</quote> will be returned for
	  any daemon not previously configured in the access file.
	  This is useful for sending a reply back to the connection
	  initiator right after the established connection is dropped.
	  Any message returned <emphasis>must</emphasis> be wrapped in
	  quote (<literal>"</literal>) characters.</para>

	<warning>
	  <para>It may be possible to launch a denial of service
	    attack on the server if an attacker, or group of
	    attackers, could flood these daemons with connection
	    requests.</para>
	</warning>

	<para>Another possibility is to use <option>spawn</option>.
	  Like <option>twist</option>, <option>spawn</option>
	  implicitly denies the connection and may be used to run
	  external shell commands or scripts.  Unlike
	  <option>twist</option>, <option>spawn</option> will not send
	  a reply back to the individual who established the
	  connection.  For example, consider the following
	  configuration line:</para>

	<programlisting># We do not allow connections from example.com:
ALL : .example.com \
	: spawn (/bin/echo %a from %h attempted to access %d &gt;&gt; \
	  /var/log/connections.log) \
	: deny</programlisting>

	<para>This will deny all connection attempts from <hostid
	    role="fqdn">*.example.com</hostid> and log the hostname,
	  <acronym>IP</acronym> address, and the daemon to which
	  access was attempted to
	  <filename>/var/log/connections.log</filename>.</para>

	<para>This example uses the substitution characters
	  <literal>%a</literal> and <literal>%h</literal>.  Refer to
	  &man.hosts.access.5; for the complete list.</para>
      </sect3>

      <sect3>
	<title>Wildcard Options</title>

	<para>The <literal>ALL</literal> option may be used to match
	  every instance of a daemon, domain, or an
	  <acronym>IP</acronym> address.  Another wildcard is
	  <literal>PARANOID</literal> which may be used to match
	  any host which provides an <acronym>IP</acronym> address
	  that may be forged.  For example,
	  <literal>PARANOID</literal> may be used to define an action
	  to be taken whenever a connection is made from an
	  <acronym>IP</acronym> address that differs from its
	  hostname.  In this example, all connection requests to
	  &man.sendmail.8; which have an <acronym>IP</acronym> address
	  that varies from its hostname will be denied:</para>

	<programlisting># Block possibly spoofed requests to sendmail:
sendmail : PARANOID : deny</programlisting>

	<caution>
	  <para>Using the <literal>PARANOID</literal> wildcard may
	    severely cripple servers if the client or server has a
	    broken <acronym>DNS</acronym> setup.  Administrator
	    discretion is advised.</para>
	</caution>

	<para>To learn more about wildcards and their associated
	  functionality, refer to &man.hosts.access.5;.</para>

	<para>Before any of the specific configuration lines above
	  will work, the first configuration line should be commented
	  out in <filename>hosts.allow</filename>.</para>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="kerberos5">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tillman</firstname>
	  <surname>Hodgson</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Mark</firstname>
	  <surname>Murray</surname>
	  <contrib>Based on a contribution by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title><application>Kerberos5</application></title>

    <para><application>Kerberos</application> is a network add-on
      system/protocol that allows users to authenticate themselves
      through the services of a secure server.
      <application>Kerberos</application> can be described as an
      identity-verifying proxy system.  It can also be described as a
      trusted third-party authentication system.  After a user
      authenticates with <application>Kerberos</application>, their
      communications can be encrypted to assure privacy and data
      integrity.</para>

    <para>The only function of <application>Kerberos</application> is
      to provide the secure authentication of users on the network.
      It does not provide authorization functions (what users are
      allowed to do) or auditing functions (what those users did).  It
      is recommended that <application>Kerberos</application> be used
      with other security methods which provide authorization and
      audit services.</para>

    <para>This section provides a guide on how to set up
      <application>Kerberos</application> as distributed for &os;.
      Refer to the relevant manual pages for more complete
      descriptions.</para>

    <para>For purposes of demonstrating a
      <application>Kerberos</application> installation, the various
      name spaces will be as follows:</para>

    <itemizedlist>
      <listitem>
	<para>The <acronym>DNS</acronym> domain (<quote>zone</quote>)
	  will be <hostid role="fqdn">example.org</hostid>.</para>
      </listitem>

      <listitem>
	<para>The <application>Kerberos</application> realm will be
	  <literal>EXAMPLE.ORG</literal>.</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>Use real domain names when setting up
	<application>Kerberos</application> even if it will run
	internally.  This avoids <acronym>DNS</acronym> problems
	and assures inter-operation with other
	<application>Kerberos</application> realms.</para>
    </note>

    <sect2>
      <title>History</title>

      <indexterm>
	<primary>Kerberos5</primary>
	<secondary>history</secondary>
      </indexterm>

      <para><application>Kerberos</application> was created by
	<acronym>MIT</acronym> as a solution to network security
	problems.  The <application>Kerberos</application> protocol
	uses strong cryptography so that a client can prove its
	identity to a server (and vice versa) across an insecure
	network connection.</para>

      <para><application>Kerberos</application> is both the name of a
	network authentication protocol and an adjective to describe
	programs that implement it, such as
	<application>Kerberos</application> telnet.  The current
	version of the protocol is version 5, described in
	<acronym>RFC</acronym>&nbsp;1510.</para>

      <para>Several free implementations of this protocol are
	available, covering a wide range of operating systems.  The
	Massachusetts Institute of Technology
	(<acronym>MIT</acronym>), where
	<application>Kerberos</application> was originally developed,
	continues to develop their <application>Kerberos</application>
	package.  It is commonly used in the <acronym>US</acronym> as
	a cryptography product, and has historically been affected by
	<acronym>US</acronym> export regulations.  The
	<acronym>MIT</acronym> <application>Kerberos</application> is
	available as the <filename
	  role="package">security/krb5</filename> package or port.
	Heimdal <application>Kerberos</application> is another version
	5 implementation, and was explicitly developed outside of the
	<acronym>US</acronym> to avoid export regulations.  The
	Heimdal <application>Kerberos</application> distribution is
	available as a the <filename
	  role="package">security/heimdal</filename> package or port,
	and a minimal installation is included in the base &os;
	install.</para>

      <para>These instructions assume the use of the Heimdal
	distribution included in &os;.</para>
    </sect2>

    <sect2>
      <title>Setting up a Heimdal <acronym>KDC</acronym></title>

      <indexterm>
	<primary>Kerberos5</primary>
	<secondary>Key Distribution Center</secondary>
      </indexterm>

      <para>The Key Distribution Center (<acronym>KDC</acronym>) is
	the centralized authentication service that
	<application>Kerberos</application> provides.  It is the
	computer that issues <application>Kerberos</application>
	tickets.  The <acronym>KDC</acronym> is considered
	<quote>trusted</quote> by all other computers in the
	<application>Kerberos</application> realm, and thus has
	heightened security concerns.</para>

      <para>While running the <application>Kerberos</application>
	server requires very few computing resources, a dedicated
	machine acting only as a <acronym>KDC</acronym> is recommended
	for security reasons.</para>

      <para>To begin setting up a <acronym>KDC</acronym>, ensure that
	<filename>/etc/rc.conf</filename> contains the correct
	settings to act as a <acronym>KDC</acronym>.  As required,
	adjust paths to reflect the system:</para>

      <programlisting>kerberos5_server_enable="YES"
kadmind5_server_enable="YES"</programlisting>

      <para>Next, edit <filename>/etc/krb5.conf</filename> as
	follows:</para>

      <programlisting>[libdefaults]
    default_realm = EXAMPLE.ORG
[realms]
    EXAMPLE.ORG = {
        kdc = kerberos.example.org
        admin_server = kerberos.example.org
    }
[domain_realm]
    .example.org = EXAMPLE.ORG</programlisting>

      <para>This <filename>/etc/krb5.conf</filename> implies that the
	<acronym>KDC</acronym> will use the fully-qualified hostname
	<hostid role="fqdn">kerberos.example.org</hostid>.  Add a
	CNAME (alias) entry to the zone file to accomplish this
	if the <acronym>KDC</acronym> has a different hostname.</para>

      <note>
	<para>For large networks with a properly configured
	  <acronym>DNS</acronym> server, the above example could be
	  trimmed to:</para>

	<programlisting>[libdefaults]
      default_realm = EXAMPLE.ORG</programlisting>

	<para>With the following lines being appended to the
	  <hostid role="fqdn">example.org</hostid> zone file:</para>

	<programlisting>_kerberos._udp      IN  SRV     01 00 88 kerberos.example.org.
_kerberos._tcp      IN  SRV     01 00 88 kerberos.example.org.
_kpasswd._udp       IN  SRV     01 00 464 kerberos.example.org.
_kerberos-adm._tcp  IN  SRV     01 00 749 kerberos.example.org.
_kerberos           IN  TXT     EXAMPLE.ORG</programlisting>
      </note>

      <note>
	<para>For clients to be able to find the
	  <application>Kerberos</application> services, it
	  <emphasis>must</emphasis> have either a fully configured
	  <filename>/etc/krb5.conf</filename> or a minimally
	  configured <filename>/etc/krb5.conf</filename>
	  <emphasis>and</emphasis> a properly configured DNS
	  server.</para>
      </note>

      <para>Next, create the <application>Kerberos</application>
	database which contains the keys of all principals encrypted
	with a master password.  It is not required to remember this
	password as it will be stored in
	<filename>/var/heimdal/m-key</filename>.  To create the
	master key, run &man.kstash.8; and enter a password.</para>

      <para>Once the master key has been created, initialize the
	database using <command>kadmin -l</command>.  This option
	instructs &man.kadmin.8; to modify the local database files
	directly rather than going through the &man.kadmind.8; network
	service.  This handles the chicken-and-egg problem of trying
	to connect to the database before it is created.  At the
	&man.kadmin.8; prompt, use <command>init</command> to create
	the realm's initial database.</para>

      <para>Lastly, while still in &man.kadmin.8;, create the first
	principal using <command>add</command>.  Stick to the default
	options for the principal for now, as these can be changed
	later with <command>modify</command>.  Type
	<literal>?</literal> at the &man.kadmin.8; prompt to see the
	available options.</para>

      <para>A sample database creation session is shown below:</para>

      <screen>&prompt.root; <userinput>kstash</userinput>
Master key: <userinput>xxxxxxxx</userinput>
Verifying password - Master key: <userinput>xxxxxxxx</userinput>

&prompt.root; <userinput>kadmin -l</userinput>
kadmin> <userinput>init EXAMPLE.ORG</userinput>
Realm max ticket life [unlimited]:
kadmin> <userinput>add tillman</userinput>
Max ticket life [unlimited]:
Max renewable life [unlimited]:
Attributes []:
Password: <userinput>xxxxxxxx</userinput>
Verifying password - Password: <userinput>xxxxxxxx</userinput></screen>

      <para>Next, start the <acronym>KDC</acronym> services.  Run
	<command>service kerberos start</command> and
	<command>service kadmind start</command> to bring up the
	services.  While there will not be any kerberized daemons
	running at this point, it is possible to confirm that the
	<acronym>KDC</acronym> is functioning by obtaining and
	listing a ticket for the principal (user) that was just
	created from the command-line of the <acronym>KDC</acronym>
	itself:</para>

      <screen>&prompt.user; <userinput>kinit <replaceable>tillman</replaceable></userinput>
tillman@EXAMPLE.ORG's Password:

&prompt.user; <userinput>klist</userinput>
Credentials cache: FILE:<filename>/tmp/krb5cc_500</filename>
	Principal: tillman@EXAMPLE.ORG

  Issued           Expires          Principal
Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG</screen>

      <para>The ticket can then be revoked when finished:</para>

      <screen>&prompt.user; <userinput>kdestroy</userinput></screen>
    </sect2>

    <sect2>
      <title><application>Kerberos</application> Enabling a Server
	with Heimdal Services</title>

      <indexterm>
	<primary>Kerberos5</primary>
	<secondary>enabling services</secondary>
      </indexterm>

      <para>First, copy
	<filename>/etc/krb5.conf</filename> from the
	<acronym>KDC</acronym> to the client computer in a secure
	fashion, such as &man.scp.1;, or physically via a removable
	media.</para>

      <para>Next, create <filename>/etc/krb5.keytab</filename>.
	This is the major difference between a server providing
	<application>Kerberos</application> enabled daemons and a
	workstation:  the server must have a
	<filename>keytab</filename>.  This file contains the
	server's host key, which allows it and the
	<acronym>KDC</acronym> to verify each others identity.  It
	must be transmitted to the server in a secure fashion, as
	the security of the server can be broken if the key is made
	public.</para>

      <para>Typically, the <filename>keytab</filename> is transferred
	to the server using &man.kadmin.8;.  This is handy because the
	host principal, the <acronym>KDC</acronym> end of the
	<filename>krb5.keytab</filename>, is also created using
	&man.kadmin.8;.</para>

      <para>A ticket must already be obtained and this ticket must be
	allowed to use the &man.kadmin.8; interface in the
	<filename>kadmind.acl</filename>.  See the section titled
	<quote>Remote administration</quote> in<command>info
	  heimdal</command> for details on designing access control
	lists.  Instead of enabling remote &man.kadmin.8; access, the
	administrator can securely connect to the
	<acronym>KDC</acronym> via the local console or &man.ssh.1;,
	and perform administration locally using
	<command>kadmin -l</command>.</para>

      <para>After installing <filename>/etc/krb5.conf</filename>,
	use <command>add --random-key</command> from the
	<application>Kerberos</application> server.  This adds
	the server's host principal.  Then, use <command>ext</command>
	to extract the server's host principal to its own keytab.  For
	example:</para>

      <screen>&prompt.root; <userinput>kadmin</userinput>
kadmin><userinput> add --random-key host/myserver.example.org</userinput>
Max ticket life [unlimited]:
Max renewable life [unlimited]:
Attributes []:
kadmin><userinput> ext host/myserver.example.org</userinput>
kadmin><userinput> exit</userinput></screen>

      <para>Note that <command>ext</command> stores the extracted key
	in <filename>/etc/krb5.keytab</filename> by default.</para>

      <para>If &man.kadmind.8; is not running on the
	<acronym>KDC</acronym> and there is no access to
	&man.kadmin.8; remotely, add the host principal
	(<username>host/myserver.EXAMPLE.ORG</username>) directly on
	the <acronym>KDC</acronym> and then extract it to a
	temporary file to avoid overwriting the
	<filename>/etc/krb5.keytab</filename> on the
	<acronym>KDC</acronym>, using something like this:</para>

      <screen>&prompt.root; <userinput>kadmin</userinput>
kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput>
kadmin><userinput> exit</userinput></screen>

      <para>The keytab can then be securely copied to the server
	using &man.scp.1; or a removable media.  Be sure to specify a
	non-default keytab name to avoid overwriting the keytab on the
	<acronym>KDC</acronym>.</para>

      <para>At this point, the server can communicate with the
	<acronym>KDC</acronym> using
	<filename>krb5.conf</filename> and it can prove its
	own identity with <filename>krb5.keytab</filename>.  It is now
	ready for the <application>Kerberos</application> services to
	be enabled.  For this example, the &man.telnetd.8; service
	is enabled in <filename>/etc/inetd.conf</filename> and
	&man.inetd.8; has been restarted with <command>service inetd
	  restart</command>:</para>

      <programlisting>telnet    stream  tcp     nowait  root    /usr/libexec/telnetd  telnetd -a user</programlisting>

      <para>The critical change is that the <option>-a</option>
	authentication type is set to user.  Refer to &man.telnetd.8;
	for more details.</para>
    </sect2>

    <sect2>
      <title><application>Kerberos</application> Enabling a Client
	with Heimdal</title>

      <indexterm>
	<primary>Kerberos5</primary>
	<secondary>configure clients</secondary>
      </indexterm>

      <para>Setting up a client computer is easy as only
	<filename>/etc/krb5.conf</filename> is needed.  Securely copy
	this file over to the client computer from the
	<acronym>KDC</acronym>.</para>

      <para>Test the client by attempting to use &man.kinit.1;,
	&man.klist.1;, and &man.kdestroy.1; from the client to obtain,
	show, and then delete a ticket for the principal created
	above.  <application>Kerberos</application> applications
	should also be able to connect to
	<application>Kerberos</application> enabled servers.  If that
	does not work but obtaining a ticket does, the problem is
	likely with the server and not with the client or the
	<acronym>KDC</acronym>.</para>

      <para>When testing a Kerberized application, try using a packet
	sniffer such as &man.tcpdump.1; to confirm that the password
	is not sent in the clear.</para>

      <para>Various non-core <application>Kerberos</application>
	client applications are available.  The <quote>minimal</quote>
	installation in &os; installs &man.telnetd.8; as the only
	<application>Kerberos</application> enabled service.</para>

      <para>The Heimdal port installs
	<application>Kerberos</application> enabled versions of
	&man.ftpd.8;, &man.rshd.8;, &man.rcp.1;, &man.rlogind.8;, and
	a few other less common programs.  The <acronym>MIT</acronym>
	port also contains a full suite of
	<application>Kerberos</application> client
	applications.</para>
    </sect2>

    <sect2>
      <title>User Configuration Files: <filename>.k5login</filename>
	and <filename>.k5users</filename></title>

      <indexterm>
	<primary><filename>.k5login</filename></primary>
      </indexterm>

      <indexterm>
	<primary><filename>.k5users</filename></primary>
      </indexterm>

      <para>Users within a realm typically have their
	<application>Kerberos</application> principal mapped to a
	local user account.  Occasionally, one needs to grant access
	to a local user account to someone who does not have a
	matching <application>Kerberos</application> principal.  For
	example, <username>tillman@EXAMPLE.ORG</username> may need
	access to the local user account
	<username>webdevelopers</username>.  Other principals may also
	need access to that local account.</para>

      <para>The <filename>.k5login</filename> and
	<filename>.k5users</filename> files, placed in a user's home
	directory, can be used to solve this problem.  For example, if
	<filename>.k5login</filename> with the following contents is
	placed in the home directory of
	<username>webdevelopers</username>, both principals listed
	will have access to that account without requiring a shared
	password.:</para>

      <screen>tillman@example.org
jdoe@example.org</screen>

      <para>Refer to &man.ksu.1; for more information about
	<filename>.k5users</filename>.</para>
    </sect2>

    <sect2>
      <title><application>Kerberos</application> Tips, Tricks, and
	Troubleshooting</title>

      <itemizedlist>
	<indexterm>
	  <primary>Kerberos5</primary>
	  <secondary>troubleshooting</secondary>
	</indexterm>

	<listitem>
	  <para>When using either the Heimdal or
	    <acronym>MIT</acronym>
	    <application>Kerberos</application> ports, ensure that
	    the <envar>PATH</envar> lists the
	    <application>Kerberos</application> versions of the
	    client applications before the system versions.</para>
	</listitem>

	<listitem>
	  <para>If all the computers in the realm do not have
	    synchronized time settings, authentication may fail.
	    <xref linkend="network-ntp"/> describes how to synchronize
	    clocks using <acronym>NTP</acronym>.</para>
	</listitem>

	<listitem>
	  <para><acronym>MIT</acronym> and Heimdal interoperate
	    except for &man.kadmin.8;, which is not
	    standardized.</para>
	</listitem>

	<listitem>
	  <para>If the hostname is changed, the
	    <username>host/</username> principal must be changed and
	    the keytab updated.  This also applies to special keytab
	    entries like the <username>www/</username> principal
	    used for Apache's <filename
	      role="package">www/mod_auth_kerb</filename>.</para>
	</listitem>

	<listitem>
	  <para>All hosts in the realm must be both forward and
	    reverse resolvable in <acronym>DNS</acronym> or, at a
	    minimum, in <filename>/etc/hosts</filename>.  CNAMEs
	    will work, but the A and PTR records must be correct and
	    in place.  The error message for unresolvable hosts is not
	    intuitive: <errorname>Kerberos5 refuses authentication
	      because Read req failed: Key table entry not
	      found</errorname>.</para>
	</listitem>

	<listitem>
	  <para>Some operating systems that act as clients to the
	    <acronym>KDC</acronym> do not set the permissions for
	    &man.ksu.1; to be setuid <username>root</username>.  This
	    means that &man.ksu.1; does not work.  This is not a
	    <acronym>KDC</acronym> error.</para>
	</listitem>

	<listitem>
	  <para>With <acronym>MIT</acronym>
	    <application>Kerberos</application>, in order to allow a
	    principal to have a ticket life longer than the default
	    ten hours, use <command>modify_principal</command> at the
	    &man.kadmin.8; prompt to change the maxlife of both the
	    principal in question and the
	    <username>krbtgt</username> principal.  Then the
	    principal can use <command>kinit -l</command> to request a
	    ticket with a longer lifetime.</para>
	</listitem>

	<listitem>
	  <note>
	    <para>When running a packet sniffer on the
	      <acronym>KDC</acronym> to aid in troubleshooting while
	      running &man.kinit.1; from a workstation, the Ticket
	      Granting Ticket (<acronym>TGT</acronym>) is sent
	      immediately upon running &man.kinit.1;, even before the
	      password is typed.  This is because the
	      <application>Kerberos</application> server freely
	      transmits a <acronym>TGT</acronym> to any unauthorized
	      request.  However, every <acronym>TGT</acronym> is
	      encrypted in a key derived from the user's password.
	      When a user types their password, it is not sent to the
	      <acronym>KDC</acronym>, it is instead used to decrypt
	      the <acronym>TGT</acronym> that &man.kinit.1; already
	      obtained.  If the decryption process results in a valid
	      ticket with a valid time stamp, the user has valid
	      <application>Kerberos</application> credentials.
	      These credentials include a session key for
	      establishing secure communications with the
	      <application>Kerberos</application> server in the
	      future, as well as the actual <acronym>TGT</acronym>,
	      which is encrypted with the
	      <application>Kerberos</application> server's own key.
	      This second layer of encryption allows the
	      <application>Kerberos</application> server to verify
	      the authenticity of each <acronym>TGT</acronym>.</para>
	  </note>
	</listitem>

	<listitem>
	  <para>To use long ticket lifetimes, such as a week, when
	    using <application>OpenSSH</application> to connect to the
	    machine where the ticket is stored, make sure that
	    <application>Kerberos</application>
	    <option>TicketCleanup</option> is set to
	    <literal>no</literal> in
	    <filename>sshd_config</filename> or else tickets will be
	    deleted at log out.</para>
	</listitem>

	<listitem>
	  <para>Host principals can have a longer ticket lifetime.  If
	    the user principal has a lifetime of a week but the host
	    being connected to has a lifetime of nine hours, the user
	    cache will have an expired host principal and the ticket
	    cache will not work as expected.</para>
	</listitem>

	<listitem>
	  <para>When setting up <filename>krb5.dict</filename> to
	    prevent specific bad passwords from being used as
	    described in &man.kadmind.8;, remember that it only
	    applies to principals that have a password policy assigned
	    to them.  The format used in
	    <filename>krb5.dict</filename> is one string per line.
	    Creating a symbolic link to
	    <filename>/usr/share/dict/words</filename> might be
	    useful.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Differences with the <acronym>MIT</acronym>
	Port</title>

      <para>The major difference between <acronym>MIT</acronym> and
	Heimdal relates to &man.kadmin.8; which has a different, but
	equivalent, set of commands and uses a different protocol.
	If the <acronym>KDC</acronym> is <acronym>MIT</acronym>, the
	Heimdal version of &man.kadmin.8; cannot be used to administer
	the <acronym>KDC</acronym> remotely, and vice versa.</para>

      <para>The client applications may also use slightly different
	command line options to accomplish the same tasks.
	Following the instructions on the <acronym>MIT</acronym>
	<application>Kerberos</application> <ulink
	  url="http://web.mit.edu/Kerberos/www/">web site</ulink> is
	recommended.  Be careful of path issues: the
	<acronym>MIT</acronym> port installs into <filename
	  class="directory">/usr/local/</filename> by default, and the
	<quote>normal</quote> system applications run instead of
	<acronym>MIT</acronym> versions if <envar>PATH</envar> lists
	the system directories first.</para>

      <note>
	<para>With the &os; <acronym>MIT</acronym> <filename
	    role="package">security/krb5</filename> port, be sure to
	  read
	  <filename>/usr/local/share/doc/krb5/README.FreeBSD</filename>
	  installed by the port to understand why logins via
	  &man.telnetd.8; and <command>klogind</command> behave
	  somewhat oddly.  Correcting the <quote>incorrect permissions
	  on cache file</quote> behavior requires that the
	  <command>login.krb5</command> binary be used for
	  authentication so that it can properly change ownership for
	  the forwarded credentials.</para>
      </note>

      <para>The following edits should also be made to
	<filename>rc.conf</filename>:</para>

      <programlisting>kerberos5_server="/usr/local/sbin/krb5kdc"
kadmind5_server="/usr/local/sbin/kadmind"
kerberos5_server_enable="YES"
kadmind5_server_enable="YES"</programlisting>

      <para>This is done because the applications for
	<acronym>MIT</acronym> Kerberos installs binaries in the
	<filename class="directory">/usr/local</filename>
	hierarchy.</para>
    </sect2>

    <sect2>
      <title>Mitigating Limitations Found in
	<application>Kerberos</application></title>

      <indexterm>
	<primary>Kerberos5</primary>
	<secondary>limitations and shortcomings</secondary>
      </indexterm>

      <sect3>
	<title><application>Kerberos</application> is an
	  All or Nothing Approach</title>

	<para>Every service enabled on the network must be modified
	  to work with <application>Kerberos</application>, or be
	  otherwise secured against network attacks, or else the
	  user's credentials could be stolen and re-used.  An example
	  of this would be <application>Kerberos</application>
	  enabling all remote shells but not converting the
	  <acronym>POP3</acronym> mail server which sends passwords in
	  plain text.</para>
      </sect3>

      <sect3>
	<title><application>Kerberos</application> is Intended for
	  Single-User Workstations</title>

	<para>In a multi-user environment,
	  <application>Kerberos</application> is less secure.  This is
	  because it stores the tickets in <filename
	    class="directory">/tmp</filename>, which is readable by
	  all users.  If a user is sharing a computer with other
	  users, it is possible that the user's tickets can be stolen
	  or copied by another user.</para>

	<para>This can be overcome with the <literal>-c</literal>
	  command-line option or, preferably, the
	  <envar>KRB5CCNAME</envar> environment variable.  Storing
	  the ticket in the user's home directory and using file
	  permissions are commonly used to mitigate this
	  problem.</para>
      </sect3>

      <sect3>
	<title>The KDC is a Single Point of Failure</title>

	<para>By design, the <acronym>KDC</acronym> must be as secure
	  as its master password database.  The <acronym>KDC</acronym>
	  should have absolutely no other services running on it and
	  should be physically secure.  The danger is high because
	  <application>Kerberos</application> stores all passwords
	  encrypted with the same <quote>master</quote> key which is
	  stored as a file on the <acronym>KDC</acronym>.</para>

	<para>A compromised master key is not quite as bad as one
	  might fear.  The master key is only used to encrypt the
	  <application>Kerberos</application> database and as a seed
	  for the random number generator.  As long as access to the
	  <acronym>KDC</acronym> is secure, an attacker cannot do much
	  with the master key.</para>

	<para>Additionally, if the <acronym>KDC</acronym> is
	  unavailable, network services are unusable as authentication
	  cannot be performed.  This can be alleviated with a single
	  master <acronym>KDC</acronym> and one or more slaves, and
	  with careful implementation of secondary or fall-back
	  authentication using <acronym>PAM</acronym>.</para>
      </sect3>

      <sect3>
	<title><application>Kerberos</application>
	  Shortcomings</title>

	<para><application>Kerberos</application> allows users, hosts
	  and services to authenticate between themselves.  It does
	  not have a mechanism to authenticate the
	  <acronym>KDC</acronym> to the users, hosts or services.
	  This means that a trojanned &man.kinit.1; could record all
	  user names and passwords.  Filesystem integrity checking
	  tools like <filename
	    role="package">security/tripwire</filename> can alleviate
	  this.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Resources and Further Information</title>

      <indexterm>
	<primary>Kerberos5</primary>
	<secondary>external resources</secondary>
      </indexterm>

      <itemizedlist>
	<listitem>
	  <para><ulink
	      url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html">
	      The <application>Kerberos</application>
	      FAQ</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://web.mit.edu/Kerberos/www/dialogue.html">Designing
	      an Authentication System: a Dialog in Four
	      Scenes</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC
	      1510, The <application>Kerberos</application> Network
	      Authentication Service (V5)</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym>
	      <application>Kerberos</application> home
	      page</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink url="http://www.pdc.kth.se/heimdal/">Heimdal
	      <application>Kerberos</application> home
	      page</ulink></para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="openssl">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>OpenSSL</title>

    <indexterm>
      <primary>security</primary>
      <secondary>OpenSSL</secondary>
    </indexterm>

    <para>The
      <application>OpenSSL</application> toolkit is included in &os;.
      It provides an encryption transport layer on top of the normal
      communications layer, allowing it to be intertwined with many
      network applications and services.</para>

    <para>Some uses of <application>OpenSSL</application> may include
      encrypted authentication of mail clients and web based
      transactions such as credit card payments.  Many ports such as
      <filename role="package">www/apache22</filename>, and
      <filename role="package">mail/claws-mail</filename> offer
      compilation support for building with
      <application>OpenSSL</application>.</para>

    <note>
      <para>In most cases, the Ports Collection will attempt to build
	the <filename role="package">security/openssl</filename>
	port unless <makevar>WITH_OPENSSL_BASE</makevar> is explicitly
	set to <quote>yes</quote>.</para>
    </note>

    <para>The version of <application>OpenSSL</application> included
      in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and
      Transport Layer Security v1 (TLSv1) network security protocols
      and can be used as a general cryptographic library.</para>

    <note>
      <para>While <application>OpenSSL</application> supports the
	<acronym>IDEA</acronym> algorithm, it is disabled by default
	due to United States patents.  To use it, the license should
	be reviewed and, if the restrictions are acceptable, the
	<makevar>MAKE_IDEA</makevar> variable must be set in
	<filename>/etc/make.conf</filename>.</para>
    </note>

    <para>One of the most common uses of
      <application>OpenSSL</application> is to provide certificates
      for use with software applications.  These certificates ensure
      that the credentials of the company or individual are valid
      and not fraudulent.  If the certificate in question has not
      been verified by a <quote>Certificate Authority</quote>
      (<acronym>CA</acronym>), a warning is produced.  A
      <acronym>CA</acronym> is a company, such as <ulink
	url="http://www.verisign.com">VeriSign</ulink>, signs
      certificates in order to validate the credentials of individuals
      or companies.  This process has a cost associated with it and is
      not a requirement for using certificates; however, it can put
      users at ease.</para>

    <sect2>
      <title>Generating Certificates</title>

      <indexterm>
	<primary>OpenSSL</primary>
	<secondary>certificate generation</secondary>
      </indexterm>

      <para>To generate a certificate, the following command is
	available:</para>

      <screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput>
Generating a 1024 bit RSA private key
................++++++
.......................................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput>
State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput>
Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput>
Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput>
Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput>
Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput>
Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput>

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput>
An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen>

      <para>Notice the response directly after the <quote>Common
	  Name</quote> prompt shows a domain name.  This prompt
	requires a server name to be entered for verification
	purposes and placing anything but a domain name yields a
	useless certificate.  Other options, such as the expire
	time and alternate encryption algorithms, are available.  A
	complete list of options is described in
	&man.openssl.1;.</para>

      <para>Two files should now exist in the directory in which this
	command was issued.  The certificate request,
	<filename>req.pem</filename>, may be sent to a
	<acronym>CA</acronym> who will validate the entered
	credentials, sign the request, and return the signed
	certificate.  The second file is named
	<filename>cert.pem</filename> and is the private key for the
	certificate and should be protected at all costs.  If this
	falls in the hands of others it can be used to impersonate
	the user or the server.</para>

      <para>In cases where a signature from a <acronym>CA</acronym>
	is not required, a self signed certificate can be created.
	First, generate the <acronym>RSA</acronym> key:</para>

      <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out <filename>myRSA.key</filename> 1024</userinput></screen>

      <para>Next, generate the <acronym>CA</acronym> key:</para>

      <screen>&prompt.root; <userinput>openssl gendsa -des3 -out <filename>myca.key</filename> <filename>myRSA.key</filename></userinput></screen>

      <para>Use this key to create the certificate:</para>

      <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key <filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen>

      <para>Two new files should appear in the directory: a
	certificate authority signature file,
	<filename>myca.key</filename> and the certificate itself,
	<filename>new.crt</filename>.  These should be placed in a
	directory, preferably under <filename
	  class="directory">/etc</filename>, which is readable only by
	<username>root</username>.  Permissions of 0700 are
	appropriate and can be set using &man.chmod.1;.</para>
    </sect2>

    <sect2>
      <title>Using Certificates</title>

      <para>One use for a certificate is to encrypt connections to the
	<application>Sendmail</application> <acronym>MTA</acronym>.
	This prevents the use of clear text authentication for users
	who send mail via the local <acronym>MTA</acronym>.</para>

      <note>
	<para>Some <acronym>MUA</acronym>s will display error if the
	  user has not installed the certificate locally.  Refer to
	  the documentation included with the software for more
	  information on certificate installation.</para>
      </note>

      <para>To configure <application>Sendmail</application>, the
	following lines should be placed in the local
	<filename>.mc</filename> file:</para>

      <programlisting>dnl SSL Options
define(`confCACERT_PATH',`/etc/certs')dnl
define(`confCACERT',`/etc/certs/new.crt')dnl
define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>

      <para>In this example,  <filename
	  class="directory">/etc/certs/</filename>
	stores the certificate and key files locally.  After saving
	the edits, rebuild the local <filename>.cf</filename> file by
	typing
	<command>make <maketarget>install</maketarget></command>
	within <filename class="directory">/etc/mail</filename>.
	Follow that up with <command>make
	  <maketarget>restart</maketarget></command> which should
	start the <application>Sendmail</application> daemon.</para>

      <para>If all went well, there will be no error messages in
	<filename>/var/log/maillog</filename> and
	<application>Sendmail</application> will show up in the
	process list.</para>

      <para>For a simple test, connect to the mail server using
	&man.telnet.1;:</para>

      <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput>
Trying 192.0.34.166...
Connected to <hostid role="fqdn">example.com</hostid>.
Escape character is '^]'.
220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
<userinput>ehlo <replaceable>example.com</replaceable></userinput>
250-example.com Hello example.com [192.0.34.166], pleased to meet you
250-ENHANCEDSTATUSCODES
250-PIPELINING
250-8BITMIME
250-SIZE
250-DSN
250-ETRN
250-AUTH LOGIN PLAIN
250-STARTTLS
250-DELIVERBY
250 HELP
<userinput>quit</userinput>
221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection
Connection closed by foreign host.</screen>

      <para>If the <quote>STARTTLS</quote> line appears in the
	output, everything is working correctly.</para>
    </sect2>
  </sect1>

  <sect1 id="ipsec">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Nik</firstname>
	  <surname>Clayton</surname>
	  <affiliation>
	    <address><email>nik@FreeBSD.org</email></address>
	  </affiliation>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title><acronym>VPN</acronym> over IPsec</title>

    <indexterm>
      <primary>IPsec</primary>
    </indexterm>

    <sect2>
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Hiten M.</firstname>
	    <surname>Pandya</surname>
	    <affiliation>
	      <address><email>hmp@FreeBSD.org</email></address>
	    </affiliation>
	    <contrib>Written by </contrib>
	  </author>
	</authorgroup>
      </sect2info>

      <title>Understanding IPsec</title>

      <para>This section demonstrates the process of setting up IPsec.
	It assumes familiarity with the concepts of building a custom
	kernel (see <xref linkend="kernelconfig"/>).</para>

      <para><emphasis>IPsec</emphasis> is a protocol which sits on
	top of the Internet Protocol (<acronym>IP</acronym>) layer.
	It allows two or more hosts to communicate in a secure manner.
	The &os; IPsec <quote>network stack</quote> is based on the
	<ulink url="http://www.kame.net/">KAME</ulink> implementation,
	which has support for both IPv4 and IPv6.</para>

      <indexterm>
	<primary>IPsec</primary>
	<secondary>ESP</secondary>
      </indexterm>

      <indexterm>
	<primary>IPsec</primary>
	<secondary>AH</secondary>
      </indexterm>

      <para>IPsec consists of two sub-protocols:</para>

      <itemizedlist>
	<listitem>
	  <para><emphasis>Encapsulated Security Payload
	      <acronym>ESP</acronym>)</emphasis>: this protocol
	    protects the IP packet data from third party interference
	    by encrypting the contents using symmetric cryptography
	    algorithms such as Blowfish and 3DES.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Authentication Header
	      (<acronym>AH</acronym>)</emphasis>: this protocol
	    protects the IP packet header from third party
	    interference and spoofing by computing a cryptographic
	    checksum and hashing the IP packet header fields with a
	    secure hashing function.  This is then followed by an
	    additional header that contains the hash, to allow the
	    information in the packet to be authenticated.</para>
	</listitem>
      </itemizedlist>

      <para><acronym>ESP</acronym> and <acronym>AH</acronym> can
	either be used together or separately, depending on the
	environment.</para>

      <indexterm>
	<primary>VPN</primary>
      </indexterm>

      <indexterm>
	<primary>virtual private network</primary>
	<see>VPN</see>
      </indexterm>

      <para>IPsec can either be used to directly encrypt the traffic
	between two hosts using <emphasis>Transport Mode</emphasis> or
	to build <quote>virtual tunnels</quote> using
	<emphasis>Tunnel Mode</emphasis>.  The latter mode is more
	commonly known as a <emphasis>Virtual Private Network
	(<acronym>VPN</acronym>)</emphasis>.  Consult &man.ipsec.4;
	for detailed information on the IPsec subsystem in
	&os;.</para>

      <para>To add IPsec support to the kernel, add the following
	options to the custom kernel configuration file:</para>

      <indexterm>
	<primary>kernel options</primary>
	<secondary>IPSEC</secondary>
      </indexterm>

      <screen>options   IPSEC        #IP security
device    crypto</screen>

      <indexterm>
	<primary>kernel options</primary>
	<secondary>IPSEC_DEBUG</secondary>
      </indexterm>

      <para>If IPsec debugging support is desired, the following
	kernel option should also be added:</para>

      <screen>options   IPSEC_DEBUG  #debug for IP security</screen>
    </sect2>

    <sect2>
      <title><acronym>VPN</acronym> Between a Home and Corporate
	Network</title>

      <indexterm>
	<primary>VPN</primary>
	<secondary>creating</secondary>
      </indexterm>

      <para>There is no standard for what constitutes a
	<acronym>VPN</acronym>.  <acronym>VPN</acronym>s can be
	implemented using a number of different technologies, each
	of which has their own strengths and weaknesses.  This
	section presents the strategies used for implementing a
	<acronym>VPN</acronym> for the following scenario:</para>

      <itemizedlist>
	<listitem>
	  <para>There are at least two sites where each site is using
	    IP internally.</para>
	</listitem>

	<listitem>
	  <para>Both sites are connected to the Internet through a
	    gateway that is running &os;.</para>
	</listitem>

	<listitem>
	  <para>The gateway on each network has at least one public
	    IP address.</para>
	</listitem>

	<listitem>
	  <para>The internal addresses of the two networks can be
	    either public or private IP addresses.  However, the
	    address space must not collide.  For example, both
	    networks cannot use
	    <hostid role="ipaddr">192.168.1.x</hostid>.</para>
	</listitem>
      </itemizedlist>

    <sect3>
      <sect3info>
	<authorgroup>
	  <author>
	    <firstname>Tom</firstname>
	    <surname>Rhodes</surname>
	    <affiliation>
	      <address><email>trhodes@FreeBSD.org</email></address>
	    </affiliation>
	    <contrib>Written by </contrib>
	  </author>
	</authorgroup>
      </sect3info>

      <title>Configuring IPsec on &os;</title>

      <para>To begin,
	<filename role="package">security/ipsec-tools</filename>
	must be installed from the Ports Collection.  This software
	provides a number of applications which support the
	configuration.</para>

      <para>The next requirement is to create two &man.gif.4;
	pseudo-devices which will be used to tunnel packets and
	allow both networks to communicate properly.  As
	<username>root</username>, run the following commands,
	replacing <replaceable>internal</replaceable> and
	<replaceable>external</replaceable> with the real IP
	addresses of the internal and external interfaces of the two
	gateways:</para>

      <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput></screen>

      <screen>&prompt.root; <userinput>ifconfig gif0 <replaceable>internal1 internal2</replaceable></userinput></screen>

      <screen>&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>external1 external2</replaceable></userinput></screen>

      <para>In this example, the corporate <acronym>LAN</acronym>'s
	external <acronym>IP</acronym> address is <hostid
	  role="ipaddr">172.16.5.4</hostid> and its internal
	<acronym>IP</acronym> address is <hostid
	  role="ipaddr">10.246.38.1</hostid>.  The home
	<acronym>LAN</acronym>'s external <acronym>IP</acronym>
	address is <hostid role="ipaddr">192.168.1.12</hostid> and its
	internal private <acronym>IP</acronym> address is <hostid
	  role="ipaddr">10.0.0.5</hostid>.</para>

      <para>If this is confusing, review the following example output
	from &man.ifconfig.8;:</para>

      <programlisting>Gateway 1:

gif0: flags=8051 mtu 1280
tunnel inet 172.16.5.4 --&gt; 192.168.1.12
inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6
inet 10.246.38.1 --&gt; 10.0.0.5 netmask 0xffffff00

Gateway 2:

gif0: flags=8051 mtu 1280
tunnel inet 192.168.1.12 --&gt; 172.16.5.4
inet 10.0.0.5 --&gt; 10.246.38.1 netmask 0xffffff00
inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4</programlisting>

      <para>Once complete, both internal <acronym>IP</acronym>
	addresses should be reachable using &man.ping.8;:</para>

      <programlisting>priv-net# ping 10.0.0.5
PING 10.0.0.5 (10.0.0.5): 56 data bytes
64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms
64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms
64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms
64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms
--- 10.0.0.5 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms

corp-net# ping 10.246.38.1
PING 10.246.38.1 (10.246.38.1): 56 data bytes
64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms
64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms
64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms
64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms
64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms
--- 10.246.38.1 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms</programlisting>

      <para>As expected, both sides have the ability to send and
	receive <acronym>ICMP</acronym> packets from the privately
	configured addresses.  Next, both gateways must be told how
	to route packets in order to correctly send traffic from
	either network.  The following command will achieve this
	goal:</para>

      <screen>&prompt.root; <userinput>corp-net# route add <replaceable>10.0.0.0 10.0.0.5 255.255.255.0</replaceable></userinput></screen>

      <screen>&prompt.root; <userinput>corp-net# route add net <replaceable>10.0.0.0: gateway 10.0.0.5</replaceable></userinput></screen>

      <screen>&prompt.root; <userinput>priv-net# route add <replaceable>10.246.38.0 10.246.38.1 255.255.255.0</replaceable></userinput></screen>

      <screen>&prompt.root; <userinput>priv-net# route add host <replaceable>10.246.38.0: gateway 10.246.38.1</replaceable></userinput></screen>

      <para>At this point, internal machines should be reachable
	from each gateway as well as from machines behind the
	gateways.  Again, use &man.ping.8; to confirm:</para>

      <programlisting>corp-net# ping 10.0.0.8
PING 10.0.0.8 (10.0.0.8): 56 data bytes
64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms
64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms
64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms
64 bytes from 10.0.0.8: icmp_seq=3 ttl=63 time=22.241 ms
64 bytes from 10.0.0.8: icmp_seq=4 ttl=63 time=174.705 ms
--- 10.0.0.8 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms

priv-net# ping 10.246.38.107
PING 10.246.38.1 (10.246.38.107): 56 data bytes
64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms
64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms
64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms
64 bytes from 10.246.38.107: icmp_seq=3 ttl=64 time=21.145 ms
64 bytes from 10.246.38.107: icmp_seq=4 ttl=64 time=36.708 ms
--- 10.246.38.107 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms</programlisting>

      <para>Setting up the tunnels is the easy part.  Configuring a
	secure link is a more in depth process.  The following
	configuration uses pre-shared (<acronym>PSK</acronym>)
	<acronym>RSA</acronym> keys.  Other than the
	<acronym>IP</acronym> addresses, the
	<filename>/usr/local/etc/racoon/racoon.conf</filename> on
	both gateways will be identical and look similar to:</para>

      <programlisting>path    pre_shared_key  "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file
log     debug;	#log verbosity setting: set to 'notify' when testing and debugging is complete

padding	# options are not to be changed
{
        maximum_length  20;
        randomize       off;
        strict_check    off;
        exclusive_tail  off;
}

timer	# timing options. change as needed
{
        counter         5;
        interval        20 sec;
        persend         1;
#       natt_keepalive  15 sec;
        phase1          30 sec;
        phase2          15 sec;
}

listen	# address [port] that racoon will listening on
{
        isakmp          172.16.5.4 [500];
        isakmp_natt     172.16.5.4 [4500];
}

remote  192.168.1.12 [500]
{
        exchange_mode   main,aggressive;
        doi             ipsec_doi;
        situation       identity_only;
        my_identifier   address 172.16.5.4;
        peers_identifier        address 192.168.1.12;
        lifetime        time 8 hour;
        passive         off;
        proposal_check  obey;
#       nat_traversal   off;
        generate_policy off;

                        proposal {
                                encryption_algorithm    blowfish;
                                hash_algorithm          md5;
                                authentication_method   pre_shared_key;
                                lifetime time           30 sec;
                                dh_group                1;
                        }
}

sainfo  (address 10.246.38.0/24 any address 10.0.0.0/24 any)	# address $network/$netmask $type address $network/$netmask $type ( $type being any or esp)
{								# $network must be the two internal networks you are joining.
        pfs_group       1;
        lifetime        time    36000 sec;
        encryption_algorithm    blowfish,3des,des;
        authentication_algorithm        hmac_md5,hmac_sha1;
        compression_algorithm   deflate;
}</programlisting>

      <para>For descriptions of each available option, refer to the
	manual page for <filename>racoon.conf</filename>.</para>

      <para>The Security Policy Database (<acronym>SPD</acronym>)
	needs to be configured so that &os; and
	<application>racoon</application> are able to encrypt and
	decrypt network traffic between the hosts.</para>

      <para>This can be achieved with a shell script, similar to the
	following, on the corporate gateway.  This file will be used
	during system initialization and should be saved as
	<filename>/usr/local/etc/racoon/setkey.conf</filename>.</para>

      <programlisting>flush;
spdflush;
# To the home network
spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use;
spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use;</programlisting>

      <para>Once in place, <application>racoon</application> may be
	started on both gateways using the following command:</para>

      <screen>&prompt.root; <userinput>/usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log</userinput></screen>

      <para>The output should be similar to the following:</para>

      <programlisting>corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf
Foreground mode.
2006-01-30 01:35:47: INFO: begin Identity Protection mode.
2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon
2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon
2006-01-30 01:36:04: INFO: ISAKMP-SA established 172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a
2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0]
2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]-&gt;172.16.5.4[0] spi=28496098(0x1b2d0e2)
2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]-&gt;192.168.1.12[0] spi=47784998(0x2d92426)
2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0]
2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]-&gt;172.16.5.4[0] spi=124397467(0x76a279b)
2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]-&gt;192.168.1.12[0] spi=175852902(0xa7b4d66)</programlisting>

      <para>To ensure the tunnel is working properly, switch to
	another console and use &man.tcpdump.1; to view network
	traffic using the following command.  Replace
	<literal>em0</literal> with the network interface card as
	required:</para>

      <screen>&prompt.root; <userinput>tcpdump -i em0 host <replaceable>172.16.5.4 and dst 192.168.1.12</replaceable></userinput></screen>

      <para>Data similar to the following should appear on the
	console.  If not, there is an issue and debugging the
	returned data will be required.</para>

      <programlisting>01:47:32.021683 IP corporatenetwork.com &gt; 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa)
01:47:33.022442 IP corporatenetwork.com &gt; 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb)
01:47:34.024218 IP corporatenetwork.com &gt; 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc)</programlisting>

      <para>At this point, both networks should be available and
	seem to be part of the same network.  Most likely both
	networks are protected by a firewall.  To allow traffic to
	flow between them, rules need to be added to pass packets.
	For the &man.ipfw.8; firewall, add the following lines to the
	firewall configuration file:</para>

      <programlisting>ipfw add 00201 allow log esp from any to any
ipfw add 00202 allow log ah from any to any
ipfw add 00203 allow log ipencap from any to any
ipfw add 00204 allow log udp from any 500 to any</programlisting>

      <note>
	<para>The rule numbers may need to be altered depending on
	  the current host configuration.</para>
      </note>

      <para>For users of &man.pf.4; or &man.ipf.8;, the following
	rules should do the trick:</para>

      <programlisting>pass in quick proto esp from any to any
pass in quick proto ah from any to any
pass in quick proto ipencap from any to any
pass in quick proto udp from any port = 500 to any port = 500
pass in quick on gif0 from any to any
pass out quick proto esp from any to any
pass out quick proto ah from any to any
pass out quick proto ipencap from any to any
pass out quick proto udp from any port = 500 to any port = 500
pass out quick on gif0 from any to any</programlisting>

      <para>Finally, to allow the machine to start support for the
	<acronym>VPN</acronym> during system initialization, add the
	following lines to <filename>/etc/rc.conf</filename>:</para>

      <programlisting>ipsec_enable="YES"
ipsec_program="/usr/local/sbin/setkey"
ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot
racoon_enable="yes"</programlisting>
    </sect3>
  </sect2>
  </sect1>

  <sect1 id="openssh">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
	</author>
	<!-- 21 April 2001 -->
      </authorgroup>
    </sect1info>

    <title>OpenSSH</title>

    <indexterm><primary>OpenSSH</primary></indexterm>
    <indexterm>
      <primary>security</primary>
      <secondary>OpenSSH</secondary>
    </indexterm>

    <para><application>OpenSSH</application> is a set of network
      connectivity tools used to access remote machines securely.
      Additionally, TCP/IP connections can be tunneled/forwarded
      securely through <acronym>SSH</acronym> connections.
      <application>OpenSSH</application> encrypts all traffic to
      effectively eliminate eavesdropping, connection hijacking, and
      other network-level attacks.</para>

    <para><application>OpenSSH</application> is maintained by the
      OpenBSD project and is installed by default in &os;.  It is
      compatible with both <acronym>SSH</acronym> version 1 and 2
      protocols.</para>

    <sect2>
      <title>Advantages of Using
	<application>OpenSSH</application></title>

      <para>When data is sent over the network in an unencrypted form,
	network sniffers anywhere in between the client and server
	can steal user/password information or data transferred
	during the session.  <application>OpenSSH</application> offers
	a variety of authentication and encryption methods to prevent
	this from happening.</para>
    </sect2>

    <sect2>
      <title>Enabling The SSH Server</title>

      <indexterm>
	<primary>OpenSSH</primary>
	<secondary>enabling</secondary>
      </indexterm>

      <para>To see if &man.sshd.8; is enabled, check
	<filename>/etc/rc.conf</filename> for this line:</para>

      <programlisting>sshd_enable="YES"</programlisting>

      <para>This will start &man.sshd.8;, the daemon program for
	<application>OpenSSH</application>, the next time the system
	initializes.  Alternatively, it is possible to use
	&man.service.8; to start <application>OpenSSH</application>
	now:</para>

      <screen>&prompt.root; <userinput>service sshd start</userinput></screen>
    </sect2>

    <sect2>
      <title>The SSH Client</title>

      <indexterm>
	<primary>OpenSSH</primary>
	<secondary>client</secondary>
      </indexterm>

      <para>To use &man.ssh.1; to connect to a system running
	&man.sshd.8;, specify the username and host to log
	into:</para>

      <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput>
Host key not found from the list of known hosts.
Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput>
Host 'example.com' added to the list of known hosts.
user@example.com's password: <userinput>*******</userinput></screen>

      <para><acronym>SSH</acronym> utilizes a key fingerprint system
	to verify the authenticity of the server when the client
	connects.  The user is prompted to type
	<literal>yes</literal> when connecting for the first time.
	Future attempts to login are verified against the saved
	fingerprint key and the &man.ssh.1; client will display an
	alert if the saved fingerprint differs from the received
	fingerprint on future login attempts.  The fingerprints are
	saved in <filename>~/.ssh/known_hosts</filename>.</para>

      <para>By default, recent versions of &man.sshd.8; only accept
	<acronym>SSH</acronym> v2 connections.  The client will use
	version 2 if possible and will fall back to version 1.  The
	client can also be forced to use one or the other by passing
	it the <option>-1</option> or <option>-2</option> for version
	1 or version 2, respectively.  The version 1 compatibility is
	maintained in the client for backwards compatibility with
	older versions.</para>
    </sect2>

    <sect2>
      <title>Secure Copy</title>

      <indexterm>
	<primary>OpenSSH</primary>
	<secondary>secure copy</secondary>
      </indexterm>
      <indexterm>
	<primary>&man.scp.1;</primary>
      </indexterm>

      <para>Use &man.scp.1; to copy a file to or from a remote machine
	in a secure fashion.</para>

      <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
user@example.com's password: <userinput>*******</userinput>
COPYRIGHT            100% |*****************************|  4735
00:00
&prompt.root;</screen>

      <para>Since the fingerprint was already saved for this host in
	the previous example, it is verified when using &man.scp.1;
	here.</para>

      <para>The arguments passed to &man.scp.1; are similar to
	&man.cp.1;, with the file or files to copy in the first
	argument, and the destination in the second.  Since the file
	is fetched over the network, through an
	<acronym>SSH</acronym>, connection, one or more of the file
	arguments takes the form
	<option>user@host:&lt;path_to_remote_file&gt;</option>.</para>
    </sect2>

    <sect2>
      <title>Configuration</title>

      <indexterm>
	<primary>OpenSSH</primary>
	<secondary>configuration</secondary>
      </indexterm>

      <para>The system-wide configuration files for both the
	<application>OpenSSH</application> daemon and client reside
	in <filename class="directory">/etc/ssh</filename>.</para>

      <para><filename>ssh_config</filename> configures the client
	settings, while <filename>sshd_config</filename> configures
	the daemon.  Each file has its own manual page which describes
	the available configuration options.</para>
    </sect2>

    <sect2 id="security-ssh-keygen">
      <title>&man.ssh-keygen.1;</title>

      <para>Instead of using passwords, &man.ssh-keygen.1; can be used
	to generate <acronym>DSA</acronym> or <acronym>RSA</acronym>
	keys to authenticate a user:</para>

      <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput>
Generating public/private dsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_dsa):
Created directory '/home/user/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/user/.ssh/id_dsa.
Your public key has been saved in /home/user/.ssh/id_dsa.pub.
The key fingerprint is:
bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</screen>

      <para>&man.ssh-keygen.1; will create a public and private key
	pair for use in authentication.  The private key is stored
	in <filename>~/.ssh/id_dsa</filename> or
	<filename>~/.ssh/id_rsa</filename>, whereas the public key
	is stored in <filename>~/.ssh/id_dsa.pub</filename> or
	<filename>~/.ssh/id_rsa.pub</filename>, respectively for the
	<acronym>DSA</acronym> and <acronym>RSA</acronym> key types.
	The public key must be placed in the
	<filename>~/.ssh/authorized_keys</filename> file of the
	remote machine for both <acronym>RSA</acronym> or
	<acronym>DSA</acronym> keys in order for the setup to
	work.</para>

      <para>This setup allows connections to the remote machine based
	upon <acronym>SSH</acronym> keys instead of passwords.</para>

      <warning>
	<para>Many users believe that keys are secure by design and
	  will use a key without a passphrase.  This is
	  <emphasis>dangerous</emphasis> behavior and the method
	  an administrator may use to verify keys have a passphrase
	  is to view the key manually.  If the private key file
	  contains the word <literal>ENCRYPTED</literal> the key
	  owner is using a passphrase.  While it may still be a weak
	  passphrase, at least if the system is compromised, access
	  to other sites will still require some level of password
	  guessing.  In addition, to better secure end users, the
	  <literal>from</literal> may be placed in the public key
	  file.  For example, adding
	  <literal>from="192.168.10.5</literal> in the front of
	  <literal>ssh-rsa</literal> or <literal>rsa-dsa</literal>
	  prefix will only allow that specific user to login from
	  that host <acronym>IP</acronym>.</para>
      </warning>

      <para>If a passphrase is used in &man.ssh-keygen.1;, the user
	will be prompted for the passphrase each time in order to use
	the private key.  &man.ssh-agent.1; can alleviate the strain
	of repeatedly entering long passphrases, and is explored in
	<xref linkend="security-ssh-agent"/>.</para>

      <warning>
	<para>The various options and files can be different according
	  to the <application>OpenSSH</application> version.  To avoid
	  problems, consult &man.ssh-keygen.1;.</para>
      </warning>
    </sect2>

    <sect2 id="security-ssh-agent">
      <title>Using SSH Agent To Cache Keys</title>

      <para>To load <acronym>SSH</acronym> keys into memory for use,
	without needing to type the passphrase each time, use
	&man.ssh-agent.1; and &man.ssh-add.1;.</para>

      <para>Authentication is handled by &man.ssh-agent.1;, using the
	private key(s) that are loaded into it.  Then,
	&man.ssh-agent.1; should be used to launch another
	application.  At the most basic level, it could spawn a shell
	or a window manager.</para>

      <para>To use &man.ssh-agent.1; in a shell, start it with a shell
	as an argument.  Next, add the identity by running
	&man.ssh-add.1; and providing it the passphrase for the
	private key.  Once these steps have been completed, the user
	will be able to &man.ssh.1; to any host that has the
	corresponding public key installed.  For example:</para>

      <screen>&prompt.user; ssh-agent <replaceable>csh</replaceable>
&prompt.user; ssh-add
Enter passphrase for /home/user/.ssh/id_dsa:
Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa)
&prompt.user;</screen>

      <para>To use &man.ssh-agent.1; in
	<application>&xorg;</application>, a call to &man.ssh-agent.1;
	needs to be placed in <filename>~/.xinitrc</filename>.  This
	provides the &man.ssh-agent.1; services to all programs
	launched in <application>&xorg;</application>.  An example
	<filename>~/.xinitrc</filename> file might look like
	this:</para>

      <programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting>

      <para>This launches &man.ssh-agent.1;, which in turn launches
	<application>XFCE</application>, every time
	<application>&xorg;</application> starts.  Once
	<application>&xorg;</application> has been restarted so that
	the changes can take effect, run &man.ssh-add.1; to load all
	of the <acronym>SSH</acronym> keys.</para>
    </sect2>

    <sect2 id="security-ssh-tunneling">
      <title><acronym>SSH</acronym> Tunneling</title>

      <indexterm>
	<primary>OpenSSH</primary>
	<secondary>tunneling</secondary>
      </indexterm>

      <para><application>OpenSSH</application> has the ability to
	create a tunnel to encapsulate another protocol in an
	encrypted session.</para>

      <para>The following command tells &man.ssh.1; to create a
	tunnel for &man.telnet.1;:</para>

      <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput>
&prompt.user;</screen>

      <para>This example uses the following options:</para>

      <variablelist>
	<varlistentry>
	  <term><option>-2</option></term>

	  <listitem>
	    <para>Forces &man.ssh.1; to use version 2 to connect to
	      the server.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-N</option></term>

	  <listitem>
	    <para>Indicates no command, or tunnel only.  If omitted,
	      &man.ssh.1; initiates a normal session.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-f</option></term>

	  <listitem>
	    <para>Forces &man.ssh.1; to run in the background.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-L</option></term>

	  <listitem>
	    <para>Indicates a local tunnel in
	      <replaceable>localport:remotehost:remoteport</replaceable>
	      format.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>user@foo.example.com</option></term>

	  <listitem>
	    <para>The login name to use on the specified remote
	      <acronym>SSH</acronym> server.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>An <acronym>SSH</acronym> tunnel works by creating a
	listen socket on <hostid>localhost</hostid> on the specified
	port.  It then forwards any connections received on the local
	host/port via the <acronym>SSH</acronym> connection to the
	specified remote host and port.</para>

      <para>In the example, port <replaceable>5023</replaceable> on
	<hostid>localhost</hostid> is forwarded to port
	<replaceable>23</replaceable> on <hostid>localhost</hostid>
	of the remote machine.  Since <replaceable>23</replaceable>
	is used by &man.telnet.1;, this creates an encrypted
	&man.telnet.1; session through an
	<acronym>SSH</acronym> tunnel.</para>

      <para>This can be used to wrap any number of insecure TCP
	protocols such as SMTP, POP3, and FTP.</para>

      <example>
	<title>Using &man.ssh.1; to Create a Secure Tunnel
	  for SMTP</title>

	<screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
user@mailserver.example.com's password: <userinput>*****</userinput>
&prompt.user; <userinput>telnet localhost 5025</userinput>
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 mailserver.example.com ESMTP</screen>

	<para>This can be used in conjunction with &man.ssh-keygen.1;
	  and additional user accounts to create a more seamless
	  <acronym>SSH</acronym> tunneling environment.  Keys can be
	  used in place of typing a password, and the tunnels can be
	  run as a separate user.</para>
      </example>

      <sect3>
	<title>Practical <acronym>SSH</acronym> Tunneling
	  Examples</title>

	<sect4>
	  <title>Secure Access of a POP3 Server</title>

	  <para>In this example, there is an <acronym>SSH</acronym>
	    server that accepts connections from the outside.  On the
	    same network resides a mail server running a POP3 server.
	    To check email in a secure manner, create an
	    <acronym>SSH</acronym> connection to the
	    <acronym>SSH</acronym> server, and tunnel through to the
	    mail server.</para>

	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
user@ssh-server.example.com's password: <userinput>******</userinput></screen>

	  <para>Once the tunnel is up and running, point the email
	    client to send POP3 requests to <hostid>localhost</hostid>
	    on port 2110.  This connection will be forwarded securely
	    across the tunnel to
	    <hostid>mail.example.com</hostid>.</para>
	</sect4>

	<sect4>
	  <title>Bypassing a Draconian Firewall</title>

	  <para>Some network administrators impose firewall rules
	    which filter both incoming and outgoing connections.  For
	    example, it might limit access from remote machines to
	    ports 22 and 80 to only allow &man.ssh.1; and web surfing.
	    This prevents access to any other service which uses a
	    port other than 22 or 80.</para>

	  <para>The solution is to create an <acronym>SSH</acronym>
	    connection to a machine outside of the network's firewall
	    and use it to tunnel to the desired service.</para>

	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput>
user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen>

	  <para>In this example, a streaming Ogg Vorbis client can now
	    be pointed to <hostid>localhost</hostid> port 8888, which
	    will be forwarded over to
	    <hostid>music.example.com</hostid> on port 8000,
	    successfully bypassing the firewall.</para>
	</sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>The <varname>AllowUsers</varname> Option</title>

      <para>It is often a good idea to limit which users can log in
	and from where using <literal>AllowUsers</literal>.  For
	example, to only allow <username>root</username> to log in
	from <hostid role="ipaddr">192.168.1.32</hostid>, add this
	line to <filename>/etc/ssh/sshd_config</filename>:</para>

      <programlisting>AllowUsers root@192.168.1.32</programlisting>

      <para>To allow <username>admin</username> to log in from
	anywhere, list that username by itself:</para>

      <programlisting>AllowUsers admin</programlisting>

      <para>Multiple users should be listed on the same line, like
	so:</para>

      <programlisting>AllowUsers root@192.168.1.32 admin</programlisting>

      <note>
	<para>It is important to list each user that needs to log into
	  this machine; otherwise, they will be locked out.</para>
      </note>

      <para>After making changes to
	<filename>/etc/ssh/sshd_config</filename>, tell &man.sshd.8;
	to reload its configuration file by running:</para>

      <screen>&prompt.root; <userinput>service sshd reload</userinput></screen>
    </sect2>

    <sect2>
      <title>Further Reading</title>

      <para>The <ulink url="http://www.openssh.com/">OpenSSH</ulink>
	website.</para>

      <para>&man.ssh.1;, &man.scp.1;, &man.ssh-keygen.1;,
	&man.ssh-agent.1;, &man.ssh-add.1;, and &man.ssh.config.5; for
	client options.</para>

      <para>&man.sshd.8;, &man.sftp-server.8;, and &man.sshd.config.5;
	for server options.</para>
    </sect2>
  </sect1>

  <sect1 id="fs-acl">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Filesystem Access Control Lists
      (<acronym>ACL</acronym>s)</title>

    <indexterm>
      <primary>ACL</primary>
    </indexterm>

    <para>Filesystem Access Control Lists (<acronym>ACL</acronym>s)
      extend the standard &unix; permission model in a &posix;.1e
      compatible way.  This permits an administrator to make use of
      and take advantage of a more sophisticated security
      model.</para>

    <para>The &os; <filename>GENERIC</filename> kernel provides
      <acronym>ACL</acronym> support for <acronym>UFS</acronym> file
      systems.  Users who prefer to compile a custom kernel must
      include the following option in their custom kernel
      configuration file:</para>

    <programlisting>options UFS_ACL</programlisting>

    <para>If this option is not compiled in, a warning message will be
      displayed when attempting to mount a filesystem supporting
      <acronym>ACL</acronym>s.  <acronym>ACL</acronym>s rely on
      extended attributes being enabled on the filesystem.  Extended
      attributes are natively supported in
      <acronym>UFS2</acronym>.</para>

    <note>
      <para>A higher level of administrative overhead is required to
	configure extended attributes on <acronym>UFS1</acronym>
	than on <acronym>UFS2</acronym>.  The performance of
	extended attributes on <acronym>UFS2</acronym> is also
	substantially higher.  As a result, <acronym>UFS2</acronym>
	is recommended for use with <acronym>ACL</acronym>s.</para>
    </note>

    <para><acronym>ACL</acronym>s are enabled by the mount-time
      administrative flag, <option>acls</option>, which may be added
      to <filename>/etc/fstab</filename>.  The mount-time flag can
      also be automatically set in a persistent manner using
      &man.tunefs.8; to modify a superblock <acronym>ACL</acronym>s
      flag in the filesystem header.  In general, it is preferred
      to use the superblock flag for several reasons:</para>

    <itemizedlist>
      <listitem>
	<para>The mount-time <acronym>ACL</acronym>s flag cannot be
	  changed by a remount using <option>mount -u</option>.  It
	  requires a complete &man.umount.8; and fresh &man.mount.8;.
	  This means that <acronym>ACL</acronym>s cannot be enabled on
	  the root filesystem after boot.  It also means that the
	  disposition of a filesystem cannot be changed once it is in
	  use.</para>
      </listitem>

      <listitem>
	<para>Setting the superblock flag will cause the filesystem
	  to always be mounted with <acronym>ACL</acronym>s enabled,
	  even if there is not an <filename>fstab</filename> entry
	  or if the devices re-order.  This prevents accidental
	  mounting of the filesystem without <acronym>ACL</acronym>s
	  enabled, which can result in the security problem of
	  <acronym>ACL</acronym>s being improperly enforced.</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>It is desirable to discourage accidental mounting without
	<acronym>ACL</acronym>s enabled, because nasty things can
	happen if <acronym>ACL</acronym>s are enabled, then disabled,
	then re-enabled without flushing the extended attributes.  In
	general, once <acronym>ACL</acronym>s are enabled on a
	filesystem, they should not be disabled, as the resulting file
	protections may not be compatible with those intended by the
	users of the system, and re-enabling <acronym>ACL</acronym>s
	may re-attach the previous <acronym>ACL</acronym>s to files
	that have since had their permissions changed, resulting in
	unpredictable behavior.</para>
    </note>

    <para>Filesystems with <acronym>ACL</acronym>s enabled will
      show a <literal>+</literal> (plus) sign in their permission
      settings when viewed.  For example:</para>

    <programlisting>drwx------  2 robert  robert  512 Dec 27 11:54 private
drwxrwx---+ 2 robert  robert  512 Dec 23 10:57 directory1
drwxrwx---+ 2 robert  robert  512 Dec 22 10:20 directory2
drwxrwx---+ 2 robert  robert  512 Dec 27 11:57 directory3
drwxr-xr-x  2 robert  robert  512 Nov 10 11:54 public_html</programlisting>

    <para>In this example,
      <filename class="directory">directory1</filename>,
      <filename class="directory">directory2</filename>, and
      <filename class="directory">directory3</filename>
      are all taking advantage of <acronym>ACL</acronym>s, whereas
      <filename class="directory">public_html</filename>
      is not.</para>

    <sect2>
      <title>Making Use of <acronym>ACL</acronym>s</title>

      <para>Filesystem <acronym>ACL</acronym>s can be viewed using
	&man.getfacl.1;.  For instance, to view the
	<acronym>ACL</acronym> settings on
	<filename>test</filename>:</para>

      <screen>&prompt.user; <userinput>getfacl <filename>test</filename></userinput>
	#file:test
	#owner:1001
	#group:1001
	user::rw-
	group::r--
	other::r--</screen>

      <para>To change the <acronym>ACL</acronym> settings on this
	file, use &man.setfacl.1;:</para>

      <screen>&prompt.user; <userinput>setfacl -k <filename>test</filename></userinput></screen>

      <para>To remove all of the currently defined
	<acronym>ACL</acronym>s from a file or filesystem, one can use
	<option>-k</option>.  However, the preferred method is to use
	<option>-b</option> as it leaves the basic fields required
	for <acronym>ACL</acronym>s to work.</para>

      <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- <filename>test</filename></userinput></screen>

      <para>In this example, <option>-m</option> is used to modify the
	default <acronym>ACL</acronym> entries.  Since there were no
	pre-defined entries, as they were removed by the previous
	command, it restores the default options and assign the
	options listed.  If a user or group is added which does not
	exist on the system, an <errorname>Invalid
	  argument</errorname> error will be displayed.</para>
    </sect2>
  </sect1>

  <sect1 id="security-portaudit">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Monitoring Third Party Security Issues</title>

    <indexterm>
      <primary>portaudit</primary>
    </indexterm>

    <para>In recent years, the security world has made many
      improvements to how vulnerability assessment is handled.  The
      threat of system intrusion increases as third party utilities
      are installed and configured for virtually any operating
      system available today.</para>

    <para>Vulnerability assessment is a key factor in security.
      While &os; releases advisories for the base system, doing so
      for every third party utility is beyond the &os; Project's
      capability.  There is a way to mitigate third party
      vulnerabilities and warn administrators of known security
      issues.  A &os; add on utility known as
      <application>portaudit</application> exists solely for this
      purpose.</para>

    <para>The
      <filename role="package">ports-mgmt/portaudit</filename>
      port polls a database, which is updated and maintained by the
      &os; Security Team and ports developers, for known security
      issues.</para>

    <para>To install <application>portaudit</application> from the
      Ports Collection:</para>

    <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portaudit &amp;&amp; make install clean</userinput></screen>

    <para>During the installation, the configuration files for
      &man.periodic.8; will be updated, permitting
      <application>portaudit</application> output in the daily
      security runs.  Ensure that the daily security run emails, which
      are sent to <username>root</username>'s email account, are
      being read.  No other configuration is required.</para>

    <para>After installation, an administrator can update the
      database and view known vulnerabilities in installed packages
      by invoking the following command:</para>

    <screen>&prompt.root; <userinput>portaudit -Fda</userinput></screen>

    <note>
      <para>The database is automatically updated during the
	&man.periodic.8; run.  The above command is optional and can
	be used to manually update the database now.</para>
    </note>

    <para>To audit the third party utilities installed as part of
      the Ports Collection at anytime, an administrator can run the
      following command:</para>

    <screen>&prompt.root; <userinput>portaudit -a</userinput></screen>

    <para><application>portaudit</application> will display messages
      for any installed vulnerable packages:</para>

    <programlisting>Affected package: cups-base-1.1.22.0_1
Type of problem: cups-base -- HPGL buffer overflow vulnerability.
Reference: &lt;http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html&gt;

1 problem(s) in your installed packages found.

You are advised to update or deinstall the affected package(s) immediately.</programlisting>

    <para>By pointing a web browser to the displayed
      <acronym>URL</acronym>, an administrator may obtain more
      information about the vulnerability.  This will include the
      versions affected, by &os; port version, along with other web
      sites which may contain security advisories.</para>

    <para><application>portaudit</application> is a powerful utility
      and is extremely useful when coupled with the
      <application>portmaster</application> port.</para>
  </sect1>

  <sect1 id="security-advisories">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>&os; Security Advisories</title>

    <indexterm>
      <primary>&os; Security Advisories</primary>
    </indexterm>

    <para>Like many production quality operating systems, &os;
      publishes <quote>Security Advisories</quote>.  These
      advisories are usually mailed to the security lists and noted
      in the Errata only after the appropriate releases have been
      patched.  This section explains what an advisory is, how to
      understand it, and what measures to take in order to patch a
      system.</para>

    <sect2>
      <title>What Does an Advisory Look Like?</title>

      <para>&os; security advisories use the format seen in this
	example:</para>

      <programlisting>=============================================================================
FreeBSD-SA-XX:XX.UTIL                                       Security Advisory
                                                          The FreeBSD Project

Topic:          denial of service due to some problem <co id="co-topic"/>

Category:       core <co id="co-category"/>
Module:         sys <co id="co-module"/>
Announced:      2003-09-23 <co id="co-announce"/>
Credits:        Person <co id="co-credit"/>
Affects:        All releases of &os; <co id="co-affects"/>
                &os; 4-STABLE prior to the correction date
Corrected:      2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE)
                2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6)
                2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15)
                2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8)
                2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18)
                2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21)
                2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33)
                2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43)
                2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) <co id="co-corrected"/>
<acronym>CVE</acronym> Name:       CVE-XXXX-XXXX <co id="co-cve"/>

For general information regarding FreeBSD Security Advisories,
including descriptions of the fields above, security branches, and the
following sections, please visit
http://www.FreeBSD.org/security/.

I.   Background <co id="co-backround"/>


II.  Problem Description <co id="co-descript"/>


III. Impact <co id="co-impact"/>


IV.  Workaround <co id="co-workaround"/>


V.   Solution <co id="co-solution"/>


VI.  Correction details <co id="co-details"/>


VII. References <co id="co-ref"/></programlisting>

      <calloutlist>
	<callout arearefs="co-topic">
	  <para>The <literal>Topic</literal> field specifies the
	    problem.  It provides an introduction to the security
	    advisory and notes the utility affected by the
	    vulnerability.</para>
	</callout>

	<callout arearefs="co-category">
	  <para>The <literal>Category</literal> refers to the
	    affected part of the system which may be one of
	    <literal>core</literal>, <literal>contrib</literal>, or
	    <literal>ports</literal>.  The <literal>core</literal>
	    category means that the vulnerability affects a core
	    component of the &os; operating system.  The
	    <literal>contrib</literal> category means that the
	    vulnerability affects software contributed to the &os;
	    Project, such as <application>Sendmail</application>.
	    The <literal>ports</literal> category indicates that the
	    vulnerability affects add on software available through
	    the Ports Collection.</para>
	</callout>

	<callout arearefs="co-module">
	  <para>The <literal>Module</literal> field refers to the
	    component location.  In this example, the
	    <literal>sys</literal> module is affected; therefore, this
	    vulnerability affects a component used within the
	    kernel.</para>
	</callout>

	<callout arearefs="co-announce">
	  <para>The <literal>Announced</literal> field reflects the
	    date the security advisory was published, or announced
	    to the world.  This means that the security team has
	    verified that the problem exists and that a patch has
	    been committed to the &os; source code repository.</para>
	</callout>

	<callout arearefs="co-credit">
	  <para>The <literal>Credits</literal> field gives credit to
	    the individual or organization who noticed the
	    vulnerability and reported it.</para>
	</callout>

	<callout arearefs="co-affects">
	  <para>The <literal>Affects</literal> field explains which
	    releases of &os; are affected by this vulnerability.
	    For the kernel, a quick look over the output from
	    &man.ident.1; on the affected files will help in
	    determining the revision.  For ports, the version number
	    is listed after the port name in <filename
	      class="directory">/var/db/pkg</filename>.  If the
	    system does not sync with the &os; Subversion repository
	    and is not rebuilt daily, chances are that it is
	    affected.</para>
	</callout>

	<callout arearefs="co-corrected">
	  <para>The <literal>Corrected</literal> field indicates the
	    date, time, time offset, and release that was
	    corrected.</para>
	</callout>

	<callout arearefs="co-cve">
	  <para>Reserved for the identification information used to
	    look up vulnerabilities in the <ulink
	      url="http://cve.mitre.org">Common Vulnerabilities
	      and Exposures</ulink> database.</para>
	</callout>

	<callout arearefs="co-backround">
	  <para>The <literal>Background</literal> field gives
	    information about the affected utility.  Most of the time
	    this is why the utility exists in &os;, what it is used
	    for, and a bit of information on how the utility came to
	    be.</para>
	</callout>

	<callout arearefs="co-descript">
	  <para>The <literal>Problem Description</literal> field
	    explains the security hole in depth.  This can include
	    information on flawed code, or even how the utility
	    could be maliciously used to open a security hole.</para>
	</callout>

	<callout arearefs="co-impact">
	  <para>The <literal>Impact</literal> field describes what
	    type of impact the problem could have on a system.  For
	    example, this could be anything from a denial of service
	    attack, to extra privileges available to users, or even
	    giving the attacker superuser access.</para>
	</callout>

	<callout arearefs="co-workaround">
	  <para>The <literal>Workaround</literal> field offers a
	    workaround to system administrators who cannot
	    upgrade the system due to time constraints, network
	    availability, or other reasons.  Security should not be
	    taken lightly, and an affected system should either be
	    patched or the workaround implemented.</para>
	</callout>

	<callout arearefs="co-solution">
	  <para>The <literal>Solution</literal> field offers
	    instructions for patching the affected system.  This is a
	    step by step tested and verified method for getting a
	    system patched and working securely.</para>
	</callout>

	<callout arearefs="co-details">
	  <para>The <literal>Correction Details</literal> field
	    displays the Subversion branch or release name with the
	    periods changed to underscore characters.  It also shows
	    the revision number of the affected files within each
	    branch.</para>
	</callout>

	<callout arearefs="co-ref">
	  <para>The <literal>References</literal> field usually
	    offers sources of other information.  This can include
	    web <acronym>URL</acronym>s, books, mailing lists, and
	    newsgroups.</para>
	</callout>
      </calloutlist>
    </sect2>
  </sect1>

  <sect1 id="security-accounting">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Process Accounting</title>

    <indexterm>
      <primary>Process Accounting</primary>
    </indexterm>

    <para>Process accounting is a security method in which an
      administrator may keep track of system resources used and
      their allocation among users, provide for system monitoring,
      and minimally track a user's commands.</para>

    <para>This indeed has both positive and negative points.  One
      of the positives is that an intrusion may be narrowed down to
      the point of entry.  A negative is the amount of logs
      generated by process accounting, and the disk space they may
      require.  This section walks an administrator through the
      basics of process accounting.</para>

    <sect2>
      <title>Enabling and Utilizing Process Accounting</title>

      <para>Before using process accounting, it must be enabled using
	the following commands:</para>

      <screen>&prompt.root; <userinput>touch <filename>/var/account/acct</filename></userinput>

&prompt.root; <userinput>accton <filename>/var/account/acct</filename></userinput>

&prompt.root; <userinput>echo 'accounting_enable="YES"' &gt;&gt; <filename>/etc/rc.conf</filename></userinput></screen>

      <para>Once enabled, accounting will begin to track information
	such as <acronym>CPU</acronym> statistics and executed
	commands.  All accounting logs are in a non-human readable
	format which can be viewed using &man.sa.8;.  If issued
	without any options, &man.sa.8; prints information relating to
	the number of per-user calls, the total elapsed time in
	minutes, total <acronym>CPU</acronym> and user time in
	minutes, and the average number of I/O operations.</para>

      <para>To view information about commands being issued, use
	&man.lastcomm.1;.  This command displays the commands issued
	by users on specific &man.ttys.5;.  For example, this command
	prints out all known usage of &man.ls.1; by
	<username>trhodes</username> on the <literal>ttyp1</literal>
	terminal:</para>

      <screen>&prompt.root; <userinput>lastcomm ls
	<username>trhodes</username> ttyp1</userinput></screen>

      <para>Many other useful options exist and are explained in the
	&man.lastcomm.1;, &man.acct.5;, and &man.sa.8;.</para>
    </sect2>
  </sect1>

  <sect1 id="security-resourcelimits">
    <sect1info>
      <authorgroup>
       <author>
         <firstname>Tom</firstname>
         <surname>Rhodes</surname>
         <contrib>Contributed by </contrib>
       </author>
      </authorgroup>
    </sect1info>

    <title>Resource Limits</title>

    <indexterm>
      <primary>Resource limits</primary>
    </indexterm>

    <para>For years, &os; has used a resource limits
      database controlled through a flat file,
      <filename>/etc/login.conf</filename>.  While it has
      been discussed previously and is still supported, it
      is not the most optimal method of controlling resources.
      The flat file requires users to be divided into various
      group labels known as classes, which require changes not
      only to this flat file but also the password database.
      Potentially a single, more constrained user would require
      an additional label added, the resource database needs to be
      built using <command>cap_mkdb</command>, edits made to
      the <filename>/etc/master.passwd</filename> file.  In
      addition, the password database must be rebuilt using
      <command>pwd_mkdb</command>.  This multi-step process could be
      very time consuming depending on how many users must be
      singled out.</para>

    <para>A new command in &os;, &man.rctl.8;, allows for a more
      fine grained method of controlling resources limits for
      users.  This command will support much more than users,
      it will also set resource constraints on processes, jails,
      and the original login class.  These advanced features
      provide administrators and users with methods to control
      resources through the command line and set rules on
      system initialization using a configuration
      file.</para>

    <para>To enable this feature, add these lines to
      <filename>GENERIC</filename>, or the custom kernel
      configuration file, and rebuild.:</para>

    <programlisting>options         RACCT
options         RCTL</programlisting>

    <para>The entire system will need rebuilt.  See <xref
        linkend="kernelconfig"/>, which will provide instructions for
      the process.  Once this is complete, the <command>rctl</command>
      may be used to set rules for the system.</para>

    <para>Rule syntax is simple, controlled through the use of
      a <emphasis>subject</emphasis>, a <emphasis>subject-id</emphasis>,
      <emphasis>resource</emphasis>, and <emphasis>action</emphasis>.
      Take the following example rule:</para>

    <programlisting>user:trhodes:<literal>maxproc</literal>:<literal>deny</literal>=10/user</programlisting>

    <para>This rule shows a basic premise of a rule, here the
      subject is <literal>user</literal> and the subject-id
      is <literal>trhodes</literal>.  The maxproc is, of course,
      max number of processes, which is considered the action.
      The action here is set to <literal>deny</literal>, which blocks
      any new processes from being created.  In the previous example,
      the user, <literal>trhodes</literal> will be constrained
      to <literal>10</literal> (ten) processes and no greater.
      Other actions are available and could be log to the console,
      pass a notification to &man.devd.8;, or
      send a sigterm to the process.</para>

    <para>Some care must be taken while adding rules.  The one above
      will unfortunately block my user from doing the most simple tasks
      after I have logged in and executed a <command>screen</command>
      session.  When a resource limit has been hit, an error will
      be printed, as in this example:</para>

    <screen>&prompt.user; <userinput>man test</userinput>
    /usr/bin/man: Cannot fork: Resource temporarily unavailable
eval: Cannot fork: Resource temporarily unavailable</screen>

    <para>For another example, &man.rctl.8; can be used to prevent
      a jail from exceeding a memory limit.  This rule could be
      written as:</para>

    <screen>&prompt.root; <userinput>rctl -a jail:httpd:memoryuse:deny=2G/jail</userinput></screen>

    <para>Rules may also persist across reboots if they have been
      added to <filename>/etc/rctl.conf</filename> file.  The
      format is a rule, without the preceding command.  For example,
      the previous rule could be added like the following:</para>

    <programlisting># Block jail from using more than 2G memory:
jail:httpd:memoryuse:deny=2G/jail</programlisting>

    <para>To remove a rule, just ask <command>rctl</command> to
      remove it from the list:</para>

    <screen>&prompt.root; <userinput>rctl -r user:trhodes:maxproc:deny=10/user</userinput></screen>

    <para>The manual page shows a method for removing all rules;
      however, if removing all rules for a single user is required,
      this command may be issued:</para>

    <screen>&prompt.root; <userinput>rctl -r user:trhodes</userinput></screen>

    <para>Many other resources exist which can be used to excert
      additional control over various <literal>subjects</literal>.
      See &man.rctl.8; to learn about them.</para>
  </sect1>
</chapter>