OLD | NEW |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.io; | 5 part of dart.io; |
6 | 6 |
7 /** | 7 /** |
8 * A high-level class for communicating securely over a TCP socket, using | 8 * A high-level class for communicating securely over a TCP socket, using |
9 * TLS and SSL. The [SecureSocket] exposes both a [Stream] and an | 9 * TLS and SSL. The [SecureSocket] exposes both a [Stream] and an |
10 * [IOSink] interface, making it ideal for using together with | 10 * [IOSink] interface, making it ideal for using together with |
(...skipping 78 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
89 host: host, | 89 host: host, |
90 sendClientCertificate: sendClientCertificate, | 90 sendClientCertificate: sendClientCertificate, |
91 onBadCertificate: onBadCertificate); | 91 onBadCertificate: onBadCertificate); |
92 }) | 92 }) |
93 .then((raw) { | 93 .then((raw) { |
94 completer.complete(new SecureSocket._(raw)); | 94 completer.complete(new SecureSocket._(raw)); |
95 }); | 95 }); |
96 return completer.future; | 96 return completer.future; |
97 } | 97 } |
98 | 98 |
99 | |
100 /** | 99 /** |
101 * Takes an already connected [socket] and starts server side TLS | 100 * Takes an already connected [socket] and starts server side TLS |
102 * handshake to make the communication secure. When the returned | 101 * handshake to make the communication secure. When the returned |
103 * future completes the [SecureSocket] has completed the TLS | 102 * future completes the [SecureSocket] has completed the TLS |
104 * handshake. Using this function requires that the other end of the | 103 * handshake. Using this function requires that the other end of the |
105 * connection is going to start the TLS handshake. | 104 * connection is going to start the TLS handshake. |
106 * | 105 * |
107 * If the [socket] already has a subscription, this subscription | 106 * If the [socket] already has a subscription, this subscription |
108 * will no longer receive and events. In most cases calling | 107 * will no longer receive and events. In most cases calling |
109 * [:pause:] on this subscription before starting TLS handshake is | 108 * [:pause:] on this subscription before starting TLS handshake is |
(...skipping 88 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
198 * useBuiltinRoots: false); | 197 * useBuiltinRoots: false); |
199 * | 198 * |
200 * The database should be an NSS certificate database directory | 199 * The database should be an NSS certificate database directory |
201 * containing a cert9.db file, not a cert8.db file. This version of | 200 * containing a cert9.db file, not a cert8.db file. This version of |
202 * the database can be created using the NSS certutil tool with "sql:" in | 201 * the database can be created using the NSS certutil tool with "sql:" in |
203 * front of the absolute path of the database directory, or setting the | 202 * front of the absolute path of the database directory, or setting the |
204 * environment variable [[NSS_DEFAULT_DB_TYPE]] to "sql". | 203 * environment variable [[NSS_DEFAULT_DB_TYPE]] to "sql". |
205 */ | 204 */ |
206 external static void initialize({String database, | 205 external static void initialize({String database, |
207 String password, | 206 String password, |
208 bool useBuiltinRoots: true}); | 207 bool useBuiltinRoots: true, |
209 | 208 bool readOnly: true}); |
210 | 209 |
211 /** | 210 /** |
212 * Trust strings for use in [addCertificate]. | 211 * Trust strings for use in [addCertificate] and [changeTrust]. |
213 */ | 212 */ |
214 static const String TRUST_ISSUE_SERVER_CERTIFICATES = 'C,,'; | 213 static const String TRUST_ISSUE_SERVER_CERTIFICATES = 'C,,'; |
215 static const String TRUST_ISSUE_CLIENT_CERTIFICATES = 'T,,'; | 214 static const String TRUST_ISSUE_CLIENT_CERTIFICATES = 'T,,'; |
216 static const String TRUST_ISSUE_CLIENT_SERVER_CERTIFICATES = 'TC,,'; | 215 static const String TRUST_ISSUE_CLIENT_SERVER_CERTIFICATES = 'TC,,'; |
217 static const String TRUST_CERTIFICATE = 'P,,'; | 216 static const String TRUST_CERTIFICATE = 'P,,'; |
218 | 217 |
219 | |
220 /** | 218 /** |
221 * Adds a X509 certificate (for SSL and TLS secure networking) to the | 219 * Adds a X509 certificate (for SSL and TLS secure networking) to the |
222 * in-memory certificate database. Returns an X509Certificate object | 220 * in-memory certificate cache. Returns an X509Certificate object |
223 * with information about the added certificate. | 221 * with information about the added certificate. |
224 * | 222 * |
| 223 * The in-memory certificate cache is different from the certificate |
| 224 * database opened by `SecureSocket.initialize`, and certificates added |
| 225 * by [addCertificate] cannot be modified or removed by [changeTrust] |
| 226 * or [removeCertificate]. However, if the certificate is already in the |
| 227 * database, then [removeCertificate] will remove it from both the database |
| 228 * and the in-memory cache. |
| 229 * |
225 * [certificate] must be a list of bytes encoding a certificate in | 230 * [certificate] must be a list of bytes encoding a certificate in |
226 * PEM format: a base64 encoded DER certificate, enclosed between | 231 * PEM format: a base64 encoded DER certificate, enclosed between |
227 * "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". | 232 * "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". |
228 * | 233 * |
229 * [trust] is a string specifying the allowed uses of this certificate. | 234 * [trust] is a string specifying the allowed uses of this certificate. |
230 * For example, 'TC,,' specifies that the certificate is for a certificate | 235 * For example, 'TC,,' specifies that the certificate is for a certificate |
231 * authority that is trusted to issue server and client certificates, so | 236 * authority that is trusted to issue server and client certificates, so |
232 * that a server or client certificate signed by this authority will be | 237 * that a server or client certificate signed by this authority will be |
233 * accepted. | 238 * accepted. |
234 * | 239 * |
235 * See the documentation of NSS certutil at | 240 * See the documentation of NSS certutil at |
236 * http://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools_:_certutil | 241 * http://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools_:_certutil |
237 * or | 242 * or |
238 * http://blogs.oracle.com/meena/entry/notes_about_trust_flags | 243 * http://blogs.oracle.com/meena/entry/notes_about_trust_flags |
239 * for more information about trust attributes. | 244 * for more information about trust attributes. |
240 */ | 245 */ |
241 external static X509Certificate addCertificate(List<int> certificate, | 246 external static X509Certificate addCertificate(List<int> certificate, |
242 String trust); | 247 String trust); |
| 248 |
| 249 /** |
| 250 * Adds a X509 certificates (for SSL and TLS secure networking) with |
| 251 * their private keys to the certificate database. SecureSocket.initialize |
| 252 * must have been called with the path to a certificate database, and with |
| 253 * readOnly set to `false`. |
| 254 * |
| 255 * [certificates] must be a list containing the bytes of a PKCS #12 encoded |
| 256 * list of certificates and private keys. These are commonly called |
| 257 * `.pfx` or `.p12` files. Only PKCS #12 files using |
| 258 * 3-key triple-DES and 40 bit RC2 encryption are accepted. |
| 259 * |
| 260 * All certificates are imported with no default trust, and the appropriate |
| 261 * uses of each certificate must be added with `SecureSocket.changeTrust`. |
| 262 * |
| 263 * See the documentation of NSS certutil at |
| 264 * http://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools_:_certutil |
| 265 * or |
| 266 * http://blogs.oracle.com/meena/entry/notes_about_trust_flags |
| 267 * for more information about trust attributes. |
| 268 * |
| 269 * Returns a CertificateError if it fails. The error code -8183 does not |
| 270 * indicate that the PKCS #12 file is corrupt. It also is returned if |
| 271 * the certificate database is read-only, or is the default internal database, |
| 272 * or if the password for the file or database is incorrect. |
| 273 */ |
| 274 external static importCertificatesWithPrivateKeys(List<int> certificates, |
| 275 String password); |
| 276 |
| 277 /** |
| 278 * Changes the trust settings for the certificate with nickname [nickname]. |
| 279 * This certificate must exist in the certificate database. |
| 280 * SecureSocket.initialize must have been called with the path to a |
| 281 * certificate database, and with readOnly set to false. |
| 282 * |
| 283 * [trust] is a string specifying the allowed uses of this certificate. |
| 284 * For example, 'TC,,' specifies that the certificate is for a certificate |
| 285 * authority that is trusted to issue server and client certificates, so |
| 286 * that a server or client certificate signed by this authority will be |
| 287 * accepted. |
| 288 * |
| 289 * See the documentation of NSS certutil at |
| 290 * http://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools_:_certutil |
| 291 * or |
| 292 * http://blogs.oracle.com/meena/entry/notes_about_trust_flags |
| 293 * for more information about trust attributes. |
| 294 */ |
| 295 external static X509Certificate changeTrust(String nickname, |
| 296 String trust); |
| 297 |
| 298 /** |
| 299 * Gets the certificate with nickname [nickname] from |
| 300 * the certificate database. Returns an X509Certificate object with |
| 301 * information about the certificate. |
| 302 * |
| 303 * Throws a CertificateException if it cannot find the certificate with |
| 304 * the given nickname. |
| 305 */ |
| 306 external static X509Certificate getCertificate(String nickname); |
| 307 |
| 308 /** |
| 309 * Removes the certificate with nickname [nickname] permanently from |
| 310 * the certificate database. |
| 311 * This certificate must exist in the certificate database. |
| 312 * SecureSocket.initialize must have been called with the path to a |
| 313 * certificate database, and with readOnly set to false. |
| 314 * |
| 315 * Returns null if it cannot find the certificate with that nickname. |
| 316 */ |
| 317 external static removeCertificate(String nickname); |
243 } | 318 } |
244 | 319 |
245 | 320 |
246 /** | 321 /** |
247 * RawSecureSocket provides a secure (SSL or TLS) network connection. | 322 * RawSecureSocket provides a secure (SSL or TLS) network connection. |
248 * Client connections to a server are provided by calling | 323 * Client connections to a server are provided by calling |
249 * RawSecureSocket.connect. A secure server, created with | 324 * RawSecureSocket.connect. A secure server, created with |
250 * RawSecureServerSocket, also returns RawSecureSocket objects representing | 325 * RawSecureServerSocket, also returns RawSecureSocket objects representing |
251 * the server end of a secure connection. | 326 * the server end of a secure connection. |
252 * The certificate provided by the server is checked | 327 * The certificate provided by the server is checked |
(...skipping 1051 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1304 /** | 1379 /** |
1305 * An exception that happens in the handshake phase of establishing | 1380 * An exception that happens in the handshake phase of establishing |
1306 * a secure network connection, when looking up or verifying a | 1381 * a secure network connection, when looking up or verifying a |
1307 * certificate. | 1382 * certificate. |
1308 */ | 1383 */ |
1309 class CertificateException extends TlsException { | 1384 class CertificateException extends TlsException { |
1310 const CertificateException([String message = "", | 1385 const CertificateException([String message = "", |
1311 OSError osError = null]) | 1386 OSError osError = null]) |
1312 : super._("CertificateException", message, osError); | 1387 : super._("CertificateException", message, osError); |
1313 } | 1388 } |
OLD | NEW |