OLD | NEW |
1 // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2015, 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 * The object containing the certificates to trust when making | 8 * The object containing the certificates to trust when making |
9 * a secure client connection, and the certificate chain and | 9 * a secure client connection, and the certificate chain and |
10 * private key to serve from a secure server. | 10 * private key to serve from a secure server. |
11 * | 11 * |
12 * The [SecureSocket] and [SecureServer] classes take a SecurityContext | 12 * The [SecureSocket] and [SecureServer] classes take a SecurityContext |
13 * as an argument to their connect and bind methods. | 13 * as an argument to their connect and bind methods. |
14 * | 14 * |
15 * Certificates and keys can be added to a SecurityContext from PEM files | 15 * Certificates and keys can be added to a SecurityContext from PEM files |
16 * on the disk. A PEM file contains one or more base-64 encoded DER-serialized | 16 * on the disk. A PEM file contains one or more base-64 encoded DER-serialized |
17 * ASN1 objects, surrounded with delimiter strings like | 17 * ASN1 objects, surrounded with delimiter strings like |
18 * "-----BEGIN CERTIFICATE -----" and "-----END CERTIFICATE-----". | 18 * "-----BEGIN CERTIFICATE -----" and "-----END CERTIFICATE-----". |
19 * Distinguished encoding rules (DER) is a canonical binary serialization | 19 * Distinguished encoding rules (DER) is a canonical binary serialization |
20 * of ASN1 objects into an octet string. | 20 * of ASN1 objects into an octet string. |
| 21 * |
| 22 * [usePrivateKey], [setTrustedCertificates], [useCertificateChain], and |
| 23 * [setClientAuthorities] are deprecated. They have been renamed |
| 24 * [usePrivateKeySync], [setTrustedCertificatesSync], [useCertificateChainSync], |
| 25 * and [setClientAuthoritiesSync] to reflect the fact that they do blocking |
| 26 * IO. Async-friendly versions have been added in [usePrivateKeyBytes], |
| 27 * [setTrustedCertificatesBytes], [useCertificateChainBytes], and |
| 28 * [setClientAuthoritiesBytes]. |
21 */ | 29 */ |
22 abstract class SecurityContext { | 30 abstract class SecurityContext { |
23 external factory SecurityContext(); | 31 external factory SecurityContext(); |
24 | 32 |
25 /** | 33 /** |
26 * Secure networking classes with an optional `context` parameter | 34 * Secure networking classes with an optional `context` parameter |
27 * use the [defaultContext] object if the parameter is omitted. | 35 * use the [defaultContext] object if the parameter is omitted. |
28 * This object can also be accessed, and modified, directly. | 36 * This object can also be accessed, and modified, directly. |
29 * Each isolate has a different [defaultContext] object. | 37 * Each isolate has a different [defaultContext] object. |
30 * The [defaultContext] object uses a list of well-known trusted | 38 * The [defaultContext] object uses a list of well-known trusted |
31 * certificate authorities as its trusted roots. This list is | 39 * certificate authorities as its trusted roots. This list is |
32 * taken from Mozilla, who maintains it as part of Firefox. | 40 * taken from Mozilla, who maintains it as part of Firefox. |
33 */ | 41 */ |
34 external static SecurityContext get defaultContext; | 42 external static SecurityContext get defaultContext; |
35 | 43 |
36 /** | 44 /** |
37 * Sets the private key for a server certificate or client certificate. | 45 * Sets the private key for a server certificate or client certificate. |
38 * | 46 * |
39 * A secure connection using this SecurityContext will use this key with | 47 * A secure connection using this SecurityContext will use this key with |
40 * the server or client certificate to sign and decrypt messages. | 48 * the server or client certificate to sign and decrypt messages. |
41 * [keyFile] is a PEM file containing an encrypted | 49 * [keyFile] is a PEM file containing an encrypted |
42 * private key, encrypted with [password]. An unencrypted file can be | 50 * private key, encrypted with [password]. An unencrypted file can be |
43 * used, but this is not usual. | 51 * used, but this is not usual. |
44 * | |
45 * The function returns a [Future] that completes when the key has been added | |
46 * to the context. | |
47 */ | 52 */ |
48 Future usePrivateKey(String keyFile, {String password}); | 53 void usePrivateKeySync(String keyFile, {String password}); |
| 54 |
| 55 /** |
| 56 * [usePrivateKey] is deprecated. Use [usePrivateKeySync] or |
| 57 * [usePrivateKeyBytes]. |
| 58 */ |
| 59 @deprecated |
| 60 void usePrivateKey(String keyFile, {String password}); |
49 | 61 |
50 /** | 62 /** |
51 * Sets the private key for a server certificate or client certificate. | 63 * Sets the private key for a server certificate or client certificate. |
52 * | 64 * |
53 * A secure connection using this SecurityContext will use this key with | 65 * A secure connection using this SecurityContext will use this key with |
54 * the server or client certificate to sign and decrypt messages. | 66 * the server or client certificate to sign and decrypt messages. |
55 * [keyBytes] is the contents of a PEM file containing an encrypted | 67 * [keyBytes] is the contents of a PEM file containing an encrypted |
56 * private key, encrypted with [password]. An unencrypted file can be | 68 * private key, encrypted with [password]. An unencrypted file can be |
57 * used, but this is not usual. | 69 * used, but this is not usual. |
58 */ | 70 */ |
59 void usePrivateKeyBytes(List<int> keyBytes, {String password}); | 71 void usePrivateKeyBytes(List<int> keyBytes, {String password}); |
60 | 72 |
61 /** | 73 /** |
62 * Sets the set of trusted X509 certificates used by [SecureSocket] | 74 * Sets the set of trusted X509 certificates used by [SecureSocket] |
63 * client connections, when connecting to a secure server. | 75 * client connections, when connecting to a secure server. |
64 * | 76 * |
65 * There are two ways to set a set of trusted certificates, with a single | 77 * [file] is the path to a PEM file containing X509 certificates, usually |
66 * PEM file, or with a directory containing individual PEM files for | 78 * root certificates from certificate authorities. |
67 * certificates. | 79 */ |
| 80 void setTrustedCertificatesSync(String file); |
| 81 |
| 82 /** |
| 83 * [setTrustedCertificates] is deprecated. Use [setTrustedCertificatesSync] |
| 84 * or [setTrustedCertificatesBytes]. |
| 85 */ |
| 86 @deprecated |
| 87 void setTrustedCertificates(String file); |
| 88 |
| 89 /** |
| 90 * Sets the set of trusted X509 certificates used by [SecureSocket] |
| 91 * client connections, when connecting to a secure server. |
68 * | 92 * |
69 * [file] is an optional PEM file containing X509 certificates, usually | 93 * [file] is the contents of a PEM file containing X509 certificates, usually |
70 * root certificates from certificate authorities. | 94 * root certificates from certificate authorities. |
71 * | |
72 * [directory] is an optional directory containing PEM files. The directory | |
73 * must also have filesystem links added, which link extra filenames based | |
74 * on the hash of a certificate's distinguished name (DN) to the file | |
75 * containing that certificate. OpenSSL contains a tool called c_rehash | |
76 * to create these links in a directory. | |
77 */ | 95 */ |
78 void setTrustedCertificates({String file, String directory}); | 96 void setTrustedCertificatesBytes(List<int> certBytes); |
79 | 97 |
80 /** | 98 /** |
81 * Sets the chain of X509 certificates served by [SecureServer] | 99 * Sets the chain of X509 certificates served by [SecureServer] |
82 * when making secure connections, including the server certificate. | 100 * when making secure connections, including the server certificate. |
83 * | 101 * |
84 * [file] is a PEM file containing X509 certificates, starting with | 102 * [file] is a PEM file containing X509 certificates, starting with |
85 * the root authority and intermediate authorities forming the signed | 103 * the root authority and intermediate authorities forming the signed |
86 * chain to the server certificate, and ending with the server certificate. | 104 * chain to the server certificate, and ending with the server certificate. |
87 * The private key for the server certificate is set by [usePrivateKey]. | 105 * The private key for the server certificate is set by [usePrivateKey]. |
88 * | |
89 * The function returns a [Future] that completes when the certificate chain | |
90 * has been set. | |
91 */ | 106 */ |
92 Future useCertificateChain(String file); | 107 void useCertificateChainSync(String file); |
| 108 |
| 109 /** |
| 110 * [useCertificateChain] is deprecated. Use [useCertificateChainSync] |
| 111 * or [useCertificateChainBytes]. |
| 112 */ |
| 113 @deprecated |
| 114 void useCertificateChain({String file, String directory}); |
93 | 115 |
94 /** | 116 /** |
95 * Sets the chain of X509 certificates served by [SecureServer] | 117 * Sets the chain of X509 certificates served by [SecureServer] |
96 * when making secure connections, including the server certificate. | 118 * when making secure connections, including the server certificate. |
97 * | 119 * |
98 * [chainBytes] is the contents of a PEM file containing X509 certificates, | 120 * [chainBytes] is the contents of a PEM file containing X509 certificates, |
99 * starting with the root authority and intermediate authorities forming the | 121 * starting with the root authority and intermediate authorities forming the |
100 * signed chain to the server certificate, and ending with the server | 122 * signed chain to the server certificate, and ending with the server |
101 * certificate. The private key for the server certificate is set by | 123 * certificate. The private key for the server certificate is set by |
102 * [usePrivateKey]. | 124 * [usePrivateKey]. |
103 */ | 125 */ |
104 void useCertificateChainBytes(List<int> chainBytes); | 126 void useCertificateChainBytes(List<int> chainBytes); |
105 | 127 |
106 /** | 128 /** |
107 * Sets the list of authority names that a [SecureServer] will advertise | 129 * Sets the list of authority names that a [SecureServer] will advertise |
108 * as accepted, when requesting a client certificate from a connecting | 130 * as accepted, when requesting a client certificate from a connecting |
109 * client. [file] is a PEM file containing the accepted signing authority | 131 * client. [file] is a PEM file containing the accepted signing authority |
110 * certificates - the authority names are extracted from the certificates. | 132 * certificates - the authority names are extracted from the certificates. |
111 */ | 133 */ |
| 134 void setClientAuthoritiesSync(String file); |
| 135 |
| 136 /** |
| 137 * [setClientAuthorities] is deprecated. Use [setClientAuthoritiesSync] |
| 138 * or [setClientAuthoritiesBytes]. |
| 139 */ |
| 140 @deprecated |
112 void setClientAuthorities(String file); | 141 void setClientAuthorities(String file); |
113 | 142 |
114 /** | 143 /** |
| 144 * Sets the list of authority names that a [SecureServer] will advertise |
| 145 * as accepted, when requesting a client certificate from a connecting |
| 146 * client. [authCertBytes] is the contents of a PEM file containing the |
| 147 * accepted signing authority certificates - the authority names are extracted |
| 148 * from the certificates. |
| 149 */ |
| 150 void setClientAuthoritiesBytes(List<int> authCertBytes); |
| 151 |
| 152 /** |
115 * Sets the list of application-level protocols supported by a client | 153 * Sets the list of application-level protocols supported by a client |
116 * connection or server connection. The ALPN (application level protocol | 154 * connection or server connection. The ALPN (application level protocol |
117 * negotiation) extension to TLS allows a client to send a list of | 155 * negotiation) extension to TLS allows a client to send a list of |
118 * protocols in the TLS client hello message, and the server to pick | 156 * protocols in the TLS client hello message, and the server to pick |
119 * one and send the selected one back in its server hello message. | 157 * one and send the selected one back in its server hello message. |
120 * | 158 * |
121 * Separate lists of protocols can be sent for client connections and | 159 * Separate lists of protocols can be sent for client connections and |
122 * for server connections, using the same SecurityContext. The [isServer] | 160 * for server connections, using the same SecurityContext. The [isServer] |
123 * boolean argument specifies whether to set the list for server connections | 161 * boolean argument specifies whether to set the list for server connections |
124 * or client connections. | 162 * or client connections. |
(...skipping 91 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
216 } | 254 } |
217 | 255 |
218 if (bytes.length >= (1 << 13)) { | 256 if (bytes.length >= (1 << 13)) { |
219 throw new ArgumentError( | 257 throw new ArgumentError( |
220 'The maximum message length supported is 2^13-1.'); | 258 'The maximum message length supported is 2^13-1.'); |
221 } | 259 } |
222 | 260 |
223 return new Uint8List.fromList(bytes); | 261 return new Uint8List.fromList(bytes); |
224 } | 262 } |
225 } | 263 } |
OLD | NEW |