denozord/strongswan-ext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

pki: Created pki --est man page

Browse Source
This commit is contained in:
Andreas Steffen
2022-08-25 07:02:29 +02:00
parent ba1d8aba32
commit c2dc5f69ca
5 changed files with 200 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
configure.ac
+2 -1
View File
@@ -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
src/libstrongswan/utils/lexparser.c
+8
View File
@@ -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
*/
src/libstrongswan/utils/lexparser.h
+6 -2
View File
@@ -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
*/
src/pki/man/Makefile.am
+1
View File
@@ -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 \
src/pki/man/pki---est.1.in
+183
View File
@@ -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)