Skip to content

Commit 3a2ec1c

Browse files
VoidSecVoidSec
committed
added documentation
1 parent fd00b5a commit 3a2ec1c

File tree

5 files changed

+78
-70
lines changed

5 files changed

+78
-70
lines changed

‎ioctlpus/AboutForm.cs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,14 @@ public AboutForm()
99
{
1010
InitializeComponent();
1111
InitializeOSC();
12+
// load about text and assembly version, instead of having it hardcoded
1213
string version = Application.ProductVersion;
13-
lblAbout.Text = "ioctlpus "+version+"\nCreated in 2017 by Jackson Thuraisamy(@Jackson_T)\nUpdated and mantained by Paolo Stagno(@Void_Sec)\n\nDedicated to my partner and family for putting up with me.";
14+
lblAbout.Text = "ioctlpus " + version + "\nCreated in 2017 by Jackson Thuraisamy(@Jackson_T)\nUpdated and mantained by Paolo Stagno(@Void_Sec)\n\nDedicated to my partner and family for putting up with me.";
1415
}
1516

1617
private void InitializeOSC()
1718
{
19+
// populate list of open source components
1820
List<OpenSourceComponent> components = new List<OpenSourceComponent>();
1921

2022
components.Add(new OpenSourceComponent("HexBox", "Bernhard Elbl", "MIT"));

‎ioctlpus/MainForm.cs

Lines changed: 39 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
using BrightIdeasSoftware;
33
using Microsoft.Win32.SafeHandles;
44
using System;
5-
using System.Diagnostics;
65
using System.Collections.Generic;
6+
using System.Diagnostics;
77
using System.Drawing;
88
using System.IO;
99
using System.Runtime.InteropServices;
@@ -22,28 +22,24 @@ public MainForm()
2222
{
2323
InitializeComponent();
2424

25-
// Add placeholder text to filters textbox.
25+
// Add placeholder text to filters textbox
2626
SendMessage(tbFilters.Handle, EM_SETCUEBANNER, 0, "Filters (e.g. 9C412000 br=64 !ec=C000000D)");
2727

28-
// Setup HexBoxes.
28+
// Setup HexBoxes
2929
InitializeHexBox(hbInput, (int)nudInputSize.Value);
3030
InitializeHexBox(hbOutput, (int)nudOutputSize.Value);
3131

32-
// Setup TreeListView.
32+
// Setup TreeListView
3333
InitializeTreeListView();
3434

35-
// Setup initial parameters.
35+
// Setup initial parameters
3636
tbDevicePath.Text = @"\\.\PhysicalDrive0";
3737
tbIOCTL.Text = "70000";
3838
tbAccessMask.Text = "20000000";
3939
cmbACL.SelectedItem = "ANY_ACCESS";
4040
}
4141

42-
/// <summary>
43-
/// Initialize the given buffer view.
44-
/// </summary>
45-
/// <param name="hexBox"></param>
46-
/// <param name="size"></param>
42+
// Initialize the given buffer view
4743
private void InitializeHexBox(HexBox hexBox, int size)
4844
{
4945
hexBox.Visible = true;
@@ -60,37 +56,35 @@ private void InitializeHexBox(HexBox hexBox, int size)
6056
hexBox.ByteProvider = new DynamicByteProvider(new byte[size]);
6157
}
6258

63-
/// <summary>
64-
/// Initialize the Request History views.
65-
/// </summary>
59+
// Initialize the Request History views
6660
private void InitializeTreeListView()
6761
{
68-
// Add colours to request rows.
62+
// Add colours to request rows
6963
tlvRequestHistory.FormatRow += (sender, eventArgs) =>
7064
{
7165
Request transmission = (Request)eventArgs.Model;
7266
if (transmission.IsFavourite)
73-
eventArgs.Item.BackColor = System.Drawing.Color.LightYellow;
67+
eventArgs.Item.BackColor = Color.LightYellow;
7468
else if (transmission.ReturnValue > 0)
75-
eventArgs.Item.BackColor = System.Drawing.Color.MistyRose;
69+
eventArgs.Item.BackColor = Color.MistyRose;
7670
};
7771

78-
// Rename requests when double-clicked or F2 is pressed.
72+
// Rename requests when double-clicked or F2 is pressed
7973
tlvRequestHistory.CellEditActivation = BrightIdeasSoftware.ObjectListView.CellEditActivateMode.DoubleClick;
8074

81-
// How to identify if a row has children.
75+
// How to identify if a row has children
8276
tlvRequestHistory.CanExpandGetter = delegate (Object tx)
8377
{
8478
return ((Request)tx).Children.Count > 0;
8579
};
8680

87-
// Where row children are located.
81+
// Where row children are located
8882
tlvRequestHistory.ChildrenGetter = delegate (Object tx)
8983
{
9084
return ((Request)tx).Children;
9185
};
9286

93-
// Populate HexBoxes when the selection changes.
87+
// Populate HexBoxes when the selection changes
9488
tlvRequestHistory.SelectionChanged += (sender, eventArgs) =>
9589
{
9690
if (tlvRequestHistory.SelectedIndex == -1) return;
@@ -110,11 +104,7 @@ private void InitializeTreeListView()
110104
};
111105
}
112106

113-
/// <summary>
114-
/// Validate provided device path.
115-
/// </summary>
116-
/// <param name="sender"></param>
117-
/// <param name="e"></param>
107+
// Validate provided DeviceName
118108
private void tbDevicePath_TextChanged(object sender, EventArgs e)
119109
{
120110
Guid guid;
@@ -142,11 +132,7 @@ private void tbDevicePath_TextChanged(object sender, EventArgs e)
142132
tbDevicePath.BackColor = Color.MistyRose;
143133
}
144134

145-
/// <summary>
146-
/// Validate that provided IOCTL is legitimate.
147-
/// </summary>
148-
/// <param name="sender"></param>
149-
/// <param name="e"></param>
135+
// Validate that provided IOCTL is legitimate
150136
private void tbIOCTL_TextChanged(object sender, EventArgs e)
151137
{
152138
Point toolTipCoords = tbIOCTL.Location;
@@ -169,12 +155,15 @@ private void tbIOCTL_TextChanged(object sender, EventArgs e)
169155

170156
private void btnSend_Click(object sender, EventArgs e)
171157
{
172-
uint fa_mask=Convert.ToUInt32("20000000", 16);
173-
if (tbAccessMask.Enabled == true) {
158+
uint fa_mask = Convert.ToUInt32("20000000", 16);
159+
// if Access mask is enabled use that value
160+
if (tbAccessMask.Enabled == true)
161+
{
174162
fa_mask = Convert.ToUInt32(tbAccessMask.Text, 16);
175163
}
176164
else
177165
{
166+
// otherwise gather the human readable ACL
178167
switch (cmbACL.SelectedItem)
179168
{
180169
case "ANY_ACCESS":
@@ -189,13 +178,14 @@ private void btnSend_Click(object sender, EventArgs e)
189178
case "WRITE_DATA":
190179
fa_mask = Convert.ToUInt32(FileAccess.Write);
191180
break;
192-
default:
181+
default:
193182
fa_mask = 0;
194183
break;
195184

196185
}
197186
}
198-
Debug.WriteLine("\nAccess Mask: "+fa_mask);
187+
Debug.WriteLine("\nAccess Mask: " + fa_mask);
188+
199189
SafeFileHandle sfh = CreateFile(
200190
tbDevicePath.Text.Trim(),
201191
dwDesiredAccess: (FileAccess)fa_mask,
@@ -217,10 +207,12 @@ private void btnSend_Click(object sender, EventArgs e)
217207

218208
if (sfh.IsInvalid)
219209
{
210+
// invalid DeviceName
220211
errorCode = Marshal.GetLastWin32Error();
221212
}
222213
else
223214
{
215+
// create buffer with specified content in memory
224216
long hbInputLength = ((DynamicByteProvider)hbInput.ByteProvider).Length;
225217
MemSet(Marshal.UnsafeAddrOfPinnedArrayElement(inputBuffer, 0), 0, (int)hbInputLength);
226218

@@ -232,18 +224,19 @@ private void btnSend_Click(object sender, EventArgs e)
232224

233225
long hbOutputLength = ((DynamicByteProvider)hbOutput.ByteProvider).Length;
234226
MemSet(Marshal.UnsafeAddrOfPinnedArrayElement(outputBuffer, 0), 0, (int)hbOutputLength);
227+
// execute DeviceIoControl request
235228
DeviceIoControl(sfh, ioctl, inputBuffer, inputSize, outputBuffer, outputSize, ref returnedBytes, IntPtr.Zero);
236-
229+
// gather error code
237230
errorCode = Marshal.GetLastWin32Error();
238231
sfh.Close();
239-
232+
// update Input/Output views
240233
DynamicByteProvider requestData = new DynamicByteProvider(inputBuffer);
241234
hbInput.ByteProvider = requestData;
242235

243236
DynamicByteProvider responseData = new DynamicByteProvider(outputBuffer);
244237
hbOutput.ByteProvider = responseData;
245238
}
246-
239+
// update request view
247240
Request newTx = new Request();
248241
newTx.RequestName = String.Format(
249242
"0x{0:X} ({1:X4}-{2:D5})",
@@ -283,11 +276,7 @@ private void btnSend_Click(object sender, EventArgs e)
283276
return;
284277
}
285278

286-
/// <summary>
287-
/// Mark the selected request as a favourite.
288-
/// </summary>
289-
/// <param name="sender"></param>
290-
/// <param name="e"></param>
279+
// Mark the selected request as a favourite
291280
private void btnStarRequest_Click(object sender, EventArgs e)
292281
{
293282
if (tlvRequestHistory.SelectedIndex == -1) return;
@@ -300,11 +289,7 @@ private void btnOpenDB_Click(object sender, EventArgs e)
300289
// ToDo
301290
}
302291

303-
/// <summary>
304-
/// Filters results in the Request History view (TODO).
305-
/// </summary>
306-
/// <param name="sender"></param>
307-
/// <param name="e"></param>
292+
// Filters results in the Request History view (TODO)
308293
private void tbFilters_TextChanged(object sender, EventArgs e)
309294
{
310295
tlvRequestHistory.ModelFilter = null;
@@ -314,11 +299,7 @@ private void tbFilters_TextChanged(object sender, EventArgs e)
314299
});
315300
}
316301

317-
/// <summary>
318-
/// Shows the About window.
319-
/// </summary>
320-
/// <param name="sender"></param>
321-
/// <param name="e"></param>
302+
// Shows the About window
322303
private void btnAbout_Click(object sender, EventArgs e)
323304
{
324305
if (Application.OpenForms["AboutForm"] as AboutForm == null)
@@ -333,6 +314,7 @@ private void btnAbout_Click(object sender, EventArgs e)
333314
}
334315
}
335316

317+
// parse and validate Access Mask
336318
private void tbAccessMask_TextChanged(object sender, EventArgs e)
337319
{
338320
Point toolTipCoords = tbAccessMask.Location;
@@ -354,12 +336,14 @@ private void tbAccessMask_TextChanged(object sender, EventArgs e)
354336

355337
}
356338

339+
// update input panel when the InputSize is changed
357340
private void nudInputSize_ValueChanged(object sender, EventArgs e)
358341
{
359342
DynamicByteProvider dbpData = new DynamicByteProvider(new byte[(int)nudInputSize.Value]);
360343
hbInput.ByteProvider = dbpData;
361344
}
362345

346+
// update output panel when the OutputSize is changed
363347
private void nudOutputSize_ValueChanged(object sender, EventArgs e)
364348
{
365349
DynamicByteProvider dbpData = new DynamicByteProvider(new byte[(int)nudOutputSize.Value]);
@@ -372,6 +356,7 @@ private void hbInput_ByteProviderChanged(object sender, EventArgs e)
372356
//nudInputSize.Value = (int)dbpData;
373357
}
374358

359+
// show the settings form
375360
private void btnSettings_Click(object sender, EventArgs e)
376361
{
377362
if (Application.OpenForms["SettingsForm"] as SettingsForm == null)
@@ -386,6 +371,7 @@ private void btnSettings_Click(object sender, EventArgs e)
386371
}
387372
}
388373

374+
// enable/disable access mask
389375
private void chkEnableAccessMask_CheckedChanged(object sender, EventArgs e)
390376
{
391377
if (chkEnableAccessMask.Checked == true)
@@ -398,7 +384,7 @@ private void chkEnableAccessMask_CheckedChanged(object sender, EventArgs e)
398384
tbAccessMask.Enabled = false;
399385
cmbACL.Enabled = true;
400386
}
401-
387+
402388
}
403389
}
404390
}

‎ioctlpus/Program.cs

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ static class Program
1414
{
1515
public static byte[] StringToByteArray(string hex)
1616
{
17+
// Convert a string to a byte array
1718
if (hex.Length % 2 == 1)
1819
{
1920
throw new Exception("The binary string cannot have an odd number of digits");
@@ -27,13 +28,14 @@ public static byte[] StringToByteArray(string hex)
2728

2829
public static string ByteArrayToString(byte[] ba)
2930
{
31+
// Convert a byte array to a string
3032
string hex = "0x" + BitConverter.ToString(ba).Replace("-", " 0x");
3133
return hex;
3234
}
3335

34-
// args options
3536
class Options
3637
{
38+
// args options
3739
[Option("cli", HelpText = "Run IOCTLpus in CLI mode.")]
3840
public bool Cli { get; set; }
3941

@@ -60,9 +62,7 @@ class Options
6062

6163
}
6264

63-
/// <summary>
64-
/// The main entry point for the application.
65-
/// </summary>
65+
// The main entry point for the application.
6666
[STAThread]
6767
static void Main(string[] args)
6868
{
@@ -73,7 +73,7 @@ static void Main(string[] args)
7373
if (opts.Cli)
7474
{
7575
Console.WriteLine("IOCTLpus CLI Mode\n--------------------\n");
76-
// hanlde some required parameters
76+
// hanlde some required arguments
7777
if (opts.Guid == null)
7878
{
7979
Console.WriteLine("Required option 'guid' is missing.");
@@ -89,7 +89,7 @@ static void Main(string[] args)
8989
Console.WriteLine("Required option 'input' is missing.");
9090
return;
9191
}
92-
// if we gathered every parameter we can proceed and perform the IOCTL request printing out the result
92+
// if we gathered every required arguments we can proceed and perform the IOCTL request printing out the result
9393
uint fa_mask = Convert.ToUInt32(opts.Access_mask, 16);
9494
SafeFileHandle sfh = CreateFile(
9595
opts.Guid.Trim(),
@@ -111,13 +111,14 @@ static void Main(string[] args)
111111

112112
if (sfh.IsInvalid)
113113
{
114+
// print out last occured error (e.g DeviceName not found)
114115
string errorMessage = new Win32Exception(Marshal.GetLastWin32Error()).Message;
115116
Console.WriteLine(errorMessage);
116117
return;
117118
}
118119
else
119120
{
120-
// grab the opts.Input_buffer transform it into a byte array
121+
// grab the opts.Input_buffer and transform it into a byte array
121122
byte[] hbInput = StringToByteArray(opts.Input_buffer);
122123
long hbInputLength = hbInput.Length;
123124
MemSet(Marshal.UnsafeAddrOfPinnedArrayElement(inputBuffer, 0), 0, (int)hbInputLength);
@@ -127,12 +128,13 @@ static void Main(string[] args)
127128
inputBuffer[i] = hbInput[i];
128129
}
129130
MemSet(Marshal.UnsafeAddrOfPinnedArrayElement(outputBuffer, 0), 0, (int)outputBuffer.Length);
131+
// send DeviceIoControl
130132
DeviceIoControl(sfh, ioctl, inputBuffer, inputSize, outputBuffer, outputSize, ref returnedBytes, IntPtr.Zero);
131-
133+
// gather last occured error (e.g Access Denied)
132134
errorCode = Marshal.GetLastWin32Error();
133135
string errorMessage = new Win32Exception(Marshal.GetLastWin32Error()).Message;
134136
sfh.Close();
135-
// print out returning values
137+
// print out DeviceIoControl returning values
136138
Console.WriteLine("GUID:\t\t" + opts.Guid);
137139
Console.WriteLine("IOCTL:\t\t0x{0:X}", ioctl);
138140
Console.WriteLine("Input Buffer:\t" + ByteArrayToString(inputBuffer));
@@ -141,9 +143,9 @@ static void Main(string[] args)
141143
Console.WriteLine("Error:\t\t0x{0:X} - " + errorMessage, errorCode);
142144
}
143145
}
144-
// run IOCTLpus in GUI mode
145146
else
146147
{
148+
// run IOCTLpus in GUI mode
147149
Application.EnableVisualStyles();
148150
Application.SetCompatibleTextRenderingDefault(false);
149151
try

0 commit comments

Comments
 (0)