I'm finding the documentation (man page) for libssh2_userauth_publickey_fromfile() confusing.

Firstly, it has parameters for both a public key file and a private key file. Why? My experience with SSH involves the server having a copy of my public key, so why would it need to be provided here? I am also aware of the 'certificate' model in which my public key would be signed by a CA, in which case I guess that the server would not necessarily have a copy, I can imagine instead it being sent to the server and the server trusting this as authenticating who you are via trusting the CA signature. Is this the reason for the public key param, to pass to the server a local CA signed copy of your public key? In which case do you thus only need to use this param for the 'certificate' based model?

I did wonder at one point whether the public key file parameter might be the public key of the server you want to connect to, but I think not. Perhaps you could understand how a user of this API could wonder this though?

Secondly, the title of the manpage states authenticate a session with a public key, read from a file, while at the end of the description there's Attempt public key authentication using a PEM encoded private key file stored on disk. Perhaps the title should say something more like authenticate a session with public-key cryptography, using a key or key-pair read from a file to indicate that "public key" in that case refers to public-key cryptography to avoid confusion with the public key in a key pair and thus the public key file param? The second case should explain how the public key file comes into things.

Could you please explain, and clarify the documentation.