patches/curl/q/t_docs_manpage.diff

   1 Subject: [PATCH] curl.1: update to match code
   2
   3 The curl.1 man page contains various information that is actually
   4 misleading about the version of darwinssl (SecureTransport) code
   5 included in this build.
   6
   7 Update it to provide accurate information.
   8
   9 Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
  10
  11 ---
  12  docs/curl.1 | 82 +++++++++++++++++++++++++------------------------------------
  13  1 file changed, 33 insertions(+), 49 deletions(-)
  14
  15 diff --git a/docs/curl.1 b/docs/curl.1
  16 index f5375ed7..be997c9e 100644
  17 --- a/docs/curl.1
  18 +++ b/docs/curl.1
  19 @@ -18,6 +18,9 @@
  20  .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  21  .\" * KIND, either express or implied.
  22  .\" *
  23 +.\" * Updates for improved DarwinSSL vtls Copyright (C) 2016 Kyle J. McKay.
  24 +.\" * All rights reserved.
  25 +.\" *
  26  .\" **************************************************************************
  27  .\"
  28  .TH curl 1 "30 Nov 2014" "Curl 7.40.0" "Curl Manual"
  29 @@ -330,6 +333,9 @@ List that may specify peer certificates that are to be considered revoked.
  30
  31  If this option is used several times, the last one will be used.
  32
  33 +This option is NOT supported in this build.  Certificates may be added to the
  34 +System keychain and marked as "Never Trust" as an alternative.
  35 +
  36  (Added in 7.19.7)
  37  .IP "-d, --data <data>"
  38  (HTTP) Sends the specified data in a POST request to the HTTP server, in the
  39 @@ -503,28 +509,18 @@ automatically set the previous URL when it follows a Location: header. The
  40  If this option is used several times, the last one will be used.
  41  .IP "-E, --cert <certificate[:password]>"
  42  (SSL) Tells curl to use the specified client certificate file when getting a
  43 -file with HTTPS, FTPS or another SSL-based protocol. The certificate must be
  44 -in PKCS#12 format if using Secure Transport, or PEM format if using any other
  45 -engine.  If the optional password isn't specified, it will be queried for on
  46 -the terminal. Note that this option assumes a \&"certificate" file that is the
  47 -private key and the client certificate concatenated! See \fI--cert\fP and
  48 +file with HTTPS, FTPS or another SSL-based protocol. The client certificate(s)
  49 +must be in PEM format.  If the optional password isn't specified, it will be
  50 +queried for.  Note that this option assumes a \&"certificate" file that is the
  51 +private key and the client certificate(s) concatenated! See \fI--cert\fP and
  52  \fI--key\fP to specify them independently.
  53
  54 -If curl is built against the NSS SSL library then this option can tell
  55 -curl the nickname of the certificate to use within the NSS database defined
  56 -by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the
  57 -NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be
  58 -loaded. If you want to use a file from the current directory, please precede
  59 -it with "./" prefix, in order to avoid confusion with a nickname.  If the
  60 -nickname contains ":", it needs to be preceded by "\\" so that it is not
  61 -recognized as password delimiter.  If the nickname contains "\\", it needs to
  62 -be escaped as "\\\\" so that it is not recognized as an escape character.
  63 -
  64 -(iOS and macOS only) If curl is built against Secure Transport, then the
  65 -certificate string can either be the name of a certificate/private key in the
  66 -system or user keychain, or the path to a PKCS#12-encoded certificate and
  67 -private key. If you want to use a file from the current directory, please
  68 -precede it with "./" prefix, in order to avoid confusion with a nickname.
  69 +The certificate string can either be the name of a certificate/private key in
  70 +the system or user keychain, or the path to a PEM format certificate(s) and
  71 +(optioanlly) private key file. If you want to use a file from the current
  72 +directory, please precede it with "./" prefix, in order to avoid confusion with
  73 +a nickname.  Note that if the client certificate is located in the user/system
  74 +keychain then the password must also be in the keychain.
  75
  76  If this option is used several times, the last one will be used.
  77  .IP "--engine <name>"
  78 @@ -549,7 +545,9 @@ curl stops waiting, it will continue as if the response has been received.
  79  (Added in 7.47.0)
  80  .IP "--cert-type <type>"
  81  (SSL) Tells curl what certificate type the provided certificate is in. PEM,
  82 -DER and ENG are recognized types.  If not specified, PEM is assumed.
  83 +DER and ENG are recognized types.  If not specified, PEM is assumed.  Use of
  84 +DER format is not recommended as only a single client leaf certificate is
  85 +supported in that case.
  86
  87  If this option is used several times, the last one will be used.
  88  .IP "--cacert <CA certificate>"
  89 @@ -558,22 +556,9 @@ file may contain multiple CA certificates. The certificate(s) must be in PEM
  90  format. Normally curl is built to use a default file for this, so this option
  91  is typically used to alter that default file.
  92
  93 -curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is
  94 -set, and uses the given path as a path to a CA cert bundle. This option
  95 -overrides that variable.
  96 -
  97 -The windows version of curl will automatically look for a CA certs file named
  98 -\'curl-ca-bundle.crt\', either in the same directory as curl.exe, or in the
  99 -Current Working Directory, or in any folder along your PATH.
 100 -
 101 -If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module
 102 -(libnsspem.so) needs to be available for this option to work properly.
 103 -
 104 -(iOS and macOS only) If curl is built against Secure Transport, then this
 105 -option is supported for backward compatibility with other SSL engines, but it
 106 -should not be set. If the option is not set, then curl will use the
 107 -certificates in the system and user Keychain to verify the peer, which is the
 108 -preferred method of verifying the peer's certificate chain.
 109 +If this option is not set, then curl will use the certificates in the system
 110 +and user Keychains to verify the peer, which is the preferred method of
 111 +verifying the peer's certificate chain.
 112
 113  If this option is used several times, the last one will be used.
 114  .IP "--capath <CA certificate directory>"
 115 @@ -587,27 +572,25 @@ OpenSSL-powered curl to make SSL-connections much more efficiently than using
 116
 117  If this option is set, the default capath value will be ignored, and if it is
 118  used several times, the last one will be used.
 119 +
 120 +This option is NOT supported with this SecureTransport-based build of curl.
 121  .IP "--pinnedpubkey <pinned public key (hashes)>"
 122  (SSL) Tells curl to use the specified public key file (or hashes) to verify the
 123  peer. This can be a path to a file which contains a single public key in PEM or
 124  DER format, or any number of base64 encoded sha256 hashes preceded by
 125 -\'sha256//\' and separated by \';\'
 126 +\'sha256//\' and separated by \';\'.
 127 +
 128 +Additionally, if this is a path to a file, the file may also contain a single
 129 +DER format certificate or one or more PEM format certificates/public keys in
 130 +which case the public keys are automatically extracted from the certificates.
 131
 132  When negotiating a TLS or SSL connection, the server sends a certificate
 133  indicating its identity. A public key is extracted from this certificate and
 134  if it does not exactly match the public key provided to this option, curl will
 135  abort the connection before sending or receiving any data.
 136
 137 -PEM/DER support:
 138 -  7.39.0: OpenSSL, GnuTLS and GSKit
 139 -  7.43.0: NSS and wolfSSL/CyaSSL
 140 -  7.47.0: mbedtls
 141 -  7.49.0: PolarSSL
 142 -sha256 support:
 143 -  7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL/CyaSSL.
 144 -  7.47.0: mbedtls
 145 -  7.49.0: PolarSSL
 146 -Other SSL backends not supported.
 147 +Although this is a SecureTransport-based build of curl, it DOES support both
 148 +PEM/DER format files AND sha256 hashes.
 149
 150  If this option is used several times, the last one will be used.
 151  .IP "--cert-status"
 152 @@ -618,7 +601,8 @@ If this option is enabled and the server sends an invalid (e.g. expired)
 153  response, if the response suggests that the server certificate has been revoked,
 154  or no response at all is received, the verification fails.
 155
 156 -This is currently only implemented in the OpenSSL, GnuTLS and NSS backends.
 157 +This is currently only implemented in the OpenSSL, GnuTLS and NSS backends which
 158 +means it is NOT supported in this build.
 159  (Added in 7.41.0)
 160  .IP "--false-start"
 161
 162 ---