1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/crmf/cmmf.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1090 @@
1.4 +/* -*- Mode: C; tab-width: 8 -*-*/
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef _CMMF_H_
1.10 +#define _CMMF_H_
1.11 +/*
1.12 + * These are the functions exported by the security library for
1.13 + * implementing Certificate Management Message Formats (CMMF).
1.14 + *
1.15 + * This API is designed against July 1998 CMMF draft. Please read this
1.16 + * draft before trying to use this API in an application that use CMMF.
1.17 + */
1.18 +#include "seccomon.h"
1.19 +#include "cmmft.h"
1.20 +#include "crmf.h"
1.21 +
1.22 +SEC_BEGIN_PROTOS
1.23 +
1.24 +/******************* Creation Functions *************************/
1.25 +
1.26 +/*
1.27 + * FUNCTION: CMMF_CreateCertRepContent
1.28 + * INPUTS:
1.29 + * NONE
1.30 + * NOTES:
1.31 + * This function will create an empty CMMFCertRepContent Structure.
1.32 + * The client of the library must set the CMMFCertResponses.
1.33 + * Call CMMF_CertRepContentSetCertResponse to accomplish this task.
1.34 + * If the client of the library also wants to include the chain of
1.35 + * CA certs required to make the certificates in CMMFCertResponse valid,
1.36 + * then the user must also set the caPubs field of CMMFCertRepContent.
1.37 + * Call CMMF_CertRepContentSetCAPubs to accomplish this. After setting
1.38 + * the desired fields, the user can then call CMMF_EncodeCertRepContent
1.39 + * to DER-encode the CertRepContent.
1.40 + * RETURN:
1.41 + * A pointer to the CMMFCertRepContent. A NULL return value indicates
1.42 + * an error in allocating memory or failure to initialize the structure.
1.43 + */
1.44 +extern CMMFCertRepContent* CMMF_CreateCertRepContent(void);
1.45 +
1.46 +/*
1.47 + * FUNCTION: CMMF_CreateCertRepContentFromDER
1.48 + * INPUTS
1.49 + * db
1.50 + * The certificate database where the certificates will be placed.
1.51 + * The certificates will be placed in the temporary database associated
1.52 + * with the handle.
1.53 + * buf
1.54 + * A buffer to the DER-encoded CMMFCertRepContent
1.55 + * len
1.56 + * The length in bytes of the buffer 'buf'
1.57 + * NOTES:
1.58 + * This function passes the buffer to the ASN1 decoder and creates a
1.59 + * CMMFCertRepContent structure. The user must call
1.60 + * CMMF_DestroyCertRepContent after the return value is no longer needed.
1.61 + *
1.62 + * RETURN:
1.63 + * A pointer to the CMMFCertRepContent structure. A NULL return
1.64 + * value indicates the library was unable to parse the DER.
1.65 + */
1.66 +extern CMMFCertRepContent*
1.67 + CMMF_CreateCertRepContentFromDER(CERTCertDBHandle *db,
1.68 + const char *buf,
1.69 + long len);
1.70 +
1.71 +/*
1.72 + * FUNCTION: CMMF_CreateCertResponse
1.73 + * INPUTS:
1.74 + * inCertReqId
1.75 + * The Certificate Request Id this response is for.
1.76 + * NOTES:
1.77 + * This creates a CMMFCertResponse. This response should correspond
1.78 + * to a request that was received via CRMF. From the CRMF message you
1.79 + * can get the Request Id to pass in as inCertReqId, in essence binding
1.80 + * a CMRFCertRequest message to the CMMFCertResponse created by this
1.81 + * function. If no requuest id is associated with the response to create
1.82 + * then the user should pass in -1 for 'inCertReqId'.
1.83 + *
1.84 + * RETURN:
1.85 + * A pointer to the new CMMFCertResponse corresponding to the request id
1.86 + * passed in. A NULL return value indicates an error while trying to
1.87 + * create the CMMFCertResponse.
1.88 + */
1.89 +extern CMMFCertResponse* CMMF_CreateCertResponse(long inCertReqId);
1.90 +
1.91 +/*
1.92 + * FUNCTION: CMMF_CreateKeyRecRepContent
1.93 + * INPUTS:
1.94 + * NONE
1.95 + * NOTES:
1.96 + * This function creates a new empty CMMFKeyRecRepContent structure.
1.97 + * At the very minimum, the user must call
1.98 + * CMMF_KeyRecRepContentSetPKIStatusInfoStatus field to have an
1.99 + * encodable structure. Depending on what the response is, the user may
1.100 + * have to set other fields as well to properly build up the structure so
1.101 + * that it can be encoded. Refer to the CMMF draft for how to properly
1.102 + * set up a CMMFKeyRecRepContent. This is the structure that an RA returns
1.103 + * to an end entity when doing key recovery.
1.104 +
1.105 + * The user must call CMMF_DestroyKeyRecRepContent when the return value
1.106 + * is no longer needed.
1.107 + * RETURN:
1.108 + * A pointer to the empty CMMFKeyRecRepContent. A return value of NULL
1.109 + * indicates an error in allocating memory or initializing the structure.
1.110 + */
1.111 +extern CMMFKeyRecRepContent *CMMF_CreateKeyRecRepContent(void);
1.112 +
1.113 +/*
1.114 + * FUNCTION: CMMF_CreateKeyRecRepContentFromDER
1.115 + * INPUTS:
1.116 + * db
1.117 + * The handle for the certificate database where the decoded
1.118 + * certificates will be placed. The decoded certificates will
1.119 + * be placed in the temporary database associated with the
1.120 + * handle.
1.121 + * buf
1.122 + * A buffer contatining the DER-encoded CMMFKeyRecRepContent
1.123 + * len
1.124 + * The length in bytes of the buffer 'buf'
1.125 + * NOTES
1.126 + * This function passes the buffer to the ASN1 decoder and creates a
1.127 + * CMMFKeyRecRepContent structure.
1.128 + *
1.129 + * RETURN:
1.130 + * A pointer to the CMMFKeyRecRepContent structure. A NULL return
1.131 + * value indicates the library was unable to parse the DER.
1.132 + */
1.133 +extern CMMFKeyRecRepContent*
1.134 + CMMF_CreateKeyRecRepContentFromDER(CERTCertDBHandle *db,
1.135 + const char *buf,
1.136 + long len);
1.137 +
1.138 +/*
1.139 + * FUNCTION: CMMF_CreatePOPODecKeyChallContent
1.140 + * INPUTS:
1.141 + * NONE
1.142 + * NOTES:
1.143 + * This function creates an empty CMMFPOPODecKeyChallContent. The user
1.144 + * must add the challenges individually specifying the random number to
1.145 + * be used and the public key to be used when creating each individual
1.146 + * challenge. User can accomplish this by calling the function
1.147 + * CMMF_POPODecKeyChallContentSetNextChallenge.
1.148 + * RETURN:
1.149 + * A pointer to a CMMFPOPODecKeyChallContent structure. Ther user can
1.150 + * then call CMMF_EncodePOPODecKeyChallContent passing in the return
1.151 + * value from this function after setting all of the challenges. A
1.152 + * return value of NULL indicates an error while creating the
1.153 + * CMMFPOPODecKeyChallContent structure.
1.154 + */
1.155 +extern CMMFPOPODecKeyChallContent*
1.156 + CMMF_CreatePOPODecKeyChallContent(void);
1.157 +
1.158 +/*
1.159 + * FUNCTION: CMMF_CreatePOPODecKeyChallContentFromDER
1.160 + * INPUTS
1.161 + * buf
1.162 + * A buffer containing the DER-encoded CMMFPOPODecKeyChallContent
1.163 + * len
1.164 + * The length in bytes of the buffer 'buf'
1.165 + * NOTES:
1.166 + * This function passes the buffer to the ASN1 decoder and creates a
1.167 + * CMMFPOPODecKeyChallContent structure.
1.168 + *
1.169 + * RETURN:
1.170 + * A pointer to the CMMFPOPODecKeyChallContent structure. A NULL return
1.171 + * value indicates the library was unable to parse the DER.
1.172 + */
1.173 +extern CMMFPOPODecKeyChallContent*
1.174 + CMMF_CreatePOPODecKeyChallContentFromDER(const char *buf, long len);
1.175 +
1.176 +/*
1.177 + * FUNCTION: CMMF_CreatePOPODecKeyRespContentFromDER
1.178 + * INPUTS:
1.179 + * buf
1.180 + * A buffer contatining the DER-encoded CMMFPOPODecKeyRespContent
1.181 + * len
1.182 + * The length in bytes of the buffer 'buf'
1.183 + * NOTES
1.184 + * This function passes the buffer to the ASN1 decoder and creates a
1.185 + * CMMFPOPODecKeyRespContent structure.
1.186 + *
1.187 + * RETURN:
1.188 + * A pointer to the CMMFPOPODecKeyRespContent structure. A NULL return
1.189 + * value indicates the library was unable to parse the DER.
1.190 + */
1.191 +extern CMMFPOPODecKeyRespContent*
1.192 + CMMF_CreatePOPODecKeyRespContentFromDER(const char *buf, long len);
1.193 +
1.194 +/************************** Set Functions *************************/
1.195 +
1.196 +/*
1.197 + * FUNCTION: CMMF_CertRepContentSetCertResponses
1.198 + * INPUTS:
1.199 + * inCertRepContent
1.200 + * The CMMFCertRepContent to operate on.
1.201 + * inCertResponses
1.202 + * An array of pointers to CMMFCertResponse structures to
1.203 + * add to the CMMFCertRepContent structure.
1.204 + * inNumResponses
1.205 + * The length of the array 'inCertResponses'
1.206 + * NOTES:
1.207 + * This function will add the CMMFCertResponse structure to the
1.208 + * CMMFCertRepContent passed in. The CMMFCertResponse field of
1.209 + * CMMFCertRepContent is required, so the client must call this function
1.210 + * before calling CMMF_EncodeCertRepContent. If the user calls
1.211 + * CMMF_EncodeCertRepContent before calling this function,
1.212 + * CMMF_EncodeCertRepContent will fail.
1.213 + *
1.214 + * RETURN:
1.215 + * SECSuccess if adding the CMMFCertResponses to the CMMFCertRepContent
1.216 + * structure was successful. Any other return value indicates an error
1.217 + * while trying to add the CMMFCertResponses.
1.218 + */
1.219 +extern SECStatus
1.220 + CMMF_CertRepContentSetCertResponses(CMMFCertRepContent *inCertRepContent,
1.221 + CMMFCertResponse **inCertResponses,
1.222 + int inNumResponses);
1.223 +
1.224 +/*
1.225 + * FUNCTION: CMMF_CertRepContentSetCAPubs
1.226 + * INPUTS:
1.227 + * inCertRepContent
1.228 + * The CMMFCertRepContent to operate on.
1.229 + * inCAPubs
1.230 + * The certificate list which makes up the chain of CA certificates
1.231 + * required to make the issued cert valid.
1.232 + * NOTES:
1.233 + * This function will set the the certificates in the CA chain as part
1.234 + * of the CMMFCertRepContent. This field is an optional member of the
1.235 + * CMMFCertRepContent structure, so the client is not required to call
1.236 + * this function before calling CMMF_EncodeCertRepContent.
1.237 + *
1.238 + * RETURN:
1.239 + * SECSuccess if adding the 'inCAPubs' to the CERTRepContent was successful.
1.240 + * Any other return value indicates an error while adding 'inCAPubs' to the
1.241 + * CMMFCertRepContent structure.
1.242 + *
1.243 + */
1.244 +extern SECStatus
1.245 + CMMF_CertRepContentSetCAPubs (CMMFCertRepContent *inCertRepContent,
1.246 + CERTCertList *inCAPubs);
1.247 +
1.248 +/*
1.249 + * FUNCTION: CMMF_CertResponseSetPKIStatusInfoStatus
1.250 + * INPUTS:
1.251 + * inCertResp
1.252 + * The CMMFCertResponse to operate on.
1.253 + * inPKIStatus
1.254 + * The value to set for the PKIStatusInfo.status field.
1.255 + * NOTES:
1.256 + * This function will set the CertResponse.status.status field of
1.257 + * the CMMFCertResponse structure. (View the definition of CertResponse
1.258 + * in the CMMF draft to see exactly which value this talks about.) This
1.259 + * field is a required member of the structure, so the user must call this
1.260 + * function in order to have a CMMFCertResponse that can be encoded.
1.261 + *
1.262 + * RETURN:
1.263 + * SECSuccess if setting the field with the passed in value was successful.
1.264 + * Any other return value indicates an error while trying to set the field.
1.265 + */
1.266 +extern SECStatus
1.267 + CMMF_CertResponseSetPKIStatusInfoStatus (CMMFCertResponse *inCertResp,
1.268 + CMMFPKIStatus inPKIStatus);
1.269 +
1.270 +/*
1.271 + * FUNCTION: CMMF_CertResponseSetCertificate
1.272 + * INPUTS:
1.273 + * inCertResp
1.274 + * The CMMFCertResponse to operate on.
1.275 + * inCertificate
1.276 + * The certificate to add to the
1.277 + * CertResponse.CertifiedKeyPair.certOrEncCert.certificate field.
1.278 + * NOTES:
1.279 + * This function will take the certificate and make it a member of the
1.280 + * CMMFCertResponse. The certificate should be the actual certificate
1.281 + * being issued via the response.
1.282 + *
1.283 + * RETURN:
1.284 + * SECSuccess if adding the certificate to the response was successful.
1.285 + * Any other return value indicates an error in adding the certificate to
1.286 + * the CertResponse.
1.287 + */
1.288 +extern SECStatus
1.289 + CMMF_CertResponseSetCertificate (CMMFCertResponse *inCertResp,
1.290 + CERTCertificate *inCertificate);
1.291 +
1.292 +/*
1.293 + * FUNCTION: CMMF_KeyRecRepContentSetPKIStatusInfoStatus
1.294 + * INPUTS:
1.295 + * inKeyRecRep
1.296 + * The CMMFKeyRecRepContent to operate on.
1.297 + * inPKIStatus
1.298 + * The value to set the PKIStatusInfo.status field to.
1.299 + * NOTES:
1.300 + * This function sets the only required field for the KeyRecRepContent.
1.301 + * In most cases, the user will set this field and other fields of the
1.302 + * structure to properly create the CMMFKeyRecRepContent structure.
1.303 + * Refer to the CMMF draft to see which fields need to be set in order
1.304 + * to create the desired CMMFKeyRecRepContent.
1.305 + *
1.306 + * RETURN:
1.307 + * SECSuccess if setting the PKIStatusInfo.status field was successful.
1.308 + * Any other return value indicates an error in setting the field.
1.309 + */
1.310 +extern SECStatus
1.311 +CMMF_KeyRecRepContentSetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep,
1.312 + CMMFPKIStatus inPKIStatus);
1.313 +
1.314 +/*
1.315 + * FUNCTION: CMMF_KeyRecRepContentSetNewSignCert
1.316 + * INPUTS:
1.317 + * inKeyRecRep
1.318 + * The CMMFKeyRecRepContent to operate on.
1.319 + * inNewSignCert
1.320 + * The new signing cert to add to the CMMFKeyRecRepContent structure.
1.321 + * NOTES:
1.322 + * This function sets the new signeing cert in the CMMFKeyRecRepContent
1.323 + * structure.
1.324 + *
1.325 + * RETURN:
1.326 + * SECSuccess if setting the new signing cert was successful. Any other
1.327 + * return value indicates an error occurred while trying to add the
1.328 + * new signing certificate.
1.329 + */
1.330 +extern SECStatus
1.331 + CMMF_KeyRecRepContentSetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep,
1.332 + CERTCertificate *inNewSignCert);
1.333 +
1.334 +/*
1.335 + * FUNCTION: CMMF_KeyRecRepContentSetCACerts
1.336 + * INPUTS:
1.337 + * inKeyRecRep
1.338 + * The CMMFKeyRecRepContent to operate on.
1.339 + * inCACerts
1.340 + * The list of CA certificates required to construct a valid
1.341 + * certificate chain with the certificates that will be returned
1.342 + * to the end user via this KeyRecRepContent.
1.343 + * NOTES:
1.344 + * This function sets the caCerts that are required to form a chain with the
1.345 + * end entity certificates that are being re-issued in this
1.346 + * CMMFKeyRecRepContent structure.
1.347 + *
1.348 + * RETURN:
1.349 + * SECSuccess if adding the caCerts was successful. Any other return value
1.350 + * indicates an error while tring to add the caCerts.
1.351 + */
1.352 +extern SECStatus
1.353 + CMMF_KeyRecRepContentSetCACerts(CMMFKeyRecRepContent *inKeyRecRep,
1.354 + CERTCertList *inCACerts);
1.355 +
1.356 +/*
1.357 + * FUNCTION: CMMF_KeyRecRepContentSetCertifiedKeyPair
1.358 + * INPUTS:
1.359 + * inKeyRecRep
1.360 + * The CMMFKeyRecRepContent to operate on.
1.361 + * inCert
1.362 + * The certificate to add to the CMMFKeyRecRepContent structure.
1.363 + * inPrivKey
1.364 + * The private key associated with the certificate above passed in.
1.365 + * inPubKey
1.366 + * The public key to use for wrapping the private key.
1.367 + * NOTES:
1.368 + * This function adds another certificate-key pair to the
1.369 + * CMMFKeyRecRepcontent structure. There may be more than one
1.370 + * certificate-key pair in the structure, so the user must call this
1.371 + * function multiple times to add more than one cert-key pair.
1.372 + *
1.373 + * RETURN:
1.374 + * SECSuccess if adding the certified key pair was successful. Any other
1.375 + * return value indicates an error in adding certified key pair to
1.376 + * CMMFKeyRecRepContent structure.
1.377 + */
1.378 +extern SECStatus
1.379 + CMMF_KeyRecRepContentSetCertifiedKeyPair(CMMFKeyRecRepContent *inKeyRecRep,
1.380 + CERTCertificate *inCert,
1.381 + SECKEYPrivateKey *inPrivKey,
1.382 + SECKEYPublicKey *inPubKey);
1.383 +
1.384 +/*
1.385 + * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
1.386 + * INPUTS:
1.387 + * inDecKeyChall
1.388 + * The CMMFPOPODecKeyChallContent to operate on.
1.389 + * inRandom
1.390 + * The random number to use when generating the challenge,
1.391 + * inSender
1.392 + * The GeneralName representation of the sender of the challenge.
1.393 + * inPubKey
1.394 + * The public key to use when encrypting the challenge.
1.395 + * passwdArg
1.396 + * This value will be passed to the function used for getting a
1.397 + * password. The password for getting a password should be registered
1.398 + * by calling PK11_SetPasswordFunc before this function is called.
1.399 + * If no password callback is registered and the library needs to
1.400 + * authenticate to the slot for any reason, this function will fail.
1.401 + * NOTES:
1.402 + * This function adds a challenge to the end of the list of challenges
1.403 + * contained by 'inDecKeyChall'. Refer to the CMMF draft on how the
1.404 + * the random number passed in and the sender's GeneralName are used
1.405 + * to generate the challenge and witness fields of the challenge. This
1.406 + * library will use SHA1 as the one-way function for generating the
1.407 + * witess field of the challenge.
1.408 + *
1.409 + * RETURN:
1.410 + * SECSuccess if generating the challenge and adding to the end of list
1.411 + * of challenges was successful. Any other return value indicates an error
1.412 + * while trying to generate the challenge.
1.413 + */
1.414 +extern SECStatus
1.415 +CMMF_POPODecKeyChallContentSetNextChallenge
1.416 + (CMMFPOPODecKeyChallContent *inDecKeyChall,
1.417 + long inRandom,
1.418 + CERTGeneralName *inSender,
1.419 + SECKEYPublicKey *inPubKey,
1.420 + void *passwdArg);
1.421 +
1.422 +
1.423 +/************************** Encoding Functions *************************/
1.424 +
1.425 +/*
1.426 + * FUNCTION: CMMF_EncodeCertRepContent
1.427 + * INPUTS:
1.428 + * inCertRepContent
1.429 + * The CMMFCertRepContent to DER-encode.
1.430 + * inCallback
1.431 + * A callback function that the ASN1 encoder will call whenever it
1.432 + * wants to write out DER-encoded bytes. Look at the defintion of
1.433 + * CRMFEncoderOutputCallback in crmft.h for a description of the
1.434 + * parameters to the function.
1.435 + * inArg
1.436 + * An opaque pointer to a user-supplied argument that will be passed
1.437 + * to the callback funtion whenever the function is called.
1.438 + * NOTES:
1.439 + * The CMMF library will use the same DER-encoding scheme as the CRMF
1.440 + * library. In other words, when reading CRMF comments that pertain to
1.441 + * encoding, those comments apply to the CMMF libray as well.
1.442 + * The callback function will be called multiple times, each time supplying
1.443 + * the next chunk of DER-encoded bytes. The user must concatenate the
1.444 + * output of each successive call to the callback in order to get the
1.445 + * entire DER-encoded CMMFCertRepContent structure.
1.446 + *
1.447 + * RETURN:
1.448 + * SECSuccess if encoding the CMMFCertRepContent was successful. Any
1.449 + * other return value indicates an error while decoding the structure.
1.450 + */
1.451 +extern SECStatus
1.452 + CMMF_EncodeCertRepContent (CMMFCertRepContent *inCertRepContent,
1.453 + CRMFEncoderOutputCallback inCallback,
1.454 + void *inArg);
1.455 +
1.456 +/*
1.457 + * FUNCTION: CMMF_EncodeKeyRecRepContent
1.458 + * INPUTS:
1.459 + * inKeyRecRep
1.460 + * The CMMFKeyRepContent to DER-encode.
1.461 + * inCallback
1.462 + * A callback function that the ASN1 encoder will call whenever it
1.463 + * wants to write out DER-encoded bytes. Look at the defintion of
1.464 + * CRMFEncoderOutputCallback in crmft.h for a description of the
1.465 + * parameters to the function.
1.466 + * inArg
1.467 + * An opaque pointer to a user-supplied argument that will be passed
1.468 + * to the callback funtion whenever the function is called.
1.469 + * NOTES:
1.470 + * The CMMF library will use the same DER-encoding scheme as the CRMF
1.471 + * library. In other words, when reading CRMF comments that pertain to
1.472 + * encoding, those comments apply to the CMMF libray as well.
1.473 + * The callback function will be called multiple times, each time supplying
1.474 + * the next chunk of DER-encoded bytes. The user must concatenate the
1.475 + * output of each successive call to the callback in order to get the
1.476 + * entire DER-encoded CMMFCertRepContent structure.
1.477 + *
1.478 + * RETURN:
1.479 + * SECSuccess if encoding the CMMFKeyRecRepContent was successful. Any
1.480 + * other return value indicates an error while decoding the structure.
1.481 + */
1.482 +extern SECStatus
1.483 + CMMF_EncodeKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep,
1.484 + CRMFEncoderOutputCallback inCallback,
1.485 + void *inArg);
1.486 +
1.487 +/*
1.488 + * FUNCTION: CMMF_EncodePOPODecKeyChallContent
1.489 + * INPUTS:
1.490 + * inDecKeyChall
1.491 + * The CMMFDecKeyChallContent to operate on.
1.492 + * inCallback
1.493 + * A callback function that the ASN1 encoder will call whenever it
1.494 + * wants to write out DER-encoded bytes. Look at the defintion of
1.495 + * CRMFEncoderOutputCallback in crmft.h for a description of the
1.496 + * parameters to the function.
1.497 + * inArg
1.498 + * An opaque pointer to a user-supplied argument that will be passed
1.499 + * to the callback function whenever the function is called.
1.500 + * NOTES:
1.501 + * The CMMF library will use the same DER-encoding scheme as the CRMF
1.502 + * library. In other words, when reading CRMF comments that pertain to
1.503 + * encoding, those comments apply to the CMMF libray as well.
1.504 + * The callback function will be called multiple times, each time supplying
1.505 + * the next chunk of DER-encoded bytes. The user must concatenate the
1.506 + * output of each successive call to the callback in order to get the
1.507 + * entire DER-encoded CMMFCertRepContent structure.
1.508 + * The DER will be an encoding of the type POPODecKeyChallContents, which
1.509 + * is just a sequence of challenges.
1.510 + *
1.511 + * RETURN:
1.512 + * SECSuccess if encoding was successful. Any other return value indicates
1.513 + * an error in trying to encode the Challenges.
1.514 + */
1.515 +extern SECStatus
1.516 +CMMF_EncodePOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyChall,
1.517 + CRMFEncoderOutputCallback inCallback,
1.518 + void *inArg);
1.519 +
1.520 +/*
1.521 + * FUNCTION: CMMF_EncodePOPODecKeyRespContent
1.522 + * INPUTS:
1.523 + * inDecodedRand
1.524 + * An array of integers to encode as the responses to
1.525 + * CMMFPOPODecKeyChallContent. The integers must be in the same order
1.526 + * as the challenges extracted from CMMFPOPODecKeyChallContent.
1.527 + * inNumRand
1.528 + * The number of random integers contained in the array 'inDecodedRand'
1.529 + * inCallback
1.530 + * A callback function that the ASN1 encoder will call whenever it
1.531 + * wants to write out DER-encoded bytes. Look at the defintion of
1.532 + * CRMFEncoderOutputCallback in crmft.h for a description of the
1.533 + * parameters to the function.
1.534 + * inArg
1.535 + * An opaque pointer to a user-supplied argument that will be passed
1.536 + * to the callback funtion whenever the function is called.
1.537 + * NOTES:
1.538 + * The CMMF library will use the same DER-encoding scheme as the CRMF
1.539 + * library. In other words, when reading CRMF comments that pertain to
1.540 + * encoding, those comments apply to the CMMF libray as well.
1.541 + * The callback function will be called multiple times, each time supplying
1.542 + * the next chunk of DER-encoded bytes. The user must concatenate the
1.543 + * output of each successive call to the callback in order to get the
1.544 + * entire DER-encoded POPODecKeyRespContent.
1.545 + *
1.546 + * RETURN:
1.547 + * SECSuccess if encoding was successful. Any other return value indicates
1.548 + * an error in trying to encode the Challenges.
1.549 + */
1.550 +extern SECStatus
1.551 + CMMF_EncodePOPODecKeyRespContent(long *inDecodedRand,
1.552 + int inNumRand,
1.553 + CRMFEncoderOutputCallback inCallback,
1.554 + void *inArg);
1.555 +
1.556 +/*************** Accessor function ***********************************/
1.557 +
1.558 +/*
1.559 + * FUNCTION: CMMF_CertRepContentGetCAPubs
1.560 + * INPUTS:
1.561 + * inCertRepContent
1.562 + * The CMMFCertRepContent to extract the caPubs from.
1.563 + * NOTES:
1.564 + * This function will return a copy of the list of certificates that
1.565 + * make up the chain of CA's required to make the cert issued valid.
1.566 + * The user must call CERT_DestroyCertList on the return value when
1.567 + * done using the return value.
1.568 + *
1.569 + * Only call this function on a CertRepContent that has been decoded.
1.570 + * The client must call CERT_DestroyCertList when the certificate list
1.571 + * is no longer needed.
1.572 + *
1.573 + * The certs in the list will not be in the temporary database. In order
1.574 + * to make these certificates a part of the permanent CA internal database,
1.575 + * the user must collect the der for all of these certs and call
1.576 + * CERT_ImportCAChain. Afterwards the certs will be part of the permanent
1.577 + * database.
1.578 + *
1.579 + * RETURN:
1.580 + * A pointer to the CERTCertList representing the CA chain associated
1.581 + * with the issued cert. A NULL return value indicates that no CA Pubs
1.582 + * were available in the CMMFCertRepContent structure.
1.583 + */
1.584 +extern CERTCertList*
1.585 + CMMF_CertRepContentGetCAPubs (CMMFCertRepContent *inCertRepContent);
1.586 +
1.587 +
1.588 +/*
1.589 + * FUNCTION: CMMF_CertRepContentGetNumResponses
1.590 + * INPUTS:
1.591 + * inCertRepContent
1.592 + * The CMMFCertRepContent to operate on.
1.593 + * NOTES:
1.594 + * This function will return the number of CertResponses that are contained
1.595 + * by the CMMFCertRepContent passed in.
1.596 + *
1.597 + * RETURN:
1.598 + * The number of CMMFCertResponses contained in the structure passed in.
1.599 + */
1.600 +extern int
1.601 + CMMF_CertRepContentGetNumResponses (CMMFCertRepContent *inCertRepContent);
1.602 +
1.603 +/*
1.604 + * FUNCTION: CMMF_CertRepContentGetResponseAtIndex
1.605 + * INPUTS:
1.606 + * inCertRepContent
1.607 + * The CMMFCertRepContent to operate on.
1.608 + * inIndex
1.609 + * The index of the CMMFCertResponse the user wants a copy of.
1.610 + * NOTES:
1.611 + * This function creates a copy of the CMMFCertResponse at the index
1.612 + * corresponding to the parameter 'inIndex'. Indexing is done like a
1.613 + * traditional C array, ie the valid indexes are (0...numResponses-1).
1.614 + * The user must call CMMF_DestroyCertResponse after the return value is
1.615 + * no longer needed.
1.616 + *
1.617 + * RETURN:
1.618 + * A pointer to the CMMFCertResponse at the index corresponding to
1.619 + * 'inIndex'. A return value of NULL indicates an error in copying
1.620 + * the CMMFCertResponse.
1.621 + */
1.622 +extern CMMFCertResponse*
1.623 +CMMF_CertRepContentGetResponseAtIndex (CMMFCertRepContent *inCertRepContent,
1.624 + int inIndex);
1.625 +
1.626 +/*
1.627 + * FUNCTION: CMMF_CertResponseGetCertReqId
1.628 + * INPUTS:
1.629 + * inCertResp
1.630 + * The CMMFCertResponse to operate on.
1.631 + * NOTES:
1.632 + * This function returns the CertResponse.certReqId from the
1.633 + * CMMFCertResponse structure passed in. If the return value is -1, that
1.634 + * means there is no associated certificate request with the CertResponse.
1.635 + * RETURN:
1.636 + * A long representing the id of the certificate request this
1.637 + * CMMFCertResponse corresponds to. A return value of -1 indicates an
1.638 + * error in extracting the value of the integer.
1.639 + */
1.640 +extern long CMMF_CertResponseGetCertReqId(CMMFCertResponse *inCertResp);
1.641 +
1.642 +/*
1.643 + * FUNCTION: CMMF_CertResponseGetPKIStatusInfoStatus
1.644 + * INPUTS:
1.645 + * inCertResp
1.646 + * The CMMFCertResponse to operate on.
1.647 + * NOTES:
1.648 + * This function returns the CertResponse.status.status field of the
1.649 + * CMMFCertResponse structure.
1.650 + *
1.651 + * RETURN:
1.652 + * The enumerated value corresponding to the PKIStatus defined in the CMMF
1.653 + * draft. See the CMMF draft for the definition of PKIStatus. See crmft.h
1.654 + * for the definition of CMMFPKIStatus.
1.655 + */
1.656 +extern CMMFPKIStatus
1.657 + CMMF_CertResponseGetPKIStatusInfoStatus(CMMFCertResponse *inCertResp);
1.658 +
1.659 +/*
1.660 + * FUNCTION: CMMF_CertResponseGetCertificate
1.661 + * INPUTS:
1.662 + * inCertResp
1.663 + * The Certificate Response to operate on.
1.664 + * inCertdb
1.665 + * This is the certificate database where the function will place the
1.666 + * newly issued certificate.
1.667 + * NOTES:
1.668 + * This function retrieves the CertResponse.certifiedKeyPair.certificate
1.669 + * from the CMMFCertResponse. The user will get a copy of that certificate
1.670 + * so the user must call CERT_DestroyCertificate when the return value is
1.671 + * no longer needed. The certificate returned will be in the temporary
1.672 + * certificate database.
1.673 + *
1.674 + * RETURN:
1.675 + * A pointer to a copy of the certificate contained within the
1.676 + * CMMFCertResponse. A return value of NULL indicates an error while trying
1.677 + * to make a copy of the certificate.
1.678 + */
1.679 +extern CERTCertificate*
1.680 + CMMF_CertResponseGetCertificate(CMMFCertResponse *inCertResp,
1.681 + CERTCertDBHandle *inCertdb);
1.682 +
1.683 +/*
1.684 + * FUNCTION: CMMF_KeyRecRepContentGetPKIStatusInfoStatus
1.685 + * INPUTS:
1.686 + * inKeyRecRep
1.687 + * The CMMFKeyRecRepContent structure to operate on.
1.688 + * NOTES:
1.689 + * This function retrieves the KeyRecRepContent.status.status field of
1.690 + * the CMMFKeyRecRepContent structure.
1.691 + * RETURN:
1.692 + * The CMMFPKIStatus corresponding to the value held in the
1.693 + * CMMFKeyRecRepContent structure.
1.694 + */
1.695 +extern CMMFPKIStatus
1.696 +CMMF_KeyRecRepContentGetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep);
1.697 +
1.698 +/*
1.699 + * FUNCTION: CMMF_KeyRecRepContentGetNewSignCert
1.700 + * INPUTS:
1.701 + * inKeyRecRep
1.702 + * The CMMFKeyRecRepContent to operate on.
1.703 + * NOTES:
1.704 + * This function retrieves the KeyRecRepContent.newSignCert field of the
1.705 + * CMMFKeyRecRepContent structure. The user must call
1.706 + * CERT_DestroyCertificate when the return value is no longer needed. The
1.707 + * returned certificate will be in the temporary database. The user
1.708 + * must then place the certificate permanently in whatever token the
1.709 + * user determines is the proper destination. A return value of NULL
1.710 + * indicates the newSigCert field was not present.
1.711 + */
1.712 +extern CERTCertificate*
1.713 + CMMF_KeyRecRepContentGetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep);
1.714 +
1.715 +/*
1.716 + * FUNCTION: CMMF_KeyRecRepContentGetCACerts
1.717 + * INPUTS:
1.718 + * inKeyRecRep
1.719 + * The CMMFKeyRecRepContent to operate on.
1.720 + * NOTES:
1.721 + * This function returns a CERTCertList which contains all of the
1.722 + * certficates that are in the sequence KeyRecRepContent.caCerts
1.723 + * User must call CERT_DestroyCertList when the return value is no longer
1.724 + * needed. All of these certificates will be placed in the tempoaray
1.725 + * database.
1.726 + *
1.727 + * RETURN:
1.728 + * A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
1.729 + * structure. A return value of NULL indicates the library was not able to
1.730 + * make a copy of the certifcates. This may be because there are no caCerts
1.731 + * included in the CMMFKeyRecRepContent strucure or an internal error. Call
1.732 + * CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts
1.733 + * included in 'inKeyRecRep'.
1.734 + */
1.735 +extern CERTCertList*
1.736 + CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);
1.737 +
1.738 +/*
1.739 + * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
1.740 + * INPUTS:
1.741 + * inKeyRecRep
1.742 + * The CMMFKeyRecRepContent to operate on.
1.743 + * RETURN:
1.744 + * This function returns the number of CMMFCertifiedKeyPair structures that
1.745 + * that are stored in the KeyRecRepContent structure.
1.746 + */
1.747 +extern int
1.748 + CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);
1.749 +
1.750 +/*
1.751 + * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
1.752 + * INPUTS:
1.753 + * inKeyRecRepContent
1.754 + * The CMMFKeyRecRepContent to operate on.
1.755 + * inIndex
1.756 + * The index of the desired CMMFCertifiedKeyPair
1.757 + * NOTES:
1.758 + * This function retrieves the CMMFCertifiedKeyPair structure at the index
1.759 + * 'inIndex'. Valid indexes are 0...(numKeyPairs-1) The user must call
1.760 + * CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
1.761 + *
1.762 + * RETURN:
1.763 + * A pointer to the Certified Key Pair at the desired index. A return value
1.764 + * of NULL indicates an error in extracting the Certified Key Pair at the
1.765 + * desired index.
1.766 + */
1.767 +extern CMMFCertifiedKeyPair*
1.768 + CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
1.769 + int inIndex);
1.770 +
1.771 +/*
1.772 + * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
1.773 + * INPUTS:
1.774 + * inCertKeyPair
1.775 + * The CMMFCertifiedKeyPair to operate on.
1.776 + * inCertdb
1.777 + * The database handle for the database you want this certificate
1.778 + * to wind up in.
1.779 + * NOTES:
1.780 + * This function retrieves the certificate at
1.781 + * CertifiedKeyPair.certOrEncCert.certificate
1.782 + * The user must call CERT_DestroyCertificate when the return value is no
1.783 + * longer needed. The user must import this certificate as a token object
1.784 + * onto PKCS#11 slot in order to make it a permanent object. The returned
1.785 + * certificate will be in the temporary database.
1.786 + *
1.787 + * RETURN:
1.788 + * A pointer to the certificate contained within the certified key pair.
1.789 + * A return value of NULL indicates an error in creating the copy of the
1.790 + * certificate.
1.791 + */
1.792 +extern CERTCertificate*
1.793 + CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
1.794 + CERTCertDBHandle *inCertdb);
1.795 +
1.796 +/*
1.797 + * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
1.798 + * INPUTS:
1.799 + * inKeyChallCont
1.800 + * The CMMFPOPODecKeyChallContent to operate on.
1.801 + * RETURN:
1.802 + * This function returns the number of CMMFChallenges are contained in
1.803 + * the CMMFPOPODecKeyChallContent structure.
1.804 + */
1.805 +extern int CMMF_POPODecKeyChallContentGetNumChallenges
1.806 + (CMMFPOPODecKeyChallContent *inKeyChallCont);
1.807 +
1.808 +/*
1.809 + * FUNCTION: CMMF_POPODecKeyChallContentGetPublicValue
1.810 + * ---------------------------------------------------
1.811 + * INPUTS:
1.812 + * inKeyChallCont
1.813 + * The CMMFPOPODecKeyChallContent to operate on.
1.814 + * inIndex
1.815 + * The index of the Challenge within inKeyChallCont to operate on.
1.816 + * Indexes start from 0, ie the Nth Challenge corresponds to index
1.817 + * N-1.
1.818 + * NOTES:
1.819 + * This function retrieves the public value stored away in the Challenge at
1.820 + * index inIndex of inKeyChallCont.
1.821 + * RETURN:
1.822 + * A pointer to a SECItem containing the public value. User must call
1.823 + * SECITEM_FreeItem on the return value when the value is no longer necessary.
1.824 + * A return value of NULL indicates an error while retrieving the public value.
1.825 + */
1.826 +extern SECItem* CMMF_POPODecKeyChallContentGetPublicValue
1.827 + (CMMFPOPODecKeyChallContent *inKeyChallCont,
1.828 + int inIndex);
1.829 +
1.830 +
1.831 +/*
1.832 + * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
1.833 + * INPUTS:
1.834 + * inChallContent
1.835 + * The CMMFPOPODecKeyChallContent to operate on.
1.836 + * inIndex
1.837 + * The index of the challenge to look at. Valid indexes are 0 through
1.838 + * (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
1.839 + * inDest
1.840 + * A pointer to a user supplied buffer where the library
1.841 + * can place a copy of the random integer contatained in the
1.842 + * challenge.
1.843 + * NOTES:
1.844 + * This function returns the value held in the decrypted Rand structure
1.845 + * corresponding to the random integer. The user must call
1.846 + * CMMF_POPODecKeyChallContentDecryptChallenge before calling this function. Call
1.847 + * CMMF_ChallengeIsDecrypted to find out if the challenge has been
1.848 + * decrypted.
1.849 + *
1.850 + * RETURN:
1.851 + * SECSuccess indicates the witness field has been previously decrypted
1.852 + * and the value for the random integer was successfully placed at *inDest.
1.853 + * Any other return value indicates an error and that the value at *inDest
1.854 + * is not a valid value.
1.855 + */
1.856 +extern SECStatus CMMF_POPODecKeyChallContentGetRandomNumber
1.857 + (CMMFPOPODecKeyChallContent *inKeyChallCont,
1.858 + int inIndex,
1.859 + long *inDest);
1.860 +
1.861 +/*
1.862 + * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
1.863 + * INPUTS:
1.864 + * inRespCont
1.865 + * The POPODecKeyRespContent to operate on.
1.866 + * RETURN:
1.867 + * This function returns the number of responses contained in inRespContent.
1.868 + */
1.869 +extern int
1.870 + CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);
1.871 +
1.872 +/*
1.873 + * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
1.874 + * INPUTS:
1.875 + * inRespCont
1.876 + * The POPODecKeyRespContent to operate on.
1.877 + * inIndex
1.878 + * The index of the response to retrieve.
1.879 + * The Nth response is at index N-1, ie the 1st response is at index 0,
1.880 + * the 2nd response is at index 1, and so on.
1.881 + * inDest
1.882 + * A pointer to a pre-allocated buffer where the library can put the
1.883 + * value of the response located at inIndex.
1.884 + * NOTES:
1.885 + * The function returns the response contained at index inIndex.
1.886 + * CMMFPOPODecKeyRespContent is a structure that the server will generally
1.887 + * get in response to a CMMFPOPODecKeyChallContent. The server will expect
1.888 + * to see the responses in the same order as it constructed them in
1.889 + * the CMMFPOPODecKeyChallContent structure.
1.890 + * RETURN:
1.891 + * SECSuccess if getting the response at the desired index was successful. Any
1.892 + * other return value indicates an errror.
1.893 + */
1.894 +extern SECStatus
1.895 + CMMF_POPODecKeyRespContentGetResponse (CMMFPOPODecKeyRespContent *inRespCont,
1.896 + int inIndex,
1.897 + long *inDest);
1.898 +
1.899 +/************************* Destructor Functions ******************************/
1.900 +
1.901 +/*
1.902 + * FUNCTION: CMMF_DestroyCertResponse
1.903 + * INPUTS:
1.904 + * inCertResp
1.905 + * The CMMFCertResponse to destroy.
1.906 + * NOTES:
1.907 + * This function frees all the memory associated with the CMMFCertResponse
1.908 + * passed in.
1.909 + * RETURN:
1.910 + * SECSuccess if freeing the memory was successful. Any other return value
1.911 + * indicates an error while freeing the memory.
1.912 + */
1.913 +extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);
1.914 +
1.915 +/*
1.916 + * FUNCTION: CMMF_DestroyCertRepContent
1.917 + * INPUTS:
1.918 + * inCertRepContent
1.919 + * The CMMFCertRepContent to destroy
1.920 + * NOTES:
1.921 + * This function frees the memory associated with the CMMFCertRepContent
1.922 + * passed in.
1.923 + * RETURN:
1.924 + * SECSuccess if freeing all the memory associated with the
1.925 + * CMMFCertRepContent passed in is successful. Any other return value
1.926 + * indicates an error while freeing the memory.
1.927 + */
1.928 +extern SECStatus
1.929 + CMMF_DestroyCertRepContent (CMMFCertRepContent *inCertRepContent);
1.930 +
1.931 +/*
1.932 + * FUNCTION: CMMF_DestroyKeyRecRepContent
1.933 + * INPUTS:
1.934 + * inKeyRecRep
1.935 + * The CMMFKeyRecRepContent to destroy.
1.936 + * NOTES:
1.937 + * This function destroys all the memory associated with the
1.938 + * CMMFKeyRecRepContent passed in.
1.939 + *
1.940 + * RETURN:
1.941 + * SECSuccess if freeing all the memory is successful. Any other return
1.942 + * value indicates an error in freeing the memory.
1.943 + */
1.944 +extern SECStatus
1.945 + CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);
1.946 +
1.947 +/*
1.948 + * FUNCTION: CMMF_DestroyCertifiedKeyPair
1.949 + * INPUTS:
1.950 + * inCertKeyPair
1.951 + * The CMMFCertifiedKeyPair to operate on.
1.952 + * NOTES:
1.953 + * This function frees up all the memory associated with 'inCertKeyPair'
1.954 + *
1.955 + * RETURN:
1.956 + * SECSuccess if freeing all the memory associated with 'inCertKeyPair'
1.957 + * is successful. Any other return value indicates an error while trying
1.958 + * to free the memory.
1.959 + */
1.960 +extern SECStatus
1.961 + CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);
1.962 +
1.963 +/*
1.964 + * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
1.965 + * INPUTS:
1.966 + * inDecKeyResp
1.967 + * The CMMFPOPODecKeyRespContent structure to free.
1.968 + * NOTES:
1.969 + * This function frees up all the memory associate with the
1.970 + * CMMFPOPODecKeyRespContent.
1.971 + *
1.972 + * RETURN:
1.973 + * SECSuccess if freeing up all the memory associated with the
1.974 + * CMMFPOPODecKeyRespContent structure is successful. Any other
1.975 + * return value indicates an error while freeing the memory.
1.976 + */
1.977 +extern SECStatus
1.978 + CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
1.979 +
1.980 +
1.981 +/************************** Miscellaneous Functions *************************/
1.982 +
1.983 +/*
1.984 + * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
1.985 + * INPUTS:
1.986 + * inCertKeyPair
1.987 + * The CMMFCertifiedKeyPair to operate on.
1.988 + * inPrivKey
1.989 + * The private key to use to un-wrap the private key
1.990 + * inNickName
1.991 + * This is the nickname that will be associated with the private key
1.992 + * to be unwrapped.
1.993 + * inSlot
1.994 + * The PKCS11 slot where the unwrapped private key should end up.
1.995 + * inCertdb
1.996 + * The Certificate database with which the new key will be associated.
1.997 + * destPrivKey
1.998 + * A pointer to memory where the library can place a pointer to the
1.999 + * private key after importing the key onto the specified slot.
1.1000 + * wincx
1.1001 + * An opaque pointer that the library will use in a callback function
1.1002 + * to get the password if necessary.
1.1003 + *
1.1004 + * NOTES:
1.1005 + * This function uses the private key passed in to unwrap the private key
1.1006 + * contained within the CMMFCertifiedKeyPair structure. After this
1.1007 + * function successfully returns, the private key has been unwrapped and
1.1008 + * placed in the specified slot.
1.1009 + *
1.1010 + * RETURN:
1.1011 + * SECSuccess if unwrapping the private key was successful. Any other
1.1012 + * return value indicates an error while trying to un-wrap the private key.
1.1013 + */
1.1014 +extern SECStatus
1.1015 + CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
1.1016 + SECKEYPrivateKey *inPrivKey,
1.1017 + SECItem *inNickName,
1.1018 + PK11SlotInfo *inSlot,
1.1019 + CERTCertDBHandle *inCertdb,
1.1020 + SECKEYPrivateKey **destPrivKey,
1.1021 + void *wincx);
1.1022 +
1.1023 +/*
1.1024 + * FUNCTION: CMMF_KeyRecRepContentHasCACerts
1.1025 + * INPUTS:
1.1026 + * inKeyRecRecp
1.1027 + * The CMMFKeyRecRepContent to operate on.
1.1028 + * RETURN:
1.1029 + * This function returns PR_TRUE if there are one or more certificates in
1.1030 + * the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
1.1031 + * structure. The function will return PR_FALSE if there are 0 certificate
1.1032 + * in the above mentioned sequence.
1.1033 + */
1.1034 +extern PRBool
1.1035 + CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);
1.1036 +
1.1037 +/*
1.1038 + * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
1.1039 + * INPUTS:
1.1040 + * inChalCont
1.1041 + * The CMMFPOPODecKeyChallContent to operate on.
1.1042 + * inIndex
1.1043 + * The index of the Challenge to operate on. The 1st Challenge is
1.1044 + * at index 0, the second at index 1 and so forth.
1.1045 + * inPrivKey
1.1046 + * The private key to use to decrypt the witness field.
1.1047 + * NOTES:
1.1048 + * This function uses the private key to decrypt the challenge field
1.1049 + * contained in the appropriate challenge. Make sure the private key matches
1.1050 + * the public key that was used to encrypt the witness. Use
1.1051 + * CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
1.1052 + * the key used to encrypt the witness and then use that to determine the
1.1053 + * appropriate private key. This can be done by calling PK11_MakeIDFromPubKey
1.1054 + * and then passing that return value to PK11_FindKeyByKeyID. The creator of
1.1055 + * the challenge will most likely be an RA that has the public key
1.1056 + * from a Cert request. So the private key should be the private key
1.1057 + * associated with public key in that request. This function will also
1.1058 + * verify the witness field of the challenge. This function also verifies
1.1059 + * that the sender and witness hashes match within the challenge.
1.1060 + *
1.1061 + * RETURN:
1.1062 + * SECSuccess if decrypting the witness field was successful. This does
1.1063 + * not indicate that the decrypted data is valid, since the private key
1.1064 + * passed in may not be the actual key needed to properly decrypt the
1.1065 + * witness field. Meaning that there is a decrypted structure now, but
1.1066 + * may be garbage because the private key was incorrect.
1.1067 + * Any other return value indicates the function could not complete the
1.1068 + * decryption process.
1.1069 + */
1.1070 +extern SECStatus
1.1071 + CMMF_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
1.1072 + int inIndex,
1.1073 + SECKEYPrivateKey *inPrivKey);
1.1074 +
1.1075 +/*
1.1076 + * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
1.1077 + * INPUTS:
1.1078 + * inDecKeyCont
1.1079 + * The CMMFPOPODecKeyChallContent to free
1.1080 + * NOTES:
1.1081 + * This function frees up all the memory associated with the
1.1082 + * CMMFPOPODecKeyChallContent
1.1083 + * RETURN:
1.1084 + * SECSuccess if freeing up all the memory associatd with the
1.1085 + * CMMFPOPODecKeyChallContent is successful. Any other return value
1.1086 + * indicates an error while freeing the memory.
1.1087 + *
1.1088 + */
1.1089 +extern SECStatus
1.1090 + CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
1.1091 +
1.1092 +SEC_END_PROTOS
1.1093 +#endif /* _CMMF_H_ */
