1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<link rel="stylesheet" href="style.css" type="text/css">
5
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
6
<link rel="Start" href="index.html">
7
<link rel="previous" href="Rpc_mapping_ref.html">
8
<link rel="next" href="Shell_sys.html">
9
<link rel="Up" href="index.html">
10
<link title="Index of types" rel=Appendix href="index_types.html">
11
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
12
<link title="Index of values" rel=Appendix href="index_values.html">
13
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
14
<link title="Index of class methods" rel=Appendix href="index_methods.html">
15
<link title="Index of classes" rel=Appendix href="index_classes.html">
16
<link title="Index of class types" rel=Appendix href="index_class_types.html">
17
<link title="Index of modules" rel=Appendix href="index_modules.html">
18
<link title="Index of module types" rel=Appendix href="index_module_types.html">
19
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
20
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
21
<link title="Https_client" rel="Chapter" href="Https_client.html">
22
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
23
<link title="Equeue" rel="Chapter" href="Equeue.html">
24
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
25
<link title="Unixqueue_pollset" rel="Chapter" href="Unixqueue_pollset.html">
26
<link title="Unixqueue_select" rel="Chapter" href="Unixqueue_select.html">
27
<link title="Uq_resolver" rel="Chapter" href="Uq_resolver.html">
28
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
29
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
30
<link title="Uq_io" rel="Chapter" href="Uq_io.html">
31
<link title="Uq_lwt" rel="Chapter" href="Uq_lwt.html">
32
<link title="Uq_libevent" rel="Chapter" href="Uq_libevent.html">
33
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
34
<link title="Netcamlbox" rel="Chapter" href="Netcamlbox.html">
35
<link title="Netcgi_apache" rel="Chapter" href="Netcgi_apache.html">
36
<link title="Netcgi_modtpl" rel="Chapter" href="Netcgi_modtpl.html">
37
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
38
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
39
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
40
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
41
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
42
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
43
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
44
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
45
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
46
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
47
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
48
<link title="Http_client_conncache" rel="Chapter" href="Http_client_conncache.html">
49
<link title="Http_client" rel="Chapter" href="Http_client.html">
50
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
51
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
52
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
53
<link title="Http_fs" rel="Chapter" href="Http_fs.html">
54
<link title="Ftp_fs" rel="Chapter" href="Ftp_fs.html">
55
<link title="Netclient_tut" rel="Chapter" href="Netclient_tut.html">
56
<link title="Netgssapi" rel="Chapter" href="Netgssapi.html">
57
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
58
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
59
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
60
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
61
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
62
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
63
<link title="Nethttpd_util" rel="Chapter" href="Nethttpd_util.html">
64
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
65
<link title="Netmech_scram" rel="Chapter" href="Netmech_scram.html">
66
<link title="Netmech_scram_gssapi" rel="Chapter" href="Netmech_scram_gssapi.html">
67
<link title="Netmcore" rel="Chapter" href="Netmcore.html">
68
<link title="Netmcore_camlbox" rel="Chapter" href="Netmcore_camlbox.html">
69
<link title="Netmcore_mempool" rel="Chapter" href="Netmcore_mempool.html">
70
<link title="Netmcore_heap" rel="Chapter" href="Netmcore_heap.html">
71
<link title="Netmcore_ref" rel="Chapter" href="Netmcore_ref.html">
72
<link title="Netmcore_array" rel="Chapter" href="Netmcore_array.html">
73
<link title="Netmcore_sem" rel="Chapter" href="Netmcore_sem.html">
74
<link title="Netmcore_mutex" rel="Chapter" href="Netmcore_mutex.html">
75
<link title="Netmcore_condition" rel="Chapter" href="Netmcore_condition.html">
76
<link title="Netmcore_queue" rel="Chapter" href="Netmcore_queue.html">
77
<link title="Netmcore_buffer" rel="Chapter" href="Netmcore_buffer.html">
78
<link title="Netmcore_matrix" rel="Chapter" href="Netmcore_matrix.html">
79
<link title="Netmcore_hashtbl" rel="Chapter" href="Netmcore_hashtbl.html">
80
<link title="Netmcore_process" rel="Chapter" href="Netmcore_process.html">
81
<link title="Netmcore_tut" rel="Chapter" href="Netmcore_tut.html">
82
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
83
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
84
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
85
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
86
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
87
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
88
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
89
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
90
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
91
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
92
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
93
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
94
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
95
<link title="Netplex_semaphore" rel="Chapter" href="Netplex_semaphore.html">
96
<link title="Netplex_sharedvar" rel="Chapter" href="Netplex_sharedvar.html">
97
<link title="Netplex_mutex" rel="Chapter" href="Netplex_mutex.html">
98
<link title="Netplex_encap" rel="Chapter" href="Netplex_encap.html">
99
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
100
<link title="Netplex_advanced" rel="Chapter" href="Netplex_advanced.html">
101
<link title="Netplex_admin" rel="Chapter" href="Netplex_admin.html">
102
<link title="Netshm" rel="Chapter" href="Netshm.html">
103
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
104
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
105
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
106
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
107
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
108
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
109
<link title="Netstream" rel="Chapter" href="Netstream.html">
110
<link title="Mimestring" rel="Chapter" href="Mimestring.html">
111
<link title="Netmime" rel="Chapter" href="Netmime.html">
112
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
113
<link title="Neturl" rel="Chapter" href="Neturl.html">
114
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
115
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
116
<link title="Netdate" rel="Chapter" href="Netdate.html">
117
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
118
<link title="Netulex" rel="Chapter" href="Netulex.html">
119
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
120
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
121
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
122
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
123
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
124
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
125
<link title="Netaux" rel="Chapter" href="Netaux.html">
126
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
127
<link title="Netpagebuffer" rel="Chapter" href="Netpagebuffer.html">
128
<link title="Netfs" rel="Chapter" href="Netfs.html">
129
<link title="Netglob" rel="Chapter" href="Netglob.html">
130
<link title="Netauth" rel="Chapter" href="Netauth.html">
131
<link title="Netsockaddr" rel="Chapter" href="Netsockaddr.html">
132
<link title="Netnumber" rel="Chapter" href="Netnumber.html">
133
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
134
<link title="Xdr_mstring" rel="Chapter" href="Xdr_mstring.html">
135
<link title="Xdr" rel="Chapter" href="Xdr.html">
136
<link title="Netcompression" rel="Chapter" href="Netcompression.html">
137
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
138
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
139
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
140
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
141
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
142
<link title="Netsys" rel="Chapter" href="Netsys.html">
143
<link title="Netsys_posix" rel="Chapter" href="Netsys_posix.html">
144
<link title="Netsys_pollset" rel="Chapter" href="Netsys_pollset.html">
145
<link title="Netlog" rel="Chapter" href="Netlog.html">
146
<link title="Netexn" rel="Chapter" href="Netexn.html">
147
<link title="Netsys_win32" rel="Chapter" href="Netsys_win32.html">
148
<link title="Netsys_pollset_posix" rel="Chapter" href="Netsys_pollset_posix.html">
149
<link title="Netsys_pollset_win32" rel="Chapter" href="Netsys_pollset_win32.html">
150
<link title="Netsys_pollset_generic" rel="Chapter" href="Netsys_pollset_generic.html">
151
<link title="Netsys_signal" rel="Chapter" href="Netsys_signal.html">
152
<link title="Netsys_oothr" rel="Chapter" href="Netsys_oothr.html">
153
<link title="Netsys_xdr" rel="Chapter" href="Netsys_xdr.html">
154
<link title="Netsys_rng" rel="Chapter" href="Netsys_rng.html">
155
<link title="Netsys_types" rel="Chapter" href="Netsys_types.html">
156
<link title="Netsys_mem" rel="Chapter" href="Netsys_mem.html">
157
<link title="Netsys_tmp" rel="Chapter" href="Netsys_tmp.html">
158
<link title="Netgzip" rel="Chapter" href="Netgzip.html">
159
<link title="Netpop" rel="Chapter" href="Netpop.html">
160
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
161
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
162
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
163
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
164
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
165
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
166
<link title="Rpc" rel="Chapter" href="Rpc.html">
167
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
168
<link title="Rpc_util" rel="Chapter" href="Rpc_util.html">
169
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
170
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
171
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
172
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
173
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
174
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
175
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
176
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
177
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
178
<link title="Rpc_auth_gssapi" rel="Chapter" href="Rpc_auth_gssapi.html">
179
<link title="Rpc_proxy" rel="Chapter" href="Rpc_proxy.html">
180
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
181
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
182
<link title="Rpc_intro_gss" rel="Chapter" href="Rpc_intro_gss.html">
183
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
184
<link title="Shell" rel="Chapter" href="Shell.html">
185
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
186
<link title="Shell_fs" rel="Chapter" href="Shell_fs.html">
187
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
188
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html">
189
<link title="Intro" rel="Chapter" href="Intro.html">
190
<link title="Platform" rel="Chapter" href="Platform.html">
191
<link title="Foreword" rel="Chapter" href="Foreword.html">
192
<link title="Ipv6" rel="Chapter" href="Ipv6.html"><link title="Securing RPC with the GSS-API" rel="Section" href="#intro">
193
<link title="The GSS-API" rel="Subsection" href="#2_TheGSSAPI">
194
<link title="The GSS-API in Ocaml" rel="Subsection" href="#2_TheGSSAPIinOcaml">
195
<link title="SCRAM" rel="Subsection" href="#2_SCRAM">
196
<link title="Enabling SCRAM for RPC clients" rel="Subsection" href="#2_EnablingSCRAMforRPCclients">
197
<link title="Enabling SCRAM for RPC proxies" rel="Subsection" href="#2_EnablingSCRAMforRPCproxies">
198
<link title="Enabling SCRAM for RPC servers" rel="Subsection" href="#2_EnablingSCRAMforRPCservers">
199
<link title="Enabling SCRAM in Netplex context" rel="Subsection" href="#2_EnablingSCRAMinNetplexcontext">
200
<link title="Security considerations" rel="Subsection" href="#2_Securityconsiderations">
201
<title>Ocamlnet 3 Reference Manual : Rpc_intro_gss</title>
204
<div class="navbar"><a href="Rpc_mapping_ref.html">Previous</a>
205
<a href="index.html">Up</a>
206
<a href="Shell_sys.html">Next</a>
208
<center><h1>Rpc_intro_gss</h1></center>
211
<span id="intro"><h1>Securing RPC with the GSS-API</h1></span>
214
This text explains how to enable strong authentication and strong
215
encryption on RPC connections.
218
<span id="2_TheGSSAPI"><h2>The GSS-API</h2></span>
221
The GSS-API (Generic Security Service API) is an interface between
222
the security provider (i.e. the authentication/encryption provider)
223
and the application needing security features. The GSS-API is a
224
standard (RFC 2743). The GSS-API is often already implemented by
225
operating systems or by security systems like Kerberos. This means,
226
there is usually a library on the C level containing the C functions
230
The nice thing about GSS-API is the mechanism genericy: The API can
231
provide access to multiple security mechanisms, and it is possible
232
to wrap almost every security mechanism in the form of GSS-API.
235
There is a "competitor" to GSS-API, namely SASL. The feature set is
236
not identical, though. Both APIs allow strong authentication. GSS-API
237
additionally includes encryption and integrity protection for
238
message-oriented communication (but not for continuous data streams),
239
whereas SASL does not have such a feature and has to rely on external
240
layers to do so (which is often SSL). There is a bridge between GSS-API
241
and SASL called GS2 - it translates the authentication part of GSS-API
245
As mentioned, GSS-API only covers the encryption and integrity
246
protection of messages, not of continuous streams. In so far there is
247
not much intersection with SSL, which only handles such streams. For
248
message-oriented protocols such as RPC the feature set of GSS-API is
249
naturally the better choice. There is a standard called RPCSEC-GSS
250
defining the details of how GSS-API is to be used for ONCRPC (RFC
254
<span id="2_TheGSSAPIinOcaml"><h2>The GSS-API in Ocaml</h2></span>
257
The GSS-API is defined as a class type <a href="Netgssapi.gss_api-c.html"><code class="code">Netgssapi.gss_api</code></a>. We do not
258
want to go much into detail - for <b>using</b> the GSS-API it is not
259
required to understand everything. The class type is "feature
260
compatible" with the standard C version of the API (RFC 2744)
261
allowing it to interface with implementations of GSS-API available
262
in C. (Note that this has not been done when this text is written.)
265
A class type has been chosen because this allows it that each
266
security provider can define an independent class implementing
267
the GSS-API. This is different than in the C bindings of GSS-API
268
where only one provider can exist at a time (linked into the program),
269
although the provider can manage several mechanisms.
272
When using GSS-API you will be confronted with OIDs, names, and
273
credentials. These concepts are defined in the <a href="Netgssapi.html"><code class="code">Netgssapi</code></a> module:
276
<li>An OID (object identifier) is a IANA-registered number helping
277
to identify especially security mechanisms, and styles of
278
naming principals (user and system identities). OIDs are also
279
used in other contexts (e.g. ASN-1, X500).</li>
280
<li>Names come in various forms, and because of this, GSS-API uses
281
opaque objects for names, not strings. Names can e.g. identify
282
users. There are various styles (name types). For example, users
283
are often identified by a simple string ("guest") whereas
284
service names also include the host name where the service runs
285
("emailserver@machine"). As names are opaque, they can be
286
imported from a string representation to the opaque object
287
and they can be converted back to strings.</li>
288
<li>Credentials are pieces of information allowing the security
289
mechanism to check whether a connected participant has actually
290
a certain name. A simple example is a password.</li>
293
OIDs are represented as <code class="code">oid = int array</code>. There are a number of predefined
297
<li><a href="Netgssapi.html#VALnt_user_name"><code class="code">Netgssapi.nt_user_name</code></a> is the OID of the name type identifying
299
<li><a href="Netgssapi.html#VALnt_hostbased_service"><code class="code">Netgssapi.nt_hostbased_service</code></a> is the OID of the name type
300
identifying services relative to hosts</li>
301
<li><a href="Netmech_scram_gssapi.html#VALscram_mech"><code class="code">Netmech_scram_gssapi.scram_mech</code></a> is the OID of the SCRAM
302
security mechanism</li>
305
An empty array is often used to mean the default (e.g. default
309
Names are represented as <a href="Netgssapi.html#TYPEname"><code class="code">Netgssapi.name</code></a>. This object has almost
310
no methods - which is intended because names are opaque to users
311
outside the GSS-API implementation. The GSS-API defines methods
312
to import and export names:
315
<li><a href="Netgssapi.gss_api-c.html#METHODimport_name"><code class="code">Netgssapi.gss_api.import_name</code></a> allows one to convert a pair
316
of a name type and a string to the opaque <a href="Netgssapi.html#TYPEname"><code class="code">Netgssapi.name</code></a>
317
object. The name type is an OID.</li>
318
<li><a href="Netgssapi.gss_api-c.html#METHODdisplay_name"><code class="code">Netgssapi.gss_api.display_name</code></a> is roughly the reverse operation
319
(but see below).</li>
320
<li><a href="Netgssapi.gss_api-c.html#METHODexport_name"><code class="code">Netgssapi.gss_api.export_name</code></a> converts an opaque name to
321
a binary string. It is ensured that another call of <code class="code">import_name</code>
322
with the same string restores the opaque name.</li>
325
Note that, at least for certain security mechanisms, there may be
326
several ways of writing the name of a principal, or there might be
327
naming elements spanning several mechanisms. This is an issue when
328
names need to be compared. Generally, it may lead to wrong results
329
when names are compared by displaying or exporting them, and then
330
comparing the resulting strings. There is a special
331
<a href="Netgssapi.gss_api-c.html#METHODcompare_name"><code class="code">Netgssapi.gss_api.compare_name</code></a> method for comparisons, and
332
<a href="Netgssapi.gss_api-c.html#METHODcanonicalize_name"><code class="code">Netgssapi.gss_api.canonicalize_name</code></a> may also be useful in this
336
For RPC, the ways of referring to names have been simplified - more on
340
Credentials are also opaque objects - <a href="Netgssapi.html#TYPEcredential"><code class="code">Netgssapi.credential</code></a>. It is
341
generally assumed that a GSS-API implementation can look up the right
342
credentials for a principal that is identified by name. For example,
343
the GSS-API provider for SCRAM can be equipped with a "keyring", i.e.
344
a callback that maps user names to passwords.
347
<span id="2_SCRAM"><h2>SCRAM</h2></span>
350
SCRAM (Salted Challenge Response Authentication Mechanism) is a
351
relatively new security mechanism (RFC 5802) with interesting
355
<li>It is a password-based authentication scheme</li>
356
<li>No complicated helpers like certification authorities or
357
ticket servers are required for deployment</li>
358
<li>The password is not transmitted during authentication (because
359
of the challenge/response style)</li>
360
<li>The server needs not to store the password in cleartext. Only the salted
361
password is needed, and it is not possible to use a salted password
362
on the client (i.e. it is fruitless to steal the password database)</li>
363
<li>Not only the client authenticates to the server, but also vice
364
versa - the protocol proves to the client that the server has access
365
to the salted password</li>
366
<li>The server does not have a name</li>
369
There is an extension for SCRAM so that AES-128 encryption and
370
SHA-1 integrity protection become available in GSS-API context.
373
SCRAM is implemented in <a href="Netmech_scram.html"><code class="code">Netmech_scram</code></a>. The GSS-API encapsulation
374
is done in <a href="Netmech_scram_gssapi.html"><code class="code">Netmech_scram_gssapi</code></a>.
377
Some more words on names and credentials: Clients have to impersonate
378
as a user, given by a simple unstructured string. The RFC requires
379
that this string is UTF-8, and that certain Unicode normalizations
380
need to be applied before use. This is not implemented right now
381
(SASLprep is missing). Because of this, only US-ASCII user names are
382
accepted. The same applies to the passwords.
385
In SCRAM, the client needs to know the password in cleartext. The
386
server, however, usually only stores a triple
389
<pre><code class="code"> (salted_password, salt, iteration_count) </code></pre>
392
in the authentication database. The <code class="code">iteration_count</code> is a
393
constant defined by the server (should be >= 4096). The <code class="code">salt</code> is
394
a random string that is created when the user entry is added to the
395
database. The function <a href="Netmech_scram.html#VALcreate_salt"><code class="code">Netmech_scram.create_salt</code></a> can be used
396
for this. The <code class="code">salted_password</code> can be computed from the two other
397
parameters and the password with <a href="Netmech_scram.html#VALsalt_password"><code class="code">Netmech_scram.salt_password</code></a>.
400
The GSS-API encapsulation of SCRAM is <a href="Netmech_scram_gssapi.scram_gss_api-c.html"><code class="code">Netmech_scram_gssapi.scram_gss_api</code></a>.
404
<pre><code class="code">class scram_gss_api :
405
?client_key_ring:client_key_ring ->
406
?server_key_verifier:server_key_verifier ->
407
Netmech_scram.profile ->
412
takes a few arguments. The <code class="code">profile</code> can be just obtained by calling
415
<pre><code class="code">Netmech_scram.profile `GSSAPI
419
which is usally the right thing here (one can also set a few parameters
420
at this point). Depending on whether the class is needed for clients
421
or servers, one passes either <code class="code">client_key_ring</code> or <code class="code">server_key_verifier</code>.
424
<a href="Netmech_scram_gssapi.client_key_ring-c.html"><code class="code">Netmech_scram_gssapi.client_key_ring</code></a> is an object like
427
<pre><code class="code">let client_key_ring =
429
method password_of_user_name user =
431
| "guest" -> "guest"
432
| "gerd" -> "I won't reveal it"
433
| _ -> raise Not_found
435
method default_user_name = Some "guest"
440
that mainly returns the passwords of users and that optionally defines
441
a default user. (E.g. the default user could be set to the current
442
login name of the process running the client.)
445
<a href="Netmech_scram_gssapi.server_key_verifier-c.html"><code class="code">Netmech_scram_gssapi.server_key_verifier</code></a> provides the credentials
446
for password verification, e.g.
449
<pre><code class="code">let server_key_verifier =
451
method scram_credentials user =
454
("\209\002U?,/Vu\253&\140\196j\158{b]\221\140\029",
455
"68bd268fe5e948a7e171a4df9ef6450a",
458
("\135\202\182P\142\r\175?\222\156\201bA\188\1296\154\197v\142",
459
"5e51d100ace8d1a69cd4d015ac5da947",
461
| _ -> raise Not_found
466
<span id="2_EnablingSCRAMforRPCclients"><h2>Enabling SCRAM for RPC clients</h2></span>
469
Basically, an RPC client is created by a call like
472
<pre><code class="code">let client = Rpc_client.create2 m prog esys
476
or by invoking ocamlrpcgen-created wrappers of this call. How can we
477
enable SCRAM authentication?
480
Assumed we already created the <code class="code">gss_api</code> object by instantiating the
481
class <a href="Netmech_scram_gssapi.scram_gss_api-c.html"><code class="code">Netmech_scram_gssapi.scram_gss_api</code></a> this is done in two steps:
484
<li>Create the authentication method on RPC level:
485
<pre><code class="code">
487
Rpc_auth_gssapi.client_auth_method
488
~user_name_interpretation:(`Plain_name Netgssapi.nt_user_name)
489
gss_api Netmech_scram.scram_mech
491
<li>Add this method to the client:
492
<pre><code class="code"> Rpc_client.set_auth_methods client [am]
496
Optionally, one can also do a third step:
499
<li>Set the user (if you do not want to impersonate the default user):
500
<pre><code class="code"> Rpc_client.set_user_name client (Some "gerd")
507
Of course, <code class="code">am</code> can be shared by several clients. This does not mean,
508
however, that the clients share the security contexts. For each client
509
a separate context is created (i.e. the authentication protocol starts
513
Both TCP and UDP are supported. Note that especially for UDP there
514
might be issues with retransmitted client requests after running into
515
timeouts. The problem is that retransmitted requests and the following
516
responses look different on the wire than the original messages, and
517
because of this the client can only accept a response when it is the
518
response to the latest retransmission. This makes the retransmission
519
feature less reliable. Best is to avoid UDP.
522
The function <a href="Rpc_auth_gssapi.html#VALclient_auth_method"><code class="code">Rpc_auth_gssapi.client_auth_method</code></a> has a few optional
523
arguments controlling whether encryption or integrity protection are
527
<li>By setting <code class="code">~privacy:`Required</code> it is ensured that encryption and
528
integrity protection are both enabled. If the security mechanism
529
does not provide this, the function fails.</li>
530
<li>The default is <code class="code">~privacy:`If_possible</code>. This means that
531
privacy is enabled if the mechanism supports it.</li>
532
<li>There is a second argument <code class="code">~integrity</code> only controlling integrity
533
protection. It comes into play if full privacy is not available
534
or if it is disabled with <code class="code">~privacy:`None</code>. If integrity protection
535
is on but full privacy is off the messages are not encrypted but
536
only signed with a checksum.</li>
537
<li>One can also turn both features off: <code class="code">~privacy:`None</code> and <code class="code">~integrity:`None</code>.
538
In this case, the messages are neither enrypted nor protected.
539
The authentication protocol at the beginning of a session is unaffected
540
and is done nevertheless. This may be an option if you only want
541
to authenticate a TCP connection but not protect the connection.
542
For UDP it is strongly discouraged to use this mode - it is very
543
easy to hack this.</li>
544
<li>Of course, the RPC server has the last word which protection level is
548
You might have wondered why we pass
551
<pre><code class="code">~user_name_interpretation:(`Plain_name Netgssapi.nt_user_name)
555
to <code class="code">client_auth_method</code>. As described above, there are various ways
556
how to represent names. In the RPC context we need a simple string.
557
The <code class="code">user_name_interpretation</code> argument selects how the opaque
558
GSS-API names are converted to strings.
561
<span id="2_EnablingSCRAMforRPCproxies"><h2>Enabling SCRAM for RPC proxies</h2></span>
564
The <a href="Rpc_proxy.html"><code class="code">Rpc_proxy</code></a> module is a higher-level encapsulation of RPC clients
565
providing additional reliability features. One can also configure the
566
proxies to use authentication:
569
<li>Pass the authentication method <code class="code">am</code> (as created above) in the
570
mclient config with the argument <code class="code">~auth_methods</code>, see
571
<a href="Rpc_proxy.ManagedClient.html#VALcreate_mclient_config"><code class="code">Rpc_proxy.ManagedClient.create_mclient_config</code></a>.</li>
572
<li>Set the user in the mclient config with the argument <code class="code">~user_name</code></li>
575
This could e.g. look like
578
<pre><code class="code">let config =
579
Rpc_proxy.ManagedClient.create_mclient_config
582
~user_name:(Some "gerd")
588
The <code class="code">config</code> value can then, as usual, be passed to
589
<a href="Rpc_proxy.ManagedClient.html#VALcreate_mclient"><code class="code">Rpc_proxy.ManagedClient.create_mclient</code></a>.
592
<span id="2_EnablingSCRAMforRPCservers"><h2>Enabling SCRAM for RPC servers</h2></span>
595
The general procedure for enabling authentication is similar to that
599
<li>Create the authentication method on RPC level:
600
<pre><code class="code">
602
Rpc_auth_gssapi.server_auth_method
603
~user_name_format:`Plain_name
604
gss_api Netmech_scram.scram_mech
606
<li>Add this method to the server:
607
<pre><code class="code"> Rpc_server.set_auth_methods server [am]
611
The method <code class="code">am</code> can be shared by several servers.
614
Each connection to a server normally opens a new security context (or
615
better, the context handles are kept private per connection). There
616
is a special mode, however, permitting a more liberal setting: By
617
passing <code class="code">~shared_context:true</code> to
618
<a href="Rpc_auth_gssapi.html#VALserver_auth_method"><code class="code">Rpc_auth_gssapi.server_auth_method</code></a> independent connections can
619
share security contexts if they know the security handles. Although
620
the Ocamlnet client does not support this mode, it might be required
621
for interoperability with other implementations. Also, for UDP
622
servers this mode <b>must</b> be enabled - each UDP request/response
623
pair is considered as a new connection by the RPC server (in some
624
sense this is a peculiarity of the implementation).
627
You can get the name of the authenticated user with the function
628
<a href="Rpc_server.html#VALget_user"><code class="code">Rpc_server.get_user</code></a>. The way of translating opaque GSS-API names
629
to strings can be selected with the <code class="code">~user_name_format</code> argument
630
of <a href="Rpc_auth_gssapi.html#VALserver_auth_method"><code class="code">Rpc_auth_gssapi.server_auth_method</code></a>.
633
By setting <code class="code">~require_privacy</code> one can demand that only privacy-protected
634
messages are accepted. <code class="code">~require_integrity</code> demands that at least
635
integrity-protected messages are used.
638
<span id="2_EnablingSCRAMinNetplexcontext"><h2>Enabling SCRAM in Netplex context</h2></span>
641
The question is where to call <a href="Rpc_server.html#VALset_auth_methods"><code class="code">Rpc_server.set_auth_methods</code></a>.
644
RPC services are created by using <a href="Rpc_netplex.html#VALrpc_factory"><code class="code">Rpc_netplex.rpc_factory</code></a>. This
645
function has an argument <code class="code">setup</code> which is a callback for configuring
646
the server. Usually, this callback is used to bind the RPC procedure
647
functions to the server object. This is also the ideal place to
648
set the authentication method.
651
<b>Pitfall:</b> Note that <code class="code">setup</code> may also be called for dummy servers
652
that are not connected to real file descriptors. Netplex does this
653
to find out how the server will be configured (especially it is
654
interested in the list of procedures). If this is an issue you can
655
test for a dummy server with <a href="Rpc_server.html#VALis_dummy"><code class="code">Rpc_server.is_dummy</code></a>.
658
<span id="2_Securityconsiderations"><h2>Security considerations</h2></span>
661
SCRAM seems to be an excellent choice for a password-based
662
authentication protocol. Of course, it has all the well-known
663
weaknesses of the password approach (e.g. dictionary attacks are
664
possible), but otherwise it is certainly state of the art.
667
The RPC messages are encrypted with AES-128. This is not configurable.
670
Integrity protection is obtained by using SHA-1 hashes. This is also
674
Some parts of the RPC messages are not fully protected: Headers and
675
error responses. This means that the numbers identifying the called
676
RPC procedures are not privacy-protected. They are only
680
Error responses are completely unprotected.
b'\\ No newline at end of file'
added
removed
doc/html-main/Rpc_intro_gss.html
