cpw.ljfisher.ssl_client_auth: 90f2d555: Added doc on design/use of PurplePrivate..
lucas.fisher at gmail.com
lucas.fisher at gmail.com
Sat Nov 26 00:31:14 EST 2011
----------------------------------------------------------------------
Revision: 90f2d55572b4552444730fab9968ddbade1edee1
Parent: 4c8b52af3da1f98d92cfb7a0605058efda168d6d
Author: lucas.fisher at gmail.com
Date: 11/26/11 00:17:47
Branch: im.pidgin.cpw.ljfisher.ssl_client_auth
URL: http://d.pidgin.im/viewmtn/revision/info/90f2d55572b4552444730fab9968ddbade1edee1
Changelog:
Added doc on design/use of PurplePrivateKey
Changes against parent 4c8b52af3da1f98d92cfb7a0605058efda168d6d
patched libpurple/privatekey.h
-------------- next part --------------
============================================================
--- libpurple/privatekey.h 912c0eaa58d077a2d793ab0eaebd69d0d96801b9
+++ libpurple/privatekey.h 3d84363651cde27970e44e7e86debcff218492b1
@@ -2,7 +2,64 @@
* @file privatekey.h Private-Key API
* @ingroup core
* @see @ref privatekey-signals
- * @since 2.2.0
+ * @since 3.0.0
+ *
+ * Purple abstraction for private keys used for cryptographic authentication.
+ * E.g., SSL/TLS client authentication. PurplePrivateKey serves as the counterpart
+ * for PurpleCertificate for storing the secret key associated with a certificate.
+ *
+ *
+ * For PurplePrivateKey Users:
+ *
+ * PurplePrivateKey provides an interface analogous to PurpleCertificate. It includes
+ * functions for loading and storing keys to a file and getting information about a
+ * key. A pool for managing multiple keys, PurplePrivateKeyPool, analogous to
+ * PurpleCertificatePool is also available.
+ *
+ * Where PurplePrivateKey differs significantly is in the need to get passwords
+ * from the user in order to encrypt and decrypt keys when they are stored on
+ * disk. The PurplePrivateKey and PurplePrivateKeyPool functions to store and retrive
+ * keys on disk take a
+ * password as an agrument which will be used by the underlying implementation
+ * to encrypt the keys.
+ *
+ * To facilitate getting a password from the use for protecting keys
+ * PurplePrivateKeyPool includes additional functions for key store and retrieve
+ * requests. These functions will prompt the user for a password for the key
+ * using the registered ui_ops functions.
+ *
+ * So all users of libpurple can share private keys and associated certificates
+ * following the convention of using the same pool id for the private key
+ * as for the associated certificate. That is, if I look up id "myidentifier"
+ * in a PurpleCertificatePool and in PurplePrivateKeyPool I should get a certificate
+ * and its private key, respectively.
+ *
+ * Currently, the User pools use the certificates distinguished name as returned
+ * by purple_certificate_get_unique_id().
+ *
+ *
+ * For PurplePrivateKey Implementers:
+ *
+ * Implementers of PurplePrivateKey must take steps to protect keys. This includes:
+ * <ol>
+ * <li>
+ * Storing keys encrypted on disk using a well-known, standard, tested format,
+ * such as PKCS8 or PKCS12, that uses a password to encrypt the keys.
+ * </li>
+ * <li>
+ * Keys should not be swapped out to disk. This usually means they must be stored in
+ * non-paged (or locked) memory pages.
+ * </li>
+ * <li>
+ * As soon as keys are no longer needed immediately for processes the memory containing
+ * they keys should be zeroed and free-ed.
+ * </li>
+ * </ol>
+ *
+ * While passwords are currently used to protect keys other mechanisms should be
+ * entertained. This could include common desktop key storage (e.g. gnome keyring,
+ * kdewallet) or PKCS11 for compatibility with hardware keystores (smartcards,
+ * usb crypto keys, etc.).
*/
/*
More information about the Commits
mailing list