-
Notifications
You must be signed in to change notification settings - Fork 3
/
listing6.html
executable file
·321 lines (265 loc) · 13.6 KB
/
listing6.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<!-- BEGIN META TAG INFO -->
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link rel="home" href="http://developer.apple.com/">
<link rel="find" href="http://developer.apple.com/search/">
<link rel="stylesheet" type="text/css" href="../../documentation/css/adcstyle.css" title="fonts">
<script language="JavaScript" src="../../documentation/js/adc.js" type="text/javascript"></script>
<!-- END META TAG INFO -->
<!-- BEGIN TITLE -->
<title>BetterAuthorizationSample - /Read Me About BetterAuthorizationSample.txt</title>
<!-- END TITLE -->
<script language="JavaScript">
function JumpToNewPage() {
window.location=document.scpopupmenu.gotop.value;
return true;
}
</script>
</head>
<!-- BEGIN BODY OPEN -->
<body>
<!--END BODY OPEN -->
<!-- START CENTER OPEN -->
<center>
<!-- END CENTER OPEN -->
<!-- BEGIN LOGO AND SEARCH -->
<!--#include virtual="/includes/adcnavbar"-->
<!-- END LOGO AND SEARCH -->
<!-- START BREADCRUMB -->
<div id="breadcrumb">
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr>
<td scope="row"><img width="340" height="10" src="images/1dot.gif" alt=""></td>
<td><img width="340" height="10" src="images/1dot.gif" alt=""></td>
</tr>
<tr valign="middle">
<td align="left" colspan="2">
<a href="http://developer.apple.com/">ADC Home</a> > <a href="../../referencelibrary/index.html">Reference Library</a> > <a href="../../samplecode/index.html">Sample Code</a> > <a href="../../samplecode/Security/index.html">Security</a> > <a href="../../samplecode/Security/idxAuthorization-date.html">Authorization</a> > <A HREF="javascript:location.replace('index.html');">BetterAuthorizationSample</A> >
</td>
</tr>
<tr>
<td colspan="2" scope="row"><img width="680" height="35" src="images/1dot.gif" alt=""></td>
</tr>
</table>
</div>
<!-- END BREADCRUMB -->
<!-- START MAIN CONTENT -->
<!-- START TITLE GRAPHIC AND INTRO-->
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr align="left" valign="top">
<td><h1><div id="pagehead">BetterAuthorizationSample</div></h1></td>
</tr>
</table>
<!-- END TITLE GRAPHIC AND INTRO -->
<!-- START WIDE COLUMN -->
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr align="left" valign="top">
<td id="scdetails">
<h2>/Read Me About BetterAuthorizationSample.txt</h2>
<form name="scpopupmenu" onSubmit="return false;" method=post>
<p><strong>View Source Code:</strong>
<select name="gotop" onChange="JumpToNewPage();" style="width:340px"><option selected value="ingnore">Select File</option>
<option value="listing1.html">/BetterAuthorizationSampleLib.c</option>
<option value="listing2.html">/BetterAuthorizationSampleLib.h</option>
<option value="listing3.html">/BetterAuthorizationSampleLibInstallTool.c</option>
<option value="listing4.html">/Design and Implementation Rationale.txt</option>
<option value="listing5.html">/Performing Privileged Operations With BetterAuthorizationSampleLib.txt</option>
<option value="listing6.html">/Read Me About BetterAuthorizationSample.txt</option>
<option value="listing7.html">/SampleApp.m</option>
<option value="listing8.html">/SampleCommon.c</option>
<option value="listing9.html">/SampleCommon.h</option>
<option value="listing10.html">/SampleTool.c</option></select>
</p>
</form>
<p><strong><a href="BetterAuthorizationSample.zip">Download Sample</a></strong> (“BetterAuthorizationSample.zip”, 237.1K)<BR>
<strong><a href="BetterAuthorizationSample.dmg">Download Sample</a></strong> (“BetterAuthorizationSample.dmg”, 319.3K)</p>
<!--
<p><strong><a href="#">Download Sample</a></strong> (“filename.sit”, 500K)</p>
-->
</td>
</tr>
<tr>
<td scope="row"><img width="680" height="10" src="images/1dot.gif" alt=""><br>
<img height="1" width="680" src="images/1dot_919699.gif" alt=""><br>
<img width="680" height="20" src="images/1dot.gif" alt=""></td>
</tr>
<tr>
<td scope="row">
<!--googleon: index -->
<pre class="sourcecodebox">Read Me About BetterAuthorizationSample
=======================================
1.0
BetterAuthorizationSample shows how to factor privileged operations out of your
application and into a privileged helper tool that is run by launchd. When your
application must do privileged operations, Apple recommends that you use this
approach because it improves security by:
o ensuring that your privileged code inherits a trusted environment
o reducing the amount of code that runs with elevated privileges
o making your privileged code easier to audit for security
The core of BetterAuthorizationSample is a reusable library that you can drop
into your own application. This reusable code takes care of the niggling
details of the problem, leaving you to concentrate on the code that's specific
to your application.
BetterAuthorizationSample has a number of advantages over previous samples in
this space.
o It is more secure because it doesn't use a setuid root helper tool. Setuid
root tools are inherently vulnerable to a certain class of attacks because they
inherit their environment from a non-trusted source.
BetterAuthorizationSample's helper tools inherit their environment from a
trusted source (launchd) and are not vulnerable to that class of attacks.
o It has better integration with Authorization Services.
BetterAuthorizationSample makes it easy to associate a custom authorization
right with your privileged operations; the reusable code will automatically
enforce that right.
You should only use BetterAuthorizationSample if your application needs ongoing
access to privileged operations. For example, if you're writing a packet
capture tool (where the underlying technology, BPF, is only available to
privileged processes) and you want to make it available to users in a controlled
and configurable fashion (determined by an authorization right),
BetterAuthorizationSample is for you. On the other hand, if your application
needs elevated privileges for a one-off task (like installing or uninstalling),
you should consider using AuthorizationExecuteWithPrivileges directly.
BetterAuthorizationSample requires Mac OS X 10.4.6 or later. The reason for
this specific requirement is that the system must support the "SockPathMode" key
in the <x-man-page://5/launchd.plist> file. This is supported on all versions
of Mac OS X for Intel-based Macintosh computers, but it wasn't supported on
PowerPC until 10.4.6.
Packing List
------------
The sample contains the following items:
o Read Me About BetterAuthorizationSample.txt -- This file.
o Performing Privileged Operations With BetterAuthorizationSampleLib.txt -- A
document describing how to adapt BetterAuthorizationSampleLib to perform
privileged operations in your own programs.
o Design and Implementation Rationale.txt -- A document describing the design
decisions and implementation details.
o BetterAuthorizationSample.xcodeproj -- An Xcode 2.4.1 project for the
program.
o build -- A pre-built version of the above.
o BetterAuthorizationSampleLib.h -- The interface to the reusable code.
o BetterAuthorizationSampleLib.c -- The implementation of the reusable code.
o BetterAuthorizationSampleLibInstallTool.c -- Reusable code for the
installation tool.
o SampleApp.m -- Source code for the sample application.
o SampleTool.c -- Source code for the sample helper tool.
o SampleCommon.h -- Declarations shared by the application and tool.
o SampleCommon.c -- Definitions shared by the application and tool.
o Info.plist -- The Info.plist file for the sample application.
o SampleApp.nib -- The UI for the sample application.
o en.lproj -- Localized resources for the sample application. While the sample
is not, in general, localized, one file, "SampleAuthorizationPrompts.strings",
is localized to illustrate a key point about custom authorization rights.
o SampleUninstall.sh -- A shell script to uninstall the sample helper tool.
This is helpful during development, because it allows you to reset your system
to a known state.
Using the Sample
----------------
To test the sample, just launch the pre-built binary. You'll see a window with
three buttons.
o GetVersion -- Click this to get the version number of the currently installed
helper tool (which should be 17, for no good reason other than it's easy to see
if things have gone wrong).
Unlike the other two buttons, this button requires that the tool be installed
already. If you click this button first, the operation will fail with error
100002 (the OSStatus equivalent of the POSIX error ENOENT). To fix this, install
the tool by clicking one of the other buttons.
There is no authorization right for this operation. All users can do it all
the time.
o GetUIDs -- Click this to ask the privileged helper tool to return its real
and effective user IDs. These should both be zero. If the privileged helper
tool is not installed, it will ask you whether you want to install it.
The authorization right for this operation defaults to allow anyone to do it.
However, a system admin can change this default by editing the right
specification for "com.example.BetterAuthorizationSample.GetUIDs" in the policy
database (currently "/etc/authorization").
o LowNumberedPorts -- Click this to ask the privileged helper tool to open
certain low numbered TCP ports (130, 131, and 132) and return descriptors for
them to the application.
The authorization right for this operation requires that the user hold (or be
able to enter) administrator credentials (typically an admin user name and
password). Again, a system admin can change this default by editing the right
specification for "com.example.BetterAuthorizationSample.LowNumberPorts" in the
policy database (currently "/etc/authorization").
Checking the "Force failure" checkbox modifies the behavior of these buttons as
described in "Force Failure", below.
Building the Sample
-------------------
The sample was built using Xcode 2.4.1 on Mac OS X 10.4.10. You should be able
to just open the project and choose Build from the Build menu. This will build
the "App" target, which builds the tool courtesy of a target dependency on the
"Tool" target. The final application will end up in the "build" directory, as
per normal, with a copy of the tool embedded within its package.
The project includes a "Debug64" build configuration, used to build a 64-bit
version of the code for testing purposes. This target only builds with Xcode
3.0, and the resulting binary is for Mac OS X 10.5 and later. Also, Mac OS X
10.5.x currently has a bug that causes the 64-bit privileged helper tool to
fail. Specifically, launch_data_get_fd does not work for 64-bit processes
<rdar://problem/5410487>.
Using BetterAuthorizationSampleLib In Your Program
--------------------------------------------------
For information about how to use the reusable portions of
BetterAuthorizationSample in your own program, read the document "Performing
Privileged Operations With BetterAuthorizationSampleLib.txt".
How it Works
------------
For information about the design and implementation of
BetterAuthorizationSample, read the document "Design and Implementation
Rationale.txt".
Force Failure
-------------
The "Force failure" checkbox in the sample application allows you to test some
likely error scenarios.
o If "Force failure" is checked and you click "GetVersion", the application
will pass an illegal command string to the reusable code. This let you validate
the mechanism that rejects illegal commands.
o If "Force failure" is checked and you click "LowNumberedPorts", the operation
will fail as if one of the ports was in use. This let you test the error path,
making sure that everything gets cleaned up along the way.
Credits and Version History
---------------------------
If you find any problems with this sample, mail <[email protected]> and we'll try
to fix them up.
1.0 (Nov 2007) was the first shipping version.
Share and Enjoy
Apple Developer Technical Support
Core OS/Hardware
12 Nov 2007
</pre>
<!--googleoff: index -->
</td>
</tr>
</table>
<!-- END WIDE COLUMN -->
<!-- END MAIN CONTENT -->
<table width="680" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><div style="width: 100%; height: 1px; background-color: #919699; margin-top: 5px; margin-bottom: 15px"></div></td>
</tr>
<tr>
<td align="center"><br/>
<table border="0" cellpadding="0" cellspacing="0" class="graybox">
<tr>
<th>Did this document help you?</th>
</tr>
<tr>
<td>
<div style="margin-bottom: 8px"><a href="http://developer.apple.com/feedback/?v=1&url=/samplecode/BetterAuthorizationSample/listing6.html%3Fid%3DDTS10004207-1.0&media=dvd" target=_new>Yes</a>: Tell us what works for you.</div>
<div style="margin-bottom: 8px"><a href="http://developer.apple.com/feedback/?v=2&url=/samplecode/BetterAuthorizationSample/listing6.html%3Fid%3DDTS10004207-1.0&media=dvd" target=_new>It’s good, but:</a> Report typos, inaccuracies, and so forth.</div>
<div><a href="http://developer.apple.com/feedback/?v=3&url=/samplecode/BetterAuthorizationSample/listing6.html%3Fid%3DDTS10004207-1.0&media=dvd" target=_new>It wasn’t helpful</a>: Tell us what would have helped.</div>
</td>
</tr>
</table>
</td>
</tr>
</table>
<!-- START BOTTOM APPLE NAVIGATION -->
<!--#include virtual="/includes/footer"-->
<!-- END BOTTOM APPLE NAVIGATION -->
<!-- START CENTER CLOSE -->
</center>
<!-- END CENTER CLOSE -->
</body>
</html>