summaryrefslogtreecommitdiff
path: root/src/lib/libssl/man/ssl.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libssl/man/ssl.3')
-rw-r--r--src/lib/libssl/man/ssl.31319
1 files changed, 1319 insertions, 0 deletions
diff --git a/src/lib/libssl/man/ssl.3 b/src/lib/libssl/man/ssl.3
new file mode 100644
index 0000000000..004d71f9f2
--- /dev/null
+++ b/src/lib/libssl/man/ssl.3
@@ -0,0 +1,1319 @@
1.\"
2.\" $OpenBSD: ssl.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
3.\"
4.Dd $Mdocdate: November 5 2016 $
5.Dt SSL 3
6.Os
7.Sh NAME
8.Nm ssl
9.Nd OpenSSL SSL/TLS library
10.Sh DESCRIPTION
11The OpenSSL
12.Nm ssl
13library implements the Secure Sockets Layer (SSL v2/v3) and
14Transport Layer Security (TLS v1) protocols.
15It provides a rich API which is documented here.
16.Pp
17At first the library must be initialized; see
18.Xr SSL_library_init 3 .
19.Pp
20Then an
21.Vt SSL_CTX
22object is created as a framework to establish TLS/SSL enabled connections (see
23.Xr SSL_CTX_new 3 ) .
24Various options regarding certificates, algorithms, etc., can be set in this
25object.
26.Pp
27When a network connection has been created, it can be assigned to an
28.Vt SSL
29object.
30After the
31.Vt SSL
32object has been created using
33.Xr SSL_new 3 ,
34.Xr SSL_set_fd 3
35or
36.Xr SSL_set_bio 3
37can be used to associate the network connection with the object.
38.Pp
39Then the TLS/SSL handshake is performed using
40.Xr SSL_accept 3
41or
42.Xr SSL_connect 3
43respectively.
44.Xr SSL_read 3
45and
46.Xr SSL_write 3
47are used to read and write data on the TLS/SSL connection.
48.Xr SSL_shutdown 3
49can be used to shut down the TLS/SSL connection.
50.Sh DATA STRUCTURES
51Currently the OpenSSL
52.Nm ssl
53library functions deals with the following data structures:
54.Bl -tag -width Ds
55.It Vt SSL_METHOD No (SSL Method)
56That's a dispatch structure describing the internal
57.Nm ssl
58library methods/functions which implement the various protocol versions
59(SSLv1, SSLv2 and TLSv1).
60It's needed to create an
61.Vt SSL_CTX .
62.It Vt SSL_CIPHER No (SSL Cipher)
63This structure holds the algorithm information for a particular cipher which
64is a core part of the SSL/TLS protocol.
65The available ciphers are configured on an
66.Vt SSL_CTX
67basis and the actually used ones are then part of the
68.Vt SSL_SESSION .
69.It Vt SSL_CTX No (SSL Context)
70That's the global context structure which is created by a server or client
71once per program lifetime and which holds mainly default values for the
72.Vt SSL
73structures which are later created for the connections.
74.It Vt SSL_SESSION No (SSL Session)
75This is a structure containing the current TLS/SSL session details for a
76connection:
77.Vt SSL_CIPHER Ns s, client and server certificates, keys, etc.
78.It Vt SSL No (SSL Connection)
79That's the main SSL/TLS structure which is created by a server or client per
80established connection.
81This actually is the core structure in the SSL API.
82Under run-time the application usually deals with this structure which has
83links to mostly all other structures.
84.El
85.Sh HEADER FILES
86Currently the OpenSSL
87.Nm ssl
88library provides the following C header files containing the prototypes for the
89data structures and functions:
90.Bl -tag -width Ds
91.It Pa ssl.h
92That's the common header file for the SSL/TLS API.
93Include it into your program to make the API of the
94.Nm ssl
95library available.
96It internally includes both more private SSL headers and headers from the
97.Em crypto
98library.
99Whenever you need hardcore details on the internals of the SSL API, look inside
100this header file.
101.It Pa ssl2.h
102That's the sub header file dealing with the SSLv2 protocol only.
103.Bf Em
104 Usually you don't have to include it explicitly because it's already included
105by
106.Pa ssl.h .
107.Ef
108.It Pa ssl3.h
109That's the sub header file dealing with the SSLv3 protocol only.
110.Bf Em
111Usually you don't have to include it explicitly because it's already included
112by
113.Pa ssl.h .
114.Ef
115.It Pa ssl23.h
116That's the sub header file dealing with the combined use of the SSLv2 and SSLv3
117protocols.
118.Bf Em
119Usually you don't have to include it explicitly because it's already included
120by
121.Pa ssl.h .
122.Ef
123.It Pa tls1.h
124That's the sub header file dealing with the TLSv1 protocol only.
125.Bf Em
126Usually you don't have to include it explicitly because it's already included
127by
128.Pa ssl.h .
129.Ef
130.El
131.Sh API FUNCTIONS
132The functions that the OpenSSL
133.Nm ssl
134library exports are documented below:
135.Ss DEALING WITH PROTOCOL METHODS
136Here we document the various API functions which deal with the SSL/TLS protocol
137methods defined in
138.Vt SSL_METHOD
139structures.
140.Bl -tag -width Ds
141.It Xo
142.Ft const SSL_METHOD *
143.Fn SSLv2_client_method void
144.Xc
145Constructor for the SSLv2
146.Vt SSL_METHOD
147structure for a dedicated client.
148.It Xo
149.Ft const SSL_METHOD *
150.Fn SSLv2_server_method void
151.Xc
152Constructor for the SSLv2
153.Vt SSL_METHOD
154structure for a dedicated server.
155.It Xo
156.Ft const SSL_METHOD *
157.Fn SSLv2_method void
158.Xc
159Constructor for the SSLv2
160.Vt SSL_METHOD
161structure for combined client and server.
162.It Xo
163.Ft const SSL_METHOD *
164.Fn SSLv3_client_method void
165.Xc
166Constructor for the SSLv3
167.Vt SSL_METHOD
168structure for a dedicated client.
169.It Xo
170.Ft const SSL_METHOD *
171.Fn SSLv3_server_method void
172.Xc
173Constructor for the SSLv3
174.Vt SSL_METHOD
175structure for a dedicated server.
176.It Xo
177.Ft const SSL_METHOD *
178.Fn SSLv3_method void
179.Xc
180Constructor for the SSLv3
181.Vt SSL_METHOD
182structure for combined client and server.
183.It Xo
184.Ft const SSL_METHOD *
185.Fn TLSv1_client_method void
186.Xc
187Constructor for the TLSv1
188.Vt SSL_METHOD
189structure for a dedicated client.
190.It Xo
191.Ft const SSL_METHOD *
192.Fn TLSv1_server_method void
193.Xc
194Constructor for the TLSv1
195.Vt SSL_METHOD
196structure for a dedicated server.
197.It Xo
198.Ft const SSL_METHOD *
199.Fn TLSv1_method void
200.Xc
201Constructor for the TLSv1
202.Vt SSL_METHOD
203structure for combined client and server.
204.El
205.Ss DEALING WITH CIPHERS
206Here we document the various API functions which deal with the SSL/TLS ciphers
207defined in
208.Vt SSL_CIPHER
209structures.
210.Bl -tag -width Ds
211.It Xo
212.Ft char *
213.Fn SSL_CIPHER_description "SSL_CIPHER *cipher" "char *buf" "int len"
214.Xc
215Write a string to
216.Fa buf
217(with a maximum size of
218.Fa len )
219containing a human readable description of
220.Fa cipher .
221Returns
222.Fa buf .
223.It Xo
224.Ft int
225.Fn SSL_CIPHER_get_bits "SSL_CIPHER *cipher" "int *alg_bits"
226.Xc
227Determine the number of bits in
228.Fa cipher .
229Because of export crippled ciphers there are two bits:
230the bits the algorithm supports in general (stored to
231.Fa alg_bits )
232and the bits which are actually used (the return value).
233.It Xo
234.Ft const char *
235.Fn SSL_CIPHER_get_name "SSL_CIPHER *cipher"
236.Xc
237Return the internal name of
238.Fa cipher
239as a string.
240These are the various strings defined by the
241.Dv SSL2_TXT_xxx ,
242.Dv SSL3_TXT_xxx
243and
244.Dv TLS1_TXT_xxx
245definitions in the header files.
246.It Xo
247.Ft char *
248.Fn SSL_CIPHER_get_version "SSL_CIPHER *cipher"
249.Xc
250Returns a string like
251Qq TLSv1/SSLv3
252or
253Qq SSLv2
254which indicates the SSL/TLS protocol version to which
255.Fa cipher
256belongs (i.e., where it was defined in the specification the first time).
257.El
258.Ss DEALING WITH PROTOCOL CONTEXTS
259Here we document the various API functions which deal with the SSL/TLS
260protocol context defined in the
261.Vt SSL_CTX
262structure.
263.Bl -tag -width Ds
264.It Xo
265.Ft int
266.Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *x"
267.Xc
268.It Xo
269.Ft long
270.Fn SSL_CTX_add_extra_chain_cert "SSL_CTX *ctx" "X509 *x509"
271.Xc
272.It Xo
273.Ft int
274.Fn SSL_CTX_add_session "SSL_CTX *ctx" "SSL_SESSION *c"
275.Xc
276.It Xo
277.Ft int
278.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx"
279.Xc
280.It Xo
281.Ft long
282.Fn SSL_CTX_ctrl "SSL_CTX *ctx" "int cmd" "long larg" "char *parg"
283.Xc
284.It Xo
285.Ft void
286.Fn SSL_CTX_flush_sessions "SSL_CTX *s" "long t"
287.Xc
288.It Xo
289.Ft void
290.Fn SSL_CTX_free "SSL_CTX *a"
291.Xc
292.It Xo
293.Ft char *
294.Fn SSL_CTX_get_app_data "SSL_CTX *ctx"
295.Xc
296.It Xo
297.Ft X509_STORE *
298.Fn SSL_CTX_get_cert_store "SSL_CTX *ctx"
299.Xc
300.It Xo
301.Ft STACK *
302.Fn SSL_CTX_get_client_CA_list "const SSL_CTX *ctx"
303.Xc
304.It Xo
305.Ft int
306.Fn "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))"
307.Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"
308.Xc
309.It Xo
310.Ft char *
311.Fn SSL_CTX_get_ex_data "const SSL_CTX *s" "int idx"
312.Xc
313.It Xo
314.Ft int
315.Fo SSL_CTX_get_ex_new_index
316.Fa "long argl"
317.Fa "void *argp"
318.Fa "CRYPTO_EX_new *new_func"
319.Fa "CRYPTO_EX_dup *dup_func"
320.Fa "CRYPTO_EX_free *free_func"
321.Fc
322.Xc
323.It Xo
324.Ft void
325.Fo "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))"
326.Fa "SSL *ssl"
327.Fa "int cb"
328.Fa "int ret"
329.Fc
330.Xc
331.It Xo
332.Ft int
333.Fn SSL_CTX_get_quiet_shutdown "const SSL_CTX *ctx"
334.Xc
335.It Xo
336.Ft int
337.Fn SSL_CTX_get_session_cache_mode "SSL_CTX *ctx"
338.Xc
339.It Xo
340.Ft long
341.Fn SSL_CTX_get_timeout "const SSL_CTX *ctx"
342.Xc
343.It Xo
344.Ft int
345.Fo "(*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))"
346.Fa "int ok"
347.Fa "X509_STORE_CTX *ctx"
348.Fc
349.Xc
350.It Xo
351.Ft int
352.Fn SSL_CTX_get_verify_mode "SSL_CTX *ctx"
353.Xc
354.It Xo
355.Ft int
356.Fn SSL_CTX_load_verify_locations "SSL_CTX *ctx" "char *CAfile" "char *CApath"
357.Xc
358.It Xo
359.Ft long
360.Fn SSL_CTX_need_tmp_RSA "SSL_CTX *ctx"
361.Xc
362.It Xo
363.Ft SSL_CTX *
364.Fn SSL_CTX_new "const SSL_METHOD *meth"
365.Xc
366.It Xo
367.Ft int
368.Fn SSL_CTX_remove_session "SSL_CTX *ctx" "SSL_SESSION *c"
369.Xc
370.It Xo
371.Ft int
372.Fn SSL_CTX_sess_accept "SSL_CTX *ctx"
373.Xc
374.It Xo
375.Ft int
376.Fn SSL_CTX_sess_accept_good "SSL_CTX *ctx"
377.Xc
378.It Xo
379.Ft int
380.Fn SSL_CTX_sess_accept_renegotiate "SSL_CTX *ctx"
381.Xc
382.It Xo
383.Ft int
384.Fn SSL_CTX_sess_cache_full "SSL_CTX *ctx"
385.Xc
386.It Xo
387.Ft int
388.Fn SSL_CTX_sess_cb_hits "SSL_CTX *ctx"
389.Xc
390.It Xo
391.Ft int
392.Fn SSL_CTX_sess_connect "SSL_CTX *ctx"
393.Xc
394.It Xo
395.Ft int
396.Fn SSL_CTX_sess_connect_good "SSL_CTX *ctx"
397.Xc
398.It Xo
399.Ft int
400.Fn SSL_CTX_sess_connect_renegotiate "SSL_CTX *ctx"
401.Xc
402.It Xo
403.Ft int
404.Fn SSL_CTX_sess_get_cache_size "SSL_CTX *ctx"
405.Xc
406.It Xo
407.Ft SSL_SESSION *
408.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))"
409.Fa "SSL *ssl"
410.Fa "unsigned char *data"
411.Fa "int len"
412.Fa "int *copy"
413.Fc
414.Xc
415.It Xo
416.Ft int
417.Fn "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" "SSL *ssl" "SSL_SESSION *sess"
418.Xc
419.It Xo
420.Ft void
421.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))"
422.Fa "SSL_CTX *ctx"
423.Fa "SSL_SESSION *sess"
424.Fc
425.Xc
426.It Xo
427.Ft int
428.Fn SSL_CTX_sess_hits "SSL_CTX *ctx"
429.Xc
430.It Xo
431.Ft int
432.Fn SSL_CTX_sess_misses "SSL_CTX *ctx"
433.Xc
434.It Xo
435.Ft int
436.Fn SSL_CTX_sess_number "SSL_CTX *ctx"
437.Xc
438.It Xo
439.Ft void
440.Fn SSL_CTX_sess_set_cache_size "SSL_CTX *ctx" "long t"
441.Xc
442.It Xo
443.Ft void
444.Fo SSL_CTX_sess_set_get_cb
445.Fa "SSL_CTX *ctx"
446.Fa "SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)"
447.Fc
448.Xc
449.It Xo
450.Ft void
451.Fo SSL_CTX_sess_set_new_cb
452.Fa "SSL_CTX *ctx"
453.Fa "int (*cb)(SSL *ssl, SSL_SESSION *sess)"
454.Fc
455.Xc
456.It Xo
457.Ft void
458.Fo SSL_CTX_sess_set_remove_cb
459.Fa "SSL_CTX *ctx"
460.Fa "void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)"
461.Fc
462.Xc
463.It Xo
464.Ft int
465.Fn SSL_CTX_sess_timeouts "SSL_CTX *ctx"
466.Xc
467.It Xo
468.Ft LHASH *
469.Fn SSL_CTX_sessions "SSL_CTX *ctx"
470.Xc
471.It Xo
472.Ft void
473.Fn SSL_CTX_set_app_data "SSL_CTX *ctx" "void *arg"
474.Xc
475.It Xo
476.Ft void
477.Fn SSL_CTX_set_cert_store "SSL_CTX *ctx" "X509_STORE *cs"
478.Xc
479.It Xo
480.Ft void
481.Fn SSL_CTX_set_cert_verify_cb "SSL_CTX *ctx" "int (*cb)()" "char *arg"
482.Xc
483.It Xo
484.Ft int
485.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "char *str"
486.Xc
487.It Xo
488.Ft void
489.Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK *list"
490.Xc
491.It Xo
492.Ft void
493.Fo SSL_CTX_set_client_cert_cb
494.Fa "SSL_CTX *ctx"
495.Fa "int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)"
496.Fc
497.Xc
498.It Xo
499.Ft void
500.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb"
501.Xc
502.It Xo
503.Ft void
504.Fn SSL_CTX_set_default_read_ahead "SSL_CTX *ctx" "int m"
505.Xc
506.It Xo
507.Ft int
508.Fn SSL_CTX_set_default_verify_paths "SSL_CTX *ctx"
509.Xc
510.It Xo
511.Ft int
512.Fn SSL_CTX_set_ex_data "SSL_CTX *s" "int idx" "char *arg"
513.Xc
514.It Xo
515.Ft void
516.Fo SSL_CTX_set_info_callback
517.Fa "SSL_CTX *ctx"
518.Fa "void (*cb)(SSL *ssl, int cb, int ret)"
519.Fc
520.Xc
521.It Xo
522.Ft void
523.Fo SSL_CTX_set_msg_callback
524.Fa "SSL_CTX *ctx"
525.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, \
526size_t len, SSL *ssl, void *arg)"
527.Fc
528.Xc
529.It Xo
530.Ft void
531.Fn SSL_CTX_set_msg_callback_arg "SSL_CTX *ctx" "void *arg"
532.Xc
533.It Xo
534.Ft void
535.Fn SSL_CTX_set_options "SSL_CTX *ctx" "unsigned long op"
536.Xc
537.It Xo
538.Ft void
539.Fn SSL_CTX_set_quiet_shutdown "SSL_CTX *ctx" "int mode"
540.Xc
541.It Xo
542.Ft void
543.Fn SSL_CTX_set_session_cache_mode "SSL_CTX *ctx" "int mode"
544.Xc
545.It Xo
546.Ft int
547.Fn SSL_CTX_set_ssl_version "SSL_CTX *ctx" "const SSL_METHOD *meth"
548.Xc
549.It Xo
550.Ft void
551.Fn SSL_CTX_set_timeout "SSL_CTX *ctx" "long t"
552.Xc
553.It Xo
554.Ft long
555.Fn SSL_CTX_set_tmp_dh "SSL_CTX* ctx" "DH *dh"
556.Xc
557.It Xo
558.Ft long
559.Fn SSL_CTX_set_tmp_dh_callback "SSL_CTX *ctx" "DH *(*cb)(void)"
560.Xc
561.It Xo
562.Ft long
563.Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa"
564.Xc
565.It Xo
566.Fn SSL_CTX_set_tmp_rsa_callback
567.Xc
568.Ft long
569.Fo SSL_CTX_set_tmp_rsa_callback
570.Fa "SSL_CTX *ctx"
571.Fa "RSA *(*cb)(SSL *ssl, int export, int keylength)"
572.Fc
573.Pp
574Sets the callback which will be called when a temporary private key is
575required.
576The
577.Fa export
578flag will be set if the reason for needing a temp key is that an export
579ciphersuite is in use, in which case,
580.Fa keylength
581will contain the required keylength in bits.
582.\" XXX using what?
583Generate a key of appropriate size (using ???) and return it.
584.It Xo
585.Fn SSL_set_tmp_rsa_callback
586.Xc
587.Ft long
588.Fo SSL_set_tmp_rsa_callback
589.Fa "SSL *ssl"
590.Fa "RSA *(*cb)(SSL *ssl, int export, int keylength)"
591.Fc
592.Pp
593The same as
594.Fn SSL_CTX_set_tmp_rsa_callback ,
595except it operates on an
596.Vt SSL
597session instead of a context.
598.It Xo
599.Ft void
600.Fn SSL_CTX_set_verify "SSL_CTX *ctx" "int mode" "int (*cb)(void)"
601.Xc
602.It Xo
603.Ft int
604.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey"
605.Xc
606.It Xo
607.Ft int
608.Fo SSL_CTX_use_PrivateKey_ASN1
609.Fa "int type"
610.Fa "SSL_CTX *ctx"
611.Fa "unsigned char *d"
612.Fa "long len"
613.Fc
614.Xc
615.It Xo
616.Ft int
617.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "char *file" "int type"
618.Xc
619.It Xo
620.Ft int
621.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa"
622.Xc
623.It Xo
624.Ft int
625.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len"
626.Xc
627.It Xo
628.Ft int
629.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "char *file" "int type"
630.Xc
631.It Xo
632.Ft int
633.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x"
634.Xc
635.It Xo
636.Ft int
637.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d"
638.Xc
639.It Xo
640.Ft int
641.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "char *file" "int type"
642.Xc
643.It Xo
644.Ft void
645.Fo SSL_CTX_set_psk_client_callback
646.Fa "SSL_CTX *ctx"
647.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \
648unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)"
649.Fc
650.Xc
651.It Xo
652.Ft int
653.Fn SSL_CTX_use_psk_identity_hint "SSL_CTX *ctx" "const char *hint"
654.Xc
655.It Xo
656.Ft void
657.Fo SSL_CTX_set_psk_server_callback
658.Fa "SSL_CTX *ctx"
659.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, \
660unsigned char *psk, int max_psk_len)"
661.Fc
662.Xc
663.El
664.Ss DEALING WITH SESSIONS
665Here we document the various API functions which deal with the SSL/TLS sessions
666defined in the
667.Vt SSL_SESSION
668structures.
669.Bl -tag -width Ds
670.It Xo
671.Ft int
672.Fn SSL_SESSION_cmp "const SSL_SESSION *a" "const SSL_SESSION *b"
673.Xc
674.It Xo
675.Ft void
676.Fn SSL_SESSION_free "SSL_SESSION *ss"
677.Xc
678.It Xo
679.Ft char *
680.Fn SSL_SESSION_get_app_data "SSL_SESSION *s"
681.Xc
682.It Xo
683.Ft char *
684.Fn SSL_SESSION_get_ex_data "const SSL_SESSION *s" "int idx"
685.Xc
686.It Xo
687.Ft int
688.Fo SSL_SESSION_get_ex_new_index
689.Fa "long argl"
690.Fa "char *argp"
691.Fa "int (*new_func)(void)"
692.Fa "int (*dup_func)(void), void (*free_func)(void)"
693.Fc
694.Xc
695.It Xo
696.Ft long
697.Fn SSL_SESSION_get_time "const SSL_SESSION *s"
698.Xc
699.It Xo
700.Ft long
701.Fn SSL_SESSION_get_timeout "const SSL_SESSION *s"
702.Xc
703.It Xo
704.Ft unsigned long
705.Fn SSL_SESSION_hash "const SSL_SESSION *a"
706.Xc
707.It Xo
708.Ft SSL_SESSION *
709.Fn SSL_SESSION_new void
710.Xc
711.It Xo
712.Ft int
713.Fn SSL_SESSION_print "BIO *bp" "const SSL_SESSION *x"
714.Xc
715.It Xo
716.Ft int
717.Fn SSL_SESSION_print_fp "FILE *fp" "const SSL_SESSION *x"
718.Xc
719.It Xo
720.Ft void
721.Fn SSL_SESSION_set_app_data "SSL_SESSION *s" "char *a"
722.Xc
723.It Xo
724.Ft int
725.Fn SSL_SESSION_set_ex_data "SSL_SESSION *s" "int idx" "char *arg"
726.Xc
727.It Xo
728.Ft long
729.Fn SSL_SESSION_set_time "SSL_SESSION *s" "long t"
730.Xc
731.It Xo
732.Ft long
733.Fn SSL_SESSION_set_timeout "SSL_SESSION *s" "long t"
734.Xc
735.El
736.Ss DEALING WITH CONNECTIONS
737Here we document the various API functions which deal with the SSL/TLS
738connection defined in the
739.Vt SSL
740structure.
741.Bl -tag -width Ds
742.It Xo
743.Ft int
744.Fn SSL_accept "SSL *ssl"
745.Xc
746.It Xo
747.Ft int
748.Fn SSL_add_dir_cert_subjects_to_stack "STACK *stack" "const char *dir"
749.Xc
750.It Xo
751.Ft int
752.Fn SSL_add_file_cert_subjects_to_stack "STACK *stack" "const char *file"
753.Xc
754.It Xo
755.Ft int
756.Fn SSL_add_client_CA "SSL *ssl" "X509 *x"
757.Xc
758.It Xo
759.Ft char *
760.Fn SSL_alert_desc_string "int value"
761.Xc
762.It Xo
763.Ft char *
764.Fn SSL_alert_desc_string_long "int value"
765.Xc
766.It Xo
767.Ft char *
768.Fn SSL_alert_type_string "int value"
769.Xc
770.It Xo
771.Ft char *
772.Fn SSL_alert_type_string_long "int value"
773.Xc
774.It Xo
775.Ft int
776.Fn SSL_check_private_key "const SSL *ssl"
777.Xc
778.It Xo
779.Ft void
780.Fn SSL_clear "SSL *ssl"
781.Xc
782.It Xo
783.Ft long
784.Fn SSL_clear_num_renegotiations "SSL *ssl"
785.Xc
786.It Xo
787.Ft int
788.Fn SSL_connect "SSL *ssl"
789.Xc
790.It Xo
791.Ft void
792.Fn SSL_copy_session_id "SSL *t" "const SSL *f"
793.Xc
794.It Xo
795.Ft long
796.Fn SSL_ctrl "SSL *ssl" "int cmd" "long larg" "char *parg"
797.Xc
798.It Xo
799.Ft int
800.Fn SSL_do_handshake "SSL *ssl"
801.Xc
802.It Xo
803.Ft SSL *
804.Fn SSL_dup "SSL *ssl"
805.Xc
806.It Xo
807.Ft STACK *
808.Fn SSL_dup_CA_list "STACK *sk"
809.Xc
810.It Xo
811.Ft void
812.Fn SSL_free "SSL *ssl"
813.Xc
814.It Xo
815.Ft SSL_CTX *
816.Fn SSL_get_SSL_CTX "const SSL *ssl"
817.Xc
818.It Xo
819.Ft char *
820.Fn SSL_get_app_data "SSL *ssl"
821.Xc
822.It Xo
823.Ft X509 *
824.Fn SSL_get_certificate "const SSL *ssl"
825.Xc
826.It Xo
827.Ft const char *
828.Fn SSL_get_cipher "const SSL *ssl"
829.Xc
830.It Xo
831.Ft int
832.Fn SSL_get_cipher_bits "const SSL *ssl" "int *alg_bits"
833.Xc
834.It Xo
835.Ft char *
836.Fn SSL_get_cipher_list "const SSL *ssl" "int n"
837.Xc
838.It Xo
839.Ft char *
840.Fn SSL_get_cipher_name "const SSL *ssl"
841.Xc
842.It Xo
843.Ft char *
844.Fn SSL_get_cipher_version "const SSL *ssl"
845.Xc
846.It Xo
847.Ft STACK *
848.Fn SSL_get_ciphers "const SSL *ssl"
849.Xc
850.It Xo
851.Ft STACK *
852.Fn SSL_get_client_CA_list "const SSL *ssl"
853.Xc
854.It Xo
855.Ft SSL_CIPHER *
856.Fn SSL_get_current_cipher "SSL *ssl"
857.Xc
858.It Xo
859.Ft long
860.Fn SSL_get_default_timeout "const SSL *ssl"
861.Xc
862.It Xo
863.Ft int
864.Fn SSL_get_error "const SSL *ssl" "int i"
865.Xc
866.It Xo
867.Ft char *
868.Fn SSL_get_ex_data "const SSL *ssl" "int idx"
869.Xc
870.It Xo
871.Ft int
872.Fn SSL_get_ex_data_X509_STORE_CTX_idx void
873.Xc
874.It Xo
875.Ft int
876.Fo SSL_get_ex_new_index
877.Fa "long argl"
878.Fa "char *argp"
879.Fa "int (*new_func)(void)"
880.Fa "int (*dup_func)(void)"
881.Fa "void (*free_func)(void)"
882.Fc
883.Xc
884.It Xo
885.Ft int
886.Fn SSL_get_fd "const SSL *ssl"
887.Xc
888.It Xo
889.Ft void
890.Fn "(*SSL_get_info_callback(const SSL *ssl))"
891.Xc
892.It Xo
893.Ft STACK *
894.Fn SSL_get_peer_cert_chain "const SSL *ssl"
895.Xc
896.It Xo
897.Ft X509 *
898.Fn SSL_get_peer_certificate "const SSL *ssl"
899.Xc
900.It Xo
901.Ft EVP_PKEY *
902.Fn SSL_get_privatekey "SSL *ssl"
903.Xc
904.It Xo
905.Ft int
906.Fn SSL_get_quiet_shutdown "const SSL *ssl"
907.Xc
908.It Xo
909.Ft BIO *
910.Fn SSL_get_rbio "const SSL *ssl"
911.Xc
912.It Xo
913.Ft int
914.Fn SSL_get_read_ahead "const SSL *ssl"
915.Xc
916.It Xo
917.Ft SSL_SESSION *
918.Fn SSL_get_session "const SSL *ssl"
919.Xc
920.It Xo
921.Ft char *
922.Fn SSL_get_shared_ciphers "const SSL *ssl" "char *buf" "int len"
923.Xc
924.It Xo
925.Ft int
926.Fn SSL_get_shutdown "const SSL *ssl"
927.Xc
928.It Xo
929.Ft const SSL_METHOD *
930.Fn SSL_get_ssl_method "SSL *ssl"
931.Xc
932.It Xo
933.Ft int
934.Fn SSL_get_state "const SSL *ssl"
935.Xc
936.It Xo
937.Ft long
938.Fn SSL_get_time "const SSL *ssl"
939.Xc
940.It Xo
941.Ft long
942.Fn SSL_get_timeout "const SSL *ssl"
943.Xc
944.It Xo
945.Ft int
946.Fn "(*SSL_get_verify_callback(const SSL *ssl))" int "X509_STORE_CTX *"
947.Xc
948.It Xo
949.Ft int
950.Fn SSL_get_verify_mode "const SSL *ssl"
951.Xc
952.It Xo
953.Ft long
954.Fn SSL_get_verify_result "const SSL *ssl"
955.Xc
956.It Xo
957.Ft char *
958.Fn SSL_get_version "const SSL *ssl"
959.Xc
960.It Xo
961.Ft BIO *
962.Fn SSL_get_wbio "const SSL *ssl"
963.Xc
964.It Xo
965.Ft int
966.Fn SSL_in_accept_init "SSL *ssl"
967.Xc
968.It Xo
969.Ft int
970.Fn SSL_in_before "SSL *ssl"
971.Xc
972.It Xo
973.Ft int
974.Fn SSL_in_connect_init "SSL *ssl"
975.Xc
976.It Xo
977.Ft int
978.Fn SSL_in_init "SSL *ssl"
979.Xc
980.It Xo
981.Ft int
982.Fn SSL_is_init_finished "SSL *ssl"
983.Xc
984.It Xo
985.Ft STACK *
986.Fn SSL_load_client_CA_file "char *file"
987.Xc
988.It Xo
989.Ft void
990.Fn SSL_load_error_strings "void"
991.Xc
992.It Xo
993.Ft SSL *
994.Fn SSL_new "SSL_CTX *ctx"
995.Xc
996.It Xo
997.Ft long
998.Fn SSL_num_renegotiations "SSL *ssl"
999.Xc
1000.It Xo
1001.Ft int
1002.Fn SSL_peek "SSL *ssl" "void *buf" "int num"
1003.Xc
1004.It Xo
1005.Ft int
1006.Fn SSL_pending "const SSL *ssl"
1007.Xc
1008.It Xo
1009.Ft int
1010.Fn SSL_read "SSL *ssl" "void *buf" "int num"
1011.Xc
1012.It Xo
1013.Ft int
1014.Fn SSL_renegotiate "SSL *ssl"
1015.Xc
1016.It Xo
1017.Ft char *
1018.Fn SSL_rstate_string "SSL *ssl"
1019.Xc
1020.It Xo
1021.Ft char *
1022.Fn SSL_rstate_string_long "SSL *ssl"
1023.Xc
1024.It Xo
1025.Ft long
1026.Fn SSL_session_reused "SSL *ssl"
1027.Xc
1028.It Xo
1029.Ft void
1030.Fn SSL_set_accept_state "SSL *ssl"
1031.Xc
1032.It Xo
1033.Ft void
1034.Fn SSL_set_app_data "SSL *ssl" "char *arg"
1035.Xc
1036.It Xo
1037.Ft void
1038.Fn SSL_set_bio "SSL *ssl" "BIO *rbio" "BIO *wbio"
1039.Xc
1040.It Xo
1041.Ft int
1042.Fn SSL_set_cipher_list "SSL *ssl" "char *str"
1043.Xc
1044.It Xo
1045.Ft void
1046.Fn SSL_set_client_CA_list "SSL *ssl" "STACK *list"
1047.Xc
1048.It Xo
1049.Ft void
1050.Fn SSL_set_connect_state "SSL *ssl"
1051.Xc
1052.It Xo
1053.Ft int
1054.Fn SSL_set_ex_data "SSL *ssl" "int idx" "char *arg"
1055.Xc
1056.It Xo
1057.Ft int
1058.Fn SSL_set_fd "SSL *ssl" "int fd"
1059.Xc
1060.It Xo
1061.Ft void
1062.Fn SSL_set_info_callback "SSL *ssl" "void (*cb)(void)"
1063.Xc
1064.It Xo
1065.Ft void
1066.Fo SSL_set_msg_callback
1067.Fa "SSL *ctx"
1068.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, \
1069size_t len, SSL *ssl, void *arg)"
1070.Fc
1071.Xc
1072.It Xo
1073.Ft void
1074.Fn SSL_set_msg_callback_arg "SSL *ctx" "void *arg"
1075.Xc
1076.It Xo
1077.Ft void
1078.Fn SSL_set_options "SSL *ssl" "unsigned long op"
1079.Xc
1080.It Xo
1081.Ft void
1082.Fn SSL_set_quiet_shutdown "SSL *ssl" "int mode"
1083.Xc
1084.It Xo
1085.Ft void
1086.Fn SSL_set_read_ahead "SSL *ssl" "int yes"
1087.Xc
1088.It Xo
1089.Ft int
1090.Fn SSL_set_rfd "SSL *ssl" "int fd"
1091.Xc
1092.It Xo
1093.Ft int
1094.Fn SSL_set_session "SSL *ssl" "SSL_SESSION *session"
1095.Xc
1096.It Xo
1097.Ft void
1098.Fn SSL_set_shutdown "SSL *ssl" "int mode"
1099.Xc
1100.It Xo
1101.Ft int
1102.Fn SSL_set_ssl_method "SSL *ssl" "const SSL_METHOD *meth"
1103.Xc
1104.It Xo
1105.Ft void
1106.Fn SSL_set_time "SSL *ssl" "long t"
1107.Xc
1108.It Xo
1109.Ft void
1110.Fn SSL_set_timeout "SSL *ssl" "long t"
1111.Xc
1112.It Xo
1113.Ft void
1114.Fn SSL_set_verify "SSL *ssl" "int mode" "int (*callback)(void)"
1115.Xc
1116.It Xo
1117.Ft void
1118.Fn SSL_set_verify_result "SSL *ssl" "long arg"
1119.Xc
1120.It Xo
1121.Ft int
1122.Fn SSL_set_wfd "SSL *ssl" "int fd"
1123.Xc
1124.It Xo
1125.Ft int
1126.Fn SSL_shutdown "SSL *ssl"
1127.Xc
1128.It Xo
1129.Ft int
1130.Fn SSL_state "const SSL *ssl"
1131.Xc
1132.It Xo
1133.Ft char *
1134.Fn SSL_state_string "const SSL *ssl"
1135.Xc
1136.It Xo
1137.Ft char *
1138.Fn SSL_state_string_long "const SSL *ssl"
1139.Xc
1140.It Xo
1141.Ft long
1142.Fn SSL_total_renegotiations "SSL *ssl"
1143.Xc
1144.It Xo
1145.Ft int
1146.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey"
1147.Xc
1148.It Xo
1149.Ft int
1150.Fn SSL_use_PrivateKey_ASN1 "int type" "SSL *ssl" "unsigned char *d" "long len"
1151.Xc
1152.It Xo
1153.Ft int
1154.Fn SSL_use_PrivateKey_file "SSL *ssl" "char *file" "int type"
1155.Xc
1156.It Xo
1157.Ft int
1158.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa"
1159.Xc
1160.It Xo
1161.Ft int
1162.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len"
1163.Xc
1164.It Xo
1165.Ft int
1166.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "char *file" "int type"
1167.Xc
1168.It Xo
1169.Ft int
1170.Fn SSL_use_certificate "SSL *ssl" "X509 *x"
1171.Xc
1172.It Xo
1173.Ft int
1174.Fn SSL_use_certificate_ASN1 "SSL *ssl" "int len" "unsigned char *d"
1175.Xc
1176.It Xo
1177.Ft int
1178.Fn SSL_use_certificate_file "SSL *ssl" "char *file" "int type"
1179.Xc
1180.It Xo
1181.Ft int
1182.Fn SSL_version "const SSL *ssl"
1183.Xc
1184.It Xo
1185.Ft int
1186.Fn SSL_want "const SSL *ssl"
1187.Xc
1188.It Xo
1189.Ft int
1190.Fn SSL_want_nothing "const SSL *ssl"
1191.Xc
1192.It Xo
1193.Ft int
1194.Fn SSL_want_read "const SSL *ssl"
1195.Xc
1196.It Xo
1197.Ft int
1198.Fn SSL_want_write "const SSL *ssl"
1199.Xc
1200.It Xo
1201.Ft int
1202.Fn SSL_want_x509_lookup "const SSL *ssl"
1203.Xc
1204.It Xo
1205.Ft int
1206.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
1207.Xc
1208.It Xo
1209.Ft void
1210.Fo SSL_set_psk_client_callback
1211.Fa "SSL *ssl"
1212.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \
1213unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)"
1214.Fc
1215.Xc
1216.It Xo
1217.Ft int
1218.Fn SSL_use_psk_identity_hint "SSL *ssl" "const char *hint"
1219.Xc
1220.It Xo
1221.Ft void
1222.Fo SSL_set_psk_server_callback
1223.Fa "SSL *ssl"
1224.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, \
1225unsigned char *psk, int max_psk_len)"
1226.Fc
1227.Xc
1228.It Xo
1229.Ft const char *
1230.Fn SSL_get_psk_identity_hint "SSL *ssl"
1231.Xc
1232.It Xo
1233.Ft const char *
1234.Fn SSL_get_psk_identity "SSL *ssl"
1235.Xc
1236.El
1237.Sh SEE ALSO
1238.Xr openssl 1 ,
1239.Xr crypto 3 ,
1240.Xr d2i_SSL_SESSION 3 ,
1241.Xr SSL_accept 3 ,
1242.Xr SSL_alert_type_string 3 ,
1243.Xr SSL_CIPHER_get_name 3 ,
1244.Xr SSL_clear 3 ,
1245.Xr SSL_COMP_add_compression_method 3 ,
1246.Xr SSL_connect 3 ,
1247.Xr SSL_CTX_add_extra_chain_cert 3 ,
1248.Xr SSL_CTX_add_session 3 ,
1249.Xr SSL_CTX_ctrl 3 ,
1250.Xr SSL_CTX_flush_sessions 3 ,
1251.Xr SSL_CTX_get_ex_new_index 3 ,
1252.Xr SSL_CTX_get_verify_mode 3 ,
1253.Xr SSL_CTX_load_verify_locations 3 ,
1254.Xr SSL_CTX_new 3 ,
1255.Xr SSL_CTX_sess_number 3 ,
1256.Xr SSL_CTX_sess_set_cache_size 3 ,
1257.Xr SSL_CTX_sess_set_get_cb 3 ,
1258.Xr SSL_CTX_sessions 3 ,
1259.Xr SSL_CTX_set_cert_store 3 ,
1260.Xr SSL_CTX_set_cert_verify_callback 3 ,
1261.Xr SSL_CTX_set_cipher_list 3 ,
1262.Xr SSL_CTX_set_client_CA_list 3 ,
1263.Xr SSL_CTX_set_client_cert_cb 3 ,
1264.Xr SSL_CTX_set_default_passwd_cb 3 ,
1265.Xr SSL_CTX_set_generate_session_id 3 ,
1266.Xr SSL_CTX_set_info_callback 3 ,
1267.Xr SSL_CTX_set_max_cert_list 3 ,
1268.Xr SSL_CTX_set_mode 3 ,
1269.Xr SSL_CTX_set_msg_callback 3 ,
1270.Xr SSL_CTX_set_options 3 ,
1271.Xr SSL_CTX_set_psk_client_callback 3 ,
1272.Xr SSL_CTX_set_quiet_shutdown 3 ,
1273.Xr SSL_CTX_set_session_cache_mode 3 ,
1274.Xr SSL_CTX_set_session_id_context 3 ,
1275.Xr SSL_CTX_set_ssl_version 3 ,
1276.Xr SSL_CTX_set_timeout 3 ,
1277.Xr SSL_CTX_set_tmp_dh_callback 3 ,
1278.Xr SSL_CTX_set_tmp_rsa_callback 3 ,
1279.Xr SSL_CTX_set_verify 3 ,
1280.Xr SSL_CTX_use_certificate 3 ,
1281.Xr SSL_CTX_use_psk_identity_hint 3 ,
1282.Xr SSL_do_handshake 3 ,
1283.Xr SSL_get_ciphers 3 ,
1284.Xr SSL_get_client_CA_list 3 ,
1285.Xr SSL_get_default_timeout 3 ,
1286.Xr SSL_get_error 3 ,
1287.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 ,
1288.Xr SSL_get_ex_new_index 3 ,
1289.Xr SSL_get_fd 3 ,
1290.Xr SSL_get_peer_cert_chain 3 ,
1291.Xr SSL_get_psk_identity 3 ,
1292.Xr SSL_get_rbio 3 ,
1293.Xr SSL_get_session 3 ,
1294.Xr SSL_get_SSL_CTX 3 ,
1295.Xr SSL_get_verify_result 3 ,
1296.Xr SSL_get_version 3 ,
1297.Xr SSL_library_init 3 ,
1298.Xr SSL_load_client_CA_file 3 ,
1299.Xr SSL_new 3 ,
1300.Xr SSL_pending 3 ,
1301.Xr SSL_read 3 ,
1302.Xr SSL_rstate_string 3 ,
1303.Xr SSL_SESSION_free 3 ,
1304.Xr SSL_SESSION_get_ex_new_index 3 ,
1305.Xr SSL_SESSION_get_time 3 ,
1306.Xr SSL_session_reused 3 ,
1307.Xr SSL_set_bio 3 ,
1308.Xr SSL_set_connect_state 3 ,
1309.Xr SSL_set_fd 3 ,
1310.Xr SSL_set_session 3 ,
1311.Xr SSL_set_shutdown 3 ,
1312.Xr SSL_shutdown 3 ,
1313.Xr SSL_state_string 3 ,
1314.Xr SSL_want 3 ,
1315.Xr SSL_write 3
1316.Sh HISTORY
1317The
1318.Nm
1319document appeared in OpenSSL 0.9.2.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-10-27 14:09:35 +0000