1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/crmf/crmf.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1750 @@
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 +
1.10 +#ifndef _CRMF_H_
1.11 +#define _CRMF_H_
1.12 +
1.13 +#include "seccomon.h"
1.14 +#include "cert.h"
1.15 +#include "crmft.h"
1.16 +#include "secoid.h"
1.17 +#include "secpkcs7.h"
1.18 +
1.19 +SEC_BEGIN_PROTOS
1.20 +
1.21 +/*
1.22 + * FUNCTION: CRMF_EncodeCertReqMsg
1.23 + * INPUTS:
1.24 + * inCertReqMsg
1.25 + * The Certificate Request Message to be encoded.
1.26 + * fn
1.27 + * A Callback function that the ASN1 encoder calls whenever
1.28 + * the encoder wants to write out some DER encoded bytes.
1.29 + * arg
1.30 + * An opaque pointer that gets passed to the function fn
1.31 + * OUTPUT:
1.32 + * The function fn will be called multiple times. Look at the
1.33 + * comments in crmft.h where the CRMFEncoderOutputCallback type is
1.34 + * defined for information on proper behavior of the function fn.
1.35 + * RETURN:
1.36 + * SECSuccess if encoding was successful. Any other return value
1.37 + * indicates an error occurred during encoding.
1.38 + */
1.39 +extern SECStatus
1.40 + CRMF_EncodeCertReqMsg (CRMFCertReqMsg *inCertReqMsg,
1.41 + CRMFEncoderOutputCallback fn,
1.42 + void *arg);
1.43 +
1.44 +/*
1.45 + * FUNCTION: CRMF_EncoderCertRequest
1.46 + * INPUTS:
1.47 + * inCertReq
1.48 + * The Certificate Request to be encoded.
1.49 + * fn
1.50 + * A Callback function that the ASN1 encoder calls whenever
1.51 + * the encoder wants to write out some DER encoded bytes.
1.52 + * arg
1.53 + * An opaque pointer that gets passed to the function fn.
1.54 + * OUTPUT:
1.55 + * The function fn will be called, probably multiple times whenever
1.56 + * the ASN1 encoder wants to write out DER-encoded bytes. Look at the
1.57 + * comments in crmft.h where the CRMFEncoderOutputCallback type is
1.58 + * defined for information on proper behavior of the function fn.
1.59 + * RETURN:
1.60 + * SECSuccess if encoding was successful. Any other return value
1.61 + * indicates an error occurred during encoding.
1.62 + */
1.63 +extern SECStatus CRMF_EncodeCertRequest (CRMFCertRequest *inCertReq,
1.64 + CRMFEncoderOutputCallback fn,
1.65 + void *arg);
1.66 +/*
1.67 + * FUNCTION: CRMF_EncodeCertReqMessages
1.68 + * INPUTS:
1.69 + * inCertReqMsgs
1.70 + * An array of pointers to the Certificate Request Messages
1.71 + * to encode. The user must place a NULL pointer in the index
1.72 + * after the last message to be encoded. When the library runs
1.73 + * into the NULL pointer, the library assumes there are no more
1.74 + * messages to encode.
1.75 + * fn
1.76 + * A Callback function that the ASN1 encoder calls whenever
1.77 + * the encoder wants to write out some DER encoded byts.
1.78 + * arg
1.79 + * An opaque pointer that gets passed to the function fn.
1.80 + *
1.81 + * NOTES:
1.82 + * The parameter inCertReqMsgs needs to be an array with a NULL pointer
1.83 + * to signal the end of messages. An array in the form of
1.84 + * {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and
1.85 + * m3. All messages from m4 on will not be looked at by the library.
1.86 + *
1.87 + * OUTPUT:
1.88 + * The function fn will be called, probably multiple times. Look at the
1.89 + * comments in crmft.h where the CRMFEncoderOutputCallback type is
1.90 + * defined for information on proper behavior of the function fn.
1.91 + *
1.92 + * RETURN:
1.93 + * SECSuccess if encoding the Certificate Request Messages was successful.
1.94 + * Any other return value indicates an error occurred while encoding the
1.95 + * certificate request messages.
1.96 + */
1.97 +extern SECStatus
1.98 + CRMF_EncodeCertReqMessages(CRMFCertReqMsg **inCertReqMsgs,
1.99 + CRMFEncoderOutputCallback fn,
1.100 + void *arg);
1.101 +
1.102 +
1.103 +/*
1.104 + * FUNCTION: CRMF_CreateCertReqMsg
1.105 + * INPUTS:
1.106 + * NONE
1.107 + * OUTPUT:
1.108 + * An empty CRMF Certificate Request Message.
1.109 + * Before encoding this message, the user must set
1.110 + * the ProofOfPossession field and the certificate
1.111 + * request which are necessary for the full message.
1.112 + * After the user no longer needs this CertReqMsg,
1.113 + * the user must call CRMF_DestroyCertReqMsg to free
1.114 + * all memory associated with the Certificate Request
1.115 + * Message.
1.116 + * RETURN:
1.117 + * A pointer to a Certificate Request Message. The user
1.118 + * must pass the return value of this function to
1.119 + * CRMF_DestroyCertReqMsg after the Certificate Request
1.120 + * Message is no longer necessary.
1.121 + */
1.122 +extern CRMFCertReqMsg* CRMF_CreateCertReqMsg(void);
1.123 +
1.124 +/*
1.125 + * FUNCTION: CRMF_DestroyCertReqMsg
1.126 + * INPUTS:
1.127 + * inCertReqMsg
1.128 + * The Certificate Request Message to destroy.
1.129 + * NOTES:
1.130 + * This function frees all the memory used for the Certificate
1.131 + * Request Message and all the memory used in making copies of
1.132 + * fields of elelments of the message, eg. the Proof Of Possession
1.133 + * filed and the Cetificate Request.
1.134 + * RETURN:
1.135 + * SECSuccess if destruction was successful. Any other return value
1.136 + * indicates an error while trying to free the memory associated
1.137 + * with inCertReqMsg.
1.138 + *
1.139 + */
1.140 +extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg);
1.141 +
1.142 +/*
1.143 + * FUNCTION: CRMF_CertReqMsgSetCertRequest
1.144 + * INPUTS:
1.145 + * inCertReqMsg
1.146 + * The Certificate Request Message that the function will set
1.147 + * the certificate request for.
1.148 + * inCertReq
1.149 + * The Certificate Request that will be added to the Certificate
1.150 + * Request Message.
1.151 + * NOTES:
1.152 + * This function will make a copy of the Certificate Request passed in
1.153 + * and store it as part of the Certificate Request Message. Therefore,
1.154 + * the user must not call this function until the Certificate Request
1.155 + * has been fully built and is ready to be encoded.
1.156 + * RETURN:
1.157 + * SECSuccess
1.158 + * If copying the Certificate as a member of the Certificate
1.159 + * request message was successful.
1.160 + * Any other return value indicates a failure to copy the Certificate
1.161 + * Request and make it a part of the Certificate Request Message.
1.162 + */
1.163 +extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg *inCertReqMsg,
1.164 + CRMFCertRequest *inCertReq);
1.165 +
1.166 +/*
1.167 + * FUNCTION: CRMF_CreateCertRequest
1.168 + * INPUTS:
1.169 + * inRequestID
1.170 + * The ID that will be associated with this certificate request.
1.171 + * OUTPUTS:
1.172 + * A certificate request which only has the requestID set.
1.173 + * NOTES:
1.174 + * The user must call the function CRMF_DestroyCertRequest when
1.175 + * the returned value is no longer needed. This is usually the
1.176 + * case after fully constructing the Certificate Request and then
1.177 + * calling the function CRMF_CertReqMsgSetCertRequest.
1.178 + * RETURN:
1.179 + * A pointer to the new Certificate Request. A NULL return value
1.180 + * indicates an error in creating the Certificate Request.
1.181 + */
1.182 +extern CRMFCertRequest *CRMF_CreateCertRequest (PRUint32 inRequestID);
1.183 +
1.184 +/*
1.185 + * FUNCTION: CRMF_DestroyCertRequest
1.186 + * INPUTS:
1.187 + * inCertReq
1.188 + * The Certificate Request that will be destroyed.
1.189 + * RETURN:
1.190 + * SECSuccess
1.191 + * If freeing the memory associated with the certificate request
1.192 + * was successful.
1.193 + * Any other return value indicates an error while trying to free the
1.194 + * memory.
1.195 + */
1.196 +extern SECStatus CRMF_DestroyCertRequest (CRMFCertRequest *inCertReq);
1.197 +
1.198 +/*
1.199 + * FUNCTION: CRMF_CreateCertExtension
1.200 + * INPUTS:
1.201 + * id
1.202 + * The SECOidTag to associate with this CertExtension. This must
1.203 + * correspond to a valid Certificate Extension, if not the function
1.204 + * will fail.
1.205 + * isCritical
1.206 + * A boolean value stating if the extension value is crtical. PR_TRUE
1.207 + * means the value is crtical. PR_FALSE indicates the value is not
1.208 + * critical.
1.209 + * data
1.210 + * This is the data associated with the extension. The user of the
1.211 + * library is responsible for making sure the value passed in is a
1.212 + * valid interpretation of the certificate extension.
1.213 + * NOTES:
1.214 + * Use this function to create CRMFCertExtension Structures which will
1.215 + * then be passed to CRMF_AddFieldToCertTemplate as part of the
1.216 + * CRMFCertCreationInfo.extensions The user must call
1.217 + * CRMF_DestroyCertExtension after the extension has been added to a certifcate
1.218 + * and the extension is no longer needed.
1.219 + *
1.220 + * RETURN:
1.221 + * A pointer to a newly created CertExtension. A return value of NULL
1.222 + * indicates the id passed in was an invalid certificate extension.
1.223 + */
1.224 +extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag id,
1.225 + PRBool isCritical,
1.226 + SECItem *data);
1.227 +
1.228 +/*
1.229 + * FUNCTION: CMRF_DestroyCertExtension
1.230 + * INPUTS:
1.231 + * inExtension
1.232 + * The Cert Extension to destroy
1.233 + * NOTES:
1.234 + * Destroy a structure allocated by CRMF_CreateCertExtension.
1.235 + *
1.236 + * RETURN:
1.237 + * SECSuccess if freeing the memory associated with the certificate extension
1.238 + * was successful. Any other error indicates an error while freeing the
1.239 + * memory.
1.240 + */
1.241 +extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension);
1.242 +
1.243 +/*
1.244 + * FUNCTION: CRMF_CertRequestSetTemplateField
1.245 + * INPUTS:
1.246 + * inCertReq
1.247 + * The Certificate Request to operate on.
1.248 + * inTemplateField
1.249 + * An enumeration that indicates which field of the Certificate
1.250 + * template to add.
1.251 + * data
1.252 + * A generic pointer that will be type cast according to the
1.253 + * table under NOTES and used as the key for adding to the
1.254 + * certificate template;
1.255 + * NOTES:
1.256 + *
1.257 + * Below is a table that tells what type to pass in as data
1.258 + * depending on the template field one wants to set.
1.259 + *
1.260 + * Look in crmft.h for the definition of CRMFCertTemplateField.
1.261 + *
1.262 + * In all cases, the library makes copies of the data passed in.
1.263 + *
1.264 + * CRMFCertTemplateField Type of data What data means
1.265 + * --------------------- ------------ ---------------
1.266 + * crmfVersion long * The version of
1.267 + * the certificate
1.268 + * to be created.
1.269 + *
1.270 + * crmfSerialNumber long * The serial number
1.271 + * for the cert to be
1.272 + * created.
1.273 + *
1.274 + * crmfSigningAlg SECAlgorithm * The ASN.1 object ID for
1.275 + * the algorithm used in encoding
1.276 + * the certificate.
1.277 + *
1.278 + * crmfIssuer CERTName * Certificate Library
1.279 + * representation of the ASN1 type
1.280 + * Name from X.509
1.281 + *
1.282 + * crmfValidity CRMFValidityCreationInfo * At least one of the two
1.283 + * fields in the structure must
1.284 + * be present. A NULL pointer
1.285 + * in the structure indicates
1.286 + * that member should not be
1.287 + * added.
1.288 + *
1.289 + * crmfSubject CERTName * Certificate Library
1.290 + * representation of the ASN1 type
1.291 + * Name from X.509
1.292 + *
1.293 + * crmfPublicKey CERTSubjectPublicKeyInfo * The public key info for the
1.294 + * certificate being requested.
1.295 + *
1.296 + * crmfIssuerUID SECItem * A bit string representation
1.297 + * of the issuer UID. NOTE: The
1.298 + * length is the number of bits
1.299 + * and not the number of bytes.
1.300 + *
1.301 + * crmfSubjectUID SECItem* A bit string representation
1.302 + * of the subject UID. NOTE: The
1.303 + * length is the number of bits
1.304 + * and not the number of bytes.
1.305 + *
1.306 + * crmfExtension CRMFCertExtCreationInfo * A pointer to the structure
1.307 + * populated with an array of
1.308 + * of certificate extensions
1.309 + * and an integer that tells
1.310 + * how many elements are in the
1.311 + * array. Look in crmft.h for
1.312 + * the definition of
1.313 + * CRMFCertExtCreationInfo
1.314 + * RETURN:
1.315 + * SECSuccess if adding the desired field to the template was successful.
1.316 + * Any other return value indicates failure when trying to add the field
1.317 + * to the template.
1.318 + *
1.319 + */
1.320 +extern SECStatus
1.321 + CRMF_CertRequestSetTemplateField(CRMFCertRequest *inCertReq,
1.322 + CRMFCertTemplateField inTemplateField,
1.323 + void *data);
1.324 +
1.325 +/*
1.326 + * FUNCTION: CRMF_CertRequestIsFieldPresent
1.327 + * INPUTS:
1.328 + * inCertReq
1.329 + * The certificate request to operate on.
1.330 + * inTemplateField
1.331 + * The enumeration for the template field the user wants to query
1.332 + * about.
1.333 + * NOTES:
1.334 + * This function checks to see if the the field associated with inTemplateField
1.335 + * enumeration is already present in the certificate request passed in.
1.336 + *
1.337 + * RETURN:
1.338 + * The function returns PR_TRUE if the field associated with inTemplateField
1.339 + * is already present in the certificate request. If the field is not present
1.340 + * the function returns PR_FALSE.
1.341 + */
1.342 +extern PRBool
1.343 + CRMF_CertRequestIsFieldPresent(CRMFCertRequest *inCertReq,
1.344 + CRMFCertTemplateField inTemplateField);
1.345 +
1.346 +/*
1.347 + * FUNCTION: CRMF_CertRequestIsControlPresent
1.348 + * INPUTS:
1.349 + * inCertReq
1.350 + * The certificate request to operate on.
1.351 + * inControlType
1.352 + * The type of control to look for.
1.353 + * NOTES:
1.354 + * This function looks at the control present in the certificate request
1.355 + * and returns PR_TRUE iff a control of type inControlType already exists.
1.356 + * The CRMF draft does not explicitly state that two controls of the same
1.357 + * type can not exist within the same request. So the library will not
1.358 + * cause an error if you try to add a control and one of the same type
1.359 + * already exists. It is up to the application to ensure that multiple
1.360 + * controls of the same type do not exist, if that is the desired behavior
1.361 + * by the application.
1.362 + *
1.363 + * RETURN:
1.364 + * The function returns PR_TRUE if a control of type inControlType already
1.365 + * exists in the certificate request. If a control of type inControlType
1.366 + * does not exist, the function will return PR_FALSE.
1.367 + */
1.368 +extern PRBool
1.369 + CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq,
1.370 + CRMFControlType inControlType);
1.371 +
1.372 +
1.373 +/*
1.374 + * FUNCTION: CRMF_CertRequestSetRegTokenControl
1.375 + * INPUTS:
1.376 + * inCertReq
1.377 + * The Certificate Request to operate on.
1.378 + * value
1.379 + * The UTF8 value which will be the Registration Token Control
1.380 + * for this Certificate Request.
1.381 + * NOTES:
1.382 + * The library does no verification that the value passed in is
1.383 + * a valid UTF8 value. The caller must make sure of this in order
1.384 + * to get an encoding that is valid. The library will ultimately
1.385 + * encode this value as it was passed in.
1.386 + * RETURN:
1.387 + * SECSucces on successful addition of the Registration Token Control.
1.388 + * Any other return value indicates an unsuccessful attempt to add the
1.389 + * control.
1.390 + *
1.391 + */
1.392 +extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq,
1.393 + SECItem *value);
1.394 +
1.395 +/*
1.396 + * FUNCTION: CRMF_CertRequestSetAuthenticatorControl
1.397 + * INPUTS:
1.398 + * inCertReq
1.399 + * The Certificate Request to operate on.
1.400 + * value
1.401 + * The UTF8 value that will become the Authenticator Control
1.402 + * for the passed in Certificate Request.
1.403 + * NOTES:
1.404 + * The library does no verification that the value passed in is
1.405 + * a valid UTF8 value. The caller must make sure of this in order
1.406 + * to get an encoding that is valid. The library will ultimately
1.407 + * encode this value as it was passed in.
1.408 + * RETURN:
1.409 + * SECSucces on successful addition of the Authenticator Control.
1.410 + * Any other return value indicates an unsuccessful attempt to add the
1.411 + * control.
1.412 + */
1.413 +extern SECStatus
1.414 + CRMF_CertRequestSetAuthenticatorControl (CRMFCertRequest *inCertReq,
1.415 + SECItem *value);
1.416 +
1.417 +/*
1.418 + * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue
1.419 + * INPUTS:
1.420 + * inPrivKey
1.421 + * This is the private key associated with a certificate that is
1.422 + * being requested. This structure will eventually wind up as
1.423 + * a part of the PKIArchiveOptions Control.
1.424 + * inCACert
1.425 + * This is the certificate for the CA that will be receiving the
1.426 + * certificate request for the private key passed in.
1.427 + * OUTPUT:
1.428 + * A CRMFEncryptedKey that can ultimately be used as part of the
1.429 + * PKIArchiveOptions Control.
1.430 + *
1.431 + * RETURN:
1.432 + * A pointer to a CRMFEncyptedKey. A NULL return value indicates an erro
1.433 + * during the creation of the encrypted key.
1.434 + */
1.435 +extern CRMFEncryptedKey*
1.436 + CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey,
1.437 + CERTCertificate *inCACert);
1.438 +
1.439 +/*
1.440 + * FUNCTION: CRMF_DestroyEncryptedKey
1.441 + * INPUTS:
1.442 + * inEncrKey
1.443 + * The CRMFEncryptedKey to be destroyed.
1.444 + * NOTES:
1.445 + * Frees all memory associated with the CRMFEncryptedKey passed in.
1.446 + * RETURN:
1.447 + * SECSuccess if freeing the memory was successful. Any other return
1.448 + * value indicates an error while freeig the memroy.
1.449 + */
1.450 +extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey);
1.451 +
1.452 +/*
1.453 + * FUNCTION: CRMF_CreatePKIArchiveOptions
1.454 + * INPUTS:
1.455 + * inType
1.456 + * An enumeration value indicating which option for
1.457 + * PKIArchiveOptions to use.
1.458 + * data
1.459 + * A pointer that will be type-cast and de-referenced according
1.460 + * to the table under NOTES.
1.461 + * NOTES:
1.462 + * A table listing what should be passed in as data
1.463 + * ------------------------------------------------
1.464 + *
1.465 + * inType data
1.466 + * ------ ----
1.467 + * crmfEncryptedPrivateKey CRMFEncryptedKey*
1.468 + * crmfKeyGenParameters SECItem*(This needs to be an octet string)
1.469 + * crmfArchiveRemGenPrivKey PRBool*
1.470 + *
1.471 + * RETURN:
1.472 + * A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate
1.473 + * Request. A NULL pointer indicates an error occurred while creating
1.474 + * the CRMFPKIArchiveOptions Structure.
1.475 + */
1.476 +extern CRMFPKIArchiveOptions*
1.477 + CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType inType,
1.478 + void *data);
1.479 +/*
1.480 + * FUNCTION: CRMF_DestroyPKIArchiveOptions
1.481 + * INPUTS:
1.482 + * inArchOpt
1.483 + * A pointer to the CRMFPKIArchiveOptions structure to free.
1.484 + * NOTES:
1.485 + * Will free all memory associated with 'inArchOpt'.
1.486 + * RETURN:
1.487 + * SECSuccess if successful in freeing the memory used by 'inArchOpt'
1.488 + * Any other return value indicates an error while freeing the memory.
1.489 + */
1.490 +extern SECStatus
1.491 + CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt);
1.492 +
1.493 +/*
1.494 + * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions
1.495 + * INPUTS:
1.496 + * inCertReq
1.497 + * The Certificate Request to add the the options to.
1.498 + * inOptions
1.499 + * The Archive Options to add to the Certificate Request.
1.500 + * NOTES:
1.501 + * Adds the PKIArchiveOption to the Certificate Request. This is what
1.502 + * enables Key Escrow to take place through CRMF. The library makes
1.503 + * its own copy of the information.
1.504 + * RETURN:
1.505 + * SECSuccess if successful in adding the ArchiveOptions to the Certificate
1.506 + * request. Any other return value indicates an error when trying to add
1.507 + * the Archive Options to the Certificate Request.
1.508 + */
1.509 +extern SECStatus
1.510 + CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest *inCertReq,
1.511 + CRMFPKIArchiveOptions *inOptions);
1.512 +
1.513 +/*
1.514 + * FUNCTION: CRMF_CertReqMsgGetPOPType
1.515 + * INPUTS:
1.516 + * inCertReqMsg
1.517 + * The Certificate Request Message to operate on.
1.518 + * NOTES:
1.519 + * Returns an enumeration value indicating the method of Proof
1.520 + * of Possession that was used for the passed in Certificate Request
1.521 + * Message.
1.522 + * RETURN:
1.523 + * An enumeration indicating what method for Proof Of Possession is
1.524 + * being used in this Certificate Request Message. Look in the file
1.525 + * crmft.h for the definition of CRMFPOPChoice for the possible return
1.526 + * values.
1.527 + */
1.528 +extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg);
1.529 +
1.530 +/*
1.531 + * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP
1.532 + * INPUT:
1.533 + * InCertReqMsg
1.534 + * The Certificate Request Message to operate on.
1.535 + * NOTES:
1.536 + * This function will set the method of Proof Of Possession to
1.537 + * crmfRAVerified which means the RA has already verified the
1.538 + * requester does possess the private key.
1.539 + * RETURN:
1.540 + * SECSuccess if adding RAVerified to the message is successful.
1.541 + * Any other message indicates an error while trying to add RAVerified
1.542 + * as the Proof of Possession.
1.543 + */
1.544 +extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg);
1.545 +
1.546 +/*
1.547 + * FUNCTION: CRMF_CertReqMsgSetSignaturePOP
1.548 + * INPUT:
1.549 + * inCertReqMsg
1.550 + * The Certificate Request Message to add the SignaturePOP to.
1.551 + * inPrivKey
1.552 + * The Private Key which corresponds to the the Certificate Request
1.553 + * Message.
1.554 + * inPubKey
1.555 + * The Public Key which corresponds to the Private Key passed in.
1.556 + * inCertForInput
1.557 + * A Certificate that in the future may be used to create
1.558 + * POPOSigningKeyInput.
1.559 + * fn
1.560 + * A callback for retrieving a password which may be used in the
1.561 + * future to generate POPOSigningKeyInput.
1.562 + * arg
1.563 + * An opaque pointer that would be passed to fn whenever it is
1.564 + * called.
1.565 + * NOTES:
1.566 + * Adds Proof Of Possession to the CertRequest using the signature field
1.567 + * of the ProofOfPossession field. NOTE: In order to use this option,
1.568 + * the certificate template must contain the publicKey at the very minimum.
1.569 + *
1.570 + * If you don't want the function to generate POPOSigningKeyInput, then
1.571 + * make sure the cert template already contains the subject and public key
1.572 + * values. Currently creating POPOSigningKeyInput is not supported, so
1.573 + * a Message passed to this function must have the publicKey and the subject
1.574 + * as part of the template
1.575 + *
1.576 + * This will take care of creating the entire POPOSigningKey structure
1.577 + * that will become part of the message.
1.578 + *
1.579 + * inPrivKey is the key to be used in the signing operation when creating
1.580 + * POPOSigningKey structure. This should be the key corresponding to
1.581 + * the certificate being requested.
1.582 + *
1.583 + * inCertForInput will be used if POPOSigningKeyInput needs to be generated.
1.584 + * It will be used in generating the authInfo.sender field. If the parameter
1.585 + * is not passed in then authInfo.publicKeyMAC will be generated instead.
1.586 + * If passed in, this certificate needs to be a valid certificate.
1.587 + *
1.588 + * The last 3 arguments are for future compatibility in case we ever want to
1.589 + * support generating POPOSigningKeyInput. Pass in NULL for all 3 if you
1.590 + * definitely don't want the function to even try to generate
1.591 + * POPOSigningKeyInput. If you try to use POPOSigningKeyInput, the function
1.592 + * will fail.
1.593 + *
1.594 + * RETURN:
1.595 + * SECSuccess if adding the Signature Proof Of Possession worked.
1.596 + * Any other return value indicates an error in trying to add
1.597 + * the Signature Proof Of Possession.
1.598 + */
1.599 +extern SECStatus
1.600 + CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg *inCertReqMsg,
1.601 + SECKEYPrivateKey *inPrivKey,
1.602 + SECKEYPublicKey *inPubKey,
1.603 + CERTCertificate *inCertForInput,
1.604 + CRMFMACPasswordCallback fn,
1.605 + void *arg);
1.606 +
1.607 +/*
1.608 + * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP
1.609 + * INPUTS:
1.610 + * inCertReqMsg
1.611 + * The Certificate Request Message to operate on.
1.612 + * inKeyChoice
1.613 + * An enumeration indicating which POPOPrivKey Choice to use
1.614 + * in constructing the KeyEnciphermentPOP.
1.615 + * subseqMess
1.616 + * This parameter must be provided iff inKeyChoice is
1.617 + * crmfSubsequentMessage. This details how the RA is to respond
1.618 + * in order to perform Proof Of Possession. Look in crmft.h under
1.619 + * the definition of CRMFSubseqMessOptions for possible values.
1.620 + * encPrivKey
1.621 + * This parameter only needs to be provided if inKeyChoice is
1.622 + * crmfThisMessage. The item should contain the encrypted private
1.623 + * key.
1.624 + *
1.625 + * NOTES:
1.626 + * Adds Proof Of Possession using the keyEncipherment field of
1.627 + * ProofOfPossession.
1.628 + *
1.629 + * The function looks at the the inKeyChoice parameter and interprets it in
1.630 + * in the following manner.
1.631 + *
1.632 + * If a parameter is not mentioned under interpretation, the function will not
1.633 + * look at its value when implementing that case.
1.634 + *
1.635 + * inKeyChoice Interpretation
1.636 + * ----------- --------------
1.637 + * crmfThisMessage This options requires that the encrypted private key
1.638 + * be included in the thisMessage field of POPOPrivKey.
1.639 + * We don't support this yet, so any clients who want
1.640 + * to use this feature have to implement a wrapping
1.641 + * function and agree with the server on how to properly
1.642 + * wrap the key. That encrypted key must be passed in
1.643 + * as the encPrivKey parameter.
1.644 + *
1.645 + * crmfSubequentMessage Must pass in a value for subseqMess. The value must
1.646 + * be either CRMFEncrCert or CRMFChallengeResp. The
1.647 + * parameter encPrivKey will not be looked at in this
1.648 + * case.
1.649 + *
1.650 + * crmfDHMAC This is not a valid option for this function. Passing
1.651 + * in this value will result in the function returning
1.652 + * SECFailure.
1.653 + * RETURN:
1.654 + * SECSuccess if adding KeyEnciphermentPOP was successful. Any other return
1.655 + * value indicates an error in adding KeyEnciphermentPOP.
1.656 + */
1.657 +extern SECStatus
1.658 + CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg *inCertReqMsg,
1.659 + CRMFPOPOPrivKeyChoice inKeyChoice,
1.660 + CRMFSubseqMessOptions subseqMess,
1.661 + SECItem *encPrivKey);
1.662 +
1.663 +/*
1.664 + * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP
1.665 + * INPUTS:
1.666 + * inCertReqMsg
1.667 + * The Certificate Request Message to operate on.
1.668 + * inKeyChoice
1.669 + * An enumeration indicating which POPOPrivKey Choice to use
1.670 + * in constructing the KeyAgreementPOP.
1.671 + * subseqMess
1.672 + * This parameter must be provided iff inKeyChoice is
1.673 + * crmfSubsequentMessage. This details how the RA is to respond
1.674 + * in order to perform Proof Of Possession. Look in crmft.h under
1.675 + * the definition of CRMFSubseqMessOptions for possible values.
1.676 + * encPrivKey
1.677 + * This parameter only needs to be provided if inKeyChoice is
1.678 + * crmfThisMessage. The item should contain the encrypted private
1.679 + * key.
1.680 + * Adds Proof Of Possession using the keyAgreement field of
1.681 + * ProofOfPossession.
1.682 + *
1.683 + * The function looks at the the inKeyChoice parameter and interprets it in
1.684 + * in the following manner.
1.685 + *
1.686 + * If a parameter is not mentioned under interpretation, the function will not
1.687 + * look at its value when implementing that case.
1.688 + *
1.689 + * inKeyChoice Interpretation
1.690 + * ----------- --------------
1.691 + * crmfThisMessage This options requires that the encrypted private key
1.692 + * be included in the thisMessage field of POPOPrivKey.
1.693 + * We don't support this yet, so any clients who want
1.694 + * to use this feature have to implement a wrapping
1.695 + * function and agree with the server on how to properly
1.696 + * wrap the key. That encrypted key must be passed in
1.697 + * as the encPrivKey parameter.
1.698 + *
1.699 + * crmfSubequentMessage Must pass in a value for subseqMess. The value must
1.700 + * be either crmfEncrCert or crmfChallengeResp. The
1.701 + * parameter encPrivKey will not be looked at in this
1.702 + * case.
1.703 + *
1.704 + * crmfDHMAC This option is not supported.
1.705 + */
1.706 +extern SECStatus
1.707 + CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg *inCertReqMsg,
1.708 + CRMFPOPOPrivKeyChoice inKeyChoice,
1.709 + CRMFSubseqMessOptions subseqMess,
1.710 + SECItem *encPrivKey);
1.711 +
1.712 +/*
1.713 + * FUNCTION: CRMF_CreateCertReqMsgFromDER
1.714 + * INPUTS:
1.715 + * buf
1.716 + * A buffer to the DER-encoded Certificate Request Message.
1.717 + * len
1.718 + * The length in bytes of the buffer 'buf'
1.719 + * NOTES:
1.720 + * This function passes the buffer to the ASN1 decoder and creates a
1.721 + * CRMFCertReqMsg structure. Do not try adding any fields to a message
1.722 + * returned from this function. Specifically adding more Controls or
1.723 + * Extensions may cause your program to crash.
1.724 + *
1.725 + * RETURN:
1.726 + * A pointer to the Certificate Request Message structure. A NULL return
1.727 + * value indicates the library was unable to parse the DER.
1.728 + */
1.729 +extern CRMFCertReqMsg* CRMF_CreateCertReqMsgFromDER(const char *buf, long len);
1.730 +
1.731 +/*
1.732 + * FUNCTION: CRMF_CreateCertReqMessagesFromDER
1.733 + * INPUTS:
1.734 + * buf
1.735 + * A buffer to the DER-encoded Certificate Request Messages.
1.736 + * len
1.737 + * The length in bytes of buf
1.738 + * NOTES:
1.739 + * This function passes the buffer to the ASN1 decoder and creates a
1.740 + * CRMFCertReqMessages structure. Do not try adding any fields to a message
1.741 + * derived from this function. Specifically adding more Controls or
1.742 + * Extensions may cause your program to crash.
1.743 + * The user must call CRMF_DestroyCertReqMessages after the return value is
1.744 + * no longer needed, ie when all individual messages have been extracted.
1.745 + *
1.746 + * RETURN:
1.747 + * A pointer to the Certificate Request Messages structure. A NULL return
1.748 + * value indicates the library was unable to parse the DER.
1.749 + */
1.750 +extern CRMFCertReqMessages*
1.751 + CRMF_CreateCertReqMessagesFromDER(const char *buf, long len);
1.752 +
1.753 +/*
1.754 + * FUNCTION: CRMF_DestroyCertReqMessages
1.755 + * INPUTS
1.756 + * inCertReqMsgs
1.757 + * The Messages to destroy.
1.758 + * RETURN:
1.759 + * SECSuccess if freeing the memory was done successfully. Any other
1.760 + * return value indicates an error in freeing up memory.
1.761 + */
1.762 +extern SECStatus
1.763 + CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs);
1.764 +
1.765 +/*
1.766 + * FUNCTION: CRMF_CertReqMessagesGetNumMessages
1.767 + * INPUTS:
1.768 + * inCertReqMsgs
1.769 + * The Request Messages to operate on.
1.770 + * RETURN:
1.771 + * The number of messages contained in the in the Request Messages
1.772 + * strucure.
1.773 + */
1.774 +extern int
1.775 + CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs);
1.776 +
1.777 +/*
1.778 + * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex
1.779 + * INPUTS:
1.780 + * inReqMsgs
1.781 + * The Certificate Request Messages to operate on.
1.782 + * index
1.783 + * The index of the single message the user wants a copy of.
1.784 + * NOTES:
1.785 + * This function returns a copy of the request messages stored at the
1.786 + * index corresponding to the parameter 'index'. Indexing of the messages
1.787 + * is done in the same manner as a C array. Meaning the valid index are
1.788 + * 0...numMessages-1. User must call CRMF_DestroyCertReqMsg when done using
1.789 + * the return value of this function.
1.790 + *
1.791 + * RETURN:
1.792 + * SECSuccess if copying the message at the requested index was successful.
1.793 + * Any other return value indicates an invalid index or error while copying
1.794 + * the single request message.
1.795 + */
1.796 +extern CRMFCertReqMsg*
1.797 + CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs,
1.798 + int index);
1.799 +
1.800 +
1.801 +/*
1.802 + * FUNCTION: CRMF_CertReqMsgGetID
1.803 + * INPUTS:
1.804 + * inCertReqMsg
1.805 + * The Certificate Request Message to get the ID from.
1.806 + * destID
1.807 + * A pointer to where the library can place the ID of the Message.
1.808 + * RETURN:
1.809 + * SECSuccess if the function was able to retrieve the ID and place it
1.810 + * at *destID. Any other return value indicates an error meaning the value
1.811 + * in *destId is un-reliable and should not be used by the caller of this
1.812 + * function.
1.813 + *
1.814 + */
1.815 +extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg,
1.816 + long *destID);
1.817 +
1.818 +/*
1.819 + * FUNCTION: CRMF_DoesRequestHaveField
1.820 + * INPUTS:
1.821 + * inCertReq
1.822 + * The Certificate Request to operate on.
1.823 + * inField
1.824 + * An enumeration indicating which filed of the certificate template
1.825 + * to look for.
1.826 + * NOTES:
1.827 + * All the fields in a certificate template are optional. This function
1.828 + * checks to see if the requested field is present. Look in crmft.h at the
1.829 + * definition of CRMFCertTemplateField for possible values for possible
1.830 + * querying.
1.831 + *
1.832 + * RETURN:
1.833 + * PR_TRUE iff the field corresponding to 'inField' has been specified as part
1.834 + * of 'inCertReq'
1.835 + * PR_FALSE iff the field corresponding to 'inField' has not been speicified
1.836 + * as part of 'inCertReq'
1.837 + *
1.838 + */
1.839 +extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest *inCertReq,
1.840 + CRMFCertTemplateField inField);
1.841 +
1.842 +/*
1.843 + * FUNCTION: CRMF_CertReqMsgGetCertRequest
1.844 + * INPUTS:
1.845 + * inCertReqMsg
1.846 + * The Certificate Request Message to operate on.
1.847 + * NOTES:
1.848 + * This function returns a copy of the Certificate Request to the user.
1.849 + * The user can keep adding to this request and then making it a part
1.850 + * of another message. After the user no longer wants to use the
1.851 + * returned request, the user must call CRMF_DestroyCertRequest and
1.852 + * pass it the request returned by this function.
1.853 + * RETURN:
1.854 + * A pointer to a copy of the certificate request contained by the message.
1.855 + * A NULL return value indicates an error occurred while copying the
1.856 + * certificate request.
1.857 + */
1.858 +extern CRMFCertRequest *
1.859 + CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg);
1.860 +
1.861 +/*
1.862 + * FUNCTION: CRMF_CertRequestGetCertTemplateVersion
1.863 + * INPUTS:
1.864 + * inCertReq
1.865 + * The Certificate Request to operate on.
1.866 + * version
1.867 + * A pointer to where the library can store the version contatined
1.868 + * in the certificate template within the certifcate request.
1.869 + * RETURN:
1.870 + * SECSuccess if the Certificate template contains the version field. In
1.871 + * this case, *version will hold the value of the certificate template
1.872 + * version.
1.873 + * SECFailure indicates that version field was not present as part of
1.874 + * of the certificate template.
1.875 + */
1.876 +extern SECStatus
1.877 + CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq,
1.878 + long *version);
1.879 +
1.880 +/*
1.881 + * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber
1.882 + * INPUTS:
1.883 + * inCertReq
1.884 + * The certificate request to operate on.
1.885 + * serialNumber
1.886 + * A pointer where the library can put the serial number contained
1.887 + * in the certificate request's certificate template.
1.888 + * RETURN:
1.889 + * If a serial number exists in the CertTemplate of the request, the function
1.890 + * returns SECSuccess and the value at *serialNumber contains the serial
1.891 + * number.
1.892 + * If no serial number is present, then the function returns SECFailure and
1.893 + * the value at *serialNumber is un-changed.
1.894 + */
1.895 +extern SECStatus
1.896 + CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq,
1.897 + long *serialNumber);
1.898 +
1.899 +/*
1.900 + * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg
1.901 + * INPUT:
1.902 + * inCertReq
1.903 + * The Certificate Request to operate on.
1.904 + * destAlg
1.905 + * A Pointer to where the library can place a copy of the signing alg
1.906 + * used in the cert request's cert template.
1.907 + * RETURN:
1.908 + * If the signingAlg is present in the CertRequest's CertTemplate, then
1.909 + * the function returns SECSuccess and places a copy of sigingAlg in
1.910 + * *destAlg.
1.911 + * If no signingAlg is present, then the function returns SECFailure and
1.912 + * the value at *destAlg is un-changed
1.913 + */
1.914 +extern SECStatus
1.915 + CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq,
1.916 + SECAlgorithmID *destAlg);
1.917 +/*
1.918 + * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer
1.919 + * INPUTS:
1.920 + * inCertReq
1.921 + * The Certificate Request to operate on.
1.922 + * destIssuer
1.923 + * A pointer to where the library can place a copy of the cert
1.924 + * request's cert template issuer field.
1.925 + * RETURN:
1.926 + * If the issuer is present in the cert request cert template, the function
1.927 + * returns SECSuccess and places a copy of the issuer in *destIssuer.
1.928 + * If there is no issuer present, the function returns SECFailure and the
1.929 + * value at *destIssuer is unchanged.
1.930 + */
1.931 +extern SECStatus
1.932 + CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq,
1.933 + CERTName *destIssuer);
1.934 +
1.935 +/*
1.936 + * FUNCTION: CRMF_CertRequestGetCertTemplateValidity
1.937 + * INPUTS:
1.938 + * inCertReq
1.939 + * The Certificate Request to operate on.
1.940 + * destValdity
1.941 + * A pointer to where the library can place a copy of the validity
1.942 + * info in the cert request cert template.
1.943 + * NOTES:
1.944 + * Pass the pointer to
1.945 + * RETURN:
1.946 + * If there is an OptionalValidity field, the function will return SECSuccess
1.947 + * and place the appropriate values in *destValidity->notBefore and
1.948 + * *destValidity->notAfter. (Each field is optional, but at least one will
1.949 + * be present if the function returns SECSuccess)
1.950 + *
1.951 + * If there is no OptionalValidity field, the function will return SECFailure
1.952 + * and the values at *destValidity will be un-changed.
1.953 + */
1.954 +extern SECStatus
1.955 + CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq,
1.956 + CRMFGetValidity *destValidity);
1.957 +/*
1.958 + * FUNCTION: CRMF_DestroyGetValidity
1.959 + * INPUTS:
1.960 + * inValidity
1.961 + * A pointer to the memroy to be freed.
1.962 + * NOTES:
1.963 + * The function will free the memory allocated by the function
1.964 + * CRMF_CertRequestGetCertTemplateValidity. That means only memory pointed
1.965 + * to within the CRMFGetValidity structure. Since
1.966 + * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the
1.967 + * structure passed into it, it will not free it. Meaning this function will
1.968 + * free the memory at inValidity->notBefore and inValidity->notAfter, but not
1.969 + * the memory directly at inValdity.
1.970 + *
1.971 + * RETURN:
1.972 + * SECSuccess if freeing the memory was successful. Any other return value
1.973 + * indicates an error while freeing the memory.
1.974 + */
1.975 +extern SECStatus
1.976 + CRMF_DestroyGetValidity(CRMFGetValidity *inValidity);
1.977 +
1.978 +/*
1.979 + * FUNCTION: CRMF_CertRequestGetCertTemplateSubject
1.980 + * INPUTS:
1.981 + * inCertReq
1.982 + * The Certificate Request to operate on.
1.983 + * destSubject
1.984 + * A pointer to where the library can place a copy of the subject
1.985 + * contained in the request's cert template.
1.986 + * RETURN:
1.987 + * If there is a subject in the CertTemplate, then the function returns
1.988 + * SECSuccess and a copy of the subject is placed in *destSubject.
1.989 + *
1.990 + * If there is no subject, the function returns SECFailure and the values at
1.991 + * *destSubject is unchanged.
1.992 + */
1.993 +extern SECStatus
1.994 + CRMF_CertRequestGetCertTemplateSubject (CRMFCertRequest *inCertReq,
1.995 + CERTName *destSubject);
1.996 +
1.997 +/*
1.998 + * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey
1.999 + * INPUTS:
1.1000 + * inCertReq
1.1001 + * The Cert request to operate on.
1.1002 + * destPublicKey
1.1003 + * A pointer to where the library can place a copy of the request's
1.1004 + * cert template public key.
1.1005 + * RETURN:
1.1006 + * If there is a publicKey parameter in the CertRequest, the function returns
1.1007 + * SECSuccess, and places a copy of the publicKey in *destPublicKey.
1.1008 + *
1.1009 + * If there is no publicKey, the function returns SECFailure and the value
1.1010 + * at *destPublicKey is un-changed.
1.1011 + */
1.1012 +extern SECStatus
1.1013 + CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq,
1.1014 + CERTSubjectPublicKeyInfo *destPublicKey);
1.1015 +
1.1016 +/*
1.1017 + * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID
1.1018 + * INPUTS:
1.1019 + * inCertReq
1.1020 + * The Cert request to operate on.
1.1021 + * destIssuerUID
1.1022 + * A pointer to where the library can store a copy of the request's
1.1023 + * cert template destIssuerUID.
1.1024 + *
1.1025 + * NOTES:
1.1026 + * destIssuerUID is a bit string and will be returned in a SECItem as
1.1027 + * a bit string. Meaning the len field contains the number of valid bits as
1.1028 + * opposed to the number of bytes allocated.
1.1029 + *
1.1030 + * RETURN:
1.1031 + * If the CertTemplate has an issuerUID, the function returns SECSuccess and
1.1032 + * places a copy of the issuerUID in *destIssuerUID.
1.1033 + *
1.1034 + * If there is no issuerUID, the function returns SECFailure and the value
1.1035 + * *destIssuerUID is unchanged.
1.1036 + */
1.1037 +extern SECStatus
1.1038 + CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq,
1.1039 + SECItem *destIssuerUID);
1.1040 +
1.1041 +/*
1.1042 + * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID
1.1043 + * inCertReq
1.1044 + * The Cert request to operate on.
1.1045 + * destSubjectUID
1.1046 + * A pointer to where the library can store a copy of the request's
1.1047 + * cert template destIssuerUID.
1.1048 + *
1.1049 + * NOTES:
1.1050 + * destSubjectUID is a bit string and will be returned in a SECItem as
1.1051 + * a bit string. Meaning the len field contains the number of valid bits as
1.1052 + * opposed to the number of bytes allocated.
1.1053 + *
1.1054 + * RETURN:
1.1055 + * If the CertTemplate has an issuerUID, the function returns SECSuccess and
1.1056 + * places a copy of the issuerUID in *destIssuerUID.
1.1057 + *
1.1058 + * If there is no issuerUID, the function returns SECSuccess and the value
1.1059 + * *destIssuerUID is unchanged.
1.1060 + */
1.1061 +extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq,
1.1062 + SECItem *destSubjectUID);
1.1063 +
1.1064 +/*
1.1065 + * FUNCTION: CRMF_CertRequestGetNumberOfExtensions
1.1066 + * INPUTS:
1.1067 + * inCertReq
1.1068 + * The cert request to operate on.
1.1069 + * RETURN:
1.1070 + * Returns the number of extensions contained by the Cert Request.
1.1071 + */
1.1072 +extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq);
1.1073 +
1.1074 +/*
1.1075 + * FUNCTION: CRMF_CertRequestGetExtensionAtIndex
1.1076 + * INPUTS:
1.1077 + * inCertReq
1.1078 + * The Certificate request to operate on.
1.1079 + * index
1.1080 + * The index of the extension array whihc the user wants to access.
1.1081 + * NOTES:
1.1082 + * This function retrieves the extension at the index corresponding to the
1.1083 + * parameter "index" indicates. Indexing is done like a C array.
1.1084 + * (0 ... numElements-1)
1.1085 + *
1.1086 + * Call CRMF_DestroyCertExtension when done using the return value.
1.1087 + *
1.1088 + * RETURN:
1.1089 + * A pointer to a copy of the extension at the desired index. A NULL
1.1090 + * return value indicates an invalid index or an error while copying
1.1091 + * the extension.
1.1092 + */
1.1093 +extern CRMFCertExtension *
1.1094 + CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq,
1.1095 + int index);
1.1096 +/*
1.1097 + * FUNCTION: CRMF_CertExtensionGetOidTag
1.1098 + * INPUTS:
1.1099 + * inExtension
1.1100 +
1.1101 + * The extension to operate on.
1.1102 + * RETURN:
1.1103 + * Returns the SECOidTag associated with the cert extension passed in.
1.1104 + */
1.1105 +extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension);
1.1106 +
1.1107 +/*
1.1108 + * FUNCTION: CRMF_CertExtensionGetIsCritical
1.1109 + * INPUT:
1.1110 + * inExt
1.1111 + * The cert extension to operate on.
1.1112 + *
1.1113 + * RETURN:
1.1114 + * PR_TRUE if the extension is critical.
1.1115 + * PR_FALSE if the extension is not critical.
1.1116 + */
1.1117 +extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt);
1.1118 +
1.1119 +/*
1.1120 + * FUNCTION: CRMF_CertExtensionGetValue
1.1121 + * INPUT:
1.1122 + * inExtension
1.1123 + * The extension to operate on.
1.1124 + * NOTES:
1.1125 + * Caller is responsible for freeing the memory associated with the return
1.1126 + * value. Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return
1.1127 + * value.
1.1128 + *
1.1129 + * RETURN:
1.1130 + * A pointer to an item containig the value for the certificate extension.
1.1131 + * A NULL return value indicates an error in copying the information.
1.1132 + */
1.1133 +extern SECItem* CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension);
1.1134 +
1.1135 +/*
1.1136 + * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey
1.1137 + * INPUTS:
1.1138 + * inCertReqMsg
1.1139 + * The certificate request message to operate on.
1.1140 + * destKey
1.1141 + * A pointer to where the library can place a pointer to
1.1142 + * a copy of the Proof Of Possession Signing Key used
1.1143 + * by the message.
1.1144 + *
1.1145 + * RETURN:
1.1146 + * Get the POPOSigningKey associated with this CRMFCertReqMsg.
1.1147 + * If the CertReqMsg does not have a pop, the function returns
1.1148 + * SECFailure and the value at *destKey is un-changed..
1.1149 + *
1.1150 + * If the CertReqMsg does have a pop, then the CertReqMsg's
1.1151 + * POPOSigningKey will be placed at *destKey.
1.1152 + */
1.1153 +extern SECStatus
1.1154 + CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg *inCertReqMsg,
1.1155 + CRMFPOPOSigningKey **destKey);
1.1156 +
1.1157 +/*
1.1158 + * FUNCTION: CRMF_DestroyPOPOSigningKey
1.1159 + * INPUTS:
1.1160 + * inKey
1.1161 + * The signing key to free.
1.1162 + *
1.1163 + * RETURN:
1.1164 + * SECSuccess if freeing the memory was successful. Any other return value
1.1165 + * indicates an error while freeing memory.
1.1166 + */
1.1167 +extern SECStatus CRMF_DestroyPOPOSigningKey (CRMFPOPOSigningKey *inKey);
1.1168 +
1.1169 +/*
1.1170 + * FUNCTION: CRMF_POPOSigningKeyGetAlgID
1.1171 + * INPUTS:
1.1172 + * inSignKey
1.1173 + * The Signing Key to operate on.
1.1174 + * RETURN:
1.1175 + * Return the algorithmID used by the CRMFPOPOSigningKey. User must
1.1176 + * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the
1.1177 + * return value.
1.1178 + */
1.1179 +extern SECAlgorithmID*
1.1180 + CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey);
1.1181 +
1.1182 +/*
1.1183 + * FUNCTION: CRMF_POPOSigningKeyGetSignature
1.1184 + * INPUTS:
1.1185 + * inSignKey
1.1186 + * The Signing Key to operate on.
1.1187 + *
1.1188 + * RETURN:
1.1189 + * Get the actual signature stored away in the CRMFPOPOSigningKey. SECItem
1.1190 + * returned is a BIT STRING, so the len field is the number of bits as opposed
1.1191 + * to the total number of bytes allocatd. User must call
1.1192 + * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value.
1.1193 + */
1.1194 +extern SECItem* CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey);
1.1195 +
1.1196 +/*
1.1197 + * FUNCTION: CRMF_POPOSigningKeyGetInput
1.1198 + * INPUTS:
1.1199 + * inSignKey
1.1200 + * The Signing Key to operate on.
1.1201 + * NOTES:
1.1202 + * This function will return the der encoded input that was read in while
1.1203 + * decoding. The API does not support this option when creating, so you
1.1204 + * cannot add this field.
1.1205 + *
1.1206 + * RETURN:
1.1207 + * Get the poposkInput that is part of the of the POPOSigningKey. If the
1.1208 + * optional field is not part of the POPOSigningKey, the function returns
1.1209 + * NULL.
1.1210 + *
1.1211 + * If the optional field is part of the POPOSingingKey, the function will
1.1212 + * return a copy of the der encoded poposkInput.
1.1213 + */
1.1214 +extern SECItem* CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey);
1.1215 +
1.1216 +/*
1.1217 + * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment
1.1218 + * INPUTS:
1.1219 + * inCertReqMsg
1.1220 + * The certificate request message to operate on.
1.1221 + * destKey
1.1222 + * A pointer to where the library can place a pointer to a
1.1223 + * copy of the POPOPrivKey representing Key Encipherment
1.1224 + * Proof of Possession.
1.1225 + *NOTES:
1.1226 + * This function gets the POPOPrivKey associated with this CRMFCertReqMsg
1.1227 + * for Key Encipherment.
1.1228 + *
1.1229 + * RETURN:
1.1230 + * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the
1.1231 + * function returns SECFailure and the value at *destKey is un-changed.
1.1232 + *
1.1233 + * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the
1.1234 + * function returns SECSuccess and places the POPOPrivKey representing the
1.1235 + * Key Encipherment Proof Of Possessin at *destKey.
1.1236 + */
1.1237 +extern SECStatus
1.1238 + CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg *inCertReqMsg,
1.1239 + CRMFPOPOPrivKey **destKey);
1.1240 +
1.1241 +/*
1.1242 + * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement
1.1243 + * INPUTS:
1.1244 + * inCertReqMsg
1.1245 + * The certificate request message to operate on.
1.1246 + * destKey
1.1247 + * A pointer to where the library can place a pointer to a
1.1248 + * copy of the POPOPrivKey representing Key Agreement
1.1249 + * Proof of Possession.
1.1250 + * NOTES:
1.1251 + * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for
1.1252 + * Key Agreement.
1.1253 + *
1.1254 + * RETURN:
1.1255 + * If the CertReqMsg used Key Agreement for Proof Of Possession, the
1.1256 + * function returns SECSuccess and the POPOPrivKey for Key Agreement
1.1257 + * is placed at *destKey.
1.1258 + *
1.1259 + * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the
1.1260 + * function return SECFailure and the value at *destKey is unchanged.
1.1261 + */
1.1262 +extern SECStatus
1.1263 + CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg *inCertReqMsg,
1.1264 + CRMFPOPOPrivKey **destKey);
1.1265 +
1.1266 +/*
1.1267 + * FUNCTION: CRMF_DestroyPOPOPrivKey
1.1268 + * INPUTS:
1.1269 + * inPrivKey
1.1270 + * The POPOPrivKey to destroy.
1.1271 + * NOTES:
1.1272 + * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or
1.1273 + * CRMF_GetPOPKeyAgreement.
1.1274 + *
1.1275 + * RETURN:
1.1276 + * SECSuccess on successful destruction of the POPOPrivKey.
1.1277 + * Any other return value indicates an error in freeing the
1.1278 + * memory.
1.1279 + */
1.1280 +extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);
1.1281 +
1.1282 +/*
1.1283 + * FUNCTION: CRMF_POPOPrivKeyGetChoice
1.1284 + * INPUT:
1.1285 + * inKey
1.1286 + * The POPOPrivKey to operate on.
1.1287 + * RETURN:
1.1288 + * Returns which choice was used in constructing the POPPOPrivKey. Look at
1.1289 + * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return
1.1290 + * values.
1.1291 + */
1.1292 +extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey);
1.1293 +
1.1294 +/*
1.1295 + * FUNCTION: CRMF_POPOPrivKeyGetThisMessage
1.1296 + * INPUTS:
1.1297 + * inKey
1.1298 + * The POPOPrivKey to operate on.
1.1299 + * destString
1.1300 + * A pointer to where the library can place a copy of the This Message
1.1301 + * field stored in the POPOPrivKey
1.1302 + *
1.1303 + * RETURN:
1.1304 + * Returns the field thisMessage from the POPOPrivKey.
1.1305 + * If the POPOPrivKey did not use the field thisMessage, the function
1.1306 + * returns SECFailure and the value at *destString is unchanged.
1.1307 + *
1.1308 + * If the POPOPrivKey did use the field thisMessage, the function returns
1.1309 + * SECSuccess and the BIT STRING representing thisMessage is placed
1.1310 + * at *destString. BIT STRING representation means the len field is the
1.1311 + * number of valid bits as opposed to the total number of bytes.
1.1312 + */
1.1313 +extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey *inKey,
1.1314 + SECItem *destString);
1.1315 +
1.1316 +/*
1.1317 + * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess
1.1318 + * INPUTS:
1.1319 + * inKey
1.1320 + * The POPOPrivKey to operate on.
1.1321 + * destOpt
1.1322 + * A pointer to where the library can place the value of the
1.1323 + * Subsequent Message option used by POPOPrivKey.
1.1324 + *
1.1325 + * RETURN:
1.1326 + * Retrieves the field subsequentMessage from the POPOPrivKey.
1.1327 + * If the POPOPrivKey used the subsequentMessage option, the function
1.1328 + * returns SECSuccess and places the appropriate enumerated value at
1.1329 + * *destMessageOption.
1.1330 + *
1.1331 + * If the POPOPrivKey did not use the subsequenMessage option, the function
1.1332 + * returns SECFailure and the value at *destOpt is un-changed.
1.1333 + */
1.1334 +extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey *inKey,
1.1335 + CRMFSubseqMessOptions *destOpt);
1.1336 +
1.1337 +/*
1.1338 + * FUNCTION: CRMF_POPOPrivKeyGetDHMAC
1.1339 + * INPUTS:
1.1340 + * inKey
1.1341 + * The POPOPrivKey to operate on.
1.1342 + * destMAC
1.1343 + * A pointer to where the library can place a copy of the dhMAC
1.1344 + * field of the POPOPrivKey.
1.1345 + *
1.1346 + * NOTES:
1.1347 + * Returns the field dhMAC from the POPOPrivKey. The populated SECItem
1.1348 + * is in BIT STRING format.
1.1349 + *
1.1350 + * RETURN:
1.1351 + * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess
1.1352 + * and the BIT STRING for dhMAC will be placed at *destMAC. The len field in
1.1353 + * destMAC (ie destMAC->len) will be the valid number of bits as opposed to
1.1354 + * the number of allocated bytes.
1.1355 + *
1.1356 + * If the POPOPrivKey did not use the dhMAC option, the function returns
1.1357 + * SECFailure and the value at *destMAC is unchanged.
1.1358 + *
1.1359 + */
1.1360 +extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey,
1.1361 + SECItem *destMAC);
1.1362 +
1.1363 +/*
1.1364 + * FUNCTION: CRMF_CertRequestGetNumControls
1.1365 + * INPUTS:
1.1366 + * inCertReq
1.1367 + * The Certificate Request to operate on.
1.1368 + * RETURN:
1.1369 + * Returns the number of Controls registered with this CertRequest.
1.1370 + */
1.1371 +extern int CRMF_CertRequestGetNumControls (CRMFCertRequest *inCertReq);
1.1372 +
1.1373 +/*
1.1374 + * FUNCTION: CRMF_CertRequestGetControlAtIndex
1.1375 + * INPUTS:
1.1376 + * inCertReq
1.1377 + * The certificate request to operate on.
1.1378 + * index
1.1379 + * The index of the control the user wants a copy of.
1.1380 + * NOTES:
1.1381 + * Function retrieves the Control at located at index. The Controls
1.1382 + * are numbered like a traditional C array (0 ... numElements-1)
1.1383 + *
1.1384 + * RETURN:
1.1385 + * Returns a copy of the control at the index specified. This is a copy
1.1386 + * so the user must call CRMF_DestroyControl after the return value is no
1.1387 + * longer needed. A return value of NULL indicates an error while copying
1.1388 + * the control or that the index was invalid.
1.1389 + */
1.1390 +extern CRMFControl*
1.1391 + CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq,
1.1392 + int index);
1.1393 +
1.1394 +/*
1.1395 + * FUNCTION: CRMF_DestroyControl
1.1396 + * INPUTS:
1.1397 + * inControl
1.1398 + * The Control to destroy.
1.1399 + * NOTES:
1.1400 + * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex.
1.1401 + *
1.1402 + * RETURN:
1.1403 + * SECSuccess if freeing the memory was successful. Any other return
1.1404 + * value indicates an error while freeing the memory.
1.1405 + */
1.1406 +extern SECStatus CRMF_DestroyControl(CRMFControl *inControl);
1.1407 +
1.1408 +/*
1.1409 + * FUNCTION: CRMF_ControlGetControlType
1.1410 + * INPUTS:
1.1411 + * inControl
1.1412 + * The control to operate on.
1.1413 + * NOTES:
1.1414 + * The function returns an enumertion which indicates the type of control
1.1415 + * 'inControl'.
1.1416 + *
1.1417 + * RETURN:
1.1418 + * Look in crmft.h at the definition of the enumerated type CRMFControlType
1.1419 + * for the possible return values.
1.1420 + */
1.1421 +extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl);
1.1422 +
1.1423 +/*
1.1424 + * FUNCTION: CRMF_ControlGetRegTokenControlValue
1.1425 + * INPUTS:
1.1426 + * inControl
1.1427 + * The Control to operate on.
1.1428 + * NOTES:
1.1429 + * The user must call SECITEM_FreeItem passing in the return value
1.1430 + * after the returnvalue is no longer needed.
1.1431 +
1.1432 + * RETURN:
1.1433 + * Return the value for a Registration Token Control.
1.1434 + * The SECItem returned should be in UTF8 format. A NULL
1.1435 + * return value indicates there was no Registration Control associated
1.1436 + * with the Control.
1.1437 + * (This library will not verify format. It assumes the client properly
1.1438 + * formatted the strings when adding it or the message decoded was properly
1.1439 + * formatted. The library will just give back the bytes it was given.)
1.1440 + */
1.1441 +extern SECItem* CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl);
1.1442 +
1.1443 +/*
1.1444 + * FUNCTION: CRMF_ControlGetAuthenticatorControlValue
1.1445 + * INPUTS:
1.1446 + * inControl
1.1447 + * The Control to operate on.
1.1448 + * NOTES:
1.1449 + * The user must call SECITEM_FreeItem passing in the return value
1.1450 + * after the returnvalue is no longer needed.
1.1451 + *
1.1452 + * RETURN:
1.1453 + * Return the value for the Authenticator Control.
1.1454 + * The SECItem returned should be in UTF8 format. A NULL
1.1455 + * return value indicates there was no Authenticator Control associated
1.1456 + * with the CRMFControl..
1.1457 + * (This library will not verify format. It assumes the client properly
1.1458 + * formatted the strings when adding it or the message decoded was properly
1.1459 + * formatted. The library will just give back the bytes it was given.)
1.1460 + */
1.1461 +extern SECItem* CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl);
1.1462 +
1.1463 +/*
1.1464 + * FUNCTION: CRMF_ControlGetPKIArchiveOptions
1.1465 + * INPUTS:inControl
1.1466 + * The Control tooperate on.
1.1467 + * NOTES:
1.1468 + * This function returns a copy of the PKIArchiveOptions. The user must call
1.1469 + * the function CRMF_DestroyPKIArchiveOptions when the return value is no
1.1470 + * longer needed.
1.1471 + *
1.1472 + * RETURN:
1.1473 + * Get the PKIArchiveOptions associated with the Control. A return
1.1474 + * value of NULL indicates the Control was not a PKIArchiveOptions
1.1475 + * Control.
1.1476 + */
1.1477 +extern CRMFPKIArchiveOptions*
1.1478 + CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl);
1.1479 +
1.1480 +/*
1.1481 + * FUNCTION: CMRF_DestroyPKIArchiveOptions
1.1482 + * INPUTS:
1.1483 + * inOptions
1.1484 + * The ArchiveOptions to destroy.
1.1485 + * NOTE:
1.1486 + * Destroy the CRMFPKIArchiveOptions structure.
1.1487 + *
1.1488 + * RETURN:
1.1489 + * SECSuccess if successful in freeing all the memory associated with
1.1490 + * the PKIArchiveOptions. Any other return value indicates an error while
1.1491 + * freeing the PKIArchiveOptions.
1.1492 + */
1.1493 +extern SECStatus
1.1494 + CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions);
1.1495 +
1.1496 +/*
1.1497 + * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType
1.1498 + * INPUTS:
1.1499 + * inOptions
1.1500 + * The PKIArchiveOptions to operate on.
1.1501 + * RETURN:
1.1502 + * Returns the choice used for the PKIArchiveOptions. Look at the definition
1.1503 + * of CRMFPKIArchiveOptionsType in crmft.h for possible return values.
1.1504 + */
1.1505 +extern CRMFPKIArchiveOptionsType
1.1506 + CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions);
1.1507 +
1.1508 +/*
1.1509 + * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey
1.1510 + * INPUTS:
1.1511 + * inOpts
1.1512 + * The PKIArchiveOptions to operate on.
1.1513 + *
1.1514 + * NOTES:
1.1515 + * The user must call CRMF_DestroyEncryptedKey when done using this return
1.1516 + * value.
1.1517 + *
1.1518 + * RETURN:
1.1519 + * Get the encryptedPrivKey field of the PKIArchiveOptions structure.
1.1520 + * A return value of NULL indicates that encryptedPrivKey was not used as
1.1521 + * the choice for this PKIArchiveOptions.
1.1522 + */
1.1523 +extern CRMFEncryptedKey*
1.1524 + CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts);
1.1525 +
1.1526 +/*
1.1527 + * FUNCTION: CRMF_EncryptedKeyGetChoice
1.1528 + * INPUTS:
1.1529 + * inEncrKey
1.1530 + * The EncryptedKey to operate on.
1.1531 + *
1.1532 + * NOTES:
1.1533 + * Get the choice used for representing the EncryptedKey.
1.1534 + *
1.1535 + * RETURN:
1.1536 + * Returns the Choice used in representing the EncryptedKey. Look in
1.1537 + * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return
1.1538 + * values.
1.1539 + */
1.1540 +extern CRMFEncryptedKeyChoice
1.1541 + CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey);
1.1542 +
1.1543 +
1.1544 +/*
1.1545 + * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue
1.1546 + * INPUTS:
1.1547 + * inKey
1.1548 + * The EncryptedKey to operate on.
1.1549 + *
1.1550 + * NOTES:
1.1551 + * The user must call CRMF_DestroyEncryptedValue passing in
1.1552 + * CRMF_GetEncryptedValue's return value.
1.1553 + *
1.1554 + * RETURN:
1.1555 + * A pointer to a copy of the EncryptedValue contained as a member of
1.1556 + * the EncryptedKey.
1.1557 + */
1.1558 +extern CRMFEncryptedValue*
1.1559 + CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey);
1.1560 +
1.1561 +/*
1.1562 + * FUNCTION: CRMF_DestroyEncryptedValue
1.1563 + * INPUTS:
1.1564 + * inEncrValue
1.1565 + * The EncryptedValue to destroy.
1.1566 + *
1.1567 + * NOTES:
1.1568 + * Free up all memory associated with 'inEncrValue'.
1.1569 + *
1.1570 + * RETURN:
1.1571 + * SECSuccess if freeing up the memory associated with the EncryptedValue
1.1572 + * is successful. Any other return value indicates an error while freeing the
1.1573 + * memory.
1.1574 + */
1.1575 +extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue);
1.1576 +
1.1577 +/*
1.1578 + * FUNCTION: CRMF_EncryptedValueGetEncValue
1.1579 + * INPUTS:
1.1580 + * inEncValue
1.1581 + * The EncryptedValue to operate on.
1.1582 + * NOTES:
1.1583 + * Function retrieves the encValue from an EncryptedValue structure.
1.1584 + *
1.1585 + * RETURN:
1.1586 + * A poiner to a SECItem containing the encValue of the EncryptedValue
1.1587 + * structure. The return value is in BIT STRING format, meaning the
1.1588 + * len field of the return structure represents the number of valid bits
1.1589 + * as opposed to the allocated number of bytes.
1.1590 + * ANULL return value indicates an error in copying the encValue field.
1.1591 + */
1.1592 +extern SECItem* CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue);
1.1593 +
1.1594 +/*
1.1595 + * FUNCTION: CRMF_EncryptedValueGetIntendedAlg
1.1596 + * INPUTS
1.1597 + * inEncValue
1.1598 + * The EncryptedValue to operate on.
1.1599 + * NOTES:
1.1600 + * Retrieve the IntendedAlg field from the EncryptedValue structure.
1.1601 + * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1.1602 + * the return value. When present, this alogorithm is the alogrithm for
1.1603 + * which the private key will be used.
1.1604 + *
1.1605 + * RETURN:
1.1606 + * A Copy of the intendedAlg field. A NULL return value indicates the
1.1607 + * optional field was not present in the structure.
1.1608 + */
1.1609 +extern SECAlgorithmID*
1.1610 + CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue *inEncValue);
1.1611 +
1.1612 +
1.1613 +/*
1.1614 + * FUNCTION: CRMF_EncryptedValueGetSymmAlg
1.1615 + * INPUTS
1.1616 + * inEncValue
1.1617 + * The EncryptedValue to operate on.
1.1618 + * NOTES:
1.1619 + * Retrieve the symmAlg field from the EncryptedValue structure.
1.1620 + * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1.1621 + * the return value. When present, this is algorithm used to
1.1622 + * encrypt the encValue of the EncryptedValue.
1.1623 + *
1.1624 + * RETURN:
1.1625 + * A Copy of the symmAlg field. A NULL return value indicates the
1.1626 + * optional field was not present in the structure.
1.1627 + */
1.1628 +extern SECAlgorithmID*
1.1629 + CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue *inEncValue);
1.1630 +
1.1631 +
1.1632 +/*
1.1633 + * FUNCTION: CRMF_EncryptedValueGetKeyAlg
1.1634 + * INPUTS
1.1635 + * inEncValue
1.1636 + * The EncryptedValue to operate on.
1.1637 + * NOTES:
1.1638 + * Retrieve the keyAlg field from the EncryptedValue structure.
1.1639 + * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
1.1640 + * the return value. When present, this is the algorithm used to encrypt
1.1641 + * the symmetric key in the encSymmKey field of the EncryptedValue structure.
1.1642 + *
1.1643 + * RETURN:
1.1644 + * A Copy of the keyAlg field. A NULL return value indicates the
1.1645 + * optional field was not present in the structure.
1.1646 + */
1.1647 +extern SECAlgorithmID*
1.1648 + CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue);
1.1649 +
1.1650 +/*
1.1651 + * FUNCTION: CRMF_EncryptedValueGetValueHint
1.1652 + * INPUTS:
1.1653 + * inEncValue
1.1654 + * The EncryptedValue to operate on.
1.1655 + *
1.1656 + * NOTES:
1.1657 + * Return a copy of the der-encoded value hint.
1.1658 + * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the
1.1659 + * return value. When, present, this is a value that the client which
1.1660 + * originally issued a certificate request can use to reproduce any data
1.1661 + * it wants. The RA does not know how to interpret this data.
1.1662 + *
1.1663 + * RETURN:
1.1664 + * A copy of the valueHint field of the EncryptedValue. A NULL return
1.1665 + * value indicates the optional valueHint field is not present in the
1.1666 + * EncryptedValue.
1.1667 + */
1.1668 +extern SECItem*
1.1669 + CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue *inEncValue);
1.1670 +
1.1671 +/*
1.1672 + * FUNCTION: CRMF_EncrypteValueGetEncSymmKey
1.1673 + * INPUTS:
1.1674 + * inEncValue
1.1675 + * The EncryptedValue to operate on.
1.1676 + *
1.1677 + * NOTES:
1.1678 + * Return a copy of the encSymmKey field. This field is the encrypted
1.1679 + * symmetric key that the client uses in doing Public Key wrap of a private
1.1680 + * key. When present, this is the symmetric key that was used to wrap the
1.1681 + * private key. (The encrypted private key will be stored in encValue
1.1682 + * of the same EncryptedValue structure.) The user must call
1.1683 + * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer
1.1684 + * needed.
1.1685 + *
1.1686 + * RETURN:
1.1687 + * A copy of the optional encSymmKey field of the EncryptedValue structure.
1.1688 + * The return value will be in BIT STRING format, meaning the len field will
1.1689 + * be the number of valid bits as opposed to the number of bytes. A return
1.1690 + * value of NULL means the optional encSymmKey field was not present in
1.1691 + * the EncryptedValue structure.
1.1692 + */
1.1693 +extern SECItem*
1.1694 + CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue);
1.1695 +
1.1696 +/*
1.1697 + * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters
1.1698 + * INPUTS:
1.1699 + * inOptions
1.1700 + * The PKiArchiveOptions to operate on.
1.1701 + *
1.1702 + * NOTES:
1.1703 + * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return
1.1704 + * value is no longer needed.
1.1705 + *
1.1706 + * RETURN:
1.1707 + * Get the keyGenParameters field of the PKIArchiveOptions.
1.1708 + * A NULL return value indicates that keyGenParameters was not
1.1709 + * used as the choice for this PKIArchiveOptions.
1.1710 + *
1.1711 + * The SECItem returned is in BIT STRING format (ie, the len field indicates
1.1712 + * number of valid bits as opposed to allocated number of bytes.)
1.1713 + */
1.1714 +extern SECItem*
1.1715 + CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions);
1.1716 +
1.1717 +/*
1.1718 + * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey
1.1719 + * INPUTS:
1.1720 + * inOpt
1.1721 + * The PKIArchiveOptions to operate on.
1.1722 + * destVal
1.1723 + * A pointer to where the library can place the value for
1.1724 + * arciveRemGenPrivKey
1.1725 + * RETURN:
1.1726 + * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the
1.1727 + * function returns SECSuccess and fills the value at *destValue with either
1.1728 + * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a
1.1729 + * value.
1.1730 + *
1.1731 + * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the
1.1732 + * function returns SECFailure and the value at *destValue is unchanged.
1.1733 + */
1.1734 +extern SECStatus
1.1735 + CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt,
1.1736 + PRBool *destVal);
1.1737 +
1.1738 +/* Helper functions that can be used by other libraries. */
1.1739 +/*
1.1740 + * A quick helper function to get the best wrap mechanism.
1.1741 + */
1.1742 +extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot);
1.1743 +
1.1744 +/*
1.1745 + * A helper function to get a randomly generated IV from a mechanism
1.1746 + * type.
1.1747 + */
1.1748 +extern SECItem* CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType);
1.1749 +
1.1750 +SEC_END_PROTOS
1.1751 +#endif /*_CRMF_H_*/
1.1752 +
1.1753 +
