man: Extended pki man page and added pki --ocsp man page

diff --git a/configure.ac b/configure.ac
index 0c2c42c988b533373746a721c1a8ce4e05e39c8c..ca2599d5321b7331d9847584567a578e1ddedcfe 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -2205,6 +2205,7 @@ AC_CONFIG_FILES([
        src/pki/man/pki---gen.1
        src/pki/man/pki---issue.1
        src/pki/man/pki---keyid.1
+       src/pki/man/pki---ocsp.1
        src/pki/man/pki---pkcs12.1
        src/pki/man/pki---pkcs7.1
        src/pki/man/pki---print.1

diff --git a/src/pki/man/Makefile.am b/src/pki/man/Makefile.am
index f220f39f4f6422ea8ddc255893c4f37676d63a10..3f64ab815a8f699cde2c19de223ceae4660dff1f 100644 (file)
--- a/src/pki/man/Makefile.am
+++ b/src/pki/man/Makefile.am
@@ -7,6 +7,7 @@ man1_MANS = \
        pki---gen.1 \
        pki---issue.1 \
        pki---keyid.1 \
+       pki---ocsp.1 \
        pki---pkcs7.1 \
        pki---print.1 \
        pki---pub.1 \

diff --git a/src/pki/man/pki---ocsp.1.in b/src/pki/man/pki---ocsp.1.in
new file mode 100644 (file)
index 0000000..23d4c7d
--- /dev/null
+++ b/src/pki/man/pki---ocsp.1.in
@@ -0,0 +1,247 @@
+.TH "PKI \-\-OCSP" 1 "2023-10-29" "@PACKAGE_VERSION@" "strongSwan"
+.
+.SH "NAME"
+.
+pki \-\-ocsp \- OCSP request parser and OCSP responder.
+.
+.SH "SYNOPSIS"
+.
+.SY pki\ \-\-ocsp
+.OP \-\-in file
+.OP \-\-cacert file
+.OP \-\-debug level
+.YS
+
+.SY pki\ \-\-ocsp
+.BI \-\-respond
+.OP \-\-in file
+.BI \-\-cacert\~ file
+.BI \-\-key\~ file
+.OP \-\-cert file
+.OP \-\-lifetime minutes
+.OP \-\-digest digest
+.OP \-\-rsa\-padding padding
+.OP \-\-debug level
+.YS
+.
+.SY pki\ \-\-ocsp
+.BI \-\-options\~ file
+.YS
+.
+.SY "pki \-\-ocsp"
+.B \-h
+|
+.B \-\-help
+.YS
+.
+.SH "DESCRIPTION"
+.
+This sub-command of
+.BR pki (1)
+parses an
+.B Online Certificate Status Protocol
+(OCSP) request as defined by RFC 6960 and with the
+.B --respond
+option generates an OCSP response based on the OCSP request.
+The certificate status is directly retrieved from the internal
+.B certificate
+database of an
+.B OpenXPKI
+(https://openxpki.org) server. The
+.B --respond
+option requires the
+.B openxpki
+and
+.B mysql
+libstrongswan plugins in order to access the
+.B certificate
+database of the
+.B OpenXPKI
+server running on the same host.
+.
+.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 "\-i, \-\-in " file
+OCSP request. If not given, the OCSP request is read from
+\fISTDIN\fR.
+.TP
+.BI "\-C, \-\-cacert " file
+CA certificate corresponding to one of the issuer hashes contained in the OCSP
+request. If the OCSP request is signed, a CA certificate forming the
+trust chain. Can be used multiple times.
+.TP
+.BI "\-k, \-\-key " file
+OCSP signer key. Can be used multiple times.
+.TP
+.BI "\-c, \-\-cert " file
+OCSP signer certificate (if it is not a CA certificate). Can be used
+multiple times.
+.TP
+.BI "\-l, \-\-lifetime " minutes
+Validity in minutes of the OCSP response (if missing, nextUpdate is omitted).
+.TP
+.BI "\-g, \-\-digest " digest
+Digest to use for signature creation. One of \fImd5\fR, \fIsha1\fR,
+\fIsha224\fR, \fIsha256\fR, \fIsha384\fR, or \fIsha512\fR, \fIsha3_224\fR,
+\fIsha3_256\fR, \fIsha3_384\fR, \fIsha3_512\fR.  The default is
+determined based on the type and size of the ocsp signing key.
+.TP
+.BI "\-R, \-\-rsa\-padding " padding
+Padding to use for RSA signatures. Either \fIpkcs1\fR or \fIpss\fR, defaults
+to \fIpkcs1\fR.
+.
+.SH "EXAMPLES"
+.
+Show the raw content of an OCSP request:
+.PP
+.EX
+pki \-\-ocsp \-\-in req_ca.der
+
+nonce:               5b:14:e3:cc:d5:b2:65:ec:c4:0d:c3:11:37:6a:9d:71
+  issuerKeyHash:     b6:76:79:95:b5:58:..:06:93:f3:39:79:19 (no match)
+  issuerNameHash:    af:25:78:ce:fc:15:..:67:95:81:31:a3:4d (no match)
+  serialNumber:      4f:33:21:1d:4d:fd:9b:db
+  issuerKeyHash:     b6:76:79:95:b5:58:..:06:93:f3:39:79:19 (no match)
+  issuerNameHash:    af:25:78:ce:fc:15:..:67:95:81:31:a3:4d (no match)
+  serialNumber:      68:f2:93:10:65:d0:5e:d1
+.EE
+.PP
+Show the content of the same OCSP request if the issuer certificate is given:
+.PP
+.EX
+pki \-\-ocsp \-\-in req_ca.der \-\-cacert cacert.pem
+
+nonce:               5b:14:e3:cc:d5:b2:65:ec:c4:0d:c3:11:37:6a:9d:71
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  issuerKeyHash:     b6:76:79:95:b5:58:..:06:93:f3:39:79:19 (ok)
+  issuerNameHash:    af:25:78:ce:fc:15:..:67:95:81:31:a3:4d (ok)
+  serialNumber:      4f:33:21:1d:4d:fd:9b:db
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  issuerKeyHash:     b6:76:79:95:b5:58:..:06:93:f3:39:79:19 (ok)
+  issuerNameHash:    af:25:78:ce:fc:15:..:67:95:81:31:a3:4d (ok)
+  serialNumber:      68:f2:93:10:65:d0:5e:d1
+.EE
+.PP
+Respond to the OCSP request above, with the OCSP response signed by the CA itself:
+.PP
+.EX
+pki \-\-ocsp \-\-respond \-\-in req_ca.der \-\-cacert cacert.pem \-\-key cakey.pem \\
+           \-\-lifetime 10 > rsp_ca.der
+
+nonce:               5b:14:e3:cc:d5:b2:65:ec:c4:0d:c3:11:37:6a:9d:71
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  issuerKeyHash:     b6:76:79:95:b5:58:..:06:93:f3:39:79:19 (ok)
+  issuerNameHash:    af:25:78:ce:fc:15:..:67:95:81:31:a3:4d (ok)
+  serialNumber:      4f:33:21:1d:4d:fd:9b:db
+  thisUpdate:        Oct 19 15:54:15 UTC 2023
+  nextUpdate:        Oct 19 16:04:15 UTC 2023
+  certValidation:    GOOD
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  issuerKeyHash:     b6:76:79:95:b5:58:..:06:93:f3:39:79:19 (ok)
+  issuerNameHash:    af:25:78:ce:fc:15:..:67:95:81:31:a3:4d (ok)
+  serialNumber:      68:f2:93:10:65:d0:5e:d1
+  thisUpdate:        Oct 19 15:54:15 UTC 2023
+  nextUpdate:        Oct 19 16:04:15 UTC 2023
+  certValidation:    GOOD
+trusted signer:     "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+ocspResponseStatus:  successful
+.EE
+.PP
+Respond to a signed OCSP request providing the complete trust chain:
+.PP
+.EX
+pki \-\-ocsp --respond --in req_signed.der --cacert cacert.pem --cacert issuer1.pem \\
+           \-\-key signerKey1.pem \-\-cert signerCert1.pem \-\-lifetime 10 > rsp_signed.der
+
+requestor:          "C=CH, O=strongSwan Project, CN=vpn.strongswan.org"
+  using certificate "C=CH, O=strongSwan Project, CN=vpn.strongswan.org"
+  using trusted intermediate ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA 1"
+  using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
+  reached self-signed root ca with a path length of 1
+requestor is trusted
+nonce:               a8:0f:29:0f:08:9c:29:c1:0d:a8:cb:b0:21:fa:e1:f7
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA 1"
+  issuerKeyHash:     5a:1b:ec:17:f0:6d:..:a2:c8:e7:6a:84:20 (ok)
+  issuerNameHash:    df:1e:24:71:96:e6:..:b9:82:18:45:e7:09 (ok)
+  serialNumber:      04:ff:cc:8d:36:91:cb:35:d7:c4
+  thisUpdate:        Oct 19 16:30:54 UTC 2023
+  nextUpdate:        Oct 19 16:40:54 UTC 2023
+  certValidation:    REVOKED
+  revocationTime:    Mar 26 06:41:54 UTC 2023
+  revocationReason:  superseded
+trusted signer:     "C=CH, O=strongSwan Project, CN=OCSP signer of strongSwan Issuing CA 1"
+ocspResponseStatus:  successful
+.EE
+.PP
+Respond to an OCSP request containing two items from different known issuers
+having an OCSP signer each. The issuer of the first request item determines the
+OCSP signer used to sign the OCSP response:
+.PP
+.EX
+pki \-\-ocsp \-\-respond \-\-in req.der \-\-cacert issuer1.pem \-\-cacert issuer2.pem \\
+           \-\-key signerKey1.pem \-\-cert signerCert1.pem \\
+           \-\-key signerKey2.pem \-\-cert signerCert2.pem \\
+           \-\-lifetime 10 > rsp_trusted.der
+
+nonce:               a1:33:aa:bc:96:60:69:76:f3:bc:9c:88:3b:07:50:47
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA 2"
+  issuerKeyHash:     72:41:ca:f9:35:87:..:d3:83:ab:d5:89:7b (ok)
+  issuerNameHash:    5e:b2:b4:42:e1:a5:..:b2:c3:9a:38:4f:cd (ok)
+  serialNumber:      29:ff:36:d9:9a:21:49:61:91:1d
+  thisUpdate:        Oct 19 16:02:35 UTC 2023
+  nextUpdate:        Oct 19 16:12:35 UTC 2023
+  certValidation:    REVOKED
+  revocationTime:    Sep 22 13:13:04 UTC 2023
+  revocationReason:  superseded
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA 1"
+  issuerKeyHash:     5a:1b:ec:17:f0:6d:..:a2:c8:e7:6a:84:20 (ok)
+  issuerNameHash:    df:1e:24:71:96:e6:..:b9:82:18:45:e7:09 (ok)
+  serialNumber:      10:ff:45:9a:6d:ee:4c:ec:7c:97
+  thisUpdate:        Oct 19 16:02:35 UTC 2023
+  nextUpdate:        Oct 19 16:12:35 UTC 2023
+  certValidation:    FAILED
+there are multiple known issuers
+trusted signer:     "C=CH, O=strongSwan Project, CN=OCSP signer of strongSwan Issuing CA 2"
+ocspResponseStatus:  successful
+.EE
+.PP
+Repeat the OCSP response above but with a self-signed OCSP signing certificate
+.PP
+.EX
+pki \-\-ocsp --respond \-\-in req.der \-\-cacert issuer1.pem \-\-cacert issuer2.pem \\
+           \-\-key signerKey.pem \-\-cert signerCert.pem \-\-lifetime 10 > rsp_self_signed.der
+
+nonce:               a1:33:aa:bc:96:60:69:76:f3:bc:9c:88:3b:07:50:47
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA 2"
+  issuerKeyHash:     72:41:ca:f9:35:87:..:d3:83:ab:d5:89:7b (ok)
+  issuerNameHash:    5e:b2:b4:42:e1:a5:..:b2:c3:9a:38:4f:cd (ok)
+  serialNumber:      29:ff:36:d9:9a:21:49:61:91:1d
+  thisUpdate:        Oct 19 16:13:23 UTC 2023
+  nextUpdate:        Oct 19 16:23:23 UTC 2023
+  certValidation:    REVOKED
+  revocationTime:    Sep 22 13:13:04 UTC 2023
+  revocationReason:  superseded
+issuer:             "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA 1"
+  issuerKeyHash:     5a:1b:ec:17:f0:6d:..:a2:c8:e7:6a:84:20 (ok)
+  issuerNameHash:    df:1e:24:71:96:e6:..:b9:82:18:45:e7:09 (ok)
+  serialNumber:      10:ff:45:9a:6d:ee:4c:ec:7c:97
+  thisUpdate:        Oct 19 16:13:23 UTC 2023
+  nextUpdate:        Oct 19 16:23:23 UTC 2023
+  certValidation:    GOOD
+there are multiple known issuers
+self-signed signer: "C=CH, O=strongSwan Project, CN=strongSwan OCSP signer"
+ocspResponseStatus:  successful
+.EE
+.PP
+.SH "SEE ALSO"
+.BR pki (1)

diff --git a/src/pki/man/pki.1.in b/src/pki/man/pki.1.in
index 6f1efa7a021711c6833b0341d9f9815277ff142e..9dddf00614d403316f390a5abb93db78d63fa96c 100644 (file)
--- a/src/pki/man/pki.1.in
+++ b/src/pki/man/pki.1.in
@@ -1,4 +1,4 @@
-.TH PKI 1 "2022-08-22" "@PACKAGE_VERSION@" "strongSwan"
+.TH PKI 1 "2023-10-20" "@PACKAGE_VERSION@" "strongSwan"
 .
 .SH "NAME"
 .
@@ -33,13 +33,19 @@ key IDs.
 .P
 The
 .B pki
-command now supports certificate enrollment via the
+command also supports certificate enrollment via the
 .B Simple Certificate Enrollment Protocol
 (SCEP) as defined by RFC 8894, replacing the obsoleted
 .B ipsec scepclient
 tool. Additionally the
 .B Enrollment over Secure Transport
 (EST) protocol (RFC 7030) is supported, too.
+.P
+The latest feature is an
+.B Online Certificate Status Protocol
+(OCSP) responder as defined by RFC 6960, interoperating with an
+.B OpenXPKI
+server by directly accessing its internal certificate datebase.
 .
 .SH "COMMANDS"
 .
@@ -94,6 +100,9 @@ Enroll an X.509 certificate with an EST server.
 .TP
 .B "\-e, \-\-estca"
 Get CA certificate[s] from an EST server.
+.TP
+.B "\-o, \-\-ocsp"
+OCSP request parser and OCSP responder.
 .
 .SH "EXAMPLES"
 .
@@ -188,3 +197,4 @@ certificates with the \-\-crl option.
 .BR pki\ \-\-scepca (1)
 .BR pki\ \-\-est (1)
 .BR pki\ \-\-estca (1)
+.BR pki\ \-\-ocsp (1)