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