tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

pkix_sample_modules.h (15793B)

      1 /* This Source Code Form is subject to the terms of the Mozilla Public
      2 * License, v. 2.0. If a copy of the MPL was not distributed with this
      3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
      4 /*
      5 * This file defines functions associated with CertStore types.
      6 *
      7 */
      8 
      9 
     10 #ifndef _PKIX_SAMPLEMODULES_H
     11 #define _PKIX_SAMPLEMODULES_H
     12 
     13 #include "pkix_pl_common.h"
     14 
     15 #ifdef __cplusplus
     16 extern "C" {
     17 #endif
     18 
     19 /* General
     20 *
     21 * Please refer to the libpkix Programmer's Guide for detailed information
     22 * about how to use the libpkix library. Certain key warnings and notices from
     23 * that document are repeated here for emphasis.
     24 *
     25 * All identifiers in this file (and all public identifiers defined in
     26 * libpkix) begin with "PKIX_". Private identifiers only intended for use
     27 * within the library begin with "pkix_".
     28 *
     29 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
     30 *
     31 * Unless otherwise noted, for all accessor (gettor) functions that return a
     32 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
     33 * shared object. Therefore, the caller should treat this shared object as
     34 * read-only and should not modify this shared object. When done using the
     35 * shared object, the caller should release the reference to the object by
     36 * using the PKIX_PL_Object_DecRef function.
     37 *
     38 * While a function is executing, if its arguments (or anything referred to by
     39 * its arguments) are modified, free'd, or destroyed, the function's behavior
     40 * is undefined.
     41 *
     42 */
     43 
     44 /* PKIX_PL_CollectionCertStore
     45 *
     46 * A PKIX_CollectionCertStore provides an example for showing how to retrieve
     47 * certificates and CRLs from a repository, such as a directory in the system.
     48 * It is expected the directory is an absolute directory which contains CRL
     49 * and Cert data files.  CRL files are expected to have the suffix of .crl
     50 * and Cert files are expected to have the suffix of .crt .
     51 *
     52 * Once the caller has created the CollectionCertStoreContext object, the caller
     53 * then can call pkix_pl_CollectionCertStore_GetCert or
     54 * pkix_pl_CollectionCertStore_GetCRL to obtain Lists of PKIX_PL_Cert or
     55 * PKIX_PL_CRL objects, respectively.
     56 */
     57 
     58 /*
     59 * FUNCTION: PKIX_PL_CollectionCertStore_Create
     60 * DESCRIPTION:
     61 *
     62 *  Creates a new CollectionCertStore and returns it at
     63 *      "pColCertStore".
     64 *
     65 * PARAMETERS:
     66 *  "storeDir"
     67 *      The absolute path where *.crl files are located.
     68 *  "pColCertStoreContext"
     69 *      Address where object pointer will be stored. Must be non-NULL.
     70 *  "plContext"
     71 *      Platform-specific context pointer.
     72 * THREAD SAFETY:
     73 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
     74 * RETURNS:
     75 *  Returns NULL if the function succeeds.
     76 *  Returns a CollectionCertStoreContext Error if the function fails in
     77 *      a non-fatal way.
     78 *  Returns a Fatal Error if the function fails in an unrecoverable way.
     79 */
     80 PKIX_Error *
     81 PKIX_PL_CollectionCertStore_Create(
     82        PKIX_PL_String *storeDir,
     83        PKIX_CertStore **pCertStore,
     84        void *plContext);
     85 
     86 /* PKIX_PL_PK11CertStore
     87 *
     88 * A PKIX_PL_PK11CertStore retrieves certificates and CRLs from a PKCS11
     89 * database. The directory that contains the cert8.db, key3.db, and secmod.db
     90 * files that comprise a PKCS11 database are specified in NSS initialization.
     91 *
     92 * Once the caller has created the Pk11CertStore object, the caller can call
     93 * pkix_pl_Pk11CertStore_GetCert or pkix_pl_Pk11CertStore_GetCert to obtain
     94 * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively.
     95 */
     96 
     97 /*
     98 * FUNCTION: PKIX_PL_Pk11CertStore_Create
     99 * DESCRIPTION:
    100 *
    101 *  Creates a new Pk11CertStore and returns it at "pPk11CertStore".
    102 *
    103 * PARAMETERS:
    104 *  "pPk11CertStore"
    105 *      Address where object pointer will be stored. Must be non-NULL.
    106 *  "plContext"
    107 *      Platform-specific context pointer.
    108 * THREAD SAFETY:
    109 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    110 * RETURNS:
    111 *  Returns NULL if the function succeeds.
    112 *  Returns a CertStore Error if the function fails in a non-fatal way.
    113 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    114 */
    115 PKIX_Error *
    116 PKIX_PL_Pk11CertStore_Create(
    117        PKIX_CertStore **pPk11CertStore,
    118        void *plContext);
    119 
    120 #ifndef NSS_PKIX_NO_LDAP
    121 /* PKIX_PL_LdapCertStore
    122 *
    123 * A PKIX_PL_LdapCertStore retrieves certificates and CRLs from an LDAP server
    124 * over a socket connection. It used the LDAP protocol as described in RFC1777.
    125 *
    126 * Once the caller has created the LdapCertStore object, the caller can call
    127 * pkix_pl_LdapCertStore_GetCert or pkix_pl_LdapCertStore_GetCert to obtain
    128 * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively.
    129 */
    130 
    131 /*
    132 * FUNCTION: PKIX_PL_LdapDefaultClient_Create
    133 * DESCRIPTION:
    134 *
    135 *  Creates an LdapDefaultClient using the PRNetAddr poined to by "sockaddr",
    136 *  with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI";
    137 *  and stores the address of the default LdapClient at "pClient".
    138 *
    139 *  At the time of this version, there are unresolved questions about the LDAP
    140 *  protocol. Although RFC1777 describes a BIND and UNBIND message, it is not
    141 *  clear whether they are appropriate to this application. We have tested only
    142 *  using servers that do not expect authentication, and that reject BIND
    143 *  messages. It is not clear what values might be appropriate for the bindname
    144 *  and authentication fields, which are currently implemented as char strings
    145 *  supplied by the caller. (If this changes, the API and possibly the templates
    146 *  will have to change.) Therefore the Client_Create API contains a BindAPI
    147 *  structure, a union, which will have to be revised and extended when this
    148 *  area of the protocol is better understood.
    149 *
    150 * PARAMETERS:
    151 *  "sockaddr"
    152 *      Address of the PRNetAddr to be used for the socket connection. Must be
    153 *      non-NULL.
    154 *  "timeout"
    155 *      The PRIntervalTime value to be used as a timeout value in socket calls;
    156 *      a zero value indicates non-blocking I/O is to be used.
    157 *  "bindAPI"
    158 *      The address of a BindAPI to be used if a BIND message is required. If
    159 *      this argument is NULL, no Bind (or Unbind) will be sent.
    160 *  "pClient"
    161 *      Address where object pointer will be stored. Must be non-NULL.
    162 *  "plContext"
    163 *      Platform-specific context pointer.
    164 * THREAD SAFETY:
    165 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    166 * RETURNS:
    167 *  Returns NULL if the function succeeds.
    168 *  Returns a CertStore Error if the function fails in a non-fatal way.
    169 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    170 */
    171 PKIX_Error *
    172 PKIX_PL_LdapDefaultClient_Create(
    173        PRNetAddr *sockaddr,
    174        PRIntervalTime timeout,
    175        LDAPBindAPI *bindAPI,
    176        PKIX_PL_LdapDefaultClient **pClient,
    177        void *plContext);
    178 
    179 /*
    180 * FUNCTION: PKIX_PL_LdapDefaultClient_CreateByName
    181 * DESCRIPTION:
    182 *
    183 *  Creates an LdapDefaultClient using the hostname poined to by "hostname",
    184 *  with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI";
    185 *  and stores the address of the default LdapClient at "pClient".
    186 *
    187 *  At the time of this version, there are unresolved questions about the LDAP
    188 *  protocol. Although RFC1777 describes a BIND and UNBIND message, it is not
    189 *  clear whether they are appropriate to this application. We have tested only
    190 *  using servers that do not expect authentication, and that reject BIND
    191 *  messages. It is not clear what values might be appropriate for the bindname
    192 *  and authentication fields, which are currently implemented as char strings
    193 *  supplied by the caller. (If this changes, the API and possibly the templates
    194 *  will have to change.) Therefore the Client_Create API contains a BindAPI
    195 *  structure, a union, which will have to be revised and extended when this
    196 *  area of the protocol is better understood.
    197 *
    198 * PARAMETERS:
    199 *  "hostname"
    200 *      Address of the hostname to be used for the socket connection. Must be
    201 *      non-NULL.
    202 *  "timeout"
    203 *      The PRIntervalTime value to be used as a timeout value in socket calls;
    204 *      a zero value indicates non-blocking I/O is to be used.
    205 *  "bindAPI"
    206 *      The address of a BindAPI to be used if a BIND message is required. If
    207 *      this argument is NULL, no Bind (or Unbind) will be sent.
    208 *  "pClient"
    209 *      Address where object pointer will be stored. Must be non-NULL.
    210 *  "plContext"
    211 *      Platform-specific context pointer.
    212 * THREAD SAFETY:
    213 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    214 * RETURNS:
    215 *  Returns NULL if the function succeeds.
    216 *  Returns a CertStore Error if the function fails in a non-fatal way.
    217 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    218 */
    219 PKIX_Error *
    220 PKIX_PL_LdapDefaultClient_CreateByName(
    221        char *hostname,
    222        PRIntervalTime timeout,
    223        LDAPBindAPI *bindAPI,
    224        PKIX_PL_LdapDefaultClient **pClient,
    225        void *plContext);
    226 
    227 /*
    228 * FUNCTION: PKIX_PL_LdapCertStore_Create
    229 * DESCRIPTION:
    230 *
    231 *  Creates a new LdapCertStore using the LdapClient pointed to by "client",
    232 *  and stores the address of the CertStore at "pCertStore".
    233 *
    234 * PARAMETERS:
    235 *  "client"
    236 *      Address of the LdapClient to be used. Must be non-NULL.
    237 *  "pCertStore"
    238 *      Address where object pointer will be stored. Must be non-NULL.
    239 *  "plContext"
    240 *      Platform-specific context pointer.
    241 * THREAD SAFETY:
    242 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    243 * RETURNS:
    244 *  Returns NULL if the function succeeds.
    245 *  Returns a CertStore Error if the function fails in a non-fatal way.
    246 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    247 */
    248 PKIX_Error *
    249 PKIX_PL_LdapCertStore_Create(
    250        PKIX_PL_LdapClient *client,
    251        PKIX_CertStore **pCertStore,
    252        void *plContext);
    253 #endif /* !NSS_PKIX_NO_LDAP */
    254 
    255 /* PKIX_PL_NssContext
    256 *
    257 * A PKIX_PL_NssContext provides an example showing how the "plContext"
    258 * argument, that is part of every libpkix function call, can be used.
    259 * The "plContext" is the Portability Layer Context, which can be used
    260 * to communicate layer-specific information from the application to the
    261 * underlying Portability Layer (while bypassing the Portable Code, which
    262 * blindly passes the plContext on to every function call).
    263 *
    264 * In this case, NSS serves as both the application and the Portability Layer.
    265 * We define an NSS-specific structure, which includes an arena and a number
    266 * of SECCertificateUsage bit flags encoded as a PKIX_UInt32. A third argument,
    267 * wincx, is used on Windows platforms for PKCS11 access, and should be set to
    268 * NULL for other platforms.
    269 * Before calling any of the libpkix functions, the caller should create the NSS
    270 * context, by calling PKIX_PL_NssContext_Create, and provide that NSS context
    271 * as the "plContext" argument in every libpkix function call the caller makes.
    272 * When the caller is finished using the NSS context (usually just after he
    273 * calls PKIX_Shutdown), the caller should call PKIX_PL_NssContext_Destroy to
    274 * free the NSS context structure.
    275 */
    276 
    277 /*
    278 * FUNCTION: PKIX_PL_NssContext_Create
    279 * DESCRIPTION:
    280 *
    281 *  Creates a new NssContext using the certificate usage(s) specified by
    282 *  "certUsage" and stores it at "pNssContext". This function also internally
    283 *  creates an arena and stores it as part of the NssContext structure. Unlike
    284 *  most other libpkix API functions, this function does not take a "plContext"
    285 *  parameter.
    286 *
    287 * PARAMETERS:
    288 *  "certUsage"
    289 *      The desired SECCertificateUsage(s).
    290 *  "useNssArena"
    291 *      Boolean flag indicates NSS Arena is used for memory allocation.
    292 *  "wincx"
    293 *      A Windows-dependent pointer for PKCS11 token handling.
    294 *  "pNssContext"
    295 *      Address where object pointer will be stored. Must be non-NULL.
    296 * THREAD SAFETY:
    297 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    298 * RETURNS:
    299 *  Returns NULL if the function succeeds.
    300 *  Returns a Context Error if the function fails in a non-fatal way.
    301 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    302 */
    303 PKIX_Error *
    304 PKIX_PL_NssContext_Create(
    305        PKIX_UInt32 certificateUsage,
    306        PKIX_Boolean useNssArena,
    307        void *wincx,
    308        void **pNssContext);
    309 
    310 /*
    311 * FUNCTION: PKIX_PL_NssContext_Destroy
    312 * DESCRIPTION:
    313 *
    314 *  Frees the structure pointed to by "nssContext" along with any of its
    315 *  associated memory. Unlike most other libpkix API functions, this function
    316 *  does not take a "plContext" parameter.
    317 *
    318 * PARAMETERS:
    319 *  "nssContext"
    320 *      Address of NssContext to be destroyed. Must be non-NULL.
    321 * THREAD SAFETY:
    322 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    323 * RETURNS:
    324 *  Returns NULL if the function succeeds.
    325 *  Returns a Context Error if the function fails in a non-fatal way.
    326 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    327 */
    328 PKIX_Error *
    329 PKIX_PL_NssContext_Destroy(
    330        void *nssContext);
    331 
    332 /*
    333 * FUNCTION: PKIX_PL_NssContext_SetTimeout
    334 * DESCRIPTION:
    335 *
    336 * Sets IO timeout for network operations like OCSP response and cert
    337 * fetching.
    338 *
    339 * PARAMETERS:
    340 *  "nssContext"
    341 *      Address of NssContext to be destroyed. Must be non-NULL.
    342 * THREAD SAFETY:
    343 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    344 * RETURNS:
    345 *  Returns NULL if the function succeeds.
    346 *  Returns a Context Error if the function fails in a non-fatal way.
    347 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    348 */
    349 PKIX_Error *
    350 PKIX_PL_NssContext_SetTimeout(PKIX_UInt32 timeout, PKIX_PL_NssContext *nssContext);
    351 
    352 /*
    353 * FUNCTION: PKIX_PL_NssContext_SetMaxResponseLen
    354 * DESCRIPTION:
    355 *
    356 * Sets maximum responce length allowed during network IO operations.
    357 *
    358 * PARAMETERS:
    359 *  "nssContext"
    360 *      Address of NssContext to be destroyed. Must be non-NULL.
    361 * THREAD SAFETY:
    362 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    363 * RETURNS:
    364 *  Returns NULL if the function succeeds.
    365 *  Returns a Context Error if the function fails in a non-fatal way.
    366 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    367 */
    368 PKIX_Error *
    369 PKIX_PL_NssContext_SetMaxResponseLen(PKIX_UInt32 len, PKIX_PL_NssContext *nssContext);
    370 
    371 /*
    372 * FUNCTION: PKIX_PL_NssContext_SetCrlReloadDelay
    373 * DESCRIPTION:
    374 *
    375 * Sets user defined timeout between attempts to load crl using
    376 * CRLDP.
    377 *
    378 * PARAMETERS:
    379 *  "delaySeconds"
    380 *      Reload delay in seconds.
    381 *  "nssContext"
    382 *      Address of NssContext to be destroyed. Must be non-NULL.
    383 * THREAD SAFETY:
    384 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    385 * RETURNS:
    386 *  Returns NULL if the function succeeds.
    387 *  Returns a Context Error if the function fails in a non-fatal way.
    388 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    389 */
    390 PKIX_Error *
    391 PKIX_PL_NssContext_SetCrlReloadDelay(PKIX_UInt32 delaySeconds,
    392                                       PKIX_PL_NssContext *nssContext);
    393 
    394 /*
    395 * FUNCTION: PKIX_PL_NssContext_SetBadDerCrlReloadDelay
    396 * DESCRIPTION:
    397 *
    398 * Sets user defined timeout between attempts to load crls
    399 * that failed to decode.
    400 *
    401 * PARAMETERS:
    402 *  "delaySeconds"
    403 *      Reload delay in seconds.
    404 *  "nssContext"
    405 *      Address of NssContext to be destroyed. Must be non-NULL.
    406 * THREAD SAFETY:
    407 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
    408 * RETURNS:
    409 *  Returns NULL if the function succeeds.
    410 *  Returns a Context Error if the function fails in a non-fatal way.
    411 *  Returns a Fatal Error if the function fails in an unrecoverable way.
    412 */
    413 PKIX_Error *
    414 PKIX_PL_NssContext_SetBadDerCrlReloadDelay(PKIX_UInt32 delaySeconds,
    415                                           PKIX_PL_NssContext *nssContext);
    416 #ifdef __cplusplus
    417 }
    418 #endif
    419 
    420 #endif /* _PKIX_SAMPLEMODULES_H */