index.rst (11415B)
1 .. _mozilla_projects_nss_ssl_functions_ssltyp: 2 3 ssltyp 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/Project:MDC_style_guide>`__. If you are 13 inclined to 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:: Selected SSL Types and Structures 18 :name: Selected_SSL_Types_and_Structures 19 20 -------------- 21 22 .. _chapter_3_selected_ssl_types_and_structures: 23 24 `Chapter 3 25 <#chapter_3_selected_ssl_types_and_structures>`__ Selected SSL Types and Structures 26 ------------------------------------------------------------------------------------ 27 28 .. container:: 29 30 This chapter describes some of the most important types and structures used with the functions 31 described in the rest of this document, and how to manage the memory used for them. Additional 32 types are described with the functions that use them or in the header files. 33 34 | `Types and Structures <#1030559>`__ 35 | `Managing SECItem Memory <#1029645>`__ 36 37 .. _types_and_structures: 38 39 `Types and Structures <#types_and_structures>`__ 40 ------------------------------------------------ 41 42 .. container:: 43 44 These types and structures are described here: 45 46 | ```CERTCertDBHandle`` <#1028465>`__ 47 | ```CERTCertificate`` <#1027387>`__ 48 | ```PK11SlotInfo`` <#1028593>`__ 49 | ```SECItem`` <#1026076>`__ 50 | ```SECKEYPrivateKey`` <#1026727>`__ 51 | ```SECStatus`` <#1026722>`__ 52 53 Additional types used by a single function only are described with the function's entry in each 54 chapter. Some of these functions also use types defined by NSPR and described in the `NSPR 55 Reference <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference>`__. 56 57 <a id="> Many of the structures presented here (```CERTCertDBHandle`` <#1028465>`__, 58 ```CERTCertificate`` <#1027387>`__, ```PK11SlotInfo`` <#1028593>`__, and 59 ```SECKEYPrivateKey`` <#1026727>`__) are opaque--that is, they are types defined as structures 60 (for example, ``CERTCertDBHandleStr``) that may change in future releases of Network Security 61 Services. As long as you use the form shown here, your code will not need revision. 62 63 .. rubric:: CERTCertDBHandle 64 :name: certcertdbhandle 65 66 An opaque handle structure for open certificate databases. 67 68 .. rubric:: Syntax 69 :name: syntax 70 71 .. code:: 72 73 #include <certt.h> 74 75 .. code:: 76 77 typedef struct CERTCertDBHandleStr CERTCertDBHandle; 78 79 .. rubric:: CERTCertificate 80 :name: certcertificate 81 82 An opaque X.509 certificate object. 83 84 .. rubric:: Syntax 85 :name: syntax_2 86 87 .. code:: 88 89 #include <certt.h> 90 91 .. code:: 92 93 typedef struct CERTCertificateStr CERTCertificate; 94 95 .. rubric:: Description 96 :name: description 97 98 Certificate structures are shared objects. When an application makes a copy of a particular 99 certificate structure that already exists in memory, SSL makes a *shallow* copy--that is, it 100 increments the reference count for that object rather than making a whole new copy. When you call 101 ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__, the function decrements the reference 102 count and, if the reference count reaches zero as a result, frees the memory. The use of the word 103 "destroy" in function names or in the description of a function often implies reference counting. 104 105 Never alter the contents of a certificate structure. If you attempt to do so, the change affects 106 all the shallow copies of that structure and can cause severe problems. 107 108 .. rubric:: PK11SlotInfo 109 :name: pk11slotinfo 110 111 An opaque structure representing a physical or logical PKCS #11 slot. 112 113 .. rubric:: Syntax 114 :name: syntax_3 115 116 .. code:: 117 118 #include <pk11expt.h> 119 120 ``typedef struct PK11SlotInfo``\ Str ``PK11SlotInfo``; 121 122 .. rubric:: SECItem 123 :name: secitem 124 125 A structure that points to other structures. 126 127 .. rubric:: Syntax 128 :name: syntax_4 129 130 .. code:: 131 132 #include <seccomon.h> 133 #include <prtypes.h> 134 #include <secport.h> 135 136 .. code:: 137 138 typedef enum { 139 siBuffer, 140 siClearDataBuffer, 141 siCipherDataBuffer, 142 siDERCertBuffer, 143 siEncodedCertBuffer, 144 siDERNameBuffer, 145 siEncodedNameBuffer, 146 siAsciiNameString, 147 siAsciiString, 148 siDEROID 149 } SECItemType; 150 151 .. code:: 152 153 typedef struct SECItemStr SECItem; 154 155 .. code:: 156 157 struct SECItemStr { 158 SECItemType type; 159 unsigned char *data; 160 unsigned int len; 161 }; 162 163 .. rubric:: Description 164 :name: description_2 165 166 A ``SECItem`` structure can be used to associate your own data with an SSL socket. 167 168 To free a structure pointed to by a ``SECItem``, and, if desired, the ``SECItem`` structure 169 itself, use one the functions ```SECItem_FreeItem`` <#1030620>`__ or 170 ```SECItem_ZfreeItem`` <#1030773>`__. 171 172 .. rubric:: SECKEYPrivateKey 173 :name: seckeyprivatekey 174 175 An opaque, generic key structure. 176 177 .. rubric:: Syntax 178 :name: syntax_5 179 180 .. code:: 181 182 #include <keyt.h> 183 184 .. code:: 185 186 typedef struct SECKEYPrivateKeyStr SECKEYPrivateKey; 187 188 .. rubric:: Description 189 :name: description_3 190 191 Key structures are not shared objects. When an application makes a copy of a particular key 192 structure that already exists in memory, SSL makes a *deep* copy--that is, it makes a whole new 193 copy of that object. When you call ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__, the 194 function both frees the memory and sets all the bits to zero. 195 196 Never alter the contents of a key structure. Treat the structure as read only. 197 198 .. rubric:: SECStatus 199 :name: secstatus 200 201 The return value for many SSL functions. 202 203 .. rubric:: Syntax 204 :name: syntax_6 205 206 .. code:: 207 208 #include <seccomon.h> 209 210 .. code:: 211 212 typedef enum { 213 SECWouldBlock = -2, 214 SECFailure = -1, 215 SECSuccess = 0 216 } SECStatus; 217 218 .. rubric:: Enumerators 219 :name: enumerators 220 221 The enum includes the following enumerators: 222 223 +-------------------------------------------------+-------------------------------------------------+ 224 | .. code:: | Reserved for internal use. | 225 | | | 226 | SECWouldBlock | | 227 +-------------------------------------------------+-------------------------------------------------+ 228 | .. code:: | The operation failed. To find out why, call | 229 | | ``PR_GetError``. | 230 | SECFailure | | 231 +-------------------------------------------------+-------------------------------------------------+ 232 | .. code:: | The operation succeeded. In this case the value | 233 | | returned by ``PR_GetError`` is meaningless. | 234 | SECSuccess | | 235 +-------------------------------------------------+-------------------------------------------------+ 236 237 .. _managing_secitem_memory: 238 239 `Managing SECItem Memory <#managing_secitem_memory>`__ 240 ------------------------------------------------------ 241 242 .. container:: 243 244 These functions are available for managing the memory associated with ``SECItem`` structures and 245 the structures to which they point. 246 247 | ```SECItem_FreeItem`` <#1030620>`__ 248 | ```SECItem_ZfreeItem`` <#1030773>`__ 249 250 .. rubric:: SECItem_FreeItem 251 :name: secitem_freeitem 252 253 Frees the memory associated with a ``SECItem`` structure. 254 255 .. rubric:: Syntax 256 :name: syntax_7 257 258 .. code:: 259 260 #include <prtypes.h> 261 262 .. code:: 263 264 SECStatus SECItem_FreeItem ( 265 SECItem *item, 266 PRBool freeItem) 267 268 .. rubric:: Parameter 269 :name: parameter 270 271 This function has the following parameter: 272 273 +----------+--------------------------------------------------------------------------------------+ 274 | ``item`` | A pointer to a ``SECItem`` structure. | 275 +----------+--------------------------------------------------------------------------------------+ 276 | freeItem | When ``PR_FALSE``, free only the structure pointed to. Otherwise, free both the | 277 | | structure pointed to and the ``SECItem`` structure itself. | 278 +----------+--------------------------------------------------------------------------------------+ 279 280 .. rubric:: Returns 281 :name: returns 282 283 The function returns one of these value\ ``s``: 284 285 - If successful, ``SECSuccess``. 286 - If unsuccessful, ``SECFailure``. Use 287 `PR_GetError <../../../../../nspr/reference/html/prerr.html#26127>`__ to retrieve the error 288 code. 289 290 .. rubric:: Description 291 :name: description_4 292 293 This function frees the memory associated with the structure to which the specified item points, 294 when that structure is no longer used. When ``freeItem`` is not ``PR_FALSE``, also frees the item 295 structure itself. 296 297 .. rubric:: SECItem_ZfreeItem 298 :name: secitem_zfreeitem 299 300 Zeroes and frees the memory associated with a ``SECItem`` structure. 301 302 .. rubric:: Syntax 303 :name: syntax_8 304 305 .. code:: 306 307 #include <prtypes.h> 308 309 .. code:: 310 311 SECStatus SECItem_ZfreeItem ( 312 SECItem *item, 313 PRBool freeItem) 314 315 .. rubric:: Parameter 316 :name: parameter_2 317 318 This function has the following parameter: 319 320 +----------+--------------------------------------------------------------------------------------+ 321 | ``item`` | A pointer to a ``SECItem`` structure. | 322 +----------+--------------------------------------------------------------------------------------+ 323 | freeItem | When ``PR_FALSE``, free only the structure pointed to. Otherwise, free both the | 324 | | structure pointed to and the ``SECItem`` structure itself. | 325 +----------+--------------------------------------------------------------------------------------+ 326 327 .. rubric:: Returns 328 :name: returns_2 329 330 The function returns one of these value\ ``s``: 331 332 - If successful, ``SECSuccess``. 333 - If unsuccessful, ``SECFailure``. Use 334 `PR_GetError <../../../../../nspr/reference/html/prerr.html#26127>`__ to retrieve the error 335 code. 336 337 .. rubric:: Description 338 :name: description_5 339 340 This function is similar to ```SECItem_FreeItem`` <#1030620>`__, except that it overwrites the 341 structures to be freed with zeroes before it frees them. Zeros and frees the memory associated 342 with the structure to which the specified item points, when that structure is no longer used. 343 When ``freeItem`` is not ``PR_FALSE``, also zeroes and frees the item structure itself.