From 6fa4ac7d090747be2a87c70945f10584dd539400 Mon Sep 17 00:00:00 2001
From: Gleb Surikov <glebs.surikovs@gmail.com>
Date: Mon, 17 Jun 2024 17:30:13 +0300
Subject: [PATCH] [NTOS:PS] NtOpenJobObject: - SAL2 annotate NtOpenJobObject
 and related user-mode functions - Re-format NtOpenJobObject - Don't use
 hungarian notation for handles in NtCreateJobObject and NtOpenJobObject

---
 dll/win32/kernel32/client/job.c | 20 ++++++------
 ntoskrnl/ps/job.c               | 57 ++++++++++++++++++++-------------
 2 files changed, 44 insertions(+), 33 deletions(-)

diff --git a/dll/win32/kernel32/client/job.c b/dll/win32/kernel32/client/job.c
index c40f7fc6654..1d26cc063e5 100644
--- a/dll/win32/kernel32/client/job.c
+++ b/dll/win32/kernel32/client/job.c
@@ -23,8 +23,8 @@
  */
 HANDLE
 WINAPI
-CreateJobObjectA(IN LPSECURITY_ATTRIBUTES lpJobAttributes,
-                 IN LPCSTR lpName)
+CreateJobObjectA(_In_ LPSECURITY_ATTRIBUTES lpJobAttributes,
+                 _In_ LPCSTR lpName)
 {
     /* Call the W(ide) function */
     ConvertWin32AnsiObjectApiToUnicodeApi(JobObject, lpName, lpJobAttributes);
@@ -35,8 +35,8 @@ CreateJobObjectA(IN LPSECURITY_ATTRIBUTES lpJobAttributes,
  */
 HANDLE
 WINAPI
-CreateJobObjectW(IN LPSECURITY_ATTRIBUTES lpJobAttributes,
-                 IN LPCWSTR lpName)
+CreateJobObjectW(_In_ LPSECURITY_ATTRIBUTES lpJobAttributes,
+                 _In_ LPCWSTR lpName)
 {
     /* Create the NT object */
     CreateNtObjectFromWin32Api(JobObject, JobObject, JOB_OBJECT_ALL_ACCESS, lpJobAttributes, lpName);
@@ -47,9 +47,9 @@ CreateJobObjectW(IN LPSECURITY_ATTRIBUTES lpJobAttributes,
  */
 HANDLE
 WINAPI
-OpenJobObjectW(IN DWORD dwDesiredAccess,
-               IN BOOL bInheritHandle,
-               IN LPCWSTR lpName)
+OpenJobObjectW(_In_ DWORD dwDesiredAccess,
+               _In_ BOOL bInheritHandle,
+               _In_ LPCWSTR lpName)
 {
     /* Open the NT object */
     OpenNtObjectFromWin32Api(JobObject, dwDesiredAccess, bInheritHandle, lpName);
@@ -61,9 +61,9 @@ OpenJobObjectW(IN DWORD dwDesiredAccess,
  */
 HANDLE
 WINAPI
-OpenJobObjectA(IN DWORD dwDesiredAccess,
-               IN BOOL bInheritHandle,
-               IN LPCSTR lpName)
+OpenJobObjectA(_In_ DWORD dwDesiredAccess,
+               _In_ BOOL bInheritHandle,
+               _In_ LPCSTR lpName)
 {
     /* Call the W(ide) function */
     ConvertOpenWin32AnsiObjectApiToUnicodeApi(JobObject, dwDesiredAccess, bInheritHandle, lpName);
diff --git a/ntoskrnl/ps/job.c b/ntoskrnl/ps/job.c
index b634a179423..a99f97d42a5 100644
--- a/ntoskrnl/ps/job.c
+++ b/ntoskrnl/ps/job.c
@@ -256,7 +256,6 @@ NtCreateJobSet(IN ULONG NumJob,
  *
  * @param[out] JobHandle
  *     A pointer to a handle that will receive the handle of the created job object.
- *     The caller must have write access to this memory.
  *
  * @param[in] DesiredAccess
  *     Specifies the desired access rights for the job object.
@@ -264,7 +263,7 @@ NtCreateJobSet(IN ULONG NumJob,
  * @param[in, optional] ObjectAttributes
  *     An optional pointer to an object attributes block
  *
-* @returns
+ * @returns
  *     STATUS_SUCCESS if the job object is successfully created.
  *     An appropriate NTSTATUS error code otherwise.
  */
@@ -276,7 +275,7 @@ NtCreateJobObject(
     _In_opt_ POBJECT_ATTRIBUTES ObjectAttributes
 )
 {
-    HANDLE hJob;
+    HANDLE Handle;
     PEJOB Job;
     KPROCESSOR_MODE PreviousMode;
     PEPROCESS CurrentProcess;
@@ -348,7 +347,7 @@ NtCreateJobObject(
                                 DesiredAccess,
                                 0,
                                 NULL,
-                                &hJob);
+                                &Handle);
         if (NT_SUCCESS(Status))
         {
             /* Pass the handle back to the caller */
@@ -357,7 +356,7 @@ NtCreateJobObject(
                 /* NOTE: if the caller passed invalid buffers to receive the handle it's his
                    own fault! the object will still be created and live... It's possible
                    to find the handle using ObFindHandleForObject()! */
-                *JobHandle = hJob;
+                *JobHandle = Handle;
             }
             _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
             {
@@ -437,26 +436,39 @@ NtIsProcessInJob (
     return Status;
 }
 
-
-/*
- * @implemented
+/*!
+ * Opens a handle to an existing job object.
+ *
+ * @param JobHandle
+ *     A pointer to a handle that will receive the handle of the created job object.
+ *
+ * @param DesiredAccess
+ *     Specifies the desired access rights for the job object.
+ *
+ * @param ObjectAttributes
+ *     Pointer to the OBJECT_ATTRIBUTES structure specifying the object name and attributes.
+ *
+ * @returns
+ *     STATUS_SUCCESS if the job object is successfully created.
+ *     An appropriate NTSTATUS error code otherwise.
  */
 NTSTATUS
 NTAPI
-NtOpenJobObject (
-    PHANDLE JobHandle,
-    ACCESS_MASK DesiredAccess,
-    POBJECT_ATTRIBUTES ObjectAttributes)
+NtOpenJobObject(
+    _Out_ PHANDLE JobHandle,
+    _In_ ACCESS_MASK DesiredAccess,
+    _In_ POBJECT_ATTRIBUTES ObjectAttributes
+)
 {
     KPROCESSOR_MODE PreviousMode;
-    HANDLE hJob;
+    HANDLE Handle;
     NTSTATUS Status;
 
     PAGED_CODE();
 
     PreviousMode = ExGetPreviousMode();
 
-    /* check for valid buffers */
+    /* Check for valid buffers */
     if (PreviousMode != KernelMode)
     {
         _SEH2_TRY
@@ -471,17 +483,17 @@ NtOpenJobObject (
     }
 
     Status = ObOpenObjectByName(ObjectAttributes,
-        PsJobType,
-        PreviousMode,
-        NULL,
-        DesiredAccess,
-        NULL,
-        &hJob);
-    if(NT_SUCCESS(Status))
+                                PsJobType,
+                                PreviousMode,
+                                NULL,
+                                DesiredAccess,
+                                NULL,
+                                &Handle);
+    if (NT_SUCCESS(Status))
     {
         _SEH2_TRY
         {
-            *JobHandle = hJob;
+            *JobHandle = Handle;
         }
         _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
         {
@@ -493,7 +505,6 @@ NtOpenJobObject (
     return Status;
 }
 
-
 /*
  * @implemented
  */