docs: Added All NetBSD Manuals

1 files changed, 369 insertions, 0 deletions

diff --git a/static/netbsd/man8/certctl.8 b/static/netbsd/man8/certctl.8
new file mode 100644
index 00000000..072f1751
--- /dev/null
+++ b/static/netbsd/man8/certctl.8
@@ -0,0 +1,369 @@
+.\"	$NetBSD: certctl.8,v 1.3 2023/10/11 15:28:05 riastradh Exp $
+.\"
+.\" Copyright (c) 2023 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd August 16, 2023
+.Dt CERTCTL 8
+.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm certctl
+.Nd configure OpenSSL certificate trust anchors
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.Nm
+.Op Fl nv
+.Op Fl C Ar config
+.Op Fl c Ar certsdir
+.Op Fl u Ar distrustdir
+.Ar cmd
+.Op Ar args...
+.\""""""""""""""""""
+.Nm
+.Oo Ar options Oc Cm list
+.Nm
+.Oo Ar options Oc Cm rehash
+.Nm
+.Oo Ar options Oc Cm trust Ar cert
+.Nm
+.Oo Ar options Oc Cm untrust Ar cert
+.Nm
+.Oo Ar options Oc Cm untrusted
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+The
+.Nm
+utility manages certificates used by OpenSSL-based applications as
+trust anchors for certificate validation in TLS or other purposes,
+for example by
+.Xr ftp 1
+in HTTPS.
+.Nm
+allows configuring the set of certificates and persistently excluding
+individual certificates.
+.Pp
+For trust anchors to validate TLS certificates, OpenSSL applications
+typically use a directory at
+.Pa /etc/openssl/certs
+of hashed certificates in PEM format, with names like
+.Pa "3513523f.0"
+used for lookup; see
+.Xr openssl_rehash 1 .
+.Pp
+.Nm
+scans all directories in the certificate search path specified by the
+configuration file
+.Ar config
+.Pq default: Pa /etc/openssl/certs.conf
+for files called
+.Pa *.cer ,
+.Pa *.crt ,
+or
+.Pa *.pem
+in PEM format, and keeps
+.Ar certsdir
+.Pq default: Pa /etc/openssl/certs
+populated with:
+.Bl -dash
+.It
+symlinks to the original files in the certificate search path, for
+applications that scan a directory for all files matching
+.Pa *.cer ,
+.Pa *.crt ,
+or
+.Pa *.pem ;
+.It
+hashed symlinks as in
+.Xr openssl_rehash 1 ; and
+.It
+a single-file bundle
+.Pa ca-certificates.crt
+concatenating all the certificates in PEM format.
+.El
+.Pp
+.Nm
+will exclude from
+.Ar certsdir
+any certificates that have been marked untrustworthy with
+.Nm Cm untrust ,
+which are persistently maintained in the private state directory
+.Ar distrustdir
+.Pq default: Pa /etc/openssl/untrusted .
+.Pp
+.Nm
+treats
+.Ar config
+and
+.Ar distrustdir
+as configuration, and treats
+.Ar certsdir
+strictly as a cache that can be safely deleted and rebuilt with
+.Nm Cm rehash .
+.Nm
+can also be instructed not to touch
+.Ar certsdir
+at all by putting
+.Cm manual
+in
+.Ar config .
+.\""""""""""""""""""""""""""""""""""""""
+.Ss Commands
+.Bl -tag -width Cm
+.\""""""""""""""""""
+.It Cm list
+List absolute paths to trusted certificates.
+.Nm Cm rehash
+will populate
+.Ar certsdir
+with these.
+Paths are printed one per line, encoded in
+.Xr vis 1
+format to escape any shell metacharacters.
+.\""""""""""""""""""
+.It Cm rehash
+Populate
+.Ar certsdir
+with all trusted certificates, excluding any from
+.Nm Cm untrust .
+.\""""""""""""""""""
+.It Cm trust Ar cert
+Allow
+.Ar cert
+to be included in
+.Ar certsdir
+if it is in the certificate search path, and rehash to make it
+effective immediately.
+In other words, reverse the persistent effect of
+.Nm Cm untrust Ar cert .
+.Pp
+.Ar cert
+must be the full absolute path to a certificate that has been excluded
+by
+.Nm Cm untrust Ar cert .
+.Pp
+This does not add a new certificate which is not in the search path.
+To do that, you can create a directory to hold it and put that
+directory in the search path.
+.\""""""""""""""""""
+.It Cm untrust Ar cert
+Persistently prevent
+.Ar cert
+from being included in
+.Ar certsdir ,
+and rehash to make it effective immediately.
+.Pp
+.Ar cert
+must be the full absolute path to a certificate that is in the
+certificate search path.
+.\""""""""""""""""""
+.It Cm untrusted
+List absolute paths to certificates that have been excluded by
+.Nm Cm untrust .
+.Nm Cm rehash
+will not put these in
+.Ar certsdir .
+Paths are printed one per line, encoded in
+.Xr vis 1
+format to escape any shell metacharacters.
+.\""""""""""""""""""
+.El
+.\""""""""""""""""""""""""""""""""""""""
+.Ss Configuration file
+The configuration file is a plain text file of lines separated by
+.Tn US-ASCII
+line feeds.
+.Pp
+.Pp
+The first line must be:
+.Dl netbsd-certctl 20230816
+.Pp
+Lines with only whitespace, or whitespace followed by the comment
+character
+.Ql #
+are ignored.
+Each line has a directive and arguments separated by whitespace, and
+may be extended by
+.Ql \e
+to continuation lines.
+.Bl -tag -width Cm
+.\""""""""""""""""""
+.It Cm path Ar dir
+Add
+.Ar dir
+to the certificate search path.
+.Ar dir
+must be an absolute pathname,
+.Xr vis 3 Ns -encoded
+if it has any characters outside the class
+.Ql "a-zA-Z0-9,.:=/+-" .
+.Pp
+All certificates must have unique base names across all directories
+in the certificate search path.
+.\""""""""""""""""""
+.It Cm manual
+Manual override.
+If specified,
+.Nm
+will
+.Em not
+modify
+.Ar certsdir ,
+but may still check consistency of the configuration when run, and
+.Nm Cm untrust
+and
+.Nm Cm trust
+will still update
+.Ar distrustdir .
+.\""""""""""""""""""
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa /etc/openssl/certs
+Default directory of hashed TLS CA certificates.
+.It Pa /etc/openssl/certs/ca-certificates.crt
+Default single-file TLS CA certificate bundle.
+.It Pa /etc/openssl/certs.conf
+Default configuration file for TLS CA certificates.
+.It Pa /etc/openssl/untrusted
+Default
+.Ar distrustdir
+directory of excluded TLS CA certificates.
+.It Pa /usr/share/certs/mozilla/all
+All root CA certificates published by Mozilla, including untrustworthy
+certificates.
+.It Pa /usr/share/certs/mozilla/code
+All root CA certificates published by Mozilla for use in code-signing.
+.It Pa /usr/share/certs/mozilla/email
+All root CA certificates published by Mozilla for use in email
+authentication.
+.It Pa /usr/share/certs/mozilla/server
+All root CA certificates published by Mozilla for use in TLS server
+authentication.
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+Example configuration file
+.Pq Pa /etc/openssl/certs.conf :
+.Bd -literal -offset indent
+netbsd-certctl 20230816
+
+# Blank lines and comments are ignored.
+# Comments begin with a `#' sign.
+
+# Gather certificates from files called *.cer, *.crt, and *.pem
+# under these directories.
+path /usr/share/certs/mozilla/server
+path /usr/pkg/share/chromium-cacerts
+path /etc/openssl/certs.local
+
+# If the next line is uncommented, certctl(8) will decline to
+# touch /etc/openssl/certs.
+#manual
+.Ed
+.Pp
+Exclude a certificate:
+.Bd -literal -offset indent
+$ certctl untrust /usr/share/certs/mozilla/server/GTS_Root_R1.pem
+.Ed
+.Pp
+There is no need to run
+.Nm Cm rehash
+explicitly after
+.Nm Cm untrust ,
+but if you do, the setting will persist.
+.Pp
+Rebuild the hashed certificate cache at
+.Pa /etc/myapplication/certs
+from
+.Pa /etc/myapplication/certs.conf
+and
+.Pa /etc/myapplication/untrusted :
+.Bd -literal -offset indent
+$ certctl -c /etc/myapplication/certs \e
+        -C /etc/myapplication/certs.conf \e
+        -u /etc/myapplication/untrusted
+.Ed
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DIAGNOSTICS
+.Ex -std
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh COMPATIBILITY
+The
+.Nm
+utility is mostly compatible with a utility of the same name in
+.Fx .
+Differences:
+.Bl -enum
+.\""""""""""""""""""
+.It
+.Fx Nm
+supports destdir/metalog handling;
+.Nx Nm
+does not.
+.\""""""""""""""""""
+.It
+.Fx Nm
+treats
+.Pa /etc/ssl/certs
+and
+.Pa /etc/ssl/untrusted
+both as configuration
+.Em and
+as caches;
+.Nx Nm
+treats
+.Pa /etc/openssl/certs.conf
+and
+.Pa /etc/openssl/untrusted
+as configuration, and treats
+.Pa /etc/openssl/certs
+strictly as a cache.
+.Fx Nm
+will forget any
+.Nm Cm untrust
+settings on
+.Nm Cm rehash ,
+but
+.Nx Nm
+will remember them.
+.\""""""""""""""""""
+.It
+.Fx Nm
+takes configuration through environment variables;
+.Nx Nm
+takes configuration through a file and command-line arguments.
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr openssl 1 ,
+.Xr openssl_rehash 1
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 10.0 .
+A utility of the same name previously appeared in
+.Fx 12.2 .