src/pki/man/pki.1.in

   1 .TH PKI 1 "2013-07-31" "@PACKAGE_VERSION@" "strongSwan"
   2 .
   3 .SH "NAME"
   4 .
   5 pki \- Simple public key infrastructure (PKI) management tool
   6 .
   7 .SH "SYNOPSIS"
   8 .
   9 .SY "pki"
  10 .I command
  11 .RI [ option\~ .\|.\|.]
  12 .YS
  13 .
  14 .SY "pki"
  15 .B \-h
  16 |
  17 .B \-\-help
  18 .YS
  19 .
  20 .SH "DESCRIPTION"
  21 .
  22 .B pki
  23 is a suite of commands that allow you to manage a simple public key
  24 infrastructure (PKI).
  25 .P
  26 Generate RSA and ECDSA key pairs, create PKCS#10 certificate requests
  27 containing subjectAltNames, create X.509 self-signed end-entity and root CA
  28 certificates, issue end-entity and intermediate CA certificates signed by the
  29 private key of a CA and containing subjectAltNames, CRL distribution points
  30 and URIs of OCSP servers. You can also extract raw public keys from private
  31 keys, certificate requests and certificates and compute two kinds of SHA-1-based
  32 key IDs.
  33 .
  34 .SH "COMMANDS"
  35 .
  36 .TP
  37 .B "\-h, \-\-help"
  38 Prints usage information and a short summary of the available commands.
  39 .TP
  40 .B "\-g, \-\-gen"
  41 Generate a new private key.
  42 .TP
  43 .B "\-s, \-\-self"
  44 Create a self-signed certificate.
  45 .TP
  46 .B "\-i, \-\-issue"
  47 Issue a certificate using a CA certificate and key.
  48 .TP
  49 .B "\-c, \-\-signcrl"
  50 Issue a CRL using a CA certificate and key.
  51 .TP
  52 .B "\-z, \-\-acert"
  53 Issue an attribute certificate.
  54 .TP
  55 .B "\-r, \-\-req"
  56 Create a PKCS#10 certificate request.
  57 .TP
  58 .B "\-7, \-\-pkcs7"
  59 Provides PKCS#7 wrap/unwrap functions.
  60 .TP
  61 .B "\-k, \-\-keyid"
  62 Calculate key identifiers of a key or certificate.
  63 .TP
  64 .B "\-a, \-\-print"
  65 Print a credential (key, certificate etc.) in human readable form.
  66 .TP
  67 .B "\-p, \-\-pub"
  68 Extract a public key from a private key or certificate.
  69 .TP
  70 .B "\-v, \-\-verify"
  71 Verify a certificate using a CA certificate.
  72 .
  73 .SH "EXAMPLES"
  74 .
  75 .SS "Generating a CA Certificate"
  76 .
  77 The first step is to generate a private key using the
  78 .B \-\-gen
  79 command. By default this generates a 2048-bit RSA key.
  80 .PP
  81 .EX
  82   pki \-\-gen > ca_key.der
  83 .EE
  84 .PP
  85 This key is used to create the self-signed CA certificate, using the
  86 .B \-\-self
  87 command. The distinguished name should be adjusted to your needs.
  88 .PP
  89 .EX
  90   pki \-\-self \-\-ca \-\-in ca_key.der \\
  91       \-\-dn "C=CH, O=strongSwan, CN=strongSwan CA" > ca_cert.der
  92 .EE
  93 .PP
  94 .
  95 .SS "Generating End-Entity Certificates"
  96 .
  97 With the root CA certificate and key at hand end-entity certificates for clients
  98 and servers can be issued. Similarly intermediate CA certificates can be issued,
  99 which in turn can issue other certificates.
 100 To generate a certificate for a server, we start by generating a private key.
 101 .PP
 102 .EX
 103   pki \-\-gen > server_key.der
 104 .EE
 105 .PP
 106 The public key will be included in the certificate so lets extract that from the
 107 private key.
 108 .PP
 109 .EX
 110   pki \-\-pub \-\-in server_key.der > server_pub.der
 111 .EE
 112 .PP
 113 The following command will use the CA certificate and private key to issue the
 114 certificate for this server. Adjust the distinguished name, subjectAltName(s)
 115 and flags as needed (check
 116 .BR pki\ \-\-issue (8)
 117 for more options).
 118 .PP
 119 .EX
 120   pki \-\-issue \-\-in server_pub.der \-\-cacert ca_cert.der \\
 121       \-\-cakey ca_key.der \-\-dn "C=CH, O=strongSwan, CN=VPN Server" \\
 122       \-\-san vpn.strongswan.org \-\-flag serverAuth > server_cert.der
 123 .EE
 124 .PP
 125 Instead of storing the public key in a separate
 126 file, the output of
 127 .B \-\-pub
 128 may also be piped directly into the above command.
 129 .
 130 .SS "Generating Certificate Revocation Lists (CRL)"
 131 .
 132 If end-entity certificates have to be revoked, CRLs may be generated using
 133 the
 134 .B \-\-signcrl
 135 command.
 136 .PP
 137 .EX
 138   pki \-\-signcrl \-\-cacert ca_cert.der \-\-cakey ca_key.der \\
 139       \-\-reason superseded \-\-cert server_cert.der > crl.der
 140 .EE
 141 .PP
 142 The certificate given with \-\-cacert must be either a CA certificate or a
 143 certificate with the
 144 .I crlSign
 145 extended key usage (\-\-flag crlSign). URIs to CRLs may be included in issued
 146 certificates with the \-\-crl option.
 147 .
 148 .SH "SEE ALSO"
 149 .
 150 .BR pki\ \-\-gen (1),
 151 .BR pki\ \-\-self (1),
 152 .BR pki\ \-\-issue (1),
 153 .BR pki\ \-\-signcrl (1),
 154 .BR pki\ \-\-acert (1),
 155 .BR pki\ \-\-req (1),
 156 .BR pki\ \-\-pkcs7 (1),
 157 .BR pki\ \-\-keyid (1),
 158 .BR pki\ \-\-print (1),
 159 .BR pki\ \-\-pub (1),
 160 .BR pki\ \-\-verify (1)