structure.rst (29251B)
1 .. _mozilla_projects_nss_nss_structure: 2 3 `NSS API Structure <#api_structure>`__ 4 ====================================== 5 6 `Libraries <#libraries>`__ 7 -------------------------- 8 9 .. container:: 10 11 NSS compiles into the libraries described below. The Layer indicates the main layer in which the library operates. The Directory is the location of the library 12 code in the NSS source tree. The Public Headers is a list of header files that contain types, and 13 functions, that are publicly available to higer-level APIs. 14 15 +----------+---------------------+---------------------+---------------+---------------------+ 16 | Library | Description | Layer | Directory | Public Headers | 17 +----------+---------------------+---------------------+---------------+---------------------+ 18 | certdb | Provides all | Low Cert | lib/certdb | cdbhdl.h, certdb.h, | 19 | | certificate | | | cert.h, certt.h | 20 | | handling functions | | | | 21 | | and types. The | | | | 22 | | certdb library | | | | 23 | | manipulates the | | | | 24 | | certificate | | | | 25 | | database (add, | | | | 26 | | create, delete | | | | 27 | | certificates and | | | | 28 | | CRLs). It also | | | | 29 | | provides general | | | | 30 | | c | | | | 31 | | ertificate-handling | | | | 32 | | routines (create a | | | | 33 | | certificate, | | | | 34 | | verify, add/check | | | | 35 | | certificate | | | | 36 | | extensions). | | | | 37 +----------+---------------------+---------------------+---------------+---------------------+ 38 | certhi | Provides high-level | High Cert | lib/certhigh | ocsp.h, ocspt.h | 39 | | certificate-related | | | | 40 | | functions, that do | | | | 41 | | not access the | | | | 42 | | certificate | | | | 43 | | database, nor | | | | 44 | | individual | | | | 45 | | certificate data | | | | 46 | | directly. | | | | 47 | | Currently, OCSP | | | | 48 | | checking settings | | | | 49 | | are exported | | | | 50 | | through certhi. | | | | 51 +----------+---------------------+---------------------+---------------+---------------------+ 52 | crmf | Provides functions, | Same Level as SSL | lib/crmf | cmmf.h, crmf.h, | 53 | | and data types, to | | | crmft.h, cmmft.h, | 54 | | handle Certificate | | | crmffut.h | 55 | | Management Message | | | | 56 | | Format (CMMF) and | | | | 57 | | Certificate Request | | | | 58 | | Message Format | | | | 59 | | (CRMF, see `RFC | | | | 60 | | 2511 <https://data | | | | 61 | | tracker.ietf.org/do | | | | 62 | | c/html/rfc2511>`__) | | | | 63 | | data. CMMF no | | | | 64 | | longer exists as a | | | | 65 | | proposed standard; | | | | 66 | | CMMF functions have | | | | 67 | | been incorporated | | | | 68 | | into the proposal | | | | 69 | | for `Certificate | | | | 70 | | Management | | | | 71 | | Protocols | | | | 72 | | (CMP) <https://data | | | | 73 | | tracker.ietf.org/do | | | | 74 | | c/html/rfc2510>`__. | | | | 75 +----------+---------------------+---------------------+---------------+---------------------+ 76 | cryptohi | Provides high-level | Sign/Verify | lib/cryptohi | cryptohi.h, | 77 | | cryptographic | | | cryptoht.h, | 78 | | support operations: | | | hasht.h, keyhi.h, | 79 | | such as signing, | | | keythi.h, key.h, | 80 | | verifying | | | keyt.h, sechash.h | 81 | | signatures, key | | | | 82 | | generation, key | | | | 83 | | manipulation, | | | | 84 | | hashing; and data | | | | 85 | | types. This code is | | | | 86 | | above the PKCS #11 | | | | 87 | | layer. | | | | 88 +----------+---------------------+---------------------+---------------+---------------------+ 89 | fort | Provides a PKCS #11 | PKCS #11 | lib/fortcrypt | cryptint.h, | 90 | | interface, to | | | fmutex.h, | 91 | | Fortezza crypto | | | fortsock.h, | 92 | | services. Fortezza | | | fpkcs11.h, | 93 | | is a set of | | | fpkcs11f.h, | 94 | | security | | | fpkcs11t.h, | 95 | | algorithms, used by | | | fpkmem.h, | 96 | | the U.S. | | | fpkstrs.h, genci.h, | 97 | | government. There | | | maci.h | 98 | | is also a SWFT | | | | 99 | | library that | | | | 100 | | provides a | | | | 101 | | software-only | | | | 102 | | implementation of a | | | | 103 | | PKCS #11 Fortezza | | | | 104 | | token. | | | | 105 +----------+---------------------+---------------------+---------------+---------------------+ 106 | freebl | Provides the API to | Within PKCS #11, | lib/freebl | blapi.h, blapit.h | 107 | | actual | wraps Crypto | | | 108 | | cryptographic | | | | 109 | | operations. The | | | | 110 | | freebl is a wrapper | | | | 111 | | API. You must | | | | 112 | | supply a library | | | | 113 | | that implements the | | | | 114 | | cryptographic | | | | 115 | | operations, such as | | | | 116 | | BSAFE from RSA | | | | 117 | | Security. This is | | | | 118 | | also known as the | | | | 119 | | "bottom layer" API, | | | | 120 | | or BLAPI. | | | | 121 +----------+---------------------+---------------------+---------------+---------------------+ 122 | jar | Provides support | Port | lib/jar | jar-ds.h, jar.h, | 123 | | for reading and | | | jarfile.h | 124 | | writing data in | | | | 125 | | Java Archive (jar) | | | | 126 | | format, including | | | | 127 | | zlib compression. | | | | 128 +----------+---------------------+---------------------+---------------+---------------------+ 129 | nss | Provides high-level | Above High Cert, | lib/nss | nss.h | 130 | | initialiazation and | High Key | | | 131 | | shutdown of | | | | 132 | | security services. | | | | 133 | | Specifically, this | | | | 134 | | library provides | | | | 135 | | NSS_Init() for | | | | 136 | | establishing | | | | 137 | | default | | | | 138 | | certificate, key, | | | | 139 | | module databases, | | | | 140 | | and initializing a | | | | 141 | | default random | | | | 142 | | number generator. | | | | 143 | | NSS_Shutdown() | | | | 144 | | closes these | | | | 145 | | databases, to | | | | 146 | | prevent further | | | | 147 | | access by an | | | | 148 | | application. | | | | 149 +----------+---------------------+---------------------+---------------+---------------------+ 150 | pk11wrap | Provides access to | Crypto Wrapper | lib/pk11wrap | pk11func.h, | 151 | | PKCS #11 modules, | | | secmod.h, secmodt.h | 152 | | through a unified | | | | 153 | | interface. The | | | | 154 | | pkcs11wrap library | | | | 155 | | provides functions | | | | 156 | | for | | | | 157 | | selecting/finding | | | | 158 | | PKCS #11 modules | | | | 159 | | and slots. It also | | | | 160 | | provides functions | | | | 161 | | that invoke | | | | 162 | | operations in | | | | 163 | | selected modules | | | | 164 | | and slots, such as | | | | 165 | | key selection and | | | | 166 | | generation, | | | | 167 | | signing, encryption | | | | 168 | | and decryption, | | | | 169 | | etc. | | | | 170 +----------+---------------------+---------------------+---------------+---------------------+ 171 | pkcs12 | Provides functions | PKCS #12 | lib/pkcs12 | pkcs12t.h, | 172 | | and types for | | | pkcs12.h, | 173 | | encoding and | | | p12plcy.h, p12.h, | 174 | | decoding PKCS #12 | | | p12t.h | 175 | | data. PKCS #12 can | | | | 176 | | be used to encode | | | | 177 | | keys, and | | | | 178 | | certificates, for | | | | 179 | | export or import | | | | 180 | | into other | | | | 181 | | applications. | | | | 182 +----------+---------------------+---------------------+---------------+---------------------+ 183 | pkcs7 | Provides functions | PKCS #7 | lib/pkcs7 | secmime.h, | 184 | | and types for | | | secpkcs7.h, | 185 | | encoding and | | | pkcs7t.h | 186 | | decoding encrypted | | | | 187 | | data in PKCS #7 | | | | 188 | | format. For | | | | 189 | | example, PKCS #7 is | | | | 190 | | used to encrypt | | | | 191 | | certificate data to | | | | 192 | | exchange between | | | | 193 | | applications, or to | | | | 194 | | encrypt S/MIME | | | | 195 | | message data. | | | | 196 +----------+---------------------+---------------------+---------------+---------------------+ 197 | softoken | Provides a software | PKCS #11: | lib/softoken | keydbt.h, keylow.h, | 198 | | implementation of a | implementation | | keytboth.h, | 199 | | PKCS #11 module. | | | keytlow.h, | 200 | | | | | secpkcs5.h, | 201 | | | | | pkcs11.h, | 202 | | | | | pkcs11f.h, | 203 | | | | | pkcs11p.h, | 204 | | | | | pkcs11t.h, | 205 | | | | | pkcs11u.h | 206 +----------+---------------------+---------------------+---------------+---------------------+ 207 | ssl | Provides an | SSL | lib/ssl | ssl.h, sslerr.h, | 208 | | implementation of | | | sslproto.h, | 209 | | the SSL protocol | | | preenc.h | 210 | | using NSS and NSPR. | | | | 211 +----------+---------------------+---------------------+---------------+---------------------+ 212 | secutil | Provides utility | Utility for any | lib/util | base64.h, | 213 | | functions and data | Layer | | ciferfam.h, | 214 | | types used by other | | | nssb64.h, | 215 | | libraries. The | | | nssb64t.h, | 216 | | library supports | | | nsslocks.h, | 217 | | base-64 | | | nssrwlk.h, | 218 | | encoding/decoding, | | | nssrwlkt.h, | 219 | | reader-writer | | | portreg.h, | 220 | | locks, the SECItem | | | pqgutil.h, | 221 | | data type, DER | | | secasn1.h, | 222 | | encoding/decoding, | | | secasn1t.h, | 223 | | error types and | | | seccomon.h, | 224 | | numbers, OID | | | secder.h, | 225 | | handling, and | | | secdert.h, | 226 | | secure random | | | secdig.h, | 227 | | number generation. | | | secdigt.h, | 228 | | | | | secitem.h, | 229 | | | | | secoid.h, | 230 | | | | | secoidt.h, | 231 | | | | | secport.h, | 232 | | | | | secrng.h, | 233 | | | | | secrngt.h, | 234 | | | | | secerr.h, | 235 | | | | | watcomfx.h | 236 +----------+---------------------+---------------------+---------------+---------------------+ 237 238 .. _naming_conventions: 239 240 `Naming Conventions <#_naming_conventions>`__ 241 --------------------------------------------- 242 243 .. container:: 244 245 This section describes the rules that (ideally) should be followed for naming and identifying new 246 files, functions, and data types. 247 248 .. _header_files: 249 250 `Header Files <#header_files>`__ 251 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 252 253 .. container:: 254 255 | We have a preferred naming system for include files. We had been moving towards one, for some 256 time, but for the NSS 3.0 project we finally wrote it down. 257 | 258 259 ========================= =========== =================== 260 \ Data Types Function Prototypes 261 Public nss____t.h nss____.h 262 Friend (only if required) nss____tf.h nss____f.h 263 NSS-private \____t.h \____.h 264 Module-private \____tm.h \____m.h 265 ========================= =========== =================== 266 267 The files on the right include the files to their left; the files in a row include the files 268 directly above them. Header files always include what they need; the files are protected against 269 double inclusion (and even double opening by the compiler). 270 271 .. note:: 272 273 Note: It's not necessary all eight files exist. Further, this is a simple ideal, and often 274 reality is more complex. 275 276 We would like to keep names to 8.3, even if we no longer support win16. This usually gives us 277 four characters to identify a module of NSS. 278 279 In short: 280 281 #. Header files for consumption outside NSS start with "nss." 282 #. Header files with types have a trailing "t", header files with prototypes don't. 283 "extern" declarations of data also go in the prototypes files. 284 #. "Friend" headers are for things that we really wish weren't used by non-NSS code, but which 285 are. Those files have a trailing "f," and their use should be deprecated. 286 #. "Module" headers are for things used only within a specific subset of NSS; things which would 287 have been "static" if we had combined separate C source files together. These header files 288 have a trailing "m." 289 290 .. _functions_and_types: 291 292 `Functions and Types <#functions_and_types>`__ 293 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 294 295 .. container:: 296 297 There are a number of ways of doing things in our API, as well as naming decisions for functions 298 that can affect the usefulness of our library. If our library is self-consistent with how we 299 accomplish these tasks, it makes it easier for the developer to learn how to use our functions. 300 This section of the document should grow as we develop our API. 301 302 First some general rules. These rules are derived from existing coding practices inside the 303 security library, since consistency is more important than debates about what might look nice. 304 305 #. **Public functions** should have the form LAYER_Body(), where LAYER is an all caps prefix for 306 what layer the function lives in, and Body is concatenated English words, where the beginning 307 letter of each word is capitalized (also known as 308 `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`__). For Example: 309 LAYER_CapitalizedEnglishWords() or CERT_DestroyCertificate(). 310 #. **Data types** and typdefs should have the Form LAYERBody, with the same definitions for LAYER 311 as public functions, and Body in camel case English words. For example: 312 LAYERCapitalizedEnglishWords or SECKEYPrivateKey. 313 #. **Structures** should have the same name as their typedefs, with the string Str added to the 314 end. For example LAYERCapitalizedEnglishWordsStr or SECKEYPrivateKeyStr. 315 #. **Private functions** should have the form layer_Body(), where layer is the all lower case 316 prefix for what layer the function lives in, and Body is camel case English words. Private 317 functions include functions that may be "public" in a C sense, but are not exported out of the 318 layer. For example: layer_CapitalizedEnglishWords() or pk11_GenerateKeyID(). 319 #. **Public macros** should have the form LAYER_BODY(), where LAYER is an all caps prefix for 320 what layer the macro lives in, and BODY is English words, all in upper case, separated by 321 underscores. For example: LAYER_UPPER_CASE_ENGLISH_WORDS() or DER_CONVERT_BIT_STRING(). 322 #. **Structure members** for exposed data structures should have the form capitalizedEnglishWords 323 (the first letter uncapitalized). For example: PK11RSAGenParamsStr.\ **keySizeInBits** 324 #. For **members of enums**, our current API has no standard (typedefs for enums should follow 325 the Data types standard). There seem to be three reasonable options: 326 327 #. Enum members have the same standard as exposed data structure members. 328 #. Enum members have the same standard as data types. 329 #. Enum members have the same standard as public macros (minus the '()' of course). 330 331 Options 2 and 3 are the more preferred options. Option 1, currently the most common used for 332 enums, actually creates namespace pollution. 333 #. **Callback functions**, and functions used in function tables, should have a typedef used to 334 define the complete signature of the given function. Function typedefs should have the 335 following format: LAYERBody(), with the same definitions for LAYER as public functions, and 336 Body is camel case English words. For example: LAYERCapitalizedEnglishWords or 337 SECKEYPrivateKey. 338 339 .. _opaque_data_structures: 340 341 `Opaque Data Structures <#_opaque_data_structures>`__ 342 ----------------------------------------------------- 343 344 .. container:: 345 346 There are many data structures in the security library whose definition is effectively private, 347 to the portion of the security library that defines and operates on those data structures. 348 External code does not have access to these definitions. The goal here is to increase the 349 opaqueness of these structures. This will allow us to modify the size, definition, and format of 350 these data structures in future releases, without interfering with the operation of existing 351 applications that use the security library. 352 353 The first task is to ensure the data structure definition lives in a private header file, while 354 its declaration lives in the public. The current standard in the security library is to typedef 355 the data structure name, the easiest way to accomplish this would be to add the typedef to the 356 public header file. 357 358 For example, for the structure SECMyOpaqueData you would add: 359 360 .. code:: 361 362 typedef struct SECMyOpaqueDataStr SECMyOpaqueData; 363 364 and add the actual structure definition to the private header file. In this same example: 365 366 .. code:: 367 368 struct SECMyOpaqueDataStr { 369 unsigned long myPrivateData1; 370 unsigned long myPrivateData2; 371 char *myName; 372 }; 373 374 the second task is to determine if individual data fields, within the data structure, are part of 375 the API.