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