ptrace.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. #ifndef _LINUX_PTRACE_H
  3. #define _LINUX_PTRACE_H
  4. #include <linux/compiler.h> /* For unlikely. */
  5. #include <linux/sched.h> /* For struct task_struct. */
  6. #include <linux/sched/signal.h> /* For send_sig(), same_thread_group(), etc. */
  7. #include <linux/err.h> /* for IS_ERR_VALUE */
  8. #include <linux/bug.h> /* For BUG_ON. */
  9. #include <linux/pid_namespace.h> /* For task_active_pid_ns. */
  10. #include <uapi/linux/ptrace.h>
  11. #include <linux/seccomp.h>
  12. /* Add sp to seccomp_data, as seccomp is user API, we don't want to modify it */
  13. struct syscall_info {
  14. __u64 sp;
  15. struct seccomp_data data;
  16. };
  17. extern int ptrace_access_vm(struct task_struct *tsk, unsigned long addr,
  18. void *buf, int len, unsigned int gup_flags);
  19. /*
  20. * Ptrace flags
  21. *
  22. * The owner ship rules for task->ptrace which holds the ptrace
  23. * flags is simple. When a task is running it owns it's task->ptrace
  24. * flags. When the a task is stopped the ptracer owns task->ptrace.
  25. */
  26. #define PT_SEIZED 0x00010000 /* SEIZE used, enable new behavior */
  27. #define PT_PTRACED 0x00000001
  28. #define PT_OPT_FLAG_SHIFT 3
  29. /* PT_TRACE_* event enable flags */
  30. #define PT_EVENT_FLAG(event) (1 << (PT_OPT_FLAG_SHIFT + (event)))
  31. #define PT_TRACESYSGOOD PT_EVENT_FLAG(0)
  32. #define PT_TRACE_FORK PT_EVENT_FLAG(PTRACE_EVENT_FORK)
  33. #define PT_TRACE_VFORK PT_EVENT_FLAG(PTRACE_EVENT_VFORK)
  34. #define PT_TRACE_CLONE PT_EVENT_FLAG(PTRACE_EVENT_CLONE)
  35. #define PT_TRACE_EXEC PT_EVENT_FLAG(PTRACE_EVENT_EXEC)
  36. #define PT_TRACE_VFORK_DONE PT_EVENT_FLAG(PTRACE_EVENT_VFORK_DONE)
  37. #define PT_TRACE_EXIT PT_EVENT_FLAG(PTRACE_EVENT_EXIT)
  38. #define PT_TRACE_SECCOMP PT_EVENT_FLAG(PTRACE_EVENT_SECCOMP)
  39. #define PT_EXITKILL (PTRACE_O_EXITKILL << PT_OPT_FLAG_SHIFT)
  40. #define PT_SUSPEND_SECCOMP (PTRACE_O_SUSPEND_SECCOMP << PT_OPT_FLAG_SHIFT)
  41. extern long arch_ptrace(struct task_struct *child, long request,
  42. unsigned long addr, unsigned long data);
  43. extern int ptrace_readdata(struct task_struct *tsk, unsigned long src, char __user *dst, int len);
  44. extern int ptrace_writedata(struct task_struct *tsk, char __user *src, unsigned long dst, int len);
  45. extern void ptrace_disable(struct task_struct *);
  46. extern int ptrace_request(struct task_struct *child, long request,
  47. unsigned long addr, unsigned long data);
  48. extern int ptrace_notify(int exit_code, unsigned long message);
  49. extern void __ptrace_link(struct task_struct *child,
  50. struct task_struct *new_parent,
  51. const struct cred *ptracer_cred);
  52. extern void __ptrace_unlink(struct task_struct *child);
  53. extern void exit_ptrace(struct task_struct *tracer, struct list_head *dead);
  54. #define PTRACE_MODE_READ 0x01
  55. #define PTRACE_MODE_ATTACH 0x02
  56. #define PTRACE_MODE_NOAUDIT 0x04
  57. #define PTRACE_MODE_FSCREDS 0x08
  58. #define PTRACE_MODE_REALCREDS 0x10
  59. /* shorthands for READ/ATTACH and FSCREDS/REALCREDS combinations */
  60. #define PTRACE_MODE_READ_FSCREDS (PTRACE_MODE_READ | PTRACE_MODE_FSCREDS)
  61. #define PTRACE_MODE_READ_REALCREDS (PTRACE_MODE_READ | PTRACE_MODE_REALCREDS)
  62. #define PTRACE_MODE_ATTACH_FSCREDS (PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS)
  63. #define PTRACE_MODE_ATTACH_REALCREDS (PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS)
  64. /**
  65. * ptrace_may_access - check whether the caller is permitted to access
  66. * a target task.
  67. * @task: target task
  68. * @mode: selects type of access and caller credentials
  69. *
  70. * Returns true on success, false on denial.
  71. *
  72. * One of the flags PTRACE_MODE_FSCREDS and PTRACE_MODE_REALCREDS must
  73. * be set in @mode to specify whether the access was requested through
  74. * a filesystem syscall (should use effective capabilities and fsuid
  75. * of the caller) or through an explicit syscall such as
  76. * process_vm_writev or ptrace (and should use the real credentials).
  77. */
  78. extern bool ptrace_may_access(struct task_struct *task, unsigned int mode);
  79. static inline int ptrace_reparented(struct task_struct *child)
  80. {
  81. return !same_thread_group(child->real_parent, child->parent);
  82. }
  83. static inline void ptrace_unlink(struct task_struct *child)
  84. {
  85. if (unlikely(child->ptrace))
  86. __ptrace_unlink(child);
  87. }
  88. int generic_ptrace_peekdata(struct task_struct *tsk, unsigned long addr,
  89. unsigned long data);
  90. int generic_ptrace_pokedata(struct task_struct *tsk, unsigned long addr,
  91. unsigned long data);
  92. /**
  93. * ptrace_parent - return the task that is tracing the given task
  94. * @task: task to consider
  95. *
  96. * Returns %NULL if no one is tracing @task, or the &struct task_struct
  97. * pointer to its tracer.
  98. *
  99. * Must called under rcu_read_lock(). The pointer returned might be kept
  100. * live only by RCU. During exec, this may be called with task_lock() held
  101. * on @task, still held from when check_unsafe_exec() was called.
  102. */
  103. static inline struct task_struct *ptrace_parent(struct task_struct *task)
  104. {
  105. if (unlikely(task->ptrace))
  106. return rcu_dereference(task->parent);
  107. return NULL;
  108. }
  109. /**
  110. * ptrace_event_enabled - test whether a ptrace event is enabled
  111. * @task: ptracee of interest
  112. * @event: %PTRACE_EVENT_* to test
  113. *
  114. * Test whether @event is enabled for ptracee @task.
  115. *
  116. * Returns %true if @event is enabled, %false otherwise.
  117. */
  118. static inline bool ptrace_event_enabled(struct task_struct *task, int event)
  119. {
  120. return task->ptrace & PT_EVENT_FLAG(event);
  121. }
  122. /**
  123. * ptrace_event - possibly stop for a ptrace event notification
  124. * @event: %PTRACE_EVENT_* value to report
  125. * @message: value for %PTRACE_GETEVENTMSG to return
  126. *
  127. * Check whether @event is enabled and, if so, report @event and @message
  128. * to the ptrace parent.
  129. *
  130. * Called without locks.
  131. */
  132. static inline void ptrace_event(int event, unsigned long message)
  133. {
  134. if (unlikely(ptrace_event_enabled(current, event))) {
  135. ptrace_notify((event << 8) | SIGTRAP, message);
  136. } else if (event == PTRACE_EVENT_EXEC) {
  137. /* legacy EXEC report via SIGTRAP */
  138. if ((current->ptrace & (PT_PTRACED|PT_SEIZED)) == PT_PTRACED)
  139. send_sig(SIGTRAP, current, 0);
  140. }
  141. }
  142. /**
  143. * ptrace_event_pid - possibly stop for a ptrace event notification
  144. * @event: %PTRACE_EVENT_* value to report
  145. * @pid: process identifier for %PTRACE_GETEVENTMSG to return
  146. *
  147. * Check whether @event is enabled and, if so, report @event and @pid
  148. * to the ptrace parent. @pid is reported as the pid_t seen from the
  149. * ptrace parent's pid namespace.
  150. *
  151. * Called without locks.
  152. */
  153. static inline void ptrace_event_pid(int event, struct pid *pid)
  154. {
  155. /*
  156. * FIXME: There's a potential race if a ptracer in a different pid
  157. * namespace than parent attaches between computing message below and
  158. * when we acquire tasklist_lock in ptrace_stop(). If this happens,
  159. * the ptracer will get a bogus pid from PTRACE_GETEVENTMSG.
  160. */
  161. unsigned long message = 0;
  162. struct pid_namespace *ns;
  163. rcu_read_lock();
  164. ns = task_active_pid_ns(rcu_dereference(current->parent));
  165. if (ns)
  166. message = pid_nr_ns(pid, ns);
  167. rcu_read_unlock();
  168. ptrace_event(event, message);
  169. }
  170. /**
  171. * ptrace_init_task - initialize ptrace state for a new child
  172. * @child: new child task
  173. * @ptrace: true if child should be ptrace'd by parent's tracer
  174. *
  175. * This is called immediately after adding @child to its parent's children
  176. * list. @ptrace is false in the normal case, and true to ptrace @child.
  177. *
  178. * Called with current's siglock and write_lock_irq(&tasklist_lock) held.
  179. */
  180. static inline void ptrace_init_task(struct task_struct *child, bool ptrace)
  181. {
  182. INIT_LIST_HEAD(&child->ptrace_entry);
  183. INIT_LIST_HEAD(&child->ptraced);
  184. child->jobctl = 0;
  185. child->ptrace = 0;
  186. child->parent = child->real_parent;
  187. if (unlikely(ptrace) && current->ptrace) {
  188. child->ptrace = current->ptrace;
  189. __ptrace_link(child, current->parent, current->ptracer_cred);
  190. if (child->ptrace & PT_SEIZED)
  191. task_set_jobctl_pending(child, JOBCTL_TRAP_STOP);
  192. else
  193. sigaddset(&child->pending.signal, SIGSTOP);
  194. }
  195. else
  196. child->ptracer_cred = NULL;
  197. }
  198. /**
  199. * ptrace_release_task - final ptrace-related cleanup of a zombie being reaped
  200. * @task: task in %EXIT_DEAD state
  201. *
  202. * Called with write_lock(&tasklist_lock) held.
  203. */
  204. static inline void ptrace_release_task(struct task_struct *task)
  205. {
  206. BUG_ON(!list_empty(&task->ptraced));
  207. ptrace_unlink(task);
  208. BUG_ON(!list_empty(&task->ptrace_entry));
  209. }
  210. #ifndef force_successful_syscall_return
  211. /*
  212. * System call handlers that, upon successful completion, need to return a
  213. * negative value should call force_successful_syscall_return() right before
  214. * returning. On architectures where the syscall convention provides for a
  215. * separate error flag (e.g., alpha, ia64, ppc{,64}, sparc{,64}, possibly
  216. * others), this macro can be used to ensure that the error flag will not get
  217. * set. On architectures which do not support a separate error flag, the macro
  218. * is a no-op and the spurious error condition needs to be filtered out by some
  219. * other means (e.g., in user-level, by passing an extra argument to the
  220. * syscall handler, or something along those lines).
  221. */
  222. #define force_successful_syscall_return() do { } while (0)
  223. #endif
  224. #ifndef is_syscall_success
  225. /*
  226. * On most systems we can tell if a syscall is a success based on if the retval
  227. * is an error value. On some systems like ia64 and powerpc they have different
  228. * indicators of success/failure and must define their own.
  229. */
  230. #define is_syscall_success(regs) (!IS_ERR_VALUE((unsigned long)(regs_return_value(regs))))
  231. #endif
  232. /*
  233. * <asm/ptrace.h> should define the following things inside #ifdef __KERNEL__.
  234. *
  235. * These do-nothing inlines are used when the arch does not
  236. * implement single-step. The kerneldoc comments are here
  237. * to document the interface for all arch definitions.
  238. */
  239. #ifndef arch_has_single_step
  240. /**
  241. * arch_has_single_step - does this CPU support user-mode single-step?
  242. *
  243. * If this is defined, then there must be function declarations or
  244. * inlines for user_enable_single_step() and user_disable_single_step().
  245. * arch_has_single_step() should evaluate to nonzero iff the machine
  246. * supports instruction single-step for user mode.
  247. * It can be a constant or it can test a CPU feature bit.
  248. */
  249. #define arch_has_single_step() (0)
  250. /**
  251. * user_enable_single_step - single-step in user-mode task
  252. * @task: either current or a task stopped in %TASK_TRACED
  253. *
  254. * This can only be called when arch_has_single_step() has returned nonzero.
  255. * Set @task so that when it returns to user mode, it will trap after the
  256. * next single instruction executes. If arch_has_block_step() is defined,
  257. * this must clear the effects of user_enable_block_step() too.
  258. */
  259. static inline void user_enable_single_step(struct task_struct *task)
  260. {
  261. BUG(); /* This can never be called. */
  262. }
  263. /**
  264. * user_disable_single_step - cancel user-mode single-step
  265. * @task: either current or a task stopped in %TASK_TRACED
  266. *
  267. * Clear @task of the effects of user_enable_single_step() and
  268. * user_enable_block_step(). This can be called whether or not either
  269. * of those was ever called on @task, and even if arch_has_single_step()
  270. * returned zero.
  271. */
  272. static inline void user_disable_single_step(struct task_struct *task)
  273. {
  274. }
  275. #else
  276. extern void user_enable_single_step(struct task_struct *);
  277. extern void user_disable_single_step(struct task_struct *);
  278. #endif /* arch_has_single_step */
  279. #ifndef arch_has_block_step
  280. /**
  281. * arch_has_block_step - does this CPU support user-mode block-step?
  282. *
  283. * If this is defined, then there must be a function declaration or inline
  284. * for user_enable_block_step(), and arch_has_single_step() must be defined
  285. * too. arch_has_block_step() should evaluate to nonzero iff the machine
  286. * supports step-until-branch for user mode. It can be a constant or it
  287. * can test a CPU feature bit.
  288. */
  289. #define arch_has_block_step() (0)
  290. /**
  291. * user_enable_block_step - step until branch in user-mode task
  292. * @task: either current or a task stopped in %TASK_TRACED
  293. *
  294. * This can only be called when arch_has_block_step() has returned nonzero,
  295. * and will never be called when single-instruction stepping is being used.
  296. * Set @task so that when it returns to user mode, it will trap after the
  297. * next branch or trap taken.
  298. */
  299. static inline void user_enable_block_step(struct task_struct *task)
  300. {
  301. BUG(); /* This can never be called. */
  302. }
  303. #else
  304. extern void user_enable_block_step(struct task_struct *);
  305. #endif /* arch_has_block_step */
  306. #ifdef ARCH_HAS_USER_SINGLE_STEP_REPORT
  307. extern void user_single_step_report(struct pt_regs *regs);
  308. #else
  309. static inline void user_single_step_report(struct pt_regs *regs)
  310. {
  311. kernel_siginfo_t info;
  312. clear_siginfo(&info);
  313. info.si_signo = SIGTRAP;
  314. info.si_errno = 0;
  315. info.si_code = SI_USER;
  316. info.si_pid = 0;
  317. info.si_uid = 0;
  318. force_sig_info(&info);
  319. }
  320. #endif
  321. #ifndef arch_ptrace_stop_needed
  322. /**
  323. * arch_ptrace_stop_needed - Decide whether arch_ptrace_stop() should be called
  324. *
  325. * This is called with the siglock held, to decide whether or not it's
  326. * necessary to release the siglock and call arch_ptrace_stop(). It can be
  327. * defined to a constant if arch_ptrace_stop() is never required, or always
  328. * is. On machines where this makes sense, it should be defined to a quick
  329. * test to optimize out calling arch_ptrace_stop() when it would be
  330. * superfluous. For example, if the thread has not been back to user mode
  331. * since the last stop, the thread state might indicate that nothing needs
  332. * to be done.
  333. *
  334. * This is guaranteed to be invoked once before a task stops for ptrace and
  335. * may include arch-specific operations necessary prior to a ptrace stop.
  336. */
  337. #define arch_ptrace_stop_needed() (0)
  338. #endif
  339. #ifndef arch_ptrace_stop
  340. /**
  341. * arch_ptrace_stop - Do machine-specific work before stopping for ptrace
  342. *
  343. * This is called with no locks held when arch_ptrace_stop_needed() has
  344. * just returned nonzero. It is allowed to block, e.g. for user memory
  345. * access. The arch can have machine-specific work to be done before
  346. * ptrace stops. On ia64, register backing store gets written back to user
  347. * memory here. Since this can be costly (requires dropping the siglock),
  348. * we only do it when the arch requires it for this particular stop, as
  349. * indicated by arch_ptrace_stop_needed().
  350. */
  351. #define arch_ptrace_stop() do { } while (0)
  352. #endif
  353. #ifndef current_pt_regs
  354. #define current_pt_regs() task_pt_regs(current)
  355. #endif
  356. /*
  357. * unlike current_pt_regs(), this one is equal to task_pt_regs(current)
  358. * on *all* architectures; the only reason to have a per-arch definition
  359. * is optimisation.
  360. */
  361. #ifndef signal_pt_regs
  362. #define signal_pt_regs() task_pt_regs(current)
  363. #endif
  364. #ifndef current_user_stack_pointer
  365. #define current_user_stack_pointer() user_stack_pointer(current_pt_regs())
  366. #endif
  367. extern int task_current_syscall(struct task_struct *target, struct syscall_info *info);
  368. extern void sigaction_compat_abi(struct k_sigaction *act, struct k_sigaction *oact);
  369. /*
  370. * ptrace report for syscall entry and exit looks identical.
  371. */
  372. static inline int ptrace_report_syscall(unsigned long message)
  373. {
  374. int ptrace = current->ptrace;
  375. int signr;
  376. if (!(ptrace & PT_PTRACED))
  377. return 0;
  378. signr = ptrace_notify(SIGTRAP | ((ptrace & PT_TRACESYSGOOD) ? 0x80 : 0),
  379. message);
  380. /*
  381. * this isn't the same as continuing with a signal, but it will do
  382. * for normal use. strace only continues with a signal if the
  383. * stopping signal is not SIGTRAP. -brl
  384. */
  385. if (signr)
  386. send_sig(signr, current, 1);
  387. return fatal_signal_pending(current);
  388. }
  389. /**
  390. * ptrace_report_syscall_entry - task is about to attempt a system call
  391. * @regs: user register state of current task
  392. *
  393. * This will be called if %SYSCALL_WORK_SYSCALL_TRACE or
  394. * %SYSCALL_WORK_SYSCALL_EMU have been set, when the current task has just
  395. * entered the kernel for a system call. Full user register state is
  396. * available here. Changing the values in @regs can affect the system
  397. * call number and arguments to be tried. It is safe to block here,
  398. * preventing the system call from beginning.
  399. *
  400. * Returns zero normally, or nonzero if the calling arch code should abort
  401. * the system call. That must prevent normal entry so no system call is
  402. * made. If @task ever returns to user mode after this, its register state
  403. * is unspecified, but should be something harmless like an %ENOSYS error
  404. * return. It should preserve enough information so that syscall_rollback()
  405. * can work (see asm-generic/syscall.h).
  406. *
  407. * Called without locks, just after entering kernel mode.
  408. */
  409. static inline __must_check int ptrace_report_syscall_entry(
  410. struct pt_regs *regs)
  411. {
  412. return ptrace_report_syscall(PTRACE_EVENTMSG_SYSCALL_ENTRY);
  413. }
  414. /**
  415. * ptrace_report_syscall_exit - task has just finished a system call
  416. * @regs: user register state of current task
  417. * @step: nonzero if simulating single-step or block-step
  418. *
  419. * This will be called if %SYSCALL_WORK_SYSCALL_TRACE has been set, when
  420. * the current task has just finished an attempted system call. Full
  421. * user register state is available here. It is safe to block here,
  422. * preventing signals from being processed.
  423. *
  424. * If @step is nonzero, this report is also in lieu of the normal
  425. * trap that would follow the system call instruction because
  426. * user_enable_block_step() or user_enable_single_step() was used.
  427. * In this case, %SYSCALL_WORK_SYSCALL_TRACE might not be set.
  428. *
  429. * Called without locks, just before checking for pending signals.
  430. */
  431. static inline void ptrace_report_syscall_exit(struct pt_regs *regs, int step)
  432. {
  433. if (step)
  434. user_single_step_report(regs);
  435. else
  436. ptrace_report_syscall(PTRACE_EVENTMSG_SYSCALL_EXIT);
  437. }
  438. #endif