1*6e76a016Sjsing.\" $OpenBSD: tls_client.3,v 1.4 2017/08/12 03:41:48 jsing Exp $ 2e690d60fSschwarze.\" 3e690d60fSschwarze.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> 4e690d60fSschwarze.\" 5e690d60fSschwarze.\" Permission to use, copy, modify, and distribute this software for any 6e690d60fSschwarze.\" purpose with or without fee is hereby granted, provided that the above 7e690d60fSschwarze.\" copyright notice and this permission notice appear in all copies. 8e690d60fSschwarze.\" 9e690d60fSschwarze.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10e690d60fSschwarze.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11e690d60fSschwarze.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12e690d60fSschwarze.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13e690d60fSschwarze.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14e690d60fSschwarze.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15e690d60fSschwarze.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16e690d60fSschwarze.\" 17*6e76a016Sjsing.Dd $Mdocdate: August 12 2017 $ 18e690d60fSschwarze.Dt TLS_CLIENT 3 19e690d60fSschwarze.Os 20e690d60fSschwarze.Sh NAME 21e690d60fSschwarze.Nm tls_client , 22e690d60fSschwarze.Nm tls_server , 23e690d60fSschwarze.Nm tls_configure , 24*6e76a016Sjsing.Nm tls_reset , 25e690d60fSschwarze.Nm tls_free 26e690d60fSschwarze.Nd configure a TLS connection 27e690d60fSschwarze.Sh SYNOPSIS 28e690d60fSschwarze.In tls.h 29e690d60fSschwarze.Ft struct tls * 30e690d60fSschwarze.Fn tls_client void 31e690d60fSschwarze.Ft struct tls * 32e690d60fSschwarze.Fn tls_server void 33e690d60fSschwarze.Ft int 34e690d60fSschwarze.Fo tls_configure 35e690d60fSschwarze.Fa "struct tls *ctx" 36e690d60fSschwarze.Fa "struct tls_config *config" 37e690d60fSschwarze.Fc 38e690d60fSschwarze.Ft void 39e690d60fSschwarze.Fn tls_free "struct tls *ctx" 40*6e76a016Sjsing.Ft void 41*6e76a016Sjsing.Fn tls_reset "struct tls *ctx" 42e690d60fSschwarze.Sh DESCRIPTION 43e690d60fSschwarzeA TLS connection is represented as a 44e690d60fSschwarze.Vt struct tls 45e690d60fSschwarzeobject called a 46e690d60fSschwarze.Dq context . 47e690d60fSschwarzeA new context is created by either the 48e690d60fSschwarze.Fn tls_client 49e690d60fSschwarzeor 50e690d60fSschwarze.Fn tls_server 51e690d60fSschwarzefunctions. 52e690d60fSschwarze.Fn tls_client 53e690d60fSschwarzeis used in TLS client programs, 54e690d60fSschwarze.Fn tls_server 55e690d60fSschwarzein TLS server programs. 56e690d60fSschwarze.Pp 57e690d60fSschwarzeThe context can then be configured with the function 58e690d60fSschwarze.Fn tls_configure . 59e690d60fSschwarzeThe same 60e690d60fSschwarze.Vt tls_config 61e690d60fSschwarzeobject can be used to configure multiple contexts. 62e690d60fSschwarze.Pp 63e690d60fSschwarzeAfter configuration, 64e690d60fSschwarze.Xr tls_connect 3 65e690d60fSschwarzecan be called on objects created with 66e690d60fSschwarze.Fn tls_client , 67e690d60fSschwarzeand 68e690d60fSschwarze.Xr tls_accept_socket 3 69e690d60fSschwarzeon objects created with 70e690d60fSschwarze.Fn tls_server . 71e690d60fSschwarze.Pp 72e690d60fSschwarzeAfter use, a TLS context should be closed with 73e690d60fSschwarze.Xr tls_close 3 , 74e690d60fSschwarzeand then freed by calling 75e690d60fSschwarze.Fn tls_free . 76dbe397f8SschwarzeIf 77dbe397f8Sschwarze.Fn tls_free 78dbe397f8Sschwarzeis called with an argument of 79dbe397f8Sschwarze.Dv NULL , 80dbe397f8Sschwarzeno action occurs. 81*6e76a016Sjsing.Pp 82*6e76a016SjsingA TLS context can be reset by calling 83*6e76a016Sjsing.Fn tls_reset , 84*6e76a016Sjsingallowing for it to be reused. 85*6e76a016SjsingThis is essentially equivalent to calling 86*6e76a016Sjsing.Fn tls_free , 87*6e76a016Sjsingfollowed by a call to the same function that was used to originally allocate 88*6e76a016Sjsingthe TLS context. 89e690d60fSschwarze.Sh RETURN VALUES 90e690d60fSschwarze.Fn tls_client 91e690d60fSschwarzeand 92e690d60fSschwarze.Fn tls_server 93e690d60fSschwarzereturn 94e690d60fSschwarze.Dv NULL 95e690d60fSschwarzeon error or an out of memory condition. 96e690d60fSschwarze.Pp 97e690d60fSschwarze.Fn tls_configure 98e690d60fSschwarzereturns 0 on success or -1 on error. 99e690d60fSschwarze.Sh SEE ALSO 100e690d60fSschwarze.Xr tls_accept_socket 3 , 101e690d60fSschwarze.Xr tls_config_new 3 , 102e690d60fSschwarze.Xr tls_connect 3 , 103e690d60fSschwarze.Xr tls_init 3 1048b02f64eSschwarze.Sh HISTORY 1058b02f64eSschwarzeThese functions appeared in 1068b02f64eSschwarze.Ox 5.6 1078b02f64eSschwarzeand got their final names in 1088b02f64eSschwarze.Ox 5.7 . 1098b02f64eSschwarze.Sh AUTHORS 1108b02f64eSschwarze.An Joel Sing Aq Mt jsing@openbsd.org 111