lib/libcrypto/man/X509_STORE_load_locations.3

   1 .\"     $OpenBSD: X509_STORE_load_locations.3,v 1.2 2017/01/07 08:46:13 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@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: January 7 2017 $
  18 .Dt X509_STORE_LOAD_LOCATIONS 3
  19 .Os
  20 .Sh NAME
  21 .Nm X509_STORE_load_locations ,
  22 .Nm X509_STORE_set_default_paths
  23 .Nd configure files and directories used by a certificate store
  24 .Sh SYNOPSIS
  25 .In openssl/x509_vfy.h
  26 .Ft int
  27 .Fo X509_STORE_load_locations
  28 .Fa "X509_STORE *store"
  29 .Fa "const char *file"
  30 .Fa "const char *dirs"
  31 .Fc
  32 .Ft int
  33 .Fo X509_STORE_set_default_paths
  34 .Fa "X509_STORE *store"
  35 .Fc
  36 .Sh DESCRIPTION
  37 .Fn X509_STORE_load_locations
  38 instructs the
  39 .Fa store
  40 to use the PEM file
  41 .Fa file
  42 and all the PEM files in the directories
  43 contained in the colon-separated list
  44 .Fa dirs
  45 for looking up certificates, in addition to files and directories
  46 that are already configured.
  47 Directories already in use are not added again.
  48 If
  49 .Dv NULL
  50 is passed for
  51 .Fa file
  52 or
  53 .Fa dirs ,
  54 no new file or no new directories are added, respectively.
  55 .Pp
  56 .Fn X509_STORE_load_locations
  57 is identical to
  58 .Xr SSL_CTX_load_verify_locations 3
  59 except that it operates directly on an
  60 .Vt X509_STORE
  61 object, rather than on the store used by an SSL context.
  62 See that manual page for more information.
  63 .Pp
  64 .Fn X509_STORE_set_default_paths
  65 is similar except that it instructs the
  66 .Fa store
  67 to use the default PEM file and directory
  68 (as documented in
  69 .Sx FILES )
  70 in addition to what is already configured.
  71 It ignores errors that occur while trying to load the file or to
  72 add the directory, but it may still fail for other reasons, for
  73 example when out of memory while trying to allocate the required
  74 .Vt X509_LOOKUP
  75 objects.
  76 .Pp
  77 .Fn X509_STORE_set_default_paths
  78 is identical to
  79 .Xr SSL_CTX_set_default_verify_paths 3
  80 except that it operates directly on an
  81 .Vt X509_STORE
  82 object, rather than on the store used by an SSL context.
  83 See that manual page for more information.
  84 .Sh RETURN VALUES
  85 .Fn X509_STORE_load_locations
  86 returns 1 if all files and directories specified were successfully
  87 added.
  88 It returns 0 for failure.
  89 That can happen if adding the file failed, if adding any of the
  90 directories failed, or if both arguments were
  91 .Dv NULL .
  92 .Pp
  93 .Fn X509_STORE_set_default_paths
  94 returns 0 for some error conditions and 1 otherwise, not just for
  95 success, but also for various cases of failure.
  96 .Sh FILES
  97 .Bl -tag -width Ds
  98 .It Pa /etc/ssl/cert.pem
  99 default PEM file for
 100 .Fn X509_STORE_set_default_paths
 101 .It Pa /etc/ssl/certs/
 102 default directory for
 103 .Fn X509_STORE_set_default_paths
 104 .El
 105 .Sh SEE ALSO
 106 .Xr SSL_CTX_load_verify_locations 3 ,
 107 .Xr X509_LOOKUP_hash_dir 3 ,
 108 .Xr X509_STORE_set1_param 3 ,
 109 .Xr X509_STORE_set_verify_cb 3
 110 .Sh BUGS
 111 By the time that adding a directory is found to have failed,
 112 the file and some other directories may already have been successfully loaded,
 113 so these functions may change the state of the store even when they fail.
 114 .Pp
 115 .Fn X509_STORE_set_default_paths
 116 clears the error queue, deleting even error information that was
 117 already present when it was called.