172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling 672613Skris 772613Skris=head1 SYNOPSIS 872613Skris 972613Skris #include <openssl/ssl.h> 1072613Skris 1172613Skris void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); 1272613Skris void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); 1372613Skris 1472613Skris int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata); 1572613Skris 1672613Skris=head1 DESCRIPTION 1772613Skris 1872613SkrisSSL_CTX_set_default_passwd_cb() sets the default password callback called 1972613Skriswhen loading/storing a PEM certificate with encryption. 2072613Skris 2172613SkrisSSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which 2272613Skriswill be provided to the password callback on invocation. 2372613Skris 2472613SkrisThe pem_passwd_cb(), which must be provided by the application, hands back the 2572613Skrispassword to be used during decryption. On invocation a pointer to B<userdata> 2672613Skrisis provided. The pem_passwd_cb must write the password into the provided buffer 2772613SkrisB<buf> which is of size B<size>. The actual length of the password must 2872613Skrisbe returned to the calling function. B<rwflag> indicates whether the 2972613Skriscallback is used for reading/decryption (rwflag=0) or writing/encryption 3072613Skris(rwflag=1). 3172613Skris 3272613Skris=head1 NOTES 3372613Skris 3472613SkrisWhen loading or storing private keys, a password might be supplied to 3572613Skrisprotect the private key. The way this password can be supplied may depend 3672613Skrison the application. If only one private key is handled, it can be practical 3772613Skristo have pem_passwd_cb() handle the password dialog interactively. If several 3872613Skriskeys have to be handled, it can be practical to ask for the password once, 3972613Skristhen keep it in memory and use it several times. In the last case, the 4072613Skrispassword could be stored into the B<userdata> storage and the 4172613Skrispem_passwd_cb() only returns the password already stored. 4272613Skris 4389837SkrisWhen asking for the password interactively, pem_passwd_cb() can use 4489837SkrisB<rwflag> to check, whether an item shall be encrypted (rwflag=1). 4589837SkrisIn this case the password dialog may ask for the same password twice 4689837Skrisfor comparison in order to catch typos, that would make decryption 4789837Skrisimpossible. 4889837Skris 4972613SkrisOther items in PEM formatting (certificates) can also be encrypted, it is 5072613Skrishowever not usual, as certificate information is considered public. 5172613Skris 5272613Skris=head1 RETURN VALUES 5372613Skris 5472613SkrisSSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata() 5572613Skrisdo not provide diagnostic information. 5672613Skris 5772613Skris=head1 EXAMPLES 5872613Skris 5972613SkrisThe following example returns the password provided as B<userdata> to the 6072613Skriscalling function. The password is considered to be a '\0' terminated 6172613Skrisstring. If the password does not fit into the buffer, the password is 6272613Skristruncated. 6372613Skris 6472613Skris int pem_passwd_cb(char *buf, int size, int rwflag, void *password) 6572613Skris { 6672613Skris strncpy(buf, (char *)(password), size); 6772613Skris buf[size - 1] = '\0'; 6872613Skris return(strlen(buf)); 6972613Skris } 7072613Skris 7172613Skris=head1 SEE ALSO 7272613Skris 7372613SkrisL<ssl(3)|ssl(3)>, 7472613SkrisL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> 7572613Skris 7672613Skris=cut 77