Tldr: curl: improve last example

[waldyrious]

The last example in the curl.md page is:

- Pass client certificate and key for a secure resource:

`curl -v -key {{key.pem}} -cacert {{ca.pem}} -cert {{client.pem}} -k {{https://example.com}}`

There are a few issues with this:

• It appears that the full-word options require double dashes. We need to confirm this and change accordingly
• The relationship between --key, --cert and --cacert is unclear to me (i.e. how the latter two differ, which depend on which, which are meant to be used together, etc.)
• The -v is not necessarily related to that example, so by including it (which requires mentioning it in the description, as pointed out in #1240) makes it hard to make the description concise; it would be better to remove it (maybe moving it a simpler example?).

I haven't used curl much, so I'll defer to @imjacobclark who originally contributed this example in #735, as well as @rubenvereecken, @igorshubovych and @ostera who participated in that discussion, and also @agnivade who raised the topic in #1240.

[morrme]

I have just tested this, and the full-word options work with both single and double dashes. It may still be useful to go with the conventions used in the documentation of this command, or possibly mention that either way works fine.

[waldyrious]

Let's just use double dashes, no need to reinforce nonstandard option formats :) would you like to submit a PR making that change, @morrme?

[morrme]

@waldyrious sure. should i remove -v at the same time?

[morrme]

@waldyrious this is done and ready for review.

[waldyrious]

This issue is not yet entirely resolved -- the unclarity of --key, --cert and --cacert should probably be resolved. Quoting the first comment:

The relationship between --key, --cert and --cacert is unclear to me (i.e. how the latter two differ, which depend on which, which are meant to be used together, etc.)

[morrme]

@waldyrious --cert is the individual cert file, --cacert is the cert of the Certificate Authority (that granted the cert ) , and --key is the location of the private key.

[waldyrious]

@morrme thanks for the clarification. Do you have any suggestion about how the example description could be improved to make this clear? I tried to rewrite it, but the best I could come up with was excessively long:

Pass client certificate, key and Certification Authority certificate for a secure resource:
curl --key {{key.pem}} --cacert {{ca.pem}} --cert {{client.pem}} -k {{https://example.com}}

[agnivade]

Do we really need --cacert for it to work ? I am no security expert but AFAIR, I never used this.

[morrme]

@agnivade --cacert is only required when the CA in question is not already in the "approved"/built in list of CAs, for example an internal CA

[agnivade]

Right, so isn't that a rare case ?

[morrme]

@agnivade i'd say so.

[agnivade]

Ok, so I suggest we leave it out. Will make the description shorter and simpler.

[agnivade]

@waldyrious / @morrme - I believe this can be closed. We agreed that --cacert is not needed for tldr's scope.

[waldyrious]

@agnivade right, good catch. This was fixed in cf046b5. I'm not sure why I made a direct commit rather than a PR, but either it was a mistake (pressed the wrong button) or I considered that the discussion had already reached a consensus here -- in which case, I should have added "(closes #1246)" to the commit message, and didn't as an overlook. Either way, closing now. Thanks all!