doc/kadmin/kadmin.protocol

   1
   2 This document references, accompanies and extends the password changing
   3 protocol document, "A Proposal for a Standardized Kerberos Password
   4 Changing Protocol" by Theodore Ts'o.
   5
   6 Administrative Command Extensions to the Password Changing Protocol
   7 ===================================================================
   8 The following commands and their accompanying definitions are an
   9 extension to the password changing protocol which allow remote
  10 administrative clients to perform functions analogous to those which
  11 are performed using the local database editing utility. These
  12 commands are encoded in the "command request" PDU described in the
  13 password changing protocol, and the server's responses to these
  14 commands are encoded in the "command reply" PDU.
  15
  16 These commands are (optional commands are marked with an asterisk, new
  17 or changed commands are marked with a plus sign):
  18         ADD-PRINCIPAL
  19         DELETE-PRINCIPAL
  20         RENAME-PRINCIPAL
  21         MODIFY-PRINCIPAL
  22         OTHER-CHANGEPW
  23         OTHER-RANDOM-CHANGEPW
  24         INQUIRE-PRINCIPAL
  25         EXTRACT-KEY             (*+)
  26         ADD-KEY                 (+)
  27         DELETE-KEY              (+)
  28
  29 In order to support these additional commands, the following additional
  30 status codes are also defined:
  31
  32 Number  Symbolic Name           Meaning
  33 64      P_ALREADY_EXISTS        The specified principal already exists.
  34 65      P_DOES_NOT_EXIST        The specified principal does not exist.
  35 66      NOT_AUTHORIZED          The access control list on the server prevents
  36                                 this operation.
  37 67      BAD_OPTION              Either: 1) A bad option was specified; 2) A
  38                                 conflicting set of options would result from
  39                                 this operation; or 3) Existing options prevent
  40                                 this type of operation.
  41 68      VALUE_REQUIRED          The specified option requires a value.
  42 69      SYSTEM_ERROR            A system error occurred while processing a
  43                                 request.
  44 70(+)   KEY_ALREADY_EXISTS      The specified key already exists.
  45 71(+)   KEY_DOES_NOT_EXIST      The specified key does not exist.
  46
  47 The add principal operation
  48 ---------------------------
  49 o Command String                "ADD-PRINCIPAL"
  50 o Arguments
  51         <new-principal-string>  - name of new principal
  52         <keyword-value-pair>    - either "KEYWORD=value" or "KEYWORD".
  53         .
  54         .
  55         .
  56 o Returns
  57         SUCCESS                 - operation successful
  58         SYSTEM_ERROR            - system error
  59         NOT_AUTHORIZED          - not allowed to perform this
  60         P_ALREADY_EXISTS        - new principal already exists
  61         BAD_OPTION              - bad option supplied
  62         VALUE_REQUIRED          - value required with keyword
  63 o Supplemental Returns
  64         NONE                    - if successful
  65         error message text      - if failure
  66 o Description
  67         If the specified principal does not exist, the arguments parse
  68         correctly, and the arguments when combined with defaulted values
  69         do not produce a conflicting set of options then add the specified
  70         principal with the specified attributes.  See below for the list of
  71         settable attributes.
  72 o Access Required
  73         Client principal must have ADD_PRINCIPAL permission.
  74
  75 The delete principal operation
  76 ------------------------------
  77 o Command String                "DELETE-PRINCIPAL"
  78 o Argument
  79         <principal-string>      - principal to delete
  80 o Returns
  81         SUCCESS                 - operation successful
  82         SYSTEM_ERROR            - system error
  83         NOT_AUTHORIZED          - not allowed to perform this
  84         P_DOES_NOT_EXIST        - old principal does not exist
  85 o Supplemental returns
  86         NONE                    - if successful
  87         error message text      - if failure
  88 o Description
  89         If the specified principal exists, then delete it from the database.
  90 o Access Required
  91         Client principal must have DELETE_PRINCIPAL permission.
  92
  93 The rename principal operation
  94 ------------------------------
  95 o Command String                "RENAME-PRINCIPAL"
  96 o Arguments
  97         <orig-principal-string> - original name
  98         <new-principal-string>  - new name
  99 o Returns
 100         SUCCESS                 - operation successful
 101         SYSTEM_ERROR            - system error
 102         NOT_AUTHORIZED          - not allowed to perform this
 103         P_DOES_NOT_EXIST        - old principal does not exist
 104         P_ALREADY_EXISTS        - new principal already exists
 105 o Supplemental Returns
 106         NONE                    - if successful
 107         error message text      - if failure
 108 o Description
 109         If the original principal exists and the new principal name does not
 110         exist, rename the original principal to the specified name.
 111 o Access Required
 112         Client principal must have ADD_PRINCIPAL and DELETE_PRINCIPAL
 113         permission.
 114
 115 The modify principal operation
 116 ------------------------------
 117 o Command String                "MODIFY-PRINCIPAL"
 118 o Arguments
 119         <principal-string>      - name of principal
 120         <keyword-value-pair>    - either KEYWORD=value or KEYWORD.
 121         .
 122         .
 123         .
 124 o Returns
 125         SUCCESS                 - operation successful
 126         SYSTEM_ERROR            - system error
 127         NOT_AUTHORIZED          - not allowed to perform this
 128         P_DOES_NOT_EXIST        - principal doesn't exist
 129         BAD_OPTION              - bad option supplied
 130         VALUE_REQUIRED          - value required with keyword
 131 o Supplemental returns
 132         NONE                    - if successful
 133         error message text      - if failure
 134 o Description
 135         If the specified principal exists, the arguments parse correctly, and
 136         the arguments when combined with existing values do not produce a
 137         conflicting set of options, then modify the specified principal with
 138         the specified attributes.  See below for the list of settable
 139         attributes.
 140 o Access Required
 141         Client principal must have MODIFY_PRINCIPAL permission.
 142
 143 The change password operation
 144 -----------------------------
 145 o Command String                "OTHER-CHANGEPW"
 146 o Arguments
 147         <principal-string>      - principal to change password for
 148         <new-password>          - new password
 149 o Returns
 150         SUCCESS                 - operation successful
 151         PW_UNACCEPT             - specified password is bad
 152         SYSTEM_ERROR            - system error
 153         NOT_AUTHORIZED          - not allowed to perform this
 154         P_DOES_NOT_EXIST        - old principal does not exist
 155         BAD_OPTION              - principal has a random key
 156 o Supplemental returns
 157         NONE                    - if successful
 158         error message text      - if failure
 159 o Description
 160         If the specified principal exists, and does not have a random key,
 161         then change the password to the specified password.  The original
 162         password is NOT required.
 163 o Access Required
 164         Client principal must have CHANGEPW permission.
 165
 166 The change random password command
 167 ----------------------------------
 168 o Command String                "OTHER-RANDOM-CHANGEPW"
 169 o Argument
 170         <principal-string>      - principal to change password for
 171 o Returns
 172         SUCCESS                 - operation successful
 173         SYSTEM_ERROR            - system error
 174         NOT_AUTHORIZED          - not allowed to perform this
 175         P_DOES_NOT_EXIST        - old principal does not exist
 176         BAD_OPTION              - principal does not have a random key
 177 o Supplemental Returns
 178         NONE                    - if successful
 179         error message text      - if failure
 180 o Description
 181         If the specified principal exists, and has a random key, then
 182         generate a new random password. The original password is NOT
 183         required.
 184 o Access Required
 185         Client principal must have CHANGEPW permission.
 186
 187 The inquire principal command
 188 -----------------------------
 189 o Command String                "INQUIRE-PRINCIPAL"
 190 o Argument
 191         <principal-string>      - name of principal or null argument
 192 o Returns
 193         SUCCESS                 - operation successful
 194         SYSTEM_ERROR            - system error
 195         NOT_AUTHORIZED          - not allowed to perform this
 196         P_DOES_NOT_EXIST        - principal doesn't exist
 197 o Supplemental Returns
 198     If the return is SUCCESS
 199         <next-principal-string> - name of next principal in database
 200         <keyword-value-pair>    - KEYWORD=value list
 201         .
 202         .
 203         .
 204     Otherwise
 205         error message text      - if failure
 206 o Description
 207         If a principal is specified, then the database is searched for that
 208         particular principal and its attributes are returned as keyword-value
 209         pairs.  If no principal is specified, then the first database entry
 210         is returned.  The name of the next principal in the database is always
 211         returned to allow for scanning.  See below for the list of attributes
 212         that can be returned.
 213 o Access Required
 214         Client principal must have INQUIRE_PRINCIPAL permission.
 215
 216 The OPTIONAL extract service key table entry command
 217 ----------------------------------------------------
 218 o Command String                "EXTRACT-KEY"
 219 o Arguments
 220         <instance-string>       - instance to extract for
 221         <name-string>           - name to extract for
 222 o Returns
 223         SUCCESS                 - operation successful
 224         CMD_UNKNOWN             - operation not supported by server
 225         SYSTEM_ERROR            - system error
 226         NOT_AUTHORIZED          - not allowed to perform this
 227         P_DOES_NOT_EXIST        - principal does not exist
 228 o Supplemental Returns
 229         <keytab-entry>          - if successful
 230         error message text      - if failure
 231 o Description
 232         If the specified name/instance exists in the database, then
 233         extract the service key entry and return it in <keytab-entry>.
 234         The description of <keytab-entry> follows below.
 235 o Access Required
 236         Client principal must have EXTRACT permission.
 237
 238 The add key operation
 239 ---------------------
 240 o Command String                "ADD-KEY"
 241 o Arguments
 242         <principal-string>      - name of the principal
 243         <password>              - current password value
 244         <keyname>               - name of the key in the form
 245                                   <keytype>:<salttype>.
 246         .
 247         .
 248         .
 249 o Returns
 250         SUCCESS                 - operation successful
 251         SYSTEM_ERROR            - system error
 252         NOT_AUTHORIZED          - not authorized to perform this
 253         KEY_ALREADY_EXISTS      - one or more of the specified
 254                                   keytypes already exist.
 255         BAD_OPTION              - bad keytype:saltype specified
 256         BAD_PW                  - supplied password is incorrect
 257 o Supplemental Returns
 258         NONE                    - if successful
 259         error message text      - if failure
 260 o Description
 261         If the specified principal exists, the keyname(s) parse
 262         correctly the specified password is successfully verified
 263         against the existing key(s), and the specified keyname(s) do
 264         not exist, then these keytype(s) are added to the principal.
 265 o Access Required
 266         Client principal must have MODIFY_PRINCIPAL permission.
 267
 268 The delete key operation
 269 ------------------------
 270 o Command String                "DELETE-KEY"
 271 o Arguments
 272         <principal-string>      - name of the principal
 273         <password>              - current password value
 274         <keyname>               - name of the key in the form
 275                                   <keytype>:<salttype>, or name of the
 276                                   key in the form <keytype>:<salttype>:
 277                                   <key-version>
 278         .
 279         .
 280         .
 281 o Returns
 282         SUCCESS                 - operation successful
 283         SYSTEM_ERROR            - system error
 284         NOT_AUTHORIZED          - not authorized to perform this
 285         KEY_DOES_NOT_EXIST      - one or more of the specified
 286                                   keytypes do not exist.
 287         BAD_OPTION              - bad keytype:saltype specified
 288         BAD_PW                  - supplied password is incorrect
 289 o Supplemental Returns
 290         NONE                    - if successful
 291         error message text      - if failure
 292 o Description
 293         If the specified principal exists, the keyname(s) parse
 294         correctly the specified password is successfully verified
 295         against the existing key(s), and the specified keyname(s)
 296         exist, then they are deleted from the principal.
 297 o Access Required
 298         Client principal must have MODIFY_PRINCIPAL permission.
 299
 300 Keywords
 301 --------
 302 The following list of keywords are used for the ADD-PRINCIPAL and
 303 MODIFY-PRINCIPAL commands and are returned from the
 304 INQUIRE-PRINCIPAL command.
 305
 306 Valid   Keyword         Value Type      Value
 307 ------- --------------- --------------- --------------------------------------
 308   (S)   PASSWORD        <string>        New password.
 309   (SR)  MAXLIFE         <integer>       The maximum lifetime of tickets for
 310                                         this principal in seconds.
 311   (SR)  MAXRENEWLIFE    <integer>       The maximum renewable lifetime of
 312                                         tickets for this principal in seconds.
 313   (SR)  EXPIRATION      <general-time>  When the new principal expires.
 314   (SR)  PWEXPIRATION    <general-time>  When the password expires for this
 315                                         principal.
 316   (SR)  RANDOMKEY       <integer>       Specifies that this is to have a
 317                                         random key generated for it.
 318   (SR)  FLAGS           <integer>       Specifies flag value for this
 319                                         principal's attributes field in the
 320                                         database.
 321   (R)   LASTSUCCESS     <general-time>  Last successful password entry.
 322   (R)   LASTFAILED      <general-time>  Last failed password attempt.
 323   (R)   FAILCOUNT       <integer>       Number of failed password attempts.
 324   (SR)  AUXDATA         <tagged-value>  Tagged auxiliary value (see below)
 325   (R)   KEYDATA         <key-value>     Key value (see below)
 326   (SR)  EXTRADATA       <unspecified>   Extra data (see below)
 327
 328 The valid field indicates whether an attribute is Settable (e.g. appropriate
 329 for use with ADD-PRINCIPAL, et. al.; Returnable (e.g. returned by
 330 INQUIRE-PRINCIPAL); or both Settable and Returnable.
 331
 332 o <tagged-value>
 333 The <tagged-value> type denotes data which is stored in the database as a
 334 tagged value.  The protocol representation consists of a 4-byte network order
 335 integer to denote the tag with the remaining data providing the value.  If
 336 encoded data is to be encapsulated, it must be in network order.  In summary:
 337         AUXDATA=<tag><value>
 338 For example, to encode the value for tag 1 with a 4-byte value of 32 71 1e 30
 339 in network order, the encoding would be:
 340         AUXDATA=00 00 00 01 32 71 1e 30
 341
 342 o <key-value>
 343 The <key-value> type denotes data which is stored in the database on a per-key
 344 basis.  The protocol representation is consists of a 4-byte network order
 345 integer to denote a particular key.  This integer is implementation dependent
 346 and is only used to correlate different <key-value> entries.  This integer
 347 is followed by a 4-byte network order integer which denotes the attribute type.
 348 Currently, only three are supported: -1 denotes the key version; 1 denotes the
 349 key type and 2 denotes the salt type.  This attribute type integer is followed
 350 by the attribute value and an optional per-attribute value.  In summary:
 351         KEYDATA=<key-tag><attribute><attribute-value>[<per-attribute-value>]
 352 For example, to encode the value of a key with keytype 3, salttype 5, with key
 353 version number 32, key data of 12 34 56 78 90 ab cd ef and salt data of f0 e1
 354 d2 c3 b4 a5 96 87, the encoding would be (using key-tag de ad be ef):
 355         (key version number 32)
 356         KEYDATA=de ad be ef ff ff ff ff 00 00 00 20
 357         (key keytype 3, value 1234567890abcdef)
 358         KEYDATA=de ad be ef 00 00 00 01 00 00 00 03 12 34 56 78 90 ab cd ef
 359         (key salttype 5, value f0e1d2c3b4a59687)
 360         KEYDATA=de ad be ef 00 00 00 02 00 00 00 05 f0 e1 d2 c3 b4 a5 96 87
 361
 362 o <unspecified>
 363 The <unspecified> type is exactly that.  Unspecified.  Any data may be encoded
 364 here without restriction.
 365
 366 Keytab Entry
 367 ------------
 368 If the EXTRACT SERVICE KEY function is supported, then the successful
 369 response to this command is the key entry.  This is a series of 6
 370 reply components as follows:
 371
 372 component       type            value
 373 ---------       --------------- -----------------------------------------
 374         1       <string>        Principal name
 375         2       <integer>       Key entry timestamp
 376         3       <integer>       Key's version number.
 377         4       <integer>       Key's keytype.
 378         5       <integer>       Key's encryption type.
 379         6       <octet-string>  Key's key value.
 380
 381 All of these components are mandatory.
 382