index.rst (3617B)
1 .. _mozilla_projects_nss_ssl_functions_sslkey: 2 3 sslkey 4 ====== 5 6 .. container:: 7 8 .. note:: 9 10 - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that 11 we are migrating into the format described in the `MDN Style 12 Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to 13 help with this migration, your help would be very much appreciated. 14 15 - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` 16 17 .. rubric:: Key Functions 18 :name: Key_Functions 19 20 -------------- 21 22 .. _chapter_6_key_functions: 23 24 `Chapter 6 25 <#chapter_6_key_functions>`__ Key Functions 26 -------------------------------------------- 27 28 .. container:: 29 30 This chapter describes two functions used to manipulate private keys and key databases such as 31 the ``key3.db`` database provided with Communicator. 32 33 | ```SECKEY_GetDefaultKeyDB`` <#1051479>`__ 34 | ```SECKEY_DestroyPrivateKey`` <#1051017>`__ 35 36 .. rubric:: SECKEY_GetDefaultKeyDB 37 :name: seckey_getdefaultkeydb 38 39 Returns a handle to the default key database opened by 40 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`. 41 42 .. rubric:: Syntax 43 :name: syntax 44 45 .. code:: 46 47 #include <key.h> 48 #include <keyt.h> 49 50 .. code:: 51 52 SECKEYKeyDBHandle *SECKEY_GetDefaultKeyDB(void); 53 54 .. rubric:: Returns 55 :name: returns 56 57 The function returns a handle of type ``SECKEYKeyDBHandle``. 58 59 .. rubric:: Description 60 :name: description 61 62 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601` opens the certificate, key, and security 63 module databases that you specify for use with NSS. ``SECKEYKeyDBHandle`` returns a handle to the 64 key database opened by ``NSS_Init``. 65 66 .. rubric:: SECKEY_DestroyPrivateKey 67 :name: seckey_destroyprivatekey 68 69 Destroys a private key structure. 70 71 .. rubric:: Syntax 72 :name: syntax_2 73 74 .. code:: 75 76 #include <key.h> 77 #include <keyt.h> 78 79 .. code:: 80 81 void SECKEY_DestroyPrivateKey(SECKEYPrivateKey *key); 82 83 .. rubric:: Parameter 84 :name: parameter 85 86 This function has the following parameter: 87 88 +-------------------------------------------------+-------------------------------------------------+ 89 | .. code:: | A pointer to the private key structure to | 90 | | destroy. | 91 | key | | 92 +-------------------------------------------------+-------------------------------------------------+ 93 94 .. rubric:: Description 95 :name: description_2 96 97 Certificate and key structures are shared objects. When an application makes a copy of a 98 particular certificate or key structure that already exists in memory, SSL makes a *shallow* 99 copy--that is, it increments the reference count for that object rather than making a whole new 100 copy. When you call ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ or 101 ```SECKEY_DestroyPrivateKey`` <#1051017>`__, the function decrements the reference count and, if 102 the reference count reaches zero as a result, both frees the memory and sets all the bits to 103 zero. The use of the word "destroy" in function names or in the description of a function implies 104 reference counting. 105 106 Never alter the contents of a certificate or key structure. If you attempt to do so, the change 107 affects all the shallow copies of that structure and can cause severe problems.