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
|
/*
* Copyright (C) 2012 Apple Inc. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/*!
* @header WebKit Mac Sandbox
*
* This header provides an *EXPERIMENTAL* API for NPAPI plug-ins that wish
* to reduce their runtime privileges. When entering the sandbox, adopting
* plug-ins specify a whitelist of files they wish to have available for
* reading and writing. Plug-ins that need to have access to arbitrary files,
* such as to enable user-initiated file uploads or downloads, can invoke
* native Cocoa APIs, which will automatically grant permissions to the plug-in.
*
*
* Security characteristics
*
* Sandboxed plug-in's local file access is restricted to the union of:
*
* 1. The file whitelist specified by the plug-in when entering the sandbox.
* 2. Any files obtained at runtime through the secure Open and Save dialogs.
* 3. Any files that were open before entering the sandbox.
*
* Implementation may additionally choose to restrict the creation of IPC
* channels or the use of other security-sensitive system resources, such as
* the ability to spawn additional processes. However, any such resources
* acquired before entry into the sandbox are guaranteed to remain available
* within it. For example, plug-ins are free to spawn a trusted broker process
* before entering the sandbox and to establish an IPC channel with it. The
* channel will remain available within the sandbox even if the implementation
* is highly restrictive and allows neither process creation nor IPC channel
* establishment.
*/
#ifndef npapi_sandbox_h
#define npapi_sandbox_h
#ifdef __cplusplus
extern "C" {
#endif
/*!
* @constant WKNVSandboxFunctions
* Use this constant with NPN_GetValue to get a pointer to WKNSandboxFunctions
* structure, which contains pointers to sandboxing functions.
*/
#define WKNVSandboxFunctions 74659
/*!
* Version of WKNSandboxFunctions structure that is returned by NPN_GetValue.
*/
#define WKNVSandboxFunctionsVersionCurrent 1
/*!
* @function WKN_EnterSandbox
* Requests that the plug-in instance be placed in a sandbox.
*
* @param readOnlyPaths
* NULL-terminated C array of paths to files and directories that the plug-in
* wishes to have available in the sandbox for read-only access. Any
* directories in this array will automatically extend the sandbox to encompass
* all their files and subdirectories, meaning that they will be available
* through OS level file access functions for reading.
*
* @param readWritePaths
* NULL-terminated C array of paths to files and directories that the plug-in
* wishes to have available in the sandbox for both reading and writing.
* Typically, this array will include paths to the plug-in's local caches, a
* directory for temporary files, and any configuration files which are not
* security sensitive, in that they are not consulted when determining the
* lists of paths to pass to this function during plug-in instantiation.
* Any directories in this array will automatically extend the sandbox to
* encompass all their files and subdirectories, meaning that they will be
* available through OS level file access functions for reading and writing.
*
* @result
* Places the plug-in instance in a sandbox. The sandbox allows read-only access
* to paths specified by `readOnlyPaths` and read-write access to
* `readWritePaths`. If the same path appears in both `readOnlyPaths` and
* `readWritePaths`, access to that path will be read-only. No other filesystem
* access is available except as expressly permitted by the user through
* NSOpenPanel and NSSavePanel invocations. Returns NPERR_NO_ERROR when the
* navigator has successfully placed the plug-in in a sandbox and
* NPERR_GENERIC_ERROR if the the plug-in instance was already placed in a sandbox
* with a prior call to this function. If entering sandbox fails for any other reason,
* the process is terminated.
* Note that either or both `readOnlyPaths` and `readWritePaths` may be NULL.
*
* @discussion
* This function should be called as early as possible during plug-in
* instantiation and ALWAYS before any untrusted code has run. Generally, the
* only things that the plug-in should do before entering the sandbox are to
* determine the paths to pass in as `readOnlyPaths` and `readWritePaths`, and
* to establish any IPC channels to be used from the sandbox. In cases where
* the plug-in must parse its configuration files to determine any needed local
* resources (such as files to preload), it should do so and then immediately
* call this function. If configuration files do not influence the paths that
* the plug-in will pass as part of `readOnlyPaths` and `readWritePaths`, the
* plug-in should enter the sandbox first and only then process configuration
* files and deal with normal startup tasks.
*
* Very close attention must be paid to weeding out security-sensitive files
* from the `readWritePaths` list. If the plug-in instance reads a configuration
* file at startup to determine which additional files it will place in the
* `readWritePaths` list to this call, then that configuration file MUST NOT be
* in the `readWritePaths` itself. Otherwise, should the plug-in become
* compromised, it can trivially escape its sandbox the next time it is
* instantiated by writing arbitrary paths (or just "/") into this writable
* configuration file.
*
* Note that after a plug-in instance enters the sandbox, any native calls that
* it makes which refer to arbitrary paths on disk will only work if the paths are
* available within the sandbox, either statically through `readOnlyPaths` and
* `readWritePaths`, or dynamically through Cocoa APIs.
* However, NPAPI calls (such as e.g. NPN_PostURL with the file parameter set to TRUE)
* can access files that navigator policies allow, which is usually an entirely
* different set for remote and for local Web pages.
*/
typedef NPError (*WKN_EnterSandboxProcPtr)(const char *readOnlyPaths[], const char *readWritePaths[]);
/*!
* @function WKN_FileStopAccessing
* Requests that the navigator revoke the plug-in's access to the given path.
*
* @param path
* Required. A path that was previously returned from NSOpenPanel or NSSavePanel.
*
* @result
* Returns NPERR_NO_ERROR, or NPERR_GENERIC_ERROR if the requesting plug-in
* instance is not in a sandbox.
*
* @discussion
* Whenever file access is provided to a plug-in instance through a
* Cocoa API, navigator should be notfied when it is no longer needed.
* This will cause subsequent open(2) calls on any of the revoked files to fail,
* but by design no attempt is made to invalidate existing file descriptors.
* plug-in writers are strongly encouraged to keep files open for as short a period
* of time as possible, and to always call this function when objects representing
* the returned files go out of scope or are otherwise destroyed.
*/
typedef NPError (*WKN_FileStopAccessingProcPtr)(const char* path);
typedef struct _WKNSandboxFunctions {
uint16_t size;
uint16_t version;
WKN_EnterSandboxProcPtr enterSandbox;
WKN_FileStopAccessingProcPtr fileStopAccessing;
} WKNSandboxFunctions;
#ifdef __cplusplus
}
#endif
#endif // npapi_sandbox_h
|
