Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_use_psk_identity_hint.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
01185282
PA
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
35'br\}
36.el\{\
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
41'br\}
42.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
47.\" If the F register is turned on, we'll generate index entries on stderr for
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
51.ie \nF \{\
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
54..
55. nr % 0
56. rr F
57.\}
58.el \{\
59. de IX
60..
61.\}
62.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
66.if n \{\
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
72.\}
73.if t \{\
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
79.\}
80. \" simple accents for nroff and troff
81.if n \{\
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
88.\}
89.if t \{\
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96.\}
97. \" troff and (daisy-wheel) nroff accents
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
107. \" corrections for vroff
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110. \" for low resolution devices (crt and lpr)
111.if \n(.H>23 .if \n(.V>19 \
112\{\
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
122.\}
123.rm #[ #] #H #V #F C
124.\" ========================================================================
125.\"
126.IX Title "SSL_CTX_use_psk_identity_hint 3"
e3261593 127.TH SSL_CTX_use_psk_identity_hint 3 "2012-01-04" "1.0.0f" "OpenSSL"
01185282
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
132.SH "NAME"
133SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
134SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback \- set PSK
135identity hint to use
136.SH "SYNOPSIS"
137.IX Header "SYNOPSIS"
138.Vb 1
139\& #include <openssl/ssl.h>
140\&
141\& int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
142\& int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
143\&
144\& void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
145\& unsigned int (*callback)(SSL *ssl, const char *identity,
146\& unsigned char *psk, int max_psk_len));
147\& void SSL_set_psk_server_callback(SSL *ssl,
148\& unsigned int (*callback)(SSL *ssl, const char *identity,
149\& unsigned char *psk, int max_psk_len));
150.Ve
151.SH "DESCRIPTION"
152.IX Header "DESCRIPTION"
153\&\fISSL_CTX_use_psk_identity_hint()\fR sets the given \fB\s-1NULL\s0\fR\-terminated \s-1PSK\s0
154identity hint \fBhint\fR to \s-1SSL\s0 context object
155\&\fBctx\fR. \fISSL_use_psk_identity_hint()\fR sets the given \fB\s-1NULL\s0\fR\-terminated
156\&\s-1PSK\s0 identity hint \fBhint\fR to \s-1SSL\s0 connection object \fBssl\fR. If \fBhint\fR
157is \fB\s-1NULL\s0\fR the current hint from \fBctx\fR or \fBssl\fR is deleted.
158.PP
159In the case where \s-1PSK\s0 identity hint is \fB\s-1NULL\s0\fR, the server
160does not send the ServerKeyExchange message to the client.
161.PP
162A server application must provide a callback function which is called
163when the server receives the ClientKeyExchange message from the
164client. The purpose of the callback function is to validate the
165received \s-1PSK\s0 identity and to fetch the pre-shared key used during the
166connection setup phase. The callback is set using functions
167\&\fISSL_CTX_set_psk_server_callback()\fR or
168\&\fISSL_set_psk_server_callback()\fR. The callback function is given the
169connection in parameter \fBssl\fR, \fB\s-1NULL\s0\fR\-terminated \s-1PSK\s0 identity sent
170by the client in parameter \fBidentity\fR, and a buffer \fBpsk\fR of length
171\&\fBmax_psk_len\fR bytes where the pre-shared key is to be stored.
172.SH "RETURN VALUES"
173.IX Header "RETURN VALUES"
174\&\fISSL_CTX_use_psk_identity_hint()\fR and \fISSL_use_psk_identity_hint()\fR return
1751 on success, 0 otherwise.
176.PP
177Return values from the server callback are interpreted as follows:
178.IP "> 0" 4
179.IX Item "> 0"
180\&\s-1PSK\s0 identity was found and the server callback has provided the \s-1PSK\s0
181successfully in parameter \fBpsk\fR. Return value is the length of
182\&\fBpsk\fR in bytes. It is an error to return a value greater than
183\&\fBmax_psk_len\fR.
184.Sp
185If the \s-1PSK\s0 identity was not found but the callback instructs the
186protocol to continue anyway, the callback must provide some random
187data to \fBpsk\fR and return the length of the random data, so the
188connection will fail with decryption_error before it will be finished
189completely.
190.IP "0" 4
191\&\s-1PSK\s0 identity was not found. An \*(L"unknown_psk_identity\*(R" alert message
192will be sent and the connection setup fails.
193.SH "POD ERRORS"
194.IX Header "POD ERRORS"
195Hey! \fBThe above document had some coding errors, which are explained below:\fR
196.IP "Around line 84:" 4
197.IX Item "Around line 84:"
198\&'=item' outside of any '=over'