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 either PEM | 15 * Certificates and keys can be added to a SecurityContext from either PEM |
16 * or PKCS12 containers. | 16 * or PKCS12 containers. |
17 * | |
18 * [usePrivateKey], [setTrustedCertificates], [useCertificateChain], and | |
19 * [setClientAuthorities] are deprecated. They have been renamed | |
20 * [usePrivateKeySync], [setTrustedCertificatesSync], [useCertificateChainSync], | |
21 * and [setClientAuthoritiesSync] to reflect the fact that they do blocking | |
22 * IO. Async-friendly versions have been added in [usePrivateKeyBytes], | |
23 * [setTrustedCertificatesBytes], [useCertificateChainBytes], and | |
24 * [setClientAuthoritiesBytes]. | |
25 */ | 17 */ |
26 abstract class SecurityContext { | 18 abstract class SecurityContext { |
27 external factory SecurityContext(); | 19 external factory SecurityContext(); |
28 | 20 |
29 /** | 21 /** |
30 * Secure networking classes with an optional `context` parameter | 22 * Secure networking classes with an optional `context` parameter |
31 * use the [defaultContext] object if the parameter is omitted. | 23 * use the [defaultContext] object if the parameter is omitted. |
32 * This object can also be accessed, and modified, directly. | 24 * This object can also be accessed, and modified, directly. |
33 * Each isolate has a different [defaultContext] object. | 25 * Each isolate has a different [defaultContext] object. |
34 * The [defaultContext] object uses a list of well-known trusted | 26 * The [defaultContext] object uses a list of well-known trusted |
35 * certificate authorities as its trusted roots. This list is | 27 * certificate authorities as its trusted roots. This list is |
36 * taken from Mozilla, who maintains it as part of Firefox. | 28 * taken from Mozilla, who maintains it as part of Firefox. |
37 */ | 29 */ |
38 external static SecurityContext get defaultContext; | 30 external static SecurityContext get defaultContext; |
39 | 31 |
40 /** | 32 /** |
41 * Sets the private key for a server certificate or client certificate. | 33 * Sets the private key for a server certificate or client certificate. |
42 * | 34 * |
43 * A secure connection using this SecurityContext will use this key with | 35 * A secure connection using this SecurityContext will use this key with |
44 * the server or client certificate to sign and decrypt messages. | 36 * the server or client certificate to sign and decrypt messages. |
45 * [keyFile] is the path to a PEM or PKCS12 file containing an encrypted | 37 * [file] is the path to a PEM or PKCS12 file containing an encrypted |
46 * private key, encrypted with [password]. An unencrypted file can be | 38 * private key, encrypted with [password]. Assuming it is well-formatted, all |
47 * used, but this is not usual. | 39 * other contents of [file] are ignored. An unencrypted file can be used, |
| 40 * but this is not usual. |
| 41 * |
| 42 * NB: This function calls [ReadFileAsBytesSync], and will block on file IO. |
| 43 * Prefer using [usePrivateKeyBytes]. |
48 */ | 44 */ |
49 void usePrivateKeySync(String keyFile, {String password}); | 45 void usePrivateKey(String file, {String password}); |
50 | |
51 /** | |
52 * [usePrivateKey] is deprecated. Use [usePrivateKeySync] or | |
53 * [usePrivateKeyBytes]. | |
54 */ | |
55 @deprecated | |
56 void usePrivateKey(String keyFile, {String password}); | |
57 | 46 |
58 /** | 47 /** |
59 * Sets the private key for a server certificate or client certificate. | 48 * Sets the private key for a server certificate or client certificate. |
60 * | 49 * |
61 * Like [usePrivateKeyBytesSync], but takes the contents of the file. | 50 * Like [usePrivateKey], but takes the contents of the file as a list |
| 51 * of bytes. |
62 */ | 52 */ |
63 void usePrivateKeyBytes(List<int> keyBytes, {String password}); | 53 void usePrivateKeyBytes(List<int> keyBytes, {String password}); |
64 | 54 |
65 /** | 55 /** |
66 * Sets the set of trusted X509 certificates used by [SecureSocket] | 56 * Sets the set of trusted X509 certificates used by [SecureSocket] |
67 * client connections, when connecting to a secure server. | 57 * client connections, when connecting to a secure server. |
68 * | 58 * |
69 * [file] is the path to a PEM or PKCS12 file containing X509 certificates, | 59 * [file] is the path to a PEM or PKCS12 file containing X509 certificates, |
70 * usually root certificates from certificate authorities. For PKCS12 files, | 60 * usually root certificates from certificate authorities. For PKCS12 files, |
71 * [password] is the password for the file. For PEM files, [password] is | 61 * [password] is the password for the file. For PEM files, [password] is |
| 62 * ignored. Assuming it is well-formatted, all other contents of [file] are |
72 * ignored. | 63 * ignored. |
| 64 * |
| 65 * NB: This function calls [ReadFileAsBytesSync], and will block on file IO. |
| 66 * Prefer using [setTrustedCertificatesBytes]. |
73 */ | 67 */ |
74 void setTrustedCertificatesSync(String file, {String password}); | |
75 | |
76 /** | |
77 * [setTrustedCertificates] is deprecated. Use [setTrustedCertificatesSync] | |
78 * or [setTrustedCertificatesBytes]. | |
79 */ | |
80 @deprecated | |
81 void setTrustedCertificates(String file, {String password}); | 68 void setTrustedCertificates(String file, {String password}); |
82 | 69 |
83 /** | 70 /** |
84 * Sets the set of trusted X509 certificates used by [SecureSocket] | 71 * Sets the set of trusted X509 certificates used by [SecureSocket] |
85 * client connections, when connecting to a secure server. | 72 * client connections, when connecting to a secure server. |
86 * | 73 * |
87 * Like [setTrustedCertificatesSync] but takes the contents of the file. | 74 * Like [setTrustedCertificates] but takes the contents of the file. |
88 */ | 75 */ |
89 void setTrustedCertificatesBytes(List<int> certBytes,{String password}); | 76 void setTrustedCertificatesBytes(List<int> certBytes, {String password}); |
90 | 77 |
91 /** | 78 /** |
92 * Sets the chain of X509 certificates served by [SecureServer] | 79 * Sets the chain of X509 certificates served by [SecureServer] |
93 * when making secure connections, including the server certificate. | 80 * when making secure connections, including the server certificate. |
94 * | 81 * |
95 * [file] is a PEM or PKCS12 file containing X509 certificates, starting with | 82 * [file] is a PEM or PKCS12 file containing X509 certificates, starting with |
96 * the root authority and intermediate authorities forming the signed | 83 * the root authority and intermediate authorities forming the signed |
97 * chain to the server certificate, and ending with the server certificate. | 84 * chain to the server certificate, and ending with the server certificate. |
98 * The private key for the server certificate is set by [usePrivateKey]. For | 85 * The private key for the server certificate is set by [usePrivateKey]. For |
99 * PKCS12 files, [password] is the password for the file. For PEM files, | 86 * PKCS12 files, [password] is the password for the file. For PEM files, |
100 * [password] is ignored. | 87 * [password] is ignored. Assuming it is well-formatted, all |
| 88 * other contents of [file] are ignored. |
| 89 * |
| 90 * NB: This function calls [ReadFileAsBytesSync], and will block on file IO. |
| 91 * Prefer using [useCertificateChainBytes]. |
101 */ | 92 */ |
102 void useCertificateChainSync(String file, {String password}); | 93 void useCertificateChain(String file, {String password}); |
103 | |
104 /** | |
105 * [useCertificateChain] is deprecated. Use [useCertificateChainSync] | |
106 * or [useCertificateChainBytes]. | |
107 */ | |
108 @deprecated | |
109 void useCertificateChain({String file, String directory, String password}); | |
110 | 94 |
111 /** | 95 /** |
112 * Sets the chain of X509 certificates served by [SecureServer] | 96 * Sets the chain of X509 certificates served by [SecureServer] |
113 * when making secure connections, including the server certificate. | 97 * when making secure connections, including the server certificate. |
114 * | 98 * |
115 * Like [useCertificateChainSync] but takes the contents of the file. | 99 * Like [useCertificateChain] but takes the contents of the file. |
116 */ | 100 */ |
117 void useCertificateChainBytes(List<int> chainBytes, {String password}); | 101 void useCertificateChainBytes(List<int> chainBytes, {String password}); |
118 | 102 |
119 /** | 103 /** |
120 * Sets the list of authority names that a [SecureServer] will advertise | 104 * Sets the list of authority names that a [SecureServer] will advertise |
121 * as accepted when requesting a client certificate from a connecting | 105 * as accepted when requesting a client certificate from a connecting |
122 * client. | 106 * client. |
123 * | 107 * |
124 * [file] is a PEM or PKCS12 file containing the accepted signing | 108 * [file] is a PEM or PKCS12 file containing the accepted signing |
125 * authority certificates - the authority names are extracted from the | 109 * authority certificates - the authority names are extracted from the |
126 * certificates. For PKCS12 files, [password] is the password for the file. | 110 * certificates. For PKCS12 files, [password] is the password for the file. |
127 * For PEM files, [password] is ignored. | 111 * For PEM files, [password] is ignored. Assuming it is well-formatted, all |
| 112 * other contents of [file] are ignored. |
| 113 * |
| 114 * NB: This function calls [ReadFileAsBytesSync], and will block on file IO. |
| 115 * Prefer using [setClientAuthoritiesBytes]. |
128 */ | 116 */ |
129 void setClientAuthoritiesSync(String file, {String password}); | |
130 | |
131 /** | |
132 * [setClientAuthorities] is deprecated. Use [setClientAuthoritiesSync] | |
133 * or [setClientAuthoritiesBytes]. | |
134 */ | |
135 @deprecated | |
136 void setClientAuthorities(String file, {String password}); | 117 void setClientAuthorities(String file, {String password}); |
137 | 118 |
138 /** | 119 /** |
139 * Sets the list of authority names that a [SecureServer] will advertise | 120 * Sets the list of authority names that a [SecureServer] will advertise |
140 * as accepted, when requesting a client certificate from a connecting | 121 * as accepted, when requesting a client certificate from a connecting |
141 * client. | 122 * client. |
142 * | 123 * |
143 * Like [setClientAuthoritySync] but takes the contents of the file. | 124 * Like [setClientAuthority] but takes the contents of the file. |
144 */ | 125 */ |
145 void setClientAuthoritiesBytes(List<int> authCertBytes, {String password}); | 126 void setClientAuthoritiesBytes(List<int> authCertBytes, {String password}); |
146 | 127 |
147 /** | 128 /** |
148 * Sets the list of application-level protocols supported by a client | 129 * Sets the list of application-level protocols supported by a client |
149 * connection or server connection. The ALPN (application level protocol | 130 * connection or server connection. The ALPN (application level protocol |
150 * negotiation) extension to TLS allows a client to send a list of | 131 * negotiation) extension to TLS allows a client to send a list of |
151 * protocols in the TLS client hello message, and the server to pick | 132 * protocols in the TLS client hello message, and the server to pick |
152 * one and send the selected one back in its server hello message. | 133 * one and send the selected one back in its server hello message. |
153 * | 134 * |
(...skipping 95 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
249 } | 230 } |
250 | 231 |
251 if (bytes.length >= (1 << 13)) { | 232 if (bytes.length >= (1 << 13)) { |
252 throw new ArgumentError( | 233 throw new ArgumentError( |
253 'The maximum message length supported is 2^13-1.'); | 234 'The maximum message length supported is 2^13-1.'); |
254 } | 235 } |
255 | 236 |
256 return new Uint8List.fromList(bytes); | 237 return new Uint8List.fromList(bytes); |
257 } | 238 } |
258 } | 239 } |
OLD | NEW |