secure/lib/libssl/man/SSL_CTX_set_client_CA_list.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH SSL_CTX_set_client_CA_list 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
 192 SSL_add_client_CA \- set list of CAs sent to the client when requesting a
 193 client certificate
 194 .SH "SYNOPSIS"
 195 .PP
 196 .Vb 6
 197 \& #include <openssl/ssl.h>
 198 \&
 199 \& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
 200 \& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
 201 \& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
 202 \& int SSL_add_client_CA(SSL *ssl, X509 *cacert);
 203 .Ve
 204 .SH "DESCRIPTION"
 205 \fISSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
 206 requesting a client certificate for \fBctx\fR.
 207 .PP
 208 \fISSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
 209 requesting a client certificate for the chosen \fBssl\fR, overriding the
 210 setting valid for \fBssl\fR's SSL_CTX object.
 211 .PP
 212 \fISSL_CTX_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the
 213 list of CAs sent to the client when requesting a client certificate for
 214 \fBctx\fR.
 215 .PP
 216 \fISSL_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the
 217 list of CAs sent to the client when requesting a client certificate for
 218 the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's SSL_CTX object.
 219 .SH "NOTES"
 220 When a TLS/SSL server requests a client certificate (see
 221 \fBSSL_CTX_set_verify_options()\fR), it sends a list of CAs, for which
 222 it will accept certificates, to the client.
 223 .PP
 224 This list must explicitly be set using \fISSL_CTX_set_client_CA_list()\fR for
 225 \fBctx\fR and \fISSL_set_client_CA_list()\fR for the specific \fBssl\fR. The list
 226 specified overrides the previous setting. The CAs listed do not become
 227 trusted (\fBlist\fR only contains the names, not the complete certificates); use
 228 SSL_CTX_load_verify_locations(3)
 229 to additionally load them for verification.
 230 .PP
 231 If the list of acceptable CAs is compiled in a file, the
 232 SSL_load_client_CA_file(3)
 233 function can be used to help importing the necessary data.
 234 .PP
 235 \fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR can be used to add additional
 236 items the list of client CAs. If no list was specified before using
 237 \fISSL_CTX_set_client_CA_list()\fR or \fISSL_set_client_CA_list()\fR, a new client
 238 CA list for \fBctx\fR or \fBssl\fR (as appropriate) is opened.
 239 .PP
 240 These functions are only useful for TLS/SSL servers.
 241 .SH "RETURN VALUES"
 242 \fISSL_CTX_set_client_CA_list()\fR and \fISSL_set_client_CA_list()\fR do not return
 243 diagnostic information.
 244 .PP
 245 \fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR have the following return
 246 values:
 247 .Ip "1" 4
 248 The operation succeeded.
 249 .Ip "0" 4
 250 A failure while manipulating the \fI\s-1STACK_OF\s0\fR\|(X509_NAME) object occurred or
 251 the X509_NAME could not be extracted from \fBcacert\fR. Check the error stack
 252 to find out the reason.
 253 .SH "EXAMPLES"
 254 Scan all certificates in \fBCAfile\fR and list them as acceptable CAs:
 255 .PP
 256 .Vb 1
 257 \&  SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
 258 .Ve
 259 .SH "SEE ALSO"
 260 ssl(3),
 261 SSL_get_client_CA_list(3),
 262 SSL_load_client_CA_file(3),
 263 SSL_CTX_load_verify_locations(3)
 264
 265 .rn }` ''
 266 .IX Title "SSL_CTX_set_client_CA_list 3"
 267 .IX Name "SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
 268 SSL_add_client_CA - set list of CAs sent to the client when requesting a
 269 client certificate"
 270
 271 .IX Header "NAME"
 272
 273 .IX Header "SYNOPSIS"
 274
 275 .IX Header "DESCRIPTION"
 276
 277 .IX Header "NOTES"
 278
 279 .IX Header "RETURN VALUES"
 280
 281 .IX Item "1"
 282
 283 .IX Item "0"
 284
 285 .IX Header "EXAMPLES"
 286
 287 .IX Header "SEE ALSO"
 288