722int getacflg(char *auditstr, int len);
723int getacna(char *auditstr, int len);
724int getacpol(char *auditstr, size_t len);
725int getauditflagsbin(char *auditstr, au_mask_t *masks);
726int getauditflagschar(char *auditstr, au_mask_t *masks,
727 int verbose);
728int au_preselect(au_event_t event, au_mask_t *mask_p,
729 int sorf, int flag);
730ssize_t au_poltostr(long policy, size_t maxsize, char *buf);
731int au_strtopol(const char *polstr, long *policy);
732
733/*
734 * Functions relating to querying audit event information.
735 */
736void setauevent(void);
737void endauevent(void);
738struct au_event_ent *getauevent(void);
739struct au_event_ent *getauevent_r(struct au_event_ent *e);
740struct au_event_ent *getauevnam(const char *name);
741struct au_event_ent *getauevnam_r(struct au_event_ent *e,
742 const char *name);
743struct au_event_ent *getauevnum(au_event_t event_number);
744struct au_event_ent *getauevnum_r(struct au_event_ent *e,
745 au_event_t event_number);
746au_event_t *getauevnonam(const char *event_name);
747au_event_t *getauevnonam_r(au_event_t *ev,
748 const char *event_name);
749
750/*
751 * Functions relating to querying audit user information.
752 */
753void setauuser(void);
754void endauuser(void);
755struct au_user_ent *getauuserent(void);
756struct au_user_ent *getauuserent_r(struct au_user_ent *u);
757struct au_user_ent *getauusernam(const char *name);
758struct au_user_ent *getauusernam_r(struct au_user_ent *u,
759 const char *name);
760int au_user_mask(char *username, au_mask_t *mask_p);
761int getfauditflags(au_mask_t *usremask,
762 au_mask_t *usrdmask, au_mask_t *lastmask);
763
764/*
765 * Functions for reading and printing records and tokens from audit trails.
766 */
767int au_read_rec(FILE *fp, u_char **buf);
768int au_fetch_tok(tokenstr_t *tok, u_char *buf, int len);
769//XXX The following interface has different prototype from BSM
770void au_print_tok(FILE *outfp, tokenstr_t *tok,
771 char *del, char raw, char sfrm);
772__END_DECLS
773
774/*
775 * The remaining APIs are associated with Apple's BSM implementation, in
776 * particular as relates to Mach IPC auditing and triggers passed via Mach
777 * IPC.
778 */
779#ifdef __APPLE__
780#include <sys/appleapiopts.h>
781
782/**************************************************************************
783 **************************************************************************
784 ** The following definitions, functions, etc., are NOT officially
785 ** supported: they may be changed or removed in the future. Do not use
786 ** them unless you are prepared to cope with that eventuality.
787 **************************************************************************
788 **************************************************************************/
789
790#ifdef __APPLE_API_PRIVATE
791#define __BSM_INTERNAL_NOTIFY_KEY "com.apple.audit.change"
792#endif /* __APPLE_API_PRIVATE */
793
794/*
795 * au_get_state() return values
796 * XXX use AUC_* values directly instead (<bsm/audit.h>); AUDIT_OFF and
797 * AUDIT_ON are deprecated and WILL be removed.
798 */
799#ifdef __APPLE_API_PRIVATE
800#define AUDIT_OFF AUC_NOAUDIT
801#define AUDIT_ON AUC_AUDITING
802#endif /* __APPLE_API_PRIVATE */
803#endif /* !__APPLE__ */
804
805/*
806 * Error return codes for audit_set_terminal_id(), audit_write() and its
807 * brethren. We have 255 (not including kAUNoErr) to play with.
808 *
809 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
810 */
811enum {
812 kAUNoErr = 0,
813 kAUBadParamErr = -66049,
814 kAUStatErr,
815 kAUSysctlErr,
816 kAUOpenErr,
817 kAUMakeSubjectTokErr,
818 kAUWriteSubjectTokErr,
819 kAUWriteCallerTokErr,
820 kAUMakeReturnTokErr,
821 kAUWriteReturnTokErr,
822 kAUCloseErr,
823 kAUMakeTextTokErr,
824 kAULastErr
825};
826
827#ifdef __APPLE__
828/*
829 * Error return codes for au_get_state() and/or its private support
830 * functions. These codes are designed to be compatible with the
831 * NOTIFY_STATUS_* codes defined in <notify.h> but non-overlapping.
832 * Any changes to notify(3) may cause these values to change in future.
833 *
834 * AU_UNIMPL should never happen unless you've changed your system software
835 * without rebooting. Shame on you.
836 */
837#ifdef __APPLE_API_PRIVATE
838#define AU_UNIMPL NOTIFY_STATUS_FAILED + 1 /* audit unimplemented */
839#endif /* __APPLE_API_PRIVATE */
840#endif /* !__APPLE__ */
841
842__BEGIN_DECLS
843/*
844 * XXX This prototype should be in audit_record.h
845 *
846 * au_free_token()
847 *
848 * @summary - au_free_token() deallocates a token_t created by any of
849 * the au_to_*() BSM API functions.
850 *
851 * The BSM API generally manages deallocation of token_t objects. However,
852 * if au_write() is passed a bad audit descriptor, the token_t * parameter
853 * will be left untouched. In that case, the caller can deallocate the
854 * token_t using au_free_token() if desired. This is, in fact, what
855 * audit_write() does, in keeping with the existing memory management model
856 * of the BSM API.
857 *
858 * @param tok - A token_t * generated by one of the au_to_*() BSM API
859 * calls. For convenience, tok may be NULL, in which case
860 * au_free_token() returns immediately.
861 *
862 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
863 */
864void au_free_token(token_t *tok);
865
866/*
867 * Lightweight check to determine if auditing is enabled. If a client
868 * wants to use this to govern whether an entire series of audit calls
869 * should be made--as in the common case of a caller building a set of
870 * tokens, then writing them--it should cache the audit status in a local
871 * variable. This call always returns the current state of auditing.
872 *
873 * @return - AUC_AUDITING or AUC_NOAUDIT if no error occurred.
874 * Otherwise the function can return any of the errno values defined for
875 * setaudit(2), or AU_UNIMPL if audit does not appear to be supported by
876 * the system.
877 *
878 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
879 */
880int au_get_state(void);
881__END_DECLS
882
883/* OpenSSH compatibility */
884int cannot_audit(int);
885
886__BEGIN_DECLS
887/*
888 * audit_set_terminal_id()
889 *
890 * @summary - audit_set_terminal_id() fills in an au_tid_t struct, which is
891 * used in audit session initialization by processes like /usr/bin/login.
892 *
893 * @param tid - A pointer to an au_tid_t struct.
894 *
895 * @return - kAUNoErr on success; kAUBadParamErr if tid is NULL, kAUStatErr
896 * or kAUSysctlErr if one of the underlying system calls fails (a message
897 * is sent to the system log in those cases).
898 *
899 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
900 */
901int audit_set_terminal_id(au_tid_t *tid);
902
903/*
904 * BEGIN au_write() WRAPPERS
905 *
906 * The following calls all wrap the existing BSM API. They use the
907 * provided subject information, if any, to construct the subject token
908 * required for every log message. They use the provided return/error
909 * value(s), if any, to construct the success/failure indication required
910 * for every log message. They only permit one "miscellaneous" token,
911 * which should contain the event-specific logging information mandated by
912 * CAPP.
913 *
914 * All these calls assume the caller has previously determined that
915 * auditing is enabled by calling au_get_state().
916 */
917
918/*
919 * audit_write()
920 *
921 * @summary - audit_write() is the basis for the other audit_write_*()
922 * calls. Performs a basic write of an audit record (subject, additional
923 * info, success/failure). Note that this call only permits logging one
924 * caller-specified token; clients needing to log more flexibly must use
925 * the existing BSM API (au_open(), et al.) directly.
926 *
927 * Note on memory management: audit_write() guarantees that the token_t *s
928 * passed to it will be deallocated whether or not the underlying write to
929 * the audit log succeeded. This addresses an inconsistency in the
930 * underlying BSM API in which token_t *s are usually but not always
931 * deallocated.
932 *
933 * @param event_code - The code for the event being logged. This should
934 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
935 *
936 * @param subject - A token_t * generated by au_to_subject(),
937 * au_to_subject32(), au_to_subject64(), or au_to_me(). If no subject is
938 * required, subject should be NULL.
939 *
940 * @param misctok - A token_t * generated by one of the au_to_*() BSM API
941 * calls. This should correspond to the additional information required by
942 * CAPP for the event being audited. If no additional information is
943 * required, misctok should be NULL.
944 *
945 * @param retval - The return value to be logged for this event. This
946 * should be 0 (zero) for success, otherwise the value is event-specific.
947 *
948 * @param errcode - Any error code associated with the return value (e.g.,
949 * errno or h_errno). If there was no error, errcode should be 0 (zero).
950 *
951 * @return - The status of the call: 0 (zero) on success, else one of the
952 * kAU*Err values defined above.
953 *
954 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
955 */
956int audit_write(short event_code, token_t *subject, token_t *misctok,
957 char retval, int errcode);
958
959/*
960 * audit_write_success()
961 *
962 * @summary - audit_write_success() records an auditable event that did not
963 * encounter an error. The interface is designed to require as little
964 * direct use of the au_to_*() API as possible. It builds a subject token
965 * from the information passed in and uses that to invoke audit_write().
966 * A subject, as defined by CAPP, is a process acting on the user's behalf.
967 *
968 * If the subject information is the same as the current process, use
969 * au_write_success_self().
970 *
971 * @param event_code - The code for the event being logged. This should
972 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
973 *
974 * @param misctok - A token_t * generated by one of the au_to_*() BSM API
975 * calls. This should correspond to the additional information required by
976 * CAPP for the event being audited. If no additional information is
977 * required, misctok should be NULL.
978 *
979 * @param auid - The subject's audit ID.
980 *
981 * @param euid - The subject's effective user ID.
982 *
983 * @param egid - The subject's effective group ID.
984 *
985 * @param ruid - The subject's real user ID.
986 *
987 * @param rgid - The subject's real group ID.
988 *
989 * @param pid - The subject's process ID.
990 *
991 * @param sid - The subject's session ID.
992 *
993 * @param tid - The subject's terminal ID.
994 *
995 * @return - The status of the call: 0 (zero) on success, else one of the
996 * kAU*Err values defined above.
997 *
998 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
999 */
1000int audit_write_success(short event_code, token_t *misctok, au_id_t auid,
1001 uid_t euid, gid_t egid, uid_t ruid, gid_t rgid, pid_t pid,
1002 au_asid_t sid, au_tid_t *tid);
1003
1004/*
1005 * audit_write_success_self()
1006 *
1007 * @summary - Similar to audit_write_success(), but used when the subject
1008 * (process) is owned and operated by the auditable user him/herself.
1009 *
1010 * @param event_code - The code for the event being logged. This should
1011 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1012 *
1013 * @param misctok - A token_t * generated by one of the au_to_*() BSM API
1014 * calls. This should correspond to the additional information required by
1015 * CAPP for the event being audited. If no additional information is
1016 * required, misctok should be NULL.
1017 *
1018 * @return - The status of the call: 0 (zero) on success, else one of the
1019 * kAU*Err values defined above.
1020 *
1021 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1022 */
1023int audit_write_success_self(short event_code, token_t *misctok);
1024
1025/*
1026 * audit_write_failure()
1027 *
1028 * @summary - audit_write_failure() records an auditable event that
1029 * encountered an error. The interface is designed to require as little
1030 * direct use of the au_to_*() API as possible. It builds a subject token
1031 * from the information passed in and uses that to invoke audit_write().
1032 * A subject, as defined by CAPP, is a process acting on the user's behalf.
1033 *
1034 * If the subject information is the same as the current process, use
1035 * au_write_failure_self().
1036 *
1037 * @param event_code - The code for the event being logged. This should
1038 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1039 *
1040 * @param errmsg - A text message providing additional information about
1041 * the event being audited.
1042 *
1043 * @param errret - A numerical value providing additional information about
1044 * the error. This is intended to store the value of errno or h_errno if
1045 * it's relevant. This can be 0 (zero) if no additional information is
1046 * available.
1047 *
1048 * @param auid - The subject's audit ID.
1049 *
1050 * @param euid - The subject's effective user ID.
1051 *
1052 * @param egid - The subject's effective group ID.
1053 *
1054 * @param ruid - The subject's real user ID.
1055 *
1056 * @param rgid - The subject's real group ID.
1057 *
1058 * @param pid - The subject's process ID.
1059 *
1060 * @param sid - The subject's session ID.
1061 *
1062 * @param tid - The subject's terminal ID.
1063 *
1064 * @return - The status of the call: 0 (zero) on success, else one of the
1065 * kAU*Err values defined above.
1066 *
1067 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1068 */
1069int audit_write_failure(short event_code, char *errmsg, int errret,
1070 au_id_t auid, uid_t euid, gid_t egid, uid_t ruid, gid_t rgid,
1071 pid_t pid, au_asid_t sid, au_tid_t *tid);
1072
1073/*
1074 * audit_write_failure_self()
1075 *
1076 * @summary - Similar to audit_write_failure(), but used when the subject
1077 * (process) is owned and operated by the auditable user him/herself.
1078 *
1079 * @param event_code - The code for the event being logged. This should
1080 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1081 *
1082 * @param errmsg - A text message providing additional information about
1083 * the event being audited.
1084 *
1085 * @param errret - A numerical value providing additional information about
1086 * the error. This is intended to store the value of errno or h_errno if
1087 * it's relevant. This can be 0 (zero) if no additional information is
1088 * available.
1089 *
1090 * @return - The status of the call: 0 (zero) on success, else one of the
1091 * kAU*Err values defined above.
1092 *
1093 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1094 */
1095int audit_write_failure_self(short event_code, char *errmsg, int errret);
1096
1097/*
1098 * audit_write_failure_na()
1099 *
1100 * @summary - audit_write_failure_na() records errors during login. Such
1101 * errors are implicitly non-attributable (i.e., not ascribable to any user).
1102 *
1103 * @param event_code - The code for the event being logged. This should
1104 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1105 *
1106 * @param errmsg - A text message providing additional information about
1107 * the event being audited.
1108 *
1109 * @param errret - A numerical value providing additional information about
1110 * the error. This is intended to store the value of errno or h_errno if
1111 * it's relevant. This can be 0 (zero) if no additional information is
1112 * available.
1113 *
1114 * @param euid - The subject's effective user ID.
1115 *
1116 * @param egid - The subject's effective group ID.
1117 *
1118 * @param pid - The subject's process ID.
1119 *
1120 * @param tid - The subject's terminal ID.
1121 *
1122 * @return - The status of the call: 0 (zero) on success, else one of the
1123 * kAU*Err values defined above.
1124 *
1125 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1126 */
1127int audit_write_failure_na(short event_code, char *errmsg, int errret,
1128 uid_t euid, gid_t egid, pid_t pid, au_tid_t *tid);
1129
1130/* END au_write() WRAPPERS */
1131
1132#ifdef __APPLE__
1133/*
1134 * audit_token_to_au32()
1135 *
1136 * @summary - Extract information from an audit_token_t, used to identify
1137 * Mach tasks and senders of Mach messages as subjects to the audit system.
1138 * audit_tokent_to_au32() is the only method that should be used to parse
1139 * an audit_token_t, since its internal representation may change over
1140 * time. A pointer parameter may be NULL if that information is not
1141 * needed.
1142 *
1143 * @param atoken - the audit token containing the desired information
1144 *
1145 * @param auidp - Pointer to a uid_t; on return will be set to the task or
1146 * sender's audit user ID
1147 *
1148 * @param euidp - Pointer to a uid_t; on return will be set to the task or
1149 * sender's effective user ID
1150 *
1151 * @param egidp - Pointer to a gid_t; on return will be set to the task or
1152 * sender's effective group ID
1153 *
1154 * @param ruidp - Pointer to a uid_t; on return will be set to the task or
1155 * sender's real user ID
1156 *
1157 * @param rgidp - Pointer to a gid_t; on return will be set to the task or
1158 * sender's real group ID
1159 *
1160 * @param pidp - Pointer to a pid_t; on return will be set to the task or
1161 * sender's process ID
1162 *
1163 * @param asidp - Pointer to an au_asid_t; on return will be set to the
1164 * task or sender's audit session ID
1165 *
1166 * @param tidp - Pointer to an au_tid_t; on return will be set to the task
1167 * or sender's terminal ID
1168 *
1169 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1170 */
1171void audit_token_to_au32(
1172 audit_token_t atoken,
1173 uid_t *auidp,
1174 uid_t *euidp,
1175 gid_t *egidp,
1176 uid_t *ruidp,
1177 gid_t *rgidp,
1178 pid_t *pidp,
1179 au_asid_t *asidp,
1180 au_tid_t *tidp);
1181#endif /* !__APPLE__ */
1182
1183__END_DECLS
1184
1185#endif /* !_LIBBSM_H_ */
| 724int getacflg(char *auditstr, int len);
725int getacna(char *auditstr, int len);
726int getacpol(char *auditstr, size_t len);
727int getauditflagsbin(char *auditstr, au_mask_t *masks);
728int getauditflagschar(char *auditstr, au_mask_t *masks,
729 int verbose);
730int au_preselect(au_event_t event, au_mask_t *mask_p,
731 int sorf, int flag);
732ssize_t au_poltostr(long policy, size_t maxsize, char *buf);
733int au_strtopol(const char *polstr, long *policy);
734
735/*
736 * Functions relating to querying audit event information.
737 */
738void setauevent(void);
739void endauevent(void);
740struct au_event_ent *getauevent(void);
741struct au_event_ent *getauevent_r(struct au_event_ent *e);
742struct au_event_ent *getauevnam(const char *name);
743struct au_event_ent *getauevnam_r(struct au_event_ent *e,
744 const char *name);
745struct au_event_ent *getauevnum(au_event_t event_number);
746struct au_event_ent *getauevnum_r(struct au_event_ent *e,
747 au_event_t event_number);
748au_event_t *getauevnonam(const char *event_name);
749au_event_t *getauevnonam_r(au_event_t *ev,
750 const char *event_name);
751
752/*
753 * Functions relating to querying audit user information.
754 */
755void setauuser(void);
756void endauuser(void);
757struct au_user_ent *getauuserent(void);
758struct au_user_ent *getauuserent_r(struct au_user_ent *u);
759struct au_user_ent *getauusernam(const char *name);
760struct au_user_ent *getauusernam_r(struct au_user_ent *u,
761 const char *name);
762int au_user_mask(char *username, au_mask_t *mask_p);
763int getfauditflags(au_mask_t *usremask,
764 au_mask_t *usrdmask, au_mask_t *lastmask);
765
766/*
767 * Functions for reading and printing records and tokens from audit trails.
768 */
769int au_read_rec(FILE *fp, u_char **buf);
770int au_fetch_tok(tokenstr_t *tok, u_char *buf, int len);
771//XXX The following interface has different prototype from BSM
772void au_print_tok(FILE *outfp, tokenstr_t *tok,
773 char *del, char raw, char sfrm);
774__END_DECLS
775
776/*
777 * The remaining APIs are associated with Apple's BSM implementation, in
778 * particular as relates to Mach IPC auditing and triggers passed via Mach
779 * IPC.
780 */
781#ifdef __APPLE__
782#include <sys/appleapiopts.h>
783
784/**************************************************************************
785 **************************************************************************
786 ** The following definitions, functions, etc., are NOT officially
787 ** supported: they may be changed or removed in the future. Do not use
788 ** them unless you are prepared to cope with that eventuality.
789 **************************************************************************
790 **************************************************************************/
791
792#ifdef __APPLE_API_PRIVATE
793#define __BSM_INTERNAL_NOTIFY_KEY "com.apple.audit.change"
794#endif /* __APPLE_API_PRIVATE */
795
796/*
797 * au_get_state() return values
798 * XXX use AUC_* values directly instead (<bsm/audit.h>); AUDIT_OFF and
799 * AUDIT_ON are deprecated and WILL be removed.
800 */
801#ifdef __APPLE_API_PRIVATE
802#define AUDIT_OFF AUC_NOAUDIT
803#define AUDIT_ON AUC_AUDITING
804#endif /* __APPLE_API_PRIVATE */
805#endif /* !__APPLE__ */
806
807/*
808 * Error return codes for audit_set_terminal_id(), audit_write() and its
809 * brethren. We have 255 (not including kAUNoErr) to play with.
810 *
811 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
812 */
813enum {
814 kAUNoErr = 0,
815 kAUBadParamErr = -66049,
816 kAUStatErr,
817 kAUSysctlErr,
818 kAUOpenErr,
819 kAUMakeSubjectTokErr,
820 kAUWriteSubjectTokErr,
821 kAUWriteCallerTokErr,
822 kAUMakeReturnTokErr,
823 kAUWriteReturnTokErr,
824 kAUCloseErr,
825 kAUMakeTextTokErr,
826 kAULastErr
827};
828
829#ifdef __APPLE__
830/*
831 * Error return codes for au_get_state() and/or its private support
832 * functions. These codes are designed to be compatible with the
833 * NOTIFY_STATUS_* codes defined in <notify.h> but non-overlapping.
834 * Any changes to notify(3) may cause these values to change in future.
835 *
836 * AU_UNIMPL should never happen unless you've changed your system software
837 * without rebooting. Shame on you.
838 */
839#ifdef __APPLE_API_PRIVATE
840#define AU_UNIMPL NOTIFY_STATUS_FAILED + 1 /* audit unimplemented */
841#endif /* __APPLE_API_PRIVATE */
842#endif /* !__APPLE__ */
843
844__BEGIN_DECLS
845/*
846 * XXX This prototype should be in audit_record.h
847 *
848 * au_free_token()
849 *
850 * @summary - au_free_token() deallocates a token_t created by any of
851 * the au_to_*() BSM API functions.
852 *
853 * The BSM API generally manages deallocation of token_t objects. However,
854 * if au_write() is passed a bad audit descriptor, the token_t * parameter
855 * will be left untouched. In that case, the caller can deallocate the
856 * token_t using au_free_token() if desired. This is, in fact, what
857 * audit_write() does, in keeping with the existing memory management model
858 * of the BSM API.
859 *
860 * @param tok - A token_t * generated by one of the au_to_*() BSM API
861 * calls. For convenience, tok may be NULL, in which case
862 * au_free_token() returns immediately.
863 *
864 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
865 */
866void au_free_token(token_t *tok);
867
868/*
869 * Lightweight check to determine if auditing is enabled. If a client
870 * wants to use this to govern whether an entire series of audit calls
871 * should be made--as in the common case of a caller building a set of
872 * tokens, then writing them--it should cache the audit status in a local
873 * variable. This call always returns the current state of auditing.
874 *
875 * @return - AUC_AUDITING or AUC_NOAUDIT if no error occurred.
876 * Otherwise the function can return any of the errno values defined for
877 * setaudit(2), or AU_UNIMPL if audit does not appear to be supported by
878 * the system.
879 *
880 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
881 */
882int au_get_state(void);
883__END_DECLS
884
885/* OpenSSH compatibility */
886int cannot_audit(int);
887
888__BEGIN_DECLS
889/*
890 * audit_set_terminal_id()
891 *
892 * @summary - audit_set_terminal_id() fills in an au_tid_t struct, which is
893 * used in audit session initialization by processes like /usr/bin/login.
894 *
895 * @param tid - A pointer to an au_tid_t struct.
896 *
897 * @return - kAUNoErr on success; kAUBadParamErr if tid is NULL, kAUStatErr
898 * or kAUSysctlErr if one of the underlying system calls fails (a message
899 * is sent to the system log in those cases).
900 *
901 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
902 */
903int audit_set_terminal_id(au_tid_t *tid);
904
905/*
906 * BEGIN au_write() WRAPPERS
907 *
908 * The following calls all wrap the existing BSM API. They use the
909 * provided subject information, if any, to construct the subject token
910 * required for every log message. They use the provided return/error
911 * value(s), if any, to construct the success/failure indication required
912 * for every log message. They only permit one "miscellaneous" token,
913 * which should contain the event-specific logging information mandated by
914 * CAPP.
915 *
916 * All these calls assume the caller has previously determined that
917 * auditing is enabled by calling au_get_state().
918 */
919
920/*
921 * audit_write()
922 *
923 * @summary - audit_write() is the basis for the other audit_write_*()
924 * calls. Performs a basic write of an audit record (subject, additional
925 * info, success/failure). Note that this call only permits logging one
926 * caller-specified token; clients needing to log more flexibly must use
927 * the existing BSM API (au_open(), et al.) directly.
928 *
929 * Note on memory management: audit_write() guarantees that the token_t *s
930 * passed to it will be deallocated whether or not the underlying write to
931 * the audit log succeeded. This addresses an inconsistency in the
932 * underlying BSM API in which token_t *s are usually but not always
933 * deallocated.
934 *
935 * @param event_code - The code for the event being logged. This should
936 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
937 *
938 * @param subject - A token_t * generated by au_to_subject(),
939 * au_to_subject32(), au_to_subject64(), or au_to_me(). If no subject is
940 * required, subject should be NULL.
941 *
942 * @param misctok - A token_t * generated by one of the au_to_*() BSM API
943 * calls. This should correspond to the additional information required by
944 * CAPP for the event being audited. If no additional information is
945 * required, misctok should be NULL.
946 *
947 * @param retval - The return value to be logged for this event. This
948 * should be 0 (zero) for success, otherwise the value is event-specific.
949 *
950 * @param errcode - Any error code associated with the return value (e.g.,
951 * errno or h_errno). If there was no error, errcode should be 0 (zero).
952 *
953 * @return - The status of the call: 0 (zero) on success, else one of the
954 * kAU*Err values defined above.
955 *
956 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
957 */
958int audit_write(short event_code, token_t *subject, token_t *misctok,
959 char retval, int errcode);
960
961/*
962 * audit_write_success()
963 *
964 * @summary - audit_write_success() records an auditable event that did not
965 * encounter an error. The interface is designed to require as little
966 * direct use of the au_to_*() API as possible. It builds a subject token
967 * from the information passed in and uses that to invoke audit_write().
968 * A subject, as defined by CAPP, is a process acting on the user's behalf.
969 *
970 * If the subject information is the same as the current process, use
971 * au_write_success_self().
972 *
973 * @param event_code - The code for the event being logged. This should
974 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
975 *
976 * @param misctok - A token_t * generated by one of the au_to_*() BSM API
977 * calls. This should correspond to the additional information required by
978 * CAPP for the event being audited. If no additional information is
979 * required, misctok should be NULL.
980 *
981 * @param auid - The subject's audit ID.
982 *
983 * @param euid - The subject's effective user ID.
984 *
985 * @param egid - The subject's effective group ID.
986 *
987 * @param ruid - The subject's real user ID.
988 *
989 * @param rgid - The subject's real group ID.
990 *
991 * @param pid - The subject's process ID.
992 *
993 * @param sid - The subject's session ID.
994 *
995 * @param tid - The subject's terminal ID.
996 *
997 * @return - The status of the call: 0 (zero) on success, else one of the
998 * kAU*Err values defined above.
999 *
1000 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1001 */
1002int audit_write_success(short event_code, token_t *misctok, au_id_t auid,
1003 uid_t euid, gid_t egid, uid_t ruid, gid_t rgid, pid_t pid,
1004 au_asid_t sid, au_tid_t *tid);
1005
1006/*
1007 * audit_write_success_self()
1008 *
1009 * @summary - Similar to audit_write_success(), but used when the subject
1010 * (process) is owned and operated by the auditable user him/herself.
1011 *
1012 * @param event_code - The code for the event being logged. This should
1013 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1014 *
1015 * @param misctok - A token_t * generated by one of the au_to_*() BSM API
1016 * calls. This should correspond to the additional information required by
1017 * CAPP for the event being audited. If no additional information is
1018 * required, misctok should be NULL.
1019 *
1020 * @return - The status of the call: 0 (zero) on success, else one of the
1021 * kAU*Err values defined above.
1022 *
1023 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1024 */
1025int audit_write_success_self(short event_code, token_t *misctok);
1026
1027/*
1028 * audit_write_failure()
1029 *
1030 * @summary - audit_write_failure() records an auditable event that
1031 * encountered an error. The interface is designed to require as little
1032 * direct use of the au_to_*() API as possible. It builds a subject token
1033 * from the information passed in and uses that to invoke audit_write().
1034 * A subject, as defined by CAPP, is a process acting on the user's behalf.
1035 *
1036 * If the subject information is the same as the current process, use
1037 * au_write_failure_self().
1038 *
1039 * @param event_code - The code for the event being logged. This should
1040 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1041 *
1042 * @param errmsg - A text message providing additional information about
1043 * the event being audited.
1044 *
1045 * @param errret - A numerical value providing additional information about
1046 * the error. This is intended to store the value of errno or h_errno if
1047 * it's relevant. This can be 0 (zero) if no additional information is
1048 * available.
1049 *
1050 * @param auid - The subject's audit ID.
1051 *
1052 * @param euid - The subject's effective user ID.
1053 *
1054 * @param egid - The subject's effective group ID.
1055 *
1056 * @param ruid - The subject's real user ID.
1057 *
1058 * @param rgid - The subject's real group ID.
1059 *
1060 * @param pid - The subject's process ID.
1061 *
1062 * @param sid - The subject's session ID.
1063 *
1064 * @param tid - The subject's terminal ID.
1065 *
1066 * @return - The status of the call: 0 (zero) on success, else one of the
1067 * kAU*Err values defined above.
1068 *
1069 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1070 */
1071int audit_write_failure(short event_code, char *errmsg, int errret,
1072 au_id_t auid, uid_t euid, gid_t egid, uid_t ruid, gid_t rgid,
1073 pid_t pid, au_asid_t sid, au_tid_t *tid);
1074
1075/*
1076 * audit_write_failure_self()
1077 *
1078 * @summary - Similar to audit_write_failure(), but used when the subject
1079 * (process) is owned and operated by the auditable user him/herself.
1080 *
1081 * @param event_code - The code for the event being logged. This should
1082 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1083 *
1084 * @param errmsg - A text message providing additional information about
1085 * the event being audited.
1086 *
1087 * @param errret - A numerical value providing additional information about
1088 * the error. This is intended to store the value of errno or h_errno if
1089 * it's relevant. This can be 0 (zero) if no additional information is
1090 * available.
1091 *
1092 * @return - The status of the call: 0 (zero) on success, else one of the
1093 * kAU*Err values defined above.
1094 *
1095 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1096 */
1097int audit_write_failure_self(short event_code, char *errmsg, int errret);
1098
1099/*
1100 * audit_write_failure_na()
1101 *
1102 * @summary - audit_write_failure_na() records errors during login. Such
1103 * errors are implicitly non-attributable (i.e., not ascribable to any user).
1104 *
1105 * @param event_code - The code for the event being logged. This should
1106 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h.
1107 *
1108 * @param errmsg - A text message providing additional information about
1109 * the event being audited.
1110 *
1111 * @param errret - A numerical value providing additional information about
1112 * the error. This is intended to store the value of errno or h_errno if
1113 * it's relevant. This can be 0 (zero) if no additional information is
1114 * available.
1115 *
1116 * @param euid - The subject's effective user ID.
1117 *
1118 * @param egid - The subject's effective group ID.
1119 *
1120 * @param pid - The subject's process ID.
1121 *
1122 * @param tid - The subject's terminal ID.
1123 *
1124 * @return - The status of the call: 0 (zero) on success, else one of the
1125 * kAU*Err values defined above.
1126 *
1127 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1128 */
1129int audit_write_failure_na(short event_code, char *errmsg, int errret,
1130 uid_t euid, gid_t egid, pid_t pid, au_tid_t *tid);
1131
1132/* END au_write() WRAPPERS */
1133
1134#ifdef __APPLE__
1135/*
1136 * audit_token_to_au32()
1137 *
1138 * @summary - Extract information from an audit_token_t, used to identify
1139 * Mach tasks and senders of Mach messages as subjects to the audit system.
1140 * audit_tokent_to_au32() is the only method that should be used to parse
1141 * an audit_token_t, since its internal representation may change over
1142 * time. A pointer parameter may be NULL if that information is not
1143 * needed.
1144 *
1145 * @param atoken - the audit token containing the desired information
1146 *
1147 * @param auidp - Pointer to a uid_t; on return will be set to the task or
1148 * sender's audit user ID
1149 *
1150 * @param euidp - Pointer to a uid_t; on return will be set to the task or
1151 * sender's effective user ID
1152 *
1153 * @param egidp - Pointer to a gid_t; on return will be set to the task or
1154 * sender's effective group ID
1155 *
1156 * @param ruidp - Pointer to a uid_t; on return will be set to the task or
1157 * sender's real user ID
1158 *
1159 * @param rgidp - Pointer to a gid_t; on return will be set to the task or
1160 * sender's real group ID
1161 *
1162 * @param pidp - Pointer to a pid_t; on return will be set to the task or
1163 * sender's process ID
1164 *
1165 * @param asidp - Pointer to an au_asid_t; on return will be set to the
1166 * task or sender's audit session ID
1167 *
1168 * @param tidp - Pointer to an au_tid_t; on return will be set to the task
1169 * or sender's terminal ID
1170 *
1171 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE.
1172 */
1173void audit_token_to_au32(
1174 audit_token_t atoken,
1175 uid_t *auidp,
1176 uid_t *euidp,
1177 gid_t *egidp,
1178 uid_t *ruidp,
1179 gid_t *rgidp,
1180 pid_t *pidp,
1181 au_asid_t *asidp,
1182 au_tid_t *tidp);
1183#endif /* !__APPLE__ */
1184
1185__END_DECLS
1186
1187#endif /* !_LIBBSM_H_ */
|