pki: Created pki --est man page

diff --git a/configure.ac b/configure.ac
index e0a78cc7f4f6a50c72e43311f3458f48e86c0cb4..7cbc96b6e57a3c20c3d0fadb67195745665d0be1 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -1,6 +1,6 @@
 #
 # Copyright (C) 2007-2017 Tobias Brunner
-# Copyright (C) 2006-2019 Andreas Steffen
+# Copyright (C) 2006-2022 Andreas Steffen
 # Copyright (C) 2006-2014 Martin Willi
 #
 # Copyright (C) secunet Security Networks AG
@@ -2162,6 +2162,7 @@ AC_CONFIG_FILES([
        src/pki/man/pki.1
        src/pki/man/pki---acert.1
        src/pki/man/pki---dn.1
+       src/pki/man/pki---est.1
        src/pki/man/pki---estca.1
        src/pki/man/pki---gen.1
        src/pki/man/pki---issue.1

diff --git a/src/libstrongswan/utils/lexparser.c b/src/libstrongswan/utils/lexparser.c
index 654a5b4b4c916f35e468c1da93bf34f831619952..fe94882f254c23682af1ed4780bd5e8c7b070f31 100644 (file)
--- a/src/libstrongswan/utils/lexparser.c
+++ b/src/libstrongswan/utils/lexparser.c
@@ -36,6 +36,14 @@ bool match(const char *pattern, const chunk_t *ch)
        return ch->len == strlen(pattern) && strncmp(pattern, ch->ptr, ch->len) == 0;
 }
 
+/**
+ * compare string with chunk ignoring the case of the characters
+ */
+bool matchcase(const char *pattern, const chunk_t *ch)
+{
+       return ch->len == strlen(pattern) && strncasecmp(pattern, ch->ptr, ch->len) == 0;
+}
+
 /**
  * extracts a token ending with the first occurrence of a given termination symbol
  */

diff --git a/src/libstrongswan/utils/lexparser.h b/src/libstrongswan/utils/lexparser.h
index 96d8d8cb5a33b5debe5f15a131936b372517b971..20379fb591f5d0393d1752132a617461ad101d2a 100644 (file)
--- a/src/libstrongswan/utils/lexparser.h
+++ b/src/libstrongswan/utils/lexparser.h
@@ -1,6 +1,5 @@
 /*
- * Copyright (C) 2001-2008 Andreas Steffen
- *
+ * Copyright (C) 2001-2022 Andreas Steffen
  *
  * Copyright (C) secunet Security Networks AG
  *
@@ -35,6 +34,11 @@ bool eat_whitespace(chunk_t *src);
  */
 bool match(const char *pattern, const chunk_t *ch);
 
+/**
+ * Compare null-terminated pattern with chunk ignoring the case of the characters
+ */
+bool matchcase(const char *pattern, const chunk_t *ch);
+
 /**
  * Extracts a token ending with the first occurrence of a given termination symbol
  */

diff --git a/src/pki/man/Makefile.am b/src/pki/man/Makefile.am
index c3f3982d96e2c58c684aa006307b7ea98c02d923..f220f39f4f6422ea8ddc255893c4f37676d63a10 100644 (file)
--- a/src/pki/man/Makefile.am
+++ b/src/pki/man/Makefile.am
@@ -2,6 +2,7 @@ man1_MANS = \
        pki.1 \
        pki---acert.1 \
        pki---dn.1 \
+       pki---est.1 \
        pki---estca.1 \
        pki---gen.1 \
        pki---issue.1 \

diff --git a/src/pki/man/pki---est.1.in b/src/pki/man/pki---est.1.in
new file mode 100644 (file)
index 0000000..5c4f16f
--- /dev/null
+++ b/src/pki/man/pki---est.1.in
@@ -0,0 +1,183 @@
+.TH "PKI \-\-EST" 1 "2022-08-22" "@PACKAGE_VERSION@" "strongSwan"
+.
+.SH "NAME"
+.
+pki \-\-est \- Enroll an X.509 certificate with an EST server
+.
+.SH "SYNOPSIS"
+.
+.SY pki\ \-\-est
+.BI\-\-\-url\~ url
+.OP \-\-in file
+.BI \-\-cacert\~ file
+.RB [ \-\-cert
+.IR file | \fB\-\-certid\fR
+.IR hex ]
+.RB [ \-\-key
+.IR file | \fB\-\-keyid\fR
+.IR hex ]
+.OP \-\-userpass username:password
+.OP \-\-interval time
+.OP \-\-maxpolltime time
+.OP \-\-outform encoding
+.OP \-\-debug level
+.YS
+.
+.SY pki\ \-\-est
+.BI \-\-options\~ file
+.YS
+.
+.SY "pki \-\-est"
+.B \-h
+|
+.B \-\-help
+.YS
+.
+.SH "DESCRIPTION"
+.
+This sub-command of
+.BR pki (1)
+sends a PKCS#10 certificate request via HTTPS to a server using the Enrollment
+over Secure Transport (EST) Protocol (RFC 7030). After successful authorization
+which with manual authentication requires periodic polling by the enrollment
+client, the EST server returns an X.509 certificate signed by the CA.
+
+Before the expiry of the current certificate, a new client certificate based on
+a fresh private key can be requested, using the old certificate and the old
+key for automatic TLS client authentication with the EST server.
+.
+.SH "OPTIONS"
+.
+.TP
+.B "\-h, \-\-help"
+Print usage information with a summary of the available options.
+.TP
+.BI "\-v, \-\-debug " level
+Set debug level, default: 1.
+.TP
+.BI "\-+, \-\-options " file
+Read command line options from \fIfile\fR.
+.TP
+.BI "\-u, \-\-url " url
+URL of the EST server.
+.TP
+.BI "\-i, \-\-in " file
+PKCS#10 certificate request. If not given, the certificate request is read from
+\fISTDIN\fR.
+.TP
+.BI "\-C, \-\-cacert " file
+CA certificate in the trust chain used for EST TLS server signature verification
+or in the trust chain to verify the client certificate issued by the CA.
+Can be used multiple times.
+.TP
+.BI "\-c, \-\-cert " file
+Client certificate to be renewed.
+.TP
+.BI "\-X, \-\-certid " hex
+Smartcard or TPM 2.0 client certficate object handle.
+.TP
+.BI "\-k, \-\-key " file
+Client private key to be replaced.
+.TP
+.BI "\-x, \-\-keyid " hex
+Smartcard or TPM 2.0 client private key object handle.
+.TP
+.BI "\-p, \-\-userpass " username:password
+Optional username:password that may be used for HTTP basic authentication.
+.TP
+.BI "\-t, \-\-interval " time
+Poll interval in seconds, defaults to \fI60s\fR. This value might get overridden
+by the
+.B retry-after
+header in the HTTP 202 reply from the EST server.
+.TP
+.BI "\-m, \-\-maxpolltime " time
+Maximum poll time in seconds, defaults to \fI0\fR which means unlimited polling.
+.TP
+.BI "\-f, \-\-outform " encoding
+Encoding of the created certificate file. Either \fIder\fR (ASN.1 DER) or
+\fIpem\fR (Base64 PEM), defaults to \fIder\fR.
+.
+.SH "EXAMPLES"
+.
+To save some typing work the following command line options are stored in a
+\fIest.opt\fR file:
+.PP
+.EX
+\-\-url https://pki.strongswan.org:8443
+\-\-cacert tlsca.crt
+\-\-cacert tlsca-1.crt
+\-\-cacert myca.crt
+\-\-cacert myca-1.crt
+.EE
+.PP
+.B NOTE:
+For a successful HTTPS connection, trust must be established into the EST server
+certificate. The TLS trust chain including the root CA certificate and
+optionally intermediate CA certificates must be given using [multiple]
+.B --cacert*
+options.
+.P
+The
+.B --cacert
+option must also be used to be able to verify the received client certificate
+issued by the CA. This second trust chain might be identical to the TLS trust
+chain (if the EST server is using a TLS server certificate issued by its own CA)
+or might be totally different, e.g. if a Let's Encrypt EST server certificate is
+used.
+.P
+With the following command, an X.509 certificate signed by the intermediate CA is
+requested from an EST server based on a PKCS#10 certificate request:
+.PP
+.EX
+pki \-\-options est.opt --in moonReq.der > moonCert.der
+
+negotiated TLS 1.3 using suite TLS_AES_256_GCM_SHA384
+received TLS server certificate 'C=CH, O=strongSwan Project, CN=pki.strongswan.org'
+  using certificate "C=CH, O=strongSwan Project, CN=pki.strongswan.org"
+  using trusted intermediate ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
+  using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  reached self-signed root ca with a path length of 1
+  EST request pending, polling indefinitely every 300 seconds
+  going to sleep for 300 seconds
+  ...
+Issued certificate "C=CH, O=strongSwan Project, CN=moon.strongswan.org"
+  serial: 1a:ff:de:66:d9:38:ea:d5:b6:da
+  using certificate "C=CH, O=strongSwan Project, CN=moon.strongswan.org"
+  using trusted intermediate ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
+  using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  reached self-signed root ca with a path length of 1
+Issued certificate is trusted, valid from Aug 22 15:19:43 2022 until Aug 22 15:19:43 2023 (currently valid)
+.EE
+.PP
+This certificate can be renewed some time before it expires with the command:
+.PP
+.EX
+pki \-\-options est.opt --in moonReqNew.der --cert moonCert.der --key moonKey.der > moonCertNew.der
+
+negotiated TLS 1.3 using suite TLS_AES_256_GCM_SHA384
+received TLS server certificate 'C=CH, O=strongSwan Project, CN=pki.strongswan.org'
+  using certificate "C=CH, O=strongSwan Project, CN=pki.strongswan.org"
+  using trusted intermediate ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
+  using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  reached self-signed root ca with a path length of 1
+sending TLS client certificate 'C=CH, O=strongSwan Project, CN=moon.strongswan.org'
+sending TLS intermediate certificate 'C=CH, O=strongSwan Project, CN=strongSwan Issuing CA'
+Issued certificate "C=CH, O=strongSwan Project, CN=moon.strongswan.org"
+  serial: 1b:ff:ad:dc:2f:50:c4:cb:a1:44
+  using certificate "C=CH, O=strongSwan Project, CN=moon.strongswan.org"
+  using trusted intermediate ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
+  using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  reached self-signed root ca with a path length of 1
+Issued certificate is trusted, valid from Jul 20 12:21:00 2023 until Jul 20 12:21:00 2024 (currently valid)
+.EE
+.PP
+If the private key and the certificate of the client is stored in a TPM 2.0, the
+renewal can be done wtih the following options:
+.PP
+.EX
+pki \-\-options est.opt --in moonReqNew.der --certid 0x01800004 --keyid 0x81010004 > moonCertNew.der
+
+.SH "SEE ALSO"
+.
+.BR pki (1)