src/pki/man/pki---scepca.1.in

   1 .TH "PKI \-\-SCEPCA" 1 "2022-08-22" "@PACKAGE_VERSION@" "strongSwan"
   2 .
   3 .SH "NAME"
   4 .
   5 pki \-\-scepca \- Get CA [and RA] certificate[s] from a SCEP server
   6 .
   7 .SH "SYNOPSIS"
   8 .
   9 .SY pki\ \-\-scepca
  10 .BI\-\-\-url\~ url
  11 .OP \-\-caout file
  12 .OP \-\-raout file
  13 .OP \-\-outform encoding
  14 .OP \-\-force
  15 .OP \-\-debug level
  16 .YS
  17 .
  18 .SY pki\ \-\-scepca
  19 .BI \-\-options\~ file
  20 .YS
  21 .
  22 .SY "pki \-\-scepca"
  23 .B \-h
  24 |
  25 .B \-\-help
  26 .YS
  27 .
  28 .SH "DESCRIPTION"
  29 .
  30 This sub-command of
  31 .BR pki (1)
  32 gets CA and RA certificates via http from a SCEP server using the \fIGetCACert\fR
  33 command of the Simple Certificate Enrollment Protocol (RFC 8894).
  34 .
  35 .SH "OPTIONS"
  36 .
  37 .TP
  38 .B "\-h, \-\-help"
  39 Print usage information with a summary of the available options.
  40 .TP
  41 .BI "\-v, \-\-debug " level
  42 Set debug level, default: 1.
  43 .TP
  44 .BI "\-+, \-\-options " file
  45 Read command line options from \fIfile\fR.
  46 .TP
  47 .BI "\-u, \-\-url " url
  48 URL of the SCEP server.
  49 .TP
  50 .BI "\-c, \-\-caout " file
  51 If present, path where the fetched root CA certificate file is stored to.
  52 If several CA certificates are downloaded, then the value of
  53 .B \-\-caout
  54 is used as a template to derive unique filenames (*-1, *-2, etc.) for the
  55 intermediate or sub CA certificates.
  56 If a file suffix is missing, then depending on the value of
  57 .B \-\-outform
  58 either .\fIder\fR (the default) or .\fIpem\fR is automatically appended.
  59 If the
  60 .B \-\-caout
  61 option is missing and
  62 .B \-\-outform
  63 is set to \fIpem\fR then a PEM-encoded CA certificate bundle is written to
  64 \fIstdout\fR.
  65 .TP
  66 .BI "\-r, \-\-raout " file
  67 If present, path where the fetched RA certificate file is stored to.
  68 If multiple RA certificates are available, then the value of
  69 .B \-\-raout
  70 is used as a template to derive unique filenames (*-2, etc.). If the
  71 .B \-\-raout
  72 option is missing, then the value of
  73 .B \-\-caout
  74 is used as a template to derive unique filenames (*-ra, *-ra-2, etc.) for the RA
  75 certificates. If a file suffix is missing, then depending on the value of
  76 .B \-\-outform
  77 either .\fIder\fR (the default) or .\fIpem\fR is automatically appended.
  78 .TP
  79 .BI "\-f, \-\-outform " encoding
  80 Encoding of the created certificate file. Either \fIder\fR (ASN.1 DER) or
  81 \fIpem\fR (Base64 PEM), defaults to \fIder\fR.
  82 .TP
  83 .B "\-F, \-\-force"
  84 Force overwrite of existing files.
  85 .
  86 .SH "EXAMPLES"
  87 .
  88 A SCEP server sends a root CA and an intermediate CA certificate as well as an
  89 RA certificate:
  90 .PP
  91 .EX
  92 pki \-\-scepca \-\-url http://pki.strongswan.org:8080/scep \-\-caout myca.crt \-\-raout myra.crt
  93
  94 Root CA cert "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
  95   serial: 65:31:00:ca:79:da:16:6b:aa:ac:89:e2:a8:f9:49:c3:10:ab:64:54
  96   SHA256: 96:70:50:51:cd:b9:e7:94:6b:04:f6:15:45:80:fc:90:85:01:71:2a:f6:4f:d1:1b:2d:a1:7e:eb:bf:dd:be:86
  97   SHA1  : 8e:f3:78:b0:34:a6:c1:6a:7b:c6:f5:91:eb:e5:46:9b:0d:0a:a7:ba (jvN4sDSmwWp7xvWR6+VGmw0Kp7o)
  98 Root CA cert is untrusted, valid until Aug 12 15:51:34 2032, 'myca.crt'
  99 Sub CA cert "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
 100   serial: 74:f9:7e:72:7d:b8:fd:f2:c6:e5:1b:fa:37:f9:cb:87:bf:9c:ea:e2
 101   SHA256: a3:5b:4b:12:d5:8f:68:7b:05:11:08:27:f5:42:62:b8:b5:01:1b:19:37:9c:28:78:5d:37:08:69:6a:8c:07:bf
 102   SHA1  : 8c:e6:67:67:c2:23:89:7b:d0:bc:b1:50:d2:1c:bc:8d:8d:69:15:11 (jOZnZ8IjiXvQvLFQ0hy8jY1pFRE)
 103   using certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
 104   using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
 105   reached self-signed root ca with a path length of 0
 106 Sub CA cert is trusted, valid until Aug 12 15:51:34 2027, 'myca-1.crt'
 107 RA cert "C=CH, O=strongSwan Project, CN=SCEP RA"
 108   serial: 74:f9:7e:72:7d:b8:fd:f2:c6:e5:1b:fa:37:f9:cb:87:bf:9c:ea:e3
 109   SHA256: 57:22:f3:13:69:2f:24:82:12:59:8e:05:63:0b:f5:a8:fb:4e:78:87:8d:68:d1:4c:c1:c4:b5:85:db:bb:64:df
 110   SHA1  : bc:d1:46:76:55:7f:8c:d1:c5:22:31:b9:d7:b1:49:b5:95:a4:f3:ea (vNFGdlV/jNHFIjG517FJtZWk8+o)
 111   using certificate "C=CH, O=strongSwan Project, CN=SCEP RA"
 112   using untrusted intermediate certificate "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
 113   using trusted ca certificate "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
 114   reached self-signed root ca with a path length of 1
 115 RA cert is trusted, valid until Aug 10 15:51:34 2023, 'myra.crt'
 116 .EE
 117 .PP
 118 The trusthworthiness of the root CA certificate has to be established manually by
 119 verifying the SHA256 or SHA1 fingerprint of the DER-encoded certificate that is
 120 e.g. listed on the official PKI website or by some other means.
 121 .P
 122 The stored certificate files in DER format can be overwritten by PEM-encoded
 123 versions with:
 124 .PP
 125 .EX
 126 pki \-\-scepca \-\-url http://pki.strongswan.org:8080/scep \-\-caout myca.crt \-\-raout myra.crt \\
 127              \-\-outform pem \-\-force
 128 .EE
 129 .PP
 130 If the
 131 .B \-\-raout
 132 option is omitted and the
 133 .B \-\-caout
 134 template doesn't have a file suffix, then with
 135 .B \-\-outform
 136 \fIpem\fR the following filenames are derived:
 137 .PP
 138 .EX
 139 pki \-\-scepca \-\-url http://pki.strongswan.org:8080/scep \-\-caout scep/myca \-\-outform pem
 140
 141 Root CA cert "C=CH, O=strongSwan Project, CN=strongSwan Root CA"
 142   ...
 143 Root CA cert is untrusted, valid until Aug 12 15:51:34 2032, written to 'scep/myca.pem'
 144 Sub CA cert "C=CH, O=strongSwan Project, CN=strongSwan Issuing CA"
 145   ...
 146 Sub CA cert is trusted, valid until Aug 12 15:51:34 2027, 'scep/myca-1.pem'
 147 RA cert "C=CH, O=strongSwan Project, CN=SCEP RA"
 148   ...
 149 RA cert is trusted, valid until Aug 10 15:51:34 2023, 'scep/myca-ra.pem'
 150 .EE
 151 .PP
 152 A CA certificate bundle in PEM format is written to \fIstdout\fR:
 153 .PP
 154 .EX
 155 pki \-\-scepca \-\-url http://pki.strongswan.org:8080/scep --raout myra.crt \-\-outform pem > cacerts.pem
 156 .EE
 157 .PP
 158 .
 159 .SH "SEE ALSO"
 160 .
 161 .BR pki (1)