source/nsswitch/libwbclient/wbclient.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    Winbind client API
   5
   6    Copyright (C) Gerald (Jerry) Carter 2007
   7
   8    This library is free software; you can redistribute it and/or
   9    modify it under the terms of the GNU Lesser General Public
  10    License as published by the Free Software Foundation; either
  11    version 3 of the License, or (at your option) any later version.
  12
  13    This library is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16    Library General Public License for more details.
  17
  18    You should have received a copy of the GNU Lesser General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  20 */
  21
  22 #ifndef _WBCLIENT_H
  23 #define _WBCLIENT_H
  24
  25 #include <pwd.h>
  26 #include <grp.h>
  27
  28 /* Define error types */
  29
  30 /**
  31  *  @brief Status codes returned from wbc functions
  32  **/
  33
  34 enum _wbcErrType {
  35         WBC_ERR_SUCCESS = 0,    /**< Successful completion **/
  36         WBC_ERR_NOT_IMPLEMENTED,/**< Function not implemented **/
  37         WBC_ERR_UNKNOWN_FAILURE,/**< General failure **/
  38         WBC_ERR_NO_MEMORY,      /**< Memory allocation error **/
  39         WBC_ERR_INVALID_SID,    /**< Invalid SID format **/
  40         WBC_ERR_INVALID_PARAM,  /**< An Invalid parameter was supplied **/
  41         WBC_ERR_WINBIND_NOT_AVAILABLE,   /**< Winbind daemon is not available **/
  42         WBC_ERR_DOMAIN_NOT_FOUND,        /**< Domain is not trusted or cannot be found **/
  43         WBC_ERR_INVALID_RESPONSE,        /**< Winbind returned an invalid response **/
  44         WBC_ERR_NSS_ERROR,            /**< NSS_STATUS error **/
  45         WBC_ERR_AUTH_ERROR        /**< Authentication failed **/
  46 };
  47
  48 typedef enum _wbcErrType wbcErr;
  49
  50 #define WBC_ERROR_IS_OK(x) ((x) == WBC_ERR_SUCCESS)
  51
  52 const char *wbcErrorString(wbcErr error);
  53
  54 /**
  55  *  @brief Some useful details about the running winbindd
  56  *
  57  **/
  58 struct wbcInterfaceDetails {
  59         uint32_t interface_version;
  60         const char *winbind_version;
  61         char winbind_separator;
  62         const char *netbios_name;
  63         const char *netbios_domain;
  64         const char *dns_domain;
  65 };
  66
  67 /*
  68  * Data types used by the Winbind Client API
  69  */
  70
  71 #ifndef MAXSUBAUTHS
  72 #define MAXSUBAUTHS 15 /* max sub authorities in a SID */
  73 #endif
  74
  75 /**
  76  *  @brief Windows Security Identifier
  77  *
  78  **/
  79
  80 struct wbcDomainSid {
  81         uint8_t   sid_rev_num;
  82         uint8_t   num_auths;
  83         uint8_t   id_auth[6];
  84         uint32_t  sub_auths[MAXSUBAUTHS];
  85 };
  86
  87 /**
  88  * @brief Security Identifier type
  89  **/
  90
  91 enum wbcSidType {
  92         WBC_SID_NAME_USE_NONE=0,
  93         WBC_SID_NAME_USER=1,
  94         WBC_SID_NAME_DOM_GRP=2,
  95         WBC_SID_NAME_DOMAIN=3,
  96         WBC_SID_NAME_ALIAS=4,
  97         WBC_SID_NAME_WKN_GRP=5,
  98         WBC_SID_NAME_DELETED=6,
  99         WBC_SID_NAME_INVALID=7,
 100         WBC_SID_NAME_UNKNOWN=8,
 101         WBC_SID_NAME_COMPUTER=9
 102 };
 103
 104 /**
 105  * @brief Security Identifier with attributes
 106  **/
 107
 108 struct wbcSidWithAttr {
 109         struct wbcDomainSid sid;
 110         uint32_t attributes;
 111 };
 112
 113 /* wbcSidWithAttr->attributes */
 114
 115 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
 116 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
 117 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
 118 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
 119 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
 120 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
 121 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
 122
 123 /**
 124  * @brief Domain Information
 125  **/
 126
 127 struct wbcDomainInfo {
 128         char *short_name;
 129         char *dns_name;
 130         struct wbcDomainSid sid;
 131         uint32_t domain_flags;
 132         uint32_t trust_flags;
 133         uint32_t trust_type;
 134 };
 135
 136 /* wbcDomainInfo->domain_flags */
 137
 138 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
 139 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
 140 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
 141 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
 142 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
 143
 144 /* wbcDomainInfo->trust_flags */
 145
 146 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
 147 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
 148 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
 149
 150 /* wbcDomainInfo->trust_type */
 151
 152 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
 153 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
 154 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
 155 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
 156
 157
 158 /**
 159  * @brief Auth User Parameters
 160  **/
 161
 162 struct wbcAuthUserParams {
 163         const char *account_name;
 164         const char *domain_name;
 165         const char *workstation_name;
 166
 167         uint32_t flags;
 168
 169         uint32_t parameter_control;
 170
 171         enum wbcAuthUserLevel {
 172                 WBC_AUTH_USER_LEVEL_PLAIN = 1,
 173                 WBC_AUTH_USER_LEVEL_HASH = 2,
 174                 WBC_AUTH_USER_LEVEL_RESPONSE = 3
 175         } level;
 176         union {
 177                 const char *plaintext;
 178                 struct {
 179                         uint8_t nt_hash[16];
 180                         uint8_t lm_hash[16];
 181                 } hash;
 182                 struct {
 183                         uint8_t challenge[8];
 184                         uint32_t nt_length;
 185                         uint8_t *nt_data;
 186                         uint32_t lm_length;
 187                         uint8_t *lm_data;
 188                 } response;
 189         } password;
 190 };
 191
 192 /* wbcAuthUserParams->parameter_control */
 193
 194 #define WBC_MSV1_0_CLEARTEXT_PASSWORD_ALLOWED           0x00000002
 195 #define WBC_MSV1_0_UPDATE_LOGON_STATISTICS              0x00000004
 196 #define WBC_MSV1_0_RETURN_USER_PARAMETERS               0x00000008
 197 #define WBC_MSV1_0_ALLOW_SERVER_TRUST_ACCOUNT           0x00000020
 198 #define WBC_MSV1_0_RETURN_PROFILE_PATH                  0x00000200
 199 #define WBC_MSV1_0_ALLOW_WORKSTATION_TRUST_ACCOUNT      0x00000800
 200
 201 /* wbcAuthUserParams->flags */
 202
 203 #define WBC_AUTH_PARAM_FLAGS_INTERACTIVE_LOGON          0x00000001
 204
 205 /**
 206  * @brief Auth User Information
 207  *
 208  * Some of the strings are maybe NULL
 209  **/
 210
 211 struct wbcAuthUserInfo {
 212         uint32_t user_flags;
 213
 214         char *account_name;
 215         char *user_principal;
 216         char *full_name;
 217         char *domain_name;
 218         char *dns_domain_name;
 219
 220         uint32_t acct_flags;
 221         uint8_t user_session_key[16];
 222         uint8_t lm_session_key[8];
 223
 224         uint16_t logon_count;
 225         uint16_t bad_password_count;
 226
 227         uint64_t logon_time;
 228         uint64_t logoff_time;
 229         uint64_t kickoff_time;
 230         uint64_t pass_last_set_time;
 231         uint64_t pass_can_change_time;
 232         uint64_t pass_must_change_time;
 233
 234         char *logon_server;
 235         char *logon_script;
 236         char *profile_path;
 237         char *home_directory;
 238         char *home_drive;
 239
 240         /*
 241          * the 1st one is the account sid
 242          * the 2nd one is the primary_group sid
 243          * followed by the rest of the groups
 244          */
 245         uint32_t num_sids;
 246         struct wbcSidWithAttr *sids;
 247 };
 248
 249 /* wbcAuthUserInfo->user_flags */
 250
 251 #define WBC_AUTH_USER_INFO_GUEST                        0x00000001
 252 #define WBC_AUTH_USER_INFO_NOENCRYPTION                 0x00000002
 253 #define WBC_AUTH_USER_INFO_CACHED_ACCOUNT               0x00000004
 254 #define WBC_AUTH_USER_INFO_USED_LM_PASSWORD             0x00000008
 255 #define WBC_AUTH_USER_INFO_EXTRA_SIDS                   0x00000020
 256 #define WBC_AUTH_USER_INFO_SUBAUTH_SESSION_KEY          0x00000040
 257 #define WBC_AUTH_USER_INFO_SERVER_TRUST_ACCOUNT         0x00000080
 258 #define WBC_AUTH_USER_INFO_NTLMV2_ENABLED               0x00000100
 259 #define WBC_AUTH_USER_INFO_RESOURCE_GROUPS              0x00000200
 260 #define WBC_AUTH_USER_INFO_PROFILE_PATH_RETURNED        0x00000400
 261 #define WBC_AUTH_USER_INFO_GRACE_LOGON                  0x01000000
 262
 263 /* wbcAuthUserInfo->acct_flags */
 264
 265 #define WBC_ACB_DISABLED                        0x00000001 /* 1 User account disabled */
 266 #define WBC_ACB_HOMDIRREQ                       0x00000002 /* 1 Home directory required */
 267 #define WBC_ACB_PWNOTREQ                        0x00000004 /* 1 User password not required */
 268 #define WBC_ACB_TEMPDUP                         0x00000008 /* 1 Temporary duplicate account */
 269 #define WBC_ACB_NORMAL                          0x00000010 /* 1 Normal user account */
 270 #define WBC_ACB_MNS                             0x00000020 /* 1 MNS logon user account */
 271 #define WBC_ACB_DOMTRUST                        0x00000040 /* 1 Interdomain trust account */
 272 #define WBC_ACB_WSTRUST                         0x00000080 /* 1 Workstation trust account */
 273 #define WBC_ACB_SVRTRUST                        0x00000100 /* 1 Server trust account */
 274 #define WBC_ACB_PWNOEXP                         0x00000200 /* 1 User password does not expire */
 275 #define WBC_ACB_AUTOLOCK                        0x00000400 /* 1 Account auto locked */
 276 #define WBC_ACB_ENC_TXT_PWD_ALLOWED             0x00000800 /* 1 Encryped text password is allowed */
 277 #define WBC_ACB_SMARTCARD_REQUIRED              0x00001000 /* 1 Smart Card required */
 278 #define WBC_ACB_TRUSTED_FOR_DELEGATION          0x00002000 /* 1 Trusted for Delegation */
 279 #define WBC_ACB_NOT_DELEGATED                   0x00004000 /* 1 Not delegated */
 280 #define WBC_ACB_USE_DES_KEY_ONLY                0x00008000 /* 1 Use DES key only */
 281 #define WBC_ACB_DONT_REQUIRE_PREAUTH            0x00010000 /* 1 Preauth not required */
 282 #define WBC_ACB_PW_EXPIRED                      0x00020000 /* 1 Password Expired */
 283 #define WBC_ACB_NO_AUTH_DATA_REQD               0x00080000   /* 1 = No authorization data required */
 284
 285 struct wbcAuthErrorInfo {
 286         uint32_t nt_status;
 287         char *nt_string;
 288         int32_t pam_error;
 289         char *display_string;
 290 };
 291
 292 /*
 293  * Memory Management
 294  */
 295
 296 void wbcFreeMemory(void*);
 297
 298
 299 /*
 300  * Utility functions for dealing with SIDs
 301  */
 302
 303 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
 304                       char **sid_string);
 305
 306 wbcErr wbcStringToSid(const char *sid_string,
 307                       struct wbcDomainSid *sid);
 308
 309 wbcErr wbcPing(void);
 310
 311 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
 312
 313 /*
 314  * Name/SID conversion
 315  */
 316
 317 wbcErr wbcLookupName(const char *dom_name,
 318                      const char *name,
 319                      struct wbcDomainSid *sid,
 320                      enum wbcSidType *name_type);
 321
 322 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
 323                     char **domain,
 324                     char **name,
 325                     enum wbcSidType *name_type);
 326
 327 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
 328                      int num_rids,
 329                      uint32_t *rids,
 330                      const char **domain_name,
 331                      const char ***names,
 332                      enum wbcSidType **types);
 333
 334 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
 335                          bool domain_groups_only,
 336                          uint32_t *num_sids,
 337                          struct wbcDomainSid **sids);
 338
 339 wbcErr wbcListUsers(const char *domain_name,
 340                     uint32_t *num_users,
 341                     const char ***users);
 342
 343 wbcErr wbcListGroups(const char *domain_name,
 344                      uint32_t *num_groups,
 345                      const char ***groups);
 346
 347 /*
 348  * SID/uid/gid Mappings
 349  */
 350
 351 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
 352                    uid_t *puid);
 353
 354 wbcErr wbcUidToSid(uid_t uid,
 355                    struct wbcDomainSid *sid);
 356
 357 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
 358                    gid_t *pgid);
 359
 360 wbcErr wbcGidToSid(gid_t gid,
 361                    struct wbcDomainSid *sid);
 362
 363 wbcErr wbcAllocateUid(uid_t *puid);
 364
 365 wbcErr wbcAllocateGid(gid_t *pgid);
 366
 367 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 368
 369 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 370
 371 wbcErr wbcSetUidHwm(uid_t uid_hwm);
 372
 373 wbcErr wbcSetGidHwm(gid_t gid_hwm);
 374
 375 /*
 376  * NSS Lookup User/Group details
 377  */
 378
 379 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
 380
 381 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
 382
 383 wbcErr wbcGetgrnam(const char *name, struct group **grp);
 384
 385 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
 386
 387 wbcErr wbcSetpwent(void);
 388
 389 wbcErr wbcEndpwent(void);
 390
 391 wbcErr wbcGetpwent(struct passwd **pwd);
 392
 393 wbcErr wbcSetgrent(void);
 394
 395 wbcErr wbcEndgrent(void);
 396
 397 wbcErr wbcGetgrent(struct group **grp);
 398
 399 wbcErr wbcGetGroups(const char *account,
 400                     uint32_t *num_groups,
 401                     gid_t **_groups);
 402
 403
 404 /*
 405  * Lookup Domain information
 406  */
 407
 408 wbcErr wbcDomainInfo(const char *domain,
 409                      struct wbcDomainInfo **info);
 410
 411 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
 412                      size_t *num_domains);
 413
 414
 415 /*
 416  * Athenticate functions
 417  */
 418
 419 wbcErr wbcAuthenticateUser(const char *username,
 420                            const char *password);
 421
 422 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
 423                              struct wbcAuthUserInfo **info,
 424                              struct wbcAuthErrorInfo **error);
 425
 426 /*
 427  * Resolve functions
 428  */
 429 wbcErr wbcResolveWinsByName(const char *name, char **ip);
 430 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
 431
 432 /*
 433  * Trusted domain functions
 434  */
 435 wbcErr wbcCheckTrustCredentials(const char *domain,
 436                                 struct wbcAuthErrorInfo **error);
 437
 438 #endif      /* _WBCLIENT_H */