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