File: rfc2479.txt

package info (click to toggle)
doc-rfc 20181229-2
  • links: PTS, VCS
  • area: non-free
  • in suites: buster
  • size: 570,944 kB
  • sloc: xml: 285,646; sh: 107; python: 90; perl: 42; makefile: 14
file content (3923 lines) | stat: -rw-r--r-- 156,070 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923






Network Working Group                                           C. Adams
Request for Comments: 2479                          Entrust Technologies
Category: Informational                                    December 1998


       Independent Data Unit Protection Generic Security Service
              Application Program Interface (IDUP-GSS-API)

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

ABSTRACT

   The IDUP-GSS-API extends the GSS-API [RFC-2078] for applications
   requiring protection of a generic data unit (such as a file or
   message) in a way which is independent of the protection of any other
   data unit and independent of any concurrent contact with designated
   "receivers" of the data unit.  Thus, it is suitable for applications
   such as secure electronic mail where data needs to be protected
   without any on-line connection with the intended recipient(s) of that
   data.  The protection offered by IDUP includes services such as data
   origin authentication with data integrity, data confidentiality with
   data integrity, and support for non-repudiation services.  Subsequent
   to being protected, the data unit can be transferred to the
   recipient(s) - or to an archive - perhaps to be processed
   ("unprotected") only days or years later.

   Throughout the remainder of this document, the "unit" of data
   described in the above paragraph will be referred to as an IDU
   (Independent Data Unit).  The IDU can be of any size (the application
   may, if it wishes, split the IDU into pieces and have the protection
   computed a piece at a time, but the resulting protection token
   applies to the entire IDU).  However, the primary characteristic of
   an IDU is that it represents a stand-alone unit of data whose
   protection is entirely independent of any other unit of data.  If an
   application protects several IDUs and sends them all to a single
   receiver, the IDUs may be unprotected by that receiver in any order
   over any time span; no logical connection of any kind is implied by
   the protection process itself.





Adams                        Informational                      [Page 1]

RFC 2479                      IDUP-GSS-API                 December 1998


   As with RFC-2078, this IDUP-GSS-API definition provides security
   services to callers in a generic fashion, supportable with a range of
   underlying mechanisms and technologies and hence allowing source-
   level portability of applications to different environments. This
   specification defines IDUP-GSS-API services and primitives at a level
   independent of underlying mechanism and programming language
   environment, and is to be complemented by other, related
   specifications:

      - documents defining specific parameter bindings for particular
        language environments;
      - documents defining token formats, protocols, and procedures to
        be implemented in order to realize IDUP-GSS-API services atop
        particular security mechanisms.

TABLE OF CONTENTS

   1.  IDUP-GSS-API Characteristics and Concepts ..................    3
   1.1.  IDUP-GSS-API Constructs ..................................    5
   1.1.1.  Credentials ............................................    5
   1.1.2.  Tokens .................................................    5
   1.1.3.  Security Environment ...................................    6
   1.1.4.  Mechanism Types ........................................    6
   1.1.5.  Naming .................................................    6
   1.1.6.  Channel Bindings .......................................    6
   1.2.  IDUP-GSS-API Features and Issues .........................    6
   1.2.1.  Status Reporting .......................................    6
   1.2.2.  Per-IDU Security Service Availability ..................    9
   1.2.3.  Per-IDU Replay Detection and Sequencing ................    9
   1.2.4.  Quality of Protection ..................................    9
   1.2.5.  The Provision of Time ..................................   12
   2.  Interface Descriptions .....................................   13
   2.1.  Credential management calls ..............................   14
   2.1.1.  Relationship to GSS-API ................................   14
   2.2.  Environment-level calls ..................................   15
   2.2.1.  Relationship to GSS-API ................................   15
   2.2.2.  IDUP_Establish_Env call ................................   15
   2.2.3.  IDUP_Abolish_Env call ..................................   19
   2.2.4.  IDUP_Inquire_Env call ..................................   19
   2.3.  Per-IDU protection/unprotection calls ....................   20
   2.3.1.  Relationship to GSS-API ................................   20
   2.3.2.  The "SE" Calls .........................................   21
   2.3.3.  The "EV" Calls .........................................   27
   2.3.4.  The "GP" Calls .........................................   36
   2.4.  Special-Purpose calls ....................................   47
   2.4.1.  Relationship to GSS-API ................................   47
   2.4.2.  IDUP_Form_Complete_PIDU ................................   48
   2.5.  Support calls ............................................   49



Adams                        Informational                      [Page 2]

RFC 2479                      IDUP-GSS-API                 December 1998


   2.5.1.  Relationship to GSS-API ................................   49
   2.5.2.  IDUP_Acquire_Cred_With_Auth ............................   49
   2.5.3.  IDUP_Get_Token_Details .................................   50
   2.5.4.  IDUP_Get_Policy_Info ...................................   53
   2.5.5.  IDUP_Cancel_Multibuffer_Op .............................   55
   3.  Related Activities .........................................   55
   4.  Acknowledgments ............................................   56
   5.  Security Considerations ....................................   56
   6.  References       ...........................................   56
   7.  Author's Address ...........................................   56
   Appendix  A Mechanism-Independent Token Format .................   57
   Appendix  B Examples of IDUP Use ...............................   58
   Full Copyright Statement .......................................   70

1. IDUP-GSS-API Characteristics and Concepts

   The paradigm within which IDUP-GSS-API operates is as follows.  An
   IDUP-GSS-API caller is any application that works with IDUs, calling
   on IDUP-GSS-API in order to protect its IDUs with services such as
   data origin authentication with integrity (DOA), confidentiality with
   integrity (CONF), and/or support for non-repudiation (e.g., evidence
   generation, where "evidence" is information that either by itself, or
   when used in conjunction with other information, is used to establish
   proof about an event or action (note:  the evidence itself does not
   necessarily prove truth or existence of something, but contributes to
   establish proof) -- see [ISO/IEC] for fuller discussion regarding
   evidence and its role in various types of non-repudiation).  An
   IDUP-GSS-API caller passes an IDU to, and accepts a token from, its
   local IDUP-GSS-API implementation, transferring the resulting
   protected IDU (P-IDU) to a peer or to any storage medium.  When a P-
   IDU is to be "unprotected", it is passed to an IDUP-GSS-API
   implementation for processing.  The security services available
   through IDUP-GSS-API in this fashion are implementable over a range
   of underlying mechanisms based on secret-key and/or public-key
   cryptographic technologies.

   During the protection operation, the input IDU buffers may be
   modified (for example, the data may be encrypted or encoded in some
   way) or may remain unchanged.  In any case, the result is termed a
   "M-IDU" (Modified IDU) in order to distinguish it from the original
   IDU.  Depending on the desire of the calling application and the
   capabilities of the underlying IDUP mechanism, the output produced by
   the protection processing may or may not encapsulate the M-IDU. Thus,
   the P-IDU may be the contents of a single output parameter (if
   encapsulation is done) or may be the logical concatenation of an
   unencapsulated token parameter and a M-IDU parameter (if
   encapsulation is not done).  In the latter case, the protecting
   application may choose whatever method it wishes to concatenate or



Adams                        Informational                      [Page 3]

RFC 2479                      IDUP-GSS-API                 December 1998


   combine the unencapsulated token and the M-IDU into a P-IDU, provided
   the unprotecting application knows how to de-couple the P-IDU back
   into its component parts prior to calling the IDUP unprotection set
   of functions.

   It is expected that any output buffer returned by IDUP (i.e., P-IDU
   or portion thereof) is ready for immediate transmission to the
   intended receiver(s) by the calling application, if this is desired.
   In other words, an application wishing to transmit data buffers as
   they appear from IDUP should not be unduly restricted from doing so
   by the underlying mechanism.

   The IDUP-GSS-API separates the operation of initializing a security
   environment (the IDUP_Establish_Env() call) from the operations of
   providing per-IDU protection, for IDUs subsequently protected in
   conjunction with that environment. Per-IDU protection and
   unprotection calls provide DOA, CONF, evidence, and other services,
   as requested by the calling application and as supported by the
   underlying mechanism.

   The following paragraphs provide an example illustrating the
   dataflows involved in the use of the IDUP-GSS-API by the sender and
   receiver of a P-IDU in a mechanism-independent fashion.  The example
   assumes that credential acquisition has already been completed by
   both sides.  Furthermore, the example does not cover all possible
   options available in the protection/unprotection calls.

      The sender first calls IDUP_Establish_Env() to establish a
      security environment.  Then, for the IDU to be protected the
      sender calls the appropriate protection calls (SE, EV, or GP) to
      perform the IDU protection.  The resulting P-IDU, which may
      (depending on whether or not encapsulation was chosen/available)
      be either the token itself or the logical concatenation of the
      token and the M-IDU, is now ready to be sent to the target.  The
      sender then calls IDUP_Abolish_Env() to flush all environment-
      specific information.

      The receiver first calls IDUP_Establish_Env() to establish a
      security environment in order to unprotect the P-IDU.  Then, for
      the received P-IDU the receiver calls the appropriate unprotection
      calls (SE, EV, or GP (known a priori, or possibly determined
      through the use of the IDUP_Get_token_details call)) to perform
      the P-IDU unprotection.  The receiver then calls
      IDUP_Abolish_Env() to flush all environment-specific information.

   It is important to note that absolutely no synchronization is implied
   or expected between the data buffer size used by the sender as input
   to the protection calls, the data buffer size used by the receiver as



Adams                        Informational                      [Page 4]

RFC 2479                      IDUP-GSS-API                 December 1998


   input to the unprotection calls, and the block sizes required by the
   underlying protection algorithms (integrity and confidentiality). All
   these sizes are meant to be independent; furthermore, the data buffer
   sizes used for the protection and unprotection calls are purely a
   function of the local environment where the calls are made.

   The IDUP-GSS-API design assumes and addresses several basic goals,
   including the following.

      Mechanism independence:  The IDUP-GSS-API defines an interface to
      cryptographically implemented security services at a generic level
      which is independent of particular underlying mechanisms. For
      example, IDUP-GSS-API-provided services can be implemented by
      secret-key technologies or public-key approaches.

      Protocol environment independence: The IDUP-GSS-API is independent
      of the communications protocol suites which may be used to
      transfer P-IDUs, permitting use in a broad range of protocol
      environments.

      Protocol association independence: The IDUP-GSS-API's security
      environment construct has nothing whatever to do with
      communications protocol association constructs, so that IDUP-GSS-
      API services can be invoked by applications, wholly independent of
      protocol associations.

      Suitability for a range of implementation placements: IDUP-GSS-API
      clients are not constrained to reside within any Trusted Computing
      Base (TCB) perimeter defined on a system where the IDUP-GSS-API is
      implemented; security services are specified in a manner suitable
      for both intra-TCB and extra-TCB callers.

1.1. IDUP-GSS-API Constructs

   This section describes the basic elements comprising the IDUP-GSS-
   API.

1.1.1.  Credentials

   Credentials in IDUP-GSS-API are to be understood and used as
   described in GSS-API [RFC-2078].

1.1.2. Tokens

   Tokens in IDUP-GSS-API are to be understood and used as described in
   GSS-API [RFC-2078] with the exception that there are no context-level
   tokens generated by IDUP-GSS-API.  The IDUP-GSS-API token may
   (depending on the underlying mechanism) encapsulate the M-IDU or may



Adams                        Informational                      [Page 5]

RFC 2479                      IDUP-GSS-API                 December 1998


   be logically concatenated with the M-IDU prior to transfer to a
   target; furthermore, for some evidence services the token may be sent
   independently of any other data transfer.

1.1.3.  Security Environment

   The "security environment" in IDUP-GSS-API is entirely different from
   the concept of security contexts used in GSS-API [RFC-2078].  Here, a
   security environment exists within a calling application (that is, it
   is purely local to the caller) for the purpose of protecting or
   unprotecting one or more IDUs using a particular caller credential or
   set of credentials.  In GSS-API, on the other hand, a security
   context exists between peers (the initiator and the target) for the
   purpose of protecting, in real time, the data that is exchanged
   between them.  Although they are different concepts, the env_handle
   in IDUP-GSS-API is similar to the context_handle in GSS-API in that
   it is a convenient way of tying together the entire process of
   protecting or unprotecting one or more IDUs using a particular
   underlying mechanism.  As with the GSS-API security contexts, a
   caller can initiate and maintain multiple environments using the same
   or different credentials.

1.1.4.  Mechanism Types

   Mechanism types in IDUP-GSS-API are to be understood and used as
   described in GSS-API [RFC-2078].

1.1.5.  Naming

   Naming in IDUP-GSS-API is to be understood and used as described in
   GSS-API [RFC-2078].

1.1.6.  Channel Bindings

   The concept of channel bindings discussed in GSS-API [RFC-2078] is
   not relevant to the IDUP-GSS-API.

1.2.  IDUP-GSS-API Features and Issues

   This section describes aspects of IDUP-GSS-API operations and of the
   security services which the IDUP-GSS-API provides.  It also provides
   commentary on design issues.

1.2.1.  Status Reporting

   Status reporting in IDUP-GSS-API is to be understood and used as
   described in GSS-API [RFC-2078], with the addition of a number of
   IDUP-specific status codes.  Descriptions of the major_status codes



Adams                        Informational                      [Page 6]

RFC 2479                      IDUP-GSS-API                 December 1998


   used in IDUP are provided in Table 1.  Codes that are informatory
   (i.e., that do not cause the requested operation to fail) are
   indicated with the symbol "(I)".

   As with GSS-API, minor_status codes, which provide more detailed
   status information than major_status codes, and which may include
   status codes specific to the underlying security mechanism, are not
   specified in this document.

    Table 1: IDUP-GSS-API Major Status Codes

      GSS_S_BAD_MECH indicates that a mech_type unsupported by the
      IDUP_GSS-API implementation was requested, causing the environment
      establishment operation to fail.

      GSS_S_BAD_QOP indicates that the provided qop_alg value is not
      recognized or supported for the environment.

      GSS_S_BAD_MIC indicates that the received P-IDU contains an
      incorrect integrity field (e.g., signature or MAC) for the data.

      GSS_S_COMPLETE indicates that the requested operation was
      successful.

      GSS_S_CREDENTIALS_EXPIRED indicates that the credentials
      associated with this operation have expired, so that the requested
      operation cannot be performed.

      GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
      performed on the credential structure referenced by
      claimant_cred_handle failed, preventing further processing from
      being performed using that credential structure.

      GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
      on the received P-IDU failed, preventing further processing from
      being performed.

      GSS_S_FAILURE indicates that the requested operation could not be
      accomplished for reasons unspecified at the IDUP-GSS-API level,
      and that no interface-defined recovery action is available.

      GSS_S_NO_CRED indicates that no environment was established,
      either because the input cred_handle was invalid or because the
      caller lacks authorization to access the referenced credentials.

      IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU data
      origin auth. / integ. has either expired or been revoked.




Adams                        Informational                      [Page 7]

RFC 2479                      IDUP-GSS-API                 December 1998


      IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
      cannot be completed because the encrypted IDU was
      invalid/defective (e.g., the final block was short or had
      incorrect padding).

      IDUP_S_BAD_KE_KEY indicates that the key used to establish a key
      for confidentiality purposes between originator and target has
      either expired or been revoked.

      IDUP_S_BAD_TARG_INFO indicates that the full set of supplied
      information regarding the target(s) is invalid or is insufficient
      for the protection of an IDU, so P-IDU cannot be created.

      IDUP_S_DEFECTIVE_VERIF indicates that consistency checks performed
      on Service_Verification_Info failed, preventing further processing
      from being performed with that parameter.

      IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying
      mechanism does not support encapsulation of the M-IDU into the
      token.

      IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied
      do not contain the information necessary for P-IDU unprotection.

      IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU
      is not yet complete (i.e., a determination cannot yet be made on
      the validity of the P-IDU).  The application should call
      IDUP_Form_Complete_PIDU and then should call this function again
      with the complete P-IDU.

      IDUP_S_INCONSISTENT_PARAMS indicates that the supplied parameters
      are inconsistent (e.g., only one or the other of two parameters
      may be supplied, but both have been input).

      IDUP_S_MORE_OUTBUFFER_NEEDED (I) indicates that the output buffer
      supplied is too small to hold the generated data.  The application
      should continue calling this routine (until GSS_S_COMPLETE is
      returned) in order to get all remaining output data.

      IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU
      has been input yet for the completion of StartUnprotect.  The
      application should call this routine again with another buffer of
      P-IDU in partial(initial)_pidu_buffer.

      IDUP_S_NO_ENV indicates that no valid environment was recognized
      for the env_handle provided.





Adams                        Informational                      [Page 8]

RFC 2479                      IDUP-GSS-API                 December 1998


      IDUP_S_NO_MATCH indicates that Service_Verification_Info (or
      evidence_check) and the P-IDU to be verified do not match.

      IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service
      requested (TTIME or UTIME) is not available in the environment.

      IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism
      does not support the service requested.

      IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the
      Service_Verification_Info parameter bundle must be input in order
      for service verification to proceed.  The output parameter
      service_verification_info_id contains an identifier which may be
      used by the calling application to locate the necessary
      information.

      IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
      is not recognized or supported in the underlying mechanism.

1.2.2. Per-IDU Security Service Availability

   Per-IDU security service availability in IDUP-GSS-API is to be
   understood and used as described in GSS-API [RFC-2078], with the
   exception that combinations of services requested by the calling
   application and supported by the underlying mechanism may be applied
   simultaneously to any IDU (true for both the SE and the EV calls, but
   true in the fullest sense for the GP calls).

   GSS-API callers desiring per-message security services should check
   the relevant service OBJECT IDs at environment establishment time to
   ensure that what is available in the established environment is
   suitable for their security needs.

1.2.3. Per-IDU Replay Detection and Sequencing

   The concept of per-IDU replay detection and sequencing discussed in
   GSS-API [RFC-2078] is not relevant to the IDUP-GSS-API.

1.2.4.  Quality of Protection

   The concept of QOP control in IDUP-GSS-API is to be understood
   essentially as described in GSS-API [RFC-2078].  However, the actual
   description and use of the QOP parameter is given as follows.

   The qop_algs parameter for IDUP is defined to be a 32-bit unsigned
   integer with the following bit-field assignments:





Adams                        Informational                      [Page 9]

RFC 2479                      IDUP-GSS-API                 December 1998


            31 (MSB)                               (LSB) 0
            ----------------------------------------------
            |        U(19)       | TS(5) | IA(4) | MA(4) |
            ----------------------------------------------

   where

      U is a 19-bit Unspecified field (available for future
      use/expansion) -- must be set to zero;

      TS is a 5-bit Type Specifier (a semantic qualifier whose value
      specifies the type of algorithm which may be used to protect the
      corresponding IDU -- see below for details);

      IA is a 4-bit field enumerating Implementation-specific
      Algorithms; and

      MA is a 4-bit field enumerating Mechanism-defined Algorithms.

   The interpretation of the qop_algs parameter is as follows.  The MA
   field is examined first.  If it is non-zero then the algorithm used
   to protect the IDU is the mechanism-specified algorithm corresponding
   to that integer value.

   If MA is zero then IA is examined.  If this field value is non-zero
   then the algorithm used to protect the IDU is the implementation-
   specified algorithm corresponding to that integer value.  Note that
   use of this field may hinder portability since a particular value may
   specify one algorithm in one implementation of the mechanism and may
   not be supported or may specify a completely different algorithm in
   another implementation of the mechanism.

   Finally, if both MA and IA are zero then TS is examined.  A value of
   zero for TS specifies the default algorithm for the established
   mechanism.  A non-zero value for TS corresponds to a particular
   algorithm qualifier and selects any algorithm from the mechanism
   specification which satisfies that qualifier (which actual algorithm
   is selected is an implementation choice; the calling application need
   not be aware of the choice made).

   The following TS values (i.e., algorithm qualifiers) are specified;
   other values may be added in the future.









Adams                        Informational                     [Page 10]

RFC 2479                      IDUP-GSS-API                 December 1998


   When qop_algs is used to select a confidentiality algorithm:

      00000  (0) = default confidentiality algorithm
      00001  (1) = IDUP_SYM_ALG_STRENGTH_STRONG
      00010  (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM
      00011  (3) = IDUP_SYM_ALG_STRENGTH_WEAK
      11111 (31) = IDUP_NO_CONFIDENTIALITY

   When qop_algs is used to select a DOA/integrity algorithm:

      00000  (0) = default integrity algorithm
      00001  (1) = IDUP_INT_ALG_DIG_SIGNATURE
                   (integrity provided through a digital signature)
      00010  (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE
                   (integrity without a dig. sig. (e.g., with a MAC))
      11111 (31) = IDUP_NO_INTEGRITY

   Clearly, qualifiers such as strong, medium, and weak are debatable
   and likely to change with time, but for the purposes of this version
   of the specification we define these terms as follows.  A
   confidentiality algorithm is "weak" if the effective key length of
   the cipher is 40 bits or less; it is "medium-strength" if the
   effective key length is strictly between 40 and 80 bits; and it is
   "strong" if the effective key length is 80 bits or greater.
   ("Effective key length" describes the computational effort required
   to break a cipher using the best-known cryptanalytic attack against
   that cipher.)

   A five-bit TS field allows up to 30 qualifiers for each of
   confidentiality and integrity (since "0" is reserved for "default"
   and "31" is reserved for "none", as shown above).  This document
   specifies three for confidentiality and two for integrity, leaving a
   lot of room for future specification.  Suggestions of qualifiers such
   as "fast", "medium-speed", and "slow" have been made, but such terms
   are difficult to quantify (and in any case are platform- and
   processor-dependent), and so have been left out of this initial
   specification.  The intention is that the TS terms be quantitative,
   environment-independent qualifiers of algorithms, as much as this is
   possible.

   Use of the qop_algs parameter as defined above is ultimately meant to
   be as follows.

    - TS values are specified at the IDUP-GSS-API level and are
      therefore portable across mechanisms.  Applications which know
      nothing about algorithms are still able to choose "quality" of
      protection for their message tokens.




Adams                        Informational                     [Page 11]

RFC 2479                      IDUP-GSS-API                 December 1998


    - MA values are specified at the mechanism level and are therefore
      portable across implementations of a mechanism.

    - IA values are specified at the implementation level (in user
      documentation, for example) and are therefore typically non-
      portable.  An application which is aware of its own mechanism
      implementation and the mechanism implementation of its intended
      P-IDU recipient, however, is free to use these values since they
      will be perfectly valid and meaningful for protecting IDUs between
      those entities.

   The receiver of a P-IDU must pass back to its calling application (in
   IDUP_Start_Unprotect()) a qop_algs parameter with all relevant fields
   set.  For example, if triple-DES has been specified by a mechanism as
   algorithm 8, then a receiver of a triple-DES-protected P-IDU must
   pass to its application (TS=1, IA=0, MA=8).  In this way, the
   application is free to read whatever part of the qop_algs parameter
   it understands (TS or IA/MA).

1.2.5.  The Provision of Time

   IDUP mechanisms should make provision in their protocols for the
   carrying of time information from originator to target(s).  That is,
   a target (a legitimate recipient) should get some indication during
   unprotection regarding the time at which the protection operation
   took place.  This is particularly important if the mechanism offers
   non-repudiation services because in some cases evidence verification
   may only be achievable if the time at which the evidence was
   generated is known.

   Depending upon the platform and resources available to the
   implementation, an IDUP environment may have access to a source of
   trusted (secure) time, untrusted (local) time, both kinds of time, or
   no time.  OBJECT IDs indicating such availability are returned by the
   IDUP_Establish_Env() call.  When starting a protection operation, an
   application may specify which time services it wishes to have applied
   to the IDU.  Similarly, for unprotection, an application may specify
   which kind of time (if any) to consult when the validity of the P-IDU
   is to be established.  Specifying both kinds of time is interpreted
   to mean that the calling application does not care which kind of time
   is used.

   The IDUP calls which use a time parameter specify the type of that
   parameter to be INTEGER.  This INTEGER is defined in all cases to be
   the number of seconds which have elapsed since midnight, January 1,
   1970, coordinated universal time.





Adams                        Informational                     [Page 12]

RFC 2479                      IDUP-GSS-API                 December 1998


2.  Interface Descriptions

   This section describes the IDUP-GSS-API's operational interface,
   dividing the set of calls offered into five groups.  Credential
   management calls are related to the acquisition and release of
   credentials by API callers. Environment-level calls are related to
   the management of the security environment by an API caller.  Per-IDU
   calls are related to the protection or unprotection of individual
   IDUs in established security environments.  Special-purpose calls
   deal with unusual or auxiliary evidence generation/verification
   requirements.  Support calls provide extra functions useful to IDUP-
   GSS-API callers.  Table 2 groups and summarizes the calls in tabular
   fashion.

    Table 2:  IDUP-GSS-API Calls

      CREDENTIAL MANAGEMENT
      (see the calls given in Section 2.1 of GSS-API [RFC-2078])

      ENVIRONMENT-LEVEL CALLS
      IDUP_Establish_Env
      IDUP_Abolish_Env
      IDUP_Inquire_Env

      PER-IDU CALLS
      SE (SIGN,ENCRYPT) CALLS
         IDUP_SE_SingleBuffer_Protect
         IDUP_SE_SingleBuffer_Unprotect
         IDUP_SE_MultiBuffer_StartProtect
         IDUP_SE_MultiBuffer_EndProtect
         IDUP_SE_MultiBuffer_StartUnprotect
         IDUP_SE_MultiBuffer_EndUnprotect
         IDUP_SE_Process_Buffer
      EV (EVIDENCE) CALLS
         IDUP_EV_SingleBuffer_Generate
         IDUP_EV_SingleBuffer_Verify
         IDUP_EV_MultiBuffer_StartGenerate
         IDUP_EV_MultiBuffer_EndGenerate
         IDUP_EV_MultiBuffer_StartVerify
         IDUP_EV_MultiBuffer_EndVerify
         IDUP_EV_Process_Buffer
      GP (GENERAL PROTECTION) CALLS
         IDUP_Start_Protect
         IDUP_Protect
         IDUP_End_Protect
         IDUP_Start_Unprotect
         IDUP_Unprotect
         IDUP_End_Unprotect



Adams                        Informational                     [Page 13]

RFC 2479                      IDUP-GSS-API                 December 1998


      SPECIAL-PURPOSE CALLS  (might not be supported by all mechanisms)
      IDUP_Form_Complete_PIDU

      SUPPORT CALLS
      IDUP_Acquire_cred_with_auth
      IDUP_Get_Token_Details
      IDUP_Get_Policy_Info
      IDUP_Cancel_Multibuffer_Op
      (see also the calls given in Section 2.4 of GSS-API [RFC-2078])

   In terms of conformance to this specification, IDUP-GSS-API
   implementations must support the credential management calls, the
   environment-level calls, some subset of the per-IDU calls, and the
   support calls (except where explicitly stated otherwise in Section
   2.5).  The subset of per-IDU calls supported will depend upon the
   underlying mechanisms supported and will typically be the SE calls,
   or the EV calls, or both.  As stated in Section 2.3.2.1,
   implementations are encouraged to support the more powerful GP calls
   to anticipate the future needs of applications developers, but this
   is not required for conformance.

2.1.  Credential management calls

2.1.1.  Relationship to GSS-API

   Credential management in IDUP-GSS-API is to be understood and used as
   described in GSS-API [RFC-2078].  The calls given in Section 2.1 of
   GSS-API (including all associated parameters) are unchanged, although
   the interpretation of the cred_usage parameter in the GSS-API calls
   for IDUP purposes is as follows.

      ENCRYPT_ONLY    8
      DECRYPT_ONLY   16
      SIGN_ONLY      32
      VERIFY_ONLY    64

   The values above may be logically OR'ed together in any desired
   combination to restrict credential usage (where OR'ing all values
   results in NO_RESTRICTION).  Future possible values for this
   parameter are for further study.

   The call IDUP_Acquire_cred_with_auth has been added as a support call
   in this specification to permit authenticated credential acquirement;
   see Section 2.5.2 for details.







Adams                        Informational                     [Page 14]

RFC 2479                      IDUP-GSS-API                 December 1998


2.2.  Environment-level calls

   This group of calls is devoted to the establishment and management of
   an environment for the purpose of IDU protection and unprotection.
   Before protecting or unprotecting any IDU, an application must call
   IDUP_Establish_Env() to initialize environment information and select
   the underlying IDUP-GSS mechanism to be used.  A series of protection
   or unprotection calls is made to process each IDU, the protection
   calls resulting in a P-IDU for each.  Finally, IDUP_Abolish_Env() is
   called to flush all environment information.

   Semantically, acquiring credentials and establishing an environment
   is (in many cases) analogous to logging in to a system -- it
   authenticates a local user to the system and gives that user access
   to a set of operations which can be performed.

2.2.1.  Relationship to GSS-API

   The set of calls described in this section is used in place of the
   calls described in Section 2.2 of GSS-API [RFC-2078], since those
   calls are specific to a session-oriented environment.

2.2.2.  IDUP_Establish_Env call

   Inputs: o  claimant_cred_handle CREDENTIAL HANDLE,
      -- NULL parameter specifies "use default"

   o  req_mech_type OBJECT IDENTIFIER,
      -- NULL parameter specifies "use default"
   o  req_environmentPolicies EnvironmentPolicies,
      -- NULL parameter specifies "use default"
   o  req_services SET OF OBJECT IDENTIFIER,
      -- GSS_C_NO_OID_SET requests full set of services available
      -- for req_mech_type

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  env_handle ENVIRONMENT HANDLE,
   o  actual_mech_type OBJECT IDENTIFIER,
      -- actual mechanism always indicated, never NULL
   o  actual_environmentPolicies EnvironmentPolicies,
      -- actual values always indicated, never NULL
   o  ret_services SET OF OBJECT IDENTIFIER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- environment-level information was successfully initialized,



Adams                        Informational                     [Page 15]

RFC 2479                      IDUP-GSS-API                 December 1998


      -- and IDU / P-IDU processing can begin.
   o  GSS_S_DEFECTIVE_CREDENTIAL
   o  GSS_S_NO_CRED
   o  GSS_S_CREDENTIALS_EXPIRED
      -- the credentials provided through claimant_cred_handle are
      -- no longer valid, so environment cannot be established.
   o  GSS_S_BAD_MECH
   o  GSS_S_FAILURE

   The following structures are defined to facilitate environment policy
   input and output:

   EnvironmentPolicies ::= SEQUENCE {
      confPolicy     [0] PolicyAndTime OPTIONAL,
      -- NULL parameter (on input) specifies "use default"
      integPolicy    [1] PolicyAndTime OPTIONAL,
      -- NULL parameter (on input) specifies "use default"
      evidencePolicy [2] PolicyAndTime OPTIONAL }
      -- NULL parameter (on input) specifies "use default"

   PolicyAndTime ::= SEQUENCE {
      policy             OBJECT IDENTIFIER,
      -- this environment-level policy identifier is separate from
      -- the policy provisions connected with credentials, if they exist
      time               INTEGER
      -- on input:  the policy rules available at the specified time
      -- on output: the time at which the policy rules came into effect
      -- (defined to be the number of seconds elapsed since midnight,
      -- January 1, 1970, coordinated universal time)
      endTime            INTEGER OPTIONAL }
      -- on input:  unused
      -- on output: the expiration time of the given policy rules

   This routine is used by an application which protects or unprotects
   IDUs.  Using information in the credentials structure referenced by
   claimant_cred_handle, IDUP_Establish_Env() initializes the data
   structures required to protect or unprotect IDUs.  The
   claimant_cred_handle, if non-NULL, must correspond to a valid
   credentials structure.

   This routine returns an env_handle for all future references to this
   environment; when protection, unprotection, or IDUP_Abolish_Env()
   calls are made, this handle value will be used as the input
   env_handle argument.  It is the caller's responsibility to establish
   a communications path to the intended recipients of the P-IDU, and to
   transmit the P-IDU to those recipients over that path.  This may
   occur subsequent to the IDUP_Abolish_Env() call.




Adams                        Informational                     [Page 16]

RFC 2479                      IDUP-GSS-API                 December 1998


   The req_services parameter may be used by the calling application to
   request that data origin authentication with integrity,
   confidentiality with integrity, evidence generation, and/or evidence
   verification services be available in the established environment.
   Requests can also be made for "trusted" or "untrusted" time services.
   Requesting evidence generation or verification indicates that the
   calling application may wish to generate or verify evidence
   information for non-repudiation purposes (note:  an IDU protector may
   request that a flag be inserted into a P-IDU asking a recipient to
   provide an evidence of the type "non-repudiation of delivery";
   however, the IDUP-GSS-API cannot by itself guarantee that the
   evidence will be sent because there is no way to force a target to
   send an evidence_token back to the IDU protector).

   Not all features will be available in all underlying mech_types; the
   returned value of ret_services indicates, as a function of mech_type
   processing capabilities and the initiator-provided input OBJECT IDs,
   the set of features which will be available in the environment. The
   value of this parameter is undefined unless the routine's
   major_status indicates COMPLETE.  Failure to provide the precise set
   of services desired by the caller does not cause environment
   establishment to fail; it is the caller's choice to abolish the
   environment if the service set provided is unsuitable for the
   caller's use.  The returned mech_type value indicates the specific
   mechanism employed in the environment and will never indicate the
   value for "default".

   The following OBJECT IDs are defined for protection and unprotection
   services (the OBJECT ID iso.org.dod.internet.security.services,
   1.3.6.1.5.7, has been assigned by IANA, and some of the security
   services under that node are assigned as shown below).  It is
   recognized that this list may grow over time.

      PER_CONF = { 1.3.6.1.5.7.1.1 }
         -- perform data confidentiality (i.e., encrypt data)
      PER_CONF_FULL = { 1.3.6.1.5.7.1.3 }
         -- perform full confidentiality (i.e., encrypt data and sig)
         -- (may be used only when PER_DOA is requested simultaneously)
      PER_DOA  = { 1.3.6.1.5.7.3.1 }
         -- perform data origin authentication with data integrity
      PER_DOA_CIPH  = { 1.3.6.1.5.7.3.3 }
         -- perform DOA with DI over ciphertext (rather than plaintext)
         -- (may be used only when PER_CONF is requested simultaneously)
      PER_POO  = { 1.3.6.1.5.7.4.1 }
         -- perform (i.e., create) non-repudiable "proof of origin"
      PER_POD  = { 1.3.6.1.5.7.4.3 }
         -- perform (i.e., create) non-repudiable "proof of delivery"




Adams                        Informational                     [Page 17]

RFC 2479                      IDUP-GSS-API                 December 1998


      REC_CONF = { 1.3.6.1.5.7.1.2 }
         -- receive data confidentiality (i.e., decrypt data)
      REC_CONF_FULL = { 1.3.6.1.5.7.1.4 }
         -- receive full confidentiality (i.e., decrypt data and sig)
         -- (may be used only when REC_DOA is received simultaneously)
      REC_DOA  = { 1.3.6.1.5.7.3.2 }
         -- receive / verify DOA with data integrity
      REC_DOA_CIPH  = { 1.3.6.1.5.7.3.4 }
         -- verify DOA with DI over ciphertext (rather than plaintext)
         -- (may be used only when PER_CONF is received simultaneously)
      REC_POO  = { 1.3.6.1.5.7.4.2 }
         -- receive / verify "proof of origin"
      REC_POD  = { 1.3.6.1.5.7.4.4 }
         -- receive / verify "proof of delivery"
      TTIME    = { 1.3.6.1.5.7.7.1 }
         -- trusted time availability
      UTIME    = { 1.3.6.1.5.7.7.2 }
         -- untrusted time availability

   The PER_CONF return value (in the ret_services paramater) indicates
   whether the environment supports confidentiality services, and so
   informs the caller whether or not a request for encryption can be
   honored.  In similar fashion, the PER_DOA return value indicates
   whether DOA services are available in the established environment,
   and the PER_POO and PER_POD return values indicate whether evidence
   generation services are available.  The TTIME and UTIME values
   indicate whether trusted time and untrusted time are available for
   protection / unprotection services.

   Note that, unlike a GSS "context", an IDUP environment does not have
   an explicit lifetime associated with it.  Instead, it relies on the
   lifetime of the calling entity's credential (set by the caller in the
   GSS_Acquire_cred() call).  When the credential expires (or is
   explicitly deleted in any other way), no new operations are allowed
   in the IDUP environment (although operations which have begun, such
   as the Protection set of calls, can be taken to completion).















Adams                        Informational                     [Page 18]

RFC 2479                      IDUP-GSS-API                 December 1998


2.2.3. IDUP_Abolish_Env call

   Input:
   o  env_handle ENVIRONMENT HANDLE

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- the relevant environment-specific information was flushed.
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   This call is made to flush environment-specific information. (Once an
   environment is established, cached credential and environment-related
   info. is expected to be retained until an IDUP_Abolish_Env() call is
   made or until the cred. lifetime expires.)  Attempts to perform IDU
   processing on a deleted environment will result in error returns.

2.2.4. IDUP_Inquire_Env call

   Input:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  mech_type OBJECT IDENTIFIER,
      -- the mechanism supporting this environment
   o  environmentPolicies EnvironmentPolicies,
      -- the environment policies in effect
   o  ret_services SET OF OBJECT IDENTIFIER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- referenced environment is valid and mech_type and other return
      -- values describe the characteristics of the environment.
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   This routine provides environment-related information to the caller.







Adams                        Informational                     [Page 19]

RFC 2479                      IDUP-GSS-API                 December 1998


2.3.  Per-IDU calls

   This group of calls is used to perform IDU protection and
   unprotection processing on an established IDUP environment. Some of
   these calls may block pending network interactions (depending on the
   underlying mechanism in use).  These calls may be invoked by an IDU's
   protector or by the P-IDU's recipient.  Members of this group form
   pairs; the output from the protection types of calls is typically
   meant to be input to the unprotection types of calls.

   The per-IDU calls can support caller-requested data origin
   authentication with data integrity, confidentiality with data
   integrity, evidence, and evidence-requested-from-target services.

   The protection operations output a token which encapsulates all the
   information required to unprotect the IDU.  The token is passed to
   the target (possibly separate from the M-IDU) and is processed by the
   unprotection calls at that system.  Unprotection performs
   decipherment, DOA verification, evidence verification, or
   notification of evidence requested, as required.

   Each of the two main operations (protection and unprotection) may be
   separated into three parts:  "Start_Operation"; "Operation" (which
   may be called once for each buffer of input data); and
   "End_Operation".  This separation is available for the case where the
   IDU or P-IDU is to be processed one buffer at a time.
   "Start_Operation" allows the caller to specify or retrieve the
   appropriate "Quality" used during the processing.  "Operation" is
   concerned with the processing itself, receiving a buffer of input
   data and potentially returning a buffer of output data.
   "End_Operation" performs any required clean-up and creates the
   appropriate token or states whether the input token was verified.

   If the IDU or P-IDU is wholly contained in a single buffer, the
   three-part protection/unprotection processing need not be done.
   Instead, protection or unprotection can be accomplished using only a
   single call, simplifying application code.

2.3.1.  Relationship to GSS-API

   The set of calls described in this section is used in place of the
   calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() which
   are specified in [RFC-2078], since those calls are specific to a
   session-oriented environment.







Adams                        Informational                     [Page 20]

RFC 2479                      IDUP-GSS-API                 December 1998


2.3.2.  The "SE" Calls

2.3.2.1. IDUP_SE Purpose

   The "SE" group of calls provides a very simple, high-level interface
   to underlying IDUP mechanisms when application developers need access
   only to signature and encryption protection/unprotection services.
   It includes both the single-buffer and multiple-buffer IDU cases and
   can be used for signing only, encrypting only, signing and encrypting
   (in either order, and with or without visibility of the resulting
   signature), and "clear signing" (where the data is not modified in
   any way and the signature itself is returned as a separate item).
   [Note that encapsulation occurs in all cases except for clear
   signing, so that these calls provide functionality similar to the
   GSS_Wrap call.]

   Note that the term "signing" is used in its most generic sense, not
   necessarily implying the use of public-key techniques.  This concept
   has also been called "sealing" in other contexts (e.g., in other
   standardization efforts).

   The SE calls may be viewed by mechanism implementors as an "API" to
   the more powerful GP calls defined later and so may be implemented as
   simple mapping functions to those calls (when those optional calls
   are supported).  Application callers, on the other hand, may find
   that the SE calls are all they currently need for many environments.
   At some time in the future when they have need of non-repudiation or
   "directed receipts" types of services, they may consider using the EV
   calls (or the GP calls -- when these are supported -- if complex and
   sophisticated combinations of services are required).  To assist in
   this migration path, mechanism implementors are encouraged to support
   the full set of IDUP calls (i.e., the SE, EV, and GP calls) even
   though some calling applications will only use the SE calls in the
   short term.

2.3.2.2. IDUP_SE Parameter Bundles

   The concept of "parameter bundles" is used in the calls presented in
   the following subsections in order to simplify their presentation and
   clarify their intended purpose and use.  See Section 2.3.4.1 for a
   more complete description of parameter bundles.

   The following parameter bundles are used in the "SE" protection and
   unprotection sets of calls.







Adams                        Informational                     [Page 21]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  Protect_Options PARAMETER BUNDLE
      o  protect_operation  INTEGER {
            sign_only              (0),
            encrypt_only           (1),
            sign_and_encrypt       (2),
            -- let mechanism choose order (and readability of signature)
            sign_then_encrypt_data (3),
            -- sign, then encrypt plaintext (leaving signature in clear)
            sign_then_encrypt_full (4),
            -- sign, then encrypt everything (including signature)
            encrypt_then_sign      (5),
            -- encrypt, then sign the ciphertext
            clear_sign_only        (6)
         } OPTIONAL,
      o  protect_oper_oid   OBJECT IDENTIFIER OPTIONAL,
         -- may be used in place of above parameter if OID is known
      o  sign_qop_alg      UNSIGNED INTEGER,
      o  sign_qop_algID    AlgorithmIdentifier, --overrides sign_qop_alg
      o  enc_qop_alg       UNSIGNED INTEGER,
      o  enc_qop_algID     AlgorithmIdentifier, --overrides enc_qop_alg
      o  idu_type_string    OCTET STRING,
         -- type of the IDU ("data", "e-mail doc", MIME type, etc.)
      o  pidu_type_string   OCTET STRING,
      o  mech_indep_encap_req BOOLEAN -- (see Appendix A)

   o  PIDU_Information PARAMETER BUNDLE
      o  protect_options    Protect_Options,
      o  originator_name    INTERNAL NAME,
      o  originator_role    Originator_Role, -- (see Section 2.3.4.1)
      o  protection_time    INTEGER,
   o  Bad_Target_Name PARAMETER BUNDLE,  -- same as in Section 2.3.3.2
      o  bad_targ_name     INTERNAL NAME,
      o  bad_targ_status   INTEGER,
         -- a status flag giving the reason for rejection of the name
         -- in bad_targ_name.  Specified reasons include:
         --  SYNTAX_INVALID        (0) the syntax of the name is invalid;
         --  NAME_UNRECOGNIZED     (1) the name is not recognized;
         --  NAME_AMBIGUOUS        (2) the name cannot be resolved;
         --  ACCESS_DENIED         (3) access to this target is denied;
         --  CERTIFICATE_NOT_FOUND (4) the encryption certificate of the
                                      target could not be found.

   o  Target_Info PARAMETER BUNDLE,      -- same as in Section 2.3.3.2
      o  targ_names        SET OF INTERNAL NAME,
      o  bad_targ_count    INTEGER,
      o  bad_target_names  SET OF Bad_Target_Name,





Adams                        Informational                     [Page 22]

RFC 2479                      IDUP-GSS-API                 December 1998


2.3.2.3. IDUP_SE major_status codes

   The following major_status return codes are defined for the "SE"
   calls in this section:

   o  GSS_S_COMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
      -- returned (by any SE call) to indicate that there is more output
      -- data than can fit into the supplied buffers.  The application
      -- should save the returned data and call again to retrieve the
      -- remaining output.
   o  IDUP_S_MORE_PIDU_NEEDED
      -- indicates that more PIDU data is needed for the StartUnprotect
      -- operation (e.g., so that PIDU_Information or initial_idu_buffer
      -- may be returned).
   o  IDUP_S_INCONSISTENT_PARAMS
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  GSS_S_BAD_QOP
   o  GSS_S_FAILURE

   If Target_Info is used as an input parameter (e.g., if an encryption
   operation is being performed), the following major_status return code
   is also defined:

   o  IDUP_S_BAD_TARG_INFO

   Note for this return code that if one or more of the targets in
   targ_names cannot be used as a valid recipient of the P-IDU, these
   names will be returned in bad_targ_names (with associated status
   codes in bad_targ_status).  As long as at least one of the targets
   can be used, however, this does not cause this call to fail (i.e.,
   the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
   caller's choice to discontinue IDU protection if the target set which
   can be used is unsuitable for the caller's purposes.

2.3.2.4. IDUP_SE_SingleBuffer_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Protect_Options PARAMETER BUNDLE,
   o  Target_Info PARAMETER BUNDLE,
   o  idu_buffer OCTET STRING
   o  additional_protection BOOLEAN
      -- TRUE if idu_buffer is the output of a previous protection
      -- operation (i.e., if this is the second (or higher) in a
      -- series of SE/EV protection calls)




Adams                        Informational                     [Page 23]

RFC 2479                      IDUP-GSS-API                 December 1998


   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  pidu_buffer OCTET STRING,
   o  sig_token OCTET STRING
      -- used if Protect_Options is clear_sign_only

   Using the security environment referenced by env_handle, encrypt
   and/or sign the supplied IDU.  If "clear signing" is performed, the
   signature will be returned in sig_token and pidu_buffer may be empty
   (depends on underlying mechanism).

2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  pidu_buffer OCTET STRING,
      -- may contain an IDU if sig_token is non-NULL (i.e., if
      -- clear_sign_only protection was applied)
   o  sig_token OCTET STRING

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  idu_buffer OCTET STRING,
      -- may be empty if clear_sign_only protection was applied (depends
      -- on underlying mechanism)
   o  PIDU_Information PARAMETER BUNDLE
   o  additional_unprotection BOOLEAN
      -- TRUE if idu_buffer should be input to another unprotection
      -- operation (i.e., if this should not be the last in a series
      -- of SE/EV unprotection calls)

   Using the security environment referenced by env_handle, decrypt
   and/or verify the supplied PIDU and return the contained IDU along
   with all available PIDU_Information.

2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Protect_Options PARAMETER BUNDLE,
   o  Target_Info PARAMETER BUNDLE,
   o  additional_protection BOOLEAN, -- (see Section 2.3.2.4)
   o  idu_size INTEGER               -- (see Section 2.3.4.2)






Adams                        Informational                     [Page 24]

RFC 2479                      IDUP-GSS-API                 December 1998


   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  initial_pidu_buffer OCTET STRING
      -- may be empty (depends on underlying mechanism)

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of signing and/or
   encrypting the IDU (which will be supplied in multiple buffers to the
   Process_Buffer call).

2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  final_pidu_buffer OCTET STRING,
   o  sig_token OCTET STRING
      -- used if Protect_Options was clear_sign_only

   Using the security environment referenced by env_handle, complete the
   protection processing on the data and place the computed output in
   final_pidu_buffer and/or sig_token. Successful application of
   IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection
   can necessarily be performed successfully when the P-IDU arrives at
   the target (for example, it may be damaged in transit).

2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  initial_pidu_buffer OCTET STRING,
   o  sign_qop_alg_in UNSIGNED INTEGER,
      -- used if Protect_Options was clear_sign_only (and calling
      -- application has prior knowledge of signing alg. applied);
      -- if NULL, then sig_token must be supplied
   o  sig_token OCTET STRING
      -- used if Protect_Options was clear_sign_only;
      -- if NULL, then sign_qop_alg_in must be supplied

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  PIDU_Information PARAMETER BUNDLE,
      -- returns all available information



Adams                        Informational                     [Page 25]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  initial_idu_buffer OCTET STRING
      -- may be empty

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of decrypting
   and/or verifying the PIDU (which will be supplied in multiple buffers
   to the Process_Buffer call).

   The parameters sign_qop_alg_in and sig_token should not both be
   supplied (i.e., they should not both be non-NULL).  If they are both
   non-NULL, however, sig_token is taken to be authoritative since this
   is the token created at protection time and therefore is guaranteed
   to carry the information needed to unprotect.

2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  sig_token OCTET STRING  OPTIONAL
      -- used if Protect_Options was clear_sign_only and sig_token was
      -- not available when StartUnprotect was called

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  PIDU_Information PARAMETER BUNDLE,
      -- returns all available information
   o  final_idu_buffer OCTET STRING   -- may be empty
   o  additional_unprotection BOOLEAN -- (see Section 2.3.2.5)

   Using the security environment referenced by env_handle, complete the
   decryption and/or verification processing on the data and place any
   residual output in final_idu_buffer.

2.3.2.10. IDUP_SE_Process_Buffer call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  input_buffer OCTET STRING,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_buffer OCTET STRING
      -- may be zero length (depends on underlying mechanism and
      -- corresponding Start() call and Protect_Options value)





Adams                        Informational                     [Page 26]

RFC 2479                      IDUP-GSS-API                 December 1998


   Using the security environment referenced by env_handle, continue the
   processing on the data in input_buffer and, if it is available, put
   any resulting output data in output_buffer.  The application calls
   this routine over and over again with new buffers of data until it
   has processed all the data buffers of the IDU/PIDU. It then calls the
   appropriate End() call to complete the processing.

2.3.3.  The "EV" Calls

2.3.3.1. IDUP_EV Purpose

   The "EV" group of calls provides a simple, high-level interface to
   underlying IDUP mechanisms when application developers need to deal
   only with evidence but not with encryption or integrity services. It
   includes both the single-buffer and multiple-buffer IDU cases and can
   be used for the generation and verification of evidence tokens
   embodying several different types of evidences.

   The following list of evidence types is supported. This list is by no
   means exhaustive and it is anticipated that it may be extended in
   future versions of this specification.

      "Non-repudiation of Origin" prevents a message creator's false
      denial of creating and sending a message.

      "Non-repudiation of Creation" prevents a message creator's false
      denial of creating a message.

      "Non-repudiation of Sender" prevents a message creator's false
      denial of sending a message (that was not necessarily created by
      the sender).

      "Non-repudiation of Delivery" prevents a message recipient's false
      denial of having received and looked at the content of a message.

      "Non-repudiation of Receipt" prevents a message recipient's false
      denial of having received a message (whose content was not
      necessarily looked at by the recipient).

      "Non-repudiation of Approval" prevents a message recipient's false
      denial of having approved the content of a received message.

   An evidence is provided in the form of a evidence token. Two forms of
   evidence tokens are supported:

      o  Tokens including the associated data,





Adams                        Informational                     [Page 27]

RFC 2479                      IDUP-GSS-API                 December 1998


      o  Tokens without included data (but with a unique reference to
         the associated data).

   Evidence tokens may be freely distributed. Any possessor of an
   evidence token (and of the associated data, if not included in the
   token) can verify the evidence if it has the appropriate credentials
   which include the definition of security policies (i.e., keys alone
   do not permit the verification of evidence tokens). Any holder of an
   evidence token may store it (along with the associated data, if not
   included in the token) for later verification.

   Calls that are specific to the support of evidence include:

   * Generate_token, which generates a non-repudiation token using the
     current environment. The generated token may consist of:

      1 - an evidence token
      2 - a token containing a request for an evidence, which carries
          information describing which evidence type should be generated
          by the recipient(s) and sent back to some entities (that may
          or may not include the sender).
      3 - a token containing an evidence token which is an answer to an
          evidence that has been previously requested.
      4 - a token including both an evidence and a request for another
          evidence to be provided.

   * Verify_evidence, which verifies the evidence token using the
     current environment. This operation returns a major_status code
     which can be used to determine whether the evidence contained in a
     token is complete (i.e., can be successfully verified (perhaps
     years) later). If a token's evidence is not complete, the token can
     be passed to form_complete_pidu to complete it.

   Additional useful calls for evidence services include:
   * IDUP_Get_token_details (see Section 2.5.3);
   * IDUP_Form_Complete_PIDU (see Section 2.4.2).

2.3.3.2. IDUP_EV Parameters

   The following parameter bundles are used in the "EV" protection and
   unprotection sets of calls.

   o  Nr_Options PARAMETER BUNDLE
      o  evidence_type  INTEGER {
                   no_evidence         (0)
                   -- used when request-only token desired
                   proof_of_receipt    (1),
                   proof_of_delivery   (2),



Adams                        Informational                     [Page 28]

RFC 2479                      IDUP-GSS-API                 December 1998


                   proof_of_approval   (3),
                   proof_of_creation   (4),
                   proof_of_sender     (5),
                   proof_of_origin     (6)
         } OPTIONAL,
      o  evidence_type_oid  OBJECT IDENTIFIER OPTIONAL,
         -- may be used in place of above parameter if OID is known
      o  evidence_validity_duration     INTEGER,
         -- duration_in_minutes
         -- DURATION_HOUR  = 60;
         -- DURATION_DAY   = 1440;
         -- DURATION_WEEK  = 10080;
         -- DURATION_MONTH = 43200;// 30 days
         -- DURATION_YEAR  = 525600;//365 days
      o  mech_indep_encap_req BOOLEAN -- (see Appendix A)

   o  Originator_Information PARAMETER BUNDLE
      o  token_generator_name INTERNAL NAME,
         -- obtained from the credentials of the originator
         -- (e.g., from its public key certificate)
      o  token_generator_role Originator_Role OPTIONAL,
         -- (see Section 2.3.4.1)
      o  protection_time      INTEGER OPTIONAL

   o  Bad_Target_Name  PARAMETER BUNDLE  -- (see Section 2.3.2.2)
      o  bad_targ_name          INTERNAL NAME,
      o  bad_targ_status        INTEGER
         -- a status flag giving the reason for rejection of the
         -- name in bad_targ_name

   o  Target_Info PARAMETER BUNDLE       -- same as in Section 2.3.2.2
      o  targ_names           SET OF INTERNAL NAME,
      o  bad_targ_count       INTEGER,
      o  bad_target_names     SET OF Bad_Target_Name

   o  Request_Features PARAMETER BUNDLE
      o  requested_evidence_type  INTEGER {
                 no_evidence         (0), - used when no token desired
                 proof_of_receipt    (1),
                 proof_of_delivery   (2),
                 proof_of_approval   (3), },
      o  nr_req_policy                        OBJECT IDENTIFIER,
      o  evidence_from                        Target_Info,
      o  evidence_to                          Target_Info,
      o  include_received_token_in_evidence   BOOLEAN

   The following data_type is used in the "EV" protection calls.




Adams                        Informational                     [Page 29]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  Nr_Operation  INTEGER {
            evidence_and_or_evidence_request  (1),
            returned_evidence                 (2) }

2.3.3.3. IDUP_EV major_status codes

   The following major_status return codes are defined for the "EV"
   calls in this section:

   o  GSS_S_COMPLETE
      -- indicates that the evidence is complete
   o  IDUP_S_INCOMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
      -- returned (by any EV call) to indicate that there is more output
      -- data than can fit into the supplied buffers.  The application
      -- should save the returned data and call again to retrieve the
      -- remaining output.
   o  IDUP_S_INCONSISTENT_PARAMS
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_MATCH
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   If Target_Info is used as an input parameter (i.e., if an evidence is
   being requested ), the following major_status return code is also
   defined:

   o  IDUP_S_BAD_TARG_INFO

   Note for this return code that if one or more of the targets in
   targ_names cannot be used as a valid recipient of the P-IDU, these
   names will be returned in bad_targ_names (with associated status
   codes in bad_targ_status).  As long as at least one of the targets
   can be used, however, this does not cause this call to fail (i.e.,
   the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
   caller's choice to discontinue IDU protection if the target set which
   can be used is unsuitable for the caller's purposes.

2.3.3.4. IDUP_EV_SingleBuffer_Generate call

   Inputs:
   o  env_handle                 ENVIRONMENT HANDLE,
   o  nr_operation               Nr_Operation,
   o  Nr_Options                 PARAMETER BUNDLE,
   o  idu_buffer                 OCTET STRING,
   o  form_complete_pidu         BOOLEAN,
      -- if TRUE the implementation will attempt to form a complete PIDU
   o  include_data_in_token      BOOLEAN,



Adams                        Informational                     [Page 30]

RFC 2479                      IDUP-GSS-API                 December 1998


      -- if TRUE, data provided in idu_buffer will be included in the
      -- generated token; if FALSE, the data will not be included
   o  Request_Features           PARAMETER BUNDLE
      -- the type of the evidence that is requested;
      -- policy under which the returned evidence should be generated;
      -- the recipients that are supposed to send back an evidence;
      -- the recipients that should receive the requested evidence;
      -- an indicator include_received_token_in_evidence:
      --   if TRUE, the evidence token incorporating the request will be
      --   included in the data for which recipients will generate
      --   evidence; if FALSE, evidence will be generated using only
      --   the data (and not the token incorporating the request).
   o  additional_protection BOOLEAN -- (see Section 2.3.2.4)

   Outputs:
   o  major_status               INTEGER,
   o  minor_status               INTEGER,
   o  token                      OCTET STRING,
   o  evidence_check             OCTET STRING,
      -- present only if an evidence is requested.  Consists of data to
      -- be used to verify the requested token(s) (if any) when they are
      -- received.

   Description:

   This operation generates a non-repudiation token associated with the
   data passed in an input buffer. Two kinds of operations can be
   performed (using the Nr_Operation parameter):

   a) generating a token that includes either an evidence only, or
      an evidence request only, or both an evidence and an evidence
      request;

   b) generating a response token for some recipients that includes an
      evidence generated as a response to a request (in this case the
      idu_buffer is used to enter the request token that was received).

   It is possible to request the generation of complete evidence. This
   may succeed or fail; if it fails, a subsequent call to
   Form_Complete_PIDU can be made.

2.3.3.5. IDUP_EV_SingleBuffer_Verify call

   Inputs:
   o  env_handle                     ENVIRONMENT HANDLE,
   o  token                          OCTET STRING,
   o  external_idu_buffer            OCTET STRING,
      -- if not present within the token



Adams                        Informational                     [Page 31]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  evidence_check                 OCTET STRING,
      -- present only if the input token is a response to a previous
      -- request for evidence (this parameter is used to validate that
      -- evidence).

   Outputs:
   o  major_status                   INTEGER,
   o  minor_status                   INTEGER,
   o  Nr_Options                     PARAMETER BUNDLE,
   o  Originator_Information         PARAMETER BUNDLE,
   o  Request_Features               PARAMETER BUNDLE,
   o  trusted_time_stamping_time     INTEGER OPTIONAL,
      -- present for informational purposes only
   o  complete_evidence_before       INTEGER OPTIONAL,
      -- if the major status code that is returned is
      -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
      -- with the same token before this time.
      --    This may be required, for example, in order to insure that
      --    the time skew between the evidence generation time and
      --    the trusted time service's countersignature on the evidence
      --    falls within the interval allowed by the current NR policy.
   o  complete_evidence_after        INTEGER OPTIONAL,
      -- if the major status code that is returned is
      -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
      -- with the same token after this time.
      --    This may be required, for example, to insure that all
      --    authorities involved in generating the evidence have passed
      --    the last time at which the current NR policy allows them to
      --    repudiate their keys.
   o  encapsulated_idu_buffer         OCTET STRING
      -- if the IDU was present within the token
   o  additional_unprotection BOOLEAN -- (see Section 2.3.2.5)

   Description:

   Verifies the validity and discloses the content of a nr_token.

   If the token containing the evidence to be verified was provided to
   the calling application by a partner responding to the calling
   application's request, then the calling application must pass the
   evidence check it received when it generated the request as a
   parameter along with the token it received from the partner.

   Output indicators are provided which give guidance about the time or
   times at which form_complete_pidu should be called; see the parameter
   descriptions for explanations of these indicators and their use. Note
   that the time specified by complete_evidence_before may be earlier
   than that specified by complete_evidence_after; in this case it will



Adams                        Informational                     [Page 32]

RFC 2479                      IDUP-GSS-API                 December 1998


   be necessary to call form_complete_pidu twice.

   Because keys can be revoked or declared compromised, the return from
   verify_evidence cannot in all cases be a definitive "valid" or
   "invalid"; sometimes "conditionally valid" may be returned, depending
   upon the policy in use. IDUP_S_INCOMPLETE will be returned, for
   example, if:

    - the interval during which the generator of the evidence may
      permissibly declare his key invalid has not yet expired (and
      therefore it is possible that the evidence may be declared invalid
      in the future), or

    - trusted time is required for verification, and the time obtained
      from the token is not trusted.

2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call

   Inputs:
   o  env_handle                 ENVIRONMENT HANDLE,
   o  nr_operation               Nr_Operation,
   o  Nr_Options                 PARAMETER BUNDLE,
   o  form_complete_pidu         BOOLEAN,
   o  include_data_in_token      BOOLEAN,
   o  idu_size                   INTEGER, -- (see Section 2.3.4.2)
   o  Request_Features           PARAMETER BUNDLE
   o  additional_protection BOOLEAN -- (see Section 2.3.2.4)

   Outputs:
   o  major_status               INTEGER,
   o  minor_status               INTEGER,
   o  initial_pidu_buffer        OCTET STRING
      -- may be empty (depends on underlying mechanism)

   Description:

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the generation of a token. The
   IDU will be supplied in multiple buffers to the
   IDUP_EV_Process_Buffer call). Two kinds of operations can be
   performed (using the Nr_Operation parameter) :

     a) generating a token that includes either an evidence only, or
        an evidence request only, or both an evidence and an evidence
        request.






Adams                        Informational                     [Page 33]

RFC 2479                      IDUP-GSS-API                 December 1998


     b) generating a return token for some recipients that includes an
        evidence generated as a response to a request. In that case the
        received token will be passed into the subsequent
        IDUP_EV_Process_Buffer calls. The boolean include_data_in_token
        is ignored as the output will always be contained in a single
        token. The Request_Features are ignored in that case at this
        time in order to keep things simple and to avoid the piggy-
        backing that is theoretically possible.

   It is possible to request the generation of complete evidence. This
   may succeed or fail; if it fails, a subsequent call to
   Form_Complete_PIDU can be made.

2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call

   Inputs:
   o  env_handle                 ENVIRONMENT HANDLE

   Outputs:
   o  major_status               INTEGER,
   o  minor_status               INTEGER,
   o  final_pidu                 OCTET STRING,
   o  token                      OCTET STRING,
   o  evidence_check             OCTET STRING
      -- present only if an evidence is requested.

   Description:

   Using the security environment referenced by env_handle, provide the
   requested token or the final P-IDU. A token will be generated if
   encapsulation was not requested; otherwise, the final P-IDU is
   provided.

2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call

   Inputs:
   o  env_handle                     ENVIRONMENT HANDLE,
   o  token                          OCTET STRING,
   o  evidence_check                 OCTET STRING,
      -- present only if an evidence has been previously requested.

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER







Adams                        Informational                     [Page 34]

RFC 2479                      IDUP-GSS-API                 December 1998


   Description:

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of verifying the
   token.  The P-IDU will be supplied in multiple buffers to the
   IDUP_EV_Process_Buffer call.

2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call

   Input:
   o  env_handle                     ENVIRONMENT HANDLE

   Outputs:
   o  major_status                   INTEGER,
   o  minor_status                   INTEGER,
   o  Nr_Options                     PARAMETER BUNDLE,
   o  Originator_Information         PARAMETER BUNDLE,
   o  Request_Features               PARAMETER BUNDLE,
   o  trusted_time_stamping_time     INTEGER OPTIONAL,
   o  complete_evidence_before       INTEGER OPTIONAL,
   o  complete_evidence_after        INTEGER OPTIONAL,
   o  idu_buffer                     OCTET STRING
      -- if the IDU was present within the token
   o  additional_unprotection BOOLEAN -- (see Section 2.3.2.5)

   Description:

   Using the security environment referenced by env_handle, complete the
   verification processing on the data and provide verified output
   parameters to the caller when the major status code is either:

   o GSS_S_COMPLETE or
   o IDUP_S_INCOMPLETE

2.3.3.10. IDUP_EV_Process_Buffer call

   Inputs:
   o  env_handle         ENVIRONMENT HANDLE,
   o  input_buffer       OCTET STRING

   Outputs:
   o  major_status       INTEGER,
   o  minor_status       INTEGER,
   o  output_buffer      OCTET STRING
      -- may be zero length (depends on underlying mechanism and
      -- corresponding Generate () call and options
      -- (e.g., data_included_in_token)




Adams                        Informational                     [Page 35]

RFC 2479                      IDUP-GSS-API                 December 1998


   Description:

   Using the security environment referenced by env_handle, continue the
   processing on the data in input_buffer and, if it is available, put
   any resulting output data in output_buffer. The application calls
   this routine over and over again with new buffers of data until it
   has processed all the data buffers of the IDU/PIDU. It then calls the
   appropriate End() call to complete the processing.

2.3.4. The "GP" Calls

   The "GP" group of calls provides a powerful interface to flexible and
   sophisticated combinations of protection and unprotection services.
   This power and flexibility, however, necessitates a more complex
   interface than either the SE or the EV calls. Furthermore, such
   combinations of services are not needed in many of the security
   mechanisms in common use today (although this is likely to change as
   time goes on).  The GP calls are therefore specified to be OPTIONAL
   and need not be supported by IDUP-conformant implementations.  Note,
   however, that the structure of IDUP tokens should be such that the
   SE/EV and GP calls may be used interchangably by the receiver.

2.3.4.1. Parameter Bundles

   The concept of "parameter bundles" is used in the calls presented in
   the following subsections in order to simplify their presentation and
   clarify their intended purpose and use (note that specific language
   bindings may or may not use parameter bundles for its actual calling
   conventions).  A parameter bundle is simply a set of closely-related
   parameters of a call which are either all used by / available to the
   calling application or all not used by / unavailable to the calling
   application.  These parameters may be all input parameters, all
   output parameters, or any combination of the two.

   An example use envisioned for parameter bundles in a language such as
   C would be as a structure, where individual parameters in the bundle
   are structure members.  The calling application wishing to use a
   particular bundle would then allocate the appropriate structure
   variable, assign the desired input values to the appropriate members,
   and pass the address of the structure as the bundle "parameter".  On
   output, the values of the appropriate output members may be read.  An
   application not wishing to use a particular bundle (or one which is
   satisfied with default values for all input parameters of the bundle
   and which doesn't care about output values), can pass NULL as the
   bundle "parameter".  From the mechanism implementor's perspective, if
   a parameter bundle is not supported (for example, if it represents a
   security service which is not supported by the implementation), then
   any non-NULL value passed as the bundle parameter will generate an



Adams                        Informational                     [Page 36]

RFC 2479                      IDUP-GSS-API                 December 1998


   error status return code.

   [Note that the parameter bundles given below, except where explicitly
   referenced by the SE and EV calls, are specific to the (optional) GP
   calls.  Thus, these bundles need not be supported by IDUP-conformant
   implementations if the GP calls are not supported.]

   The following parameter bundles are used in the subsequent protection
   and unprotection sets of calls.  A parameter preceded by "(I)" is an
   input parameter; one preceded by "(O)" is an output parameter; one
   preceded by neither is an input if the bundle itself is an input and
   is an output if the bundle itself is an output; one preceded by "(X)"
   is the opposite:  an output if the bundle itself is an input and an
   input if the bundle itself is an output.

      o Mech_Specific_Info PARAMETER BUNDLE
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism

      o Sensitivity PARAMETER BUNDLE,
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism, but may include
        -- codified values for "Unclassified", "Secret", "Top Secret",
        -- and so on

      o Service_Creation_Info PARAMETER BUNDLE
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism, but it is mandatory
        -- that they include at least service_id and Quality

      o Service_Verification_Info PARAMETER BUNDLE
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism, but it is mandatory
        -- that they include at least service_id and Quality

      o  Quality PARAMETER BUNDLE
         o  qop_algs  UNSIGNED INTEGER,
         o  qop_algID AlgorithmIdentifier, --overrides qop_algs
         o  validity  UNSIGNED INTEGER,
            -- protection guaranteed to be valid until time specified
         o  policy_id OBJECT IDENTIFIER,
            -- security policy under which protection is/was carried out
         o  allow_policy_mapping BOOLEAN,
            -- determines whether mapping between policy IDs is allowed
         o  actual_policy_time INTEGER
            -- time at which the above policy rules came into effect





Adams                        Informational                     [Page 37]

RFC 2479                      IDUP-GSS-API                 December 1998


      o  Idu_Information PARAMETER BUNDLE,
         o  idu_type_oid OBJECT IDENTIFIER,
         o  idu_type_string OCTET STRING,
         o  idu_title OCTET STRING,
         o  idu_sensitivity Sensitivity,
         o  pidu_type_oid OBJECT IDENTIFIER,
         o  pidu_type_string OCTET STRING,
         o  pidu_title OCTET STRING,
         o  pidu_sensitivity Sensitivity,

      o  Prot_Information PARAMETER BUNDLE,
         o  originator_name INTERNAL NAME,
         o  originator_role Originator_Role,
         o  idu_information Idu_Information,
         o  protection_time INTEGER,

      o  Originator_Role PARAMETER BUNDLE, -- role in organization
         o  domain_name                 INTERNAL NAME OPTIONAL,
         o  role                        PRINTABLE STRING,
         o  role_info_is_authenticated  BOOLEAN
            -- TRUE if info. is authenticated (e.g., inside a cert.)

      o  Special_Conditions PARAMETER BUNDLE,
         o  prot_oper_id INTEGER,
         o  form_complete_pidu BOOLEAN,
            -- input to protection operations for evidence generation
         o  pidu_in_solic_service BOOLEAN,
            -- in protection operations, used as input for service
            -- solicitation to request that receiver include the
            -- received PIDU when generating the response.  In unprot.
            -- operations, used as output to inform receiver that PIDU
            -- should be included when generating the response.
         o  use_trusted_time BOOLEAN,
         o  use_untrusted_time BOOLEAN,
         o  mech_indep_encap_req BOOLEAN -- (see Appendix A)

      o  Bad_Target_Name PARAMETER BUNDLE,
         o  (O) bad_targ_name INTERNAL NAME,
         o  (O) bad_targ_status INTEGER,
                -- a status flag giving the reason for rejection of
                -- the name in bad_targ_name. Specified reasons include:
                --    SYNTAX_INVALID        (0)
                --       the syntax of the name is invalid;
                --    NAME_UNRECOGNIZED     (1)
                --       the name is not recognized;
                --    NAME_AMBIGUOUS        (2)
                --       the name cannot be resolved;
                --    ACCESS_DENIED         (3)



Adams                        Informational                     [Page 38]

RFC 2479                      IDUP-GSS-API                 December 1998


                --       access to this target is denied;
                --    CERTIFICATE_NOT_FOUND (4)
                --       the encryption certificate of the target could
                --       not be found.

      o  Target_Info PARAMETER BUNDLE,
         o      targ_names       SET OF INTERNAL NAME,
         o  (O) bad_targ_count   INTEGER,
         o  (O) bad_target_names SET OF Bad_Target_Name,

      o  General_Service_Data PARAMETER BUNDLE,
         o      target_info Target_Info,
         o  (X) unencapsulated_token OCTET STRING,
                -- zero length if encapsulation_request is TRUE
         o  (O) minor_status INTEGER,

   Three types of protection services are defined in IDUP.  These are:

      1. perform unsolicited service (i.e., act on a locally-generated
         service request),
      2. perform solicited service (i.e., act on a remotely-generated
         service request), and
      3. perform service solicitation (i.e., send a service request to
         the remote end).

   As an originator, applying data confidentiality with data integrity,
   or data origin authentication with data integrity, or proof of origin
   evidence is an example of service type 1.  As a target, creating a
   proof of delivery (i.e., receipt) evidence token as the result of a
   request received from the originator is an example of service type 2.
   Finally, as an originator, submitting a request that one or more
   targets return a receipt for the data sent is an example of service
   type 3.

   The first four parameters in the Prot_Service parameter bundle
   pertain to all service types; the fifth parameter is used if and only
   if service type 2 is desired; parameters 6-8 are used if and only if
   service type 3 is desired.

      o  Prot_Service PARAMETER BUNDLE
         o  (I) prot_service_type INTEGER,
         o  (I) service_id OBJECT IDENTIFIER,
         o  (I) quality Quality, -- NULL specifies default Quality
         o  (I) general_service_data General_Service_Data,
         o  (I) service_creation_info Service_Creation_Info,
         o  (I) service_to SET OF INTERNAL NAME,
         o  (O) service_verification_info Service_Verification_Info,
         o  (O) service_verification_info_id INTEGER,



Adams                        Informational                     [Page 39]

RFC 2479                      IDUP-GSS-API                 December 1998


   Also, three types of unprotection services are defined.  These are:

      1. receive unsolicited service (i.e., process unrequested
         remotely-generated service),
      2. receive solicited service (i.e., process remotely-generated
         response to locally-generated request), and
      3. receive service solicitation (i.e., process req. from rem. end)

   As a target, unprotecting an encrypted message, or verifying the
   originator's proof of origin is an example of service type 1.  As an
   originator, verifying a proof of delivery which you requested from a
   target is an example of service type 2.  Finally, as a target,
   receiving a request from an originator for a proof of delivery is an
   example of service type 3.

   The first four parameters in the Unprot_Service parameter bundle
   pertain to all service types; parameters 5-6 are used if and only if
   service type 2 is required; parameters 7-8 are used only if service
   type 3 is required.

      o  Unprot_Service PARAMETER BUNDLE
         o  (O) unprot_service_type INTEGER,
         o  (O) service_id OBJECT IDENTIFIER,
         o  (O) quality Quality,
                -- actual Quality specified (never NULL)
         o  (O) general_service_data General_Service_Data,
         o  (O) service_verification_info_id INTEGER,
         o  (I) service_verification_info Service_Verification_Info,
         o  (O) service_to SET OF INTERNAL NAME,
         o  (O) service_creation_info Service_Creation_Info,

2.3.4.2. IDUP_Start_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Mech_Specific_Info PARAMETER BUNDLE,
      -- NULL selects the mechanism-defined default values
   o  Idu_Information PARAMETER BUNDLE,
   o  Special_Conditions PARAMETER BUNDLE,
   o  encapsulation_request BOOLEAN,
   o  single_idu_buffer OCTET STRING,
      -- non-zero length for this buffer means that Protect/End_Protect
      -- won't be called (i.e., entire IDU is contained in this buffer)
   o  idu_size INTEGER,
      -- size (in bytes) of the IDU to be protected;
      -- may be "-1" signifying "UNKNOWN" (note that some mechanisms
      -- may not support encapsulation in such a case)
   o  Target_Info PARAMETER BUNDLE,



Adams                        Informational                     [Page 40]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  Services_to_Perform SET OF Prot_Service,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  midu_buffer OCTET STRING,
      -- zero length if encapsulation_request is TRUE;
      -- may be zero length otherwise (depends on underlying mechanism)
   o  pidu_buffer OCTET STRING,
      -- zero length if encapsulation_request is FALSE;
      -- may be zero length otherwise (depends on underlying mechanism)

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- the protection process can begin (or has completed, if
      -- single_idu_buffer has non-zero length).
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  IDUP_S_ENCAPSULATION_UNAVAIL
   o  IDUP_S_SERVICE_UNAVAIL
   o  IDUP_S_REQ_TIME_SERVICE_UNAVAIL
   o  IDUP_S_UNKNOWN_OPER_ID
   o  GSS_S_BAD_QOP
   o  IDUP_S_BAD_TARG_INFO
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of protecting the
   IDU buffers.  The caller requests specific protection services by
   supplying the appropriate Prot_Service parameter bundles in
   Services_to_Perform.  Each service is able to return a minor status
   code to the calling application, if necessary.

   The calling application, knowing the size of the IDU it wishes to
   protect and the buffer size which it has available to it, can choose
   to input the entire IDU in a single buffer and omit the subsequent
   IDUP_Protect() and IDUP_End_Protect() calls.  Furthermore, the
   application can request that the resulting M-IDU be encapsulated in
   the token -- so that the token contains the entire P-IDU -- rather
   than having it be returned separately in midu_buffer.  Encapsulation,
   however, may not be supported by all underlying mechanisms or
   implementations; if this is the case, the
   IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and
   M-IDU will be returned in midu_buffer.






Adams                        Informational                     [Page 41]

RFC 2479                      IDUP-GSS-API                 December 1998


   For those mechanisms which allow or require multiple stages of
   processing, each producing a different aspect of protection for the
   IDU, the operation identifier prot_oper_id is used to specify which
   stage is currently being requested by the application.  An example
   where this would be useful is a mechanism which implements the signed
   Message Security Protocol [MSP].  As another example, a mechanism may
   choose to do a digital signature in two stages:  one for the hashing
   of the message and another for the signature on the hash.  The
   calling application would therefore use the protection set of calls
   on the IDU in stage 1 and then use the protection set of calls on the
   token (from stage 1) in stage 2.

   Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where
   "n" is the number of stages as defined by the mechanism (typically 1
   or 2)).  The calling application uses this parameter to indicate to
   the underlying mechanism whether it wishes to do stage 1 of
   protection / unprotection processing, or stage 2, and so on. Portable
   applications may pass "0" to let the mechanism choose the stage (note
   that mechanism implementers may still iterate when prot_oper_id = 0
   (e.g., use output as next input, et cetera).

   If one or more of the targets in targ_names cannot be used as a valid
   recipient of the P-IDU, these names will be returned in
   bad_targ_names (with associated status codes in bad_targ_status).  As
   long as at least one of the targets can be used, this does not cause
   this call to fail; it is the caller's choice to discontinue IDU
   protection if the target set which can be used is unsuitable for the
   caller's purposes.  Note that each Prot_Service parameter bundle can
   also input a list of targ_names; this is used if a separate list is
   to be used for that service only (the general list of targets is to
   be used for all services unless overridden in this way).

2.3.4.3. IDUP_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  input_buffer OCTET STRING,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_buffer OCTET STRING
      -- may be zero length if encapsulation_request was set to TRUE in
      -- IDUP_Start_Protect() (depends on underlying mechanism)

   Return major_status codes:
   o  GSS_S_COMPLETE
   o  IDUP_S_NO_ENV



Adams                        Informational                     [Page 42]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, continue the
   protection processing on the data in input_buffer and, if the
   underlying mechanism defines this, put any resulting P-IDU/M-IDU data
   in output_buffer.  The application calls this routine over and over
   again with new buffers of data until it has protected all the data
   buffers of the IDU.  It then calls IDUP_End_Protect() to complete the
   protection processing.

2.3.4.4. IDUP_End_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  Services_to_Perform SET OF Prot_Service,
   o  final_midu_buffer OCTET STRING,
      -- zero length if encapsulation_request was set to TRUE in
      -- IDUP_Start_Protect(), in which case pidu is used
   o  final_pidu_buffer OCTET STRING,
      -- zero length if encapsulation_request was set to FALSE in
      -- IDUP_Start_Protect(), in which case token and midu are used

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- protection has successfully completed and the resulting P-IDU
      -- is ready for transfer.  If defined by the underlying mechanism,
      -- final_midu_buffer will contain any residual M-IDU data.
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, complete the
   protection processing on the data and place the computed output in
   final_pidu_buffer (or final_midu_buffer and the unencapsulated_token
   parameter for each Prot_Service).  If a service was requested from
   one or more targets in Start_Protect() - and if this is supported by
   the underlying mechanism - Service_Verification_Info will hold
   whatever data is necessary for the mechanism to verify a service
   returned by a target (unprotector) of the P-IDU.  Successful
   application of IDUP_End_Protect() does not guarantee that the
   corresponding unprotection set of calls can necessarily be performed
   successfully when the P-IDU arrives at the target (for example, it
   may be damaged in transit).




Adams                        Informational                     [Page 43]

RFC 2479                      IDUP-GSS-API                 December 1998


2.3.4.5. IDUP_Start_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Mech_Specific_Info PARAMETER BUNDLE,
      -- NULL selects the mechanism-defined default values
   o  single_pidu_buffer OCTET STRING,
      -- non-zero length for this buffer means that IDUP_Unprotect() and
      -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU
      -- (if encapsulation is used) or M-IDU (if encap. is not used)
      -- is contained in this buffer)
   o  partial_pidu_buffer OCTET STRING,
      -- may be an arbitrary-sized piece of the full pidu (if the
      -- application's buffer isn't large enough to hold entire pidu).
      -- Used if pidu_buffer will be input a buffer at a time (except
      -- that the final buffer must be passed in final_pidu_buffer
      -- rather than partial_pidu_buffer).  Only one of
      -- single_pidu_buffer and partial(final)_pidu_buffer can have
      -- nonzero length.
   o  final_pidu_buffer OCTET STRING,
   o  Special_Conditions PARAMETER BUNDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  Services_to_Receive SET OF Unprot_Service,
   o  Prot_Information PARAMETER BUNDLE,
   o  single_idu_buffer OCTET STRING,
      -- if this buffer has non-zero length, then service processing has
      -- been completed on the data in single_pidu_buffer
   o  initial_idu_buffer OCTET STRING,
      -- holds any data from partial(final)_pidu_buffer which has been
      -- unprotected; remaining data will be returned by Unprotect and
      -- End_Unprotect as they are called with successive buffers of
      -- pidu
   o  Service_Verification_Info PARAMETER BUNDLE,
      -- used only if target is on "service_to" list in Unprot_Service
   o  service_verification_info_id INTEGER,
      -- used only if target is on "service_to" list in Unprot_Service












Adams                        Informational                     [Page 44]

RFC 2479                      IDUP-GSS-API                 December 1998


   Return major_status codes:
   o  GSS_S_COMPLETE
      -- unprotection processing can begin (or has completed, if
      -- single_idu_buffer has non-zero length).
   o  IDUP_S_INCOMPLETE
      -- used only if single_idu_buffer has non-zero length.
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  IDUP_S_MORE_PIDU_NEEDED
   o  GSS_S_DEFECTIVE_TOKEN
   o  IDUP_S_INAPPROPRIATE_CRED
   o  IDUP_S_INCONSISTENT_PARAMS
   o  IDUP_S_DEFECTIVE_VERIF
   o  IDUP_S_NO_MATCH
   o  IDUP_S_SERVICE_UNAVAIL
   o  IDUP_S_REQ_TIME_SERVICE_UNAVAIL
   o  IDUP_S_SERV_VERIF_INFO_NEEDED
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  IDUP_S_UNKNOWN_OPER_ID
   o  GSS_S_BAD_QOP
      -- the qop_algs value specified in P-IDU for at least one of the
      -- services is unavailable in the local mechanism, so processing
      -- cannot continue.
   o  GSS_S_BAD_MIC
   o  IDUP_S_BAD_DOA_KEY
   o  IDUP_S_BAD_KE_KEY
   o  IDUP_S_BAD_ENC_IDU
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of unprotecting a
   P-IDU.  The caller will be alerted as to which services were applied
   to the P-IDU in the returned Services_to_Receive set of parameters.

   If encapsulation was not used by the originator, it is the receiving
   application's responsibility to separate the received P-IDU into a
   M-IDU and one or more unencapsulated_token buffers (the latter being
   input in separate Unprot_Service bundles in the Services_to_Receive
   parameter).  These unencapsulated_token buffers should be input
   before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU
   (i.e., in IDUP_End_Unprotect) as appropriate; this order may be
   dictated, for example, by their placement in the in-coming message.

   If unprotection will be applied more than once to a given P-IDU, it
   is the responsibility of the calling application to remember if a
   service solicitation has been responded to previously (i.e., if the
   requested service has already been generated / sent for that P-IDU)
   and thus ignore subsequent solicitations on unprotect.



Adams                        Informational                     [Page 45]

RFC 2479                      IDUP-GSS-API                 December 1998


   The time flags indicate whether to consult trusted, untrusted, or no
   time (if both flags are FALSE) during the unprotection operation.  If
   the current time is not to be checked, then unprotection may be
   successful even if the protector's key has expired since the P-IDU
   was generated (that is, if the Validity period -- as specified in the
   Quality parameter bundle -- has expired).

   If the underlying mechanism supports it and if this information is
   contained in the P-IDU, information regarding the originator (that
   is, the entity which used the protection set of calls to generate
   this P-IDU) is returned in the Prot_Information parameter bundle.

2.3.4.6. IDUP_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  input_buffer OCTET STRING

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_buffer OCTET STRING

   Return major_status codes:
   o  GSS_S_COMPLETE
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, continue the
   unprotection processing on the data in input_buffer, putting any
   resulting IDU data in output_buffer (if required).

2.3.4.7. IDUP_End_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  Prot_Information PARAMETER BUNDLE,
   o  Services_to_Receive SET OF Unprot_Service,
   o  final_idu_buffer OCTET STRING,
   o  Service_Verification_Info PARAMETER BUNDLE,
      -- used only if target is on "service_to" list in Unprot_Service
   o  service_verification_info_id INTEGER,
      -- used only if target is on "service_to" list in Unprot_Service




Adams                        Informational                     [Page 46]

RFC 2479                      IDUP-GSS-API                 December 1998


   Return major_status codes:
   o  GSS_S_COMPLETE
      -- residual IDU data will be returned in final_idu_buffer.
   o  IDUP_S_INCOMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  GSS_S_BAD_MIC
   o  IDUP_S_BAD_DOA_KEY
   o  IDUP_S_BAD_KE_KEY
   o  IDUP_S_BAD_ENC_IDU
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, complete the
   unprotection processing on the data and return the appropriate status
   code.  If there is any residual IDU data it will be returned in
   final_idu_buffer.

   If the IDUP_S_INCOMPLETE major status value is returned, all output
   parameters are conditionally valid; the unprotection set of functions
   will have to be called again (perhaps with a complete P-IDU, as
   produced by IDUP_Form_Complete_PIDU) in order to get valid values for
   all parameters.  "Conditional validity" may arise, for example, if
   all relevant certificates verify correctly, but it is not yet past
   the time up to which the current policy allows the authorities
   involved to repudiate their keys.

   If the underlying mechanism supports it and if this information is
   contained in the token, information regarding the originator (that
   is, the entity which used the protection set of calls to generate
   this token) is returned in the Prot_Information parameter bundle.
   This information may or may not be omitted if it was returned by the
   IDUP_Start_Unprotect() call.

   Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the
   concept of error tokens transferred between sender and recipient
   since the protection and unprotection of an IDU may be separated by
   an indefinite amount of time and may or may not be performed by the
   same entity.

2.4. Special-Purpose Calls

2.4.1.  Relationship to GSS-API

   The special-purpose call described in this section has no analog in
   GSS-API [RFC-2078].  This call is used to complete a P-IDU (that is,
   to generate a P-IDU which can be unprotected successfully with no
   additional data at any time during its validity period).  This call
   may not be supported by all underlying IDUP mechanisms or



Adams                        Informational                     [Page 47]

RFC 2479                      IDUP-GSS-API                 December 1998


   implementations.

2.4.2. IDUP_Form_Complete_PIDU call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  single_pidu_buffer OCTET STRING,
   o  partial_pidu_buffer OCTET STRING,
      -- an arbitrary-sized piece of the full pidu token.  Used if pidu
      -- will be input a buffer at a time (except that the final buffer
      -- must be passed in final_pidu_buffer rather than
      -- partial_pidu_buffer).  Only one of single_pidu_buffer and
      -- partial(final)_pidu_buffer can have nonzero length.
   o  final_pidu_buffer OCTET STRING,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  pidu_token_out OCTET STRING -- the augmented PIDU; may be complete
   o  call_again_before INTEGER,
   o  call_again_after INTEGER,
   o  trusted_time_stamping_time INTEGER  -- for information only

   Return major_status codes:
   o  GSS_S_COMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  IDUP_S_INCOMPLETE
      -- generation of the P-IDU is not yet complete.  The application
      -- should call this function again before the time given in
      -- call_again_before (if not NULL), or after the time given in
      -- call_again_after (if not NULL), or both (if neither are NULL).
   o  IDUP_S_INCONSISTENT_PARAMS
   o  IDUP_S_SERVICE_UNAVAIL
   o  GSS_S_DEFECTIVE_TOKEN
   o  GSS_S_FAILURE

   Form_Complete_PIDU is used primarily by the evidence services; in
   particular, when the evidence token itself does not contain all the
   data required for its verification and it is anticipated that some of
   the data not stored in the token may become unavailable during the
   interval between generation of the evidence token and verification
   unless it is stored in the token. The Form_Complete_PIDU operation
   gathers the missing information and includes it in the token so that
   verification can be guaranteed to be possible at any future time.

   This call generates a PIDU which can be unprotected successfully with
   no additional data at any time during its validity period.  [For
   background information on the notion of "complete" evidence, see



Adams                        Informational                     [Page 48]

RFC 2479                      IDUP-GSS-API                 December 1998


   "CORBA Security Service v1.2 Draft D02", 18 June 1997.]

   Using the security environment referenced by env_handle, complete the
   generation of a P-IDU token and return the appropriate status value
   along with the completed token (if available).  Such a call may be
   used, for example, for the purpose of batch evidence generation on an
   "evidence server".  A local machine may be able to use the protection
   set of calls to fill out most of an evidence token and then send a
   number of these to a batch processor which forms the complete
   evidence tokens (perhaps by adding a certification path, or a
   timestamp and signature from a timestamping authority).  As another
   example, on the receiving end an application may make such a call in
   order to collect all the information necessary to unprotect a P-IDU
   (such as all relevant certificates and Certificate Revocation Lists);
   this will ensure that the calls to the unprotection set of operations
   will be entirely local (i.e., can be performed off-line) and fast.

   Note that the complete P-IDU generated will be formed using trusted
   time if this is available in the environment referenced by env_handle
   and will use untrusted time or no time otherwise (depending on what
   is available).

2.5.  Support calls

2.5.1.  Relationship to GSS-API

   Support calls in IDUP-GSS-API are to be understood and used as
   described in GSS-API [RFC-2078].  The calls described in Section 2.4
   of GSS-API (including all associated parameters) are unchanged.  The
   following additional calls are specified for IDUP-GSS-API.

2.5.2:  IDUP_Acquire_cred_with_auth call

   Inputs:
   o  desired_name INTERNAL NAME,
      -- NULL requests locally-determined default
   o  authenticator OCTET STRING
      -- string which authenticates the caller claiming to be
      -- desired_name
   o  lifetime_req INTEGER,
      -- in seconds; 0 requests default
   o  desired_mechs SET OF OBJECT IDENTIFIER,
      -- empty set requests system-selected default
   o  cred_usage BIT STRING
      -- actual values which can be used currently correspond to those
      -- given in Section 2.1.1 (i.e.,
      --    ENCRYPT_ONLY    8
      --    DECRYPT_ONLY   16



Adams                        Informational                     [Page 49]

RFC 2479                      IDUP-GSS-API                 December 1998


      --    SIGN_ONLY      32
      --    VERIFY_ONLY    64
      -- with the values logically OR'ed together in any desired
      -- combination to restrict credential usage; OR'ing all values
      -- results in NO_RESTRICTION).
      -- Future possible values for this parameter are for further
      -- study (note that the type of this parameter is BIT STRING
      -- (rather than INTEGER as in GSS_Acquire_cred) to facilitate
      -- such future expansion).

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_cred_handle  CREDENTIAL HANDLE,
   o  actual_mechs SET OF OBJECT IDENTIFIER,
   o  actual_cred_usage   BIT STRING,
   o  lifetime_rec INTEGER
      -- in seconds, or reserved value for INDEFINITE

   This call (which need not be supported by all underlying mechanisms
   or implementations) is identical to the GSS_Acquire_cred call, with
   the exception of the added input parameter "authenticator" and the
   added output parameter "actual_cred_usage". The authenticator
   (typically a password, pass-phrase, or PIN) is used to authenticate
   the caller claiming to be desired_name to the underlying GSS (or
   mechanism) code.  The actual_cred_usage specifies the actual uses
   available for these credentials; it is up to the caller to determine
   if this is sufficient for its purposes.

   Implementations that are able to authenticate the caller in some
   other way are encouraged to use the GSS_Acquire_cred call; those
   having no other means available to them, or wishing to explicitly
   authenticate the caller at the time of credential acquisition, should
   use the IDUP_Acquire_cred_with_auth call (if supported).

   Note that the return major status codes for this call are identical
   to those given for the GSS_Acquire_cred call.  If the authentication
   fails (e.g., the wrong authenticator is supplied for the given
   desired_name), the major status GSS_S_FAILURE is returned (along with
   an appropriate minor status code).

2.5.3. IDUP_Get_token_details call

   Inputs:
   o  token                  OCTET STRING,
   -- all the data to be returned shall be within the first 4 KB of
   -- the token; hence, a single call is needed. It is not necessary
   -- to provide the entire token when the token includes the IDU.



Adams                        Informational                     [Page 50]

RFC 2479                      IDUP-GSS-API                 December 1998


   o  mech_type              SET OF OBJECT IDENTIFIER
   -- input if known (typically SET will contain a single member)

   Outputs:
   o  major_status                       INTEGER,
   o  minor_status                       INTEGER,
   o  actual_mech_type                   OBJECT IDENTIFIER,
   o  data_included_in_token             BOOLEAN,
      -- true if the data is encapsulated
   o  idu_size                           INTEGER,
   o  has_SE_protection                  BOOLEAN,
   o  has_EV_protection                  BOOLEAN,
   o  PIDU_Information                   PARAMETER BUNDLE,
   o  nr_policy                          OBJECT IDENTIFIER,
      -- this and subsequent parameters pertain only to evidence tokens
   o  Nr_Options                         PARAMETER BUNDLE,
   o  Originator_Information             PARAMETER BUNDLE,
   o  time_stamping_time                 INTEGER  OPTIONAL
   o  Request_Features                   PARAMETER BUNDLE,
      -- describes the included request, if any.
   o  requested_evidence_back            BOOLEAN,
      -- true if this is an evidence generated in response to a
      -- previously-sent request
   o  evidence_check                     OCTET STRING,
      -- meaningful if the boolean above is true

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- input_token could be parsed for all relevant fields.
   o  GSS_S_CREDENTIALS_EXPIRED
   o  GSS_S_DEFECTIVE_TOKEN
      -- the mechanism type could be parsed, but either the other fields
      -- could not be determined from the input_token, or their values
      -- did not correspond to valid values for that mechanism.
   o  GSS_S_FAILURE
      -- the mechanism type was missing or corrupted.

   IDUP_Get_token_details() is used to return to an application the
   attributes that correspond to a given input token.  Since IDUP-GSS-
   API tokens are meant to be opaque to the calling application, this
   function allows the application to determine information about the
   token without having to violate the opaqueness intention of IDUP. Of
   primary importance is the mechanism type, which the application can
   then use as input to the IDUP_Establish_Env() call in order to
   establish the correct environment in which to have the token
   processed.





Adams                        Informational                     [Page 51]

RFC 2479                      IDUP-GSS-API                 December 1998


   If all tokens are framed as suggested in Section 3.1 of [RFC-2078]
   (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM
   GSS Mechanism [RFC 2025]), then any mechanism implementation should
   be able to return the mech_type parameter for any uncorrupted input
   token. If the mechanism implementation whose IDUP_Get_token_details()
   function is being called does recognize the token, it can return any
   further relevant information in the other token attributes, as
   specified.  In particular, this function can set has_SE_protection if
   the SE calls may be used to unprotect it, or has_EV_protection if the
   EV calls may be used to unprotect it, or both if both kinds of
   protection have been applied (so that SE or EV calls may be used in
   any order for unprotection) [note that GP calls, when supported,
   should be usable for unprotection of any IDUP token].

   IDUP_Get_token_details (which need not be supported by all underlying
   mechanisms or implementations) gives only a hint about the content of
   the token, there is no integrity check of any kind performed.
   Regardless of the token type, it is possible to check that this
   information is correct only by doing a proper unprotection of the
   token.  It is recommended that IDUP callers supply a token buffer at
   least 4 KB in length in order to ensure that the desired data can
   easily flow across this interface.

   The OID of the mechanism and whether the token contains the
   associated data is returned. In addition the size of the associated
   data, whether inside or outside the token, is included if known.
   [Note:  data size will typically be unknown if the data was protected
   using multibuffer calls.  A value of "-1" may be used to indicate
   "UNKNOWN".]

   When the input token contains only an evidence generated
   spontaneously, the following is returned:
    - the evidence type;
    - the Non-Repudiation policy under which the evidence was generated;
    - the name of the generator of the evidence;
    - the date and time when the evidence was generated (if available);
    - the date and time when it was time stamped (if available).

   When the input token contains only an evidence generated in response
   to  a request from another entity, the following additional
   information is returned:
    - an indicator to state that this evidence relates to a request;
    - a string significant for the requester that will allow him to
      check whether the answer corresponds to the requested evidence.

   When the input token only contains a request, the following is
   returned:
    - the name of the requestor of the evidence,



Adams                        Informational                     [Page 52]

RFC 2479                      IDUP-GSS-API                 December 1998


    - the date and time when the request was made,
    - the evidence type to send back,
    - the non-repudiation policy under which the evidence to send back
      should be generated,
    - the names of the recipients which should generate and distribute
      the requested evidence,
    - the names of the recipients to whom the requested evidence should
      be sent after it has been generated.

   When the input token contains both evidence and a request, an
   indicator is returned describing whether the new evidence should be
   generated using only the data in the input token, or using both the
   data and the evidence in the input token.

   When the input token contains only CONF and DOA services, the
   PIDU_Information bundle is returned.  Other relevant parameters (such
   as idu_size and time_stamping_time) may also be returned if this data
   is available.

2.5.4. IDUP_Get_policy_info call

   Inputs:
   o  policy_id OBJECT IDENTIFIER

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  policy_version INTEGER,
   o  policy_effective_time INTEGER,
   o  policy_expiry_time INTEGER,
   o  supported_services SET OF Service_Descriptor,
      -- services supported by this particular policy_id (equal to the
      -- intersection of the services supported by the mechanisms
      -- listed in supported_mechanisms)
   o  supported_mechanisms SET OF Mechanism_Descriptor
      -- mechanisms supported by this particular policy_id

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- policy_id recognized; all relevant fields have been returned.
   o  GSS_S_FAILURE
      -- the policy_id was not recognized.

   This call (which need not be supported by all underlying mechanisms
   or implementations) allows the application to retrieve information
   pertaining to a given policy_id.  Policies define the following:
      -  rules for the protection of IDUs, such as trusted third
         parties which may be involved in P-IDU generation, the roles in



Adams                        Informational                     [Page 53]

RFC 2479                      IDUP-GSS-API                 December 1998


         which they may be involved, and the duration for which the
         generated P-IDU is valid;

      -  rules for the unprotection of P-IDUs, such as the interval
         during which a trusted third party may legitimately declare its
         key to have been compromised or revoked; and

      -  rules for adjudication, such as which authorities may be used
         to adjudicate disputes.

   The policy itself may be used by an adjudicator when resolving a
   dispute.  For example, the adjudicator might refer to the policy to
   determine whether the rules for generation of the P-IDU have been
   followed.

   The following parameter bundles are associated with this call.

      o  Service_Descriptor PARAMETER BUNDLE,
         o  service_type OBJECT IDENTIFIER,
         o  service_validity_duration INTEGER,
         o  must_use_trusted_time BOOLEAN

      o  Mechanism_Descriptor PARAMETER BUNDLE,
         o  mechanism_type OBJECT IDENTIFIER,
         o  Authority_List PARAMETER BUNDLE,
         o  maximum_time_skew INTEGER
            -- maximum permissible difference between P-IDU generation
            -- time and the time of countersignature from a time
            -- service (if required).  This parameter is unused if
            -- trusted time is not required.

      o  Authority_List PARAMETER BUNDLE,
         o  authority_name INTERNAL NAME,
         o  authority_role OCTET STRING,
         o  last_revocation_check_offset INTEGER
            -- may be 0, greater than 0, or less than 0.  The value of
            -- this parameter is added to P-IDU generation time to
            -- get latest time at which the mechanism will check to
            -- see if this authority's key has been revoked.

   An example of the use of the last parameter in Authority_List is as
   follows.  If an authority has a defined last_revocation_check_offset
   of negative one hour, then all revocations taking effect earlier than
   one hour before the generation of a P-IDU will render that P-IDU
   invalid; no revocation taking place later than one hour before the
   generation of the P-IDU will affect the P-IDU's validity.





Adams                        Informational                     [Page 54]

RFC 2479                      IDUP-GSS-API                 December 1998


   Note that both the maximum_time_skew and the
   last_revocation_check_offset values are given in minutes.

2.5.5. IDUP_Cancel_multibuffer_op call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- operation cancelled; state purged.
   o  GSS_S_FAILURE
      -- unable to cancel operation; state retained.

   This call (which need not be supported by all underlying mechanisms
   or implementations) allows the application to cancel a multibuffer
   operation prior to normal completion (e.g., subsequent to calling
   Start_operation and zero or more Process_operation, but prior to
   calling End_operation).  When successful, this call purges any
   internal state information which would have been used to continue
   processing for the full set of multibuffer calls.

3.  Related Activities

   In order to implement the IDUP-GSS-API atop existing, emerging, and
   future security mechanisms, the following is necessary:

    - object identifiers must be assigned to candidate IDUP-GSS-API
      mechanisms and the name types which they support; and

    - concrete data element (i.e., token and parameter bundle) formats
      must be defined for candidate mechanisms.

   Calling applications must implement formatting conventions which will
   enable them to distinguish IDUP-GSS-API P-IDUs from other IDUs in
   their environment.

   Concrete language bindings are required for the programming
   environments in which the IDUP-GSS-API is to be employed.








Adams                        Informational                     [Page 55]

RFC 2479                      IDUP-GSS-API                 December 1998


4.  Acknowledgments

   Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust
   Technologies, Denis Pinkas of Bull, and David Kurn of Tandem
   Computers for a number of helpful comments and contributions.

5. Security Considerations

   Security issues are discussed throughout this memo.

6. REFERENCES

   [MSP]       U.S. National Security Agency, "Message Security
               Protocol", Secure Data Network System SDN.701, March
               1994.

   [RFC-1421]  Linn, J., "Privacy Enhancement for Internet Electronic
               Mail:  Part I: Message Encryption and Authentication
               Procedures", RFC 1421, February 1993.

   [RFC-2078]  Linn, J., "Generic Security Service Application Program
               Interface, Version 2", RFC 2078, January 1997..

   [RFC 1964]  Linn, J, "The Kerberos Version 5 GSS-API Mechanism", RFC
               1964, June 1996.

   [RFC 2025]  Adams, C., "The Simple Public-Key GSS-API Mechanism
               (SPKM)", RFC 2025, October 1996.

   [ISO/IEC]   2nd ISO/IEC CD 13888-1, "Information technology -
               Security techniques - Non-repudiation - Part 1:  General
               Model", ISO/IEC JTC 1/SC 27, May 30, 1995

7. Author's Address

   Carlisle Adams
   Entrust Technologies
   750 Heron Road, Suite E08,
   Ottawa, Ontario, CANADA  K1V 1A7

   Phone:  +1 613.247.3180
   EMail: cadams@entrust.com









Adams                        Informational                     [Page 56]

RFC 2479                      IDUP-GSS-API                 December 1998


APPENDIX  A:  MECHANISM-INDEPENDENT TOKEN FORMAT

   This appendix specifies the use, for IDUP-GSS-API tokens, of the
   mechanism-independent level of encapsulating representation for
   tokens given in Section 3.1 of GSS-API [RFC-2078].  The
   representation given there incorporates an identifier of the
   mechanism type to be used when processing the associated tokens. Use
   of that octet format is recommended to the designers of IDUP-GSS-API
   implementations based on various mechanisms so that tokens can be
   interpreted unambiguously at IDUP-GSS-API peers. It is recognized,
   however, that for interoperability purposes with peers not using IDUP
   for specific IDU protection/unprotection protocols, the encapsulating
   representation may need to be omitted.  (In such a case it is
   necessary that the underlying mechanism provides some sort of
   internal or external identification that allows it to recognize its
   own tokens.)  When the mechanism-independent level of encapsulating
   representation is not desired, callers SHOULD set
   mech_indep_encap_req to FALSE (note that some underlying mechanisms
   may default this parameter to FALSE).

   For purely descriptive purposes, the following simple ASN.1 structure
   is used to illustrate the structural relationships among token and
   tag objects.  For interoperability purposes, token and tag encoding
   shall be performed using the concrete encoding procedures described
   in Section 3.1 of GSS-API [RFC-2078].

          -- top-level token definition to frame different mechanisms

          IDUP-GSS-API DEFINITIONS ::=
          BEGIN
          MechType ::= OBJECT IDENTIFIER

          Token ::= [APPLICATION 0] IMPLICIT SEQUENCE {
                  thisMech MechType,
                  token ANY DEFINED BY thisMech
                     -- contents mechanism-specific
                  }
          END













Adams                        Informational                     [Page 57]

RFC 2479                      IDUP-GSS-API                 December 1998


APPENDIX  B:  EXAMPLES OF IDUP USE

   This appendix provides examples of the use of IDUP to do IDU
   protection and unprotection.  It should not be regarded as
   constrictive to implementations or as defining the only means through
   which IDUP-GSS-API functions can be realized with particular
   underlying technology, and does not demonstrate all IDUP-GSS-API
   features.

   Most of the examples below only illustrate the use of CONF/DOA
   protection services.  Note that when both CONF/DOA and Evidence
   services are required, calling applications may use a series of SE
   and EV calls, or may use the GP calls (when these are supported).
   Using the former approach implies multiple calls (e.g., the SE calls
   are used to protect some data and the resulting token is then input
   to the EV calls to add evidence information), but some callers may
   find this to be more attractive than coding to the GP calls because
   of the simpler SE/EV interface.  Depending upon the underlying
   mechanism, the series of SE/EV calls may result in a single token
   that can be unprotected using the SE and EV calls in any order (for
   example, because it is a single ASN.1 SEQUENCE that incorporates all
   the specified protection services at one level), or the series may
   result in a token that can only be unprotected in the reverse order
   of protection (for example, because each SE/EV output token was
   effectively embedded in the token of the subsequent call). The
   IDUP_Get_token_details call can assist callers in determining how to
   unprotect any received token.

B.1.  Simple Mechanism, Single Buffer

   To illustrate the simplest possible case, consider an underlying IDUP
   mechanism which does straightforward encryption/decryption and
   signing/verification only using public-key techniques; none of the
   other possible services, such as creation of proof-of-origin
   evidence, requests for proof-of-delivery evidence, or use of trusted
   time, are supported.  PEM[RFC-1421] is one example of a mechanism
   which fits this description.  Furthermore (again for simplicity),
   assume that encapsulation is chosen by the calling application during
   IDU protection.

   Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls.
   The following parameter bundle uses and defaults would therefore be
   specified in the relevant IDUP mechanism document.








Adams                        Informational                     [Page 58]

RFC 2479                      IDUP-GSS-API                 December 1998


   SENDER:

   Set
      env_handle                = environment handle in use;
      idu_buffer                = data buffer;
      Target_Info.targ_names    = receiver names;
      Protect_Options           = as necessary;

   Call
      IDUP_SE_SingleBuffer_Protect() with above input parameters

   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         Target_Info.Bad_Targ_Name,
      (as required) for more detailed information.

   Send
      Output parameter pidu_buffer to receiver.

   RECEIVER (any parameters not listed below are given the value NULL):

   Set
      env_handle         = environment handle in use;
      pidu_buffer        = received data buffer;

   Call
      IDUP_SE_SingleBuffer_Unprotect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
      (as required) for more detailed information

   Utilize
      PIDU_Information.Protect_Options.Protect_Operation,
         (to determine which services were applied by the originator)
      PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg,
         (to determine the corresponding qualities of the services)
      Prot_Information.originator_name,
         (to determine the name of the originator)
      Prot_Information.protection_time,
         (to determine when the IDU was protected)
      idu_buffer
         (to retrieve the unprotected data).







Adams                        Informational                     [Page 59]

RFC 2479                      IDUP-GSS-API                 December 1998


B.2.  Simple Mechanism, Single Buffer (Again)

   To illustrate a slight variation on the simplest possible case,
   assume that everything is as in the previous scenario except that the
   "GP" calls are used.

   The following parameter bundle uses and defaults would therefore be
   specified in the relevant IDUP mechanism document.

   Mech_Specific_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Idu_Sensitivity
      - NOT USED (the only acceptable input, therefore, is NULL)

   Service_Creation_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Service_Verification_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Quality
      - the qop_algs parameter must be supported, with a suitable
        DEFAULT value specified;
      - suitable DEFAULT values for validity, policy_id, and
        allow_policy_mapping must be specified (it may be an
        implementation option as to whether these parameters are
        explicitly modifiable by the calling application, or whether
        NULLs are the only acceptable input)

    Idu_Information
      - the idu_type parameter must have a value representing a suitable
        IDU type (for example, in PEM a value representing the string
        "RFC822" or some other valid "Content-Domain" would be used),
        with a suitable DEFAULT value specified;
      - the idu_title parameter is NOT USED (the only acceptable input,
        therefore, is NULL)

   Prot_Information
      - the originator_name and idu_type (in Idu_Information) parameters
        are read from the encapsulating information and output by
        IDUP_Start_Unprotect;
      - all other parameters are NOT USED (and therefore NULL)

   Special_Conditions
      - NOT USED (the only acceptable input, therefore, is NULL)





Adams                        Informational                     [Page 60]

RFC 2479                      IDUP-GSS-API                 December 1998


   Target_Info
      - this bundle is used as described in IDUP; no DEFAULT values are
        specified

   General_Service_Data
      - the unencapsulated_token parameter is used if
        encapsulation_request is FALSE;
      - the minor_status parameter is used to return minor status values
        as specified by the mechanism document

   Prot_Service
      - the prot_service_type parameter may have a value of "1"
        ("perform unsolicited service") or NULL (which specifies the
        DEFAULT value of "1");
      - the service_id parameter must have a value representing
        "PER_CONF" or "PER_DOA";
      - the parameters Service_Creation_Info, service_to,
        Service_Verification_Info, and service_verification_info_id are
        NOT USED (and therefore NULL)

   Unprot_Service
      - the unprot_service_type parameter will always have a value of
        "1" ("receive unsolicited service");
      - the service_id parameter will have a value representing
        "REC_CONF" or "REC_DOA";
      - the parameters service_verification_info_id,
        Service_Verification_Info, service_to, and
        Service_Creation_Info, are NOT USED (and therefore NULL)

   Assuming that the calling application has only a single buffer of
   data to protect/unprotect, the following sequence of operations must
   be performed by the sender and receivers (subsequent to environment
   establishment).

   SENDER (any parameters not listed below are given the value NULL):

   Set
      env_handle                           = environment handle in use;
      encapsulation_request                = TRUE;
      single_idu_buffer                    = data buffer;
      Target_Info.targ_names               = receiver names;
      P_Services.Prot_Service_1.service_id = PER_CONF;
      P_Services.Prot_Service_2.service_id = PER_DOA;

   Call
      IDUP_Start_Protect() with above input parameters





Adams                        Informational                     [Page 61]

RFC 2479                      IDUP-GSS-API                 December 1998


   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         Target_Info.bad_targ_names / Target_Info.bad_targ_status,
         P_Services.Prot_Service_1.General_Service_Data.minor_status,
         P_Services.Prot_Service_2.General_Service_Data.minor_status
      (as required) for more detailed information.

   Send
      Output parameter pidu_buffer to receiver.


   RECEIVER (any parameters not listed below are given the value NULL):

   Set
      env_handle         = environment handle in use;
      single_pidu_buffer = received data buffer;

   Call
      IDUP_Start_Unprotect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
         R_Services.Unprot_Service_2.General_Service_Data.minor_status
      (as required) for more detailed information

   Utilize
      R_Services.Unprot_Service_1/2.service_id,
         (to determine which services were applied by the originator)
      R_Services.Unprot_Service_1/2.Quality,
         (to determine the corresponding qualities of the services)
      Prot_Information.originator_name,
         (to determine the name of the originator)
      single_idu_buffer
         (to retrieve the unprotected data).

B.3.  Simple Mechanism, Multiple Buffers

   To illustrate the next step up in complexity, consider the use of the
   simple IDUP mechanism described in B.2 above with multiple data
   buffers.  In particular, consider the case in which a large data file
   is to be signed.  For this example, assume that the calling
   application does not wish to use encapsulation.

   Note that the parameter bundle uses and defaults are as specified in
   B.2. above.




Adams                        Informational                     [Page 62]

RFC 2479                      IDUP-GSS-API                 December 1998


   SENDER (any parameters not listed below are given the value NULL):

   Set
      env_handle                           = environment handle in use;
      encapsulation_request                = FALSE;
      P_Services.Prot_Service.service_id   = PER_DOA;

   Call
      IDUP_Start_Protect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         P_Services.Prot_Service.General_Service_Data.minor_status
      (as required) for more detailed information.

   For each buffer of input data:
      Set
         input_buffer = buffer
      Call
         IDUP_Protect() with above input parameter
      Check
         major_status.  If not GSS_S_COMPLETE, check
            minor_status

   Call
      IDUP_End_Protect()
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         P_Services.Prot_Service.General_Service_Data.minor_status
      (as required) for more detailed information.

   Send
      P_Services.Prot_Service.General_Service_Data.unencapsulated_token,
      and the file for which the signature was calculated (if required),
      to receiver.

   RECEIVER (any parameters not listed below are given the value NULL):

   Set
      env_handle            = environment handle in use;
      R_Services.Unprot_Service_1.General_Service_Data.
      unencapsulated_token  = received unencapsulated token;

   Call
      IDUP_Start_Unprotect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check



Adams                        Informational                     [Page 63]

RFC 2479                      IDUP-GSS-API                 December 1998


         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
      (as required) for more detailed information

   For each buffer of input data:
      Set
         input_buffer = buffer
      Call
         IDUP_Unprotect() with above input parameter
      Check
         major_status.  If not GSS_S_COMPLETE, check
            minor_status

   Call
      IDUP_End_Unprotect()
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
      (as required) for more detailed information.

   Utilize
      R_Services.Unprot_Service_1.service_id,
         (to determine which service was applied by the originator; note
          that Unprot_Service_2 will have NULL in unprot_service_type
          to indicate that it is not used)
      R_Services.Unprot_Service_1.Quality,
         (to determine the corresponding quality of the service)
      Prot_Information.originator_name, (from IDUP_Start_Unprotect)
         (to determine the name of the signer)
      major_status (from IDUP_End_Unprotect)
         (to determine pass/fail status of signature verification).

B.4.  More Sophisticated Mechanism, Small Application Buffers

   To illustrate a higher level of complexity, consider the use of a
   more sophisticated IDUP mechanism and a calling application with
   small data buffers.  In particular, consider the case in which a very
   small e-mail message is to be encrypted for a relatively large
   receiver list (R), some subset of whom (r) will be asked to send
   proofs of receipt of the message to some other subset (L) (which
   includes the originator).  So that the example is not unnecessarily
   complicated, assume again that the originating application uses
   encapsulation.

   The uses and defaults for the various parameter bundles for this
   mechanism would be specified in the relevant IDUP mechanism document
   as follows.



Adams                        Informational                     [Page 64]

RFC 2479                      IDUP-GSS-API                 December 1998


   Mech_Specific_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Idu_Sensitivity
      - NOT USED (the only acceptable input, therefore, is NULL)

   Service_Creation_Info
      - used to create "proof of delivery" evidence (but actual
        structure is opaque to calling application)

   Service_Verification_Info
      - used to verify "proof of delivery" evidence (but actual
        structure is opaque to calling application)

   Quality
      - the qop_algs parameter must be supported, with a suitable
        DEFAULT value specified;
      - suitable DEFAULT values for validity, policy_id, and
        allow_policy_mapping must be specified (it may be an
        implementation option as to whether these parameters are
        explicitly modifiable by the calling application, or whether
        NULLs are the only acceptable input)

   Idu_Information
      - the idu_type parameter must have a value representing a suitable
        IDU type, with a suitable DEFAULT value specified;
      - the idu_title parameter must have a value representing a
        suitable IDU title, with a suitable DEFAULT value specified

   Prot_Information
      - the originator_name, protection_time, and idu_type / idu_title
        (in Idu_Information) parameters are read from the contained
        header information and output by IDUP_Start_Unprotect;

   Special_Conditions
      - the parameter prot_oper_id is NOT USED (the only acceptable
        input, therefore, is NULL);
      - trusted or untrusted time may be selected by the calling
        application, with a suitable DEFAULT value specified

   Target_Info
      - this bundle is used as described in IDUP; no DEFAULT values are
        specified

   General_Service_Data
      - the unencapsulated_token parameter is used if
        encapsulation_request is FALSE;
      - the minor_status parameter is used to return minor status values



Adams                        Informational                     [Page 65]

RFC 2479                      IDUP-GSS-API                 December 1998


        as specified by the mechanism document

   Prot_Service
      - the prot_service_type parameter may have a value of "1"
        ("perform unsolicited service"), "2" ("perform solicited
        service"), "3" (perform service solicitation), or NULL (which
        specifies the DEFAULT value of "1");
      - the service_id parameter must have a value representing
        "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD";
      - the parameters Service_Creation_Info, service_to,
        Service_Verification_Info, and service_verification_info_id are
        used when required by the IDUP operation

   Unprot_Service
      - the unprot_service_type parameter may have a value of "1"
        ("receive unsolicited service"), "2" ("receive solicited
        service"), or "3" (receive service solicitation);
      - the service_id parameter will have a value representing
        "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD";
      - the parameters service_verification_info_id,
        Service_Verification_Info, service_to, and
        Service_Creation_Info, are used when required by the IDUP
        operation


   SENDER (any parameters not listed below are given the value NULL):

   Set
      env_handle                          = environment handle in use;
      Idu_Information.idu_type            = value for "e-mail document";
      Idu_Information.idu_title           = "Contract 1234";
      Special_Conditions.use_trusted_time = TRUE;
      encapsulation_request               = TRUE;
      single_idu_buffer                   = very small e-mail message;
      Target_Info.targ_names              = receiver names (R);
      Prot_Service_1.prot_service_type    = "1";
      Prot_Service_1.service_id           = PER_CONF;
      Prot_Service_2.prot_service_type    = "3";
      Prot_Service_2.service_id           = PER_POD;
      Prot_Service_2.General_Service_Data.Target_Info.targ_names
                                          = "receipts from" list (r);
      Prot_Service_2.service_to           = "receipts to" list (L);
      P_Services.Prot_Service_1           = Prot_Service_1;
      P_Services.Prot_Service_2           = Prot_Service_2;

   Call
      IDUP_Start_Protect() with above input parameters




Adams                        Informational                     [Page 66]

RFC 2479                      IDUP-GSS-API                 December 1998


   Check
      major_status.  If not GSS_S_COMPLETE,
         while major_status == IDUP_S_MORE_OUTBUFFER_NEEDED
            Save
               pidu_buffer,
            Call
               IDUP_Start_Protect() (to get next portion of pidu_buffer)
         Check
            major_status,
            minor_status,
            Target_Info.bad_targ_names / Target_Info.bad_targ_status,
            P_Services.Prot_Service_1.General_Service_Data.minor_status,
            P_Services.Prot_Service_2.General_Service_Data.minor_status
         (as required) for more detailed information.

   Save
      Prot_Service_2.Service_Verification_Info,
      Prot_Service_2.service_verification_info_id

   Send
      All saved buffers of pidu_buffer to receiver list (R).


   RECEIVER (ON RECEIVER LIST (R)):
      (any parameters not listed below are given the value NULL)

   Set
      env_handle          = environment handle in use;
      partial_pidu_buffer = initial buffer of received p-idu;

   Call
      IDUP_Start_Unprotect() with above input parameters
   While major_status == IDUP_S_MORE_PIDU_NEEDED,
      Set
         partial_pidu_buffer = next buffer of p-idu
      Call
         IDUP_Start_Unprotect()
   Check
      major_status,
      minor_status,
      R_Services.Unprot_Service_1.General_Service_Data.minor_status,
      R_Services.Unprot_Service_2.General_Service_Data.minor_status,
   (as required) for more detailed information

   Save
      initial_idu_buffer (if non-empty)





Adams                        Informational                     [Page 67]

RFC 2479                      IDUP-GSS-API                 December 1998


   Set
      input_buffer = remaining p-idu buffer
   Call
      IDUP_Unprotect() with above input parameter
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status
   Save
      output_buffer

   Call
      IDUP_End_Unprotect()
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
         R_Services.Unprot_Service_2.General_Service_Data.minor_status,
      (as required) for more detailed information.

   Utilize
      R_Services.Unprot_Service_1/2.service_id,
         (to determine which services were applied by the originator)
      R_Services.Unprot_Service_1/2.Quality,
         (to determine the corresponding qualities of the service)
      Prot_Information.originator_name/protection_time and
         Prot_Information.Idu_Information.idu_type/idu_title,
         (from IDUP_Start_Unprotect) (to determine originator info.)
      R_Services.Unprot_Service_2.General_Service_Data.Target_Info.
         targ.names, (to determine if rec. is in "receipts from" (r))
      Service_Verification_Info/service_verification_info_id
         (to determine if receiver is in "receipts to" list (L))

   If receiver is in "receipts from" list (r)
      Save
         R_Services.Unprot_Service_2.service_to,
         R_Services.Unprot_Service_2.Service_Creation_Info

   If receiver is in "receipts to" list (L)
      Save
         Service_Verification_Info,
         service_verification_info_id

   RECEIVER (ON "RECEIPTS FROM" LIST (r)):
      (procedure to generate receipt)

   Set
      env_handle                           = environment handle in use;
      Target_Info.targ_names               = service_to



Adams                        Informational                     [Page 68]

RFC 2479                      IDUP-GSS-API                 December 1998


      Prot_Service_1.prot_service_type     = "2";
      Prot_Service_1.service_id            = "PER_POD";
      Prot_Service_1.Service_Creation_Info = Service_Creation_Info;
      P_Services.Prot_Service_1            = Prot_Service_1

   Call
      IDUP_Start_Protect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         P_Services.Prot_Service_1.General_Service_Data.minor_status
      (as required) for more detailed information.

   Send
      pidu_buffer to "receipts to" list (L)

   RECEIVER (ON "RECEIPTS TO" LIST (L)):
      (procedure to process received receipt)

   Set
      env_handle         = environment handle in use;
      single_pidu_buffer = received p-idu buffer (if it fits in a single
         buffer; otherwise use partial_pidu_buffer and make multiple
         calls, as above)

   Call
      IDUP_Start_Unprotect() with above input parameters
   If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED
      Utilize
         R_Services.Unprot_Service_1.service_verification_info.id
         (to assist in locating necessary Service_Verification_Info)
      Set
         R_Services.Unprot_Service_1.Service_Verification_Info
            = Service_Verification_Info
      Call
         IDUP_Start_Unprotect() with above input parameters
   Check
      major_status,
      minor_status,
      R_Services.Unprot_Service_1.General_Service_Data.minor_status
   (as required) for more detailed information.

   Utilize
      R_Services.Unprot_Service_1.service_id,
         (to determine that this is a "proof of delivery" evidence)
      R_Services.Unprot_Service_1.Quality,
      Prot_Information.originator_name, (for evidence generator info.)
      major_status (to determine pass/fail status of evi. verif.).



Adams                        Informational                     [Page 69]

RFC 2479                      IDUP-GSS-API                 December 1998


Full Copyright Statement

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Adams                        Informational                     [Page 70]