SSL_CTX_use_PrivateKey_file

The SSL_CTX_use_PrivateKey_file function loads the private key into a specified context (CTX) structure for use by Secure Sockets Layer (SSL) sessions.

Last updated

  • Changed in 2023 (information only; no code change).
  • Changed for PUT06.
  • Changed for PUT00.

Format

LIBS := CSSL 
#include <openssl/ssl.h>
int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type)
ctx
A pointer to a token returned on the SSL_CTX_new call or the SSL_CTX_new_shared call.
file
A pointer to the name of the file that contains the private key. The maximum length of the file name is 255 characters. To use a private key that resides in the z/TPF keystore, specify /tpfpubk/xxx.yyy, where xxx is the z/TPF public key pair name. (yyy is ignored.)
type
The file type. Specify the following value:
SSL_FILETYPE_PEM
The file is in base64 privacy enhanced mail (PEM) format.
Note: This parameter is ignored if you are using a private key that resides in the z/TPF keystore.

Normal return

Return code 1 indicates that the function was successful.

Error return

A return code equal to 0 indicates an error. The following are the most likely causes of errors:
  • The private key file does not exist or you do not have permission to read that file.
  • The private key file is not in PEM format.
  • If the private key file is encrypted, the password is not correct or no password was provided.
  • The specified z/TPF public key pair name does not exist or is not active.
  • If you loaded a certificate file before issuing this function, the public key in that certificate does not match the corresponding private key in the private key file.

Programming considerations

  • To use this function, you must include the library that is specified in the prototype in your makefile.
  • Before calling the SSL_CTX_use_PrivateKey_file function, you must identify the password for the private key file by issuing the SSL_CTX_set_default_passwd_cb_userdata function. Do this only if the private key file has been encrypted. Do not issue the SSL_CTX_set_default_passwd_cb_userdata function if you are using a private key that resides in the z/TPF keystore.
  • If you are assigning many SSL sessions to the same CTX structure and all the sessions will use the same private key file, issue the SSL_CTX_use_PrivateKey_file function once to assign the certificate to the CTX structure rather than issuing the SSL_CTX_use_PrivateKey_file function once for each SSL session.

Examples

For sample SSL applications, see SSL examples.