ed97a673739acbc56be33624bab39374ec7335cc
[samba.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    Copyright (C) Matthew Newton 2015
9
10    This library is free software; you can redistribute it and/or
11    modify it under the terms of the GNU Lesser General Public
12    License as published by the Free Software Foundation; either
13    version 3 of the License, or (at your option) any later version.
14
15    This library is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18    Library General Public License for more details.
19
20    You should have received a copy of the GNU Lesser General Public License
21    along with this program.  If not, see <http://www.gnu.org/licenses/>.
22 */
23
24 #ifndef _WBCLIENT_H
25 #define _WBCLIENT_H
26
27 #include <pwd.h>
28 #include <grp.h>
29
30 /* Define error types */
31
32 /**
33  *  @brief Status codes returned from wbc functions
34  **/
35
36 enum _wbcErrType {
37         WBC_ERR_SUCCESS = 0,    /**< Successful completion **/
38         WBC_ERR_NOT_IMPLEMENTED,/**< Function not implemented **/
39         WBC_ERR_UNKNOWN_FAILURE,/**< General failure **/
40         WBC_ERR_NO_MEMORY,      /**< Memory allocation error **/
41         WBC_ERR_INVALID_SID,    /**< Invalid SID format **/
42         WBC_ERR_INVALID_PARAM,  /**< An Invalid parameter was supplied **/
43         WBC_ERR_WINBIND_NOT_AVAILABLE,   /**< Winbind daemon is not available **/
44         WBC_ERR_DOMAIN_NOT_FOUND,        /**< Domain is not trusted or cannot be found **/
45         WBC_ERR_INVALID_RESPONSE,        /**< Winbind returned an invalid response **/
46         WBC_ERR_NSS_ERROR,            /**< NSS_STATUS error **/
47         WBC_ERR_AUTH_ERROR,        /**< Authentication failed **/
48         WBC_ERR_UNKNOWN_USER,      /**< User account cannot be found */
49         WBC_ERR_UNKNOWN_GROUP,     /**< Group account cannot be found */
50         WBC_ERR_PWD_CHANGE_FAILED  /**< Password Change has failed */
51 };
52
53 typedef enum _wbcErrType wbcErr;
54
55 #define WBC_ERROR_IS_OK(x) ((x) == WBC_ERR_SUCCESS)
56
57 const char *wbcErrorString(wbcErr error);
58
59 /**
60  *  @brief Some useful details about the wbclient library
61  *
62  *  0.1: Initial version
63  *  0.2: Added wbcRemoveUidMapping()
64  *       Added wbcRemoveGidMapping()
65  *  0.3: Added wbcGetpwsid()
66  *       Added wbcGetSidAliases()
67  *  0.4: Added wbcSidTypeString()
68  *  0.5: Added wbcChangeTrustCredentials()
69  *  0.6: Made struct wbcInterfaceDetails char* members non-const
70  *  0.7: Added wbcSidToStringBuf()
71  *  0.8: Added wbcSidsToUnixIds() and wbcLookupSids()
72  *  0.9: Added support for WBC_ID_TYPE_BOTH
73  *  0.10: Added wbcPingDc2()
74  *  0.11: Extended wbcAuthenticateUserEx to provide PAC parsing
75  *  0.12: Added wbcCtxCreate and friends
76  *  0.13: Added wbcCtxUnixIdsToSids and wbcUnixIdsToSids
77  *  0.14: Added "authoritative" to wbcAuthErrorInfo
78  *        Added WBC_SID_NAME_LABEL
79  **/
80 #define WBCLIENT_MAJOR_VERSION 0
81 #define WBCLIENT_MINOR_VERSION 14
82 #define WBCLIENT_VENDOR_VERSION "Samba libwbclient"
83 struct wbcLibraryDetails {
84         uint16_t major_version;
85         uint16_t minor_version;
86         const char *vendor_version;
87 };
88
89 /**
90  *  @brief Some useful details about the running winbindd
91  *
92  **/
93 struct wbcInterfaceDetails {
94         uint32_t interface_version;
95         char *winbind_version;
96         char winbind_separator;
97         char *netbios_name;
98         char *netbios_domain;
99         char *dns_domain;
100 };
101
102 /**
103  *  @brief Library context data
104  *
105  **/
106
107 struct wbcContext;
108
109 /*
110  * Data types used by the Winbind Client API
111  */
112
113 #ifndef WBC_MAXSUBAUTHS
114 #define WBC_MAXSUBAUTHS 15 /* max sub authorities in a SID */
115 #endif
116
117 /**
118  *  @brief Windows Security Identifier
119  *
120  **/
121
122 struct wbcDomainSid {
123         uint8_t   sid_rev_num;
124         uint8_t   num_auths;
125         uint8_t   id_auth[6];
126         uint32_t  sub_auths[WBC_MAXSUBAUTHS];
127 };
128
129 /**
130  * @brief Security Identifier type
131  **/
132
133 enum wbcSidType {
134         WBC_SID_NAME_USE_NONE=0,
135         WBC_SID_NAME_USER=1,
136         WBC_SID_NAME_DOM_GRP=2,
137         WBC_SID_NAME_DOMAIN=3,
138         WBC_SID_NAME_ALIAS=4,
139         WBC_SID_NAME_WKN_GRP=5,
140         WBC_SID_NAME_DELETED=6,
141         WBC_SID_NAME_INVALID=7,
142         WBC_SID_NAME_UNKNOWN=8,
143         WBC_SID_NAME_COMPUTER=9,
144         WBC_SID_NAME_LABEL=10
145 };
146
147 /**
148  * @brief Security Identifier with attributes
149  **/
150
151 struct wbcSidWithAttr {
152         struct wbcDomainSid sid;
153         uint32_t attributes;
154 };
155
156 /* wbcSidWithAttr->attributes */
157
158 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
159 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
160 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
161 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
162 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
163 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
164 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
165
166 /**
167  *  @brief Windows GUID
168  *
169  **/
170
171 struct wbcGuid {
172         uint32_t time_low;
173         uint16_t time_mid;
174         uint16_t time_hi_and_version;
175         uint8_t clock_seq[2];
176         uint8_t node[6];
177 };
178
179 /**
180  * @brief Domain Information
181  **/
182
183 struct wbcDomainInfo {
184         char *short_name;
185         char *dns_name;
186         struct wbcDomainSid sid;
187         uint32_t domain_flags;
188         uint32_t trust_flags;
189         uint32_t trust_type;
190 };
191
192 /* wbcDomainInfo->domain_flags */
193
194 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
195 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
196 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
197 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
198 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
199
200 /* wbcDomainInfo->trust_flags */
201
202 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
203 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
204 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
205
206 /* wbcDomainInfo->trust_type */
207
208 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
209 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
210 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
211 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
212
213 /**
214  * @brief Generic Blob
215  **/
216
217 struct wbcBlob {
218         uint8_t *data;
219         size_t length;
220 };
221
222 /**
223  * @brief Named Blob
224  **/
225
226 struct wbcNamedBlob {
227         const char *name;
228         uint32_t flags;
229         struct wbcBlob blob;
230 };
231
232 /**
233  * @brief Auth User Parameters
234  **/
235
236 struct wbcAuthUserParams {
237         const char *account_name;
238         const char *domain_name;
239         const char *workstation_name;
240
241         uint32_t flags;
242
243         uint32_t parameter_control;
244
245         enum wbcAuthUserLevel {
246                 WBC_AUTH_USER_LEVEL_PLAIN = 1,
247                 WBC_AUTH_USER_LEVEL_HASH = 2,
248                 WBC_AUTH_USER_LEVEL_RESPONSE = 3,
249                 WBC_AUTH_USER_LEVEL_PAC = 4
250         } level;
251         union {
252                 const char *plaintext;
253                 struct {
254                         uint8_t nt_hash[16];
255                         uint8_t lm_hash[16];
256                 } hash;
257                 struct {
258                         uint8_t challenge[8];
259                         uint32_t nt_length;
260                         uint8_t *nt_data;
261                         uint32_t lm_length;
262                         uint8_t *lm_data;
263                 } response;
264                 struct wbcBlob pac;
265         } password;
266 };
267
268 /**
269  * @brief Logon User Parameters
270  **/
271
272 struct wbcLogonUserParams {
273         const char *username;
274         const char *password;
275         size_t num_blobs;
276         struct wbcNamedBlob *blobs;
277 };
278
279 /**
280  * @brief ChangePassword Parameters
281  **/
282
283 struct wbcChangePasswordParams {
284         const char *account_name;
285         const char *domain_name;
286
287         uint32_t flags;
288
289         enum wbcChangePasswordLevel {
290                 WBC_CHANGE_PASSWORD_LEVEL_PLAIN = 1,
291                 WBC_CHANGE_PASSWORD_LEVEL_RESPONSE = 2
292         } level;
293
294         union {
295                 const char *plaintext;
296                 struct {
297                         uint32_t old_nt_hash_enc_length;
298                         uint8_t *old_nt_hash_enc_data;
299                         uint32_t old_lm_hash_enc_length;
300                         uint8_t *old_lm_hash_enc_data;
301                 } response;
302         } old_password;
303         union {
304                 const char *plaintext;
305                 struct {
306                         uint32_t nt_length;
307                         uint8_t *nt_data;
308                         uint32_t lm_length;
309                         uint8_t *lm_data;
310                 } response;
311         } new_password;
312 };
313
314 /* wbcAuthUserParams->parameter_control */
315
316 #define WBC_MSV1_0_CLEARTEXT_PASSWORD_ALLOWED           0x00000002
317 #define WBC_MSV1_0_UPDATE_LOGON_STATISTICS              0x00000004
318 #define WBC_MSV1_0_RETURN_USER_PARAMETERS               0x00000008
319 #define WBC_MSV1_0_ALLOW_SERVER_TRUST_ACCOUNT           0x00000020
320 #define WBC_MSV1_0_RETURN_PROFILE_PATH                  0x00000200
321 #define WBC_MSV1_0_ALLOW_WORKSTATION_TRUST_ACCOUNT      0x00000800
322 #define WBC_MSV1_0_ALLOW_MSVCHAPV2                      0x00010000
323
324 /* wbcAuthUserParams->flags */
325
326 #define WBC_AUTH_PARAM_FLAGS_INTERACTIVE_LOGON          0x00000001
327
328 /**
329  * @brief Auth User Information
330  *
331  * Some of the strings are maybe NULL
332  **/
333
334 struct wbcAuthUserInfo {
335         uint32_t user_flags;
336
337         char *account_name;
338         char *user_principal;
339         char *full_name;
340         char *domain_name;
341         char *dns_domain_name;
342
343         uint32_t acct_flags;
344         uint8_t user_session_key[16];
345         uint8_t lm_session_key[8];
346
347         uint16_t logon_count;
348         uint16_t bad_password_count;
349
350         uint64_t logon_time;
351         uint64_t logoff_time;
352         uint64_t kickoff_time;
353         uint64_t pass_last_set_time;
354         uint64_t pass_can_change_time;
355         uint64_t pass_must_change_time;
356
357         char *logon_server;
358         char *logon_script;
359         char *profile_path;
360         char *home_directory;
361         char *home_drive;
362
363         /*
364          * the 1st one is the account sid
365          * the 2nd one is the primary_group sid
366          * followed by the rest of the groups
367          */
368         uint32_t num_sids;
369         struct wbcSidWithAttr *sids;
370 };
371
372 /**
373  * @brief Logon User Information
374  *
375  * Some of the strings are maybe NULL
376  **/
377
378 struct wbcLogonUserInfo {
379         struct wbcAuthUserInfo *info;
380         size_t num_blobs;
381         struct wbcNamedBlob *blobs;
382 };
383
384 /* wbcAuthUserInfo->user_flags */
385
386 #define WBC_AUTH_USER_INFO_GUEST                        0x00000001
387 #define WBC_AUTH_USER_INFO_NOENCRYPTION                 0x00000002
388 #define WBC_AUTH_USER_INFO_CACHED_ACCOUNT               0x00000004
389 #define WBC_AUTH_USER_INFO_USED_LM_PASSWORD             0x00000008
390 #define WBC_AUTH_USER_INFO_EXTRA_SIDS                   0x00000020
391 #define WBC_AUTH_USER_INFO_SUBAUTH_SESSION_KEY          0x00000040
392 #define WBC_AUTH_USER_INFO_SERVER_TRUST_ACCOUNT         0x00000080
393 #define WBC_AUTH_USER_INFO_NTLMV2_ENABLED               0x00000100
394 #define WBC_AUTH_USER_INFO_RESOURCE_GROUPS              0x00000200
395 #define WBC_AUTH_USER_INFO_PROFILE_PATH_RETURNED        0x00000400
396 #define WBC_AUTH_USER_INFO_GRACE_LOGON                  0x01000000
397
398 /* wbcAuthUserInfo->acct_flags */
399
400 #define WBC_ACB_DISABLED                        0x00000001 /* 1 User account disabled */
401 #define WBC_ACB_HOMDIRREQ                       0x00000002 /* 1 Home directory required */
402 #define WBC_ACB_PWNOTREQ                        0x00000004 /* 1 User password not required */
403 #define WBC_ACB_TEMPDUP                         0x00000008 /* 1 Temporary duplicate account */
404 #define WBC_ACB_NORMAL                          0x00000010 /* 1 Normal user account */
405 #define WBC_ACB_MNS                             0x00000020 /* 1 MNS logon user account */
406 #define WBC_ACB_DOMTRUST                        0x00000040 /* 1 Interdomain trust account */
407 #define WBC_ACB_WSTRUST                         0x00000080 /* 1 Workstation trust account */
408 #define WBC_ACB_SVRTRUST                        0x00000100 /* 1 Server trust account */
409 #define WBC_ACB_PWNOEXP                         0x00000200 /* 1 User password does not expire */
410 #define WBC_ACB_AUTOLOCK                        0x00000400 /* 1 Account auto locked */
411 #define WBC_ACB_ENC_TXT_PWD_ALLOWED             0x00000800 /* 1 Encryped text password is allowed */
412 #define WBC_ACB_SMARTCARD_REQUIRED              0x00001000 /* 1 Smart Card required */
413 #define WBC_ACB_TRUSTED_FOR_DELEGATION          0x00002000 /* 1 Trusted for Delegation */
414 #define WBC_ACB_NOT_DELEGATED                   0x00004000 /* 1 Not delegated */
415 #define WBC_ACB_USE_DES_KEY_ONLY                0x00008000 /* 1 Use DES key only */
416 #define WBC_ACB_DONT_REQUIRE_PREAUTH            0x00010000 /* 1 Preauth not required */
417 #define WBC_ACB_PW_EXPIRED                      0x00020000 /* 1 Password Expired */
418 #define WBC_ACB_NO_AUTH_DATA_REQD               0x00080000   /* 1 = No authorization data required */
419
420 struct wbcAuthErrorInfo {
421         uint32_t nt_status;
422         char *nt_string;
423         int32_t pam_error;
424         char *display_string;
425         uint8_t authoritative;
426 };
427
428 /**
429  * @brief User Password Policy Information
430  **/
431
432 /* wbcUserPasswordPolicyInfo->password_properties */
433
434 #define WBC_DOMAIN_PASSWORD_COMPLEX             0x00000001
435 #define WBC_DOMAIN_PASSWORD_NO_ANON_CHANGE      0x00000002
436 #define WBC_DOMAIN_PASSWORD_NO_CLEAR_CHANGE     0x00000004
437 #define WBC_DOMAIN_PASSWORD_LOCKOUT_ADMINS      0x00000008
438 #define WBC_DOMAIN_PASSWORD_STORE_CLEARTEXT     0x00000010
439 #define WBC_DOMAIN_REFUSE_PASSWORD_CHANGE       0x00000020
440
441 struct wbcUserPasswordPolicyInfo {
442         uint32_t min_length_password;
443         uint32_t password_history;
444         uint32_t password_properties;
445         uint64_t expire;
446         uint64_t min_passwordage;
447 };
448
449 /**
450  * @brief Change Password Reject Reason
451  **/
452
453 enum wbcPasswordChangeRejectReason {
454         WBC_PWD_CHANGE_NO_ERROR=0,
455         WBC_PWD_CHANGE_PASSWORD_TOO_SHORT=1,
456         WBC_PWD_CHANGE_PWD_IN_HISTORY=2,
457         WBC_PWD_CHANGE_USERNAME_IN_PASSWORD=3,
458         WBC_PWD_CHANGE_FULLNAME_IN_PASSWORD=4,
459         WBC_PWD_CHANGE_NOT_COMPLEX=5,
460         WBC_PWD_CHANGE_MACHINE_NOT_DEFAULT=6,
461         WBC_PWD_CHANGE_FAILED_BY_FILTER=7,
462         WBC_PWD_CHANGE_PASSWORD_TOO_LONG=8
463 };
464
465 /* Note: this defines exist for compatibility reasons with existing code */
466 #define WBC_PWD_CHANGE_REJECT_OTHER      WBC_PWD_CHANGE_NO_ERROR
467 #define WBC_PWD_CHANGE_REJECT_TOO_SHORT  WBC_PWD_CHANGE_PASSWORD_TOO_SHORT
468 #define WBC_PWD_CHANGE_REJECT_IN_HISTORY WBC_PWD_CHANGE_PWD_IN_HISTORY
469 #define WBC_PWD_CHANGE_REJECT_COMPLEXITY WBC_PWD_CHANGE_NOT_COMPLEX
470
471 /**
472  * @brief Logoff User Parameters
473  **/
474
475 struct wbcLogoffUserParams {
476         const char *username;
477         size_t num_blobs;
478         struct wbcNamedBlob *blobs;
479 };
480
481 /** @brief Credential cache log-on parameters
482  *
483  */
484
485 struct wbcCredentialCacheParams {
486         const char *account_name;
487         const char *domain_name;
488         enum wbcCredentialCacheLevel {
489                 WBC_CREDENTIAL_CACHE_LEVEL_NTLMSSP = 1
490         } level;
491         size_t num_blobs;
492         struct wbcNamedBlob *blobs;
493 };
494
495
496 /** @brief Info returned by credential cache auth
497  *
498  */
499
500 struct wbcCredentialCacheInfo {
501         size_t num_blobs;
502         struct wbcNamedBlob *blobs;
503 };
504
505 /*
506  * DomainControllerInfo struct
507  */
508 struct wbcDomainControllerInfo {
509         char *dc_name;
510 };
511
512 /*
513  * DomainControllerInfoEx struct
514  */
515 struct wbcDomainControllerInfoEx {
516         const char *dc_unc;
517         const char *dc_address;
518         uint16_t dc_address_type;
519         struct wbcGuid *domain_guid;
520         const char *domain_name;
521         const char *forest_name;
522         uint32_t dc_flags;
523         const char *dc_site_name;
524         const char *client_site_name;
525 };
526
527 /**********************************************************
528  * Memory Management
529  **********************************************************/
530
531 /**
532  * @brief Free library allocated memory
533  *
534  * @param * Pointer to free
535  *
536  * @return void
537  **/
538 void wbcFreeMemory(void*);
539
540
541 /**********************************************************
542  * Context Management
543  **********************************************************/
544
545 /**
546  * @brief Create a new wbcContext context
547  *
548  * @return wbcContext
549  **/
550 struct wbcContext *wbcCtxCreate(void);
551
552 /**
553  * @brief Free a library context
554  *
555  * @param ctx           wbcContext to free
556  *
557  * @return void
558  **/
559 void wbcCtxFree(struct wbcContext *ctx);
560
561
562
563 /*
564  * Utility functions for dealing with SIDs
565  */
566
567 /**
568  * @brief Get a string representation of the SID type
569  *
570  * @param type          type of the SID
571  *
572  * @return string representation of the SID type
573  */
574 const char* wbcSidTypeString(enum wbcSidType type);
575
576 #define WBC_SID_STRING_BUFLEN (15*11+25)
577
578 /*
579  * @brief Print a sid into a buffer
580  *
581  * @param sid           Binary Security Identifier
582  * @param buf           Target buffer
583  * @param buflen        Target buffer length
584  *
585  * @return Resulting string length.
586  */
587 int wbcSidToStringBuf(const struct wbcDomainSid *sid, char *buf, int buflen);
588
589 /**
590  * @brief Convert a binary SID to a character string
591  *
592  * @param sid           Binary Security Identifier
593  * @param **sid_string  Resulting character string
594  *
595  * @return #wbcErr
596  **/
597 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
598                       char **sid_string);
599
600 /**
601  * @brief Convert a character string to a binary SID
602  *
603  * @param *sid_string   Character string in the form of S-...
604  * @param sid           Resulting binary SID
605  *
606  * @return #wbcErr
607  **/
608 wbcErr wbcStringToSid(const char *sid_string,
609                       struct wbcDomainSid *sid);
610
611 /*
612  * Utility functions for dealing with GUIDs
613  */
614
615 /**
616  * @brief Convert a binary GUID to a character string
617  *
618  * @param guid           Binary Guid
619  * @param **guid_string  Resulting character string
620  *
621  * @return #wbcErr
622  **/
623 wbcErr wbcGuidToString(const struct wbcGuid *guid,
624                        char **guid_string);
625
626 /**
627  * @brief Convert a character string to a binary GUID
628  *
629  * @param *guid_string  Character string
630  * @param guid          Resulting binary GUID
631  *
632  * @return #wbcErr
633  **/
634 wbcErr wbcStringToGuid(const char *guid_string,
635                        struct wbcGuid *guid);
636
637 /**
638  * @brief Ping winbindd to see if the daemon is running
639  *
640  * @param *ctx        wbclient Context
641  *
642  * @return #wbcErr
643  **/
644 wbcErr wbcCtxPing(struct wbcContext *ctx);
645
646 /**
647  * @brief Ping winbindd to see if the daemon is running
648  *
649  * @return #wbcErr
650  **/
651 wbcErr wbcPing(void);
652
653 wbcErr wbcLibraryDetails(struct wbcLibraryDetails **details);
654
655 wbcErr wbcCtxInterfaceDetails(struct wbcContext *ctx,
656                               struct wbcInterfaceDetails **details);
657 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
658
659 /**********************************************************
660  * Name/SID conversion
661  **********************************************************/
662
663 /**
664  * @brief Convert a domain and name to SID
665  *
666  * @param *ctx        wbclient Context
667  * @param dom_name    Domain name (possibly "")
668  * @param name        User or group name
669  * @param *sid        Pointer to the resolved domain SID
670  * @param *name_type  Pointer to the SID type
671  *
672  * @return #wbcErr
673  **/
674 wbcErr wbcCtxLookupName(struct wbcContext *ctx,
675                         const char *dom_name,
676                         const char *name,
677                         struct wbcDomainSid *sid,
678                         enum wbcSidType *name_type);
679
680 /**
681  * @brief Convert a domain and name to SID
682  *
683  * @param dom_name    Domain name (possibly "")
684  * @param name        User or group name
685  * @param *sid        Pointer to the resolved domain SID
686  * @param *name_type  Pointer to the SID type
687  *
688  * @return #wbcErr
689  **/
690 wbcErr wbcLookupName(const char *dom_name,
691                      const char *name,
692                      struct wbcDomainSid *sid,
693                      enum wbcSidType *name_type);
694
695 /**
696  * @brief Convert a SID to a domain and name
697  *
698  * @param *ctx       wbclient Context
699  * @param *sid       Pointer to the domain SID to be resolved
700  * @param domain     Resolved Domain name (possibly "")
701  * @param name       Resolved User or group name
702  * @param *name_type Pointer to the resolved SID type
703  *
704  * @return #wbcErr
705  **/
706 wbcErr wbcCtxLookupSid(struct wbcContext *ctx,
707                        const struct wbcDomainSid *sid,
708                        char **domain,
709                        char **name,
710                        enum wbcSidType *name_type);
711
712 /**
713  * @brief Convert a SID to a domain and name
714  *
715  * @param *sid       Pointer to the domain SID to be resolved
716  * @param domain     Resolved Domain name (possibly "")
717  * @param name       Resolved User or group name
718  * @param *name_type Pointer to the resolved SID type
719  *
720  * @return #wbcErr
721  **/
722 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
723                     char **domain,
724                     char **name,
725                     enum wbcSidType *name_type);
726
727 struct wbcTranslatedName {
728         enum wbcSidType type;
729         char *name;
730         int domain_index;
731 };
732
733 wbcErr wbcCtxLookupSids(struct wbcContext *ctx,
734                         const struct wbcDomainSid *sids, int num_sids,
735                         struct wbcDomainInfo **domains, int *num_domains,
736                         struct wbcTranslatedName **names);
737
738 wbcErr wbcLookupSids(const struct wbcDomainSid *sids, int num_sids,
739                      struct wbcDomainInfo **domains, int *num_domains,
740                      struct wbcTranslatedName **names);
741
742 /**
743  * @brief Translate a collection of RIDs within a domain to names
744  */
745 wbcErr wbcCtxLookupRids(struct wbcContext *ctx,
746                         struct wbcDomainSid *dom_sid,
747                         int num_rids,
748                         uint32_t *rids,
749                         const char **domain_name,
750                         const char ***names,
751                         enum wbcSidType **types);
752
753 /**
754  * @brief Translate a collection of RIDs within a domain to names
755  */
756 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
757                      int num_rids,
758                      uint32_t *rids,
759                      const char **domain_name,
760                      const char ***names,
761                      enum wbcSidType **types);
762
763 /*
764  * @brief Get the groups a user belongs to
765  **/
766 wbcErr wbcCtxLookupUserSids(struct wbcContext *ctx,
767                             const struct wbcDomainSid *user_sid,
768                             bool domain_groups_only,
769                             uint32_t *num_sids,
770                             struct wbcDomainSid **sids);
771
772 /*
773  * @brief Get the groups a user belongs to
774  **/
775 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
776                          bool domain_groups_only,
777                          uint32_t *num_sids,
778                          struct wbcDomainSid **sids);
779
780 /*
781  * @brief Get alias membership for sids
782  **/
783 wbcErr wbcCtxGetSidAliases(struct wbcContext *ctx,
784                            const struct wbcDomainSid *dom_sid,
785                            struct wbcDomainSid *sids,
786                            uint32_t num_sids,
787                            uint32_t **alias_rids,
788                            uint32_t *num_alias_rids);
789
790 /*
791  * @brief Get alias membership for sids
792  **/
793 wbcErr wbcGetSidAliases(const struct wbcDomainSid *dom_sid,
794                         struct wbcDomainSid *sids,
795                         uint32_t num_sids,
796                         uint32_t **alias_rids,
797                         uint32_t *num_alias_rids);
798
799 /**
800  * @brief Lists Users
801  **/
802 wbcErr wbcCtxListUsers(struct wbcContext *ctx,
803                        const char *domain_name,
804                        uint32_t *num_users,
805                        const char ***users);
806
807 /**
808  * @brief Lists Users
809  **/
810 wbcErr wbcListUsers(const char *domain_name,
811                     uint32_t *num_users,
812                     const char ***users);
813
814 /**
815  * @brief Lists Groups
816  **/
817 wbcErr wbcCtxListGroups(struct wbcContext *ctx,
818                         const char *domain_name,
819                         uint32_t *num_groups,
820                         const char ***groups);
821
822 /**
823  * @brief Lists Groups
824  **/
825 wbcErr wbcListGroups(const char *domain_name,
826                      uint32_t *num_groups,
827                      const char ***groups);
828
829 wbcErr wbcCtxGetDisplayName(struct wbcContext *ctx,
830                             const struct wbcDomainSid *sid,
831                             char **pdomain,
832                             char **pfullname,
833                             enum wbcSidType *pname_type);
834
835 wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid,
836                          char **pdomain,
837                          char **pfullname,
838                          enum wbcSidType *pname_type);
839
840 /**********************************************************
841  * SID/uid/gid Mappings
842  **********************************************************/
843
844 /**
845  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
846  *
847  * @param *ctx        wbclient Context
848  * @param *sid        Pointer to the domain SID to be resolved
849  * @param *puid       Pointer to the resolved uid_t value
850  *
851  * @return #wbcErr
852  *
853  **/
854 wbcErr wbcCtxSidToUid(struct wbcContext *ctx,
855                       const struct wbcDomainSid *sid,
856                       uid_t *puid);
857
858 /**
859  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
860  *
861  * @param *sid        Pointer to the domain SID to be resolved
862  * @param *puid       Pointer to the resolved uid_t value
863  *
864  * @return #wbcErr
865  *
866  **/
867 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
868                    uid_t *puid);
869
870 /**
871  * @brief Convert a Windows SID to a Unix uid if there already is a mapping
872  *
873  * @param *sid        Pointer to the domain SID to be resolved
874  * @param *puid       Pointer to the resolved uid_t value
875  *
876  * @return #wbcErr
877  *
878  **/
879 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
880                         uid_t *puid);
881
882 /**
883  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
884  *
885  * @param *ctx        wbclient Context
886  * @param uid         Unix uid to be resolved
887  * @param *sid        Pointer to the resolved domain SID
888  *
889  * @return #wbcErr
890  *
891  **/
892 wbcErr wbcCtxUidToSid(struct wbcContext *ctx, uid_t uid,
893                       struct wbcDomainSid *sid);
894
895 /**
896  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
897  *
898  * @param uid         Unix uid to be resolved
899  * @param *sid        Pointer to the resolved domain SID
900  *
901  * @return #wbcErr
902  *
903  **/
904 wbcErr wbcUidToSid(uid_t uid,
905                    struct wbcDomainSid *sid);
906
907 /**
908  * @brief Convert a Unix uid to a Windows SID if there already is a mapping
909  *
910  * @param uid         Unix uid to be resolved
911  * @param *sid        Pointer to the resolved domain SID
912  *
913  * @return #wbcErr
914  *
915  **/
916 wbcErr wbcQueryUidToSid(uid_t uid,
917                         struct wbcDomainSid *sid);
918
919 /**
920  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
921  *
922  * @param *ctx        wbclient Context
923  * @param *sid        Pointer to the domain SID to be resolved
924  * @param *pgid       Pointer to the resolved gid_t value
925  *
926  * @return #wbcErr
927  *
928  **/
929 wbcErr wbcCtxSidToGid(struct wbcContext *ctx,
930                       const struct wbcDomainSid *sid,
931                       gid_t *pgid);
932
933 /**
934  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
935  *
936  * @param *sid        Pointer to the domain SID to be resolved
937  * @param *pgid       Pointer to the resolved gid_t value
938  *
939  * @return #wbcErr
940  *
941  **/
942 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
943                    gid_t *pgid);
944
945 /**
946  * @brief Convert a Windows SID to a Unix gid if there already is a mapping
947  *
948  * @param *sid        Pointer to the domain SID to be resolved
949  * @param *pgid       Pointer to the resolved gid_t value
950  *
951  * @return #wbcErr
952  *
953  **/
954 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
955                         gid_t *pgid);
956
957 /**
958  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
959  *
960  * @param *ctx        wbclient Context
961  * @param gid         Unix gid to be resolved
962  * @param *sid        Pointer to the resolved domain SID
963  *
964  * @return #wbcErr
965  *
966  **/
967 wbcErr wbcCtxGidToSid(struct wbcContext *ctx, gid_t gid,
968                    struct wbcDomainSid *sid);
969
970 /**
971  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
972  *
973  * @param gid         Unix gid to be resolved
974  * @param *sid        Pointer to the resolved domain SID
975  *
976  * @return #wbcErr
977  *
978  **/
979 wbcErr wbcGidToSid(gid_t gid,
980                    struct wbcDomainSid *sid);
981
982 /**
983  * @brief Convert a Unix gid to a Windows SID if there already is a mapping
984  *
985  * @param gid         Unix gid to be resolved
986  * @param *sid        Pointer to the resolved domain SID
987  *
988  * @return #wbcErr
989  *
990  **/
991 wbcErr wbcQueryGidToSid(gid_t gid,
992                         struct wbcDomainSid *sid);
993
994 enum wbcIdType {
995         WBC_ID_TYPE_NOT_SPECIFIED,
996         WBC_ID_TYPE_UID,
997         WBC_ID_TYPE_GID,
998         WBC_ID_TYPE_BOTH
999 };
1000
1001 union wbcUnixIdContainer {
1002         uid_t uid;
1003         gid_t gid;
1004 };
1005
1006 struct wbcUnixId {
1007         enum wbcIdType type;
1008         union wbcUnixIdContainer id;
1009 };
1010
1011 /**
1012  * @brief Convert a list of sids to unix ids
1013  *
1014  * @param *ctx        wbclient Context
1015  * @param sids        Pointer to an array of SIDs to convert
1016  * @param num_sids    Number of SIDs
1017  * @param ids         Preallocated output array for translated IDs
1018  *
1019  * @return #wbcErr
1020  *
1021  **/
1022 wbcErr wbcCtxSidsToUnixIds(struct wbcContext *ctx,
1023                            const struct wbcDomainSid *sids, uint32_t num_sids,
1024                            struct wbcUnixId *ids);
1025
1026 /**
1027  * @brief Convert a list of sids to unix ids
1028  *
1029  * @param sids        Pointer to an array of SIDs to convert
1030  * @param num_sids    Number of SIDs
1031  * @param ids         Preallocated output array for translated IDs
1032  *
1033  * @return #wbcErr
1034  *
1035  **/
1036 wbcErr wbcSidsToUnixIds(const struct wbcDomainSid *sids, uint32_t num_sids,
1037                         struct wbcUnixId *ids);
1038
1039 wbcErr wbcCtxUnixIdsToSids(struct wbcContext *ctx,
1040                            const struct wbcUnixId *ids, uint32_t num_ids,
1041                            struct wbcDomainSid *sids);
1042 wbcErr wbcUnixIdsToSids(const struct wbcUnixId *ids, uint32_t num_ids,
1043                         struct wbcDomainSid *sids);
1044
1045 /**
1046  * @brief Obtain a new uid from Winbind
1047  *
1048  * @param *ctx        wbclient Context
1049  * @param *puid       Pointer to the allocated uid
1050  *
1051  * @return #wbcErr
1052  **/
1053 wbcErr wbcCtxAllocateUid(struct wbcContext *ctx, uid_t *puid);
1054
1055 /**
1056  * @brief Obtain a new uid from Winbind
1057  *
1058  * @param *puid       Pointer to the allocated uid
1059  *
1060  * @return #wbcErr
1061  **/
1062 wbcErr wbcAllocateUid(uid_t *puid);
1063
1064 /**
1065  * @brief Obtain a new gid from Winbind
1066  *
1067  * @param *ctx        wbclient Context
1068  * @param *pgid       Pointer to the allocated gid
1069  *
1070  * @return #wbcErr
1071  **/
1072 wbcErr wbcCtxAllocateGid(struct wbcContext *ctx, gid_t *pgid);
1073
1074 /**
1075  * @brief Obtain a new gid from Winbind
1076  *
1077  * @param *pgid       Pointer to the allocated gid
1078  *
1079  * @return #wbcErr
1080  **/
1081 wbcErr wbcAllocateGid(gid_t *pgid);
1082
1083 /**
1084  * @brief Set an user id mapping
1085  *
1086  * @param uid       Uid of the desired mapping.
1087  * @param *sid      Pointer to the sid of the desired mapping.
1088  *
1089  * @return #wbcErr
1090  *
1091  * @deprecated      This method is not impemented any more and should
1092  *                  be removed in the next major version change.
1093  **/
1094 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
1095
1096 /**
1097  * @brief Set a group id mapping
1098  *
1099  * @param gid       Gid of the desired mapping.
1100  * @param *sid      Pointer to the sid of the desired mapping.
1101  *
1102  * @return #wbcErr
1103  *
1104  * @deprecated      This method is not impemented any more and should
1105  *                  be removed in the next major version change.
1106  **/
1107 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
1108
1109 /**
1110  * @brief Remove a user id mapping
1111  *
1112  * @param uid       Uid of the mapping to remove.
1113  * @param *sid      Pointer to the sid of the mapping to remove.
1114  *
1115  * @return #wbcErr
1116  *
1117  * @deprecated      This method is not impemented any more and should
1118  *                  be removed in the next major version change.
1119  **/
1120 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid);
1121
1122 /**
1123  * @brief Remove a group id mapping
1124  *
1125  * @param gid       Gid of the mapping to remove.
1126  * @param *sid      Pointer to the sid of the mapping to remove.
1127  *
1128  * @return #wbcErr
1129  *
1130  * @deprecated      This method is not impemented any more and should
1131  *                  be removed in the next major version change.
1132  **/
1133 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid);
1134
1135 /**
1136  * @brief Set the highwater mark for allocated uids.
1137  *
1138  * @param uid_hwm      The new uid highwater mark value
1139  *
1140  * @return #wbcErr
1141  *
1142  * @deprecated      This method is not impemented any more and should
1143  *                  be removed in the next major version change.
1144  **/
1145 wbcErr wbcSetUidHwm(uid_t uid_hwm);
1146
1147 /**
1148  * @brief Set the highwater mark for allocated gids.
1149  *
1150  * @param gid_hwm      The new gid highwater mark value
1151  *
1152  * @return #wbcErr
1153  *
1154  * @deprecated      This method is not impemented any more and should
1155  *                  be removed in the next major version change.
1156  **/
1157 wbcErr wbcSetGidHwm(gid_t gid_hwm);
1158
1159 /**********************************************************
1160  * NSS Lookup User/Group details
1161  **********************************************************/
1162
1163 /**
1164  * @brief Fill in a struct passwd* for a domain user based
1165  *   on username
1166  *
1167  * @param *ctx      wbclient Context
1168  * @param *name     Username to lookup
1169  * @param **pwd     Pointer to resulting struct passwd* from the query.
1170  *
1171  * @return #wbcErr
1172  **/
1173 wbcErr wbcCtxGetpwnam(struct wbcContext *ctx,
1174                       const char *name, struct passwd **pwd);
1175
1176 /**
1177  * @brief Fill in a struct passwd* for a domain user based
1178  *   on username
1179  *
1180  * @param *name     Username to lookup
1181  * @param **pwd     Pointer to resulting struct passwd* from the query.
1182  *
1183  * @return #wbcErr
1184  **/
1185 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
1186
1187 /**
1188  * @brief Fill in a struct passwd* for a domain user based
1189  *   on uid
1190  *
1191  * @param *ctx      wbclient Context
1192  * @param uid       Uid to lookup
1193  * @param **pwd     Pointer to resulting struct passwd* from the query.
1194  *
1195  * @return #wbcErr
1196  **/
1197 wbcErr wbcCtxGetpwuid(struct wbcContext *ctx,
1198                       uid_t uid, struct passwd **pwd);
1199
1200 /**
1201  * @brief Fill in a struct passwd* for a domain user based
1202  *   on uid
1203  *
1204  * @param uid       Uid to lookup
1205  * @param **pwd     Pointer to resulting struct passwd* from the query.
1206  *
1207  * @return #wbcErr
1208  **/
1209 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
1210
1211 /**
1212  * @brief Fill in a struct passwd* for a domain user based
1213  *   on sid
1214  *
1215  * @param *ctx         wbclient Context
1216  * @param sid       Sid to lookup
1217  * @param **pwd     Pointer to resulting struct passwd* from the query.
1218  *
1219  * @return #wbcErr
1220  **/
1221 wbcErr wbcCtxGetpwsid(struct wbcContext *ctx,
1222                       struct wbcDomainSid * sid, struct passwd **pwd);
1223
1224 /**
1225  * @brief Fill in a struct passwd* for a domain user based
1226  *   on sid
1227  *
1228  * @param sid       Sid to lookup
1229  * @param **pwd     Pointer to resulting struct passwd* from the query.
1230  *
1231  * @return #wbcErr
1232  **/
1233 wbcErr wbcGetpwsid(struct wbcDomainSid * sid, struct passwd **pwd);
1234
1235 /**
1236  * @brief Fill in a struct passwd* for a domain user based
1237  *   on username
1238  *
1239  * @param *ctx      wbclient Context
1240  * @param *name     Username to lookup
1241  * @param **grp     Pointer to resulting struct group* from the query.
1242  *
1243  * @return #wbcErr
1244  **/
1245 wbcErr wbcCtxGetgrnam(struct wbcContext *ctx,
1246                       const char *name, struct group **grp);
1247
1248 /**
1249  * @brief Fill in a struct passwd* for a domain user based
1250  *   on username
1251  *
1252  * @param *name     Username to lookup
1253  * @param **grp     Pointer to resulting struct group* from the query.
1254  *
1255  * @return #wbcErr
1256  **/
1257 wbcErr wbcGetgrnam(const char *name, struct group **grp);
1258
1259 /**
1260  * @brief Fill in a struct passwd* for a domain user based
1261  *   on uid
1262  *
1263  * @param *ctx      wbclient Context
1264  * @param gid       Uid to lookup
1265  * @param **grp     Pointer to resulting struct group* from the query.
1266  *
1267  * @return #wbcErr
1268  **/
1269 wbcErr wbcCtxGetgrgid(struct wbcContext *ctx,
1270                       gid_t gid, struct group **grp);
1271
1272 /**
1273  * @brief Fill in a struct passwd* for a domain user based
1274  *   on uid
1275  *
1276  * @param gid       Uid to lookup
1277  * @param **grp     Pointer to resulting struct group* from the query.
1278  *
1279  * @return #wbcErr
1280  **/
1281 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
1282
1283 /**
1284  * @brief Reset the passwd iterator
1285  *
1286  * @param *ctx      wbclient Context
1287  *
1288  * @return #wbcErr
1289  **/
1290 wbcErr wbcCtxSetpwent(struct wbcContext *ctx);
1291
1292 /**
1293  * @brief Reset the passwd iterator
1294  *
1295  * @return #wbcErr
1296  **/
1297 wbcErr wbcSetpwent(void);
1298
1299 /**
1300  * @brief Close the passwd iterator
1301  *
1302  * @param *ctx      wbclient Context
1303  *
1304  * @return #wbcErr
1305  **/
1306 wbcErr wbcCtxEndpwent(struct wbcContext *ctx);
1307
1308 /**
1309  * @brief Close the passwd iterator
1310  *
1311  * @return #wbcErr
1312  **/
1313 wbcErr wbcEndpwent(void);
1314
1315 /**
1316  * @brief Return the next struct passwd* entry from the pwent iterator
1317  *
1318  * @param *ctx      wbclient Context
1319  * @param **pwd     Pointer to resulting struct passwd* from the query.
1320  *
1321  * @return #wbcErr
1322  **/
1323 wbcErr wbcCtxGetpwent(struct wbcContext *ctx, struct passwd **pwd);
1324
1325 /**
1326  * @brief Return the next struct passwd* entry from the pwent iterator
1327  *
1328  * @param **pwd     Pointer to resulting struct passwd* from the query.
1329  *
1330  * @return #wbcErr
1331  **/
1332 wbcErr wbcGetpwent(struct passwd **pwd);
1333
1334 /**
1335  * @brief Reset the group iterator
1336  *
1337  * @param *ctx      wbclient Context
1338  *
1339  * @return #wbcErr
1340  **/
1341 wbcErr wbcCtxSetgrent(struct wbcContext *ctx);
1342
1343 /**
1344  * @brief Reset the group iterator
1345  *
1346  * @return #wbcErr
1347  **/
1348 wbcErr wbcSetgrent(void);
1349
1350 /**
1351  * @brief Close the group iterator
1352  *
1353  * @param *ctx      wbclient Context
1354  *
1355  * @return #wbcErr
1356  **/
1357 wbcErr wbcCtxEndgrent(struct wbcContext *ctx);
1358
1359 /**
1360  * @brief Close the group iterator
1361  *
1362  * @return #wbcErr
1363  **/
1364 wbcErr wbcEndgrent(void);
1365
1366 /**
1367  * @brief Return the next struct group* entry from the pwent iterator
1368  *
1369  * @param *ctx      wbclient Context
1370  * @param **grp     Pointer to resulting struct group* from the query.
1371  *
1372  * @return #wbcErr
1373  **/
1374 wbcErr wbcCtxGetgrent(struct wbcContext *ctx, struct group **grp);
1375
1376 /**
1377  * @brief Return the next struct group* entry from the pwent iterator
1378  *
1379  * @param **grp     Pointer to resulting struct group* from the query.
1380  *
1381  * @return #wbcErr
1382  **/
1383 wbcErr wbcGetgrent(struct group **grp);
1384
1385 /**
1386  * @brief Return the next struct group* entry from the pwent iterator
1387  *
1388  * This is similar to #wbcGetgrent, just that the member list is empty
1389  *
1390  * @param *ctx      wbclient Context
1391  * @param **grp     Pointer to resulting struct group* from the query.
1392  *
1393  * @return #wbcErr
1394  **/
1395 wbcErr wbcCtxGetgrlist(struct wbcContext *ctx, struct group **grp);
1396
1397 /**
1398  * @brief Return the next struct group* entry from the pwent iterator
1399  *
1400  * This is similar to #wbcGetgrent, just that the member list is empty
1401  *
1402  * @param **grp     Pointer to resulting struct group* from the query.
1403  *
1404  * @return #wbcErr
1405  **/
1406 wbcErr wbcGetgrlist(struct group **grp);
1407
1408 /**
1409  * @brief Return the unix group array belonging to the given user
1410  *
1411  * @param *ctx           wbclient Context
1412  * @param *account       The given user name
1413  * @param *num_groups    Number of elements returned in the groups array
1414  * @param **_groups      Pointer to resulting gid_t array.
1415  *
1416  * @return #wbcErr
1417  **/
1418 wbcErr wbcCtxGetGroups(struct wbcContext *ctx,
1419                        const char *account,
1420                        uint32_t *num_groups,
1421                        gid_t **_groups);
1422
1423 /**
1424  * @brief Return the unix group array belonging to the given user
1425  *
1426  * @param *account       The given user name
1427  * @param *num_groups    Number of elements returned in the groups array
1428  * @param **_groups      Pointer to resulting gid_t array.
1429  *
1430  * @return #wbcErr
1431  **/
1432 wbcErr wbcGetGroups(const char *account,
1433                     uint32_t *num_groups,
1434                     gid_t **_groups);
1435
1436
1437 /**********************************************************
1438  * Lookup Domain information
1439  **********************************************************/
1440
1441 /**
1442  * @brief Lookup the current status of a trusted domain
1443  *
1444  * @param *ctx           wbclient Context
1445  * @param domain         The domain to query
1446  *
1447  * @param dinfo          A pointer to store the returned domain_info struct.
1448  *
1449  * @return #wbcErr
1450  **/
1451 wbcErr wbcCtxDomainInfo(struct wbcContext *ctx,
1452                         const char *domain,
1453                         struct wbcDomainInfo **dinfo);
1454
1455 /**
1456  * @brief Lookup the current status of a trusted domain
1457  *
1458  * @param domain         The domain to query
1459  *
1460  * @param dinfo          A pointer to store the returned domain_info struct.
1461  *
1462  * @return #wbcErr
1463  **/
1464 wbcErr wbcDomainInfo(const char *domain,
1465                      struct wbcDomainInfo **dinfo);
1466
1467 /**
1468  * @brief Lookup the currently contacted DCs
1469  *
1470  * @param *ctx          wbclient Context
1471  * @param domain        The domain to query
1472  *
1473  * @param num_dcs       Number of DCs currently known
1474  * @param dc_names      Names of the currently known DCs
1475  * @param dc_ips        IP addresses of the currently known DCs
1476  *
1477  * @return #wbcErr
1478  **/
1479 wbcErr wbcCtxDcInfo(struct wbcContext *ctx,
1480                     const char *domain, size_t *num_dcs,
1481                     const char ***dc_names, const char ***dc_ips);
1482
1483 /**
1484  * @brief Lookup the currently contacted DCs
1485  *
1486  * @param domain        The domain to query
1487  *
1488  * @param num_dcs       Number of DCs currently known
1489  * @param dc_names      Names of the currently known DCs
1490  * @param dc_ips        IP addresses of the currently known DCs
1491  *
1492  * @return #wbcErr
1493  **/
1494 wbcErr wbcDcInfo(const char *domain, size_t *num_dcs,
1495                  const char ***dc_names, const char ***dc_ips);
1496
1497 /**
1498  * @brief Enumerate the domain trusts known by Winbind
1499  *
1500  * @param *ctx          wbclient Context
1501  * @param **domains     Pointer to the allocated domain list array
1502  * @param *num_domains  Pointer to number of domains returned
1503  *
1504  * @return #wbcErr
1505  **/
1506 wbcErr wbcCtxListTrusts(struct wbcContext *ctx,
1507                         struct wbcDomainInfo **domains,
1508                         size_t *num_domains);
1509
1510 /**
1511  * @brief Enumerate the domain trusts known by Winbind
1512  *
1513  * @param **domains     Pointer to the allocated domain list array
1514  * @param *num_domains  Pointer to number of domains returned
1515  *
1516  * @return #wbcErr
1517  **/
1518 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
1519                      size_t *num_domains);
1520
1521 /* Flags for wbcLookupDomainController */
1522
1523 #define WBC_LOOKUP_DC_FORCE_REDISCOVERY        0x00000001
1524 #define WBC_LOOKUP_DC_DS_REQUIRED              0x00000010
1525 #define WBC_LOOKUP_DC_DS_PREFERRED             0x00000020
1526 #define WBC_LOOKUP_DC_GC_SERVER_REQUIRED       0x00000040
1527 #define WBC_LOOKUP_DC_PDC_REQUIRED             0x00000080
1528 #define WBC_LOOKUP_DC_BACKGROUND_ONLY          0x00000100
1529 #define WBC_LOOKUP_DC_IP_REQUIRED              0x00000200
1530 #define WBC_LOOKUP_DC_KDC_REQUIRED             0x00000400
1531 #define WBC_LOOKUP_DC_TIMESERV_REQUIRED        0x00000800
1532 #define WBC_LOOKUP_DC_WRITABLE_REQUIRED        0x00001000
1533 #define WBC_LOOKUP_DC_GOOD_TIMESERV_PREFERRED  0x00002000
1534 #define WBC_LOOKUP_DC_AVOID_SELF               0x00004000
1535 #define WBC_LOOKUP_DC_ONLY_LDAP_NEEDED         0x00008000
1536 #define WBC_LOOKUP_DC_IS_FLAT_NAME             0x00010000
1537 #define WBC_LOOKUP_DC_IS_DNS_NAME              0x00020000
1538 #define WBC_LOOKUP_DC_TRY_NEXTCLOSEST_SITE     0x00040000
1539 #define WBC_LOOKUP_DC_DS_6_REQUIRED            0x00080000
1540 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
1541 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
1542
1543 /**
1544  * @brief Enumerate the domain trusts known by Winbind
1545  *
1546  * @param *ctx          wbclient Context
1547  * @param domain        Name of the domain to query for a DC
1548  * @param flags         Bit flags used to control the domain location query
1549  * @param *dc_info      Pointer to the returned domain controller information
1550  *
1551  * @return #wbcErr
1552  **/
1553 wbcErr wbcCtxLookupDomainController(struct wbcContext *ctx,
1554                                     const char *domain,
1555                                     uint32_t flags,
1556                                     struct wbcDomainControllerInfo **dc_info);
1557
1558 /**
1559  * @brief Enumerate the domain trusts known by Winbind
1560  *
1561  * @param domain        Name of the domain to query for a DC
1562  * @param flags         Bit flags used to control the domain location query
1563  * @param *dc_info      Pointer to the returned domain controller information
1564  *
1565  * @return #wbcErr
1566  **/
1567 wbcErr wbcLookupDomainController(const char *domain,
1568                                  uint32_t flags,
1569                                  struct wbcDomainControllerInfo **dc_info);
1570
1571 /**
1572  * @brief Get extended domain controller information
1573  *
1574  * @param *ctx          wbclient Context
1575  * @param domain        Name of the domain to query for a DC
1576  * @param guid          Guid of the domain to query for a DC
1577  * @param site          Site of the domain to query for a DC
1578  * @param flags         Bit flags used to control the domain location query
1579  * @param *dc_info      Pointer to the returned extended domain controller information
1580  *
1581  * @return #wbcErr
1582  **/
1583 wbcErr wbcCtxLookupDomainControllerEx(struct wbcContext *ctx,
1584                                       const char *domain,
1585                                       struct wbcGuid *guid,
1586                                       const char *site,
1587                                       uint32_t flags,
1588                                       struct wbcDomainControllerInfoEx **dc_info);
1589
1590 /**
1591  * @brief Get extended domain controller information
1592  *
1593  * @param domain        Name of the domain to query for a DC
1594  * @param guid          Guid of the domain to query for a DC
1595  * @param site          Site of the domain to query for a DC
1596  * @param flags         Bit flags used to control the domain location query
1597  * @param *dc_info      Pointer to the returned extended domain controller information
1598  *
1599  * @return #wbcErr
1600  **/
1601 wbcErr wbcLookupDomainControllerEx(const char *domain,
1602                                    struct wbcGuid *guid,
1603                                    const char *site,
1604                                    uint32_t flags,
1605                                    struct wbcDomainControllerInfoEx **dc_info);
1606
1607 /**********************************************************
1608  * Athenticate functions
1609  **********************************************************/
1610
1611 /**
1612  * @brief Authenticate a username/password pair
1613  *
1614  * @param *ctx         wbclient Context
1615  * @param username     Name of user to authenticate
1616  * @param password     Clear text password os user
1617  *
1618  * @return #wbcErr
1619  **/
1620 wbcErr wbcCtxAuthenticateUser(struct wbcContext *ctx,
1621                               const char *username,
1622                               const char *password);
1623
1624 /**
1625  * @brief Authenticate a username/password pair
1626  *
1627  * @param username     Name of user to authenticate
1628  * @param password     Clear text password os user
1629  *
1630  * @return #wbcErr
1631  **/
1632 wbcErr wbcAuthenticateUser(const char *username,
1633                            const char *password);
1634
1635 /**
1636  * @brief Authenticate with more detailed information
1637  *
1638  * @param *ctx         wbclient Context
1639  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1640  *                     is not supported yet
1641  * @param info         Output details on WBC_ERR_SUCCESS
1642  * @param error        Output details on WBC_ERR_AUTH_ERROR
1643  *
1644  * @return #wbcErr
1645  **/
1646 wbcErr wbcCtxAuthenticateUserEx(struct wbcContext *ctx,
1647                                 const struct wbcAuthUserParams *params,
1648                                 struct wbcAuthUserInfo **info,
1649                                 struct wbcAuthErrorInfo **error);
1650
1651 /**
1652  * @brief Authenticate with more detailed information
1653  *
1654  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1655  *                     is not supported yet
1656  * @param info         Output details on WBC_ERR_SUCCESS
1657  * @param error        Output details on WBC_ERR_AUTH_ERROR
1658  *
1659  * @return #wbcErr
1660  **/
1661 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
1662                              struct wbcAuthUserInfo **info,
1663                              struct wbcAuthErrorInfo **error);
1664
1665 /**
1666  * @brief Logon a User
1667  *
1668  * @param[in]  *ctx        wbclient Context
1669  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1670  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1671  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1672  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1673  *
1674  * @return #wbcErr
1675  **/
1676 wbcErr wbcCtxLogonUser(struct wbcContext *ctx,
1677                        const struct wbcLogonUserParams *params,
1678                        struct wbcLogonUserInfo **info,
1679                        struct wbcAuthErrorInfo **error,
1680                        struct wbcUserPasswordPolicyInfo **policy);
1681
1682 /**
1683  * @brief Logon a User
1684  *
1685  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1686  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1687  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1688  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1689  *
1690  * @return #wbcErr
1691  **/
1692 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
1693                     struct wbcLogonUserInfo **info,
1694                     struct wbcAuthErrorInfo **error,
1695                     struct wbcUserPasswordPolicyInfo **policy);
1696
1697 /**
1698  * @brief Trigger a logoff notification to Winbind for a specific user
1699  *
1700  * @param *ctx        wbclient Context
1701  * @param username    Name of user to remove from Winbind's list of
1702  *                    logged on users.
1703  * @param uid         Uid assigned to the username
1704  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1705  *                    be removed
1706  *
1707  * @return #wbcErr
1708  **/
1709 wbcErr wbcCtxLogoffUser(struct wbcContext *ctx,
1710                         const char *username, uid_t uid,
1711                         const char *ccfilename);
1712
1713 /**
1714  * @brief Trigger a logoff notification to Winbind for a specific user
1715  *
1716  * @param username    Name of user to remove from Winbind's list of
1717  *                    logged on users.
1718  * @param uid         Uid assigned to the username
1719  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1720  *                    be removed
1721  *
1722  * @return #wbcErr
1723  **/
1724 wbcErr wbcLogoffUser(const char *username,
1725                      uid_t uid,
1726                      const char *ccfilename);
1727
1728 /**
1729  * @brief Trigger an extended logoff notification to Winbind for a specific user
1730  *
1731  * @param *ctx        wbclient Context
1732  * @param params      A wbcLogoffUserParams structure
1733  * @param error       User output details on error
1734  *
1735  * @return #wbcErr
1736  **/
1737 wbcErr wbcCtxLogoffUserEx(struct wbcContext *ctx,
1738                           const struct wbcLogoffUserParams *params,
1739                           struct wbcAuthErrorInfo **error);
1740
1741 /**
1742  * @brief Trigger an extended logoff notification to Winbind for a specific user
1743  *
1744  * @param params      A wbcLogoffUserParams structure
1745  * @param error       User output details on error
1746  *
1747  * @return #wbcErr
1748  **/
1749 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
1750                        struct wbcAuthErrorInfo **error);
1751
1752 /**
1753  * @brief Change a password for a user
1754  *
1755  * @param *ctx          wbclient Context
1756  * @param username      Name of user to authenticate
1757  * @param old_password  Old clear text password of user
1758  * @param new_password  New clear text password of user
1759  *
1760  * @return #wbcErr
1761  **/
1762 wbcErr wbcCtxChangeUserPassword(struct wbcContext *ctx,
1763                                 const char *username,
1764                                 const char *old_password,
1765                                 const char *new_password);
1766
1767 /**
1768  * @brief Change a password for a user
1769  *
1770  * @param username      Name of user to authenticate
1771  * @param old_password  Old clear text password of user
1772  * @param new_password  New clear text password of user
1773  *
1774  * @return #wbcErr
1775  **/
1776 wbcErr wbcChangeUserPassword(const char *username,
1777                              const char *old_password,
1778                              const char *new_password);
1779
1780 /**
1781  * @brief Change a password for a user with more detailed information upon
1782  *   failure
1783  *
1784  * @param *ctx                  wbclient Context
1785  * @param params                Input parameters
1786  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1787  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1788  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1789  *
1790  * @return #wbcErr
1791  **/
1792 wbcErr wbcCtxChangeUserPasswordEx(struct wbcContext *ctx,
1793                                   const struct wbcChangePasswordParams *params,
1794                                   struct wbcAuthErrorInfo **error,
1795                                   enum wbcPasswordChangeRejectReason *reject_reason,
1796                                   struct wbcUserPasswordPolicyInfo **policy);
1797
1798 /**
1799  * @brief Change a password for a user with more detailed information upon
1800  *   failure
1801  *
1802  * @param params                Input parameters
1803  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1804  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1805  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1806  *
1807  * @return #wbcErr
1808  **/
1809 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
1810                                struct wbcAuthErrorInfo **error,
1811                                enum wbcPasswordChangeRejectReason *reject_reason,
1812                                struct wbcUserPasswordPolicyInfo **policy);
1813
1814 /**
1815  * @brief Authenticate a user with cached credentials
1816  *
1817  * @param *ctx       wbclient Context
1818  * @param *params    Pointer to a wbcCredentialCacheParams structure
1819  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1820  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1821  *
1822  * @return #wbcErr
1823  **/
1824 wbcErr wbcCtxCredentialCache(struct wbcContext *ctx,
1825                              struct wbcCredentialCacheParams *params,
1826                              struct wbcCredentialCacheInfo **info,
1827                              struct wbcAuthErrorInfo **error);
1828
1829 /**
1830  * @brief Authenticate a user with cached credentials
1831  *
1832  * @param *params    Pointer to a wbcCredentialCacheParams structure
1833  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1834  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1835  *
1836  * @return #wbcErr
1837  **/
1838 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
1839                           struct wbcCredentialCacheInfo **info,
1840                           struct wbcAuthErrorInfo **error);
1841
1842 /**
1843  * @brief Save a password with winbind for doing wbcCredentialCache() later
1844  *
1845  * @param *ctx       wbclient Context
1846  * @param *user      Username
1847  * @param *password  Password
1848  *
1849  * @return #wbcErr
1850  **/
1851 wbcErr wbcCtxCredentialSave(struct wbcContext *ctx,
1852                             const char *user, const char *password);
1853
1854 /**
1855  * @brief Save a password with winbind for doing wbcCredentialCache() later
1856  *
1857  * @param *user      Username
1858  * @param *password  Password
1859  *
1860  * @return #wbcErr
1861  **/
1862 wbcErr wbcCredentialSave(const char *user, const char *password);
1863
1864 /**********************************************************
1865  * Resolve functions
1866  **********************************************************/
1867
1868 /**
1869  * @brief Resolve a NetbiosName via WINS
1870  *
1871  * @param *ctx         wbclient Context
1872  * @param name         Name to resolve
1873  * @param *ip          Pointer to the ip address string
1874  *
1875  * @return #wbcErr
1876  **/
1877 wbcErr wbcCtxResolveWinsByName(struct wbcContext *ctx,
1878                                const char *name, char **ip);
1879
1880 /**
1881  * @brief Resolve a NetbiosName via WINS
1882  *
1883  * @param name         Name to resolve
1884  * @param *ip          Pointer to the ip address string
1885  *
1886  * @return #wbcErr
1887  **/
1888 wbcErr wbcResolveWinsByName(const char *name, char **ip);
1889
1890 /**
1891  * @brief Resolve an IP address via WINS into a NetbiosName
1892  *
1893  * @param *ctx         wbclient Context
1894  * @param ip           The ip address string
1895  * @param *name        Pointer to the name
1896  *
1897  * @return #wbcErr
1898  *
1899  **/
1900 wbcErr wbcCtxResolveWinsByIP(struct wbcContext *ctx,
1901                              const char *ip, char **name);
1902
1903 /**
1904  * @brief Resolve an IP address via WINS into a NetbiosName
1905  *
1906  * @param ip           The ip address string
1907  * @param *name        Pointer to the name
1908  *
1909  * @return #wbcErr
1910  *
1911  **/
1912 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
1913
1914 /**********************************************************
1915  * Trusted domain functions
1916  **********************************************************/
1917
1918 /**
1919  * @brief Trigger a verification of the trust credentials of a specific domain
1920  *
1921  * @param *ctx         wbclient Context
1922  * @param *domain      The name of the domain.
1923  * @param error        Output details on WBC_ERR_AUTH_ERROR
1924  *
1925  * @return #wbcErr
1926  **/
1927 wbcErr wbcCtxCheckTrustCredentials(struct wbcContext *ctx, const char *domain,
1928                                    struct wbcAuthErrorInfo **error);
1929
1930 /**
1931  * @brief Trigger a verification of the trust credentials of a specific domain
1932  *
1933  * @param *domain      The name of the domain.
1934  * @param error        Output details on WBC_ERR_AUTH_ERROR
1935  *
1936  * @return #wbcErr
1937  **/
1938 wbcErr wbcCheckTrustCredentials(const char *domain,
1939                                 struct wbcAuthErrorInfo **error);
1940
1941 /**
1942  * @brief Trigger a change of the trust credentials for a specific domain
1943  *
1944  * @param *ctx         wbclient Context
1945  * @param *domain      The name of the domain.
1946  * @param error        Output details on WBC_ERR_AUTH_ERROR
1947  *
1948  * @return #wbcErr
1949  **/
1950 wbcErr wbcCtxChangeTrustCredentials(struct wbcContext *ctx, const char *domain,
1951                                     struct wbcAuthErrorInfo **error);
1952
1953 /**
1954  * @brief Trigger a change of the trust credentials for a specific domain
1955  *
1956  * @param *domain      The name of the domain.
1957  * @param error        Output details on WBC_ERR_AUTH_ERROR
1958  *
1959  * @return #wbcErr
1960  **/
1961 wbcErr wbcChangeTrustCredentials(const char *domain,
1962                                  struct wbcAuthErrorInfo **error);
1963
1964 /**
1965  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
1966  *        version of wbcCheckTrustCredentials
1967  *
1968  * @param *ctx         wbclient Context
1969  * @param *domain      The name of the domain, only NULL for the default domain is
1970  *                     supported yet. Other values than NULL will result in
1971  *                     WBC_ERR_NOT_IMPLEMENTED.
1972  * @param error        Output details on WBC_ERR_AUTH_ERROR
1973  *
1974  * @return #wbcErr
1975  **/
1976 wbcErr wbcCtxPingDc(struct wbcContext *ctx, const char *domain,
1977                     struct wbcAuthErrorInfo **error);
1978
1979 /**
1980  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
1981  *        version of wbcCheckTrustCredentials
1982  *
1983  * @param *domain      The name of the domain, only NULL for the default domain is
1984  *                     supported yet. Other values than NULL will result in
1985  *                     WBC_ERR_NOT_IMPLEMENTED.
1986  * @param error        Output details on WBC_ERR_AUTH_ERROR
1987  *
1988  * @return #wbcErr
1989  **/
1990 wbcErr wbcPingDc(const char *domain, struct wbcAuthErrorInfo **error);
1991
1992 /**
1993  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
1994  *        version of wbcCheckTrustCredentials
1995  *
1996  * @param *ctx         wbclient Context
1997  * @param *domain      The name of the domain, only NULL for the default domain is
1998  *                     supported yet. Other values than NULL will result in
1999  *                     WBC_ERR_NOT_IMPLEMENTED.
2000  * @param error        Output details on WBC_ERR_AUTH_ERROR
2001  * @param dcname       DC that was attempted to ping
2002  *
2003  * @return #wbcErr
2004  **/
2005 wbcErr wbcCtxPingDc2(struct wbcContext *ctx, const char *domain,
2006                      struct wbcAuthErrorInfo **error,
2007                      char **dcname);
2008
2009 /**
2010  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
2011  *        version of wbcCheckTrustCredentials
2012  *
2013  * @param *domain      The name of the domain, only NULL for the default domain is
2014  *                     supported yet. Other values than NULL will result in
2015  *                     WBC_ERR_NOT_IMPLEMENTED.
2016  * @param error        Output details on WBC_ERR_AUTH_ERROR
2017  * @param dcname       DC that was attempted to ping
2018  *
2019  * @return #wbcErr
2020  **/
2021 wbcErr wbcPingDc2(const char *domain, struct wbcAuthErrorInfo **error,
2022                   char **dcname);
2023
2024 /**********************************************************
2025  * Helper functions
2026  **********************************************************/
2027
2028 /**
2029  * @brief Initialize a named blob and add to list of blobs
2030  *
2031  * @param[in,out] num_blobs     Pointer to the number of blobs
2032  * @param[in,out] blobs         Pointer to an array of blobs
2033  * @param[in]     name          Name of the new named blob
2034  * @param[in]     flags         Flags of the new named blob
2035  * @param[in]     data          Blob data of new blob
2036  * @param[in]     length        Blob data length of new blob
2037  *
2038  * @return #wbcErr
2039  **/
2040 wbcErr wbcAddNamedBlob(size_t *num_blobs,
2041                        struct wbcNamedBlob **blobs,
2042                        const char *name,
2043                        uint32_t flags,
2044                        uint8_t *data,
2045                        size_t length);
2046
2047 #endif      /* _WBCLIENT_H */