diff options
Diffstat (limited to '')
-rw-r--r-- | src/lib/libtls/tls_init.3 (renamed from src/lib/libressl/ressl_init.3) | 232 |
1 files changed, 116 insertions, 116 deletions
diff --git a/src/lib/libressl/ressl_init.3 b/src/lib/libtls/tls_init.3 index 81a32350ee..faa9b99539 100644 --- a/src/lib/libressl/ressl_init.3 +++ b/src/lib/libtls/tls_init.3 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: ressl_init.3,v 1.9 2014/10/16 12:46:35 tedu Exp $ | 1 | .\" $OpenBSD: tls_init.3,v 1.1 2014/10/31 13:46:17 jsing Exp $ |
2 | .\" | 2 | .\" |
3 | .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> | 3 | .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> |
4 | .\" | 4 | .\" |
@@ -14,167 +14,167 @@ | |||
14 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | 14 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
15 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | 15 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
16 | .\" | 16 | .\" |
17 | .Dd $Mdocdate: October 16 2014 $ | 17 | .Dd $Mdocdate: October 31 2014 $ |
18 | .Dt RESSL 3 | 18 | .Dt TLS 3 |
19 | .Os | 19 | .Os |
20 | .Sh NAME | 20 | .Sh NAME |
21 | .Nm ressl_init , | 21 | .Nm tls_init , |
22 | .Nm ressl_error , | 22 | .Nm tls_error , |
23 | .Nm ressl_config_new , | 23 | .Nm tls_config_new , |
24 | .Nm ressl_config_free , | 24 | .Nm tls_config_free , |
25 | .Nm ressl_config_set_ca_file , | 25 | .Nm tls_config_set_ca_file , |
26 | .Nm ressl_config_set_ca_path , | 26 | .Nm tls_config_set_ca_path , |
27 | .Nm ressl_config_set_cert_file , | 27 | .Nm tls_config_set_cert_file , |
28 | .Nm ressl_config_set_cert_mem , | 28 | .Nm tls_config_set_cert_mem , |
29 | .Nm ressl_config_set_ciphers , | 29 | .Nm tls_config_set_ciphers , |
30 | .Nm ressl_config_set_ecdhcurve , | 30 | .Nm tls_config_set_ecdhcurve , |
31 | .Nm ressl_config_set_key_file , | 31 | .Nm tls_config_set_key_file , |
32 | .Nm ressl_config_set_key_mem , | 32 | .Nm tls_config_set_key_mem , |
33 | .Nm ressl_config_set_protocols , | 33 | .Nm tls_config_set_protocols , |
34 | .Nm ressl_config_set_verify_depth , | 34 | .Nm tls_config_set_verify_depth , |
35 | .Nm ressl_config_clear_keys , | 35 | .Nm tls_config_clear_keys , |
36 | .Nm ressl_config_insecure_noverifyhost , | 36 | .Nm tls_config_insecure_noverifyhost , |
37 | .Nm ressl_config_insecure_noverifycert , | 37 | .Nm tls_config_insecure_noverifycert , |
38 | .Nm ressl_config_verify , | 38 | .Nm tls_config_verify , |
39 | .Nm ressl_client , | 39 | .Nm tls_client , |
40 | .Nm ressl_server , | 40 | .Nm tls_server , |
41 | .Nm ressl_configure , | 41 | .Nm tls_configure , |
42 | .Nm ressl_reset , | 42 | .Nm tls_reset , |
43 | .Nm ressl_close , | 43 | .Nm tls_close , |
44 | .Nm ressl_free , | 44 | .Nm tls_free , |
45 | .Nm ressl_connect , | 45 | .Nm tls_connect , |
46 | .Nm ressl_connect_socket , | 46 | .Nm tls_connect_socket , |
47 | .Nm ressl_read , | 47 | .Nm tls_read , |
48 | .Nm ressl_write , | 48 | .Nm tls_write , |
49 | .Nd ressl TLS client and server API | 49 | .Nd tls TLS client and server API |
50 | .Sh SYNOPSIS | 50 | .Sh SYNOPSIS |
51 | .In ressl.h | 51 | .In tls.h |
52 | .Ft "int" | 52 | .Ft "int" |
53 | .Fn ressl_init "void" | 53 | .Fn tls_init "void" |
54 | .Ft "const char *" | 54 | .Ft "const char *" |
55 | .Fn ressl_error "struct ressl *ctx" | 55 | .Fn tls_error "struct tls *ctx" |
56 | .Ft "struct ressl_config *" | 56 | .Ft "struct tls_config *" |
57 | .Fn ressl_config_new "void" | 57 | .Fn tls_config_new "void" |
58 | .Ft "void" | 58 | .Ft "void" |
59 | .Fn ressl_config_free "struct ressl_config *config" | 59 | .Fn tls_config_free "struct tls_config *config" |
60 | .Ft "int" | 60 | .Ft "int" |
61 | .Fn ressl_config_set_ca_file "struct ressl_config *config" "const char *ca_file" | 61 | .Fn tls_config_set_ca_file "struct tls_config *config" "const char *ca_file" |
62 | .Ft "int" | 62 | .Ft "int" |
63 | .Fn ressl_config_set_ca_path "struct ressl_config *config" "const char *ca_path" | 63 | .Fn tls_config_set_ca_path "struct tls_config *config" "const char *ca_path" |
64 | .Ft "int" | 64 | .Ft "int" |
65 | .Fn ressl_config_set_cert_file "struct ressl_config *config" "const char *cert_file" | 65 | .Fn tls_config_set_cert_file "struct tls_config *config" "const char *cert_file" |
66 | .Ft "int" | 66 | .Ft "int" |
67 | .Fn ressl_config_set_cert_mem "struct ressl_config *config" "const uint8_t *cert" "size_t len" | 67 | .Fn tls_config_set_cert_mem "struct tls_config *config" "const uint8_t *cert" "size_t len" |
68 | .Ft "int" | 68 | .Ft "int" |
69 | .Fn ressl_config_set_ciphers "struct ressl_config *config" "const char *ciphers" | 69 | .Fn tls_config_set_ciphers "struct tls_config *config" "const char *ciphers" |
70 | .Ft "int" | 70 | .Ft "int" |
71 | .Fn ressl_config_set_ecdhcurve "struct ressl_config *config" "const char *name" | 71 | .Fn tls_config_set_ecdhcurve "struct tls_config *config" "const char *name" |
72 | .Ft "int" | 72 | .Ft "int" |
73 | .Fn ressl_config_set_key_file "struct ressl_config *config" "const char *key_file" | 73 | .Fn tls_config_set_key_file "struct tls_config *config" "const char *key_file" |
74 | .Ft "int" | 74 | .Ft "int" |
75 | .Fn ressl_config_set_key_mem "struct ressl_config *config" "const uint8_t *key" "size_t len" | 75 | .Fn tls_config_set_key_mem "struct tls_config *config" "const uint8_t *key" "size_t len" |
76 | .Ft "int" | 76 | .Ft "int" |
77 | .Fn ressl_config_set_protocols "struct ressl_config *config" "uint32_t protocols" | 77 | .Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols" |
78 | .Ft "int" | 78 | .Ft "int" |
79 | .Fn ressl_config_set_verify_depth "struct ressl_config *config" "int verify_depth" | 79 | .Fn tls_config_set_verify_depth "struct tls_config *config" "int verify_depth" |
80 | .Ft "void" | 80 | .Ft "void" |
81 | .Fn ressl_config_clear_keys "struct ressl_config *config" | 81 | .Fn tls_config_clear_keys "struct tls_config *config" |
82 | .Ft "void" | 82 | .Ft "void" |
83 | .Fn ressl_config_insecure_noverifyhost "struct ressl_config *config" | 83 | .Fn tls_config_insecure_noverifyhost "struct tls_config *config" |
84 | .Ft "void" | 84 | .Ft "void" |
85 | .Fn ressl_config_insecure_noverifycert "struct ressl_config *config" | 85 | .Fn tls_config_insecure_noverifycert "struct tls_config *config" |
86 | .Ft "void" | 86 | .Ft "void" |
87 | .Fn ressl_config_verify "struct ressl_config *config" | 87 | .Fn tls_config_verify "struct tls_config *config" |
88 | .Ft "struct ressl *" | 88 | .Ft "struct tls *" |
89 | .Fn ressl_client void | 89 | .Fn tls_client void |
90 | .Ft "struct ressl *" | 90 | .Ft "struct tls *" |
91 | .Fn ressl_server void | 91 | .Fn tls_server void |
92 | .Ft "int" | 92 | .Ft "int" |
93 | .Fn ressl_configure "struct ressl *ctx" "struct ressl_config *config" | 93 | .Fn tls_configure "struct tls *ctx" "struct tls_config *config" |
94 | .Ft "void" | 94 | .Ft "void" |
95 | .Fn ressl_reset "struct ressl *ctx" | 95 | .Fn tls_reset "struct tls *ctx" |
96 | .Ft "int" | 96 | .Ft "int" |
97 | .Fn ressl_close "struct ressl *ctx" | 97 | .Fn tls_close "struct tls *ctx" |
98 | .Ft "void" | 98 | .Ft "void" |
99 | .Fn ressl_free "struct ressl *ctx" | 99 | .Fn tls_free "struct tls *ctx" |
100 | .Ft "int" | 100 | .Ft "int" |
101 | .Fn ressl_connect "struct ressl *ctx" "const char *host" "const char *port" | 101 | .Fn tls_connect "struct tls *ctx" "const char *host" "const char *port" |
102 | .Ft "int" | 102 | .Ft "int" |
103 | .Fn ressl_connect_socket "struct ressl *ctx" "int s" "const char *hostname" | 103 | .Fn tls_connect_socket "struct tls *ctx" "int s" "const char *hostname" |
104 | .Ft "int" | 104 | .Ft "int" |
105 | .Fn ressl_read "struct ressl *ctx" "void *buf" "size_t buflen" "size_t *outlen" | 105 | .Fn tls_read "struct tls *ctx" "void *buf" "size_t buflen" "size_t *outlen" |
106 | .Ft "int" | 106 | .Ft "int" |
107 | .Fn ressl_write "struct ressl *ctx" "const void *buf" "size_t buflen" | 107 | .Fn tls_write "struct tls *ctx" "const void *buf" "size_t buflen" |
108 | .Sh DESCRIPTION | 108 | .Sh DESCRIPTION |
109 | The | 109 | The |
110 | .Nm ressl | 110 | .Nm tls |
111 | family of functions establishes a secure communications channel | 111 | family of functions establishes a secure communications channel |
112 | using the TLS socket protocol. | 112 | using the TLS socket protocol. |
113 | Both clients and servers are supported. | 113 | Both clients and servers are supported. |
114 | .Pp | 114 | .Pp |
115 | The | 115 | The |
116 | .Fn ressl_init | 116 | .Fn tls_init |
117 | function should be called once before any function is used. | 117 | function should be called once before any function is used. |
118 | .Pp | 118 | .Pp |
119 | Before a connection is created, a configuration must be created. | 119 | Before a connection is created, a configuration must be created. |
120 | The | 120 | The |
121 | .Fn ressl_config_new | 121 | .Fn tls_config_new |
122 | function returns a new default configuration that can be used for future | 122 | function returns a new default configuration that can be used for future |
123 | connections. | 123 | connections. |
124 | Several functions exist to change the options of the configuration; see below. | 124 | Several functions exist to change the options of the configuration; see below. |
125 | .Pp | 125 | .Pp |
126 | A | 126 | A |
127 | .Em ressl | 127 | .Em tls |
128 | connection is represented as a | 128 | connection is represented as a |
129 | .Em context . | 129 | .Em context . |
130 | A new | 130 | A new |
131 | .Em context | 131 | .Em context |
132 | is created by either the | 132 | is created by either the |
133 | .Fn ressl_client | 133 | .Fn tls_client |
134 | or | 134 | or |
135 | .Fn ressl_server | 135 | .Fn tls_server |
136 | functions. | 136 | functions. |
137 | The context can then be configured with the function | 137 | The context can then be configured with the function |
138 | .Fn ressl_configure . | 138 | .Fn tls_configure . |
139 | The same | 139 | The same |
140 | .Em ressl_config | 140 | .Em tls_config |
141 | object can be used to configure multiple contexts. | 141 | object can be used to configure multiple contexts. |
142 | .Pp | 142 | .Pp |
143 | A client connection is initiated after configuration by calling | 143 | A client connection is initiated after configuration by calling |
144 | .Fn ressl_connect . | 144 | .Fn tls_connect . |
145 | This function will create a new socket, connect to the specified host and | 145 | This function will create a new socket, connect to the specified host and |
146 | port, and then establish a secure connection. | 146 | port, and then establish a secure connection. |
147 | An already existing socket can be upgraded to a secure connection by calling | 147 | An already existing socket can be upgraded to a secure connection by calling |
148 | .Fn ressl_connect_socket . | 148 | .Fn tls_connect_socket . |
149 | .Pp | 149 | .Pp |
150 | Two functions are provided for input and output, | 150 | Two functions are provided for input and output, |
151 | .Fn ressl_read | 151 | .Fn tls_read |
152 | and | 152 | and |
153 | .Fn ressl_write . | 153 | .Fn tls_write . |
154 | .Pp | 154 | .Pp |
155 | After use, a ressl | 155 | After use, a tls |
156 | .Em context | 156 | .Em context |
157 | should be closed with | 157 | should be closed with |
158 | .Fn ressl_close , | 158 | .Fn tls_close , |
159 | and then freed by calling | 159 | and then freed by calling |
160 | .Fn ressl_free . | 160 | .Fn tls_free . |
161 | When no more contexts are to be created, the | 161 | When no more contexts are to be created, the |
162 | .Em ressl_config | 162 | .Em tls_config |
163 | object should be freed by calling | 163 | object should be freed by calling |
164 | .Fn ressl_config_free . | 164 | .Fn tls_config_free . |
165 | .Sh FUNCTIONS | 165 | .Sh FUNCTIONS |
166 | The | 166 | The |
167 | .Fn ressl_init | 167 | .Fn tls_init |
168 | function initializes global data structures. | 168 | function initializes global data structures. |
169 | It should be called once before any other functions. | 169 | It should be called once before any other functions. |
170 | .Pp | 170 | .Pp |
171 | The following functions create and free configuration objects. | 171 | The following functions create and free configuration objects. |
172 | .Bl -bullet -offset four | 172 | .Bl -bullet -offset four |
173 | .It | 173 | .It |
174 | .Fn ressl_config_new | 174 | .Fn tls_config_new |
175 | allocates a new default configuration object. | 175 | allocates a new default configuration object. |
176 | .It | 176 | .It |
177 | .Fn ressl_config_free | 177 | .Fn tls_config_free |
178 | frees a configuration object. | 178 | frees a configuration object. |
179 | .El | 179 | .El |
180 | .Pp | 180 | .Pp |
@@ -182,68 +182,68 @@ The following functions modify a configuration by setting parameters. | |||
182 | Configuration options may apply to only clients or only servers or both. | 182 | Configuration options may apply to only clients or only servers or both. |
183 | .Bl -bullet -offset four | 183 | .Bl -bullet -offset four |
184 | .It | 184 | .It |
185 | .Fn ressl_config_set_ca_file | 185 | .Fn tls_config_set_ca_file |
186 | sets the filename used to load a file | 186 | sets the filename used to load a file |
187 | containing the root certificates. | 187 | containing the root certificates. |
188 | .Em (Client) | 188 | .Em (Client) |
189 | .It | 189 | .It |
190 | .Fn ressl_config_set_ca_path | 190 | .Fn tls_config_set_ca_path |
191 | sets the path (directory) which should be searched for root | 191 | sets the path (directory) which should be searched for root |
192 | certificates. | 192 | certificates. |
193 | .Em (Client) | 193 | .Em (Client) |
194 | .It | 194 | .It |
195 | .Fn ressl_config_set_cert_file | 195 | .Fn tls_config_set_cert_file |
196 | sets file from which the public certificate will be read. | 196 | sets file from which the public certificate will be read. |
197 | .Em (Client and server) | 197 | .Em (Client and server) |
198 | .It | 198 | .It |
199 | .Fn ressl_config_set_cert_mem | 199 | .Fn tls_config_set_cert_mem |
200 | sets the public certificate directly from memory. | 200 | sets the public certificate directly from memory. |
201 | .Em (Client and server) | 201 | .Em (Client and server) |
202 | .It | 202 | .It |
203 | .Fn ressl_config_set_ciphers | 203 | .Fn tls_config_set_ciphers |
204 | sets the list of ciphers that may be used. | 204 | sets the list of ciphers that may be used. |
205 | .Em (Client and server) | 205 | .Em (Client and server) |
206 | .It | 206 | .It |
207 | .Fn ressl_config_set_key_file | 207 | .Fn tls_config_set_key_file |
208 | sets the file from which the private key will be read. | 208 | sets the file from which the private key will be read. |
209 | .Em (Server) | 209 | .Em (Server) |
210 | .It | 210 | .It |
211 | .Fn ressl_config_set_key_mem | 211 | .Fn tls_config_set_key_mem |
212 | directly sets the private key from memory. | 212 | directly sets the private key from memory. |
213 | .Em (Server) | 213 | .Em (Server) |
214 | .It | 214 | .It |
215 | .Fn ressl_config_set_protocols | 215 | .Fn tls_config_set_protocols |
216 | sets which versions of the protocol may be used. | 216 | sets which versions of the protocol may be used. |
217 | Possible values are the bitwise OR of: | 217 | Possible values are the bitwise OR of: |
218 | .Pp | 218 | .Pp |
219 | .Bl -tag -width "RESSL_PROTOCOL_TLSv1_2" -offset indent -compact | 219 | .Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact |
220 | .It Dv RESSL_PROTOCOL_TLSv1_0 | 220 | .It Dv TLS_PROTOCOL_TLSv1_0 |
221 | .It Dv RESSL_PROTOCOL_TLSv1_1 | 221 | .It Dv TLS_PROTOCOL_TLSv1_1 |
222 | .It Dv RESSL_PROTOCOL_TLSv1_2 | 222 | .It Dv TLS_PROTOCOL_TLSv1_2 |
223 | .El | 223 | .El |
224 | .Pp | 224 | .Pp |
225 | Additionally, the values | 225 | Additionally, the values |
226 | .Dv RESSL_PROTOCOL_TLSv1 | 226 | .Dv TLS_PROTOCOL_TLSv1 |
227 | (all TLS versions) and | 227 | (all TLS versions) and |
228 | .Dv RESSL_PROTOCOLS_DEFAULT | 228 | .Dv TLS_PROTOCOLS_DEFAULT |
229 | (currently all TLS versions) may be used. | 229 | (currently all TLS versions) may be used. |
230 | .Em (Client and server) | 230 | .Em (Client and server) |
231 | .It | 231 | .It |
232 | .Fn ressl_config_clear_keys | 232 | .Fn tls_config_clear_keys |
233 | clears any secret keys from memory. | 233 | clears any secret keys from memory. |
234 | .Em (Server) | 234 | .Em (Server) |
235 | .It | 235 | .It |
236 | .Fn ressl_config_insecure_noverifyhost | 236 | .Fn tls_config_insecure_noverifyhost |
237 | disables hostname verification. | 237 | disables hostname verification. |
238 | Be careful when using this option. | 238 | Be careful when using this option. |
239 | .Em (Client) | 239 | .Em (Client) |
240 | .It | 240 | .It |
241 | .Fn ressl_config_insecure_noverifycert | 241 | .Fn tls_config_insecure_noverifycert |
242 | disables certificate verification. | 242 | disables certificate verification. |
243 | Be extremely careful when using this option. | 243 | Be extremely careful when using this option. |
244 | .Em (Client) | 244 | .Em (Client) |
245 | .It | 245 | .It |
246 | .Fn ressl_config_verify | 246 | .Fn tls_config_verify |
247 | reenables hostname and certificate verification. | 247 | reenables hostname and certificate verification. |
248 | .Em (Client) | 248 | .Em (Client) |
249 | .El | 249 | .El |
@@ -251,28 +251,28 @@ reenables hostname and certificate verification. | |||
251 | The following functions create, prepare, and free a connection context. | 251 | The following functions create, prepare, and free a connection context. |
252 | .Bl -bullet -offset four | 252 | .Bl -bullet -offset four |
253 | .It | 253 | .It |
254 | .Fn ressl_client | 254 | .Fn tls_client |
255 | creates a new ressl context for client connections. | 255 | creates a new tls context for client connections. |
256 | .It | 256 | .It |
257 | .Fn ressl_server | 257 | .Fn tls_server |
258 | creates a new ressl context for server connections. | 258 | creates a new tls context for server connections. |
259 | .It | 259 | .It |
260 | .Fn ressl_configure | 260 | .Fn tls_configure |
261 | readies a ressl context for use by applying the configuration | 261 | readies a tls context for use by applying the configuration |
262 | options. | 262 | options. |
263 | .It | 263 | .It |
264 | .Fn ressl_close | 264 | .Fn tls_close |
265 | closes a connection after use. | 265 | closes a connection after use. |
266 | .It | 266 | .It |
267 | .Fn ressl_free | 267 | .Fn tls_free |
268 | frees a ressl context after use. | 268 | frees a tls context after use. |
269 | .El | 269 | .El |
270 | .Pp | 270 | .Pp |
271 | The following functions initiate a connection and perform input and output | 271 | The following functions initiate a connection and perform input and output |
272 | operations. | 272 | operations. |
273 | .Bl -bullet -offset four | 273 | .Bl -bullet -offset four |
274 | .It | 274 | .It |
275 | .Fn ressl_connect | 275 | .Fn tls_connect |
276 | connects a client context to the server named by | 276 | connects a client context to the server named by |
277 | .Fa host . | 277 | .Fa host . |
278 | The | 278 | The |
@@ -280,10 +280,10 @@ The | |||
280 | may be numeric or a service name. | 280 | may be numeric or a service name. |
281 | If it is NULL then a host of the format "hostname:port" is permitted. | 281 | If it is NULL then a host of the format "hostname:port" is permitted. |
282 | .It | 282 | .It |
283 | .Fn ressl_connect_socket | 283 | .Fn tls_connect_socket |
284 | connects a client context to an already established socket connection. | 284 | connects a client context to an already established socket connection. |
285 | .It | 285 | .It |
286 | .Fn ressl_read | 286 | .Fn tls_read |
287 | reads | 287 | reads |
288 | .Fa buflen | 288 | .Fa buflen |
289 | bytes of data from the socket into | 289 | bytes of data from the socket into |
@@ -291,7 +291,7 @@ bytes of data from the socket into | |||
291 | The amount of data read is returned in | 291 | The amount of data read is returned in |
292 | .Fa outlen . | 292 | .Fa outlen . |
293 | .It | 293 | .It |
294 | .Fn ressl_write | 294 | .Fn tls_write |
295 | writes | 295 | writes |
296 | .Fa buflen | 296 | .Fa buflen |
297 | bytes of data from | 297 | bytes of data from |
@@ -309,7 +309,7 @@ Functions that return a pointer will return NULL on error. | |||
309 | .\" .Sh SEE ALSO | 309 | .\" .Sh SEE ALSO |
310 | .Sh HISTORY | 310 | .Sh HISTORY |
311 | The | 311 | The |
312 | .Nm ressl | 312 | .Nm tls |
313 | API first appeared in | 313 | API first appeared in |
314 | .Ox 5.6 | 314 | .Ox 5.6 |
315 | as a response to the unnecessary challenges other APIs present in | 315 | as a response to the unnecessary challenges other APIs present in |