nsswitch/libwbclient/wbclient.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    Winbind client API
   5
   6    Copyright (C) Gerald (Jerry) Carter 2007
   7    Copyright (C) Volker Lendecke 2009
   8
   9    This library is free software; you can redistribute it and/or
  10    modify it under the terms of the GNU Lesser General Public
  11    License as published by the Free Software Foundation; either
  12    version 3 of the License, or (at your option) any later version.
  13
  14    This library is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17    Library General Public License for more details.
  18
  19    You should have received a copy of the GNU Lesser General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21 */
  22
  23 #ifndef _WBCLIENT_H
  24 #define _WBCLIENT_H
  25
  26 #include <pwd.h>
  27 #include <grp.h>
  28
  29 /* Define error types */
  30
  31 /**
  32  *  @brief Status codes returned from wbc functions
  33  **/
  34
  35 enum _wbcErrType {
  36         WBC_ERR_SUCCESS = 0,    /**< Successful completion **/
  37         WBC_ERR_NOT_IMPLEMENTED,/**< Function not implemented **/
  38         WBC_ERR_UNKNOWN_FAILURE,/**< General failure **/
  39         WBC_ERR_NO_MEMORY,      /**< Memory allocation error **/
  40         WBC_ERR_INVALID_SID,    /**< Invalid SID format **/
  41         WBC_ERR_INVALID_PARAM,  /**< An Invalid parameter was supplied **/
  42         WBC_ERR_WINBIND_NOT_AVAILABLE,   /**< Winbind daemon is not available **/
  43         WBC_ERR_DOMAIN_NOT_FOUND,        /**< Domain is not trusted or cannot be found **/
  44         WBC_ERR_INVALID_RESPONSE,        /**< Winbind returned an invalid response **/
  45         WBC_ERR_NSS_ERROR,            /**< NSS_STATUS error **/
  46         WBC_ERR_AUTH_ERROR,        /**< Authentication failed **/
  47         WBC_ERR_UNKNOWN_USER,      /**< User account cannot be found */
  48         WBC_ERR_UNKNOWN_GROUP,     /**< Group account cannot be found */
  49         WBC_ERR_PWD_CHANGE_FAILED  /**< Password Change has failed */
  50 };
  51
  52 typedef enum _wbcErrType wbcErr;
  53
  54 #define WBC_ERROR_IS_OK(x) ((x) == WBC_ERR_SUCCESS)
  55
  56 const char *wbcErrorString(wbcErr error);
  57
  58 /**
  59  *  @brief Some useful details about the wbclient library
  60  *
  61  *  0.1: Initial version
  62  *  0.2: Added wbcRemoveUidMapping()
  63  *       Added wbcRemoveGidMapping()
  64  *  0.3: Added wbcGetpwsid()
  65  *       Added wbcGetSidAliases()
  66  *  0.4: Added wbcSidTypeString()
  67  *  0.5: Added wbcChangeTrustCredentials()
  68  *  0.6: Made struct wbcInterfaceDetails char* members non-const
  69  **/
  70 #define WBCLIENT_MAJOR_VERSION 0
  71 #define WBCLIENT_MINOR_VERSION 6
  72 #define WBCLIENT_VENDOR_VERSION "Samba libwbclient"
  73 struct wbcLibraryDetails {
  74         uint16_t major_version;
  75         uint16_t minor_version;
  76         const char *vendor_version;
  77 };
  78
  79 /**
  80  *  @brief Some useful details about the running winbindd
  81  *
  82  **/
  83 struct wbcInterfaceDetails {
  84         uint32_t interface_version;
  85         char *winbind_version;
  86         char winbind_separator;
  87         char *netbios_name;
  88         char *netbios_domain;
  89         char *dns_domain;
  90 };
  91
  92 /*
  93  * Data types used by the Winbind Client API
  94  */
  95
  96 #ifndef WBC_MAXSUBAUTHS
  97 #define WBC_MAXSUBAUTHS 15 /* max sub authorities in a SID */
  98 #endif
  99
 100 /**
 101  *  @brief Windows Security Identifier
 102  *
 103  **/
 104
 105 struct wbcDomainSid {
 106         uint8_t   sid_rev_num;
 107         uint8_t   num_auths;
 108         uint8_t   id_auth[6];
 109         uint32_t  sub_auths[WBC_MAXSUBAUTHS];
 110 };
 111
 112 /**
 113  * @brief Security Identifier type
 114  **/
 115
 116 enum wbcSidType {
 117         WBC_SID_NAME_USE_NONE=0,
 118         WBC_SID_NAME_USER=1,
 119         WBC_SID_NAME_DOM_GRP=2,
 120         WBC_SID_NAME_DOMAIN=3,
 121         WBC_SID_NAME_ALIAS=4,
 122         WBC_SID_NAME_WKN_GRP=5,
 123         WBC_SID_NAME_DELETED=6,
 124         WBC_SID_NAME_INVALID=7,
 125         WBC_SID_NAME_UNKNOWN=8,
 126         WBC_SID_NAME_COMPUTER=9
 127 };
 128
 129 /**
 130  * @brief Security Identifier with attributes
 131  **/
 132
 133 struct wbcSidWithAttr {
 134         struct wbcDomainSid sid;
 135         uint32_t attributes;
 136 };
 137
 138 /* wbcSidWithAttr->attributes */
 139
 140 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
 141 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
 142 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
 143 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
 144 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
 145 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
 146 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
 147
 148 /**
 149  *  @brief Windows GUID
 150  *
 151  **/
 152
 153 struct wbcGuid {
 154         uint32_t time_low;
 155         uint16_t time_mid;
 156         uint16_t time_hi_and_version;
 157         uint8_t clock_seq[2];
 158         uint8_t node[6];
 159 };
 160
 161 /**
 162  * @brief Domain Information
 163  **/
 164
 165 struct wbcDomainInfo {
 166         char *short_name;
 167         char *dns_name;
 168         struct wbcDomainSid sid;
 169         uint32_t domain_flags;
 170         uint32_t trust_flags;
 171         uint32_t trust_type;
 172 };
 173
 174 /* wbcDomainInfo->domain_flags */
 175
 176 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
 177 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
 178 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
 179 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
 180 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
 181
 182 /* wbcDomainInfo->trust_flags */
 183
 184 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
 185 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
 186 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
 187
 188 /* wbcDomainInfo->trust_type */
 189
 190 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
 191 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
 192 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
 193 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
 194
 195 /**
 196  * @brief Auth User Parameters
 197  **/
 198
 199 struct wbcAuthUserParams {
 200         const char *account_name;
 201         const char *domain_name;
 202         const char *workstation_name;
 203
 204         uint32_t flags;
 205
 206         uint32_t parameter_control;
 207
 208         enum wbcAuthUserLevel {
 209                 WBC_AUTH_USER_LEVEL_PLAIN = 1,
 210                 WBC_AUTH_USER_LEVEL_HASH = 2,
 211                 WBC_AUTH_USER_LEVEL_RESPONSE = 3
 212         } level;
 213         union {
 214                 const char *plaintext;
 215                 struct {
 216                         uint8_t nt_hash[16];
 217                         uint8_t lm_hash[16];
 218                 } hash;
 219                 struct {
 220                         uint8_t challenge[8];
 221                         uint32_t nt_length;
 222                         uint8_t *nt_data;
 223                         uint32_t lm_length;
 224                         uint8_t *lm_data;
 225                 } response;
 226         } password;
 227 };
 228
 229 /**
 230  * @brief Generic Blob
 231  **/
 232
 233 struct wbcBlob {
 234         uint8_t *data;
 235         size_t length;
 236 };
 237
 238 /**
 239  * @brief Named Blob
 240  **/
 241
 242 struct wbcNamedBlob {
 243         const char *name;
 244         uint32_t flags;
 245         struct wbcBlob blob;
 246 };
 247
 248 /**
 249  * @brief Logon User Parameters
 250  **/
 251
 252 struct wbcLogonUserParams {
 253         const char *username;
 254         const char *password;
 255         size_t num_blobs;
 256         struct wbcNamedBlob *blobs;
 257 };
 258
 259 /**
 260  * @brief ChangePassword Parameters
 261  **/
 262
 263 struct wbcChangePasswordParams {
 264         const char *account_name;
 265         const char *domain_name;
 266
 267         uint32_t flags;
 268
 269         enum wbcChangePasswordLevel {
 270                 WBC_CHANGE_PASSWORD_LEVEL_PLAIN = 1,
 271                 WBC_CHANGE_PASSWORD_LEVEL_RESPONSE = 2
 272         } level;
 273
 274         union {
 275                 const char *plaintext;
 276                 struct {
 277                         uint32_t old_nt_hash_enc_length;
 278                         uint8_t *old_nt_hash_enc_data;
 279                         uint32_t old_lm_hash_enc_length;
 280                         uint8_t *old_lm_hash_enc_data;
 281                 } response;
 282         } old_password;
 283         union {
 284                 const char *plaintext;
 285                 struct {
 286                         uint32_t nt_length;
 287                         uint8_t *nt_data;
 288                         uint32_t lm_length;
 289                         uint8_t *lm_data;
 290                 } response;
 291         } new_password;
 292 };
 293
 294 /* wbcAuthUserParams->parameter_control */
 295
 296 #define WBC_MSV1_0_CLEARTEXT_PASSWORD_ALLOWED           0x00000002
 297 #define WBC_MSV1_0_UPDATE_LOGON_STATISTICS              0x00000004
 298 #define WBC_MSV1_0_RETURN_USER_PARAMETERS               0x00000008
 299 #define WBC_MSV1_0_ALLOW_SERVER_TRUST_ACCOUNT           0x00000020
 300 #define WBC_MSV1_0_RETURN_PROFILE_PATH                  0x00000200
 301 #define WBC_MSV1_0_ALLOW_WORKSTATION_TRUST_ACCOUNT      0x00000800
 302
 303 /* wbcAuthUserParams->flags */
 304
 305 #define WBC_AUTH_PARAM_FLAGS_INTERACTIVE_LOGON          0x00000001
 306
 307 /**
 308  * @brief Auth User Information
 309  *
 310  * Some of the strings are maybe NULL
 311  **/
 312
 313 struct wbcAuthUserInfo {
 314         uint32_t user_flags;
 315
 316         char *account_name;
 317         char *user_principal;
 318         char *full_name;
 319         char *domain_name;
 320         char *dns_domain_name;
 321
 322         uint32_t acct_flags;
 323         uint8_t user_session_key[16];
 324         uint8_t lm_session_key[8];
 325
 326         uint16_t logon_count;
 327         uint16_t bad_password_count;
 328
 329         uint64_t logon_time;
 330         uint64_t logoff_time;
 331         uint64_t kickoff_time;
 332         uint64_t pass_last_set_time;
 333         uint64_t pass_can_change_time;
 334         uint64_t pass_must_change_time;
 335
 336         char *logon_server;
 337         char *logon_script;
 338         char *profile_path;
 339         char *home_directory;
 340         char *home_drive;
 341
 342         /*
 343          * the 1st one is the account sid
 344          * the 2nd one is the primary_group sid
 345          * followed by the rest of the groups
 346          */
 347         uint32_t num_sids;
 348         struct wbcSidWithAttr *sids;
 349 };
 350
 351 /**
 352  * @brief Logon User Information
 353  *
 354  * Some of the strings are maybe NULL
 355  **/
 356
 357 struct wbcLogonUserInfo {
 358         struct wbcAuthUserInfo *info;
 359         size_t num_blobs;
 360         struct wbcNamedBlob *blobs;
 361 };
 362
 363 /* wbcAuthUserInfo->user_flags */
 364
 365 #define WBC_AUTH_USER_INFO_GUEST                        0x00000001
 366 #define WBC_AUTH_USER_INFO_NOENCRYPTION                 0x00000002
 367 #define WBC_AUTH_USER_INFO_CACHED_ACCOUNT               0x00000004
 368 #define WBC_AUTH_USER_INFO_USED_LM_PASSWORD             0x00000008
 369 #define WBC_AUTH_USER_INFO_EXTRA_SIDS                   0x00000020
 370 #define WBC_AUTH_USER_INFO_SUBAUTH_SESSION_KEY          0x00000040
 371 #define WBC_AUTH_USER_INFO_SERVER_TRUST_ACCOUNT         0x00000080
 372 #define WBC_AUTH_USER_INFO_NTLMV2_ENABLED               0x00000100
 373 #define WBC_AUTH_USER_INFO_RESOURCE_GROUPS              0x00000200
 374 #define WBC_AUTH_USER_INFO_PROFILE_PATH_RETURNED        0x00000400
 375 #define WBC_AUTH_USER_INFO_GRACE_LOGON                  0x01000000
 376
 377 /* wbcAuthUserInfo->acct_flags */
 378
 379 #define WBC_ACB_DISABLED                        0x00000001 /* 1 User account disabled */
 380 #define WBC_ACB_HOMDIRREQ                       0x00000002 /* 1 Home directory required */
 381 #define WBC_ACB_PWNOTREQ                        0x00000004 /* 1 User password not required */
 382 #define WBC_ACB_TEMPDUP                         0x00000008 /* 1 Temporary duplicate account */
 383 #define WBC_ACB_NORMAL                          0x00000010 /* 1 Normal user account */
 384 #define WBC_ACB_MNS                             0x00000020 /* 1 MNS logon user account */
 385 #define WBC_ACB_DOMTRUST                        0x00000040 /* 1 Interdomain trust account */
 386 #define WBC_ACB_WSTRUST                         0x00000080 /* 1 Workstation trust account */
 387 #define WBC_ACB_SVRTRUST                        0x00000100 /* 1 Server trust account */
 388 #define WBC_ACB_PWNOEXP                         0x00000200 /* 1 User password does not expire */
 389 #define WBC_ACB_AUTOLOCK                        0x00000400 /* 1 Account auto locked */
 390 #define WBC_ACB_ENC_TXT_PWD_ALLOWED             0x00000800 /* 1 Encryped text password is allowed */
 391 #define WBC_ACB_SMARTCARD_REQUIRED              0x00001000 /* 1 Smart Card required */
 392 #define WBC_ACB_TRUSTED_FOR_DELEGATION          0x00002000 /* 1 Trusted for Delegation */
 393 #define WBC_ACB_NOT_DELEGATED                   0x00004000 /* 1 Not delegated */
 394 #define WBC_ACB_USE_DES_KEY_ONLY                0x00008000 /* 1 Use DES key only */
 395 #define WBC_ACB_DONT_REQUIRE_PREAUTH            0x00010000 /* 1 Preauth not required */
 396 #define WBC_ACB_PW_EXPIRED                      0x00020000 /* 1 Password Expired */
 397 #define WBC_ACB_NO_AUTH_DATA_REQD               0x00080000   /* 1 = No authorization data required */
 398
 399 struct wbcAuthErrorInfo {
 400         uint32_t nt_status;
 401         char *nt_string;
 402         int32_t pam_error;
 403         char *display_string;
 404 };
 405
 406 /**
 407  * @brief User Password Policy Information
 408  **/
 409
 410 /* wbcUserPasswordPolicyInfo->password_properties */
 411
 412 #define WBC_DOMAIN_PASSWORD_COMPLEX             0x00000001
 413 #define WBC_DOMAIN_PASSWORD_NO_ANON_CHANGE      0x00000002
 414 #define WBC_DOMAIN_PASSWORD_NO_CLEAR_CHANGE     0x00000004
 415 #define WBC_DOMAIN_PASSWORD_LOCKOUT_ADMINS      0x00000008
 416 #define WBC_DOMAIN_PASSWORD_STORE_CLEARTEXT     0x00000010
 417 #define WBC_DOMAIN_REFUSE_PASSWORD_CHANGE       0x00000020
 418
 419 struct wbcUserPasswordPolicyInfo {
 420         uint32_t min_length_password;
 421         uint32_t password_history;
 422         uint32_t password_properties;
 423         uint64_t expire;
 424         uint64_t min_passwordage;
 425 };
 426
 427 /**
 428  * @brief Change Password Reject Reason
 429  **/
 430
 431 enum wbcPasswordChangeRejectReason {
 432         WBC_PWD_CHANGE_NO_ERROR=0,
 433         WBC_PWD_CHANGE_PASSWORD_TOO_SHORT=1,
 434         WBC_PWD_CHANGE_PWD_IN_HISTORY=2,
 435         WBC_PWD_CHANGE_USERNAME_IN_PASSWORD=3,
 436         WBC_PWD_CHANGE_FULLNAME_IN_PASSWORD=4,
 437         WBC_PWD_CHANGE_NOT_COMPLEX=5,
 438         WBC_PWD_CHANGE_MACHINE_NOT_DEFAULT=6,
 439         WBC_PWD_CHANGE_FAILED_BY_FILTER=7,
 440         WBC_PWD_CHANGE_PASSWORD_TOO_LONG=8
 441 };
 442
 443 /* Note: this defines exist for compatibility reasons with existing code */
 444 #define WBC_PWD_CHANGE_REJECT_OTHER      WBC_PWD_CHANGE_NO_ERROR
 445 #define WBC_PWD_CHANGE_REJECT_TOO_SHORT  WBC_PWD_CHANGE_PASSWORD_TOO_SHORT
 446 #define WBC_PWD_CHANGE_REJECT_IN_HISTORY WBC_PWD_CHANGE_PWD_IN_HISTORY
 447 #define WBC_PWD_CHANGE_REJECT_COMPLEXITY WBC_PWD_CHANGE_NOT_COMPLEX
 448
 449 /**
 450  * @brief Logoff User Parameters
 451  **/
 452
 453 struct wbcLogoffUserParams {
 454         const char *username;
 455         size_t num_blobs;
 456         struct wbcNamedBlob *blobs;
 457 };
 458
 459 /** @brief Credential cache log-on parameters
 460  *
 461  */
 462
 463 struct wbcCredentialCacheParams {
 464         const char *account_name;
 465         const char *domain_name;
 466         enum wbcCredentialCacheLevel {
 467                 WBC_CREDENTIAL_CACHE_LEVEL_NTLMSSP = 1
 468         } level;
 469         size_t num_blobs;
 470         struct wbcNamedBlob *blobs;
 471 };
 472
 473
 474 /** @brief Info returned by credential cache auth
 475  *
 476  */
 477
 478 struct wbcCredentialCacheInfo {
 479         size_t num_blobs;
 480         struct wbcNamedBlob *blobs;
 481 };
 482
 483 /*
 484  * DomainControllerInfo struct
 485  */
 486 struct wbcDomainControllerInfo {
 487         char *dc_name;
 488 };
 489
 490 /*
 491  * DomainControllerInfoEx struct
 492  */
 493 struct wbcDomainControllerInfoEx {
 494         const char *dc_unc;
 495         const char *dc_address;
 496         uint16_t dc_address_type;
 497         struct wbcGuid *domain_guid;
 498         const char *domain_name;
 499         const char *forest_name;
 500         uint32_t dc_flags;
 501         const char *dc_site_name;
 502         const char *client_site_name;
 503 };
 504
 505 /**********************************************************
 506  * Memory Management
 507  **********************************************************/
 508
 509 /**
 510  * @brief Free library allocated memory
 511  *
 512  * @param * Pointer to free
 513  *
 514  * @return void
 515  **/
 516 void wbcFreeMemory(void*);
 517
 518
 519 /*
 520  * Utility functions for dealing with SIDs
 521  */
 522
 523 /**
 524  * @brief Get a string representation of the SID type
 525  *
 526  * @param type          type of the SID
 527  *
 528  * @return string representation of the SID type
 529  */
 530 const char* wbcSidTypeString(enum wbcSidType type);
 531
 532 /**
 533  * @brief Convert a binary SID to a character string
 534  *
 535  * @param sid           Binary Security Identifier
 536  * @param **sid_string  Resulting character string
 537  *
 538  * @return #wbcErr
 539  **/
 540 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
 541                       char **sid_string);
 542
 543 /**
 544  * @brief Convert a character string to a binary SID
 545  *
 546  * @param *sid_string   Character string in the form of S-...
 547  * @param sid           Resulting binary SID
 548  *
 549  * @return #wbcErr
 550  **/
 551 wbcErr wbcStringToSid(const char *sid_string,
 552                       struct wbcDomainSid *sid);
 553
 554 /*
 555  * Utility functions for dealing with GUIDs
 556  */
 557
 558 /**
 559  * @brief Convert a binary GUID to a character string
 560  *
 561  * @param guid           Binary Guid
 562  * @param **guid_string  Resulting character string
 563  *
 564  * @return #wbcErr
 565  **/
 566 wbcErr wbcGuidToString(const struct wbcGuid *guid,
 567                        char **guid_string);
 568
 569 /**
 570  * @brief Convert a character string to a binary GUID
 571  *
 572  * @param *guid_string  Character string
 573  * @param guid          Resulting binary GUID
 574  *
 575  * @return #wbcErr
 576  **/
 577 wbcErr wbcStringToGuid(const char *guid_string,
 578                        struct wbcGuid *guid);
 579
 580 /**
 581  * @brief Ping winbindd to see if the daemon is running
 582  *
 583  * @return #wbcErr
 584  **/
 585 wbcErr wbcPing(void);
 586
 587 wbcErr wbcLibraryDetails(struct wbcLibraryDetails **details);
 588
 589 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
 590
 591 /**********************************************************
 592  * Name/SID conversion
 593  **********************************************************/
 594
 595 /**
 596  * @brief Convert a domain and name to SID
 597  *
 598  * @param dom_name    Domain name (possibly "")
 599  * @param name        User or group name
 600  * @param *sid        Pointer to the resolved domain SID
 601  * @param *name_type  Pointer to the SID type
 602  *
 603  * @return #wbcErr
 604  **/
 605 wbcErr wbcLookupName(const char *dom_name,
 606                      const char *name,
 607                      struct wbcDomainSid *sid,
 608                      enum wbcSidType *name_type);
 609
 610 /**
 611  * @brief Convert a SID to a domain and name
 612  *
 613  * @param *sid        Pointer to the domain SID to be resolved
 614  * @param domain     Resolved Domain name (possibly "")
 615  * @param name       Resolved User or group name
 616  * @param *name_type Pointer to the resolved SID type
 617  *
 618  * @return #wbcErr
 619  **/
 620 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
 621                     char **domain,
 622                     char **name,
 623                     enum wbcSidType *name_type);
 624
 625 /**
 626  * @brief Translate a collection of RIDs within a domain to names
 627  */
 628 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
 629                      int num_rids,
 630                      uint32_t *rids,
 631                      const char **domain_name,
 632                      const char ***names,
 633                      enum wbcSidType **types);
 634
 635 /*
 636  * @brief Get the groups a user belongs to
 637  **/
 638 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
 639                          bool domain_groups_only,
 640                          uint32_t *num_sids,
 641                          struct wbcDomainSid **sids);
 642
 643 /*
 644  * @brief Get alias membership for sids
 645  **/
 646 wbcErr wbcGetSidAliases(const struct wbcDomainSid *dom_sid,
 647                         struct wbcDomainSid *sids,
 648                         uint32_t num_sids,
 649                         uint32_t **alias_rids,
 650                         uint32_t *num_alias_rids);
 651
 652 /**
 653  * @brief Lists Users
 654  **/
 655 wbcErr wbcListUsers(const char *domain_name,
 656                     uint32_t *num_users,
 657                     const char ***users);
 658
 659 /**
 660  * @brief Lists Groups
 661  **/
 662 wbcErr wbcListGroups(const char *domain_name,
 663                      uint32_t *num_groups,
 664                      const char ***groups);
 665
 666 wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid,
 667                          char **pdomain,
 668                          char **pfullname,
 669                          enum wbcSidType *pname_type);
 670
 671 /**********************************************************
 672  * SID/uid/gid Mappings
 673  **********************************************************/
 674
 675 /**
 676  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
 677  *
 678  * @param *sid        Pointer to the domain SID to be resolved
 679  * @param *puid       Pointer to the resolved uid_t value
 680  *
 681  * @return #wbcErr
 682  *
 683  **/
 684 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
 685                    uid_t *puid);
 686
 687 /**
 688  * @brief Convert a Windows SID to a Unix uid if there already is a mapping
 689  *
 690  * @param *sid        Pointer to the domain SID to be resolved
 691  * @param *puid       Pointer to the resolved uid_t value
 692  *
 693  * @return #wbcErr
 694  *
 695  **/
 696 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
 697                         uid_t *puid);
 698
 699 /**
 700  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
 701  *
 702  * @param uid         Unix uid to be resolved
 703  * @param *sid        Pointer to the resolved domain SID
 704  *
 705  * @return #wbcErr
 706  *
 707  **/
 708 wbcErr wbcUidToSid(uid_t uid,
 709                    struct wbcDomainSid *sid);
 710
 711 /**
 712  * @brief Convert a Unix uid to a Windows SID if there already is a mapping
 713  *
 714  * @param uid         Unix uid to be resolved
 715  * @param *sid        Pointer to the resolved domain SID
 716  *
 717  * @return #wbcErr
 718  *
 719  **/
 720 wbcErr wbcQueryUidToSid(uid_t uid,
 721                         struct wbcDomainSid *sid);
 722
 723 /**
 724  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
 725  *
 726  * @param *sid        Pointer to the domain SID to be resolved
 727  * @param *pgid       Pointer to the resolved gid_t value
 728  *
 729  * @return #wbcErr
 730  *
 731  **/
 732 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
 733                    gid_t *pgid);
 734
 735 /**
 736  * @brief Convert a Windows SID to a Unix gid if there already is a mapping
 737  *
 738  * @param *sid        Pointer to the domain SID to be resolved
 739  * @param *pgid       Pointer to the resolved gid_t value
 740  *
 741  * @return #wbcErr
 742  *
 743  **/
 744 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
 745                         gid_t *pgid);
 746
 747 /**
 748  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
 749  *
 750  * @param gid         Unix gid to be resolved
 751  * @param *sid        Pointer to the resolved domain SID
 752  *
 753  * @return #wbcErr
 754  *
 755  **/
 756 wbcErr wbcGidToSid(gid_t gid,
 757                    struct wbcDomainSid *sid);
 758
 759 /**
 760  * @brief Convert a Unix gid to a Windows SID if there already is a mapping
 761  *
 762  * @param gid         Unix gid to be resolved
 763  * @param *sid        Pointer to the resolved domain SID
 764  *
 765  * @return #wbcErr
 766  *
 767  **/
 768 wbcErr wbcQueryGidToSid(gid_t gid,
 769                         struct wbcDomainSid *sid);
 770
 771 /**
 772  * @brief Obtain a new uid from Winbind
 773  *
 774  * @param *puid      *pointer to the allocated uid
 775  *
 776  * @return #wbcErr
 777  **/
 778 wbcErr wbcAllocateUid(uid_t *puid);
 779
 780 /**
 781  * @brief Obtain a new gid from Winbind
 782  *
 783  * @param *pgid      Pointer to the allocated gid
 784  *
 785  * @return #wbcErr
 786  **/
 787 wbcErr wbcAllocateGid(gid_t *pgid);
 788
 789 /**
 790  * @brief Set an user id mapping
 791  *
 792  * @param uid       Uid of the desired mapping.
 793  * @param *sid      Pointer to the sid of the diresired mapping.
 794  *
 795  * @return #wbcErr
 796  *
 797  * @deprecated      This method is not impemented any more and should
 798  *                  be removed in the next major version change.
 799  **/
 800 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 801
 802 /**
 803  * @brief Set a group id mapping
 804  *
 805  * @param gid       Gid of the desired mapping.
 806  * @param *sid      Pointer to the sid of the diresired mapping.
 807  *
 808  * @return #wbcErr
 809  *
 810  * @deprecated      This method is not impemented any more and should
 811  *                  be removed in the next major version change.
 812  **/
 813 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 814
 815 /**
 816  * @brief Remove a user id mapping
 817  *
 818  * @param uid       Uid of the mapping to remove.
 819  * @param *sid      Pointer to the sid of the mapping to remove.
 820  *
 821  * @return #wbcErr
 822  *
 823  * @deprecated      This method is not impemented any more and should
 824  *                  be removed in the next major version change.
 825  **/
 826 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 827
 828 /**
 829  * @brief Remove a group id mapping
 830  *
 831  * @param gid       Gid of the mapping to remove.
 832  * @param *sid      Pointer to the sid of the mapping to remove.
 833  *
 834  * @return #wbcErr
 835  *
 836  * @deprecated      This method is not impemented any more and should
 837  *                  be removed in the next major version change.
 838  **/
 839 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 840
 841 /**
 842  * @brief Set the highwater mark for allocated uids.
 843  *
 844  * @param uid_hwm      The new uid highwater mark value
 845  *
 846  * @return #wbcErr
 847  *
 848  * @deprecated      This method is not impemented any more and should
 849  *                  be removed in the next major version change.
 850  **/
 851 wbcErr wbcSetUidHwm(uid_t uid_hwm);
 852
 853 /**
 854  * @brief Set the highwater mark for allocated gids.
 855  *
 856  * @param gid_hwm      The new gid highwater mark value
 857  *
 858  * @return #wbcErr
 859  *
 860  * @deprecated      This method is not impemented any more and should
 861  *                  be removed in the next major version change.
 862  **/
 863 wbcErr wbcSetGidHwm(gid_t gid_hwm);
 864
 865 /**********************************************************
 866  * NSS Lookup User/Group details
 867  **********************************************************/
 868
 869 /**
 870  * @brief Fill in a struct passwd* for a domain user based
 871  *   on username
 872  *
 873  * @param *name     Username to lookup
 874  * @param **pwd     Pointer to resulting struct passwd* from the query.
 875  *
 876  * @return #wbcErr
 877  **/
 878 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
 879
 880 /**
 881  * @brief Fill in a struct passwd* for a domain user based
 882  *   on uid
 883  *
 884  * @param uid       Uid to lookup
 885  * @param **pwd     Pointer to resulting struct passwd* from the query.
 886  *
 887  * @return #wbcErr
 888  **/
 889 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
 890
 891 /**
 892  * @brief Fill in a struct passwd* for a domain user based
 893  *   on sid
 894  *
 895  * @param sid       Sid to lookup
 896  * @param **pwd     Pointer to resulting struct passwd* from the query.
 897  *
 898  * @return #wbcErr
 899  **/
 900 wbcErr wbcGetpwsid(struct wbcDomainSid * sid, struct passwd **pwd);
 901
 902 /**
 903  * @brief Fill in a struct passwd* for a domain user based
 904  *   on username
 905  *
 906  * @param *name     Username to lookup
 907  * @param **grp     Pointer to resulting struct group* from the query.
 908  *
 909  * @return #wbcErr
 910  **/
 911 wbcErr wbcGetgrnam(const char *name, struct group **grp);
 912
 913 /**
 914  * @brief Fill in a struct passwd* for a domain user based
 915  *   on uid
 916  *
 917  * @param gid       Uid to lookup
 918  * @param **grp     Pointer to resulting struct group* from the query.
 919  *
 920  * @return #wbcErr
 921  **/
 922 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
 923
 924 /**
 925  * @brief Reset the passwd iterator
 926  *
 927  * @return #wbcErr
 928  **/
 929 wbcErr wbcSetpwent(void);
 930
 931 /**
 932  * @brief Close the passwd iterator
 933  *
 934  * @return #wbcErr
 935  **/
 936 wbcErr wbcEndpwent(void);
 937
 938 /**
 939  * @brief Return the next struct passwd* entry from the pwent iterator
 940  *
 941  * @param **pwd       Pointer to resulting struct passwd* from the query.
 942  *
 943  * @return #wbcErr
 944  **/
 945 wbcErr wbcGetpwent(struct passwd **pwd);
 946
 947 /**
 948  * @brief Reset the group iterator
 949  *
 950  * @return #wbcErr
 951  **/
 952 wbcErr wbcSetgrent(void);
 953
 954 /**
 955  * @brief Close the group iterator
 956  *
 957  * @return #wbcErr
 958  **/
 959 wbcErr wbcEndgrent(void);
 960
 961 /**
 962  * @brief Return the next struct group* entry from the pwent iterator
 963  *
 964  * @param **grp       Pointer to resulting struct group* from the query.
 965  *
 966  * @return #wbcErr
 967  **/
 968 wbcErr wbcGetgrent(struct group **grp);
 969
 970 /**
 971  * @brief Return the next struct group* entry from the pwent iterator
 972  *
 973  * This is similar to #wbcGetgrent, just that the member list is empty
 974  *
 975  * @param **grp       Pointer to resulting struct group* from the query.
 976  *
 977  * @return #wbcErr
 978  **/
 979 wbcErr wbcGetgrlist(struct group **grp);
 980
 981 /**
 982  * @brief Return the unix group array belonging to the given user
 983  *
 984  * @param *account       The given user name
 985  * @param *num_groups    Number of elements returned in the groups array
 986  * @param **_groups      Pointer to resulting gid_t array.
 987  *
 988  * @return #wbcErr
 989  **/
 990 wbcErr wbcGetGroups(const char *account,
 991                     uint32_t *num_groups,
 992                     gid_t **_groups);
 993
 994
 995 /**********************************************************
 996  * Lookup Domain information
 997  **********************************************************/
 998
 999 /**
1000  * @brief Lookup the current status of a trusted domain
1001  *
1002  * @param domain        The domain to query
1003  *
1004  * @param dinfo          A pointer to store the returned domain_info struct.
1005  *
1006  * @return #wbcErr
1007  **/
1008 wbcErr wbcDomainInfo(const char *domain,
1009                      struct wbcDomainInfo **dinfo);
1010
1011 /**
1012  * @brief Lookup the currently contacted DCs
1013  *
1014  * @param domain        The domain to query
1015  *
1016  * @param num_dcs       Number of DCs currently known
1017  * @param dc_names      Names of the currently known DCs
1018  * @param dc_ips        IP addresses of the currently known DCs
1019  *
1020  * @return #wbcErr
1021  **/
1022 wbcErr wbcDcInfo(const char *domain, size_t *num_dcs,
1023                  const char ***dc_names, const char ***dc_ips);
1024
1025 /**
1026  * @brief Enumerate the domain trusts known by Winbind
1027  *
1028  * @param **domains     Pointer to the allocated domain list array
1029  * @param *num_domains  Pointer to number of domains returned
1030  *
1031  * @return #wbcErr
1032  **/
1033 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
1034                      size_t *num_domains);
1035
1036 /* Flags for wbcLookupDomainController */
1037
1038 #define WBC_LOOKUP_DC_FORCE_REDISCOVERY        0x00000001
1039 #define WBC_LOOKUP_DC_DS_REQUIRED              0x00000010
1040 #define WBC_LOOKUP_DC_DS_PREFERRED             0x00000020
1041 #define WBC_LOOKUP_DC_GC_SERVER_REQUIRED       0x00000040
1042 #define WBC_LOOKUP_DC_PDC_REQUIRED             0x00000080
1043 #define WBC_LOOKUP_DC_BACKGROUND_ONLY          0x00000100
1044 #define WBC_LOOKUP_DC_IP_REQUIRED              0x00000200
1045 #define WBC_LOOKUP_DC_KDC_REQUIRED             0x00000400
1046 #define WBC_LOOKUP_DC_TIMESERV_REQUIRED        0x00000800
1047 #define WBC_LOOKUP_DC_WRITABLE_REQUIRED        0x00001000
1048 #define WBC_LOOKUP_DC_GOOD_TIMESERV_PREFERRED  0x00002000
1049 #define WBC_LOOKUP_DC_AVOID_SELF               0x00004000
1050 #define WBC_LOOKUP_DC_ONLY_LDAP_NEEDED         0x00008000
1051 #define WBC_LOOKUP_DC_IS_FLAT_NAME             0x00010000
1052 #define WBC_LOOKUP_DC_IS_DNS_NAME              0x00020000
1053 #define WBC_LOOKUP_DC_TRY_NEXTCLOSEST_SITE     0x00040000
1054 #define WBC_LOOKUP_DC_DS_6_REQUIRED            0x00080000
1055 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
1056 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
1057
1058 /**
1059  * @brief Enumerate the domain trusts known by Winbind
1060  *
1061  * @param domain        Name of the domain to query for a DC
1062  * @param flags         Bit flags used to control the domain location query
1063  * @param *dc_info      Pointer to the returned domain controller information
1064  *
1065  * @return #wbcErr
1066  **/
1067 wbcErr wbcLookupDomainController(const char *domain,
1068                                  uint32_t flags,
1069                                  struct wbcDomainControllerInfo **dc_info);
1070
1071 /**
1072  * @brief Get extended domain controller information
1073  *
1074  * @param domain        Name of the domain to query for a DC
1075  * @param guid          Guid of the domain to query for a DC
1076  * @param site          Site of the domain to query for a DC
1077  * @param flags         Bit flags used to control the domain location query
1078  * @param *dc_info      Pointer to the returned extended domain controller information
1079  *
1080  * @return #wbcErr
1081  **/
1082 wbcErr wbcLookupDomainControllerEx(const char *domain,
1083                                    struct wbcGuid *guid,
1084                                    const char *site,
1085                                    uint32_t flags,
1086                                    struct wbcDomainControllerInfoEx **dc_info);
1087
1088 /**********************************************************
1089  * Athenticate functions
1090  **********************************************************/
1091
1092 /**
1093  * @brief Authenticate a username/password pair
1094  *
1095  * @param username     Name of user to authenticate
1096  * @param password     Clear text password os user
1097  *
1098  * @return #wbcErr
1099  **/
1100 wbcErr wbcAuthenticateUser(const char *username,
1101                            const char *password);
1102
1103 /**
1104  * @brief Authenticate with more detailed information
1105  *
1106  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1107  *                     is not supported yet
1108  * @param info         Output details on WBC_ERR_SUCCESS
1109  * @param error        Output details on WBC_ERR_AUTH_ERROR
1110  *
1111  * @return #wbcErr
1112  **/
1113 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
1114                              struct wbcAuthUserInfo **info,
1115                              struct wbcAuthErrorInfo **error);
1116
1117 /**
1118  * @brief Logon a User
1119  *
1120  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1121  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1122  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1123  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1124  *
1125  * @return #wbcErr
1126  **/
1127 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
1128                     struct wbcLogonUserInfo **info,
1129                     struct wbcAuthErrorInfo **error,
1130                     struct wbcUserPasswordPolicyInfo **policy);
1131
1132 /**
1133  * @brief Trigger a logoff notification to Winbind for a specific user
1134  *
1135  * @param username    Name of user to remove from Winbind's list of
1136  *                    logged on users.
1137  * @param uid         Uid assigned to the username
1138  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1139  *                    be removed
1140  *
1141  * @return #wbcErr
1142  **/
1143 wbcErr wbcLogoffUser(const char *username,
1144                      uid_t uid,
1145                      const char *ccfilename);
1146
1147 /**
1148  * @brief Trigger an extended logoff notification to Winbind for a specific user
1149  *
1150  * @param params      A wbcLogoffUserParams structure
1151  * @param error       User output details on error
1152  *
1153  * @return #wbcErr
1154  **/
1155 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
1156                        struct wbcAuthErrorInfo **error);
1157
1158 /**
1159  * @brief Change a password for a user
1160  *
1161  * @param username      Name of user to authenticate
1162  * @param old_password  Old clear text password of user
1163  * @param new_password  New clear text password of user
1164  *
1165  * @return #wbcErr
1166  **/
1167 wbcErr wbcChangeUserPassword(const char *username,
1168                              const char *old_password,
1169                              const char *new_password);
1170
1171 /**
1172  * @brief Change a password for a user with more detailed information upon
1173  *   failure
1174  *
1175  * @param params                Input parameters
1176  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1177  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1178  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1179  *
1180  * @return #wbcErr
1181  **/
1182 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
1183                                struct wbcAuthErrorInfo **error,
1184                                enum wbcPasswordChangeRejectReason *reject_reason,
1185                                struct wbcUserPasswordPolicyInfo **policy);
1186
1187 /**
1188  * @brief Authenticate a user with cached credentials
1189  *
1190  * @param *params    Pointer to a wbcCredentialCacheParams structure
1191  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1192  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1193  *
1194  * @return #wbcErr
1195  **/
1196 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
1197                           struct wbcCredentialCacheInfo **info,
1198                           struct wbcAuthErrorInfo **error);
1199
1200 /**
1201  * @brief Save a password with winbind for doing wbcCredentialCache() later
1202  *
1203  * @param *user      Username
1204  * @param *password  Password
1205  *
1206  * @return #wbcErr
1207  **/
1208 wbcErr wbcCredentialSave(const char *user, const char *password);
1209
1210 /**********************************************************
1211  * Resolve functions
1212  **********************************************************/
1213
1214 /**
1215  * @brief Resolve a NetbiosName via WINS
1216  *
1217  * @param name         Name to resolve
1218  * @param *ip          Pointer to the ip address string
1219  *
1220  * @return #wbcErr
1221  **/
1222 wbcErr wbcResolveWinsByName(const char *name, char **ip);
1223
1224 /**
1225  * @brief Resolve an IP address via WINS into a NetbiosName
1226  *
1227  * @param ip          The ip address string
1228  * @param *name       Pointer to the name
1229  *
1230  * @return #wbcErr
1231  *
1232  **/
1233 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
1234
1235 /**********************************************************
1236  * Trusted domain functions
1237  **********************************************************/
1238
1239 /**
1240  * @brief Trigger a verification of the trust credentials of a specific domain
1241  *
1242  * @param *domain      The name of the domain.
1243  * @param error        Output details on WBC_ERR_AUTH_ERROR
1244  *
1245  * @return #wbcErr
1246  **/
1247 wbcErr wbcCheckTrustCredentials(const char *domain,
1248                                 struct wbcAuthErrorInfo **error);
1249
1250 /**
1251  * @brief Trigger a change of the trust credentials for a specific domain
1252  *
1253  * @param *domain      The name of the domain.
1254  * @param error        Output details on WBC_ERR_AUTH_ERROR
1255  *
1256  * @return #wbcErr
1257  **/
1258 wbcErr wbcChangeTrustCredentials(const char *domain,
1259                                  struct wbcAuthErrorInfo **error);
1260
1261 /**
1262  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
1263  *        version of wbcCheckTrustCredentials
1264  *
1265  * @param *domain      The name of the domain, only NULL for the default domain is
1266  *                     supported yet. Other values than NULL will result in
1267  *                     WBC_ERR_NOT_IMPLEMENTED.
1268  * @param error        Output details on WBC_ERR_AUTH_ERROR
1269  *
1270  * @return #wbcErr
1271  **/
1272 wbcErr wbcPingDc(const char *domain, struct wbcAuthErrorInfo **error);
1273
1274 /**********************************************************
1275  * Helper functions
1276  **********************************************************/
1277
1278 /**
1279  * @brief Initialize a named blob and add to list of blobs
1280  *
1281  * @param[in,out] num_blobs     Pointer to the number of blobs
1282  * @param[in,out] blobs         Pointer to an array of blobs
1283  * @param[in]     name          Name of the new named blob
1284  * @param[in]     flags         Flags of the new named blob
1285  * @param[in]     data          Blob data of new blob
1286  * @param[in]     length        Blob data length of new blob
1287  *
1288  * @return #wbcErr
1289  **/
1290 wbcErr wbcAddNamedBlob(size_t *num_blobs,
1291                        struct wbcNamedBlob **blobs,
1292                        const char *name,
1293                        uint32_t flags,
1294                        uint8_t *data,
1295                        size_t length);
1296
1297 #endif      /* _WBCLIENT_H */