summaryrefslogtreecommitdiff
path: root/src/lib/libtls/tls_init.3
diff options
context:
space:
mode:
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
109The 109The
110.Nm ressl 110.Nm tls
111family of functions establishes a secure communications channel 111family of functions establishes a secure communications channel
112using the TLS socket protocol. 112using the TLS socket protocol.
113Both clients and servers are supported. 113Both clients and servers are supported.
114.Pp 114.Pp
115The 115The
116.Fn ressl_init 116.Fn tls_init
117function should be called once before any function is used. 117function should be called once before any function is used.
118.Pp 118.Pp
119Before a connection is created, a configuration must be created. 119Before a connection is created, a configuration must be created.
120The 120The
121.Fn ressl_config_new 121.Fn tls_config_new
122function returns a new default configuration that can be used for future 122function returns a new default configuration that can be used for future
123connections. 123connections.
124Several functions exist to change the options of the configuration; see below. 124Several functions exist to change the options of the configuration; see below.
125.Pp 125.Pp
126A 126A
127.Em ressl 127.Em tls
128connection is represented as a 128connection is represented as a
129.Em context . 129.Em context .
130A new 130A new
131.Em context 131.Em context
132is created by either the 132is created by either the
133.Fn ressl_client 133.Fn tls_client
134or 134or
135.Fn ressl_server 135.Fn tls_server
136functions. 136functions.
137The context can then be configured with the function 137The context can then be configured with the function
138.Fn ressl_configure . 138.Fn tls_configure .
139The same 139The same
140.Em ressl_config 140.Em tls_config
141object can be used to configure multiple contexts. 141object can be used to configure multiple contexts.
142.Pp 142.Pp
143A client connection is initiated after configuration by calling 143A client connection is initiated after configuration by calling
144.Fn ressl_connect . 144.Fn tls_connect .
145This function will create a new socket, connect to the specified host and 145This function will create a new socket, connect to the specified host and
146port, and then establish a secure connection. 146port, and then establish a secure connection.
147An already existing socket can be upgraded to a secure connection by calling 147An 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
150Two functions are provided for input and output, 150Two functions are provided for input and output,
151.Fn ressl_read 151.Fn tls_read
152and 152and
153.Fn ressl_write . 153.Fn tls_write .
154.Pp 154.Pp
155After use, a ressl 155After use, a tls
156.Em context 156.Em context
157should be closed with 157should be closed with
158.Fn ressl_close , 158.Fn tls_close ,
159and then freed by calling 159and then freed by calling
160.Fn ressl_free . 160.Fn tls_free .
161When no more contexts are to be created, the 161When no more contexts are to be created, the
162.Em ressl_config 162.Em tls_config
163object should be freed by calling 163object should be freed by calling
164.Fn ressl_config_free . 164.Fn tls_config_free .
165.Sh FUNCTIONS 165.Sh FUNCTIONS
166The 166The
167.Fn ressl_init 167.Fn tls_init
168function initializes global data structures. 168function initializes global data structures.
169It should be called once before any other functions. 169It should be called once before any other functions.
170.Pp 170.Pp
171The following functions create and free configuration objects. 171The 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
175allocates a new default configuration object. 175allocates a new default configuration object.
176.It 176.It
177.Fn ressl_config_free 177.Fn tls_config_free
178frees a configuration object. 178frees a configuration object.
179.El 179.El
180.Pp 180.Pp
@@ -182,68 +182,68 @@ The following functions modify a configuration by setting parameters.
182Configuration options may apply to only clients or only servers or both. 182Configuration 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
186sets the filename used to load a file 186sets the filename used to load a file
187containing the root certificates. 187containing 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
191sets the path (directory) which should be searched for root 191sets the path (directory) which should be searched for root
192certificates. 192certificates.
193.Em (Client) 193.Em (Client)
194.It 194.It
195.Fn ressl_config_set_cert_file 195.Fn tls_config_set_cert_file
196sets file from which the public certificate will be read. 196sets 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
200sets the public certificate directly from memory. 200sets 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
204sets the list of ciphers that may be used. 204sets 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
208sets the file from which the private key will be read. 208sets 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
212directly sets the private key from memory. 212directly 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
216sets which versions of the protocol may be used. 216sets which versions of the protocol may be used.
217Possible values are the bitwise OR of: 217Possible 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
225Additionally, the values 225Additionally, 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
233clears any secret keys from memory. 233clears 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
237disables hostname verification. 237disables hostname verification.
238Be careful when using this option. 238Be 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
242disables certificate verification. 242disables certificate verification.
243Be extremely careful when using this option. 243Be 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
247reenables hostname and certificate verification. 247reenables hostname and certificate verification.
248.Em (Client) 248.Em (Client)
249.El 249.El
@@ -251,28 +251,28 @@ reenables hostname and certificate verification.
251The following functions create, prepare, and free a connection context. 251The 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
255creates a new ressl context for client connections. 255creates a new tls context for client connections.
256.It 256.It
257.Fn ressl_server 257.Fn tls_server
258creates a new ressl context for server connections. 258creates a new tls context for server connections.
259.It 259.It
260.Fn ressl_configure 260.Fn tls_configure
261readies a ressl context for use by applying the configuration 261readies a tls context for use by applying the configuration
262options. 262options.
263.It 263.It
264.Fn ressl_close 264.Fn tls_close
265closes a connection after use. 265closes a connection after use.
266.It 266.It
267.Fn ressl_free 267.Fn tls_free
268frees a ressl context after use. 268frees a tls context after use.
269.El 269.El
270.Pp 270.Pp
271The following functions initiate a connection and perform input and output 271The following functions initiate a connection and perform input and output
272operations. 272operations.
273.Bl -bullet -offset four 273.Bl -bullet -offset four
274.It 274.It
275.Fn ressl_connect 275.Fn tls_connect
276connects a client context to the server named by 276connects a client context to the server named by
277.Fa host . 277.Fa host .
278The 278The
@@ -280,10 +280,10 @@ The
280may be numeric or a service name. 280may be numeric or a service name.
281If it is NULL then a host of the format "hostname:port" is permitted. 281If 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
284connects a client context to an already established socket connection. 284connects a client context to an already established socket connection.
285.It 285.It
286.Fn ressl_read 286.Fn tls_read
287reads 287reads
288.Fa buflen 288.Fa buflen
289bytes of data from the socket into 289bytes of data from the socket into
@@ -291,7 +291,7 @@ bytes of data from the socket into
291The amount of data read is returned in 291The 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
295writes 295writes
296.Fa buflen 296.Fa buflen
297bytes of data from 297bytes 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
311The 311The
312.Nm ressl 312.Nm tls
313API first appeared in 313API first appeared in
314.Ox 5.6 314.Ox 5.6
315as a response to the unnecessary challenges other APIs present in 315as a response to the unnecessary challenges other APIs present in