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