src/security/cert_generators/file/security_file_certgen.8.in

   1 .if !'po4a'hide' .TH security_file_certgen 8
   2 .
   3 .SH NAME
   4 security_file_certgen \- SSL certificate generator for Squid.
   5 .PP
   6 Version 1.1
   7 .
   8 .SH SYNOPSIS
   9 .if !'po4a'hide' .B security_file_certgen
  10 .if !'po4a'hide' .B "[\-cdhv] [\-s "
  11 directory
  12 .if !'po4a'hide' .B "\-M "
  13 size
  14 .if !'po4a'hide' .B "] [\-b "
  15 fs_block_size
  16 .if !'po4a'hide' .B ]
  17 .
  18 .SH DESCRIPTION
  19 .B security_file_certgen
  20 is an installed binary.
  21 .PP
  22 Because the generation and signing of SSL certificates takes time
  23 Squid can use this helper as an external process to handle the work.
  24 .
  25 Communication occurs via TCP sockets bound to the loopback interface.
  26 .
  27 This helper can use a disk cache of certificates to improve response
  28 times on repeated requests. It can also operate without a cache,
  29 generating new certificates on every request.
  30 .
  31 .SH OPTIONS
  32 .if !'po4a'hide' .TP 12
  33 .if !'po4a'hide' .B \-b fs_block_size
  34 File system block size in bytes. Needed for processing natural size of certificate on disk.
  35 Default value is 2048 bytes.
  36 The following suffixes are accepted:
  37 .B B, KB, MB, GB.
  38 When no suffix is set,
  39 .B B
  40 is assumed.
  41 .
  42 .if !'po4a'hide' .TP
  43 .if !'po4a'hide' .B \-c
  44 Initialize the SSL storage database and exit. Requires the
  45 .B \-s
  46 and
  47 .B \-M
  48 options to determine the storage location and size being created.
  49 .
  50 .if !'po4a'hide' .TP
  51 .if !'po4a'hide' .B \-d
  52 Write debug info to stderr.
  53 .
  54 .if !'po4a'hide' .TP
  55 .if !'po4a'hide' .B \-h
  56 Display the binary help and command line syntax info using stderr.
  57 .
  58 .if !'po4a'hide' .TP
  59 .if !'po4a'hide' .B \-s directory
  60 Directory path of SSL storage database. Requires the
  61 .B \-M
  62 option.
  63 .
  64 .if !'po4a'hide' .TP
  65 .if !'po4a'hide' .B \-M size
  66 Maximum size of SSL certificate disk storage. Same suffixes supported by the
  67 .B \-b
  68 option can be used.
  69 .
  70 .if !'po4a'hide' .TP
  71 .if !'po4a'hide' .B \-v
  72 Display the binary version details using stderr.
  73 .
  74 .SH KNOWN ISSUES
  75 .PP
  76 .B SSL errors after changing the CA
  77 .
  78 .PP
  79 Certificates are stored in this database in signed form.
  80 After any change to the signing CA in squid.conf be sure to erase and reinitialize the certificate database.
  81 .
  82 .PP
  83 .B Certificate chaining
  84 .
  85 .PP
  86 The versions 1.0 to 1.1 of this helper will not add chained intermediate CA certificates.
  87 The client must have a full chain of trust from the root CA all the way
  88 down to the end certificate generated by this program.
  89 .
  90 Signing with an intermediate CA needs to install both the
  91 root and the intermediate public CA on the clients.
  92 .
  93 .SH CONFIGURATION
  94 .PP
  95 Before this helper can be used with disk storage, the storage area for new certificates must be initialized manually.
  96 This is done from the command line using the
  97 .B \-c
  98 parameter.
  99 .
 100 .PP
 101 For example:
 102 .if !'po4a'hide' .RS
 103 .if !'po4a'hide' .B @DEFAULT_SSL_CRTD@ \-c \-s @DEFAULT_SSL_DB_DIR@ \-M 4MB
 104 .if !'po4a'hide' .RE
 105 .
 106 .PP
 107 Certificates are stored in this database in signed form.
 108 After any change to the signing CA in squid.conf be sure to erase and re-initialize the certificate database.
 109 .
 110 .PP
 111 For simple configuration the helper defaults can be used.
 112 Only HTTP listening port options are required to enable generation and set the signing CA certificate.
 113 .
 114 .PP
 115 For example:
 116 .if !'po4a'hide' .RS
 117 .if !'po4a'hide' .B http_port 3128 ssl-bump generate-host-certificates=on dynamic_cert_mem_cache_size=4MB cert=@SYSCONFDIR@/ssl_cert/example.com.pem
 118 .if !'po4a'hide' .RE
 119 .
 120 .PP
 121 For more customized configuration, the helper certificate storage directory location and size can be altered with the
 122 .B sslcrtd_program
 123 configuration directive. The number of helper processes running can be configured with the
 124 and
 125 .B ssl_crtd_children
 126 configuration directive.
 127 .
 128 .PP
 129 For example:
 130 .if !'po4a'hide' .RS
 131 .if !'po4a'hide' .B sslcrtd_program @DEFAULT_SSL_CRTD@ \-s @DEFAULT_SSL_DB_DIR@ \-M 4MB
 132 .if !'po4a'hide' .br
 133 .if !'po4a'hide' .B sslcrtd_children 5
 134 .if !'po4a'hide' .RE
 135 .
 136 .PP
 137 To operate without disk storage, the helper should be configured explicitly without the
 138 .B \-s
 139 and
 140 .B \-M
 141 parameters.
 142 .
 143 .PP
 144 For example:
 145 .if !'po4a'hide' .RS
 146 .if !'po4a'hide' .B sslcrtd_program @DEFAULT_SSL_CRTD@
 147 .if !'po4a'hide' .RE
 148 .
 149 .SH AUTHOR
 150 This program was written by
 151 .if !'po4a'hide' .I Christos Tsantilas <christos@chtsanti.net>
 152 .PP
 153 This manual was written by
 154 .if !'po4a'hide' .I Christos Tsantilas <christos@chtsanti.net>
 155 and
 156 .if !'po4a'hide' .I Amos Jeffries <amosjeffries@squid-cache.org>
 157 .
 158 .SH COPYRIGHT
 159 .PP
 160  * Copyright (C) 1996-2021 The Squid Software Foundation and contributors
 161  *
 162  * Squid software is distributed under GPLv2+ license and includes
 163  * contributions from numerous individuals and organizations.
 164  * Please see the COPYING and CONTRIBUTORS files for details.
 165 .
 166 .SH QUESTIONS
 167 Questions on the usage of this program can be sent to the
 168 .I Squid Users mailing list
 169 .if !'po4a'hide' <squid-users@lists.squid-cache.org>
 170 .
 171 .SH REPORTING BUGS
 172 Bug reports need to be made in English.
 173 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
 174 .PP
 175 Report bugs or bug fixes using http://bugs.squid-cache.org/
 176 .PP
 177 Report serious security bugs to
 178 .I Squid Bugs <squid-bugs@lists.squid-cache.org>
 179 .PP
 180 Report ideas for new improvements to the
 181 .I Squid Developers mailing list
 182 .if !'po4a'hide' <squid-dev@lists.squid-cache.org>
 183 .
 184 .SH SEE ALSO
 185 .if !'po4a'hide' .BR squid "(8), "
 186 .if !'po4a'hide' .BR GPL "(7), "
 187 .br
 188 The Squid FAQ wiki
 189 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
 190 .br
 191 The Squid Configuration Manual
 192 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/