add temp key bindings

[jmayclin]

This PR adds bindings for a selection of the "temp key" apis.

https://www.openssl.org/docs/manmaster/man3/SSL_get_peer_tmp_key.html

These functions are implemented using the ctrl macro. Constants are taken from

https://github.com/openssl/openssl/blob/497a7810bcee48781aa12d4db870f6a565bd0592/include/openssl/ssl.h.in#L1314

https://github.com/openssl/openssl/blob/497a7810bcee48781aa12d4db870f6a565bd0592/include/openssl/ssl.h.in#L1334

API Shape

The api's return a Result<PKey> rather than a Result<Option<PKey>>, because it is expected that whenever the function returns a non-error value, the key is valid. This can be seen from the implementation of the function in openssl source:
https://github.com/openssl/openssl/blob/186b3f6a016de8fcf8573be111e3d174ca20f1bc/ssl/s3_lib.c#L3734-L3741

Macro Return Value

The Openssl ctrl macros return c_long, but the functions implemented the macros normally downcast this to a c_int. The tmp_key apis do not downcast this value, and instead return a c_long. I added an additional cvt_long error function to handle this.

History

The man pages don't mention anything about the history of the function and I couldn't find anything in the changelog so I dug through the openssl git repository to find the commit that introduced the tmp_key apis.

commit a51c9f637cdef7926d8a8991365e4b58975346db
Author: Viktor Dukhovni <[email protected]>
Date:   Sat Nov 10 01:53:56 2018 -0500

    Added missing signature algorithm reflection functions
    
        SSL_get_signature_nid()      -- local signature algorithm
        SSL_get_signature_type_nid() -- local signature algorithm key type
        SSL_get_peer_tmp_key()       -- Peer key-exchange public key
        SSL_get_tmp_key              -- local key exchange public key
    
    Aliased pre-existing SSL_get_server_tmp_key(), which was formerly
    just for clients, to SSL_get_peer_tmp_key().  Changed internal
    calls to use the new name.
    
    Reviewed-by: Matt Caswell <[email protected]>

I then pulled in git branches until I found the ones that contained the feature commit.

~/workspace/openssl$ git branch
  OpenSSL_1_0_2-stable
  OpenSSL_1_1_0-stable
  OpenSSL_1_1_1-stable
  master
* openssl-3.0
~/workspace/openssl$ git branch --contains a51c9f637cdef7926d8a8991365e4b58975346db
  master
* openssl-3.0

From this, I concluded that the APIs were first available in Openssl 3.0.0

[jmayclin]

The CI is failing because my cfg-gated definitions are causing "unused import" and "unused function" errors.

 error: unused imports: `PKey`, `Public`
  --> openssl/src/ssl/mod.rs:70:31
   |
70 | use crate::pkey::{HasPrivate, PKey, PKeyRef, Params, Private, Public};
   |                               ^^^^                            ^^^^^^
   |
   = note: `-D unused-imports` implied by `-D warnings`

error: unused import: `cvt_long`
  --> openssl/src/ssl/mod.rs:81:18
   |
81 | use crate::{cvt, cvt_long, cvt_n, cvt_p, init};
   |                  ^^^^^^^^

error: function `cvt_long` is never used
   --> openssl/src/lib.rs:216:4
    |
216 | fn cvt_long(r: c_long) -> Result<c_long, ErrorStack> {
    |    ^^^^^^^^
    |
    = note: `-D dead-code` implied by `-D warnings`

I think the neatest way to solve this from my side is by gating the import statements/definitions behind cfg(ossl300) statements. It does seem a little odd to gate the definition of cvt_long on the openssl version, but I think that's the easiest way to work with the current CI setup. Let me know if you have different thoughts. 🙂

[sfackler]

Yeah cfg'ing the imports off is the way to go.

[jmayclin]

Hi @sfackler, I'm wondering if I could have another review on this? Thanks!

[sfackler]

Thanks!