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
|
\documentstyle[12pt,fullpage,changebar,rcsid]{article}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Make _ actually generate an _, and allow line-breaking after it.
\let\underscore=\_
\catcode`_=13
\def_{\underscore\penalty75\relax}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\rcs$Id$
\setlength{\parskip}{.7\baselineskip}
\setlength{\parindent}{0pt}
\def\v#1{\verb+#1+}
\title{Kerberos Administration System \\
KADM5 API Functional Specifications\thanks{\rcsId}}
\author{Barry Jaspan}
\begin{document}
\sloppy
\maketitle
{\setlength{\parskip}{0pt}\tableofcontents}
\section{Introduction}
This document describes the Admin API that can be used to maintain
principals and policies. It describes the data structures used for
each function and the interpretation of each data type field, the
semantics of each API function, and the possible return codes.
The Admin API is intended to be used by remote clients using an RPC
interface. It is implemented by the admin server running on the
Kerberos master server. It is also possible for a program running on
the Kerberos master server to use the Admin API directly, without
going through the admin server.
\section{Versions of the API}
The versions of this API and a brief description of the changes for
each are:
\begin{description}
\item[KADM5_API_VERSION_1] The initial version of this API, written by
OpenVision Technologies and donated to MIT for including in the public
release. Originally called OVSEC_KADM_API_VERSION_1. Most everything
has been renamed in one way or another, including functions, header
files, and data structures. Where possible, the old OVSEC_KADM names
have been left behind for compatibility with version 1, and
KADM5_API_VERSION_1 is compatible with OVSEC_KADM_API_VERSION_1 at
compile-, link-, and run-time.
The OVSEC_KADM name compatibility will not be extended to new
functionality in future versions because no existing OVSEC_KADM
clients will use that functionality; new clients should be written to
the KADM5 API.
\item[KADM5_API_VERSION_2] This version contains the initial changes
necessary to make the OpenVision administration system work with the
mid-1996 MIT version of Kerberos 5. Changes include
\begin{enumerate}
\item The kadm5_init functions now take a structure of parameters
instead of just a realm name, allowing the calling program to specify
non-default values for various configuration options. See section
\ref{sec:configparams} for details.
\item The KADM5 API has been extended to support new features of the
Kerberos database, including multiple encryption and salt types per
principal. See section \ref{sec:keys} for details.
\item kadm5_get_principal now allows a principal's keys to be
retrieved {\it by local clients only}. This is necessary in order for
the kadm5 API to provide the primary Kerberos database interface.
\item The KADM5 authorization system has been completely changed.
\item The functions kadm5_flush, kadm5_get_principals, and
kadm5_get_policies have been added.
\item The KADM5 API now obeys a caller-allocates rather than
callee-allocates system. kadm5_get_principal and kadm5_get_policy are
affected.
\end{enumerate}
\end{description}
\section{Policies and Password Quality}
The Admin API Password Quality mechanism provides the following
controls. Note that two strings are defined to be ``significantly
different'' if they differ by at least one character. The compare is not
case sensitive.
\begin{itemize}
\item A minimum length can be required; a password with
fewer than the specified number of characters will not be accepted.
\item A minimum number of character classes can be required; a
password that does not contain at least one character from at least
the specified number of character classes will not be accepted. The
character classes are defined by islower(), isupper(), isdigit(),
ispunct(), and other.
\item Passwords can be required to be different from
previous passwords; a password that generates the same encryption key
as any of the principal's specified previous number of passwords will
not be accepted. This comparison is performed on the encryption keys
generated from the passwords, not on the passwords themselves.
\item A single ``forbidden password'' dictionary can be specified for all
users; a password that is not significantly different from every word
in the dictionary will not be accepted.
\end{itemize}
\section{Data Structures}
This section describes the data structures used by the Admin API.
They are defined in $<$kadm5/admin.h$>$.
\subsection{Principals, kadm5_principal_ent_t}
\label{sec:principal-structure}
A Kerberos principal entry is represented by a kadm5_principal_ent_t.
It contains a subset of the information stored in the master Kerberos
database as well as the additional information maintained by the admin
system. In the current version, the only additional information is
the principal's policy and the aux_attributes flags.
The principal may or may not have a policy enforced on it. If the
POLICY bit (see section \ref{sec:masks}) is set in aux_attributes, the
policy field names the principal's policy. If the POLICY bit is not
set in aux_attributes, no policy is enforced on the principal and the
value of the policy field is undefined.
\begin{figure}[htbp]
\begin{verbatim}
typedef struct _kadm5_principal_ent_t {
krb5_principal principal;
krb5_timestamp princ_expire_time;
krb5_timestamp last_pwd_change;
krb5_timestamp pw_expiration;
krb5_deltat max_life;
krb5_principal mod_name;
krb5_timestamp mod_date;
krb5_flags attributes;
krb5_kvno kvno;
krb5_kvno mkvno;
char * policy;
u_int32 aux_attributes;
krb5_deltat max_renewable_life;
krb5_timestamp last_success;
krb5_timestamp last_failed;
krb5_kvno fail_auth_count;
krb5_int16 n_key_data;
krb5_int16 n_tl_data;
krb5_tl_data *tl_data;
krb5_key_data *key_data;
} kadm5_principal_ent_rec, *kadm5_principal_ent_t;
\end{verbatim}
\caption{Definition of kadm5_principal_ent_t.}
\label{fig:princ-t}
\end{figure}
The fields of an kadm5_principal_ent_t are interpreted as
follows.
\begin{description}
\item[principal] The name of the principal; must conform to Kerberos
naming specifications.
\item[princ_expire_time] The expire time of the principal as a Kerberos
timestamp. No Kerberos tickets will be issued for a principal after
its expire time.
\item[last_pwd_change] The time this principal's password was last
changed, as a Kerberos timestamp.
\item[pw_expiration] The expire time of the user's current password, as a
Kerberos timestamp. No application service tickets will be issued for the
principal once the password expire time has passed. Note that the user can
only obtain tickets for services that have the PW_CHANGE_SERVICE bit set in
the attributes field.
\item[max_life] The maximum lifetime of any Kerberos ticket issued to
this principal.
\item[attributes] A bitfield of attributes for use by the KDC. The
symbols and constant values are defined below; their interpretation
appears in the libkdb functional specification.
\begin{tabular}{clr}
{\bf Name} & {\bf Value} \\
KRB5_KDB_DISALLOW_POSTDATED & 0x00000001 \\
KRB5_KDB_DISALLOW_FORWARDABLE & 0x00000002 \\
KRB5_KDB_DISALLOW_TGT_BASED & 0x00000004 \\
KRB5_KDB_DISALLOW_RENEWABLE & 0x00000008 \\
KRB5_KDB_DISALLOW_PROXIABLE & 0x00000010 \\
KRB5_KDB_DISALLOW_DUP_SKEY & 0x00000020 \\
KRB5_KDB_DISALLOW_ALL_TIX & 0x00000040 \\
KRB5_KDB_REQUIRES_PRE_AUTH & 0x00000080 \\
KRB5_KDB_REQUIRES_HW_AUTH & 0x00000100 \\
KRB5_KDB_REQUIRES_PWCHANGE & 0x00000200 \\
KRB5_KDB_DISALLOW_SVR & 0x00001000 \\
KRB5_KDB_PWCHANGE_SERVICE & 0x00002000 \\
KRB5_KDB_SUPPORT_DESMD5 & 0x00004000 \\
KRB5_KDB_NEW_PRINC & 0x00008000
\end{tabular}
\item[mod_name] The name of the Kerberos principal that most recently
modified this principal.
\item[mod_date] The time this principal was last modified, as a Kerberos
timestamp.
\item[kvno] The version of the principal's current key.
\item[mkvno] The version of the Kerberos Master Key in effect when
this principal's key was last changed. In KADM5_API_VERSION_2, this
field is always zero.
\item[policy] If the POLICY bit is set in aux_attributes, the name
of the policy controlling this principal.
\item[aux_attributes] A bitfield of flags for use by the
administration system. Currently, the only valid flag is POLICY, and
it indicates whether or not the principal has a policy enforced on it.
\item[max_renewable_life] The maximum renewable lifetime of any
Kerberos ticket issued to or for this principal. This field only
exists in KADM5_API_VERSION_2.
\item[last_success] The KDC time of the last successful AS_REQ. This
is only updated if KRBCONF_KDC_MODIFIES_KDB is defined during
compilation of the KDC. This field only exists in
KADM5_API_VERSION_2.
\item[last_failed] The KDC time of the last failed AS_REQ. This is
only updated if KRBCONF_KDC_MODIFIES_KDB is defined during compilation
of the KDC. This field only exists in KADM5_API_VERSION_2.
\item[fail_auth_count] The number of consecutive failed AS_REQs. When
this number reaches KRB5_MAX_FAIL_COUNT, the KRB5_KDC_DISALLOW_ALL_TIX
is set on the principal. This is only updated if
KRBCONF_KDC_MODIFIES_KDB is defined during compilation. This field
only exists in KADM5_API_VERSION_2.
\item[n_tl_data] The number of elements in the \v{tl_data} linked
list. This field only exists in KADM5_API_VERSION_2.
\item[n_key_data] The number of elements in the \v{key_data}
array. This field only exists in KADM5_API_VERSION_2.
\item[tl_data] A linked list of tagged data. This list is a mechanism
by which programs can store extended information in a principal entry,
without having to modify the database API. Each element is of type
krb5_tl_data:
\begin{verbatim}
typedef struct _krb5_tl_data {
struct _krb5_tl_data* tl_data_next;
krb5_int16 tl_data_type;
krb5_int16 tl_data_length;
krb5_octet * tl_data_contents;
} krb5_tl_data;
\end{verbatim}
The libkdb library defines the tagged data types
KRB5_TL_LAST_PWD_CHANGE, KRB5_TL_MOD_PRINC, and KRB5_TL_KADM_DATA,
which store the last password modification time, time and modifier of
last principal modification, and administration system data. All of
these entries are expected by the administration system and parsed out
into fields of the kadm5_principal_ent_rec structure; they are also
left in the tl_data list.
The KADM5 API defines its own tagged data type, KRB5_TL_KADM5_E_DATA,
which stores the contents of the e_data field of a krb5_db_entry. The
tagged data is only present if the database entry has extended data,
and will only ever exist while KADM5 is implemented on top of the
DB/DBM database mechansim.
Any additional tagged data fields found in the database will also be
provided, without interpretation.
\item[key_data] An array of the principal's keys. The keys contained
in this array are encrypted in the Kerberos master key. See section
\ref{sec:keys} for a discussion of the krb5_key_data structure.
\end{description}
\subsection{Policies, kadm5_policy_ent_t}
\label{sec:policy-fields}
If the POLICY bit is set in aux_attributes, the \v{policy} name field
in the kadm5_principal_ent_t structure refers to a password policy
entry defined in a \v{kadm5_policy_ent_t}.
\begin{verbatim}
typedef struct _kadm5_policy_ent_t {
char *policy;
u_int32 pw_min_life;
u_int32 pw_max_life;
u_int32 pw_min_length;
u_int32 pw_min_classes;
u_int32 pw_history_num;
u_int32 policy_refcnt;
} kadm5_policy_ent_rec, *kadm5_policy_ent_t;
\end{verbatim}
The fields of an kadm5_policy_ent_t are interpreted as follows.
Note that a policy's values only apply to a principal using that
policy.
\begin{description}
\item[policy] The name of this policy, as a NULL-terminated string.
The ASCII characters between 32 (space) and 126 (tilde), inclusive,
are legal.
\item[pw_min_life] The minimum password lifetime, in seconds.
A principal cannot change its password before pw_min_life seconds have
passed since last_pwd_change.
\item[pw_max_life] The default duration, in seconds, used to compute
pw_expiration when a principal's password is changed.
\item[pw_min_length] The minimum password length, in characters. A
principal cannot set its password to anything with fewer than this
number of characters. This value must be greater than zero.
\item[pw_min_classes] The minimum number of character classes in the
password. This value can only be 1, 2, 3, 4, or 5. A principal cannot
set its password to anything with fewer than this number of character
classes in it.
\item[pw_history_num] The number of past passwords that are
stored for the principal; the minimum value is 1 and the maximum value
is 10. A principal cannot set its password to any of its previous
pw_history_num passwords. The first ``previous'' password is the
current password; thus, a principal with a policy can never reset its
password to its current value.
\item[policy_refcnt] The number of principals currently using this policy.
A policy cannot be deleted unless this number is zero.
\end{description}
\subsection{Configuration parameters}
\label{sec:configparams}
The KADM5 API acquires configuration information from the Kerberos
configuration file (\$KRB5_CONFIG or DEFAULT_PROFILE_PATH) and from
the KDC configuration file (\$KRB5_KDC_CONFIG or DEFAULT_KDC_PROFILE).
In KADM5_API_VERSION_2, some of the configuration parameters used by
the KADM5 API can be controlled by the caller by providing a
kadm5_config_params structure to kadm5_init:
%
\begin{verbatim}
typedef struct _kadm5_config_params {
u_int32 mask;
/* Client and server fields */
char *realm;
char *profile;
int kadmind_port;
/* client fields */
char *admin_server;
/* server fields */
char *dbname;
char *admin_dbname;
char *admin_lockfile;
char *acl_file;
char *dict_file;
char *admin_keytab;
/* server library (database) fields */
int mkey_from_kbd;
char *stash_file;
char *mkey_name;
krb5_enctype enctype;
krb5_deltat max_life;
krb5_deltat max_rlife;
krb5_timestamp expiration;
krb5_flags flags;
krb5_key_salt_tuple *keysalts;
krb5_int32 num_keysalts;
} kadm5_config_params;
\end{verbatim}
%
The following list describes each of the fields of the structure,
along with the profile relation it overrides, its mask value, its
default value, and whether it is valid on the client, server, or both.
\begin{description}
\item[mask] No variable. No mask value. A bitfield specifying which
fields of the structure contain valid information. A caller sets this
mask before calling kadm5_init_*, indicating which parameters are
specified. The mask values are defined in $<$kadm5/admin.h$>$ and are
all prefixed with KADM5_CONFIG_; the prefix is not included in the
descriptions below.
\item[realm] No variable. REALM. Client and server. The realm to
which these parameters apply, and the realm for which additional
parameters are to be acquired, if any. If this field is not specified
in the mask, the default local realm is used.
\item[profile] Variable: profile (server only). PROFILE. Client and
server. The Kerberos profile to use. On the client, the default is
the value of the KRB5_CONFIG environment variable, or
DEFAULT_PROFILE_PATH if that is not set. On the server, the value of
the ``profile'' variable of the KDC configuration file will be used as
the first default if it exists; otherwise, the default is the value of
the KRB5_KDC_PROFILE environment variable or DEFAULT_KDC_PROFILE.
\item[kadmind_port] Variable: kadmind_port. KADMIND_PORT. Client and
server. The port number the kadmind server listens on. The client
uses this field to determine where to connect, and the server to
determine where to listen. The default is 749, which has been
assigned by IANA.
\item[admin_server] Variable: admin_server. ADMIN_SERVER. Client.
The host name of the admin server to which to connect. There is no
default. If the value of this field contains a colon (:), the text
following the colon is treated as an integer and assigned to the
kadmind_port field, overriding any value of the kadmind_port variable.
\item[dbname] Variable: dbname. DBNAME. Server. The Kerberos
database name to use; the Kerberos database stores principal
information. The default is DEFAULT_KDB_FILE.
\item[admin_dbname] Variable: admin_database_name. ADBNAME. Server.
The administration database name to use; the administration database
stores policy information. If DBNAME is specified in the input
parameters and ADBNAME is not, the admin_database_name variable is
overridden and the field is set to the value of dbname followed by
``.kadm5''. The default, if DBNAME is not set and the variable is not
defined, is also the value of dbname followed by ``.kadm5'', if dbname
is set. NOTE: The ADBNAME mask value is allowed to be set by callers
{\it only} for testing purposes; it should {\it never} be set by
normal clients, which instead should allow it to be derived from the
database name.
\item[admin_lockfile] Variable: admin_database_lockfile.
ADB_LOCKFILE. Server. The administration database lock file name,
used to lock the administration database. If ADBNAME or DBNAME is
specified in the input parameters and ADB_LOCKFILE is not, the
admin_database_lockfile variable is overridden and the field is set to
the value of admin_dbname followed by ``.lock'' (this depends on
admin_dbname already being set based on DBNAME as described above).
The default, if neither DBNAME nor ADBNAME is set in the input
parameters and the variable is not defined, is admin_dbname followed
by ``.lock'', if admin_dbname is set. NOTE: The ADBNAME mask value is
allowed to be set by callers {\it only} for testing purposes; it
should {\it never} be set by normal clients, which instead should
allow it to be derived from the database name.
\item[acl_file] Variable: acl_file. ACL_FILE. Server. The admin
server's ACL file. The default is DEFAULT_KADM5_ACL_FILE.
\item[dict_file] Variable: admin_dict_file. DICT_FILE. Server. The
admin server's dictionary file of passwords to disallow. No default.
\item[admin_keytab] Variable: admin_keytab. ADMIN_KEYTAB. Server.
The keytab file containing the kadmin/admin and kadmin/changepw
entries for the server to use. The default is the value of the
KRB5_KTNAME environment variable, if defined, else
DEFAULT_KADM5_KEYTAB.
\item[mkey_from_keyboard] No variable. MKEY_FROM_KEYBOARD. Server.
If non-zero, prompt for the master password via the tty instead of
using the stash file. If this mask bit is not set, or is set and the
value is zero, the stash file is used.
\item[stash_file] Variable: key_stash_file. STASH_FILE. Server. The
file name containing the master key stash file. No default; libkdb
will work with a NULL value.
\item[mkey_name] Variable: master_key_name. MKEY_NAME. Server. The
name of the master principal for the realm. No default; lbkdb will
work with a NULL value.
\item[enctype] Variable: master_key_type. ENCTYPE. Server. The
encryption type of the master principal. The default is
DEFAULT_KDC_ENCTYPE.
\item[max_life, max_rlife, expiration, flags] Variables: max_life,
max_renewable_life, default_principal_expiration,
default_principal_flags. MAX_LIFE, MAX_RLIFE, EXPIRATION, FLAGS.
Server. Default values for new principals. All default to 0.
\item[keysalts, num_keysalts] Variable: supported_enctypes. ENCTYPES.
Server. The list of supported encryption type/salt type tuples; both
fields must be assigned if ENCTYPES is set. The default is a list
containing one enctype, DES-CBC-CRC with normal salt.
\end{description}
\subsection{Principal keys}
\label{sec:keys}
In KADM5_API_VERSION_1, all principals had a single key. The
encryption method was always DES, and the salt type was determined
outside the API (by command-line options to the administration
server).
In KADM5_API_VERSION_2, principals can have multiple keys, each with
its own encryption type and salt. Each time a principal's key is
changed with kadm5_create_principal, kadm5_chpass_principal or
kadm5_randkey_principal, existing key entries are removed and a key
entry for each encryption and salt type tuple specified in the
configuration parameters is added. There is no provision for
specifying encryption and salt type information on a per-principal
basis; in a future version, this will probably be part of the admin
policy. There is also presently no provision for keeping multiple key
versions for a single principal active in the database.
A single key is represented by a krb5_key_data:
%
\begin{verbatim}
typedef struct _krb5_key_data {
krb5_int16 key_data_ver; /* Version */
krb5_int16 key_data_kvno; /* Key Version */
krb5_int16 key_data_type[2]; /* Array of types */
krb5_int16 key_data_length[2]; /* Array of lengths */
krb5_octet * key_data_contents[2]; /* Array of pointers */
} krb5_key_data;
\end{verbatim}
%
\begin{description}
\item[key_data_ver] The verion number of the structure. Versions 1
and 2 are currently defined. If key_data_ver is 1 then the key is
either a random key (not requiring a salt) or the salt is the normal
v5 salt which is the same as the realm and therefore doesn't need to
be saved in the database.
\item[key_data_kvno] The key version number of this key.
\item[key_data_type] The first element is the enctype of this key. In
a version 2 structure, the second element is the salttype of this key.
The legal encryption types are defined in $<$krb5.h$>$. The legal
salt types are defined in $<$k5-int.h$>$.
\item[key_data_length] The first element is length this key. In a
version 2 structure, the second element is length of the salt for this
key.
\item[key_data_contents] The first element is the content of this key.
In a version 2 structure, the second element is the contents of the
salt for this key.
\end{description}
\subsection{Field masks}
\label{sec:masks}
The API functions for creating, retrieving, and modifying principals
and policies allow for a relevant subset of the fields of the
kadm5_principal_ent_t and kadm5_policy_ent_t to be specified or
changed. The chosen fields are determined by a bitmask that is passed
to the relevant function. Each API function has different rules for
which mask values can be specified, and can specify whether a given
mask value is mandatory, optional, or forbidden. Mandatory fields
must be present and forbidden fields must not be present or an error
is generated. When creating a principal or policy, optional fields
have a default value if they are not specified. When modifying a
principal or policy, optional fields are unchanged if they are not
specified. When retrieving a principal, optional fields are simply
not provided if they are not specified; not specifying undeeded fields
for retrieval may improve efficiency. The values for forbidden fields
are defined in the function semantics.
The masks for principals are in table \ref{tab:princ-bits} and the
masks for policies are in table \ref{tab:policy-bits}. They are
defined in $<$kadm5/admin.h$>$. The KADM5_ prefix has been removed
from the Name fields. In the Create and Modify fields, M means
mandatory, F means forbidden, and O means optional. Create fields
that are optional specify the default value. The notation ``K/M
value'' means that the field inherits its value from the corresponding
field in the Kerberos master principal, for KADM5_API_VERSION_1, and
from the configuration parameters for KADM5_API_VERSION_2.
All masks for principals are optional for retrevial, {\it except} that
the KEY_DATA mask is illegal when specified by a remote client; for
details, see the function semantics for kadm5_get_principal.
Note that the POLICY and POLICY_CLR bits are special. When POLICY is
set, the policy is assigned to the principal. When POLICY_CLR is
specified, the policy is unassigned to the principal and as a result
no policy controls the principal.
For convenience, the mask KADM5_PRINCIPAL_NORMAL_MASK contains all of
the principal masks {\it except} KADM5_KEY_DATA and KADM5_TL_DATA, and
the mask KADM5_POLICY_NORMAL_MASK contains all of the policy masks.
\begin{table}[htbp]
\begin{tabular}{@{}lclll}
{\bf Name} & {\bf Value} & {\bf Fields Affected} & {\bf Create} &
{\bf Modify} \\
PRINCIPAL & 0x000001 & principal & M & F \\
PRINC_EXPIRE_TIME & 0x000002 & princ_expire_time & O, K/M value & O \\
PW_EXPIRATION & 0x000004 & pw_expiration & O, now+pw_max_life & O \\
LAST_PWD_CHANGE & 0x000008 & last_pwd_change & F & F \\
ATTRIBUTES & 0x000010 & attributes & O, 0 & O \\
MAX_LIFE & 0x000020 & max_life & O, K/M value & O \\
MOD_TIME & 0x000040 & mod_date & F & F \\
MOD_NAME & 0x000080 & mod_name & F & F \\
KVNO & 0x000100 & kvno & O, 1 & O \\
MKVNO & 0x000200 & mkvno & F & F \\
AUX_ATTRIBUTES & 0x000400 & aux_attributes & F & F \\
POLICY & 0x000800 & policy & O, none & O \\
POLICY_CLR & 0x001000 & policy & F & O \\
MAX_RLIFE & 0x002000 & max_renewable_life & O, K/M value & O \\
LAST_SUCCESS & 0x004000 & last_success & F & F \\
LAST_FAILED & 0x008000 & last_failed & F & F \\
FAIL_AUTH_COUNT & 0x010000 & fail_auth_count & F & O \\
KEY_DATA & 0x020000 & n_key_data, key_data & F & F \\
TL_DATA & 0x040000 & n_tl_data, tl_data & O, 0, NULL & O
\end{tabular}
\caption{Mask bits for creating, retrieving, and modifying principals.}
\label{tab:princ-bits}
\end{table}
\begin{table}[htbp]
\begin{tabular}{@{}lclll}
Name & Value & Field Affected & Create & Modify \\
POLICY & same & policy & M & F \\
PW_MAX_LIFE & 0x004000 & pw_max_life & O, 0 (infinite) & O \\
PW_MIN_LIFE & 0x008000 & pw_min_life & O, 0 & O \\
PW_MIN_LENGTH & 0x010000 & pw_min_length & O, 1 & O \\
PW_MIN_CLASSES & 0x020000 & pw_min_classes & O, 1 & O \\
PW_HISTORY_NUM & 0x040000 & pw_history_num & O, 0 & O \\
REF_COUNT & 0x080000 & pw_refcnt & F & F
\end{tabular}
\caption{Mask bits for creating/modifying policies.}
\label{tab:policy-bits}
\end{table}
\section{Constants, Header Files, Libraries}
$<$kadm5/admin.h$>$ includes a number of required header files,
including RPC, Kerberos 5, com_err, and admin com_err
defines. It contains prototypes for all kadm5 routines mentioned
below, as well as all Admin API data structures, type definitions and
defines mentioned in this document.
Before \v{\#include}ing $<$kadm5/admin.h$>$, the programmer can
specify the API version number that the program will use by
\v{\#define}ing USE_KADM5_API_VERSION; for example, define that symbol
to be 1 to use KADM5_API_VERSION_1. This will ensure that the correct
functional protoypes and data structures are defined. If no version
symbol is defined, the most recent version supported by the header
files will be used.
Some of the defines and their values contained in $<$kadm5/admin.h$>$
include the following, whose KADM5_ prefixes have been removed.
Symbols that do not exist in KADM5_API_VERSION_2 do not have a KADM5_
prefix, but instead retain only with OVSEC_KADM_ prefix for
compatibility.
\begin{description}
\item[admin service principal] ADMIN_SERVICE (``kadmin/admin'')
\item[admin history key] HIST_PRINCIPAL (``kadmin/history'')
\item[change password principal] CHANGEPW_SERVICE (``kadmin/changepw'')
\item[server acl file path] ACLFILE (``/krb5/ovsec_adm.acl''). In
KADM5_API_VERSION 2, this is controlled by configuration parameters.
\item[dictionary] WORDFILE (``/krb5/kadmind.dict''). In
KADM5_API_VERSION 2, this is controlled by configuration parameters.
\end{description}
KADM5 errors are described in $<$kadm5/kadm_err.h$>$, which
is included by $<$kadm5/admin.h$>$.
The locations of the admin policy and principal databases, as well as
defines and type definitions for the databases, are defined in
$<$kadm5/adb.h$>$. Some of the defines in that file are:
\begin{description}
\item[admin policy database] POLICY_DB (``/krb5/kadm5_policy.db''). In
KADM5_API_VERSION 2, this is controlled by configuration parameters.
\item[admin principal database] PRINCIPAL_DB
(``/krb5/ovsec_principal.db''). In KADM5_API_VERSION 2, this is
controlled by configuration parameters.
\end{description}
Client applications will link against libkadm5clnt.a and server
programs against libkadm5srv.a. Client applications must also link
against: libgssapi_krb5.a, libkrb5.a, libcrypto.a, libgssrpc.a,
libcom_err.a, and libdyn.a. Server applications must also link
against: libkdb5.a, libkrb5.a, libcrypto.a, libgssrpc.a, libcom_err.a,
and libdyn.a.
\section{Error Codes}
The error codes that can be returned by admin functions are listed
below. Error codes indicated with a ``*'' can be returned by every
admin function and always have the same meaning; these codes are
omitted from the list presented with each function.
The admin system guarantees that a function that returns an error code
has no other side effect.
The Admin system will use \v{com_err} for error codes. Note that this
means \v{com_err} codes may be returned from functions that the admin
routines call (e.g. the kerberos library). Callers should not expect
that only KADM5 errors will be returned. The Admin system error code
table name will be ``ovk'', and the offsets will be the same as the
order presented here. As mentioned above, the error table include file
will be $<$kadm5/kadm_err.h$>$.
Note that these error codes are also used as protocol error code
constants and therefore must not change between product releases.
Additional codes should be added at the end of the list, not in the
middle. The integer value of KADM5_FAILURE is 43787520; the
remaining values are assigned in sequentially increasing order.
\begin{description}
\item[* KADM5_FAILURE] Operation failed for unspecified reason
\item[* KADM5_AUTH_GET] Operation requires ``get'' privilege
\item[* KADM5_AUTH_ADD] Operation requires ``add'' privilege
\item[* KADM5_AUTH_MODIFY] Operation requires ``modify'' privilege
\item[* KADM5_AUTH_DELETE] Operation requires ``delete'' privilege
\item[* KADM5_AUTH_INSUFFICIENT] Insufficient authorization for
operation
\item[* KADM5_BAD_DB] Database inconsistency detected
\item[KADM5_DUP] Principal or policy already exists
\item[KADM5_RPC_ERROR] Communication failure with server
\item[KADM5_NO_SRV] No administration server found for realm
\item[KADM5_BAD_HIST_KEY] Password history principal key version
mismatch
\item[KADM5_NOT_INIT] Connection to server not initialized
\item[KADM5_UNK_PRINC] Principal does not exist
\item[KADM5_UNK_POLICY] Policy does not exist
\item[KADM5_BAD_MASK] Invalid field mask for operation
\item[KADM5_BAD_CLASS] Invalid number of character classes
\item[KADM5_BAD_LENGTH] Invalid password length
\item[KADM5_BAD_POLICY] Illegal policy name
\item[KADM5_BAD_PRINCIPAL] Illegal principal name.
\item[KADM5_BAD_AUX_ATTR] Invalid auxillary attributes
\item[KADM5_BAD_HISTORY] Invalid password history count
\item[KADM5_BAD_MIN_PASS_LIFE] Password minimum life is greater
then password maximum life
\item[KADM5_PASS_Q_TOOSHORT] Password is too short
\item[KADM5_PASS_Q_CLASS] Password does not contain enough
character classes
\item[KADM5_PASS_Q_DICT] Password is in the password dictionary
\item[KADM5_PASS_REUSE] Cannot resuse password
\item[KADM5_PASS_TOOSOON] Current password's minimum life has not
expired
\item[KADM5_POLICY_REF] Policy is in use
\item[KADM5_INIT] Connection to server already initialized
\item[KADM5_BAD_PASSWORD] Incorrect password
\item[KADM5_PROTECT_PRINCIPAL] Cannot change protected principal
\item[* KADM5_BAD_SERVER_HANDLE] Programmer error! Bad Admin server handle
\item[* KADM5_BAD_STRUCT_VERSION] Programmer error! Bad API structure version
\item[* KADM5_OLD_STRUCT_VERSION] API structure version specified by application is no longer supported (to fix, recompile application against current Admin API header files and libraries)
\item[* KADM5_NEW_STRUCT_VERSION] API structure version specified by application is unknown to libraries (to fix, obtain current Admin API header files and libraries and recompile application)
\item[* KADM5_BAD_API_VERSION] Programmer error! Bad API version
\item[* KADM5_OLD_LIB_API_VERSION] API version specified by application is no longer supported by libraries (to fix, update application to adhere to current API version and recompile)
\item[* KADM5_OLD_SERVER_API_VERSION] API version specified by application is no longer supported by server (to fix, update application to adhere to current API version and recompile)
\item[* KADM5_NEW_LIB_API_VERSION] API version specified by application is unknown to libraries (to fix, obtain current Admin API header files and libraries and recompile application)
\item[* KADM5_NEW_SERVER_API_VERSION] API version specified by
application is unknown to server (to fix, obtain and install newest
Admin Server)
\item[KADM5_SECURE_PRINC_MISSING] Database error! Required principal missing
\item[KADM5_NO_RENAME_SALT] The salt type of the specified principal
does not support renaming
\item[KADM5_BAD_CLIENT_PARAMS] Illegal configuration parameter for
remote KADM5 client
\item[KADM5_BAD_SERVER_PARAMS] Illegal configuration parameter for
local KADM5 client.
\item[KADM5_AUTH_LIST] Operation requires ``list'' privilege
\item[KADM5_AUTH_CHANGEPW] Operation requires ``change-password'' privilege
\end{description}
\section{Authentication and Authorization}
\label{sec:auth}
Two Kerberos principals exist for use in communicating with the Admin
system: kadmin/admin and kadmin/changepw. Both principals
have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so
that service tickets for them can only be acquired via a
password-based (AS_REQ) request. Additionally, kadmin/changepw
has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an
expired password can still obtain a service ticket for it.
The Admin system accepts requests that are authenticated to either
service principal, but the sets of operations that can be performed by
a request authenticated to each service are different. In particular,
only the functions chpass_principal, randkey_principal, get_principal,
and get_policy can be performed by a request authenticated to the
kadmin/changepw service. The function semantics descriptions below
give the precise details.
Each Admin API operation authenticated to the kadmin/admin service
requires a specific authorization to run. This version uses a simple
named privilege system with the following names and meanings:
\begin{description}
\item[Get] Able to examine the attributes (NOT key data) of principals
and policies.
\item[Add] Able to add principals and policies.
\item[Modify] Able to modify attributes of existing principals and
policies; this does not include changing passwords.
\item[Delete] Able to remove principals and policies.
\item[List] Able to retrieve a list of principals and policies.
\item[Changepw] Able to change the password of principals.
\end{description}
Privileges are specified via an external configuration file on the
Kerberos master server.
Table \ref{tab:func-overview} summarizes the authorization
requirements of each function. Additionally, each API function
description identifies the privilege required to perform it. The
Authorization checks only happen if you are using the RPC mechanism.
If you are using the server-side API functions locally on the admin
server, the only authorization check is if you can access the
approporiate local files.
\section{Functions}
\subsection{Overview}
The functions provided by the Admin API, and the authorization they
require, are listed in the table \ref{tab:func-overview}. The
``kadm5_'' prefix has been removed from each function name.
The function semantics in the following sections omit details that are
the same for every function.
\begin{itemize}
\item The effects of every function are atomic.
\item Every function performs an authorization check and returns
the appropriate KADM5_AUTH_* error code if the caller does not
have the required privilege. No other information or error code is
ever returned to an unauthorized user.
\item Every function checks its arguments for NULL pointers or other
obviously invalid values, and returns EINVAL if any are detected.
\item Any function that performs a policy check uses the policy named
in the principal's policy field. If the POLICY bit is not set in the
principal's aux_attributes field, however, the principal has no
policy, so the policy check is not performed.
\item Unless otherwise specified, all functions return KADM5_OK.
\end{itemize}
\begin{table}[htbp]
\caption{Summary of functions and required authorization.}
\label{tab:func-overview}
\begin{tabular}{@{}llp{3.24in}}
\\
{\bf Function Name} & {\bf Authorization} & {\bf Operation} \\
init & none & Open a connection with the kadm5 library. OBSOLETE
but still provided---use init_with_password instead. \\
init_with_password & none & Open a connection with the kadm5
library using a password to obtain initial credentials. \\
init_with_skey & none & Open a connection with the kadm5 library
using the keytab entry to obtain initial credentials. \\
destroy & none & Close the connection with the kadm5 library. \\
flush & none & Flush all database changes to disk; no-op when called
remotely. \\
create_principal & add & Create a new principal. \\
delete_principal & delete & Delete a principal. \\
modify_principal & modify & Modify the attributes of an existing
principal (not password). \\
rename_principal & add and delete & Rename a principal. \\
get_principal & get\footnotemark & Retrieve a principal. \\
get_principals & list & Retrieve some or all principal names. \\
chpass_principal & changepw\footnotemark[\thefootnote] &
Change a principal's password. \\
chpass_principal_util & changepw\footnotemark[\thefootnote] & Utility wrapper around chpass_principal. \\
randkey_principal & changepw\footnotemark[\thefootnote] &
Randomize a principal's key. \\
decrypt_key & none & Decrypt a principal key. \\
create_policy & add & Create a new policy. \\
delete_policy & delete & Delete a policy. \\
modify_policy & modify & Modify the attributes of a policy. \\
get_policy & get & Retrieve a policy. \\
get_policies & list & Retrieve some or all policy names. \\
free_principal_ent & none & Free the memory associated with an
kadm5_principal_ent_t. \\
free_policy_ent & none & Free the memory associated with an
kadm5_policy_ent_t. \\
get_privs & none & Return the caller's admin server privileges.
\end{tabular}
\end{table}
\footnotetext[\thefootnote]{These functions also allow a principal to
perform the operation on itself; see the function's semantics for
details.}
\subsection{kadm5_init_*}
In KADM5_API_VERSION 1:
\begin{verbatim}
kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
char *service_name, char *realm,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
char *service_name, char *realm,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init(char *client_name, char *pass,
char *service_name, char *realm,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
\end{verbatim}
In KADM5_API_VERSION 2:
\begin{verbatim}
kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
char *service_name,
kadm5_config_params *realm_params,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
char *service_name,
kadm5_config_params *realm_params,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init(char *client_name, char *pass,
char *service_name,
kadm5_config_params *realm_params,
unsigned long struct_version,
unsigned long api_version,
void **server_handle)
kadm5_ret_t kadm5_init_with_creds(char *client_name,
krb5_ccache ccache,
char *service_name,
kadm5_config_params *params,
krb5_ui_4 struct_version,
krb5_ui_4 api_version,
void **server_handle)
\end{verbatim}
AUTHORIZATION REQUIRED: none
NOTE: kadm5_init is an obsolete function provided for backwards
compatibility. It is identical to kadm5_init_with_password.
These three functions open a connection to the kadm5 library and
initialize any neccessary state information. They behave differently
when called from local and remote clients.
In KADM5_API_VERSION_2, these functions take a kadm5_config_params
structure instead of a realm name as an argument. The semantics are
similar: if a NULL pointer is passed for the realm_params argument,
the default realm and default parameters for that realm, as specified
in the krb5 configuration file (e.g. /etc/krb5.conf) are used. If a
realm_params structure is provided, the fields that are set override
the default values. If a parameter is specified to the local or
remote libraries that does not apply to that side, an error code
(KADM5_BAD_CLIENT_PARAMS or KADM5_BAD_SERVER_PARAMS) is returned. See
section \ref{sec:configparams} for a discussion of configuration
parameters.
For remote clients, the semantics are:
\begin{enumerate}
\item Initializes all the com_err error tables used by the Admin
system.
\item Acquires configuration parameters. In KADM5_API_VERSION_1, all
the defaults specified in the configuration file are used, according
to the realm. In KADM5_API_VERSION_2, the values in params_in are
merged with the default values. If an illegal mask value is
specified, KADM5_BAD_CLIENT_PARAMS is returned.
\item Acquires a Kerberos ticket for the specified service.
\begin{enumerate}
\item The ticket's client is client_name, which can be any valid
Kerberos principal. If client_name does not include a realm, the
default realm of the local host is used
\item The ticket's service is service_name@realm. service_name must
be one of the constants KADM5_ADMIN_SERVICE or
KADM5_CHANGEPW_SERVICE.
\item If realm is NULL, client_name's realm is used.
\item For init_with_password, an initial ticket is acquired and
decoded with the password pass, which must be client_name's password.
If pass is NULL or an empty string, the user is prompted (via the tty)
for a password.
\item For init_with_skey, an initial ticket is acquired and decoded
with client_name's key obtained from the specified keytab. If keytab
is NULL or an empty string the default keytab is used.
\item For init_with_creds, ccache must be an open credential cache
that already has a ticket for the specified client and server.
Alternatively, if a site chooses to disable the DISALLOW_TGT_BASED
flag on the admin and changepw principals, the ccache can contain a
ticket-granting ticket for client_name.
\end{enumerate}
\item Creates a GSS-API authenticated connection to the Admin server,
using the just-acquired Kerberos ticket.
\item Verifies that the struct_version and api_version specified by
the caller are valid and known to the library.
\item Sends the specified api_version to the server.
\item Upon successful completion, fills in server_handle with a handle
for this connection, to be used in all subsequent API calls.
\end{enumerate}
The caller should always specify KADM5_STRUCT_VERSION for the
struct_version argument, a valid and supported API version constant
for the api_version argument (currently, KADM5_API_VERSION_1 or
KADM5_API_VERSION_2), and a valid pointer in which the server handle
will be stored.
If any kadm5_init_* is invoked locally its semantics are:
\begin{enumerate}
\item Initializes all the com_err error tables used by the Admin
system.
\item Acquires configuration parameters. In KADM5_API_VERSION_1, all
the defaults specified in the configuration file are used, according
to the realm. In KADM5_API_VERSION_2, the values in params_in are
merged with the default values. If an illegal mask value is
specified, KADM5_BAD_SERVER_PARAMS is returned.
\item Initializes direct access to the KDC database. In
KADM5_API_VERISON_1, if pass (or keytab) is NULL or an empty string,
reads the master password from the stash file; otherwise, the non-NULL
password is ignored and the user is prompted for it via the tty. In
KADM5_API_VERSION_2, if the MKEY_FROM_KEYBOARD parameter mask is set
and the value is non-zero, reads the master password from the user via
the tty; otherwise, the master key is read from the stash file.
Calling init_with_skey or init_with_creds with the MKEY_FROM_KEYBOARD
mask set with a non-zero field is illegal, and calling them without
the mask set is exactly like calling init_with_password.
\item Initializes the dictionary (if present) for dictionary checks.
\item Parses client_name as a Kerberos principal. client_name should
usually be specified as the name of the program.
\item Verifies that the struct_version and api_version specified by
the caller are valid.
\item Fills in server_handle with a handle containing all state
information (version numbers and client name) for this ``connection.''
\end{enumerate}
The service_name argument is not used.
RETURN CODES:
\begin{description}
\item[KADM5_NO_SRV] No Admin server can be found for the
specified realm.
\item[KADM5_RPC_ERROR] The RPC connection to the server cannot be
initiated.
\item[KADM5_BAD_PASSWORD] Incorrect password.
\item[KADM5_SECURE_PRINC_MISSING] The principal
KADM5_ADMIN_SERVICE or KADM5_CHANGEPW_SERVICE does not
exist. This is a special-case replacement return code for ``Server
not found in database'' for these required principals.
\item[KADM5_BAD_CLIENT_PARAMS] A field in the parameters mask was
specified to the remote client library that is not legal for remote
clients.
\item[KADM5_BAD_SERVER_PARAMS] A field in the parameters mask was
specified to the local client library that is not legal for local
clients.
\end{description}
\subsection{kadm5_flush}
\begin{verbatim}
kadm5_ret_t kadm5_flush(void *server_handle)
\end{verbatim}
AUTHORIZATION REQUIRED: none
Flush all changes to the Kerberos databases, leaving the connection to
the Admin API open. This function behaves differently when called by
local and remote clients.
For local clients, the function closes and reopens the Kerberos
database with krb5_db_fini() and krb5_db_init(), and closes and
reopens the Admin policy database with adb_policy_close() and
adb_policy_open(). Although it is unlikely, any other these functions
could return errors; in that case, this function calls
kadm5_destroy and returns the error code. Therefore, if
kadm5_flush does not return KADM5_OK, the connection to the
Admin server has been terminated and, in principle, the databases
might be corrupt.
For remote clients, the function is a no-op.
\subsection{kadm5_destroy}
\begin{verbatim}
kadm5_ret_t kadm5_destroy(void *server_handle)
\end{verbatim}
AUTHORIZATION REQUIRED: none
Close the connection to the Admin server and releases all related
resources. This function behaves differently when called by local and
remote clients.
For remote clients, the semantics are:
\begin{enumerate}
\item Destroy the temporary credential cache created by
kadm5_init.
\item Tear down the GSS-API context negotiated with the server.
\item Close the RPC connection.
\item Free storage space associated with server_handle, after erasing
its magic number so it won't be mistaken for a valid handle by the
library later.
\end{enumerate}
For local clients, this function just frees the storage space
associated with server_handle after erasing its magic number.
RETURN CODES:
\subsection{kadm5_create_principal}
\begin{verbatim}
kadm5_ret_t
kadm5_create_principal(void *server_handle,
kadm5_principal_ent_t princ, u_int32 mask,
char *pw);
\end{verbatim}
AUTHORIZATION REQUIRED: add
\begin{enumerate}
\item Return KADM5_BAD_MASK if the mask is invalid.
\item If the named principal exists, return KADM5_DUP.
\item If the POLICY bit is set and the named policy does not exist,
return KADM5_UNK_POLICY.
\item If KADM5_POLICY bit is set in aux_attributes check to see if
the password does not meets quality standards, return the appropriate
KADM5_PASS_Q_* error code if it fails.
\item Store the principal, set the key; see section \ref{sec:keys}.
\item If the POLICY bit is set, increment the named policy's reference
count by one.
\item Set the pw_expiration field.
\begin{enumerate}
\item If the POLICY bit is not set, then
\begin{enumerate}
\item if the PW_EXPIRATION bit is set, set pw_expiration to the given
value, else
\item set pw_expiration to never.
\end{enumerate}
\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to
the sooner of the given value and now + pw_max_life.
\item Otherwise, set pw_expiration to now + pw_max_life.
\end{enumerate}
\item Set mod_date to now and set mod_name to caller.
\item Set last_pwd_change to now.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_BAD_MASK] The field mask is invalid for a create
operation.
\item[KADM5_DUP] Principal already exists.
\item[KADM5_UNK_POLICY] Policy named in entry does not exist.
\item[KADM5_PASS_Q_*] Specified password does not meet policy
standards.
\end{description}
\subsection{kadm5_delete_principal}
\begin{verbatim}
kadm5_ret_t
kadm5_delete_principal(void *server_handle, krb5_principal princ);
\end{verbatim}
AUTHORIZATION REQUIRED: delete
\begin{enumerate}
\item Return KADM5_UNK_PRINC if the principal does not exist.
\item If the POLICY bit is set in aux_attributes, decrement the named
policy's reference count by one.
\item Delete principal.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_UNK_PRINC] Principal does not exist.
\end{description}
\subsection{kadm5_modify_principal}
\begin{verbatim}
kadm5_ret_t
kadm5_modify_principal(void *server_handle,
kadm5_principal_ent_t princ, u_int32 mask);
\end{verbatim}
Modify the attributes of the principal named in
kadm5_principal_ent_t. This does not allow the principal to be
renamed or for its password to be changed.
AUTHORIZATION REQUIRED: modify
Although a principal's pw_expiration is usually computed based on its
policy and the time at which it changes its password, this function
also allows it to be specified explicitly. This allows an
administrator, for example, to create a principal and assign it to a
policy with a pw_max_life of one month, but to declare that the new
principal must change its password away from its initial value
sometime within the first week.
\begin{enumerate}
\item Return KADM5_UNK_PRINC if the principal does not exist.
\item Return KADM5_BAD_MASK if the mask is invalid.
\item If POLICY bit is set but the new policy does not exist, return
KADM5_UNK_POLICY.
\item If either the POLICY or POLICY_CLR bits are set, update the
corresponding bits in aux_attributes.
\item Update policy reference counts.
\begin{enumerate}
\item If the POLICY bit is set, then increment policy count on new
policy.
\item If the POLICY or POLICY_CLR bit is set, and the POLICY bit in
aux_attributes is set, decrement policy count on old policy.
\end{enumerate}
\item Set pw_expiration according to the new policy.
\begin{enumerate}
\item If the POLICY bit is not set in aux_attributes, then
\begin{enumerate}
\item if the PW_EXPIRATION bit is set, set pw_expiration to the given
value, else
\item set pw_expiration to never.
\end{enumerate}
\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to
the sooner of the given value and last_pwd_change + pw_max_life.
\item Otherwise, set pw_expiration to last_pwd_change + pw_max_life.
\end{enumerate}
\item Update the fields specified in the mask.
\item Update mod_name field to caller and mod_date to now.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_UNK_PRINC] Entry does not exist.
\item[KADM5_BAD_MASK] The mask is not valid for a modify
operation.
\item[KADM5_UNK_POLICY] The POLICY bit is set but the new
policy does not exist.
\end{description}
\subsection{kadm5_rename_principal}
\begin{verbatim}
kadm5_ret_t
kadm5_rename_principal(void *server_handle, krb5_principal source,
krb5_principal target);
\end{verbatim}
AUTHORIZATION REQUIRED: add and delete
\begin{enumerate}
\item Check to see if source principal exists, if not return
KADM5_UNK_PRINC error.
\item Check to see if target exists, if so return KADM5_DUP error.
\item Create the new principal named target, then delete the old
principal named source. All of target's fields will be the same as
source's fields, except that mod_name and mod_date will be updated to
reflect the current caller and time.
\end{enumerate}
Note that since the principal name may have been used as the salt for
the principal's key, renaming the principal may render the principal's
current password useless; with the new salt, the key generated by
string-to-key on the password will suddenly be different. Therefore,
an application that renames a principal must also require the user to
specify a new password for the principal (and administrators should
notify the affected party).
Note also that, by the same argument, renaming a principal will
invalidate that principal's password history information; since the
salt will be different, a user will be able to select a previous
password without error.
RETURN CODES:
\begin{description}
\item[KADM5_UNK_PRINC] Source principal does not exist.
\item[KADM5_DUP] Target principal already exist.
\end{description}
\subsection{kadm5_chpass_principal}
\begin{verbatim}
kadm5_ret_t
kadm5_chpass_principal(void *server_handle, krb5_principal princ,
char *pw);
\end{verbatim}
AUTHORIZATION REQUIRED: changepw, or the calling principal being the
same as the princ argument. If the request is authenticated to the
kadmin/changepw service, the changepw privilege is disregarded.
Change a principal's password. See section \ref{sec:keys} for a
description of how the keys are determined.
This function enforces password policy and dictionary checks. If the new
password specified is in the password dictionary, and the policy bit is set
KADM5_PASS_DICT is returned. If the principal's POLICY bit is set in
aux_attributes, compliance with each of the named policy fields is verified
and an appropriate error code is returned if verification fails.
Note that the policy checks are only be performed if the POLICY bit is
set in the principal's aux_attributes field.
\begin{enumerate}
\item Make sure principal exists, if not return KADM5_UNK_PRINC error.
\item If caller does not have modify privilege, (now - last_pwd_change) $<$
pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
principal's attributes, return KADM5_PASS_TOOSOON.
\item If the principal your are trying to change is kadmin/history
return KADM5_PROTECT_PRINCIPAL.
\item If the password does not meet the quality
standards, return the appropriate KADM5_PASS_Q_* error code.
\item Convert password to key; see section \ref{sec:keys}.
\item If the new key is in the principal's password history, return
KADM5_PASS_REUSE.
\item Store old key in history.
\item Update principal to have new key.
\item Increment principal's key version number by one.
\item If the POLICY bit is set, set pw_expiration to now +
max_pw_life. If the POLICY bit is not set, set pw_expiration to
never.
\item If the KRB5_KDB_REQUIRES_PWCHANGE bit is set in the principal's
attributes, clear it.
\item Update last_pwd_change and mod_date to now, update mod_name to
caller.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_UNK_PRINC] Principal does not exist.
\item[KADM5_PASS_Q_*] Requested password does not meet quality
standards.
\item[KADM5_PASS_REUSE] Requested password is in user's
password history.
\item[KADM5_PASS_TOOSOON] Current password has not reached minimum life
\item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special principal
\end{description}
\subsection{kadm5_chpass_principal_util}
\begin{verbatim}
kadm5_ret_t
kadm5_chpass_principal_util(void *server_handle, krb5_principal princ,
char *new_pw, char **pw_ret,
char *msg_ret);
\end{verbatim}
AUTHORIZATION REQUIRED: changepw, or the calling principal being the
same as the princ argument. If the request is authenticated to the
kadmin/changepw service, the changepw privilege is disregarded.
This function is a wrapper around kadm5_chpass_principal. It can
read a new password from a user, change a principal's password, and
return detailed error messages. msg_ret should point to a char buffer
in the caller's space of sufficient length for the error messages
described below. 1024 bytes is recommended. It will also return the
new password to the caller if pw_ret is non-NULL.
\begin{enumerate}
\item If new_pw is NULL, this routine will prompt the user for the new
password (using the strings specified by KADM5_PW_FIRST_PROMPT and
KADM5_PW_SECOND_PROMPT) and read (without echoing) the password input.
Since it is likely that this will simply call krb5_read_password only
terminal-based applications will make use of the password reading
functionality. If the passwords don't match the string ``New passwords do
not match - password not changed.'' will be copied into msg_ret, and the
error code KRB5_LIBOS_BADPWDMATCH will be returned. For other errors that
ocurr while reading the new password, copy the string ``<com_err message$>$
occurred while trying to read new password.'' followed by a blank line and
the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and
return the error code returned by krb5_read_password.
\item If pw_ret is non-NULL, and the password was prompted, set *pw_ret to
point to a static buffer containing the password. If pw_ret is non-NULL
and the password was supplied, set *pw_ret to the supplied password.
\item Call kadm5_chpass_principal with princ, and new_pw.
\item If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED
into msg_ret and return zero.
\item For a policy related failure copy the appropriate message (from below)
followed by a newline and ``Password not changed.'' into msg_ret
filling in the parameters from the principal's policy information. If
the policy information cannot be obtained copy the generic message if
one is specified below. Return the error code from
kadm5_chpass_principal.
Detailed messages:
\begin{description}
\item[PASS_Q_TOO_SHORT]
New password is too short. Please choose a
password which is more than $<$pw-min-len$>$ characters.
\item[PASS_Q_TOO_SHORT - generic]
New password is too short. Please choose a longer password.
\item[PASS_REUSE]
New password was used previously. Please choose a
different password.
\item[PASS_Q_CLASS]
New password does not have enough character classes. Classes include
lower class letters, upper case letters, digits, punctuation and all
other characters. Please choose a password with at least
$<$min-classes$>$ character classes.
\item[PASS_Q_CLASS - generic]
New password does not have enough character classes. Classes include
lower class letters, upper case letters, digits, punctuation and all
other characters.
\item[PASS_Q_DICT]
New password was found in a dictionary of possible passwords and
therefore may be easily guessed. Please choose another password. See
the kpasswd man page for help in choosing a good password.
\item[PASS_TOOSOON]
Password cannot be changed because it was changed too recently. Please
wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you
need to change your password before then, contact your system
security administrator.
\item[PASS_TOOSOON - generic]
Password cannot be changed because it was changed too recently. If you
need to change your now please contact your system security
administrator.
\end{description}
\item For other errors copy the string ``$<$com_err message$>$
occurred while trying to change password.'' following by a blank line
and ``Password not changed.'' into msg_ret. Return the error code
returned by kadm5_chpass_principal.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KRB5_LIBOS_BADPWDMATCH] Typed new passwords did not match.
\item[KADM5_UNK_PRINC] Principal does not exist.
\item[KADM5_PASS_Q_*] Requested password does not meet quality
standards.
\item[KADM5_PASS_REUSE] Requested password is in user's
password history.
\item[KADM5_PASS_TOOSOON] Current password has not reached minimum
life.
\end{description}
\subsection{kadm5_randkey_principal}
In KADM5_API_VERSION_1:
\begin{verbatim}
kadm5_ret_t
kadm5_randkey_principal(void *server_handle, krb5_principal princ,
krb5_keyblock **new_key)
\end{verbatim}
In KADM5_API_VERSION_2:
\begin{verbatim}
kadm5_ret_t
kadm5_randkey_principal(void *server_handle, krb5_principal princ,
krb5_keyblock **new_keys, int *n_keys)
\end{verbatim}
AUTHORIZATION REQUIRED: changepw, or the calling principal being the
same as the princ argument. If the request is authenticated to the
kadmin/changepw service, the changepw privilege is disregarded.
Generate and assign a new random key to the named principal, and
return the generated key in allocated storage. In
KADM5_API_VERSION_2, multiple keys may be generated and returned as an
array, and n_new_keys is filled in with the number of keys generated.
See section \ref{sec:keys} for a description of how the keys are
chosen. In KADM5_API_VERSION_1, the caller must free the returned
krb5_keyblock * with krb5_free_keyblock. In KADM5_API_VERSION_2, the
caller must free each returned keyblock with krb5_free_keyblock.
If the principal's POLICY bit is set in aux_attributes and the caller does
not have modify privilege , compliance with the password minimum life
specified by the policy is verified and an appropriate error code is returned
if verification fails.
\begin{enumerate}
\item If the principal does not exist, return KADM5_UNK_PRINC.
\item If caller does not have modify privilege, (now - last_pwd_change) $<$
pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
principal's attributes, return KADM5_PASS_TOOSOON.
\item If the principal you are trying to change is kadmin/history return
KADM5_PROTECT_PRINCIPAL.
\item Store old key in history.
\item Update principal to have new key.
\item Increment principal's key version number by one.
\item If the POLICY bit in aux_attributes is set, set pw_expiration to
now + max_pw_life.
\item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's
attributes, clear it.
\item Update last_pwd_change and mod_date to now, update mod_name to
caller.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_UNK_PRINC] Principal does not exist.
\item[KADM5_PASS_TOOSOON] The minimum lifetime for the current
key has not expired.
\item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special
principal
\end{description}
This function can also be used as part of a sequence to create a new
principal with a random key. The steps to perform the operation
securely are
\begin{enumerate}
\item Create the principal with kadm5_create_principal with a
random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set
in the attributes field.
\item Randomize the principal's key with kadm5_randkey_principal.
\item Call kadm5_modify_principal to reset the
KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.
\end{enumerate}
The three steps are necessary to ensure secure creation. Since an
attacker might be able to guess the initial password assigned by the
client program, the principal must be disabled until the key can be
truly randomized.
\subsection{kadm5_get_principal}
In KADM5_API_VERSION_1:
\begin{verbatim}
kadm5_ret_t
kadm5_get_principal(void *server_handle, krb5_principal princ,
kadm5_principal_ent_t *ent);
\end{verbatim}
In KADM5_API_VERSION_2:
\begin{verbatim}
kadm5_ret_t
kadm5_get_principal(void *server_handle, krb5_principal princ,
kadm5_principal_ent_t ent, u_int32 mask);
\end{verbatim}
AUTHORIZATION REQUIRED: get, or the calling principal being the same
as the princ argument. If the request is authenticated to the
kadmin/changepw service, the get privilege is disregarded.
In KADM5_API_VERSION_1, return all of the principal's attributes in
allocated memory; if an error is returned entry is set to NULL. In
KADM5_API_VERSION_2, fill in the fields of the principal structure
specified in the mask; memory for the structure is not allocated.
Typically, a caller will specify the mask KADM5_PRINCIPAL_NORMAL_MASK,
which includes all the fields {\it except} key_data and tl_data to
improve time and memory efficiency. A caller that wants key_data and
tl_data can bitwise-OR those masks onto NORMAL_MASK.
The caller must free the returned entry with kadm5_free_principal_ent.
The function behaves differently for local and remote clients. For
remote clients, the KEY_DATA mask is illegal and results in a
KADM5_BAD_MASK error.
RETURN CODES:
\begin{description}
\item[KADM5_UNK_PRINC] Principal does not exist.
\item[KADM5_BAD_MASK] The mask is not valid for a get operation.
\end{description}
\subsection{kadm5_decyrpt_key}
\begin{verbatim}
kadm5_ret_t kadm5_decrypt_key(void *server_handle,
kadm5_principal_ent_t entry, krb5_int32
ktype, krb5_int32 stype, krb5_int32
kvno, krb5_keyblock *keyblock,
krb5_keysalt *keysalt, int *kvnop)
\end{verbatim}
AUTHORIZATION REQUIRED: none, local function
Searches a principal's key_data array to find a key with the specified
enctype, salt type, and kvno, and decrypts the key into keyblock and
keysalt if found. entry must have been returned by
kadm5_get_principal with at least the KADM5_KEY_DATA mask set.
Returns ENOENT if the key cannot be found, EINVAL if the key_data
array is empty (as it always is in an RPC client).
If ktype or stype is -1, it is ignored for the search. If kvno is -1,
ktype and stype are ignored and the key with the max kvno is returned.
If kvno is 0, only the key with the max kvno is returned and only if
it matches the ktype and stype; otherwise, ENOENT is returned.
\subsection{kadm5_get_principals}
\begin{verbatim}
kadm5_ret_t
kadm5_get_principals(void *server_handle, char *exp,
char ***princs, int *count)
\end{verbatim}
Retrieves the list of principal names.
AUTHORIZATION REQUIRED: list
If \v{exp} is NULL, all principal names are retrieved; otherwise,
principal names that match the expression exp are retrieved.
\v{princs} is filled in with a pointer to a NULL-terminated array of
strings, and \v{count} is filled in with the number of principal names
in the array. \v{princs} must be freed with a call to
\v{kadm5_free_name_list}.
All characters in the expression match themselves except ``?'' which
matches any single character, ``*'' which matches any number of
consecutive characters, and ``[chars]'' which matches any single
character of ``chars''. Any character which follows a ``$\backslash$''
matches itself exactly, and a ``$\backslash$'' cannot be the last
character in the string.
\subsection{kadm5_create_policy}
\begin{verbatim}
kadm5_ret_t
kadm5_create_policy(void *server_handle,
kadm5_policy_ent_t policy, u_int32 mask);
\end{verbatim}
Create a new policy.
AUTHORIZATION REQUIRED: add
\begin{enumerate}
\item Check to see if mask is valid, if not return KADM5_BAD_MASK error.
\item Return KADM5_BAD_POLICY if the policy name contains illegal
characters.
\item Check to see if the policy already exists, if so return
KADM5_DUP error.
\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
3, 4, or 5, return KADM5_BAD_CLASS.
\item Create a new policy setting the appropriate fields determined
by the mask.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_DUP] Policy already exists
\item[KADM5_BAD_MASK] The mask is not valid for a create
operation.
\item[KADM5_BAD_CLASS] The specified number of character classes
is invalid.
\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
\end{description}
\subsection{kadm5_delete_policy}
\begin{verbatim}
kadm5_ret_t
kadm5_delete_policy(void *server_handle, char *policy);
\end{verbatim}
Deletes a policy.
AUTHORIZATION REQUIRED: delete
\begin{enumerate}
\item Return KADM5_BAD_POLICY if the policy name contains illegal
characters.
\item Return KADM5_UNK_POLICY if the named policy does not exist.
\item Return KADM5_POLICY_REF if the named policy's refcnt is not 0.
\item Delete policy.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
\item[KADM5_UNK_POLICY] Policy does not exist.
\item[KADM5_POLICY_REF] Policy is being referenced.
\end{description}
\subsection{kadm5_modify_policy}
\begin{verbatim}
kadm5_ret_t
kadm5_modify_policy(void *server_handle,
kadm5_policy_ent_t policy, u_int32 mask);
\end{verbatim}
Modify an existing policy. Note that modifying a policy has no affect
on a principal using the policy until the next time the principal's
password is changed.
AUTHORIZATION REQUIRED: modify
\begin{enumerate}
\item Return KADM5_BAD_POLICY if the policy name contains illegal
characters.
\item Check to see if mask is legal, if not return KADM5_BAD_MASK error.
\item Check to see if policy exists, if not return
KADM5_UNK_POLICY error.
\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
3, 4, or 5, return KADM5_BAD_CLASS.
\item Update the fields specified in the mask.
\end{enumerate}
RETURN CODES:
\begin{description}
\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
\item[KADM5_UNK_POLICY] Policy not found.
\item[KADM5_BAD_MASK] The mask is not valid for a modify
operation.
\item[KADM5_BAD_CLASS] The specified number of character classes
is invalid.
\end{description}
\subsection{kadm5_get_policy}
In KADM5_API_VERSION_1:
\begin{verbatim}
kadm5_ret_t
kadm5_get_policy(void *server_handle, char *policy, kadm5_policy_ent_t *ent);
\end{verbatim}
In KADM5_API_VERSION_2:
\begin{verbatim}
kadm5_ret_t
kadm5_get_policy(void *server_handle, char *policy, kadm5_policy_ent_t ent);
\end{verbatim}
AUTHORIZATION REQUIRED: get, or the calling principal's policy being
the same as the policy argument. If the request is authenticated to
the kadmin/changepw service, the get privilege is disregarded.
In KADM5_API_VERSION_1, return the policy's attributes in allocated
memory; if an error is returned entry is set to NULL. In
KADM5_API_VERSION_2, fill in fields of the policy structure allocated
by the caller. The caller must free the returned entry with
kadm5_free_policy_ent
RETURN CODES:
\begin{description}
\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
\item[KADM5_UNK_POLICY] Policy not found.
\end{description}
\subsection{kadm5_get_policies}
\begin{verbatim}
kadm5_ret_t
kadm5_get_policies(void *server_handle, char *exp,
char ***pols, int *count)
\end{verbatim}
Retrieves the list of principal names.
AUTHORIZATION REQUIRED: list
If \v{exp} is NULL, all principal names are retrieved; otherwise,
principal names that match the expression exp are retrieved. \v{pols}
is filled in with a pointer to a NULL-terminated array of strings, and
\v{count} is filled in with the number of principal names in the
array. \v{pols} must be freed with a call to
\v{kadm5_free_name_list}.
All characters in the expression match themselves except ``?'' which
matches any single character, ``*'' which matches any number of
consecutive characters, and ``[chars]'' which matches any single
character of ``chars''. Any character which follows a ``$\backslash$''
matches itself exactly, and a ``$\backslash$'' cannot be the last
character in the string.
\subsection{kadm5_free_principal_ent, _policy_ent}
\begin{verbatim}
void kadm5_free_principal_ent(void *server_handle,
kadm5_principal_ent_t princ);
\end{verbatim}
In KADM5_API_VERSION_1, free the structure and contents allocated by a
call to kadm5_get_principal. In KADM5_API_VERSION_2, free the
contents allocated by a call to kadm5_get_principal.
AUTHORIZATION REQUIRED: none (local operation)
\begin{verbatim}
void kadm5_free_policy_ent(kadm5_policy_ent_t policy);
\end{verbatim}
Free memory that was allocated by a call to kadm5_get_policy. If
the argument is NULL, the function returns succesfully.
AUTHORIZATION REQUIRED: none (local operation)
\subsection{kadm5_free_name_list}
\begin{verbatim}
void kadm5_free_name_list(void *server_handle,
char **names, int *count);
\end{verbatim}
Free the memory that was allocated by kadm5_get_principals or
kadm5_get_policies. names and count must be a matched pair of
values returned from one of those two functions.
\subsection{kadm5_free_key_data}
\begin{verbatim}
void kadm5_free_key_data(void *server_handle,
krb5_int16 *n_key_data, krb5_key_data *key_data)
\end{verbatim}
Free the memory that was allocated by kadm5_randkey_principal.
n_key_data and key_data must be a matched pair of values returned from
that function.
\subsection{kadm5_get_privs}
\begin{verbatim}
kadm5_ret_t
kadm5_get_privs(void *server_handle, u_int32 *privs);
\end{verbatim}
Return the caller's admin server privileges in the integer pointed to
by the argument. The Admin API does not define any way for a
principal's privileges to be set. Note that this function will
probably be removed or drastically changed in future versions of this
system.
The returned value is a bitmask indicating the caller's privileges:
\begin{tabular}{llr}
{\bf Privilege} & {\bf Symbol} & {\bf Value} \\
Get & KADM5_PRIV_GET & 0x01 \\
Add & KADM5_PRIV_ADD & 0x02 \\
Modify & KADM5_PRIV_MODIFY & 0x04 \\
Delete & KADM5_PRIV_DELETE & 0x08 \\
List & KADM5_PRIV_LIST & 0x10 \\
Changepw & KADM5_PRIV_CPW & 0x20
\end{tabular}
There is no guarantee that a caller will have a privilege indicated by
this function for any length of time or for any particular target;
applications using this function must still be prepared to handle all
possible KADM5_AUTH_* error codes.
In the initial MIT Kerberos version of the admin server, permissions
depend both on the caller and the target; this function returns a
bitmask representing all privileges the caller can possibly have for
any possible target.
\end{document}
|