1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
   12:             RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
   13:  long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
   14:  long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
   15: 
   16:  void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
   17:             RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
   18:  long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
   19:  long SSL_need_tmp_rsa(SSL *ssl)
   20: 
   21:  RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength);
   22: 
   23: =head1 DESCRIPTION
   24: 
   25: SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be
   26: used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>.
   27: The callback is inherited by all SSL objects newly created from B<ctx>
   28: with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected.
   29: 
   30: SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be
   31: B<rsa>. The key is inherited by all SSL objects newly created from B<ctx>
   32: with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected.
   33: 
   34: SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed
   35: for RSA-based strength-limited 'exportable' ciphersuites because a RSA key
   36: with a keysize larger than 512 bits is installed.
   37: 
   38: SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>.
   39: 
   40: SSL_set_tmp_rsa() sets the key only for B<ssl>.
   41: 
   42: SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed,
   43: for RSA-based strength-limited 'exportable' ciphersuites because a RSA key
   44: with a keysize larger than 512 bits is installed.
   45: 
   46: These functions apply to SSL/TLS servers only.
   47: 
   48: =head1 NOTES
   49: 
   50: When using a cipher with RSA authentication, an ephemeral RSA key exchange
   51: can take place. In this case the session data are negotiated using the
   52: ephemeral/temporary RSA key and the RSA key supplied and certified
   53: by the certificate chain is only used for signing.
   54: 
   55: Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
   56: than the usual key length of 1024 bits were created. To use these ciphers
   57: with RSA keys of usual length, an ephemeral key exchange must be performed,
   58: as the normal (certified) key cannot be directly used.
   59: 
   60: Using ephemeral RSA key exchange yields forward secrecy, as the connection
   61: can only be decrypted, when the RSA key is known. By generating a temporary
   62: RSA key inside the server application that is lost when the application
   63: is left, it becomes impossible for an attacker to decrypt past sessions,
   64: even if he gets hold of the normal (certified) RSA key, as this key was
   65: used for signing only. The downside is that creating a RSA key is
   66: computationally expensive.
   67: 
   68: Additionally, the use of ephemeral RSA key exchange is only allowed in
   69: the TLS standard, when the RSA key can be used for signing only, that is
   70: for export ciphers. Using ephemeral RSA key exchange for other purposes
   71: violates the standard and can break interoperability with clients.
   72: It is therefore strongly recommended to not use ephemeral RSA key
   73: exchange and use EDH (Ephemeral Diffie-Hellman) key exchange instead
   74: in order to achieve forward secrecy (see
   75: L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
   76: 
   77: On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default
   78: and must be explicitly enabled  using the SSL_OP_EPHEMERAL_RSA option of
   79: L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, violating the TLS/SSL
   80: standard. When ephemeral RSA key exchange is required for export ciphers,
   81: it will automatically be used without this option!
   82: 
   83: An application may either directly specify the key or can supply the key via
   84: a callback function. The callback approach has the advantage, that the
   85: callback may generate the key only in case it is actually needed. As the
   86: generation of a RSA key is however costly, it will lead to a significant
   87: delay in the handshake procedure.  Another advantage of the callback function
   88: is that it can supply keys of different size (e.g. for SSL_OP_EPHEMERAL_RSA
   89: usage) while the explicit setting of the key is only useful for key size of
   90: 512 bits to satisfy the export restricted ciphers and does give away key length
   91: if a longer key would be allowed.
   92: 
   93: The B<tmp_rsa_callback> is called with the B<keylength> needed and
   94: the B<is_export> information. The B<is_export> flag is set, when the
   95: ephemeral RSA key exchange is performed with an export cipher.
   96: 
   97: =head1 EXAMPLES
   98: 
   99: Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the
  100: generation of a RSA key costs a lot of computer time, they saved for later
  101: reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
  102: respectively are generated.
  103: 
  104:  ...
  105:  /* Set up ephemeral RSA stuff */
  106:  RSA *rsa_512 = NULL;
  107:  RSA *rsa_1024 = NULL;
  108: 
  109:  rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
  110:  if (rsa_512 == NULL)
  111:      evaluate_error_queue();
  112: 
  113:  rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
  114:  if (rsa_1024 == NULL)
  115:    evaluate_error_queue();
  116: 
  117:  ...
  118: 
  119:  RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
  120:  {
  121:     RSA *rsa_tmp=NULL;
  122: 
  123:     switch (keylength) {
  124:     case 512:
  125:       if (rsa_512)
  126:         rsa_tmp = rsa_512;
  127:       else { /* generate on the fly, should not happen in this example */
  128:         rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL);
  129:         rsa_512 = rsa_tmp; /* Remember for later reuse */
  130:       }
  131:       break;
  132:     case 1024:
  133:       if (rsa_1024)
  134:         rsa_tmp=rsa_1024;
  135:       else
  136:         should_not_happen_in_this_example();
  137:       break;
  138:     default:
  139:       /* Generating a key on the fly is very costly, so use what is there */
  140:       if (rsa_1024)
  141:         rsa_tmp=rsa_1024;
  142:       else
  143:         rsa_tmp=rsa_512; /* Use at least a shorter key */
  144:     }
  145:     return(rsa_tmp);
  146:  }
  147: 
  148: =head1 RETURN VALUES
  149: 
  150: SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return
  151: diagnostic output.
  152: 
  153: SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0
  154: on failure. Check the error queue to find out the reason of failure.
  155: 
  156: SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary
  157: RSA key is needed and 0 otherwise.
  158: 
  159: =head1 SEE ALSO
  160: 
  161: L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
  162: L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
  163: L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
  164: L<SSL_new(3)|SSL_new(3)>, L<ciphers(1)|ciphers(1)>
  165: 
  166: =cut