SourceFormat Enforcement

[thirdparty/squid.git] / src / security / cert_generators / file / security_file_certgen.8.in

.if !'po4a'hide' .TH security_file_certgen 8
.
.SH NAME
security_file_certgen \- SSL certificate generator for Squid.
.PP
Version 1.0
.
.SH SYNOPSIS
.if !'po4a'hide' .B security_file_certgen
.if !'po4a'hide' .B [\-dhv]
.br
.if !'po4a'hide' .B security_file_certgen
.if !'po4a'hide' .B "[\-d] \-s "
directory
.if !'po4a'hide' .B "[\-M "
size
.if !'po4a'hide' .B ]
.br
.if !'po4a'hide' .B security_file_certgen
.if !'po4a'hide' .B "[\-d] \-c \-s "
directory
.if !'po4a'hide' .B "[\-n "
serial number
.if !'po4a'hide' .B ]
.br
.if !'po4a'hide' .B security_file_certgen
.if !'po4a'hide' .B "[\-d] \-g \-s "
directory
.
.SH DESCRIPTION
.B security_file_certgen
is an installed binary.
.PP
Because the generation and signing of SSL certificates takes time
Squid must use external process to handle the work.
.
This process generates new SSL certificates and uses a disk cache of certificatess
to improve response times on repeated requests.
Communication occurs via TCP sockets bound to the loopback interface.
.
.SH OPTIONS
.if !'po4a'hide' .TP 12
.if !'po4a'hide' .B \-b fs_block_size
File system block size in bytes. Needed for processing natural size of certificate on disk.
Default value is 2048 bytes.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-c
Initialize the SSL storage database and exit.
Requires the 
.B -s 
option to determine the storage location being created.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-d
Write debug info to stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-g
Display the current serial number using stderr and exit.
Requires 
.B \-s 
option to determine which storage directory the serial is located in.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-h
Display the binary help and command line syntax info using stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-s directory
Directory path of disk storage for new SSL certificates.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-M size
Maximum size of SSL certificate disk storage.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-n serial number
HEX 
.B "serial number "
to use when initializing an SSL storage database.
The default value of serial number is the number of seconds since Epoch minus 1200000000.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-v
Display the binary version details using stderr.
.
.SH KNOWN ISSUES
.PP
.B SSL errors after changing the CA
.
.PP
Certificates are stored in this database in signed form.
After any change to the signing CA in squid.conf be sure to erase and re-initialize the certificate database.
.
.PP
.B Certificate chaining
.
.PP
The version 1.0 of this helper will not add chained intermediate CA certificates.
The client must have a full chain of trust from the root CA all the way
down to the end certificate generated by this program.
.
Signing with an intermediate CA needs to install both the
root and the intermediate public CA on the clients.
.
.SH CONFIGURATION
.PP
Before this helper can be used the storage area for new certificates must be initialized manually.
This is done from the command line using the 
.B \-c 
parameters.
.
.PP
For example:
.if !'po4a'hide' .RS
.if !'po4a'hide' .B @DEFAULT_SSL_CRTD@ -c -s @DEFAULT_SSL_DB_DIR@
.if !'po4a'hide' .RE
.
.PP
Certificates are stored in this database in signed form.
After any change to the signing CA in squid.conf be sure to erase and re-initialize the certificate database.
.
.PP
For simple configuration the helper defaults can be used.
Only HTTP listening port options are required to enable generation and set the signign CA certificate.
For Example:
.if !'po4a'hide' .RS
.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
.if !'po4a'hide' .RE
.
.PP
For more customized configuration the helper certificate storage directory location and size can be altered with the
.B sslcrtd_program 
configuration directive.
For example:
.if !'po4a'hide' .RS
.if !'po4a'hide' .B sslcrtd_program @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
.if !'po4a'hide' .br
.if !'po4a'hide' .B sslcrtd_children 5
.if !'po4a'hide' .RE
.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Christos Tsantilas <christos@chtsanti.net>
.PP
This manual was written by
.if !'po4a'hide' .I Christos Tsantilas <christos@chtsanti.net>
.if !'po4a'hide' .I Amos Jeffries <squid3@treenet.co.nz>
.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2017 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.
.SH QUESTIONS
Questions on the usage of this program can be sent to the
.I Squid Users mailing list
.if !'po4a'hide' <squid-users@squid-cache.org>
.
.SH REPORTING BUGS
Bug reports need to be made in English.
See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
.PP
Report bugs or bug fixes using http://bugs.squid-cache.org/
.PP
Report serious security bugs to
.I Squid Bugs <squid-bugs@squid-cache.org>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <squid-dev@squid-cache.org>
.
.SH SEE ALSO
.if !'po4a'hide' .BR squid "(8), "
.if !'po4a'hide' .BR GPL "(7), "
.br
The Squid FAQ wiki
.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
.br
The Squid Configuration Manual
.if !'po4a'hide' http://www.squid-cache.org/Doc/config/