Last commit for security.html: 3ab67036f46fcdfd26b03ca3a549e4104e478edc

Worklets Documentation

dp2041 [2002-10-28 07:14:48]
Worklets Documentation
  1. <title>Worklets Documentation: Security</title>
  2. </head>
  5. <font color='#000080' size=4 face='Verdana, Arial, Helvetica'>
  6. <h4>
  7. Worklets Documentation: Security
  8. </h4>
  9. </font>
  11. <font color='#000080' size=2 face='Verdana, Arial, Helvetica' >
  12. <h5 align="right">
  13. back to <a href=Worklets.html>Worklets documentation</a>
  14. </h5>
  16. <p>
  17. <h3>Description</h3>
  18. The Worklet security system provides methods for securing Worklet
  19. transmission. The vulnerable objects are the RMI (Remote Method
  20. Invocation) transport layer, the WVM (Worklet Virtual Machine)
  21. transport layer and the class loaders. Other objects that have or
  22. provide methods for security measures are HostnameVerifier and
  23. WorkletJunctions.
  24. </p>
  26. <p>
  27. The RMI Transport layer involves an RMI registry, associated RMI
  28. servers and class loaders. Only one registry can be created on a
  29. specific host:port to which many RMI servers can be bound. A secure
  30. registry authenticates all registry calls such as server lookups,
  31. binds, and unbinds. A secure RMI server uses custom secure sockets to
  32. authenticate and encrypt all communication. In the instance of a
  33. secure server, the default RMI class loader is set to our own
  34. implementation that uses a class loader with secure sockets. Both
  35. plain and secure RMI servers can be bound to plain registries but only
  36. secure RMI servers can be bound to secure registries. Communication
  37. between RMI servers can only proceed plain-plain or secure-secure.
  38. Depending on the security level (described in the Usage section) the
  39. RMI server could have either only plain, only secure, or both class
  40. loaders available to load classes.
  41. </p>
  43. <p>
  44. The WVM transport layer includes server sockets and class loaders.
  45. Depending on the level of security the transport layer can be created
  46. with plain, secure, or both types of server sockets and associated
  47. class loaders.
  48. </p>
  50. <p>
  51. A HostnameVerifier is also implemented and is used on the remote
  52. (receiving) end. This object is used by the remote host if the
  53. hostname of the sending WVM is not recognized from the CA certificate
  54. file. The specification of the hosts that are allowed and denied is
  55. described in the usage section.
  56. <p>
  58. </p>
  59. There are situations where the user of the WorkletJunctions could be
  60. uncertain of the security specifications at a certain WVM. The user
  61. can now specify parameters that allow the users to specify which
  62. methods of transport (plain RMI, secure RMI, plain socket, secure
  63. socket) the WorkletJunction should try and in what order. The RMI
  64. related methods specify what type of communication to try when looking
  65. up the recipient RMI server, not the actual RMI server. The socket
  66. related features specify the type of socket to try connecting on. The
  67. ability to specify transport methods contributes to the robustness of
  68. WorkletJunction communication.
  69. </p>
  71. <p>
  72. <h3>Usage</h3>
  73. Note that all previous functionality is retained. This section
  74. documents the features pertinent to Worklet Security. I make a
  75. delineation between the <a href="#remote_host">remote</a> and <a
  76. href="#local_host">local</a> hosts. The remote host represents the
  77. intended recipient of the Worklet while the local host is the entity
  78. that is sending the Worklet.
  79. </p>
  81. <p>
  82. <h4><a name="remote_host">Remote Host</a></h4>
  83. To create a plain host you need not specify any parameters, like
  84. this:
  85. </p>
  87. <font size=2 face='Terminal, Arial'>
  88. java psl.worklets.WVM<br>
  89. </font>
  91. <p>
  92. The name and port of the RMI server will default to WVM_Host and
  93. 9100. If a remote host is created in this manner communication will
  94. not be authenticated nor encrypted. You can specify the RMI server
  95. name and port by using the switches -name and -port. See java
  96. psl.worklets.WVM -help for option details.
  97. </p>
  99. <p>
  100. To create secure hosts you must specify at least the keys file,
  101. password, and WVM properties file (WVM file). Because the WVM file
  102. must contain the keysfile and password it is usually sufficient to
  103. simply specify the WVM file. The keys file is the file containing the
  104. public/private keys of the host and the password is the passphrase
  105. specified in the creation of the keysfile. For more information on
  106. how to create a keysfile see the <a href=#FAQ>FAQ</a> below. The WVM file holds the
  107. security specifications. These security specifications can be
  108. specified by setting environment variables with the -D java switch or
  109. non the command line. The parameter loading precedence is:<br>
  110. <ul>
  111. <li>Environment variables</li>
  112. <li>WVM file</li>
  113. <li>command line specification</li>
  114. </ul>
  115. </p>
  117. <p>
  118. The WVM file contains property=value pairs separated by white space.
  119. The important parameters in the WVM file are the keysfile and
  120. password as these are used by the Worklet system at different times.
  121. It is <u>very</u> important that the security of this file is set at
  122. the operating systems level, meaning that the permissions on this file
  123. should be set accordingly. For example, for maximum security I would
  124. set the permission to user read-only. This can be done under Unix
  125. with the following:
  126. </p>
  128. <font size=2 face='Terminal, Arial'>
  129. chmod a-rwx wvm_properties<br>
  130. chmod u+r wvm_properties<br>
  131. </font>
  133. <p>
  134. Included with the distribution should be an example WVM file named
  135. ``wvm_properties''. It should look like this:
  136. </p>
  138. <font size=2 face='Terminal, Arial'>
  139. # WVM host related parameters<br>
  140. WVM_RMI_PORT=9100 # port that the rmi registry will be created on<br>
  141. WVM_RMI_NAME=target # name that the RMI server will be bound to<br>
  142. <br>
  143. # Security related parameters <br>
  144. WVM_KEYSFILE=testkeys # file holding the public/private keys<br>
  145. WVM_PASSWORD=passphrase # password into the keysfile. <br>
  146. WVM_SSLCONTEXT=TLS # SSL context instance to use<br>
  147. WVM_KEYMANAGER=SunX509 # key manager implementation type<br>
  148. WVM_KEYSTORE=JKS # key store implementation type<br>
  149. WVM_RNG=SHA1PRNG # random number generator algorithm to use<br>
  150. # location of the certified security certificates.<br>
  151. WVM_HOSTS_ALLOW=localhost, # allowed hosts<br>
  152. WVM_HOSTS_DENY= # denied hosts<br>
  153. WVM_FILE=wvm_properties # reference to this file<br>
  154. <br>
  155. # security level of the WVM. <br>
  156. # 0: no security. <br>
  157. # 1: low security = plain RMI Registry, secure RMI server, <br>
  158. # plain and secure server sockets, and <br>
  159. # plain and secure class loaders.<br>
  160. # 2: medium security = same as 1 but with a secure RMI Registry<br>
  161. # 3: high security = secure RMI Registry, secure RMI server, <br>
  162. # secure server socket and secure class loaders.<br>
  163. WVM_SECURITY_LEVEL=1 <br>
  164. </font>
  166. <p>
  167. Notice the last parameter of WVM_SECURITY_LEVEL. This parameter is
  168. what you would modify to tailor the security level according to the
  169. needs at a certain WVM. A security level of 1 is the most flexible as
  170. it creates a registry that will allow binding by both plain and secure
  171. RMI servers. Also created with a security level of 1 are plain and
  172. secure server sockets and class loaders. The only difference between
  173. security level 1 and 2 is that the registry is secure in the latter.
  174. A security level of 3 creates a WVM host that has a secure RMI server
  175. that must be bound to a secure registry, a secure server socket, and only
  176. secure class loaders. There is a plain server socket created, but
  177. that is used only for internal purposes for robust registry upkeep.
  178. </p>
  180. <p>
  181. The WVM_HOSTS_ALLOW and WVM_HOSTS_DENY specify which hosts on the
  182. remote end are allowed and denied. If no hosts are specified in both
  183. settings, then all hosts will be allowed. These entries are the only
  184. parameters that are concatenated, meaning that if you specify these
  185. parameters in the system environment, the WVM file, and on the command
  186. line then all entries will be used.
  187. </p>
  189. <h4><a name="Examples">Examples</a></h4>
  191. <p>
  192. Create a plain host with the RMI name target on port 9100.<br>
  193. <font size=2 face='Terminal, Arial'>
  194. java psl.worklets.WVM -name target
  195. </font>
  196. </p>
  198. <p>
  199. Create a host according to the parameters in the WVM file.<br>
  200. <font size=2 face='Terminal, Arial'>
  201. java psl.worklets.WVM -wvmfile wvm_properties<br>
  202. </font>
  203. </p>
  205. <p>
  206. Create a host according to the parameters in the WVM file, but with
  207. the RMI name target and a security level of 2.<br>
  208. <font size=2 face='Terminal, Arial'>
  209. java -DWVM_FILE=wvm_properties psl.worklets.WVM -name target -S 2<br>
  210. </font>
  211. </p>
  213. <p>
  214. <h4><a name="local_host">Local Host</a></h4>
  215. The sending of secure Worklets involves the creation of a local WVM
  216. host that bootstraps the Worklet into the WVM system. Creation of
  217. secure Worklets and WorkletJunctions is the same as described in the
  218. Worklet documentation except that you need to set the WVM_FILE system
  219. property to your WVM file (described above). This can either be done
  220. with the -D java switch or within the application with the
  221. System.setProperty method. Included in the distribution should be an
  222. example program ``''.
  223. </p>
  225. <p>
  226. Here is the portion within the example program that sets the security
  227. parameters. Also shown is the creation of the WVM.
  228. </p>
  230. <p>
  231. <font size=2 face='Terminal, Arial'>
  232. psl.worklets.OptionsParser op = new psl.worklets.OptionsParser();<br>
  233. op.loadWVMFile(System.getProperty("WVM_FILE"));<br>
  234. op.setWVMProperties();<br>
  236. wvm = new psl.worklets.WVM(new Object(), InetAddress.getLocalHost().getHostAddress(), <br>
  237. "SendSecure", op.port, op.keysfile, op.password,<br>
  238. op.ctx, op.kmf, op.ks, op.rng, op.securityLevel);<br>
  239. </font>
  240. </p>
  242. <p>
  243. The WVM_FILE system property was set on the command line like this:<br>
  244. <font size=2 face='Terminal, Arial'>
  245. java -DWVM_FILE=wvm_properties SendSecure localhost target 9101 Apps.Face 1 0 mysend<br>
  246. </font>
  247. </p>
  249. <p>
  250. You can also manage the WorkletJunction transport methods by setting
  251. the transportMethods to a combination of plainRMI, secureRMI,
  252. plainSocket, and secureSocket. The plainRMI and secureRMI keywords
  253. specify the type of registry used by that server. The type of server
  254. cannot be specified because the parameters for which type of socket to
  255. use is set at creation time. The plainSocket and secureSocket
  256. keywords specify which type of socket to communicate with. The
  257. security will always default to the ``parent'' if not set. So if the
  258. Worklet.isSecure and the WorkletJunction.isSecure have not been
  259. specified, then the WorkletJunction will default to the security of
  260. the current WVM system. The default for plain systems is plainRMI and
  261. plainSocket and the default for secure systems is secureRMI and
  262. secureSocket. If WorkletJunction.isSecure is set and the
  263. WorkletJunction.isSecure has not been set then those WorkletJunctions
  264. will default to the security level of the Worklet. The last, and
  265. highest priority level is at the WorkletJunction. You can either use
  266. the isSecure method or specify the methods through the
  267. transportMethods function. Using the transportMethods function alone
  268. is sufficient, and will override the isSecure method. Here's an
  269. example of how to set the methods:
  270. </p>
  272. <p>
  273. <font size=2 face='Terminal, Arial'>
  274. String[] tm = {"secureRMI", "plainRMI", "secureSocket", "plainSocket"};<br>
  275. wjxn.setTransportMethods(tm);<br>
  276. </font>
  277. </p>
  280. <h3><a name="FAQ">Frequently Asked Questions (FAQ)</a></h3>
  282. <ul>
  284. <li>
  285. <p>
  286. How do I create my own public/private keystore and how
  287. do I self certify it?
  288. </p>
  290. <p>
  291. Here is an example of how to create a keystore named testkeys with the
  292. password asd123. In general you do not want to specify the password
  293. in the command used. When not specified on the command line the
  294. keytool program will prompt you for a password. The following
  295. command line should all be on the same line.
  296. </p>
  298. <p>
  299. <font size=2 face='Terminal, Arial'>
  300. keytool -genkey -dname "cn=Foo Bar, ou=Columbia University, o=PSL, \<br>
  301. c=US" -alias foobar -keypass asd123 -keystore testkeys \<br>
  302. -storepass asd123 -validity 180
  303. </font>
  304. </p>
  306. <p>
  307. The example also self-certifies the keystore with a validity time of
  308. 180 days. A better way to certify the keystore would be to create a
  309. certificate request and then send it to a third party certifier (see
  310. Java JSSE docs). The entries that reside in the WVM file that are
  311. related to the file that was just created are:
  312. </p>
  314. <font size=2 face='Terminal, Arial'>
  315. WVM_KEYSFILE=testkeys<br>
  316. WVM_PASSWORD=asd123<br>
  318. </font>
  320. <p>
  321. to view details about the keystore you can do:
  322. </p>
  324. <font size=2 face='Terminal, Arial'>
  325. keytool -list -keystore testkeys
  326. </font>
  328. <p>
  329. For for information see: <br>
  330. <a href=></a>
  331. </p>
  332. </li>
  334. <li>
  335. <p>
  336. Where do I find out more information about the available
  337. algorithms that I can use?
  338. </p>
  340. <p>
  341. See the Java documentation about security. Specifically, look at the
  342. JSSE and JCE docs.
  343. </p>
  344. </li>
  346. <li>
  347. <p>
  348. What about java policies?
  349. </p>
  351. <p>
  352. In my implementation the java policies do not play a role.
  353. </p>
  354. </li>
  356. <li>
  357. <p>
  358. Are Worklets signed?
  359. </p>
  361. <p>
  362. Worklets themselves are not signed. Security is at the level of the WVM's. Once
  363. WVMs have authenticated one other, then communication, including that of Worklets,
  364. is trusted.
  365. </p>
  366. </li>
  368. </ul> <!--// End - FAQ //-->
  371. <h3>Possible errors</h3>
  373. <ul>
  375. <li>
  376. The most common errors pertain to the keysfile and the file holding
  377. the CA certificates. Either these files are spelled incorrectly when
  378. specified or the password is incorrect. Another set of parameters to
  379. check are the permissions for the files. Make sure they at least give user
  380. read rights.<br><br> </li>
  382. <li>RMI server cannot bind to registry. <br>
  383. Upon trying to bind a RMI server, if you get this error: <br>
  384. <font size=2 face='Terminal, Arial'>
  385. Shutting down; cannot bind to a non-local host:
  386. RemoteException occurred in server thread; nested exception is:
  387. java.rmi.UnmarshalException: Transport return code invalid
  388. </font>
  389. <p>
  390. Check that the security level of the server and registry are
  391. compliant. If it is secure, then it is expecting the registry to be
  392. secure as well, and is thus communicating through secure protocols.
  393. Security levels of 0 and 1 (none, and low) can bind on the same
  394. registry. Security levels of 2 and 3 (medium and high) can also bind
  395. together on the same registry, but cannot be matched with levels 0 and
  396. 1. Another issue to be aware of is the RMI class loader of the
  397. Registry. If the Registry is created with a secure RMI server, the
  398. instatiation of the server sets the RMI class loader to our secure
  399. implementation and essentially sets the RMI class loader for that JVM.
  400. Therefore when other non-secure servers try to bind, the registry
  401. interacts with the secure RMI class loader, and a remote exception is
  402. thrown. To prevent this from happening you should create the registry
  403. with a plain server.
  404. </p>
  405. </li>
  406. </ul> </ul> <!--// End - Possible Errors //-->
  408. <h3>Future Items</h3>
  409. <ul>
  410. <li>Implement hierarchical structure to security features.</li>
  411. </ul>
  413. <h3>Questions, Contact</h3>
  414. <p>Any questions or comments can be directed to <a href="">Dan Phung</a>.
  415. </p>
  417. <h5 align="right">
  418. back to <a href=Worklets.html>Worklets documentation</a>
  419. </h5>
  421. <!--Start Copyright-->
  422. <font color='#000080' size=1 face='Verdana, Arial, Helvetica'>
  423. <hr size='1' width="400"/>
  424. Copyright © 2002: The Trustees of Columbia University in the City of New York. All Rights Reserved<br>
  425. Author: <a href="">Dan Phung<a> <br>
  426. Last Modified 20 October 2002
  427. <!--End Copyright-->
  429. </body>
  430. </html>