include/kadm5/admin.h

0001 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
0002 /* lib/kadm5/admin.h */
0003 /*
0004  * Copyright 2001, 2008 by the Massachusetts Institute of Technology.
0005  * All Rights Reserved.
0006  *
0007  * Export of this software from the United States of America may
0008  *   require a specific license from the United States Government.
0009  *   It is the responsibility of any person or organization contemplating
0010  *   export to obtain such a license before exporting.
0011  *
0012  * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
0013  * distribute this software and its documentation for any purpose and
0014  * without fee is hereby granted, provided that the above copyright
0015  * notice appear in all copies and that both that copyright notice and
0016  * this permission notice appear in supporting documentation, and that
0017  * the name of M.I.T. not be used in advertising or publicity pertaining
0018  * to distribution of the software without specific, written prior
0019  * permission.  Furthermore if you modify this software you must label
0020  * your software as modified software and not distribute it in such a
0021  * fashion that it might be confused with the original M.I.T. software.
0022  * M.I.T. makes no representations about the suitability of
0023  * this software for any purpose.  It is provided "as is" without express
0024  * or implied warranty.
0025  */
0026 /*
0027  * Copyright 1993 OpenVision Technologies, Inc., All Rights Reserved
0028  *
0029  * $Header$
0030  */
0031
0032 /*
0033  * This API is not considered as stable as the main krb5 API.
0034  *
0035  * - We may make arbitrary incompatible changes between feature
0036  *   releases (e.g. from 1.7 to 1.8).
0037  * - We will make some effort to avoid making incompatible changes for
0038  *   bugfix releases, but will make them if necessary.
0039  */
0040
0041 #ifndef __KADM5_ADMIN_H__
0042 #define __KADM5_ADMIN_H__
0043
0044 #include        <sys/types.h>
0045 #include        <gssrpc/rpc.h>
0046 #include        <krb5.h>
0047 #include        <kdb.h>
0048 #include        <com_err.h>
0049 #include        <kadm5/kadm_err.h>
0050 #include        <kadm5/chpass_util_strings.h>
0051
0052 #ifndef KADM5INT_BEGIN_DECLS
0053 #if defined(__cplusplus)
0054 #define KADM5INT_BEGIN_DECLS    extern "C" {
0055 #define KADM5INT_END_DECLS      }
0056 #else
0057 #define KADM5INT_BEGIN_DECLS
0058 #define KADM5INT_END_DECLS
0059 #endif
0060 #endif
0061
0062 KADM5INT_BEGIN_DECLS
0063
0064 #define KADM5_ADMIN_SERVICE     "kadmin/admin"
0065 #define KADM5_CHANGEPW_SERVICE  "kadmin/changepw"
0066 #define KADM5_HIST_PRINCIPAL    "kadmin/history"
0067 #define KADM5_KIPROP_HOST_SERVICE "kiprop"
0068
0069 typedef krb5_principal  kadm5_princ_t;
0070 typedef char            *kadm5_policy_t;
0071 typedef long            kadm5_ret_t;
0072
0073 #define KADM5_PW_FIRST_PROMPT                           \
0074     (error_message(CHPASS_UTIL_NEW_PASSWORD_PROMPT))
0075 #define KADM5_PW_SECOND_PROMPT                                  \
0076     (error_message(CHPASS_UTIL_NEW_PASSWORD_AGAIN_PROMPT))
0077
0078 /*
0079  * Successful return code
0080  */
0081 #define KADM5_OK        0
0082
0083 /*
0084  * Field masks
0085  */
0086
0087 /* kadm5_principal_ent_t */
0088 #define KADM5_PRINCIPAL         0x000001
0089 #define KADM5_PRINC_EXPIRE_TIME 0x000002
0090 #define KADM5_PW_EXPIRATION     0x000004
0091 #define KADM5_LAST_PWD_CHANGE   0x000008
0092 #define KADM5_ATTRIBUTES        0x000010
0093 #define KADM5_MAX_LIFE          0x000020
0094 #define KADM5_MOD_TIME          0x000040
0095 #define KADM5_MOD_NAME          0x000080
0096 #define KADM5_KVNO              0x000100
0097 #define KADM5_MKVNO             0x000200
0098 #define KADM5_AUX_ATTRIBUTES    0x000400
0099 #define KADM5_POLICY            0x000800
0100 #define KADM5_POLICY_CLR        0x001000
0101 /* version 2 masks */
0102 #define KADM5_MAX_RLIFE         0x002000
0103 #define KADM5_LAST_SUCCESS      0x004000
0104 #define KADM5_LAST_FAILED       0x008000
0105 #define KADM5_FAIL_AUTH_COUNT   0x010000
0106 #define KADM5_KEY_DATA          0x020000
0107 #define KADM5_TL_DATA           0x040000
0108 #ifdef notyet /* Novell */
0109 #define KADM5_CPW_FUNCTION      0x080000
0110 #define KADM5_RANDKEY_USED      0x100000
0111 #endif
0112 #define KADM5_LOAD              0x200000
0113 #define KADM5_KEY_HIST          0x400000
0114
0115 /* all but KEY_DATA, TL_DATA, LOAD */
0116 #define KADM5_PRINCIPAL_NORMAL_MASK 0x41ffff
0117
0118
0119 /* kadm5_policy_ent_t */
0120 #define KADM5_PW_MAX_LIFE               0x00004000
0121 #define KADM5_PW_MIN_LIFE               0x00008000
0122 #define KADM5_PW_MIN_LENGTH             0x00010000
0123 #define KADM5_PW_MIN_CLASSES            0x00020000
0124 #define KADM5_PW_HISTORY_NUM            0x00040000
0125 #define KADM5_REF_COUNT                 0x00080000
0126 #define KADM5_PW_MAX_FAILURE            0x00100000
0127 #define KADM5_PW_FAILURE_COUNT_INTERVAL 0x00200000
0128 #define KADM5_PW_LOCKOUT_DURATION       0x00400000
0129 #define KADM5_POLICY_ATTRIBUTES         0x00800000
0130 #define KADM5_POLICY_MAX_LIFE           0x01000000
0131 #define KADM5_POLICY_MAX_RLIFE          0x02000000
0132 #define KADM5_POLICY_ALLOWED_KEYSALTS   0x04000000
0133 #define KADM5_POLICY_TL_DATA            0x08000000
0134
0135 /* kadm5_config_params */
0136 #define KADM5_CONFIG_REALM              0x00000001
0137 #define KADM5_CONFIG_DBNAME             0x00000002
0138 #define KADM5_CONFIG_MKEY_NAME          0x00000004
0139 #define KADM5_CONFIG_MAX_LIFE           0x00000008
0140 #define KADM5_CONFIG_MAX_RLIFE          0x00000010
0141 #define KADM5_CONFIG_EXPIRATION         0x00000020
0142 #define KADM5_CONFIG_FLAGS              0x00000040
0143 /*#define KADM5_CONFIG_ADMIN_KEYTAB       0x00000080*/
0144 #define KADM5_CONFIG_STASH_FILE         0x00000100
0145 #define KADM5_CONFIG_ENCTYPE            0x00000200
0146 #define KADM5_CONFIG_ADBNAME            0x00000400
0147 #define KADM5_CONFIG_ADB_LOCKFILE       0x00000800
0148 #define KADM5_CONFIG_KADMIND_LISTEN     0x00001000
0149 #define KADM5_CONFIG_ACL_FILE           0x00002000
0150 #define KADM5_CONFIG_KADMIND_PORT       0x00004000
0151 #define KADM5_CONFIG_ENCTYPES           0x00008000
0152 #define KADM5_CONFIG_ADMIN_SERVER       0x00010000
0153 #define KADM5_CONFIG_DICT_FILE          0x00020000
0154 #define KADM5_CONFIG_MKEY_FROM_KBD      0x00040000
0155 #define KADM5_CONFIG_KPASSWD_PORT       0x00080000
0156 #define KADM5_CONFIG_OLD_AUTH_GSSAPI    0x00100000
0157 #define KADM5_CONFIG_NO_AUTH            0x00200000
0158 #define KADM5_CONFIG_AUTH_NOFALLBACK    0x00400000
0159 #define KADM5_CONFIG_KPASSWD_LISTEN     0x00800000
0160 #define KADM5_CONFIG_IPROP_ENABLED      0x01000000
0161 #define KADM5_CONFIG_ULOG_SIZE          0x02000000
0162 #define KADM5_CONFIG_POLL_TIME          0x04000000
0163 #define KADM5_CONFIG_IPROP_LOGFILE      0x08000000
0164 #define KADM5_CONFIG_IPROP_PORT         0x10000000
0165 #define KADM5_CONFIG_KVNO               0x20000000
0166 #define KADM5_CONFIG_IPROP_RESYNC_TIMEOUT   0x40000000
0167 #define KADM5_CONFIG_IPROP_LISTEN       0x80000000
0168 /*
0169  * permission bits
0170  */
0171 #define KADM5_PRIV_GET          0x01
0172 #define KADM5_PRIV_ADD          0x02
0173 #define KADM5_PRIV_MODIFY       0x04
0174 #define KADM5_PRIV_DELETE       0x08
0175
0176 /*
0177  * API versioning constants
0178  */
0179 #define KADM5_MASK_BITS         0xffffff00
0180
0181 #define KADM5_STRUCT_VERSION_MASK       0x12345600
0182 #define KADM5_STRUCT_VERSION_1  (KADM5_STRUCT_VERSION_MASK|0x01)
0183 #define KADM5_STRUCT_VERSION    KADM5_STRUCT_VERSION_1
0184
0185 #define KADM5_API_VERSION_MASK  0x12345700
0186 #define KADM5_API_VERSION_2     (KADM5_API_VERSION_MASK|0x02)
0187 #define KADM5_API_VERSION_3     (KADM5_API_VERSION_MASK|0x03)
0188 #define KADM5_API_VERSION_4     (KADM5_API_VERSION_MASK|0x04)
0189
0190 typedef struct _kadm5_principal_ent_t {
0191     krb5_principal  principal;
0192     krb5_timestamp  princ_expire_time;
0193     krb5_timestamp  last_pwd_change;
0194     krb5_timestamp  pw_expiration;
0195     krb5_deltat     max_life;
0196     krb5_principal  mod_name;
0197     krb5_timestamp  mod_date;
0198     krb5_flags      attributes;
0199     krb5_kvno       kvno;
0200     krb5_kvno       mkvno;
0201     char            *policy;
0202     long            aux_attributes;
0203
0204     /* version 2 fields */
0205     krb5_deltat max_renewable_life;
0206     krb5_timestamp last_success;
0207     krb5_timestamp last_failed;
0208     krb5_kvno fail_auth_count;
0209     krb5_int16 n_key_data;
0210     krb5_int16 n_tl_data;
0211     krb5_tl_data *tl_data;
0212     krb5_key_data *key_data;
0213 } kadm5_principal_ent_rec, *kadm5_principal_ent_t;
0214
0215 typedef struct _kadm5_policy_ent_t {
0216     char            *policy;
0217     long            pw_min_life;
0218     long            pw_max_life;
0219     long            pw_min_length;
0220     long            pw_min_classes;
0221     long            pw_history_num;
0222     long            policy_refcnt;  /* no longer used */
0223
0224     /* version 3 fields */
0225     krb5_kvno       pw_max_fail;
0226     krb5_deltat     pw_failcnt_interval;
0227     krb5_deltat     pw_lockout_duration;
0228
0229     /* version 4 fields */
0230     krb5_flags      attributes;
0231     krb5_deltat     max_life;
0232     krb5_deltat     max_renewable_life;
0233     char            *allowed_keysalts;
0234     krb5_int16      n_tl_data;
0235     krb5_tl_data    *tl_data;
0236 } kadm5_policy_ent_rec, *kadm5_policy_ent_t;
0237
0238 /*
0239  * Data structure returned by kadm5_get_config_params()
0240  */
0241 typedef struct _kadm5_config_params {
0242     long               mask;
0243     char *             realm;
0244     int                kadmind_port;
0245     int                kpasswd_port;
0246
0247     char *             admin_server;
0248 #ifdef notyet /* Novell */ /* ABI change? */
0249     char *             kpasswd_server;
0250 #endif
0251
0252     /* Deprecated except for db2 backwards compatibility.  Don't add
0253        new uses except as fallbacks for parameters that should be
0254        specified in the database module section of the config
0255        file.  */
0256     char *             dbname;
0257
0258     char *             acl_file;
0259     char *             dict_file;
0260
0261     int                mkey_from_kbd;
0262     char *             stash_file;
0263     char *             mkey_name;
0264     krb5_enctype       enctype;
0265     krb5_deltat        max_life;
0266     krb5_deltat        max_rlife;
0267     krb5_timestamp     expiration;
0268     krb5_flags         flags;
0269     krb5_key_salt_tuple *keysalts;
0270     krb5_int32         num_keysalts;
0271     krb5_kvno          kvno;
0272     bool_t              iprop_enabled;
0273     uint32_t            iprop_ulogsize;
0274     krb5_deltat         iprop_poll_time;
0275     char *              iprop_logfile;
0276 /*    char *            iprop_server;*/
0277     int                 iprop_port;
0278     int                 iprop_resync_timeout;
0279     char *              kadmind_listen;
0280     char *              kpasswd_listen;
0281     char *              iprop_listen;
0282 } kadm5_config_params;
0283
0284 typedef struct _kadm5_key_data {
0285     krb5_kvno       kvno;
0286     krb5_keyblock   key;
0287     krb5_keysalt    salt;
0288 } kadm5_key_data;
0289
0290 /*
0291  * functions
0292  */
0293
0294 /* The use_kdc_config parameter is no longer used, as configuration is
0295  * retrieved from the context profile. */
0296 krb5_error_code kadm5_get_config_params(krb5_context context,
0297                                         int use_kdc_config,
0298                                         kadm5_config_params *params_in,
0299                                         kadm5_config_params *params_out);
0300
0301 krb5_error_code kadm5_free_config_params(krb5_context context,
0302                                          kadm5_config_params *params);
0303
0304 krb5_error_code kadm5_get_admin_service_name(krb5_context, char *,
0305                                              char *, size_t);
0306
0307 /*
0308  * For all initialization functions, the caller must first initialize
0309  * a context with kadm5_init_krb5_context which will survive as long
0310  * as the resulting handle.  The caller should free the context with
0311  * krb5_free_context.
0312  */
0313
0314 kadm5_ret_t    kadm5_init(krb5_context context, char *client_name,
0315                           char *pass, char *service_name,
0316                           kadm5_config_params *params,
0317                           krb5_ui_4 struct_version,
0318                           krb5_ui_4 api_version,
0319                           char **db_args,
0320                           void **server_handle);
0321 kadm5_ret_t kadm5_init_anonymous(krb5_context context, char *client_name,
0322                                  char *service_name,
0323                                  kadm5_config_params *params,
0324                                  krb5_ui_4 struct_version,
0325                                  krb5_ui_4 api_version,
0326                                  char **db_args,
0327                                  void **server_handle);
0328 kadm5_ret_t    kadm5_init_with_password(krb5_context context,
0329                                         char *client_name,
0330                                         char *pass,
0331                                         char *service_name,
0332                                         kadm5_config_params *params,
0333                                         krb5_ui_4 struct_version,
0334                                         krb5_ui_4 api_version,
0335                                         char **db_args,
0336                                         void **server_handle);
0337 kadm5_ret_t    kadm5_init_with_skey(krb5_context context,
0338                                     char *client_name,
0339                                     char *keytab,
0340                                     char *service_name,
0341                                     kadm5_config_params *params,
0342                                     krb5_ui_4 struct_version,
0343                                     krb5_ui_4 api_version,
0344                                     char **db_args,
0345                                     void **server_handle);
0346 kadm5_ret_t    kadm5_init_with_creds(krb5_context context,
0347                                      char *client_name,
0348                                      krb5_ccache cc,
0349                                      char *service_name,
0350                                      kadm5_config_params *params,
0351                                      krb5_ui_4 struct_version,
0352                                      krb5_ui_4 api_version,
0353                                      char **db_args,
0354                                      void **server_handle);
0355 kadm5_ret_t    kadm5_lock(void *server_handle);
0356 kadm5_ret_t    kadm5_unlock(void *server_handle);
0357 kadm5_ret_t    kadm5_flush(void *server_handle);
0358 kadm5_ret_t    kadm5_destroy(void *server_handle);
0359 kadm5_ret_t    kadm5_create_principal(void *server_handle,
0360                                       kadm5_principal_ent_t ent,
0361                                       long mask, char *pass);
0362 kadm5_ret_t    kadm5_create_principal_3(void *server_handle,
0363                                         kadm5_principal_ent_t ent,
0364                                         long mask,
0365                                         int n_ks_tuple,
0366                                         krb5_key_salt_tuple *ks_tuple,
0367                                         char *pass);
0368 kadm5_ret_t    kadm5_delete_principal(void *server_handle,
0369                                       krb5_principal principal);
0370 kadm5_ret_t    kadm5_modify_principal(void *server_handle,
0371                                       kadm5_principal_ent_t ent,
0372                                       long mask);
0373 kadm5_ret_t    kadm5_rename_principal(void *server_handle,
0374                                       krb5_principal,krb5_principal);
0375 kadm5_ret_t    kadm5_get_principal(void *server_handle,
0376                                    krb5_principal principal,
0377                                    kadm5_principal_ent_t ent,
0378                                    long mask);
0379 kadm5_ret_t    kadm5_chpass_principal(void *server_handle,
0380                                       krb5_principal principal,
0381                                       char *pass);
0382 kadm5_ret_t    kadm5_chpass_principal_3(void *server_handle,
0383                                         krb5_principal principal,
0384                                         krb5_boolean keepold,
0385                                         int n_ks_tuple,
0386                                         krb5_key_salt_tuple *ks_tuple,
0387                                         char *pass);
0388 kadm5_ret_t    kadm5_randkey_principal(void *server_handle,
0389                                        krb5_principal principal,
0390                                        krb5_keyblock **keyblocks,
0391                                        int *n_keys);
0392 kadm5_ret_t    kadm5_randkey_principal_3(void *server_handle,
0393                                          krb5_principal principal,
0394                                          krb5_boolean keepold,
0395                                          int n_ks_tuple,
0396                                          krb5_key_salt_tuple *ks_tuple,
0397                                          krb5_keyblock **keyblocks,
0398                                          int *n_keys);
0399
0400 kadm5_ret_t    kadm5_setkey_principal(void *server_handle,
0401                                       krb5_principal principal,
0402                                       krb5_keyblock *keyblocks,
0403                                       int n_keys);
0404
0405 kadm5_ret_t    kadm5_setkey_principal_3(void *server_handle,
0406                                         krb5_principal principal,
0407                                         krb5_boolean keepold,
0408                                         int n_ks_tuple,
0409                                         krb5_key_salt_tuple *ks_tuple,
0410                                         krb5_keyblock *keyblocks,
0411                                         int n_keys);
0412
0413 kadm5_ret_t    kadm5_setkey_principal_4(void *server_handle,
0414                                         krb5_principal principal,
0415                                         krb5_boolean keepold,
0416                                         kadm5_key_data *key_data,
0417                                         int n_key_data);
0418
0419 kadm5_ret_t    kadm5_decrypt_key(void *server_handle,
0420                                  kadm5_principal_ent_t entry, krb5_int32
0421                                  ktype, krb5_int32 stype, krb5_int32
0422                                  kvno, krb5_keyblock *keyblock,
0423                                  krb5_keysalt *keysalt, int *kvnop);
0424
0425 kadm5_ret_t    kadm5_create_policy(void *server_handle,
0426                                    kadm5_policy_ent_t ent,
0427                                    long mask);
0428 kadm5_ret_t    kadm5_delete_policy(void *server_handle,
0429                                    kadm5_policy_t policy);
0430 kadm5_ret_t    kadm5_modify_policy(void *server_handle,
0431                                    kadm5_policy_ent_t ent,
0432                                    long mask);
0433 kadm5_ret_t    kadm5_get_policy(void *server_handle,
0434                                 kadm5_policy_t policy,
0435                                 kadm5_policy_ent_t ent);
0436 kadm5_ret_t    kadm5_get_privs(void *server_handle,
0437                                long *privs);
0438
0439 kadm5_ret_t    kadm5_chpass_principal_util(void *server_handle,
0440                                            krb5_principal princ,
0441                                            char *new_pw,
0442                                            char **ret_pw,
0443                                            char *msg_ret,
0444                                            unsigned int msg_len);
0445
0446 kadm5_ret_t    kadm5_free_principal_ent(void *server_handle,
0447                                         kadm5_principal_ent_t
0448                                         ent);
0449 kadm5_ret_t    kadm5_free_policy_ent(void *server_handle,
0450                                      kadm5_policy_ent_t ent);
0451
0452 kadm5_ret_t    kadm5_get_principals(void *server_handle,
0453                                     char *exp, char ***princs,
0454                                     int *count);
0455
0456 kadm5_ret_t    kadm5_get_policies(void *server_handle,
0457                                   char *exp, char ***pols,
0458                                   int *count);
0459
0460 kadm5_ret_t    kadm5_free_key_data(void *server_handle,
0461                                    krb5_int16 *n_key_data,
0462                                    krb5_key_data *key_data);
0463
0464 kadm5_ret_t    kadm5_free_name_list(void *server_handle, char **names,
0465                                     int count);
0466
0467 krb5_error_code kadm5_init_krb5_context (krb5_context *);
0468
0469 krb5_error_code kadm5_init_iprop(void *server_handle, char **db_args);
0470
0471 kadm5_ret_t    kadm5_get_principal_keys(void *server_handle,
0472                                         krb5_principal principal,
0473                                         krb5_kvno kvno,
0474                                         kadm5_key_data **key_data,
0475                                         int *n_key_data);
0476
0477 kadm5_ret_t    kadm5_purgekeys(void *server_handle,
0478                                krb5_principal principal,
0479                                int keepkvno);
0480
0481 kadm5_ret_t    kadm5_get_strings(void *server_handle,
0482                                  krb5_principal principal,
0483                                  krb5_string_attr **strings_out,
0484                                  int *count_out);
0485
0486 kadm5_ret_t    kadm5_set_string(void *server_handle,
0487                                 krb5_principal principal,
0488                                 const char *key,
0489                                 const char *value);
0490
0491 kadm5_ret_t    kadm5_free_strings(void *server_handle,
0492                                   krb5_string_attr *strings,
0493                                   int count);
0494
0495 kadm5_ret_t    kadm5_free_kadm5_key_data(krb5_context context, int n_key_data,
0496                                          kadm5_key_data *key_data);
0497
0498 KADM5INT_END_DECLS
0499
0500 #endif /* __KADM5_ADMIN_H__ */