1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_certsel.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1826 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * This file defines functions associated with the PKIX_CertSelector and the
1.9 + * PKIX_ComCertSelParams types.
1.10 + *
1.11 + */
1.12 +
1.13 +#ifndef _PKIX_CERTSEL_H
1.14 +#define _PKIX_CERTSEL_H
1.15 +
1.16 +#include "pkixt.h"
1.17 +
1.18 +#ifdef __cplusplus
1.19 +extern "C" {
1.20 +#endif
1.21 +
1.22 +/* General
1.23 + *
1.24 + * Please refer to the libpkix Programmer's Guide for detailed information
1.25 + * about how to use the libpkix library. Certain key warnings and notices from
1.26 + * that document are repeated here for emphasis.
1.27 + *
1.28 + * All identifiers in this file (and all public identifiers defined in
1.29 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.30 + * within the library begin with "pkix_".
1.31 + *
1.32 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.33 + *
1.34 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.35 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.36 + * shared object. Therefore, the caller should treat this shared object as
1.37 + * read-only and should not modify this shared object. When done using the
1.38 + * shared object, the caller should release the reference to the object by
1.39 + * using the PKIX_PL_Object_DecRef function.
1.40 + *
1.41 + * While a function is executing, if its arguments (or anything referred to by
1.42 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.43 + * is undefined.
1.44 + *
1.45 + */
1.46 +
1.47 +/* PKIX_CertSelector
1.48 + *
1.49 + * PKIX_CertSelectors provide a standard way for the caller to select
1.50 + * certificates based on particular criteria. A CertSelector is typically used
1.51 + * by the caller to specify the constraints they wish to impose on the target
1.52 + * certificate in a chain. (see pkix_params.h) A CertSelector is also often
1.53 + * used to retrieve certificates from a CertStore that match the selector's
1.54 + * criteria. (See pkix_certstore.h) For example, the caller may wish to only
1.55 + * select those certificates that have a particular Subject Distinguished Name
1.56 + * and a particular value for a private certificate extension. The
1.57 + * MatchCallback allows the caller to specify the custom matching logic to be
1.58 + * used by a CertSelector.
1.59 + *
1.60 + * By default, the MatchCallback is set to point to the default implementation
1.61 + * provided by libpkix, which understands how to process the most common
1.62 + * parameters. If the default implementation is used, the caller should set
1.63 + * these common parameters using PKIX_CertSelector_SetCommonCertSelectorParams.
1.64 + * Any common parameter that is not set is assumed to be disabled, which means
1.65 + * the default MatchCallback implementation will select all certificates
1.66 + * without regard to that particular disabled parameter. For example, if the
1.67 + * SerialNumber parameter is not set, MatchCallback will not filter out any
1.68 + * certificate based on its serial number. As such, if no parameters are set,
1.69 + * all are disabled and any certificate will match. If a parameter is
1.70 + * disabled, its associated PKIX_ComCertSelParams_Get* function returns a
1.71 + * default value of NULL, or -1 for PKIX_ComCertSelParams_GetBasicConstraints
1.72 + * and PKIX_ComCertSelParams_GetVersion, or 0 for
1.73 + * PKIX_ComCertSelParams_GetKeyUsage.
1.74 + *
1.75 + * If a custom implementation is desired, the default implementation can be
1.76 + * overridden by calling PKIX_CertSelector_SetMatchCallback. In this case, the
1.77 + * CertSelector can be initialized with a certSelectorContext, which is where
1.78 + * the caller can specify the desired parameters the caller wishes to match
1.79 + * against. Note that this certSelectorContext must be an Object (although any
1.80 + * object type), allowing it to be reference-counted and allowing it to
1.81 + * provide the standard Object functions (Equals, Hashcode, ToString, Compare,
1.82 + * Duplicate).
1.83 + *
1.84 + */
1.85 +
1.86 +/*
1.87 + * FUNCTION: PKIX_CertSelector_MatchCallback
1.88 + * DESCRIPTION:
1.89 + *
1.90 + * This callback function determines whether the specified Cert pointed to by
1.91 + * "cert" matches the criteria of the CertSelector pointed to by "selector".
1.92 + * If the Cert does not matches the CertSelector's criteria, an exception will
1.93 + * be thrown.
1.94 + *
1.95 + * PARAMETERS:
1.96 + * "selector"
1.97 + * Address of CertSelector whose MatchCallback logic and parameters are
1.98 + * to be used. Must be non-NULL.
1.99 + * "cert"
1.100 + * Address of Cert that is to be matched using "selector".
1.101 + * Must be non-NULL.
1.102 + * "plContext"
1.103 + * Platform-specific context pointer.
1.104 + * THREAD SAFETY:
1.105 + * Thread Safe
1.106 + *
1.107 + * Multiple threads must be able to safely call this function without
1.108 + * worrying about conflicts, even if they're operating on the same object.
1.109 + * RETURNS:
1.110 + * Returns NULL if the function succeeds.
1.111 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.112 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.113 + */
1.114 +typedef PKIX_Error *
1.115 +(*PKIX_CertSelector_MatchCallback)(
1.116 + PKIX_CertSelector *selector,
1.117 + PKIX_PL_Cert *cert,
1.118 + void *plContext);
1.119 +
1.120 +/*
1.121 + * FUNCTION: PKIX_CertSelector_Create
1.122 + * DESCRIPTION:
1.123 + *
1.124 + * Creates a new CertSelector using the Object pointed to by
1.125 + * "certSelectorContext" (if any) and stores it at "pSelector". As noted
1.126 + * above, by default, the MatchCallback is set to point to the default
1.127 + * implementation provided by libpkix, which understands how to process
1.128 + * ComCertSelParams objects. This is overridden if the MatchCallback pointed
1.129 + * to by "callback" is not NULL, in which case the parameters are specified
1.130 + * using the certSelectorContext.
1.131 + *
1.132 + * PARAMETERS:
1.133 + * "callback"
1.134 + * The MatchCallback function to be used.
1.135 + * "certSelectorContext"
1.136 + * Address of Object representing the CertSelector's context (if any).
1.137 + * "pSelector"
1.138 + * Address where object pointer will be stored. Must be non-NULL.
1.139 + * "plContext"
1.140 + * Platform-specific context pointer.
1.141 + * THREAD SAFETY:
1.142 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.143 + * RETURNS:
1.144 + * Returns NULL if the function succeeds.
1.145 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.146 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.147 + */
1.148 +PKIX_Error *
1.149 +PKIX_CertSelector_Create(
1.150 + PKIX_CertSelector_MatchCallback callback,
1.151 + PKIX_PL_Object *certSelectorContext,
1.152 + PKIX_CertSelector **pSelector,
1.153 + void *plContext);
1.154 +
1.155 +/*
1.156 + * FUNCTION: PKIX_CertSelector_GetMatchCallback
1.157 + * DESCRIPTION:
1.158 + *
1.159 + * Retrieves a pointer to "selector's" Match callback function and puts it in
1.160 + * "pCallback".
1.161 + *
1.162 + * PARAMETERS:
1.163 + * "selector"
1.164 + * The CertSelector whose Match callback is desired. Must be non-NULL.
1.165 + * "pCallback"
1.166 + * Address where Match callback function pointer will be stored.
1.167 + * Must be non-NULL.
1.168 + * "plContext"
1.169 + * Platform-specific context pointer.
1.170 + * THREAD SAFETY:
1.171 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.172 + * RETURNS:
1.173 + * Returns NULL if the function succeeds.
1.174 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.175 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.176 + */
1.177 +PKIX_Error *
1.178 +PKIX_CertSelector_GetMatchCallback(
1.179 + PKIX_CertSelector *selector,
1.180 + PKIX_CertSelector_MatchCallback *pCallback,
1.181 + void *plContext);
1.182 +
1.183 +/*
1.184 + * FUNCTION: PKIX_CertSelector_GetCertSelectorContext
1.185 + * DESCRIPTION:
1.186 + *
1.187 + * Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
1.188 + * of the CertSelector pointed to by "selector" and stores it at
1.189 + * "pCertSelectorContext".
1.190 + *
1.191 + * PARAMETERS:
1.192 + * "selector"
1.193 + * Address of CertSelector whose context is to be stored.
1.194 + * Must be non-NULL.
1.195 + * "pCertSelectorContext"
1.196 + * Address where object pointer will be stored. Must be non-NULL.
1.197 + * "plContext"
1.198 + * Platform-specific context pointer.
1.199 + * THREAD SAFETY:
1.200 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.201 + * RETURNS:
1.202 + * Returns NULL if the function succeeds.
1.203 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.204 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.205 + */
1.206 +PKIX_Error *
1.207 +PKIX_CertSelector_GetCertSelectorContext(
1.208 + PKIX_CertSelector *selector,
1.209 + PKIX_PL_Object **pCertSelectorContext,
1.210 + void *plContext);
1.211 +
1.212 +/*
1.213 + * FUNCTION: PKIX_CertSelector_GetCommonCertSelectorParams
1.214 + * DESCRIPTION:
1.215 + *
1.216 + * Retrieves a pointer to the ComCertSelParams object that represent the
1.217 + * common parameters of the CertSelector pointed to by "selector" and stores
1.218 + * it at "pCommonCertSelectorParams". If there are no common parameters
1.219 + * stored with the CertSelector, this function stores NULL at
1.220 + * "pCommonCertSelectorParams".
1.221 + *
1.222 + * PARAMETERS:
1.223 + * "selector"
1.224 + * Address of CertSelector whose ComCertSelParams object is to be stored.
1.225 + * Must be non-NULL.
1.226 + * "pCommonCertSelectorParams"
1.227 + * Address where object pointer will be stored. Must be non-NULL.
1.228 + * "plContext"
1.229 + * Platform-specific context pointer.
1.230 + * THREAD SAFETY:
1.231 + * Conditionally Thread Safe
1.232 + * (see Thread Safety Definitions in Programmer's Guide)
1.233 + * RETURNS:
1.234 + * Returns NULL if the function succeeds.
1.235 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.236 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.237 + */
1.238 +PKIX_Error *
1.239 +PKIX_CertSelector_GetCommonCertSelectorParams(
1.240 + PKIX_CertSelector *selector,
1.241 + PKIX_ComCertSelParams **pCommonCertSelectorParams,
1.242 + void *plContext);
1.243 +
1.244 +/*
1.245 + * FUNCTION: PKIX_CertSelector_SetCommonCertSelectorParams
1.246 + * DESCRIPTION:
1.247 + *
1.248 + * Sets the common parameters for the CertSelector pointed to by "selector"
1.249 + * using the ComCertSelParams object pointed to by "commonCertSelectorParams".
1.250 + *
1.251 + * PARAMETERS:
1.252 + * "selector"
1.253 + * Address of CertSelector whose common parameters are to be set.
1.254 + * Must be non-NULL.
1.255 + * "commonCertSelectorParams"
1.256 + * Address of ComCertSelParams object representing the common parameters.
1.257 + * "plContext"
1.258 + * Platform-specific context pointer.
1.259 + * THREAD SAFETY:
1.260 + * Not Thread Safe - assumes exclusive access to "selector"
1.261 + * (see Thread Safety Definitions in Programmer's Guide)
1.262 + * RETURNS:
1.263 + * Returns NULL if the function succeeds.
1.264 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.265 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.266 + */
1.267 +PKIX_Error *
1.268 +PKIX_CertSelector_SetCommonCertSelectorParams(
1.269 + PKIX_CertSelector *selector,
1.270 + PKIX_ComCertSelParams *commonCertSelectorParams,
1.271 + void *plContext);
1.272 +
1.273 +/* PKIX_ComCertSelParams
1.274 + *
1.275 + * PKIX_ComCertSelParams objects are X.509 parameters commonly used with
1.276 + * CertSelectors, especially when enforcing constraints on a target
1.277 + * certificate or determining which certificates to retrieve from a CertStore.
1.278 + * ComCertSelParams objects are typically used with those CertSelectors that
1.279 + * use the default implementation of MatchCallback, which understands how to
1.280 + * process ComCertSelParams objects.
1.281 + */
1.282 +
1.283 +/*
1.284 + * FUNCTION: PKIX_ComCertSelParams_Create
1.285 + * DESCRIPTION:
1.286 + *
1.287 + * Creates a new ComCertSelParams object and stores it at "pParams".
1.288 + *
1.289 + * PARAMETERS:
1.290 + * "pParams"
1.291 + * Address where object pointer will be stored. Must be non-NULL.
1.292 + * "plContext"
1.293 + * Platform-specific context pointer.
1.294 + * THREAD SAFETY:
1.295 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.296 + * RETURNS:
1.297 + * Returns NULL if the function succeeds.
1.298 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.299 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.300 + */
1.301 +PKIX_Error *
1.302 +PKIX_ComCertSelParams_Create(
1.303 + PKIX_ComCertSelParams **pParams,
1.304 + void *plContext);
1.305 +
1.306 +/*
1.307 + * FUNCTION: PKIX_ComCertSelParams_GetSubjAltNames
1.308 + * DESCRIPTION:
1.309 + *
1.310 + * Retrieves a pointer to the List of GeneralNames (if any) representing the
1.311 + * subject alternative names criterion that is set in the ComCertSelParams
1.312 + * object pointed to by "params" and stores it at "pNames". In order to match
1.313 + * against this criterion, a certificate must contain all or at least one of
1.314 + * the criterion's subject alternative names (depending on the result of
1.315 + * PKIX_ComCertSelParams_GetMatchAllSubjAltNames). The default behavior
1.316 + * requires a certificate to contain all of the criterion's subject
1.317 + * alternative names in order to match.
1.318 + *
1.319 + * If "params" does not have this criterion set, this function stores NULL at
1.320 + * "pNames", in which case all certificates are considered to match this
1.321 + * criterion.
1.322 + *
1.323 + * Note that the List returned by this function is immutable.
1.324 + *
1.325 + * PARAMETERS:
1.326 + * "params"
1.327 + * Address of ComCertSelParams object whose subject alternative names
1.328 + * criterion (if any) is to be stored. Must be non-NULL.
1.329 + * "pNames"
1.330 + * Address where object pointer will be stored. Must be non-NULL.
1.331 + * "plContext"
1.332 + * Platform-specific context pointer.
1.333 + * THREAD SAFETY:
1.334 + * Conditionally Thread Safe
1.335 + * (see Thread Safety Definitions in Programmer's Guide)
1.336 + * RETURNS:
1.337 + * Returns NULL if the function succeeds.
1.338 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.339 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.340 + */
1.341 +PKIX_Error *
1.342 +PKIX_ComCertSelParams_GetSubjAltNames(
1.343 + PKIX_ComCertSelParams *params,
1.344 + PKIX_List **pNames, /* list of PKIX_PL_GeneralName */
1.345 + void *plContext);
1.346 +
1.347 +/*
1.348 + * FUNCTION: PKIX_ComCertSelParams_SetSubjAltNames
1.349 + * DESCRIPTION:
1.350 + *
1.351 + * Sets the subject alternative names criterion of the ComCertSelParams object
1.352 + * pointed to by "params" using a List of GeneralNames pointed to by "names".
1.353 + * In order to match against this criterion, a certificate must contain all or
1.354 + * at least one of the criterion's subject alternative names (depending on the
1.355 + * result of PKIX_ComCertSelParams_GetMatchAllSubjAltNames). The default
1.356 + * behavior requires a certificate to contain all of the criterion's subject
1.357 + * alternative names in order to match.
1.358 + *
1.359 + * If "names" is NULL, all certificates are considered to match this
1.360 + * criterion.
1.361 + *
1.362 + * PARAMETERS:
1.363 + * "params"
1.364 + * Address of ComCertSelParams object whose subject alternative
1.365 + * names criterion is to be set. Must be non-NULL.
1.366 + * "names"
1.367 + * Address of List of GeneralNames used to set the criterion
1.368 + * (or NULL to disable the criterion).
1.369 + * "plContext"
1.370 + * Platform-specific context pointer.
1.371 + * THREAD SAFETY:
1.372 + * Not Thread Safe - assumes exclusive access to "params"
1.373 + * (see Thread Safety Definitions in Programmer's Guide)
1.374 + * RETURNS:
1.375 + * Returns NULL if the function succeeds.
1.376 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.377 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.378 + */
1.379 +PKIX_Error *
1.380 +PKIX_ComCertSelParams_SetSubjAltNames(
1.381 + PKIX_ComCertSelParams *params,
1.382 + PKIX_List *names, /* list of PKIX_PL_GeneralName */
1.383 + void *plContext);
1.384 +
1.385 +/*
1.386 + * FUNCTION: PKIX_ComCertSelParams_AddSubjAltName
1.387 + * DESCRIPTION:
1.388 + *
1.389 + * Adds to the subject alternative names criterion of the ComCertSelParams
1.390 + * object pointed to by "params" using the GeneralName pointed to by "name".
1.391 + * In order to match against this criterion, a certificate must contain all
1.392 + * or at least one of the criterion's subject alternative names (depending on
1.393 + * the result of PKIX_ComCertSelParams_GetMatchAllSubjAltNames). The default
1.394 + * behavior requires a certificate to contain all of the criterion's subject
1.395 + * alternative names in order to match.
1.396 + *
1.397 + * PARAMETERS:
1.398 + * "params"
1.399 + * Address of ComCertSelParams object whose subject alternative names
1.400 + * criterion is to be added to. Must be non-NULL.
1.401 + * "name"
1.402 + * Address of GeneralName to be added.
1.403 + * "plContext"
1.404 + * Platform-specific context pointer.
1.405 + * THREAD SAFETY:
1.406 + * Not Thread Safe - assumes exclusive access to "params"
1.407 + * (see Thread Safety Definitions in Programmer's Guide)
1.408 + * RETURNS:
1.409 + * Returns NULL if the function succeeds.
1.410 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.411 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.412 + */
1.413 +PKIX_Error *
1.414 +PKIX_ComCertSelParams_AddSubjAltName(
1.415 + PKIX_ComCertSelParams *params,
1.416 + PKIX_PL_GeneralName *name,
1.417 + void *plContext);
1.418 +
1.419 +/*
1.420 + * FUNCTION: PKIX_ComCertSelParams_GetPathToNames
1.421 + * DESCRIPTION:
1.422 + *
1.423 + * Retrieves a pointer to the List of GeneralNames (if any) representing the
1.424 + * path to names criterion that is set in the ComCertSelParams object pointed
1.425 + * to by "params" and stores it at "pNames". In order to match against this
1.426 + * criterion, a certificate must not include name constraints that would
1.427 + * prohibit building a path to the criterion's specified names.
1.428 + *
1.429 + * If "params" does not have this criterion set, this function stores NULL at
1.430 + * "pNames", in which case all certificates are considered to match this
1.431 + * criterion.
1.432 + *
1.433 + * Note that the List returned by this function is immutable.
1.434 + *
1.435 + * PARAMETERS:
1.436 + * "params"
1.437 + * Address of ComCertSelParams object whose path to names criterion
1.438 + * (if any) is to be stored. Must be non-NULL.
1.439 + * "pNames"
1.440 + * Address where object pointer will be stored. Must be non-NULL.
1.441 + * "plContext"
1.442 + * Platform-specific context pointer.
1.443 + * THREAD SAFETY:
1.444 + * Conditionally Thread Safe
1.445 + * (see Thread Safety Definitions in Programmer's Guide)
1.446 + * RETURNS:
1.447 + * Returns NULL if the function succeeds.
1.448 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.449 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.450 + */
1.451 +PKIX_Error *
1.452 +PKIX_ComCertSelParams_GetPathToNames(
1.453 + PKIX_ComCertSelParams *params,
1.454 + PKIX_List **pNames, /* list of PKIX_PL_GeneralName */
1.455 + void *plContext);
1.456 +
1.457 +/*
1.458 + * FUNCTION: PKIX_ComCertSelParams_SetPathToNames
1.459 + * DESCRIPTION:
1.460 + *
1.461 + * Sets the path to names criterion of the ComCertSelParams object pointed to
1.462 + * by "params" using a List of GeneralNames pointed to by "names". In order to
1.463 + * match against this criterion, a certificate must not include name
1.464 + * constraints that would prohibit building a path to the criterion's
1.465 + * specified names.
1.466 + *
1.467 + * If "names" is NULL, all certificates are considered to match this
1.468 + * criterion.
1.469 + *
1.470 + * PARAMETERS:
1.471 + * "params"
1.472 + * Address of ComCertSelParams object whose path to names criterion
1.473 + * is to be set. Must be non-NULL.
1.474 + * "names"
1.475 + * Address of List of GeneralNames used to set the criterion
1.476 + * (or NULL to disable the criterion).
1.477 + * "plContext"
1.478 + * Platform-specific context pointer.
1.479 + * THREAD SAFETY:
1.480 + * Not Thread Safe - assumes exclusive access to "params"
1.481 + * (see Thread Safety Definitions in Programmer's Guide)
1.482 + * RETURNS:
1.483 + * Returns NULL if the function succeeds.
1.484 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.485 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.486 + */
1.487 +PKIX_Error *
1.488 +PKIX_ComCertSelParams_SetPathToNames(
1.489 + PKIX_ComCertSelParams *params,
1.490 + PKIX_List *names, /* list of PKIX_PL_GeneralName */
1.491 + void *plContext);
1.492 +
1.493 +/*
1.494 + * FUNCTION: PKIX_ComCertSelParams_AddPathToName
1.495 + * DESCRIPTION:
1.496 + *
1.497 + * Adds to the path to names criterion of the ComCertSelParams object pointed
1.498 + * to by "params" using the GeneralName pointed to by "pathToName". In order
1.499 + * to match against this criterion, a certificate must not include name
1.500 + * constraints that would prohibit building a path to the criterion's
1.501 + * specified names.
1.502 + *
1.503 + * PARAMETERS:
1.504 + * "params"
1.505 + * Address of ComCertSelParams object whose path to names criterion is to
1.506 + * be added to. Must be non-NULL.
1.507 + * "pathToName"
1.508 + * Address of GeneralName to be added.
1.509 + * "plContext"
1.510 + * Platform-specific context pointer.
1.511 + * THREAD SAFETY:
1.512 + * Not Thread Safe - assumes exclusive access to "params"
1.513 + * (see Thread Safety Definitions in Programmer's Guide)
1.514 + * RETURNS:
1.515 + * Returns NULL if the function succeeds.
1.516 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.517 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.518 + */
1.519 +PKIX_Error *
1.520 +PKIX_ComCertSelParams_AddPathToName(
1.521 + PKIX_ComCertSelParams *params,
1.522 + PKIX_PL_GeneralName *pathToName,
1.523 + void *plContext);
1.524 +
1.525 +/*
1.526 + * FUNCTION: PKIX_ComCertSelParams_GetAuthorityKeyIdentifier
1.527 + * DESCRIPTION:
1.528 + *
1.529 + * Retrieves a pointer to the ByteArray (if any) representing the authority
1.530 + * key identifier criterion that is set in the ComCertSelParams object
1.531 + * pointed to by "params" and stores it at "pAuthKeyId". In order to match
1.532 + * against this criterion, a certificate must contain an
1.533 + * AuthorityKeyIdentifier extension whose value matches the criterion's
1.534 + * authority key identifier value.
1.535 + *
1.536 + * If "params" does not have this criterion set, this function stores NULL at
1.537 + * "pAuthKeyId", in which case all certificates are considered to match this
1.538 + * criterion.
1.539 + *
1.540 + * PARAMETERS:
1.541 + * "params"
1.542 + * Address of ComCertSelParams object whose authority key identifier
1.543 + * criterion (if any) is to be stored. Must be non-NULL.
1.544 + * "pAuthKeyId"
1.545 + * Address where object pointer will be stored. Must be non-NULL.
1.546 + * "plContext"
1.547 + * Platform-specific context pointer.
1.548 + * THREAD SAFETY:
1.549 + * Conditionally Thread Safe
1.550 + * (see Thread Safety Definitions in Programmer's Guide)
1.551 + * RETURNS:
1.552 + * Returns NULL if the function succeeds.
1.553 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.554 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.555 + */
1.556 +PKIX_Error *
1.557 +PKIX_ComCertSelParams_GetAuthorityKeyIdentifier(
1.558 + PKIX_ComCertSelParams *params,
1.559 + PKIX_PL_ByteArray **pAuthKeyId,
1.560 + void *plContext);
1.561 +
1.562 +/*
1.563 + * FUNCTION: PKIX_ComCertSelParams_SetAuthorityKeyIdentifier
1.564 + * DESCRIPTION:
1.565 + *
1.566 + * Sets the authority key identifier criterion of the ComCertSelParams object
1.567 + * pointed to by "params" to the ByteArray pointed to by "authKeyId". In
1.568 + * order to match against this criterion, a certificate must contain an
1.569 + * AuthorityKeyIdentifier extension whose value matches the criterion's
1.570 + * authority key identifier value.
1.571 + *
1.572 + * PARAMETERS:
1.573 + * "params"
1.574 + * Address of ComCertSelParams object whose authority key identifier
1.575 + * criterion is to be set. Must be non-NULL.
1.576 + * "authKeyId"
1.577 + * Address of ByteArray used to set the criterion
1.578 + * "plContext"
1.579 + * Platform-specific context pointer.
1.580 + * THREAD SAFETY:
1.581 + * Not Thread Safe - assumes exclusive access to "params"
1.582 + * (see Thread Safety Definitions in Programmer's Guide)
1.583 + * RETURNS:
1.584 + * Returns NULL if the function succeeds.
1.585 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.586 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.587 + */
1.588 +PKIX_Error *
1.589 +PKIX_ComCertSelParams_SetAuthorityKeyIdentifier(
1.590 + PKIX_ComCertSelParams *params,
1.591 + PKIX_PL_ByteArray *authKeyId,
1.592 + void *plContext);
1.593 +
1.594 +/*
1.595 + * FUNCTION: PKIX_ComCertSelParams_GetSubjKeyIdentifier
1.596 + * DESCRIPTION:
1.597 + *
1.598 + * Retrieves a pointer to the ByteArray (if any) representing the subject key
1.599 + * identifier criterion that is set in the ComCertSelParams object pointed to
1.600 + * by "params" and stores it at "pSubjKeyId". In order to match against this
1.601 + * criterion, a certificate must contain a SubjectKeyIdentifier extension
1.602 + * whose value matches the criterion's subject key identifier value.
1.603 + *
1.604 + * If "params" does not have this criterion set, this function stores NULL at
1.605 + * "pSubjKeyId", in which case all certificates are considered to match this
1.606 + * criterion.
1.607 + *
1.608 + * PARAMETERS:
1.609 + * "params"
1.610 + * Address of ComCertSelParams object whose subject key identifier
1.611 + * criterion (if any) is to be stored. Must be non-NULL.
1.612 + * "pSubjKeyId"
1.613 + * Address where object pointer will be stored. Must be non-NULL.
1.614 + * "plContext"
1.615 + * Platform-specific context pointer.
1.616 + * THREAD SAFETY:
1.617 + * Conditionally Thread Safe
1.618 + * (see Thread Safety Definitions in Programmer's Guide)
1.619 + * RETURNS:
1.620 + * Returns NULL if the function succeeds.
1.621 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.622 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.623 + */
1.624 +PKIX_Error *
1.625 +PKIX_ComCertSelParams_GetSubjKeyIdentifier(
1.626 + PKIX_ComCertSelParams *params,
1.627 + PKIX_PL_ByteArray **pSubjKeyId,
1.628 + void *plContext);
1.629 +
1.630 +/*
1.631 + * FUNCTION: PKIX_ComCertSelParams_SetSubjKeyIdentifier
1.632 + * DESCRIPTION:
1.633 + *
1.634 + * Sets the subject key identifier criterion of the ComCertSelParams object
1.635 + * pointed to by "params" using a ByteArray pointed to by "subjKeyId". In
1.636 + * order to match against this criterion, a certificate must contain an
1.637 + * SubjectKeyIdentifier extension whose value matches the criterion's subject
1.638 + * key identifier value.
1.639 + *
1.640 + * PARAMETERS:
1.641 + * "params"
1.642 + * Address of ComCertSelParams object whose subject key identifier
1.643 + * criterion is to be set. Must be non-NULL.
1.644 + * "subjKeyId"
1.645 + * Address of ByteArray used to set the criterion
1.646 + * "plContext"
1.647 + * Platform-specific context pointer.
1.648 + * THREAD SAFETY:
1.649 + * Not Thread Safe - assumes exclusive access to "params"
1.650 + * (see Thread Safety Definitions in Programmer's Guide)
1.651 + * RETURNS:
1.652 + * Returns NULL if the function succeeds.
1.653 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.654 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.655 + */
1.656 +PKIX_Error *
1.657 +PKIX_ComCertSelParams_SetSubjKeyIdentifier(
1.658 + PKIX_ComCertSelParams *params,
1.659 + PKIX_PL_ByteArray *subKeyId,
1.660 + void *plContext);
1.661 +
1.662 +/*
1.663 + * FUNCTION: PKIX_ComCertSelParams_GetSubjPubKey
1.664 + * DESCRIPTION:
1.665 + *
1.666 + * Retrieves a pointer to the PublicKey (if any) representing the subject
1.667 + * public key criterion that is set in the ComCertSelParams object pointed to
1.668 + * by "params" and stores it at "pPubKey". In order to match against this
1.669 + * criterion, a certificate must contain a SubjectPublicKey that matches the
1.670 + * criterion's public key.
1.671 + *
1.672 + * If "params" does not have this criterion set, this function stores NULL at
1.673 + * "pPubKey", in which case all certificates are considered to match this
1.674 + * criterion.
1.675 + *
1.676 + * PARAMETERS:
1.677 + * "params"
1.678 + * Address of ComCertSelParams object whose subject public key criterion
1.679 + * (if any) is to be stored. Must be non-NULL.
1.680 + * "pPubKey"
1.681 + * Address where object pointer will be stored. Must be non-NULL.
1.682 + * "plContext"
1.683 + * Platform-specific context pointer.
1.684 + * THREAD SAFETY:
1.685 + * Conditionally Thread Safe
1.686 + * (see Thread Safety Definitions in Programmer's Guide)
1.687 + * RETURNS:
1.688 + * Returns NULL if the function succeeds.
1.689 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.690 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.691 + */
1.692 +PKIX_Error *
1.693 +PKIX_ComCertSelParams_GetSubjPubKey(
1.694 + PKIX_ComCertSelParams *params,
1.695 + PKIX_PL_PublicKey **pPubKey,
1.696 + void *plContext);
1.697 +
1.698 +/*
1.699 + * FUNCTION: PKIX_ComCertSelParams_SetSubjPubKey
1.700 + * DESCRIPTION:
1.701 + *
1.702 + * Sets the subject public key criterion of the ComCertSelParams object
1.703 + * pointed to by "params" using a PublicKey pointed to by "pubKey". In order
1.704 + * to match against this criterion, a certificate must contain a
1.705 + * SubjectPublicKey that matches the criterion's public key.
1.706 + *
1.707 + * PARAMETERS:
1.708 + * "params"
1.709 + * Address of ComCertSelParams object whose subject public key
1.710 + * criterion is to be set. Must be non-NULL.
1.711 + * "pubKey"
1.712 + * Address of PublicKey used to set the criterion
1.713 + * "plContext"
1.714 + * Platform-specific context pointer.
1.715 + * THREAD SAFETY:
1.716 + * Not Thread Safe - assumes exclusive access to "params"
1.717 + * (see Thread Safety Definitions in Programmer's Guide)
1.718 + * RETURNS:
1.719 + * Returns NULL if the function succeeds.
1.720 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.721 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.722 + */
1.723 +PKIX_Error *
1.724 +PKIX_ComCertSelParams_SetSubjPubKey(
1.725 + PKIX_ComCertSelParams *params,
1.726 + PKIX_PL_PublicKey *pubKey,
1.727 + void *plContext);
1.728 +
1.729 +/*
1.730 + * FUNCTION: PKIX_ComCertSelParams_GetSubjPKAlgId
1.731 + * DESCRIPTION:
1.732 + *
1.733 + * Retrieves a pointer to the OID (if any) representing the subject public key
1.734 + * algorithm identifier criterion that is set in the ComCertSelParams object
1.735 + * pointed to by "params" and stores it at "pPubKey". In order to match
1.736 + * against this criterion, a certificate must contain a SubjectPublicKey with
1.737 + * an algorithm that matches the criterion's algorithm.
1.738 + *
1.739 + * If "params" does not have this criterion set, this function stores NULL at
1.740 + * "pAlgId", in which case all certificates are considered to match this
1.741 + * criterion.
1.742 + *
1.743 + * PARAMETERS:
1.744 + * "params"
1.745 + * Address of ComCertSelParams object whose subject public key algorithm
1.746 + * identifier (if any) is to be stored. Must be non-NULL.
1.747 + * "pAlgId"
1.748 + * Address where object pointer will be stored. Must be non-NULL.
1.749 + * "plContext"
1.750 + * Platform-specific context pointer.
1.751 + * THREAD SAFETY:
1.752 + * Conditionally Thread Safe
1.753 + * (see Thread Safety Definitions in Programmer's Guide)
1.754 + * RETURNS:
1.755 + * Returns NULL if the function succeeds.
1.756 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.757 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.758 + */
1.759 +PKIX_Error *
1.760 +PKIX_ComCertSelParams_GetSubjPKAlgId(
1.761 + PKIX_ComCertSelParams *params,
1.762 + PKIX_PL_OID **pAlgId,
1.763 + void *plContext);
1.764 +
1.765 +/*
1.766 + * FUNCTION: PKIX_ComCertSelParams_SetSubjPKAlgId
1.767 + * DESCRIPTION:
1.768 + *
1.769 + * Sets the subject public key algorithm identifier criterion of the
1.770 + * ComCertSelParams object pointed to by "params" using an OID pointed to by
1.771 + * "algId". In order to match against this criterion, a certificate must
1.772 + * contain a SubjectPublicKey with an algorithm that matches the criterion's
1.773 + * algorithm.
1.774 + *
1.775 + * If "algId" is NULL, all certificates are considered to match this
1.776 + * criterion.
1.777 + *
1.778 + * PARAMETERS:
1.779 + * "params"
1.780 + * Address of ComCertSelParams object whose subject public key
1.781 + * algorithm identifier criterion is to be set. Must be non-NULL.
1.782 + * "algId"
1.783 + * Address of OID used to set criterion
1.784 + * (or NULL to disable the criterion).
1.785 + * "plContext"
1.786 + * Platform-specific context pointer.
1.787 + * THREAD SAFETY:
1.788 + * Not Thread Safe - assumes exclusive access to "params"
1.789 + * (see Thread Safety Definitions in Programmer's Guide)
1.790 + * RETURNS:
1.791 + * Returns NULL if the function succeeds.
1.792 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.793 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.794 + */
1.795 +PKIX_Error *
1.796 +PKIX_ComCertSelParams_SetSubjPKAlgId(
1.797 + PKIX_ComCertSelParams *params,
1.798 + PKIX_PL_OID *algId,
1.799 + void *plContext);
1.800 +
1.801 +/*
1.802 + * FUNCTION: PKIX_ComCertSelParams_GetBasicConstraints
1.803 + * DESCRIPTION:
1.804 + *
1.805 + * Retrieves a pointer to the minimum path length (if any) representing the
1.806 + * basic constraints criterion that is set in the ComCertSelParams object
1.807 + * pointed to by "params" and stores it at "pMinPathLength". In order to
1.808 + * match against this criterion, there are several possibilities.
1.809 + *
1.810 + * 1) If the criterion's minimum path length is greater than or equal to zero,
1.811 + * a certificate must include a BasicConstraints extension with a pathLen of
1.812 + * at least this value.
1.813 + *
1.814 + * 2) If the criterion's minimum path length is -2, a certificate must be an
1.815 + * end-entity certificate.
1.816 + *
1.817 + * 3) If the criterion's minimum path length is -1, no basic constraints check
1.818 + * is done and all certificates are considered to match this criterion.
1.819 + *
1.820 + * The semantics of other values of the criterion's minimum path length are
1.821 + * undefined but may be defined in future versions of the API.
1.822 + *
1.823 + * If "params" does not have this criterion set, this function stores -1 at
1.824 + * "pMinPathLength", in which case all certificates are considered to match
1.825 + * this criterion.
1.826 + *
1.827 + * PARAMETERS:
1.828 + * "params"
1.829 + * Address of ComCertSelParams object whose basic constraints criterion
1.830 + * (if any) is to be stored. Must be non-NULL.
1.831 + * "pMinPathLength"
1.832 + * Address where PKIX_Int32 will be stored. Must be non-NULL.
1.833 + * "plContext"
1.834 + * Platform-specific context pointer.
1.835 + * THREAD SAFETY:
1.836 + * Conditionally Thread Safe
1.837 + * (see Thread Safety Definitions in Programmer's Guide)
1.838 + * RETURNS:
1.839 + * Returns NULL if the function succeeds.
1.840 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.841 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.842 + */
1.843 +PKIX_Error *
1.844 +PKIX_ComCertSelParams_GetBasicConstraints(
1.845 + PKIX_ComCertSelParams *params,
1.846 + PKIX_Int32 *pMinPathLength,
1.847 + void *plContext);
1.848 +
1.849 +/*
1.850 + * FUNCTION: PKIX_ComCertSelParams_SetBasicConstraints
1.851 + * DESCRIPTION:
1.852 + *
1.853 + * Sets the basic constraints criterion of the ComCertSelParams object
1.854 + * pointed to by "params" using the integer value of "minPathLength". In
1.855 + * order to match against this criterion, there are several possibilities.
1.856 + *
1.857 + * 1) If the criterion's minimum path length is greater than or equal to zero,
1.858 + * a certificate must include a BasicConstraints extension with a pathLen of
1.859 + * at least this value.
1.860 + *
1.861 + * 2) If the criterion's minimum path length is -2, a certificate must be an
1.862 + * end-entity certificate.
1.863 + *
1.864 + * 3) If the criterion's minimum path length is -1, no basic constraints check
1.865 + * is done and all certificates are considered to match this criterion.
1.866 + *
1.867 + * The semantics of other values of the criterion's minimum path length are
1.868 + * undefined but may be defined in future versions of the API.
1.869 + *
1.870 + * PARAMETERS:
1.871 + * "params"
1.872 + * Address of ComCertSelParams object whose basic constraints
1.873 + * criterion is to be set. Must be non-NULL.
1.874 + * "minPathLength"
1.875 + * Value of PKIX_Int32 used to set the criterion
1.876 + * (or -1 to disable the criterion).
1.877 + * "plContext"
1.878 + * Platform-specific context pointer.
1.879 + * THREAD SAFETY:
1.880 + * Not Thread Safe - assumes exclusive access to "params"
1.881 + * (see Thread Safety Definitions in Programmer's Guide)
1.882 + * RETURNS:
1.883 + * Returns NULL if the function succeeds.
1.884 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.885 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.886 + */
1.887 +PKIX_Error *
1.888 +PKIX_ComCertSelParams_SetBasicConstraints(
1.889 + PKIX_ComCertSelParams *params,
1.890 + PKIX_Int32 minPathLength,
1.891 + void *plContext);
1.892 +
1.893 +/*
1.894 + * FUNCTION: PKIX_ComCertSelParams_GetCertificate
1.895 + * DESCRIPTION:
1.896 + *
1.897 + * Retrieves a pointer to the Cert (if any) representing the certificate
1.898 + * criterion that is set in the ComCertSelParams object pointed to by
1.899 + * "params" and stores it at "pCert". In order to match against this
1.900 + * criterion, a certificate must be equal to the criterion's certificate. If
1.901 + * this criterion is specified, it is usually not necessary to specify any
1.902 + * other criteria, since this criterion requires an exact certificate match.
1.903 + *
1.904 + * If "params" does not have this criterion set, this function stores NULL at
1.905 + * "pCert", in which case all certificates are considered to match this
1.906 + * criterion.
1.907 + *
1.908 + * PARAMETERS:
1.909 + * "params"
1.910 + * Address of ComCertSelParams object whose certificate criterion
1.911 + * (if any) is to be stored. Must be non-NULL.
1.912 + * "pCert"
1.913 + * Address where object pointer will be stored. Must be non-NULL.
1.914 + * "plContext"
1.915 + * Platform-specific context pointer.
1.916 + * THREAD SAFETY:
1.917 + * Conditionally Thread Safe
1.918 + * (see Thread Safety Definitions in Programmer's Guide)
1.919 + * RETURNS:
1.920 + * Returns NULL if the function succeeds.
1.921 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.922 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.923 + */
1.924 +PKIX_Error *
1.925 +PKIX_ComCertSelParams_GetCertificate(
1.926 + PKIX_ComCertSelParams *params,
1.927 + PKIX_PL_Cert **pCert,
1.928 + void *plContext);
1.929 +
1.930 +/*
1.931 + * FUNCTION: PKIX_ComCertSelParams_SetCertificate
1.932 + * DESCRIPTION:
1.933 + *
1.934 + * Sets the certificate criterion of the ComCertSelParams object pointed to by
1.935 + * "params" using a Cert pointed to by "cert". In order to match against this
1.936 + * criterion, a certificate must be equal to the criterion's certificate.
1.937 + * If this criterion is specified, it is usually not necessary to specify
1.938 + * any other criteria, since this criterion requires an exact certificate
1.939 + * match.
1.940 + *
1.941 + * If "cert" is NULL, all certificates are considered to match this criterion.
1.942 + *
1.943 + * PARAMETERS:
1.944 + * "params"
1.945 + * Address of ComCertSelParams object whose certificate criterion is to be
1.946 + * set. Must be non-NULL.
1.947 + * "cert"
1.948 + * Address of Cert used to set the criterion
1.949 + * (or NULL to disable the criterion).
1.950 + * "plContext"
1.951 + * Platform-specific context pointer.
1.952 + * THREAD SAFETY:
1.953 + * Not Thread Safe - assumes exclusive access to "params"
1.954 + * (see Thread Safety Definitions in Programmer's Guide)
1.955 + * RETURNS:
1.956 + * Returns NULL if the function succeeds.
1.957 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.958 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.959 + */
1.960 +PKIX_Error *
1.961 +PKIX_ComCertSelParams_SetCertificate(
1.962 + PKIX_ComCertSelParams *params,
1.963 + PKIX_PL_Cert *cert,
1.964 + void *plContext);
1.965 +
1.966 +/*
1.967 + * FUNCTION: PKIX_ComCertSelParams_GetCertificateValid
1.968 + * DESCRIPTION:
1.969 + *
1.970 + * Retrieves a pointer to the Date (if any) representing the certificate
1.971 + * validity criterion that is set in the ComCertSelParams object pointed to by
1.972 + * "params" and stores it at "pDate". In order to match against this
1.973 + * criterion, a certificate's validity period must include the criterion's
1.974 + * Date.
1.975 + *
1.976 + * If "params" does not have this criterion set, this function stores NULL at
1.977 + * "pDate", in which case all certificates are considered to match this
1.978 + * criterion.
1.979 + *
1.980 + * PARAMETERS:
1.981 + * "params"
1.982 + * Address of ComCertSelParams object whose certificate validity criterion
1.983 + * (if any) is to be stored. Must be non-NULL.
1.984 + * "pDate"
1.985 + * Address where object pointer will be stored. Must be non-NULL.
1.986 + * "plContext"
1.987 + * Platform-specific context pointer.
1.988 + * THREAD SAFETY:
1.989 + * Conditionally Thread Safe
1.990 + * (see Thread Safety Definitions in Programmer's Guide)
1.991 + * RETURNS:
1.992 + * Returns NULL if the function succeeds.
1.993 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.994 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.995 + */
1.996 +PKIX_Error *
1.997 +PKIX_ComCertSelParams_GetCertificateValid(
1.998 + PKIX_ComCertSelParams *params,
1.999 + PKIX_PL_Date **pDate,
1.1000 + void *plContext);
1.1001 +
1.1002 +/*
1.1003 + * FUNCTION: PKIX_ComCertSelParams_SetCertificateValid
1.1004 + * DESCRIPTION:
1.1005 + *
1.1006 + * Sets the certificate validity criterion of the ComCertSelParams object
1.1007 + * pointed to by "params" using a Date pointed to by "date". In order to
1.1008 + * match against this criterion, a certificate's validity period must include
1.1009 + * the criterion's Date.
1.1010 + *
1.1011 + * If "date" is NULL, all certificates are considered to match this criterion.
1.1012 + *
1.1013 + * PARAMETERS:
1.1014 + * "params"
1.1015 + * Address of ComCertSelParams object whose certificate validity criterion
1.1016 + * is to be set. Must be non-NULL.
1.1017 + * "date"
1.1018 + * Address of Date used to set the criterion
1.1019 + * (or NULL to disable the criterion).
1.1020 + * "plContext"
1.1021 + * Platform-specific context pointer.
1.1022 + * THREAD SAFETY:
1.1023 + * Not Thread Safe - assumes exclusive access to "params"
1.1024 + * (see Thread Safety Definitions in Programmer's Guide)
1.1025 + * RETURNS:
1.1026 + * Returns NULL if the function succeeds.
1.1027 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1028 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1029 + */
1.1030 +PKIX_Error *
1.1031 +PKIX_ComCertSelParams_SetCertificateValid(
1.1032 + PKIX_ComCertSelParams *params,
1.1033 + PKIX_PL_Date *date,
1.1034 + void *plContext);
1.1035 +
1.1036 +/*
1.1037 + * FUNCTION: PKIX_ComCertSelParams_GetSerialNumber
1.1038 + * DESCRIPTION:
1.1039 + *
1.1040 + * Retrieves a pointer to the BigInt (if any) representing the serial number
1.1041 + * criterion that is set in the ComCertSelParams object pointed to by
1.1042 + * "params" and stores it at "pSerialNumber". In order to match against this
1.1043 + * criterion, a certificate must have a serial number equal to the
1.1044 + * criterion's serial number.
1.1045 + *
1.1046 + * If "params" does not have this criterion set, this function stores NULL at
1.1047 + * "pSerialNumber", in which case all certificates are considered to match
1.1048 + * this criterion.
1.1049 + *
1.1050 + * PARAMETERS:
1.1051 + * "params"
1.1052 + * Address of ComCertSelParams object whose serial number criterion
1.1053 + * (if any) is to be stored. Must be non-NULL.
1.1054 + * "pSerialNumber"
1.1055 + * Address where object pointer will be stored. Must be non-NULL.
1.1056 + * "plContext"
1.1057 + * Platform-specific context pointer.
1.1058 + * THREAD SAFETY:
1.1059 + * Conditionally Thread Safe
1.1060 + * (see Thread Safety Definitions in Programmer's Guide)
1.1061 + * RETURNS:
1.1062 + * Returns NULL if the function succeeds.
1.1063 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1064 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1065 + */
1.1066 +PKIX_Error *
1.1067 +PKIX_ComCertSelParams_GetSerialNumber(
1.1068 + PKIX_ComCertSelParams *params,
1.1069 + PKIX_PL_BigInt **pSerialNumber,
1.1070 + void *plContext);
1.1071 +
1.1072 +/*
1.1073 + * FUNCTION: PKIX_ComCertSelParams_SetSerialNumber
1.1074 + * DESCRIPTION:
1.1075 + *
1.1076 + * Sets the serial number criterion of the ComCertSelParams object pointed to
1.1077 + * by "params" using a BigInt pointed to by "serialNumber". In order to match
1.1078 + * against this criterion, a certificate must have a serial number equal to
1.1079 + * the criterion's serial number.
1.1080 + *
1.1081 + * If "serialNumber" is NULL, all certificates are considered to match this
1.1082 + * criterion.
1.1083 + *
1.1084 + * PARAMETERS:
1.1085 + * "params"
1.1086 + * Address of ComCertSelParams object whose serial number criterion is to
1.1087 + * be set. Must be non-NULL.
1.1088 + * "serialNumber"
1.1089 + * Address of BigInt used to set the criterion
1.1090 + * (or NULL to disable the criterion).
1.1091 + * "plContext"
1.1092 + * Platform-specific context pointer.
1.1093 + * THREAD SAFETY:
1.1094 + * Not Thread Safe - assumes exclusive access to "params"
1.1095 + * (see Thread Safety Definitions in Programmer's Guide)
1.1096 + * RETURNS:
1.1097 + * Returns NULL if the function succeeds.
1.1098 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1099 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1100 + */
1.1101 +PKIX_Error *
1.1102 +PKIX_ComCertSelParams_SetSerialNumber(
1.1103 + PKIX_ComCertSelParams *params,
1.1104 + PKIX_PL_BigInt *serialNumber,
1.1105 + void *plContext);
1.1106 +
1.1107 +/*
1.1108 + * FUNCTION: PKIX_ComCertSelParams_GetVersion
1.1109 + * DESCRIPTION:
1.1110 + *
1.1111 + * Retrieves a PKIX_UInt32 (if any) representing the version criterion that is
1.1112 + * set in the ComCertSelParams object pointed to by "params" and stores it at
1.1113 + * "pVersion". In order to match against this criterion, a certificate's
1.1114 + * version must be equal to the criterion's version.
1.1115 + *
1.1116 + * The version number will either be 0, 1, or 2 (corresponding to
1.1117 + * v1, v2, or v3, respectively).
1.1118 + *
1.1119 + * If "params" does not have this criterion set, this function stores
1.1120 + * 0xFFFFFFFF at "pVersion", in which case all certificates are considered
1.1121 + * to match this criterion.
1.1122 + *
1.1123 + * PARAMETERS:
1.1124 + * "params"
1.1125 + * Address of ComCertSelParams object whose version criterion (if any) is
1.1126 + * to be stored. Must be non-NULL.
1.1127 + * "pVersion"
1.1128 + * Address where PKIX_Int32 will be stored. Must be non-NULL.
1.1129 + * "plContext"
1.1130 + * Platform-specific context pointer.
1.1131 + * THREAD SAFETY:
1.1132 + * Conditionally Thread Safe
1.1133 + * (see Thread Safety Definitions in Programmer's Guide)
1.1134 + * RETURNS:
1.1135 + * Returns NULL if the function succeeds.
1.1136 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1137 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1138 + */
1.1139 +PKIX_Error *
1.1140 +PKIX_ComCertSelParams_GetVersion(
1.1141 + PKIX_ComCertSelParams *params,
1.1142 + PKIX_UInt32 *pVersion,
1.1143 + void *plContext);
1.1144 +
1.1145 +/*
1.1146 + * FUNCTION: PKIX_ComCertSelParams_SetVersion
1.1147 + * DESCRIPTION:
1.1148 + *
1.1149 + * Sets the version criterion of the ComCertSelParams object pointed to by
1.1150 + * "params" using the integer value of "version". In order to match against
1.1151 + * this criterion, a certificate's version must be equal to the criterion's
1.1152 + * version. If the criterion's version is -1, no version check is done and
1.1153 + * all certificates are considered to match this criterion.
1.1154 + *
1.1155 + * PARAMETERS:
1.1156 + * "params"
1.1157 + * Address of ComCertSelParams object whose version criterion is to be
1.1158 + * set. Must be non-NULL.
1.1159 + * "version"
1.1160 + * Value of PKIX_Int32 used to set the criterion
1.1161 + * (or -1 to disable the criterion).
1.1162 + * "plContext"
1.1163 + * Platform-specific context pointer.
1.1164 + * THREAD SAFETY:
1.1165 + * Not Thread Safe - assumes exclusive access to "params"
1.1166 + * (see Thread Safety Definitions in Programmer's Guide)
1.1167 + * RETURNS:
1.1168 + * Returns NULL if the function succeeds.
1.1169 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1170 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1171 + */
1.1172 +PKIX_Error *
1.1173 +PKIX_ComCertSelParams_SetVersion(
1.1174 + PKIX_ComCertSelParams *params,
1.1175 + PKIX_Int32 version,
1.1176 + void *plContext);
1.1177 +
1.1178 +
1.1179 +/*
1.1180 + * FUNCTION: PKIX_ComCertSelParams_GetKeyUsage
1.1181 + * DESCRIPTION:
1.1182 + *
1.1183 + * Retrieves a PKIX_UInt32 (if any) representing the key usage criterion that
1.1184 + * is set in the ComCertSelParams object pointed to by "params" and stores it
1.1185 + * at "pKeyUsage". In order to match against this criterion, a certificate
1.1186 + * must allow the criterion's key usage values. Note that a certificate that
1.1187 + * has no KeyUsage extension implicity allows all key usages. Note also that
1.1188 + * this functions supports a maximum of 32 key usage bits.
1.1189 + *
1.1190 + * If "params" does not have this criterion set, this function stores zero at
1.1191 + * "pKeyUsage", in which case all certificates are considered to match this
1.1192 + * criterion.
1.1193 + *
1.1194 + * PARAMETERS:
1.1195 + * "params"
1.1196 + * Address of ComCertSelParams object whose key usage criterion (if any)
1.1197 + * is to be stored. Must be non-NULL.
1.1198 + * "pKeyUsage"
1.1199 + * Address where PKIX_UInt32 will be stored. Must not be non-NULL.
1.1200 + * "plContext"
1.1201 + * Platform-specific context pointer.
1.1202 + * THREAD SAFETY:
1.1203 + * Conditionally Thread Safe
1.1204 + * (see Thread Safety Definitions in Programmer's Guide)
1.1205 + * RETURNS:
1.1206 + * Returns NULL if the function succeeds.
1.1207 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1208 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1209 + */
1.1210 +PKIX_Error *
1.1211 +PKIX_ComCertSelParams_GetKeyUsage(
1.1212 + PKIX_ComCertSelParams *params,
1.1213 + PKIX_UInt32 *pKeyUsage,
1.1214 + void *plContext);
1.1215 +
1.1216 +/*
1.1217 + * FUNCTION: PKIX_ComCertSelParams_SetKeyUsage
1.1218 + * DESCRIPTION:
1.1219 + *
1.1220 + * Sets the key usage criterion of the ComCertSelParams object pointed to by
1.1221 + * "params" using the integer value of "keyUsage". In order to match against
1.1222 + * this criterion, a certificate must allow the criterion's key usage values.
1.1223 + * Note that a certificate that has no KeyUsage extension implicity allows
1.1224 + * all key usages. Note also that this functions supports a maximum of 32 key
1.1225 + * usage bits.
1.1226 + *
1.1227 + * If the criterion's key usage value is zero, no key usage check is done and
1.1228 + * all certificates are considered to match this criterion.
1.1229 + *
1.1230 + * PARAMETERS:
1.1231 + * "params"
1.1232 + * Address of ComCertSelParams object whose key usage criterion is to be
1.1233 + * set. Must be non-NULL.
1.1234 + * "keyUsage"
1.1235 + * Value of PKIX_Int32 used to set the criterion
1.1236 + * (or zero to disable the criterion).
1.1237 + * "plContext"
1.1238 + * Platform-specific context pointer.
1.1239 + * THREAD SAFETY:
1.1240 + * Not Thread Safe - assumes exclusive access to "params"
1.1241 + * (see Thread Safety Definitions in Programmer's Guide)
1.1242 + * RETURNS:
1.1243 + * Returns NULL if the function succeeds.
1.1244 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1245 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1246 + */
1.1247 +PKIX_Error *
1.1248 +PKIX_ComCertSelParams_SetKeyUsage(
1.1249 + PKIX_ComCertSelParams *params,
1.1250 + PKIX_UInt32 keyUsage,
1.1251 + void *plContext);
1.1252 +
1.1253 +/*
1.1254 + * FUNCTION: PKIX_ComCertSelParams_GetExtendedKeyUsage
1.1255 + * DESCRIPTION:
1.1256 + *
1.1257 + * Retrieves a pointer to the List of OIDs (if any) representing the extended
1.1258 + * key usage criterion that is set in the ComCertSelParams object pointed to
1.1259 + * by "params" and stores it at "pExtKeyUsage". In order to match against this
1.1260 + * criterion, a certificate's ExtendedKeyUsage extension must allow the
1.1261 + * criterion's extended key usages. Note that a certificate that has no
1.1262 + * ExtendedKeyUsage extension implicity allows all key purposes.
1.1263 + *
1.1264 + * If "params" does not have this criterion set, this function stores NULL at
1.1265 + * "pExtKeyUsage", in which case all certificates are considered to match
1.1266 + * this criterion.
1.1267 + *
1.1268 + * Note that the List returned by this function is immutable.
1.1269 + *
1.1270 + * PARAMETERS:
1.1271 + * "params"
1.1272 + * Address of ComCertSelParams object whose extended key usage criterion
1.1273 + * (if any) is to be stored. Must be non-NULL.
1.1274 + * "pExtKeyUsage"
1.1275 + * Address where object pointer will be stored. Must be non-NULL.
1.1276 + * "plContext"
1.1277 + * Platform-specific context pointer.
1.1278 + * THREAD SAFETY:
1.1279 + * Conditionally Thread Safe
1.1280 + * (see Thread Safety Definitions in Programmer's Guide)
1.1281 + * RETURNS:
1.1282 + * Returns NULL if the function succeeds.
1.1283 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1284 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1285 + */
1.1286 +PKIX_Error *
1.1287 +PKIX_ComCertSelParams_GetExtendedKeyUsage(
1.1288 + PKIX_ComCertSelParams *params,
1.1289 + PKIX_List **pExtKeyUsage, /* list of PKIX_PL_OID */
1.1290 + void *plContext);
1.1291 +
1.1292 +/*
1.1293 + * FUNCTION: PKIX_ComCertSelParams_SetExtendedKeyUsage
1.1294 + * DESCRIPTION:
1.1295 + *
1.1296 + * Sets the extended key usage criterion of the ComCertSelParams object
1.1297 + * pointed to by "params" using a List of OIDs pointed to by "extKeyUsage".
1.1298 + * In order to match against this criterion, a certificate's ExtendedKeyUsage
1.1299 + * extension must allow the criterion's extended key usages. Note that a
1.1300 + * certificate that has no ExtendedKeyUsage extension implicitly allows all
1.1301 + * key purposes.
1.1302 + *
1.1303 + * If "extKeyUsage" is NULL, all certificates are considered to match this
1.1304 + * criterion.
1.1305 + *
1.1306 + * PARAMETERS:
1.1307 + * "params"
1.1308 + * Address of ComCertSelParams object whose extended key usage criterion
1.1309 + * is to be set. Must be non-NULL.
1.1310 + * "extKeyUsage"
1.1311 + * Address of List of OIDs used to set the criterion
1.1312 + * (or NULL to disable the criterion).
1.1313 + * "plContext"
1.1314 + * Platform-specific context pointer.
1.1315 + * THREAD SAFETY:
1.1316 + * Not Thread Safe - assumes exclusive access to "params"
1.1317 + * (see Thread Safety Definitions in Programmer's Guide)
1.1318 + * RETURNS:
1.1319 + * Returns NULL if the function succeeds.
1.1320 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1321 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1322 + */
1.1323 +PKIX_Error *
1.1324 +PKIX_ComCertSelParams_SetExtendedKeyUsage(
1.1325 + PKIX_ComCertSelParams *params,
1.1326 + PKIX_List *extKeyUsage, /* list of PKIX_PL_OID */
1.1327 + void *plContext);
1.1328 +
1.1329 +/*
1.1330 + * FUNCTION: PKIX_ComCertSelParams_GetPolicy
1.1331 + * DESCRIPTION:
1.1332 + *
1.1333 + * Retrieves a pointer to the List of OIDs (if any) representing the policy
1.1334 + * criterion that is set in the ComCertSelParams object pointed to by
1.1335 + * "params" and stores it at "pPolicy". In order to match against this
1.1336 + * criterion, a certificate's CertificatePolicies extension must include at
1.1337 + * least one of the criterion's policies. If "params" has this criterion set,
1.1338 + * but the List of OIDs is empty, then a certificate's CertificatePolicies
1.1339 + * extension must include at least some policy.
1.1340 + *
1.1341 + * If "params" does not have this criterion set, this function stores NULL at
1.1342 + * "pPolicy", in which case all certificates are considered to match this
1.1343 + * criterion.
1.1344 + *
1.1345 + * Note that the List returned by this function is immutable.
1.1346 + *
1.1347 + * PARAMETERS:
1.1348 + * "params"
1.1349 + * Address of ComCertSelParams object whose policy criterion (if any) is
1.1350 + * to be stored. Must be non-NULL.
1.1351 + * "pPolicy"
1.1352 + * Address where object pointer will be stored. Must be non-NULL.
1.1353 + * "plContext"
1.1354 + * Platform-specific context pointer.
1.1355 + * THREAD SAFETY:
1.1356 + * Conditionally Thread Safe
1.1357 + * (see Thread Safety Definitions in Programmer's Guide)
1.1358 + * RETURNS:
1.1359 + * Returns NULL if the function succeeds.
1.1360 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1361 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1362 + */
1.1363 +PKIX_Error *
1.1364 +PKIX_ComCertSelParams_GetPolicy(
1.1365 + PKIX_ComCertSelParams *params,
1.1366 + PKIX_List **pPolicy, /* list of PKIX_PL_OID */
1.1367 + void *plContext);
1.1368 +
1.1369 +/*
1.1370 + * FUNCTION: PKIX_ComCertSelParams_SetPolicy
1.1371 + * DESCRIPTION:
1.1372 + *
1.1373 + * Sets the policy criterion of the ComCertSelParams object pointed to by
1.1374 + * "params" using a List of OIDs pointed to by "policy". In order to match
1.1375 + * against this criterion, a certificate's CertificatePolicies extension must
1.1376 + * include at least one of the criterion's policies. If "params" has this
1.1377 + * criterion set, but the List of OIDs is empty, then a certificate's
1.1378 + * CertificatePolicies extension must include at least some policy.
1.1379 + *
1.1380 + * If "policy" is NULL, all certificates are considered to match this
1.1381 + * criterion.
1.1382 + *
1.1383 + * PARAMETERS:
1.1384 + * "params"
1.1385 + * Address of ComCertSelParams object whose policy criterion is to be set.
1.1386 + * Must be non-NULL.
1.1387 + * "policy"
1.1388 + * Address of List of OIDs used to set the criterion
1.1389 + * (or NULL to disable the criterion).
1.1390 + * "plContext"
1.1391 + * Platform-specific context pointer.
1.1392 + * THREAD SAFETY:
1.1393 + * Not Thread Safe - assumes exclusive access to "params"
1.1394 + * (see Thread Safety Definitions in Programmer's Guide)
1.1395 + * RETURNS:
1.1396 + * Returns NULL if the function succeeds.
1.1397 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1398 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1399 + */
1.1400 +PKIX_Error *
1.1401 +PKIX_ComCertSelParams_SetPolicy(
1.1402 + PKIX_ComCertSelParams *params,
1.1403 + PKIX_List *policy, /* list of PKIX_PL_OID */
1.1404 + void *plContext);
1.1405 +
1.1406 +/*
1.1407 + * FUNCTION: PKIX_ComCertSelParams_GetIssuer
1.1408 + * DESCRIPTION:
1.1409 + *
1.1410 + * Retrieves a pointer to the X500Name (if any) representing the issuer
1.1411 + * criterion that is set in the ComCertSelParams object pointed to by
1.1412 + * "params" and stores it at "pIssuer". In order to match against this
1.1413 + * criterion, a certificate's IssuerName must match the criterion's issuer
1.1414 + * name.
1.1415 + *
1.1416 + * If "params" does not have this criterion set, this function stores NULL at
1.1417 + * "pIssuer", in which case all certificates are considered to match this
1.1418 + * criterion.
1.1419 + *
1.1420 + * PARAMETERS:
1.1421 + * "params"
1.1422 + * Address of ComCertSelParams object whose issuer criterion (if any) is
1.1423 + * to be stored. Must be non-NULL.
1.1424 + * "pIssuer"
1.1425 + * Address where object pointer will be stored. Must be non-NULL.
1.1426 + * "plContext"
1.1427 + * Platform-specific context pointer.
1.1428 + * THREAD SAFETY:
1.1429 + * Conditionally Thread Safe
1.1430 + * (see Thread Safety Definitions in Programmer's Guide)
1.1431 + * RETURNS:
1.1432 + * Returns NULL if the function succeeds.
1.1433 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1434 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1435 + */
1.1436 +PKIX_Error *
1.1437 +PKIX_ComCertSelParams_GetIssuer(
1.1438 + PKIX_ComCertSelParams *params,
1.1439 + PKIX_PL_X500Name **pIssuer,
1.1440 + void *plContext);
1.1441 +
1.1442 +/*
1.1443 + * FUNCTION: PKIX_ComCertSelParams_SetIssuer
1.1444 + * DESCRIPTION:
1.1445 + *
1.1446 + * Sets the issuer criterion of the ComCertSelParams object pointed to by
1.1447 + * "params" using an X500Name pointed to by "issuer". In order to match
1.1448 + * against this criterion, a certificate's IssuerName must match the
1.1449 + * criterion's issuer name.
1.1450 + *
1.1451 + * If "issuer" is NULL, all certificates are considered to match this
1.1452 + * criterion.
1.1453 + *
1.1454 + * PARAMETERS:
1.1455 + * "params"
1.1456 + * Address of ComCertSelParams object whose issuer criterion is to be set.
1.1457 + * Must be non-NULL.
1.1458 + * "issuer"
1.1459 + * Address of X500Name used to set the criterion
1.1460 + * (or NULL to disable the criterion).
1.1461 + * "plContext"
1.1462 + * Platform-specific context pointer.
1.1463 + * THREAD SAFETY:
1.1464 + * Not Thread Safe - assumes exclusive access to "params"
1.1465 + * (see Thread Safety Definitions in Programmer's Guide)
1.1466 + * RETURNS:
1.1467 + * Returns NULL if the function succeeds.
1.1468 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1469 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1470 + */
1.1471 +PKIX_Error *
1.1472 +PKIX_ComCertSelParams_SetIssuer(
1.1473 + PKIX_ComCertSelParams *params,
1.1474 + PKIX_PL_X500Name *issuer,
1.1475 + void *plContext);
1.1476 +
1.1477 +/*
1.1478 + * FUNCTION: PKIX_ComCertSelParams_GetSubject
1.1479 + * DESCRIPTION:
1.1480 + *
1.1481 + * Retrieves a pointer to the X500Name (if any) representing the subject
1.1482 + * criterion that is set in the ComCertSelParams object pointed to by
1.1483 + * "params" and stores it at "pSubject". In order to match against this
1.1484 + * criterion, a certificate's SubjectName must match the criterion's subject
1.1485 + * name.
1.1486 + *
1.1487 + * If "params" does not have this criterion set, this function stores NULL at
1.1488 + * "pSubject", in which case all certificates are considered to match this
1.1489 + * criterion.
1.1490 + *
1.1491 + * PARAMETERS:
1.1492 + * "params"
1.1493 + * Address of ComCertSelParams object whose subject criterion (if any) is
1.1494 + * to be stored. Must be non-NULL.
1.1495 + * "pSubject"
1.1496 + * Address where object pointer will be stored. Must be non-NULL.
1.1497 + * "plContext"
1.1498 + * Platform-specific context pointer.
1.1499 + * THREAD SAFETY:
1.1500 + * Conditionally Thread Safe
1.1501 + * (see Thread Safety Definitions in Programmer's Guide)
1.1502 + * RETURNS:
1.1503 + * Returns NULL if the function succeeds.
1.1504 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1505 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1506 + */
1.1507 +PKIX_Error *
1.1508 +PKIX_ComCertSelParams_GetSubject(
1.1509 + PKIX_ComCertSelParams *params,
1.1510 + PKIX_PL_X500Name **pSubject,
1.1511 + void *plContext);
1.1512 +
1.1513 +/*
1.1514 + * FUNCTION: PKIX_ComCertSelParams_SetSubject
1.1515 + * DESCRIPTION:
1.1516 + *
1.1517 + * Sets the subject criterion of the ComCertSelParams object pointed to by
1.1518 + * "params" using an X500Name pointed to by "subject". In order to match
1.1519 + * against this criterion, a certificate's SubjectName must match the
1.1520 + * criterion's subject name.
1.1521 + *
1.1522 + * If "subject" is NULL, all certificates are considered to match this
1.1523 + * criterion.
1.1524 + *
1.1525 + * PARAMETERS:
1.1526 + * "params"
1.1527 + * Address of ComCertSelParams object whose subject criterion is to be
1.1528 + * set. Must be non-NULL.
1.1529 + * "subject"
1.1530 + * Address of X500Name used to set the criterion
1.1531 + * (or NULL to disable the criterion).
1.1532 + * "plContext"
1.1533 + * Platform-specific context pointer.
1.1534 + * THREAD SAFETY:
1.1535 + * Not Thread Safe - assumes exclusive access to "params"
1.1536 + * (see Thread Safety Definitions in Programmer's Guide)
1.1537 + * RETURNS:
1.1538 + * Returns NULL if the function succeeds.
1.1539 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1540 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1541 + */
1.1542 +PKIX_Error *
1.1543 +PKIX_ComCertSelParams_SetSubject(
1.1544 + PKIX_ComCertSelParams *params,
1.1545 + PKIX_PL_X500Name *subject,
1.1546 + void *plContext);
1.1547 +
1.1548 +/*
1.1549 + * FUNCTION: PKIX_ComCertSelParams_GetSubjectAsByteArray
1.1550 + * DESCRIPTION:
1.1551 + *
1.1552 + * Retrieves a pointer to the ByteArray (if any) representing the subject
1.1553 + * criterion that is set in the ComCertSelParams object pointed to by
1.1554 + * "params" and stores it at "pSubject". In order to match against this
1.1555 + * criterion, a certificate's SubjectName must match the criterion's subject
1.1556 + * name.
1.1557 + *
1.1558 + * If "params" does not have this criterion set, this function stores NULL at
1.1559 + * "pSubject", in which case all certificates are considered to match this
1.1560 + * criterion.
1.1561 + *
1.1562 + * PARAMETERS:
1.1563 + * "params"
1.1564 + * Address of ComCertSelParams object whose subject criterion (if any) is
1.1565 + * to be stored. Must be non-NULL.
1.1566 + * "pSubject"
1.1567 + * Address where object pointer will be stored. Must be non-NULL.
1.1568 + * "plContext"
1.1569 + * Platform-specific context pointer.
1.1570 + * THREAD SAFETY:
1.1571 + * Conditionally Thread Safe
1.1572 + * (see Thread Safety Definitions in Programmer's Guide)
1.1573 + * RETURNS:
1.1574 + * Returns NULL if the function succeeds.
1.1575 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1576 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1577 + */
1.1578 +PKIX_Error *
1.1579 +PKIX_ComCertSelParams_GetSubjectAsByteArray(
1.1580 + PKIX_ComCertSelParams *params,
1.1581 + PKIX_PL_ByteArray **pSubject,
1.1582 + void *plContext);
1.1583 +
1.1584 +/*
1.1585 + * FUNCTION: PKIX_ComCertSelParams_SetSubjectAsByteArray
1.1586 + * DESCRIPTION:
1.1587 + *
1.1588 + * Sets the subject criterion of the ComCertSelParams object pointed to by
1.1589 + * "params" using a ByteArray pointed to by "subject". In order to match
1.1590 + * against this criterion, a certificate's SubjectName must match the
1.1591 + * criterion's subject name.
1.1592 + *
1.1593 + * If "subject" is NULL, all certificates are considered to match this
1.1594 + * criterion.
1.1595 + *
1.1596 + * PARAMETERS:
1.1597 + * "params"
1.1598 + * Address of ComCertSelParams object whose subject criterion is to be
1.1599 + * set. Must be non-NULL.
1.1600 + * "subject"
1.1601 + * Address of ByteArray used to set the criterion
1.1602 + * (or NULL to disable the criterion).
1.1603 + * "plContext"
1.1604 + * Platform-specific context pointer.
1.1605 + * THREAD SAFETY:
1.1606 + * Not Thread Safe - assumes exclusive access to "params"
1.1607 + * (see Thread Safety Definitions in Programmer's Guide)
1.1608 + * RETURNS:
1.1609 + * Returns NULL if the function succeeds.
1.1610 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1611 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1612 + */
1.1613 +PKIX_Error *
1.1614 +PKIX_ComCertSelParams_SetSubjectAsByteArray(
1.1615 + PKIX_ComCertSelParams *params,
1.1616 + PKIX_PL_ByteArray *subject,
1.1617 + void *plContext);
1.1618 +
1.1619 +/*
1.1620 + * FUNCTION: PKIX_ComCertSelParams_GetNameConstraints
1.1621 + * DESCRIPTION:
1.1622 + *
1.1623 + * Retrieves a pointer to the X500Name (if any) representing the name
1.1624 + * constraints criterion that is set in the ComCertSelParams object pointed
1.1625 + * to by "params" and stores it at "pConstraints". In order to match against
1.1626 + * this criterion, a certificate's subject and subject alternative names must
1.1627 + * be allowed by the criterion's name constraints.
1.1628 + *
1.1629 + * If "params" does not have this criterion set, this function stores NULL at
1.1630 + * "pConstraints", in which case all certificates are considered to match
1.1631 + * this criterion.
1.1632 + *
1.1633 + * PARAMETERS:
1.1634 + * "params"
1.1635 + * Address of ComCertSelParams object whose name constraints criterion
1.1636 + * (if any) is to be stored. Must be non-NULL.
1.1637 + * "pConstraints"
1.1638 + * Address where object pointer will be stored. Must be non-NULL.
1.1639 + * "plContext"
1.1640 + * Platform-specific context pointer.
1.1641 + * THREAD SAFETY:
1.1642 + * Conditionally Thread Safe
1.1643 + * (see Thread Safety Definitions in Programmer's Guide)
1.1644 + * RETURNS:
1.1645 + * Returns NULL if the function succeeds.
1.1646 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1647 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1648 + */
1.1649 +PKIX_Error *
1.1650 +PKIX_ComCertSelParams_GetNameConstraints(
1.1651 + PKIX_ComCertSelParams *params,
1.1652 + PKIX_PL_CertNameConstraints **pConstraints,
1.1653 + void *plContext);
1.1654 +
1.1655 +/*
1.1656 + * FUNCTION: PKIX_ComCertSelParams_SetNameConstraints
1.1657 + * DESCRIPTION:
1.1658 + *
1.1659 + * Sets the name constraints criterion of the ComCertSelParams object pointed
1.1660 + * to by "params" using the CertNameConstraints pointed to by "constraints".
1.1661 + * In order to match against this criterion, a certificate's subject and
1.1662 + * subject alternative names must be allowed by the criterion's name
1.1663 + * constraints.
1.1664 + *
1.1665 + * If "constraints" is NULL, all certificates are considered to match this
1.1666 + * criterion.
1.1667 + *
1.1668 + * PARAMETERS:
1.1669 + * "params"
1.1670 + * Address of ComCertSelParams object whose name constraints criterion is
1.1671 + * to be set. Must be non-NULL.
1.1672 + * "constraints"
1.1673 + * Address of CertNameConstraints used to set the criterion
1.1674 + * (or NULL to disable the criterion).
1.1675 + * "plContext"
1.1676 + * Platform-specific context pointer.
1.1677 + * THREAD SAFETY:
1.1678 + * Not Thread Safe - assumes exclusive access to "params"
1.1679 + * (see Thread Safety Definitions in Programmer's Guide)
1.1680 + * RETURNS:
1.1681 + * Returns NULL if the function succeeds.
1.1682 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1683 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1684 + */
1.1685 +PKIX_Error *
1.1686 +PKIX_ComCertSelParams_SetNameConstraints(
1.1687 + PKIX_ComCertSelParams *params,
1.1688 + PKIX_PL_CertNameConstraints *constraints,
1.1689 + void *plContext);
1.1690 +
1.1691 +/*
1.1692 + * FUNCTION: PKIX_ComCertSelParams_GetMatchAllSubjAltNames
1.1693 + * DESCRIPTION:
1.1694 + *
1.1695 + * Checks whether the ComCertSelParams object pointed to by "params" indicate
1.1696 + * that all subject alternative names are to be matched and stores the Boolean
1.1697 + * result at "pMatch". This Boolean value determines the behavior of the
1.1698 + * subject alternative names criterion.
1.1699 + *
1.1700 + * In order to match against the subject alternative names criterion, if the
1.1701 + * Boolean value at "pMatch" is PKIX_TRUE, a certificate must contain all of
1.1702 + * the criterion's subject alternative names. If the Boolean value at
1.1703 + * "pMatch" is PKIX_FALSE, a certificate must contain at least one of the
1.1704 + * criterion's subject alternative names. The default behavior is as if the
1.1705 + * Boolean value at "pMatch" is PKIX_TRUE.
1.1706 + *
1.1707 + * PARAMETERS:
1.1708 + * "params"
1.1709 + * Address of ComCertSelParams object used to determine whether all
1.1710 + * subject alternative names must be matched. Must be non-NULL.
1.1711 + * "pMatch"
1.1712 + * Address where object pointer will be stored. Must be non-NULL.
1.1713 + * "plContext"
1.1714 + * Platform-specific context pointer.
1.1715 + * THREAD SAFETY:
1.1716 + * Conditionally Thread Safe
1.1717 + * (see Thread Safety Definitions in Programmer's Guide)
1.1718 + * RETURNS:
1.1719 + * Returns NULL if the function succeeds.
1.1720 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1721 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1722 + */
1.1723 +PKIX_Error *
1.1724 +PKIX_ComCertSelParams_GetMatchAllSubjAltNames(
1.1725 + PKIX_ComCertSelParams *params,
1.1726 + PKIX_Boolean *pMatch,
1.1727 + void *plContext);
1.1728 +
1.1729 +/*
1.1730 + * FUNCTION: PKIX_ComCertSelParams_SetMatchAllSubjAltNames
1.1731 + * DESCRIPTION:
1.1732 + *
1.1733 + * Sets the match flag of the ComCertSelParams object pointed to by "params"
1.1734 + * using the Boolean value of "match". This Boolean value determines the
1.1735 + * behavior of the subject alternative names criterion.
1.1736 + *
1.1737 + * In order to match against the subject alternative names criterion, if the
1.1738 + * "match" is PKIX_TRUE, a certificate must contain all of the criterion's
1.1739 + * subject alternative names. If the "match" is PKIX_FALSE, a certificate
1.1740 + * must contain at least one of the criterion's subject alternative names.
1.1741 + * The default behavior is as if "match" is PKIX_TRUE.
1.1742 + *
1.1743 + * PARAMETERS:
1.1744 + * "params"
1.1745 + * Address of ComCertSelParams object whose match flag is to be set.
1.1746 + * Must be non-NULL.
1.1747 + * "match"
1.1748 + * Boolean value used to set the match flag.
1.1749 + * "plContext"
1.1750 + * Platform-specific context pointer.
1.1751 + * THREAD SAFETY:
1.1752 + * Not Thread Safe - assumes exclusive access to "params"
1.1753 + * (see Thread Safety Definitions in Programmer's Guide)
1.1754 + * RETURNS:
1.1755 + * Returns NULL if the function succeeds.
1.1756 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1757 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1758 + */
1.1759 +PKIX_Error *
1.1760 +PKIX_ComCertSelParams_SetMatchAllSubjAltNames(
1.1761 + PKIX_ComCertSelParams *params,
1.1762 + PKIX_Boolean match,
1.1763 + void *plContext);
1.1764 +
1.1765 +/*
1.1766 + * FUNCTION: PKIX_ComCertSelParams_GetLeafCertFlag
1.1767 + * DESCRIPTION:
1.1768 + *
1.1769 + * Return "leafCert" flag of the ComCertSelParams structure. If set to true,
1.1770 + * the flag indicates that a selector should filter out all cert that are not
1.1771 + * qualified to be a leaf cert according to the specified key/ekey usages.
1.1772 + *
1.1773 + * PARAMETERS:
1.1774 + * "params"
1.1775 + * Address of ComCertSelParams object used to determine whether all
1.1776 + * subject alternative names must be matched. Must be non-NULL.
1.1777 + * "pLeafFlag"
1.1778 + * Address of returned value.
1.1779 + * "plContext"
1.1780 + * Platform-specific context pointer.
1.1781 + * THREAD SAFETY:
1.1782 + * Conditionally Thread Safe
1.1783 + * (see Thread Safety Definitions in Programmer's Guide)
1.1784 + * RETURNS:
1.1785 + * Returns NULL if the function succeeds.
1.1786 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1787 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1788 + */
1.1789 +PKIX_Error*
1.1790 +PKIX_ComCertSelParams_GetLeafCertFlag(
1.1791 + PKIX_ComCertSelParams *params,
1.1792 + PKIX_Boolean *pLeafFlag,
1.1793 + void *plContext);
1.1794 +
1.1795 +/*
1.1796 + * FUNCTION: PKIX_ComCertSelParams_SetLeafCertFlag
1.1797 + * DESCRIPTION:
1.1798 + *
1.1799 + * Sets a flag that if its value is true, indicates that the selector
1.1800 + * should only pick certs that qualifies to be leaf for this cert path
1.1801 + * validation.
1.1802 + *
1.1803 + * PARAMETERS:
1.1804 + * "params"
1.1805 + * Address of ComCertSelParams object whose match flag is to be set.
1.1806 + * Must be non-NULL.
1.1807 + * "leafFlag"
1.1808 + * Boolean value used to set the leaf flag.
1.1809 + * "plContext"
1.1810 + * Platform-specific context pointer.
1.1811 + * THREAD SAFETY:
1.1812 + * Not Thread Safe - assumes exclusive access to "params"
1.1813 + * (see Thread Safety Definitions in Programmer's Guide)
1.1814 + * RETURNS:
1.1815 + * Returns NULL if the function succeeds.
1.1816 + * Returns a CertSelector Error if the function fails in a non-fatal way.
1.1817 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.1818 + */
1.1819 +PKIX_Error *
1.1820 +PKIX_ComCertSelParams_SetLeafCertFlag(
1.1821 + PKIX_ComCertSelParams *params,
1.1822 + PKIX_Boolean leafFlag,
1.1823 + void *plContext);
1.1824 +
1.1825 +#ifdef __cplusplus
1.1826 +}
1.1827 +#endif
1.1828 +
1.1829 +#endif /* _PKIX_CERTSEL_H */
