index.rst (53559B)
1 .. _mozilla_projects_nss_nss_api_guidelines: 2 3 NSS API Guidelines 4 ================== 5 6 .. container:: 7 8 Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ 9 10 `Introduction <#introduction>`__ 11 -------------------------------- 12 13 .. container:: 14 15 This document describes how the NSS code is organized, the libraries that get built from the NSS 16 sources, and guidelines for writing NSS code. These guidelines will familiarize you with some of 17 the ways things can be done in the NSS code. This will help you understand existing NSS code. It 18 should also help you understand how to write new code, and where to place it. 19 20 Some of the guidelines in this document, are more forward-looking than documentary. These rules 21 are here to help us all immediately achieve more consistent and usable code, but some existing 22 code won't follow all these rules. 23 24 .. _nss_api_structure: 25 26 `NSS API Structure <#nss_api_structure>`__ 27 ------------------------------------------ 28 29 .. container:: 30 31 This section explains the structure and relationships of the NSS libraries. The 32 `Layering <#layering>`__ section explains how the NSS code is layered, and how higher-level 33 functions wrap low-level functions. The `Libraries <#libraries>`__ section describes the NSS 34 libraries, the functionality each provides, and the layer in which the library (mostly) operates. 35 36 `Layering <#layering>`__ 37 ~~~~~~~~~~~~~~~~~~~~~~~~ 38 39 .. container:: 40 41 Each separate component of the API should live in its own layer. The functions in these APIs 42 should never call API layers above them. In addition, some low-level APIs may be completely 43 opaque to higher level layers. That is, access to these functions should only be provided by the 44 API directly above them. The NSS APIs are layered, as shown in this diagram: 45 46 .. image:: /en-US/docs/Mozilla/Projects/NSS/NSS_API_Guidelines/layer.gif 47 :alt: A diagram of the different layers that collectively make up "NSS". Dependencies are only 48 permitted between siblings and layers below them. 49 :width: 427px 50 :height: 507px 51 52 The boxes in the gray section, towards the center, are exported only through PKCS #11. PKCS #11 53 is only exported through the Wrappers. The areas which need the most work (both here and 54 throughout the code) is: 55 56 #. The relationship of the Certificate library with just about every other component (most 57 noticeably PKCS #12, PKCS #7, and PKCS #11) 58 #. Splitting Low Key and High Key components more clearly 59 #. The Crypto wrappers (PKCS #11 Wrappers) and High Key 60 #. PKCS #12 and PKCS #5 61 62 `Libraries <#libraries>`__ 63 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 64 65 .. container:: 66 67 NSS compiles into the libraries described below. The Layer indicates the main layer, seen in the 68 previous diagram, in which the library operates. The Directory is the location of the library 69 code in the NSS source tree. The Public Headers is a list of header files that contain types, and 70 functions, that are publicly available to higer-level APIs. 71 72 +----------+---------------------+---------------------+---------------+---------------------+ 73 | Library | Description | Layer | Directory | Public Headers | 74 +----------+---------------------+---------------------+---------------+---------------------+ 75 | certdb | Provides all | Low Cert | lib/certdb | cdbhdl.h, certdb.h, | 76 | | certificate | | | cert.h, certt.h | 77 | | handling functions | | | | 78 | | and types. The | | | | 79 | | certdb library | | | | 80 | | manipulates the | | | | 81 | | certificate | | | | 82 | | database (add, | | | | 83 | | create, delete | | | | 84 | | certificates and | | | | 85 | | CRLs). It also | | | | 86 | | provides general | | | | 87 | | c | | | | 88 | | ertificate-handling | | | | 89 | | routines (create a | | | | 90 | | certificate, | | | | 91 | | verify, add/check | | | | 92 | | certificate | | | | 93 | | extensions). | | | | 94 +----------+---------------------+---------------------+---------------+---------------------+ 95 | certhi | Provides high-level | High Cert | lib/certhigh | ocsp.h, ocspt.h | 96 | | certificate-related | | | | 97 | | functions, that do | | | | 98 | | not access the | | | | 99 | | certificate | | | | 100 | | database, nor | | | | 101 | | individual | | | | 102 | | certificate data | | | | 103 | | directly. | | | | 104 | | Currently, OCSP | | | | 105 | | checking settings | | | | 106 | | are exported | | | | 107 | | through certhi. | | | | 108 +----------+---------------------+---------------------+---------------+---------------------+ 109 | crmf | Provides functions, | Same Level as SSL | lib/crmf | cmmf.h, crmf.h, | 110 | | and data types, to | | | crmft.h, cmmft.h, | 111 | | handle Certificate | | | crmffut.h | 112 | | Management Message | | | | 113 | | Format (CMMF) and | | | | 114 | | Certificate Request | | | | 115 | | Message Format | | | | 116 | | (CRMF, see `RFC | | | | 117 | | 2511 <https://data | | | | 118 | | tracker.ietf.org/do | | | | 119 | | c/html/rfc2511>`__) | | | | 120 | | data. CMMF no | | | | 121 | | longer exists as a | | | | 122 | | proposed standard; | | | | 123 | | CMMF functions have | | | | 124 | | been incorporated | | | | 125 | | into the proposal | | | | 126 | | for `Certificate | | | | 127 | | Management | | | | 128 | | Protocols | | | | 129 | | (CMP) <https://data | | | | 130 | | tracker.ietf.org/do | | | | 131 | | c/html/rfc2510>`__. | | | | 132 +----------+---------------------+---------------------+---------------+---------------------+ 133 | cryptohi | Provides high-level | Sign/Verify | lib/cryptohi | cryptohi.h, | 134 | | cryptographic | | | cryptoht.h, | 135 | | support operations: | | | hasht.h, keyhi.h, | 136 | | such as signing, | | | keythi.h, key.h, | 137 | | verifying | | | keyt.h, sechash.h | 138 | | signatures, key | | | | 139 | | generation, key | | | | 140 | | manipulation, | | | | 141 | | hashing; and data | | | | 142 | | types. This code is | | | | 143 | | above the PKCS #11 | | | | 144 | | layer. | | | | 145 +----------+---------------------+---------------------+---------------+---------------------+ 146 | fort | Provides a PKCS #11 | PKCS #11 | lib/fortcrypt | cryptint.h, | 147 | | interface, to | | | fmutex.h, | 148 | | Fortezza crypto | | | fortsock.h, | 149 | | services. Fortezza | | | fpkcs11.h, | 150 | | is a set of | | | fpkcs11f.h, | 151 | | security | | | fpkcs11t.h, | 152 | | algorithms, used by | | | fpkmem.h, | 153 | | the U.S. | | | fpkstrs.h, genci.h, | 154 | | government. There | | | maci.h | 155 | | is also a SWFT | | | | 156 | | library that | | | | 157 | | provides a | | | | 158 | | software-only | | | | 159 | | implementation of a | | | | 160 | | PKCS #11 Fortezza | | | | 161 | | token. | | | | 162 +----------+---------------------+---------------------+---------------+---------------------+ 163 | freebl | Provides the API to | Within PKCS #11, | lib/freebl | blapi.h, blapit.h | 164 | | actual | wraps Crypto | | | 165 | | cryptographic | | | | 166 | | operations. The | | | | 167 | | freebl is a wrapper | | | | 168 | | API. You must | | | | 169 | | supply a library | | | | 170 | | that implements the | | | | 171 | | cryptographic | | | | 172 | | operations, such as | | | | 173 | | BSAFE from RSA | | | | 174 | | Security. This is | | | | 175 | | also known as the | | | | 176 | | "bottom layer" API, | | | | 177 | | or BLAPI. | | | | 178 +----------+---------------------+---------------------+---------------+---------------------+ 179 | jar | Provides support | Port | lib/jar | jar-ds.h, jar.h, | 180 | | for reading and | | | jarfile.h | 181 | | writing data in | | | | 182 | | Java Archive (jar) | | | | 183 | | format, including | | | | 184 | | zlib compression. | | | | 185 +----------+---------------------+---------------------+---------------+---------------------+ 186 | nss | Provides high-level | Above High Cert, | lib/nss | nss.h | 187 | | initialiazation and | High Key | | | 188 | | shutdown of | | | | 189 | | security services. | | | | 190 | | Specifically, this | | | | 191 | | library provides | | | | 192 | | NSS_Init() for | | | | 193 | | establishing | | | | 194 | | default | | | | 195 | | certificate, key, | | | | 196 | | module databases, | | | | 197 | | and initializing a | | | | 198 | | default random | | | | 199 | | number generator. | | | | 200 | | NSS_Shutdown() | | | | 201 | | closes these | | | | 202 | | databases, to | | | | 203 | | prevent further | | | | 204 | | access by an | | | | 205 | | application. | | | | 206 +----------+---------------------+---------------------+---------------+---------------------+ 207 | pk11wrap | Provides access to | Crypto Wrapper | lib/pk11wrap | pk11func.h, | 208 | | PKCS #11 modules, | | | secmod.h, secmodt.h | 209 | | through a unified | | | | 210 | | interface. The | | | | 211 | | pkcs11wrap library | | | | 212 | | provides functions | | | | 213 | | for | | | | 214 | | selecting/finding | | | | 215 | | PKCS #11 modules | | | | 216 | | and slots. It also | | | | 217 | | provides functions | | | | 218 | | that invoke | | | | 219 | | operations in | | | | 220 | | selected modules | | | | 221 | | and slots, such as | | | | 222 | | key selection and | | | | 223 | | generation, | | | | 224 | | signing, encryption | | | | 225 | | and decryption, | | | | 226 | | etc. | | | | 227 +----------+---------------------+---------------------+---------------+---------------------+ 228 | pkcs12 | Provides functions | PKCS #12 | lib/pkcs12 | pkcs12t.h, | 229 | | and types for | | | pkcs12.h, | 230 | | encoding and | | | p12plcy.h, p12.h, | 231 | | decoding PKCS #12 | | | p12t.h | 232 | | data. PKCS #12 can | | | | 233 | | be used to encode | | | | 234 | | keys, and | | | | 235 | | certificates, for | | | | 236 | | export or import | | | | 237 | | into other | | | | 238 | | applications. | | | | 239 +----------+---------------------+---------------------+---------------+---------------------+ 240 | pkcs7 | Provides functions | PKCS #7 | lib/pkcs7 | secmime.h, | 241 | | and types for | | | secpkcs7.h, | 242 | | encoding and | | | pkcs7t.h | 243 | | decoding encrypted | | | | 244 | | data in PKCS #7 | | | | 245 | | format. For | | | | 246 | | example, PKCS #7 is | | | | 247 | | used to encrypt | | | | 248 | | certificate data to | | | | 249 | | exchange between | | | | 250 | | applications, or to | | | | 251 | | encrypt S/MIME | | | | 252 | | message data. | | | | 253 +----------+---------------------+---------------------+---------------+---------------------+ 254 | softoken | Provides a software | PKCS #11: | lib/softoken | keydbt.h, keylow.h, | 255 | | implementation of a | implementation | | keytboth.h, | 256 | | PKCS #11 module. | | | keytlow.h, | 257 | | | | | secpkcs5.h, | 258 | | | | | pkcs11.h, | 259 | | | | | pkcs11f.h, | 260 | | | | | pkcs11p.h, | 261 | | | | | pkcs11t.h, | 262 | | | | | pkcs11u.h | 263 +----------+---------------------+---------------------+---------------+---------------------+ 264 | ssl | Provides an | SSL | lib/ssl | ssl.h, sslerr.h, | 265 | | implementation of | | | sslproto.h, | 266 | | the SSL protocol | | | preenc.h | 267 | | using NSS and NSPR. | | | | 268 +----------+---------------------+---------------------+---------------+---------------------+ 269 | secutil | Provides utility | Utility for any | lib/util | base64.h, | 270 | | functions and data | Layer | | ciferfam.h, | 271 | | types used by other | | | nssb64.h, | 272 | | libraries. The | | | nssb64t.h, | 273 | | library supports | | | nsslocks.h, | 274 | | base-64 | | | nssrwlk.h, | 275 | | encoding/decoding, | | | nssrwlkt.h, | 276 | | reader-writer | | | portreg.h, | 277 | | locks, the SECItem | | | pqgutil.h, | 278 | | data type, DER | | | secasn1.h, | 279 | | encoding/decoding, | | | secasn1t.h, | 280 | | error types and | | | seccomon.h, | 281 | | numbers, OID | | | secder.h, | 282 | | handling, and | | | secdert.h, | 283 | | secure random | | | secdig.h, | 284 | | number generation. | | | secdigt.h, | 285 | | | | | secitem.h, | 286 | | | | | secoid.h, | 287 | | | | | secoidt.h, | 288 | | | | | secport.h, | 289 | | | | | secrng.h, | 290 | | | | | secrngt.h, | 291 | | | | | secerr.h, | 292 | | | | | watcomfx.h | 293 +----------+---------------------+---------------------+---------------+---------------------+ 294 295 .. _naming_conventions: 296 297 `Naming Conventions <#naming_conventions>`__ 298 -------------------------------------------- 299 300 .. container:: 301 302 This section describes the rules that (ideally) should be followed for naming and identifying new 303 files, functions, and data types. 304 305 .. _cvs_id: 306 307 `CVS ID <#cvs_id>`__ 308 ~~~~~~~~~~~~~~~~~~~~ 309 310 .. container:: 311 312 Each file should include a CVS ID string for identification. The preferred format is: 313 314 .. code:: 315 316 "@(#) $RCSfile: nss-guidelines.html, 317 v $ $Revision: 48936 $ $Date: 2009-08-11 07:45:57 -0700 (Tue, 11 Aug 2009) $ $Name$" 318 319 You can put the string in a comment or in a static char array. Use #ifdef DEBUG to include the 320 array in debug builds only. The advantage of using an array is that you can use strings(1) to 321 pull the ID tags out of a (debug) compiled library. You can even put them in header files; the 322 header files are protected from double inclusion. The only catch is that you have to determine 323 the name of the array. 324 325 Here is an example from lib/base/baset.h: 326 327 .. code:: 328 329 #ifdef DEBUG 330 static const char BASET_CVS_ID[] = "@(#) $RCSfile: nss-guidelines.html, 331 v $ $Revision: 48936 $ $Date: 2009-08-11 07:45:57 -0700 (Tue, 11 Aug 2009) $ $Name$"; 332 #endif /* DEBUG */ 333 334 The difference, between this and Id, is that Id has some useless information (*every* file is 335 "experimental"), and doesn't have Name. Name is the tag (if any) from which this file was pulled. 336 If you're good with tagging your releases, and then checking out (or exporting!) from the tag for 337 your build, this saves you from messing around with specific files revision numbers. 338 339 .. _header_files: 340 341 `Header Files <#header_files>`__ 342 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 343 344 .. container:: 345 346 | We have a preferred naming system for include files. We had been moving towards one, for some 347 time, but for the NSS 3.0 project we finally wrote it down. 348 | 349 350 ========================= =========== =================== 351 \ Data Types Function Prototypes 352 Public nss____t.h nss____.h 353 Friend (only if required) nss____tf.h nss____f.h 354 NSS-private \____t.h \____.h 355 Module-private \____tm.h \____m.h 356 ========================= =========== =================== 357 358 The files on the right include the files to their left; the files in a row include the files 359 directly above them. Header files always include what they need; the files are protected against 360 double inclusion (and even double opening by the compiler). 361 362 .. note:: 363 364 Note: It's not necessary all eight files exist. Further, this is a simple ideal, and often 365 reality is more complex. 366 367 We would like to keep names to 8.3, even if we no longer support win16. This usually gives us 368 four characters to identify a module of NSS. 369 370 In short: 371 372 #. Header files for consumption outside NSS start with "nss." 373 #. Header files with types have a trailing "t", header files with prototypes don't. 374 "extern" declarations of data also go in the prototypes files. 375 #. "Friend" headers are for things that we really wish weren't used by non-NSS code, but which 376 are. Those files have a trailing "f," and their use should be deprecated. 377 #. "Module" headers are for things used only within a specific subset of NSS; things which would 378 have been "static" if we had combined separate C source files together. These header files 379 have a trailing "m." 380 381 .. _functions_and_types: 382 383 `Functions and Types <#functions_and_types>`__ 384 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 385 386 .. container:: 387 388 There are a number of ways of doing things in our API, as well as naming decisions for functions 389 that can affect the usefulness of our library. If our library is self-consistent with how we 390 accomplish these tasks, it makes it easier for the developer to learn how to use our functions. 391 This section of the document should grow as we develop our API. 392 393 First some general rules. These rules are derived from existing coding practices inside the 394 security library, since consistency is more important than debates about what might look nice. 395 396 #. **Public functions** should have the form LAYER_Body(), where LAYER is an all caps prefix for 397 what layer the function lives in, and Body is concatenated English words, where the beginning 398 letter of each word is capitalized (also known as 399 `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`__). For Example: 400 LAYER_CapitalizedEnglishWords() or CERT_DestroyCertificate(). 401 #. **Data types** and typdefs should have the Form LAYERBody, with the same definitions for LAYER 402 as public functions, and Body in camel case English words. For example: 403 LAYERCapitalizedEnglishWords or SECKEYPrivateKey. 404 #. **Structures** should have the same name as their typedefs, with the string Str added to the 405 end. For example LAYERCapitalizedEnglishWordsStr or SECKEYPrivateKeyStr. 406 #. **Private functions** should have the form layer_Body(), where layer is the all lower case 407 prefix for what layer the function lives in, and Body is camel case English words. Private 408 functions include functions that may be "public" in a C sense, but are not exported out of the 409 layer. For example: layer_CapitalizedEnglishWords() or pk11_GenerateKeyID(). 410 #. **Public macros** should have the form LAYER_BODY(), where LAYER is an all caps prefix for 411 what layer the macro lives in, and BODY is English words, all in upper case, separated by 412 underscores. For example: LAYER_UPPER_CASE_ENGLISH_WORDS() or DER_CONVERT_BIT_STRING(). 413 #. **Structure members** for exposed data structures should have the form capitalizedEnglishWords 414 (the first letter uncapitalized). For example: PK11RSAGenParamsStr.\ **keySizeInBits** 415 #. For **members of enums**, our current API has no standard (typedefs for enums should follow 416 the Data types standard). There seem to be three reasonable options: 417 418 #. Enum members have the same standard as exposed data structure members. 419 #. Enum members have the same standard as data types. 420 #. Enum members have the same standard as public macros (minus the '()' of course). 421 422 Options 2 and 3 are the more preferred options. Option 1, currently the most common used for 423 enums, actually creates namespace pollution. 424 #. **Callback functions**, and functions used in function tables, should have a typedef used to 425 define the complete signature of the given function. Function typedefs should have the 426 following format: LAYERBody(), with the same definitions for LAYER as public functions, and 427 Body is camel case English words. For example: LAYERCapitalizedEnglishWords or 428 SECKEYPrivateKey. 429 430 .. _opaque_data_structures: 431 432 `Opaque Data Structures <#opaque_data_structures>`__ 433 ---------------------------------------------------- 434 435 .. container:: 436 437 There are many data structures in the security library whose definition is effectively private, 438 to the portion of the security library that defines and operates on those data structures. 439 External code does not have access to these definitions. The goal here is to increase the 440 opaqueness of these structures. This will allow us to modify the size, definition, and format of 441 these data structures in future releases, without interfering with the operation of existing 442 applications that use the security library. 443 444 The first task is to ensure the data structure definition lives in a private header file, while 445 its declaration lives in the public. The current standard in the security library is to typedef 446 the data structure name, the easiest way to accomplish this would be to add the typedef to the 447 public header file. 448 449 For example, for the structure SECMyOpaqueData you would add: 450 451 .. code:: 452 453 typedef struct SECMyOpaqueDataStr SECMyOpaqueData; 454 455 and add the actual structure definition to the private header file. In this same example: 456 457 .. code:: 458 459 struct SECMyOpaqueDataStr { 460 unsigned long myPrivateData1; 461 unsigned long myPrivateData2; 462 char *myName; 463 }; 464 465 the second task is to determine if individual data fields, within the data structure, are part of 466 the API. One example may be the peerCert field, in an SSL data structure. Accessor functions, for 467 these data elements, should be added to the API. 468 469 There can be legitimate exceptions to this 'make everything opaque' rule. For example, in 470 container structures, such as SECItem, or maybe linked list data structures. These data 471 structures need to be examined on a case by case basis, to determine if 472 473 #. They are truly stable and will not change in future release 474 #. It is necessary for the callers of the API to know the size of these structures, as they may 475 allocate new ones and pass them down. 476 477 .. _memory_allocation_with_arenas: 478 479 `Memory Allocation with Arenas <#memory_allocation_with_arenas>`__ 480 ------------------------------------------------------------------ 481 482 .. container:: 483 484 This section discusses memory allocation using arenas. NSS code uses arenas, and this section 485 explains some of the improvements we are making. 486 487 NSS makes use of traditional memory allocation functions, wrapping NSPR's PR_Alloc in a util 488 function called PORT_Alloc. Though NSS makes further use of an NSPR memory-allocation facility 489 which uses 'Arenas' and 'ArenaPools'. This was added via javascript; a fast, lightweight, 490 non-thread-safe (though 'free-threaded') implementation. 491 492 Experience shows that users of the security library expect arenas to be threadsafe, so we added 493 locking, and other useful changes. 494 495 - There has always been confusion as to the difference between Arenas and ArenaPools. We will 496 simplify down to one logical 'memory bucket' type. Consensus called this type NSSArena. 497 - We have lots of code which takes an optional arena pointer, using the arena if there is one, 498 or alternatively the heap if there isn't. Therefore, we wrap that logic into the allocators. 499 Knowing what to then free does takes discipline not to leak memory, but it simplifies things a 500 lot. Also, the implementation of free works (doesn't crash), no matter if from an arena, or 501 the heap, as long as from our allocators. Combined with purify, this also helps us catch cases 502 where things being allocated by one allocator are freed by another, which is a common Windows 503 pitfall. 504 - The security code often wants to be sure to zero memory, when it's being freed; we'll add it 505 to the primitives to deal with. 506 507 The ARENA_THREADMARK preprocessor definition (default in debug builds), and code it encloses, 508 will add some checking for the following situation: 509 510 #. Thread A marks the arena, and allocates some memory from it. 511 #. Thread B allocates some memory from the arena. 512 #. Thread A releases the arena back to the mark. 513 #. Thread B now finds itself with a pointer to released data. 514 #. Some thread -- doesn't matter which -- allocates some data from the arena; this may overlap 515 the chunk thread B has. 516 #. Boom! 517 518 Threadmark code notes the thread ID, whenever an arena is marked, and disallows any allocations 519 or marks by any other thread. (Frees are allowed.) 520 521 The ARENA_DESTRUCTOR_LIST preprocessor definition, and the code it encloses, are an effort to 522 make the following work together: 523 524 #. Arenas, letting you allocate stuff and then removing them all at once 525 #. Lazy creation of pure-memory objects from ASN.1 blobs, for example use of NSSPKIXCertificate 526 doesn't drag all the code in for all constituent objects, unless they're actually being used 527 #. Our agressive pointer-tracking facility 528 529 All these are useful, but they don't combine well. Now some of the pointer-tracking pressure has 530 eased off, we can drop its use when it becomes too difficult. 531 532 Many routines are defined to take an NSSArena \*arenaOpt argument. This means if an arena is 533 specified (non-null), it is used, otherwise (null) the routine uses the heap. You can think of 534 the heap as a default arena you can't destroy. 535 536 .. _error_handling: 537 538 `Error Handling <#error_handling>`__ 539 ------------------------------------ 540 541 .. container:: 542 543 NSS 3.0 introduces the concept of an error stack. When something goes wrong, the call stack 544 unwinds, with routines returning an error indication. Each level which flags a problem, adds its 545 own error number to the stack. At the bottom of the stack is the fundamental error, for example: 546 file not found, and on top is an error precisely relating to what you are doing. 547 548 .. note:: 549 550 Note: Error stacks are vertical, and never horizontal. If multiple things go wrong 551 simultaneously, and you want to report them all, use another mechanism. 552 553 Errors, though not integers, are done as external constants, instead of preprocessor definitions. 554 This is so any additional error doesn't trigger the entire tree to rebuild. Likewise, the 555 external references to errors are made in the prototypes files, with the functions which can 556 return them. Error stacks are thread-private. 557 558 The usual semantic is that public routines clear the stack first, private routines don't. 559 Usually, every public routine has a private counterpart, and the implementation of the public 560 routine looks like this: 561 562 .. code:: 563 564 NSSImplement rv * 565 NSSType_Method 566 ( 567 NSSType *t, 568 NSSFoo *arg1, 569 NSSBar *arg2 570 ) 571 { 572 nss_ClearErrorStack(); 573 574 #ifdef DEBUG 575 if( !nssFoo_verifyPointer(arg1) ) return (rv *)NULL; 576 if( !nssBar_verifyPointer(arg2) ) return (rv *)NULL; 577 #endif /* DEBUG */ 578 579 return nssType_Method(t, arg1, arg2); 580 } 581 582 Aside from error cases, all documented entry points should check pointers in a debug, wherever 583 possible. Pointers to user-supplied buffers, and templates, should be checked against NULL. 584 Pointers to context-style functions should be checked using special debug macros. These macros 585 only define code when DEBUG is turned on, providing a way for systems to register, deregister, 586 and check valid pointers. 587 588 SECPORT_DECL_PTR_CLASS(*classname*, *size*) - declare a class of pointers (labelled *classname*) 589 this object file needs to check. This class is local only to this object file. *Size* is the 590 expected number of pointers of type *classname*. 591 592 SECPORT_DECL_GLOBAL_PTR_CLASS(*classname*, *size*) - same as above except *classname* can be used 593 in other object files. 594 595 SECPORT_ADD_POINTER(*classname*, *pointer*) - Add *pointer* as a valid pointer for 596 class\ *classname*. This is usually called by a Create function. 597 598 SECPORT_VERIFY_POINTER(*classname*, *pointer*, *secError*, *returnValue*)- Check if a given 599 *pointer* really belongs to the requested class. If it doesn't set the error *secError* and 600 return the value *returnValue*. 601 602 SECPORT_REMOVE_POINTER(*classname*, *pointer*) - Remove a pointer from the valid list. Usually 603 called by a destroy function. 604 605 Finally, error logging should be added an documented when debug is turned on. Interfaces for 606 these are in NSPR. 607 608 .. _thread_safety: 609 610 `Thread Safety <#thread_safety>`__ 611 ---------------------------------- 612 613 .. container:: 614 615 Code developed using the NSS APIs needs to make use of thread safety features. First to examine 616 is **object creation** and **deletion**. 617 618 Object creation is usually not a problem. No other threads have access to allocated memory just 619 created. Exceptions to this include objects which are created on the fly, or as global objects. 620 621 Deletion, on the other hand, may be trickier. Threads may be referencing the object at the same 622 time a another thread tries to delete it. The semantics depend on the way the application uses 623 the object, also how and when the application wants to destroy it. For some data structures, this 624 problem can be removed by protected reference counting. The object does not disappear until all 625 users have released it. 626 627 Next we examine **global data**, including function local static structures. Just initialized, 628 and never to be changed global data, does not need to protection from mutexes. We should also 629 determine if global data should be moved to a session context (see `session 630 context <#sessioncontext>`__ and `global effects <#globaleffects>`__ below). 631 632 .. note:: 633 634 Note: Permanent objects, like data in files, databases, tokens, etc. should be treated as 635 global data. Global data which is changed rarely, should be protected by reader/writer locks. 636 637 Aside from global data, **allocated data** that gets modified needs to be examined. Data that's 638 just been allocated, within a function, is safe to modify. No other code has access to that data 639 pointer. Once that data pointer is made visible to the 'outside', either by returning the 640 pointer, or attaching the pointer to an existing visible data structure, access to the data 641 should be protected. Data structures that are read only, like SECKEYPublicKeys or PK11SymKeys, 642 need not be protected. 643 644 Many of the data structures in the security code contain some sort of **session state** or 645 **session context**. These data structures may be accessed without data protection as long as: 646 647 #. This semantic is documented in the functions which use these data structures. 648 #. These data structures are used for single streams, and not reused. 649 650 Examples of these data in structures may include things like the PKCS #7 ContentInfo structure. 651 Example code should be included in the documentation, to show how to safely use these data 652 objects. 653 654 A major type of global and allocated data that should be examined is various **data on lists**. 655 Queued, linked, and hash table stored objects should be examined with special care. Make sure 656 adding, removing, accessing, and destroying these objects are all safe operations. 657 658 There are a number of strategies, and entire books about how to safely access data on lists. Some 659 simple strategies and their issues: 660 661 - **Use hash tables:** Hash table lookups are usually quite fast, limiting the contention on the 662 lock. This is best for large lists of objects. Be sure to calculate the hash value first, then 663 only lock over the hash table value itself. Be sure to increment the reference count, on the 664 returned object, before unlocking. Examples of hash tables can be found in 665 security/nss/lib/certdb/pcertdb.c 666 - **Lock over the entire search:** For small linked listed, queues, or arrays, you can lock over 667 the entire search. This strategy is best when lists are short, or even better if lists are 668 relatively read only (they don't change very often) and using reader/writer locks. 669 - **Copy the linked list:** Instead of operating on the global list, you can copy the list. This 670 also requires small lists. 671 - **Lock over single element with retry:** For medium sized lists, you can secure the reference 672 to each element, complete a test, then detect if the given element has been removed from the 673 list. In the case of removal, the search can either be either restarted, or terminated. This 674 method is a more complicated than the other methods: requiring the calling of search code 675 tolerant to often repeated element inspection. 676 - Examples of the previous strategies can be found in 677 `security/nss/lib/pk11wrap/pk11slot.c. <https://searchfox.org/mozilla-central/source/security/nss/lib/pk11wrap/pk11slot.c>`__ 678 679 Where possible use the NSPR list primitives. From these you can even set up SECUtil style 680 thread-safe lists that use some combination of the above strategies. 681 682 In order to be fully thread safe, your code must understand the semantics of the **service 683 functions** it calls, and whether they are thread safe. For now, we should internally document 684 which service functions we call, and how we expect them to behave in a threaded environment. 685 686 Finally, from an API point of view, we should examine functions which have **global effects**. 687 Functions like XXX_SetDefaultYYY(); should not operate on global data, particularly if they may 688 be called multiple times, to provide different semantics for different operations. For example, 689 the following should be avoided : 690 691 - SEC_SetKey(keyForOperation); 692 SEC_Encrypt(Data,Length); 693 694 Instead, a context handle should be created, and the SEC_SetKey() function, above, made on that 695 handle. Fortunately most of the existing API has the correct semantics. 696 697 The exception to this global effects rule may be functions which set global state for an 698 application at initialization time. 699 700 .. _methodsfunctions_design: 701 702 `Methods/Functions Design <#methodsfunctions_design>`__ 703 ------------------------------------------------------- 704 705 .. container:: 706 707 .. _init_shutdown_functions: 708 709 `Init, Shutdown Functions <#init_shutdown_functions>`__ 710 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 711 712 .. container:: 713 714 If a layer has some global initialization tasks, which need to be completed before the layer can 715 be used, that layer should supply an initialization function of the form LAYER_Init(). If an 716 initialization function is supplied, a corresponding LAYER_Shutdown() function should also be 717 supplied. LAYER_INIT() should increment a count of the number of times it is called, and 718 LAYER_Shutdown() should decrement that count, and shutdown when the count reaches '0'. 719 720 .. _open_close_functions: 721 722 `Open, Close Functions <#open_close_functions>`__ 723 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 724 725 .. container:: 726 727 Open functions should have a corresponding close function. Open and close function are not 728 reference counted, like init and shutdown functions. 729 730 .. _creation_functions: 731 732 `Creation Functions <#creation_functions>`__ 733 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 734 735 .. container:: 736 737 In general, data objects should all have functions which create them. These functions should have 738 the form LAYER_CreateDataType[FromDataType](). For instance generating a new key would change 739 from PK11_KeyGen() to PK11_CreateSymKey(). 740 741 .. _destruction_functions: 742 743 `Destruction Functions <#destruction_functions>`__ 744 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 745 746 .. container:: 747 748 In the security library we have 3 different ways of saying 'get rid of this data object': Free, 749 Delete, and Destroy. 750 751 It turns out there are several different semantics of getting rid of a data object too: 752 753 #. decrement the reference count, and when the object goes to '0' free/delete/destroy it 754 #. destroy it right now, this very instance, not matter what 755 #. make any permanent objects associated with this data object go away 756 #. a combination of 1 and 3, or 2 and 3 757 758 Unfortunately, within the security library Free, Delete, and Destroy are all used 759 interchangeably, for all sorts of object destruction. For instance, CERT_DestroyCertificate() is 760 type 1, PK11_DestroySlot() is type 2, and PK11_DestroyTokenObject() is type 3. 761 762 .. note:: 763 764 Note: In non-reference counted functions, types 1 and 2 are the same. 765 766 We are standardizing on the following definitions: 767 768 Destroy - means #1 for reference counted objects, #2 for non reference counted objects. 769 770 Delete - means #3. 771 772 This has the advantage of *not* surfacing the reference countedness of a data object. If you own 773 a pointer to an object, you must always destroy it. There is no way to destroy an object by 774 bypassing it's reference count. Also, the signature of public destruction functions do not have 775 the 'freeit' PRBool, since the structures being freed are opaque. 776 777 .. _dup_copy_and_reference_functions: 778 779 `Dup, Copy, and Reference Functions <#dup_copy_and_reference_functions>`__ 780 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 781 782 .. container:: 783 784 Functions that return a new reference or copy of a given object should have the form 785 LAYER_DupDataType(). For instance, CERT_DupCertifiate() will remain the same, but 786 PK11_ReferenceSlot() will become PK11_DupSlot(), and PK11_CloneContext() will become 787 PK11_DupContext(). 788 789 .. _search_functions: 790 791 `Search Functions <#search_functions>`__ 792 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 793 794 .. container:: 795 796 There are several different kinds of searches done via the security library. The first is a 797 search for exactly one object, meeting a given criteria. These types of searches include 798 CERT_FindCertByDERCert(), PK11_FindAnyCertFromDERCert(), PK11_FindKeyByCert(), 799 PK11_GetBestSlot(). These functions should all have the form LAYER_FindDataType[ByDataType](). 800 801 The second kind of search, looks for all the objects that match a given criteria. These functions 802 operate on a variety of levels. Some return allocated arrays of data, some return linked lists of 803 data, others use callbacks to return data elements one at a time. Unfortunately, there are good 804 reasons to maintain all these types. So here are some guidelines to make them more manageable: 805 806 All callback operating search functions should be in the low level of the API, if exposed at all. 807 Developers dealing with SSL and PKCS #7 layers should not have to see any of these functions. 808 These functions should have the form LAYER_TraverseStorageObjectOrList(). 809 810 List and Array returning functions should be available at the higher layers of the API, most 811 wrapping LAYER_Traverse() functions. They should have the form 812 LAYER_LookupDataType{List|Array}[ByDataType](). 813 814 .. _accesssor_functions: 815 816 `Accesssor Functions <#accesssor_functions>`__ 817 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 818 819 .. container:: 820 821 Accessor Functions should take the following formats: 822 823 | LAYER_DataTypeGetElement() -- Get a specific element of a data structure. 824 | LAYER_DataTypeSetElement() -- Set a specific element of a data structure. 825 | LAYER_DataTypeExtractDataType() -- Get a pointer to the second data type which was derived for 826 elements of the first data type. 827 828 Examples: PK11_SlotGetSeries(), PK11_SymKeyGetSeries(), CERT_CertificateExtractPublicKey() 829 830 .. _parameter_ordering: 831 832 `Parameter ordering <#parameter_ordering>`__ 833 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 834 835 .. container:: 836 837 Most functions will have a 'Natural' ordering for parameters. To keep consistency we should have 838 some minimal parameter consistency. For most functions, they can be seen as operating on a 839 particular object. This object, that the function is operating on, should come first. For 840 instance, in most SSL functions this is the NSPR Socket, or the SSL Socket structure: Update, 841 final, encrypt, decrypt type functions operating on their state contexts, etc. 842 843 All encrypt and decrypt functions, which return data inline, should have a consistent signature: 844 845 .. code:: 846 847 SECStatus MY_FunctionName(MyContext *context, 848 unsigned char *outBuf, 849 SECBufferLen *outLen, 850 SECBufferLenmaxOutLength, 851 unsigned char *inBuf, 852 SECBufferLeninLen) 853 854 Encrypt and decrypt like functions which have different properties, additional parameters, 855 callbacks, etc., should insert their additional parameters between the context (first parameter) 856 and the output buffer. 857 858 All hashing update, MACing update, and encrypt/decrypt functions which act like filters should 859 have a consistent signature: 860 861 .. code:: 862 863 SECStatus PK11_DigestOp(PK11Context *context, 864 unsigned char *inBuf, 865 SECBufferLeninLen) 866 867 Functions like these which have different properties, for example, additional parameters, 868 callbacks, etc., should insert their additional parameters between the context (first parameter) 869 and the input buffer. 870 871 Within your layer, multiple similar functions should have consistent parameter order. 872 873 .. _callback_functions: 874 875 `Callback Functions <#callback_functions>`__ 876 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 877 878 .. container:: 879 880 Callback functions should all contain an opaque parameter (void \*) as their first argument, 881 passed by the original caller. Callbacks which are set, like SSL callbacks, should have defaults 882 which provide generally useful semantics.