RSA BSAFE Cert-C

00001 /*
00002 ** Copyright (c) 1999-2002, RSA Security Inc.
00003 **
00004 ** This file is used to demonstrate how to interface to an RSA
00005 ** Security licensed development product.  You have a
00006 ** royalty-free right to use, modify, reproduce and distribute this
00007 ** demonstration file (including any modified version), provided that
00008 ** you agree that RSA Security has no warranty, implied or
00009 ** otherwise, or liability for this demonstration file or any modified
00010 ** version.
00011 **
00012 */
00013 
00020 #ifndef _PKI_MSG_H_
00021 #define _PKI_MSG_H_
00022 
00023 #include "basetype.h"
00024 #include "bsafe.h"
00025 #include "certext.h"
00026 #include "certapi.h"
00027 #include "certalg.h"
00028 #include "cms.h"
00029 #include "altname.h"
00030 #include "pkistinf.h"
00031 
00032 #ifdef __cplusplus
00033 extern "C" {
00034 #endif
00035 
00261 typedef POINTER PKI_MSG_OBJ;    /* handle to opaque PKI msg obj */
00262 
00263 /*
00264  * DEPRECATED values and structs Cert-C 2.5:
00265  */
00297 typedef struct {
00298   ALGORITHM_IDENTIFIER contentEncryptionAlgorithmId;
00299   RECIPIENT_INFO       recipient;
00300 } PKI_RECIPIENT;
00301 
00302 #define PKI_MSGTYPE_CERTREQ       1
00303 #define PKI_MSGTYPE_CERTRESP      2
00304 
00305 /* values for PKI_MSG_FIELDS.flags */
00306 #define PKI_MSGFLAGS_WRAP_NONE               0x00000000
00307 #define PKI_MSGFLAGS_WRAP_SIGN               0x00000001
00308 #define PKI_MSGFLAGS_WRAP_ENVELOPE           0x00000002
00309 #define PKI_MSGFLAGS_WRAP_SIGN_THEN_ENVELOPE 0x00000003
00310 #define PKI_MSGFLAGS_WRAP_ENVELOPE_THEN_SIGN 0x00000004
00311 #define PKI_MSGFLAGS_WRAP_MASK                      0x7
00312 #define PKI_MSGFLAGS_IGNORE_SENDER           0x00000008
00313 #define PKI_MSGFLAGS_IGNORE_RECIPIENT        0x00000010
00314 #define PKI_MSGFLAGS_IGNORE_MSGTYPE          0x00000020
00315 #define PKI_MSGFLAGS_IGNORE_PROTOCOLVERSION  0x00000040
00316 #define PKI_MSGFLAGS_IGNORE_MSGTIME          0x00000080
00317 #define PKI_MSGFLAGS_IGNORE_TRANSACTIONID    0x00000100
00318 #define PKI_MSGFLAGS_IGNORE_FREETEXT         0x00000200
00319 #define PKI_MSGFLAGS_IGNORE_GENERALINFO      0x00000400
00320 #define PKI_MSGFLAGS_IGNORE_EXTRACERTS       0x00000800
00321 #define PKI_MSGFLAGS_IGNORE_EXTRACRLS        0x00001000
00322 
00323 /* General PKI message information */
00603 typedef struct {
00604   unsigned int     flags;         /* wrap & PKI_MSGFLAGS_IGNORE_* flags      */
00605   SIGNER_INFO      sender;        /* identifies request initiator (EE/RA)    */
00606   PKI_RECIPIENT    recipient;     /* identifies request target    (RA/CA)    */
00607   unsigned int     msgType;       /* PKI message type (one of PKI_MSGTYPE_*) */
00608   unsigned int     version;       /* protocol version identifier             */
00609   GENERALIZED_TIME messageTime;   /* time of message production              */
00610   ITEM             transactionID; /* transaction identifier                  */
00611   LIST_OBJ         freeText;      /* list of UTF8 strings                    */
00612   ATTRIBUTES_OBJ   generalInfo;   /* context-specific info                   */
00613   LIST_OBJ         extraCerts;    /* list of CERT_OBJ                        */
00614   LIST_OBJ         extraCRLs;     /* list of CRL_OBJ                         */
00615 } PKI_MSG_FIELDS;
00616 
00617 /*
00618  * PKI cert request related structs
00619  */
00620 
00621 /* values for PKI_CERTREQ_FIELDS.flags */
00622 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_VERSION     0x00000001
00623 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_SERIAL      0x00000002
00624 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_SIGALG      0x00000004
00625 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_ISSUERNAME  0x00000008
00626 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_VALIDSTART  0x00000010
00627 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_VALIDEND    0x00000020
00628 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_SUBJECTNAME 0x00000040
00629 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_PUBLICKEY   0x00000080
00630 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_ISSUERUID   0x00000100
00631 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_SUBJECTUID  0x00000200
00632 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_CERTEXTS    0x00000400
00633 #define PKI_CERTREQFLAGS_IGNORE_TEMPLATE_RESERVED    0x00000800
00634 #define PKI_CERTREQFLAGS_IGNORE_CERTREQID            0x00001000
00635 #define PKI_CERTREQFLAGS_IGNORE_CONTROLS             0x00002000
00636 #define PKI_CERTREQFLAGS_IGNORE_POPTYPE              0x00004000
00637 #define PKI_CERTREQFLAGS_IGNORE_REGINFO              0x00008000
00638 
00804 typedef struct {
00805   unsigned int   flags;        /* bit-field of PKI_CERTREQFLAGS_*        */
00806   CERT_FIELDS    certTemplate; /* selected fields of new cert            */
00807   ITEM           certReqID;    /* ID to match request and response       */
00808   ATTRIBUTES_OBJ controls;     /* attributes affecting issuance          */
00809   unsigned int   popType;      /* proof-of-possession (one of PKI_POP_*) */
00810   ATTRIBUTES_OBJ regInfo;      /* supplementary information              */
00811 } PKI_CERTREQ_FIELDS;
00812 
00813 /*
00814  * PKI cert response related structs
00815  */
00816 
00817 /* values for PKI_CERTRESP_FIELDS.flags */
00818 #define PKI_CERTRESPFLAGS_IGNORE_STATUS_STATUS       0x00000001
00819 #define PKI_CERTRESPFLAGS_IGNORE_STATUS_STATUSSTRING 0x00000002
00820 #define PKI_CERTRESPFLAGS_IGNORE_STATUS_FAILINFO     0x00000004
00821 #define PKI_CERTRESPFLAGS_IGNORE_STATUS_FAILINFOAUX  0x00000008
00822 #define PKI_CERTRESPFLAGS_IGNORE_CERTREQID           0x00000010
00823 #define PKI_CERTRESPFLAGS_IGNORE_CERT                0x00000020
00824 #define PKI_CERTRESPFLAGS_IGNORE_PRIVATEKEY          0x00000040
00825 #define PKI_CERTRESPFLAGS_IGNORE_REGINFO             0x00000080
00826 #define PKI_CERTRESPFLAGS_IGNORE_CACERTS             0x00000100
00827 
00949 typedef struct {
00950   unsigned int      flags;       /* bit field of PKI_CERTRESPFLAGS_* */
00951   PKI_STATUS_INFO   statusInfo;  /* certification status             */
00952   ITEM              certReqID;   /* ID to match request and response */
00953   CERT_OBJ          cert;        /* returned certificate             */
00954   B_KEY_OBJ         privateKey;  /* corresponding private key        */
00955   ATTRIBUTES_OBJ    regInfo;     /* supplementary information        */
00956   LIST_OBJ          caCerts;     /* list of CA CERT_OBJs             */
00957 } PKI_CERTRESP_FIELDS;
00958 
00959 /*
00960  * END OF DEPRECATED values and structures
00961  */
00962 
00963 /*
00964  * PKI Message types -- these are types of PKIBody, the message-specific
00965  * information contained in PKIMessage. There're 27 different types in
00966  * draft-ietf-pkix-rfc2510bis-05.txt, the following are supported in CertC
00967  * 2.5.
00968  */
00969 #define PKI_MSGTYPE_UNKNOWN         0
00970 #define PKI_MSGTYPE_CERT_REQ        1
00971 #define PKI_MSGTYPE_CERT_RESP       2
00972 #define PKI_MSGTYPE_REVOKE_REQ      3
00973 #define PKI_MSGTYPE_REVOKE_RESP     4
00974 #define PKI_MSGTYPE_KEY_UPDATE_REQ  5
00975 #define PKI_MSGTYPE_KEY_UPDATE_RESP 6
00976 #define PKI_MSGTYPE_ERROR_MSG       7
00977 #define PKI_MSGTYPE_CERT_CONF_REQ   8
00978 #define PKI_MSGTYPE_CERT_CONF_RESP  9
00979 #define _PKI_MSGTYPE_MAX            9
00980 
00981 /*
00982  * values for PKI_CERTREQ_FIELDS.popType(deprecated) or popType used in
00983  * PKI_CERT_REQUEST_OBJ/PKI_KEY_UPDATE_REQ_OBJ.
00984  */
00985 #define PKI_POP_RA_VERIFIED 0
00986 #define PKI_POP_SIGNATURE   1
00987 #define PKI_POP_ENCRYPTION  2
00988 #define PKI_POP_KEY_AGREE   3
00989 
01012 typedef struct {
01013   GENERAL_NAME *name;
01014   ITEM          keyId;
01015 } GENERAL_NAME_KEYID;
01016 
01017 #define PKI_ENTITY_UNDEFINED         0
01018 #define PKI_ENTITY_ISSUER_SERIAL     1
01019 #define PKI_ENTITY_GENERALNAME_KEYID 2
01020 
01058 typedef struct {
01059   int  type;                /* one of PKI_ENTITY_* */
01060   union {
01061     ISSUER_SERIAL_NUMBER issuerSerialNumber;
01062     GENERAL_NAME_KEYID   generalNameKeyId;
01063   } id;
01064 } PKI_ENTITY_ID;
01065 
01137 typedef struct {
01138   PKI_ENTITY_ID        senderId;
01139   ALGORITHM_IDENTIFIER digestAlgorithmId;
01140   ATTRIBUTES_OBJ       authenticatedAttributes;
01141   ALGORITHM_IDENTIFIER signatureAlgorithmId;
01142   ATTRIBUTES_OBJ       extraAttributes;
01143 } PKI_SENDER_INFO;
01144 
01166 typedef struct {
01167   PKI_ENTITY_ID        recipientId;
01168   ALGORITHM_IDENTIFIER keyEncryptionAlgorithmId;
01169 } PKI_KEY_TRANSPORT_INFO;
01170 
01171 #define PKI_RECIPIENT_UNDEFINED         0
01172 #define PKI_RECIPIENT_KEY_TRANSPORT     1
01173 #define PKI_RECIPIENT_GENERALNAME_KEYID 2
01174 
01239 typedef struct {
01240   int type;                      /* one of PKI_RECIPIENT_* */
01241   ALGORITHM_IDENTIFIER     contentEncryptionAlgorithmId;
01242   union {
01243     PKI_KEY_TRANSPORT_INFO keyTrans;
01244     GENERAL_NAME_KEYID     generalNameKeyId;
01245   } info;
01246 } PKI_RECIPIENT_INFO;
01247 
01248 /*
01249  * PKI protection related structs
01250  */
01251 
01273 typedef struct {
01274   ITEM                 sharedSecret;
01275   ALGORITHM_IDENTIFIER algorithm;
01276 } PBM_INFO;
01277 
01278 #define PKI_POP_AUTH_TYPE_NAME  0
01279 #define PKI_POP_AUTH_TYPE_PBM   1
01280 
01326 typedef struct {
01327   int authInfoType;             /* one of PKI_POP_AUTH_*   */
01328   union {
01329     ALTERNATE_NAME subject;     /* name of subject         */
01330     PBM_INFO       pbmInfo;     /* password-based MAC info */
01331   } authInfo;
01332   ITEM publicKey;               /* subject public key info */
01333 } PKI_POP_GEN_SIGNATURE_INFO;
01334 
01335 #define PKI_POP_METHOD_ENCRYPT_KEY      0
01336 #define PKI_POP_METHOD_DH_MAC           1
01337 #define PKI_POP_METHOD_ENCRYPT_CERT     2
01338 #define PKI_POP_METHOD_CHALLENGE        3
01339 
01395 typedef union {
01396   int                        method; /* one of PKI_POP_METHOD_* */
01397   PKI_POP_GEN_SIGNATURE_INFO sign;
01398 } PKI_POP_GEN_INFO;
01399 
01400 /*
01401  * PKI protection generation and verifcation related structs
01402  */
01403 #define PKI_MSG_PROTECTION_NONE               0
01404 #define PKI_MSG_PROTECTION_SIGN               1
01405 #define PKI_MSG_PROTECTION_ENVELOPE           2
01406 #define PKI_MSG_PROTECTION_SIGN_THEN_ENVELOPE 3
01407 #define PKI_MSG_PROTECTION_ENVELOPE_THEN_SIGN 4
01408 #define PKI_MSG_PROTECTION_PBM                5
01409 
01434 typedef struct {
01435   union {
01436     ITEM          *secret;         /* shared secret                             */
01437     CERT_PATH_CTX *protectionCtx;  /* for building sign/enc-related cert chains */
01438   } info;
01439 } PKI_PROTECT_INFO;
01440 
01462 typedef struct {
01463   union {
01464     ITEM      *secret;         /* shared secret                    */
01465     B_KEY_OBJ  privateKey;     /* private key for unencrypting POP */
01466   } info;
01467 } PKI_POP_VAL_INFO;
01468 
01469 
01477 typedef struct {
01478   GENERAL_NAME issuerName;
01479   ITEM         serialNumber;
01480 } PKI_ISSUER_SERIAL_NUMBER;
01481 
01496 typedef struct {
01497   int type;
01498   union {
01499     PKI_ISSUER_SERIAL_NUMBER issuerSerialNumber;
01500   } id;
01501 } PKI_CERT_IDENTIFIER;
01502 
01503 /* Choice(s) for PKI_CERT_IDENTIFIER.type */
01504 #define PKI_ISSUER_SERIAL  1
01505 
01506 /*
01507  ****************************** API FUNCTION INTERFACE ************************
01508  */
01526 int C_CreatePKIMsgObject (
01527   CERTC_CTX   ctx,            /* (in)  Cert-C context                     */
01528   PKI_MSG_OBJ *pPkiMsgObj);   /* (out) returned pointer to message object */
01529 
01545 void C_DestroyPKIMsgObject (
01546   PKI_MSG_OBJ *pPkiMsgObj);     /* (mod) message object to free and zero-out */
01547 
01644 int C_SetPKIMsgSender (
01645   PKI_MSG_OBJ     pkiMsgObj,      /* (mod) message object        */
01646   PKI_SENDER_INFO *pSenderInfo);  /* (in)  sender content to set */
01647 
01702 int C_GetPKIMsgSender (
01703   PKI_MSG_OBJ      pkiMsgObj,     /* (in)  message object             */
01704   PKI_SENDER_INFO *pSenderInfo);  /* (out) sender content to retrieve */
01705 
01800 int C_SetPKIMsgRecipient (
01801   PKI_MSG_OBJ         pkiMsgObj,        /* (mod) message object        */
01802   PKI_RECIPIENT_INFO  *pRecipientInfo); /* (in)  recip. content to set */
01803 
01861 int C_GetPKIMsgRecipient (
01862   PKI_MSG_OBJ         pkiMsgObj,        /* (in)  message object             */
01863   PKI_RECIPIENT_INFO  *pRecipientInfo); /* (out) recip. content to retrieve */
01864 
01878 int C_SetPKIMsgProtectionType (
01879   PKI_MSG_OBJ   pkiMsgObj,        /* (mod) message object */
01880   unsigned int  protectionType);  /* (in) message protection type to set */
01881 
01895 int C_GetPKIMsgProtectionType (
01896   PKI_MSG_OBJ   pkiMsgObj,          /* (in) message object */
01897   unsigned int  *pProtectionType);  /* (out) message protection type to retrieve */
01898 
01912 int C_SetPKIMsgType (
01913   PKI_MSG_OBJ   pkiMsgObj,        /* (mod) message object */
01914   unsigned int  msgType);         /* (in) message type to set */
01915 
01929 int C_GetPKIMsgType (
01930   PKI_MSG_OBJ   pkiMsgObj,        /* (in) message object */
01931   unsigned int  *pMsgType);       /* (out) message type to retrieve */
01932 
01946 int C_SetPKIMsgVersion (
01947   PKI_MSG_OBJ   pkiMsgObj,        /* (mod) message object */
01948   unsigned int  version);         /* (in) protocol version identifier to set */
01949 
01963 int C_GetPKIMsgVersion (
01964   PKI_MSG_OBJ   pkiMsgObj,        /* (in) message object */
01965   unsigned int  *pVersion);       /* (out) protocol version identifier to retrieve */
01966 
01980 int C_SetPKIMsgTime (
01981   PKI_MSG_OBJ       pkiMsgObj,    /* (mod) message object */
01982   GENERALIZED_TIME  *pMsgTime);   /* (in) time of message production to set */
01983 
01997 int C_GetPKIMsgTime (
01998   PKI_MSG_OBJ       pkiMsgObj,    /* (in) message object */
01999   GENERALIZED_TIME  *pMsgTime);   /* (out) time of message production to retrieve */
02000 
02016 int C_SetPKIMsgTransID (
02017   PKI_MSG_OBJ pkiMsgObj,          /* (mod) message object */
02018   ITEM        *pTransID);         /* (in) transaction identifier to set */
02019 
02035 int C_GetPKIMsgTransID (
02036   PKI_MSG_OBJ pkiMsgObj,          /* (in) message object */
02037   ITEM        *pTransID);         /* (out) transaction identifier to retrieve */
02038 
02058 int C_SetPKIMsgSenderNonce (
02059   PKI_MSG_OBJ pkiMsgObj,          /* (mod) message object */
02060   ITEM        *pSenderNonce);     /* (in) sender nonce to set */
02061 
02075 int C_GetPKIMsgSenderNonce (
02076   PKI_MSG_OBJ pkiMsgObj,          /* (in) message object */
02077   ITEM        *pSenderNonce);     /* (out) sender nonce to retrieve */
02078 
02092 int C_SetPKIMsgRecipientNonce (
02093   PKI_MSG_OBJ pkiMsgObj,          /* (mod) message object */
02094   ITEM        *pRecipientNonce);  /* (in) recipient nonce to set */
02095 
02109 int C_GetPKIMsgRecipientNonce (
02110   PKI_MSG_OBJ pkiMsgObj,          /* (in) message object */
02111   ITEM        *pRecipientNonce);  /* (out) recipient nonce to retrieve */
02112 
02128 int C_SetPKIMsgFreeText (
02129   PKI_MSG_OBJ pkiMsgObj,          /* (mod) message object */
02130   LIST_OBJ    freeText);          /* (in) list of UTF8 strings to set */
02131 
02147 int C_GetPKIMsgFreeText (
02148   PKI_MSG_OBJ pkiMsgObj,          /* (in) message object */
02149   LIST_OBJ    *pFreeText);        /* (out) list of UTF8 strings to retrieve */
02150 
02166 int C_SetPKIMsgGeneralInfo (
02167   PKI_MSG_OBJ     pkiMsgObj,      /* (mod) message object */
02168   ATTRIBUTES_OBJ  genInfo);       /* (in) context-specific info to set */
02169 
02185 int C_GetPKIMsgGeneralInfo (
02186   PKI_MSG_OBJ     pkiMsgObj,      /* (in) message object */
02187   ATTRIBUTES_OBJ  *pGenInfo);     /* (out) context-specific info to retrieve */
02188 
02203 int C_SetPKIMsgExtraCerts (
02204   PKI_MSG_OBJ pkiMsgObj,      /* (mod) message object */
02205   LIST_OBJ    extraCerts);    /* (in) list of CERT_OBJ to set */
02206 
02221 int C_GetPKIMsgExtraCerts (
02222   PKI_MSG_OBJ pkiMsgObj,      /* (in) message object */
02223   LIST_OBJ    *pExtraCerts);  /* (out) list of CERT_OBJ to retrieve */
02224 
02239 int C_SetPKIMsgExtraCRLs (
02240   PKI_MSG_OBJ pkiMsgObj,      /* (mod) message object */
02241   LIST_OBJ    extraCRLs);     /* (in) list of CRL_OBJ to set */
02242 
02257 int C_GetPKIMsgExtraCRLs (
02258   PKI_MSG_OBJ pkiMsgObj,      /* (in) message object */
02259   LIST_OBJ    *pExtraCRLs);   /* (out) list of CRL_OBJ to retrieve */
02260 
02274 int C_ResetPKIMsgObject (
02275   PKI_MSG_OBJ pkiMsgObj);     /* (mod) pki message object */
02276 
02291 int C_GetPKIMsgCount (
02292   PKI_MSG_OBJ   pkiMsgObj,    /* (in) PKI message object  */
02293   unsigned int  *pCount);      /* (mod) count of messages in object */
02294 
02311 int C_AddPKIMsg (
02312   PKI_MSG_OBJ   pkiMsgObj,    /* (mod) PKI message object */
02313   POINTER       pkiMsg,       /* (in) one of the pki message's object */
02314   unsigned int  *pIndex);     /* (out) index of request */
02315 
02329 int C_DeletePKIMsg (
02330   PKI_MSG_OBJ   pkiMsgObj,    /* (mod) PKI message object */
02331   unsigned int  index);       /* (in) index of request */
02332 
02349 int C_GetPKIMsg (
02350   PKI_MSG_OBJ   pkiMsgObj,    /* (in)  certification request object   */
02351   POINTER       *pPkiMsg,     /* (in) one of the pki message's object */
02352   unsigned int  index);       /* (in) index of request */
02353 
02354 /* The C_RequestPKIMsg function sends a certification request message to
02355  * the specified PKI service. It receives and processes the response. If
02356  * any certificates, CRLs, or keys are received in the response, these are
02357  * stored in the database(s) bound to db. The application can examine the
02358  * response message for status information. In addition, some services may
02359  * require the application to examine the response to determine whether the
02360  * identity of the responder is the one the application expected
02361  * responder name.
02362  */
02393 int C_RequestPKIMsg (
02394   CERTC_CTX         ctx,            /* (in)  Cert-C context                 */
02395   char              *pki,           /* (in)  PKI protocol handler name      */
02396   PKI_MSG_OBJ       pkiRequest,     /* (in)  request object                 */
02397   PKI_PROTECT_INFO  *pProtectInfo,  /* (in)  protection/integrity info      */
02398   SERVICE           db,             /* (out) where to put keys, certs, crls */
02399   PKI_MSG_OBJ       response);      /* (out) response message object        */
02400 
02401 /* Creates a serialized certification request message according to the protocol
02402  * implemented by the specified PKI service provider. The message is not
02403  * actually transmitted to a PKI server. This function also applies relevant
02404  * cryptographic protections, such as digital signatures or envelopes, to the
02405  * message as a part of the serialization process
02406  */
02439 int C_GetPKIMsgDER (
02440   CERTC_CTX         ctx,            /* (in)  Cert-C context               */
02441   char              *pki,           /* (in)  PKI protocol handler name    */
02442   PKI_MSG_OBJ       request,        /* (in)  certification request object */
02443   PKI_PROTECT_INFO  *pProtectInfo,  /* (in)  protection/integrity info    */
02444   ITEM              *pEncodedMsg);  /* (out) serialized request           */
02445 
02446 /* The C_SendPKIRequest function sends a PKI request message to the server,
02447  * return an encoded response message and the status of the send request
02448  * operation.
02449  */
02479 int C_SendPKIRequest (
02480   CERTC_CTX           ctx,              /* (in)  Cert-C context                 */
02481   char                *pki,             /* (in)  PKI protocol handler name      */
02482   ITEM                *pEncodedRequest, /* (in)  encoded request message        */
02483   ITEM                *pEncodedResponse,/* (out) encoded response message       */
02484   PKI_STATUS_INFO_OBJ statusInfo);      /* (out) out-of-band status information */
02485 
02486 /* Processes a certification response message. Relevant cryptographic protections
02487  * are validated (for example, digital signatures) or inverted (for example,
02488  * digital envelopes), or both validated and inverted. Information extracted from
02489  * the message is stored in the supplied PKI_MSG_OBJ. The application is
02490  * responsible for the long-term disposition of the information in the response
02491  * object. The function does not store any elements of the certification response
02492  * in the persistent data stores
02493  */
02524 int C_SetPKIMsgBER (
02525   CERTC_CTX         ctx,            /* (in)  Cert-C context            */
02526   char              *pki,           /* (in)  PKI protocol handler name */
02527   ITEM              *pEncodedMsg,   /* (in)  serialized response       */
02528   PKI_PROTECT_INFO  *pProtectInfo,  /* (in)  protection/integrity info */
02529   PKI_MSG_OBJ       response);      /* (out) response message object   */
02530 
02556 int C_GeneratePKIMsgProofOfPossession (
02557   CERTC_CTX         ctx,            /* (in)  Cert-C context               */
02558   char              *pki,           /* (in)  PKI protocol handler name    */
02559   PKI_MSG_OBJ       pkiMsgObj,      /* (mod) PKI message object */
02560   unsigned int      index,          /* (in)  index of request in message object */
02561   B_KEY_OBJ         privateKey,     /* (in)  private key                  */
02562   PKI_POP_GEN_INFO  *pPopGenInfo);  /* (in)  determined by POP type       */
02563 
02590 int C_ValidatePKIMsgProofOfPossession (
02591   CERTC_CTX         ctx,            /* (in)  Cert-C context                   */
02592   char              *pki,           /* (in)  PKI protocol handler name        */
02593   PKI_MSG_OBJ       msg,            /* (in)  PKI message object */
02594   unsigned int      index,          /* (in)  index of request or response in message object */
02595   PKI_POP_VAL_INFO  *pPopValInfo,   /* (in)  private info to open response    */
02596   B_KEY_OBJ         privateKey);    /* (out) subject's private key            */
02597 
02598 /*
02599  * Typically called by the SP, but could also be useful for providing info
02600  * for PKI_MSG_OBJ-cloning to the application.  Cert-C allocates the memory
02601  * in either case.
02602  */
02612 typedef LIST_OBJ_ENTRY_HANDLER PKI_SP_DATA_HANDLER;
02645  int C_SetPKIProviderData (
02646   PKI_MSG_OBJ         message,      /* (mod) message object                   */
02647   POINTER             data,         /* (in)  data to associate with "message" */
02648   PKI_SP_DATA_HANDLER *pHandler);
02674 int C_GetPKIProviderData (
02675   PKI_MSG_OBJ message,    /* (in)  certification response                  */
02676   POINTER     *data);     /* (out) serialization of provider-specific data */
02677 
02704 void C_DestroyPKIProviderData (
02705   PKI_MSG_OBJ message);   /* (mod) serialization of provider-specific data */
02706 
02707 /*
02708  * DEPRECATED APIs Cert-C 2.5:
02709  */
02710 
02720 int C_SetPKIMsgFields (
02721   PKI_MSG_OBJ     pkiMsgObj,    /* (mod) message object                       */
02722   PKI_MSG_FIELDS  *pMsgFields); /* (in)  message fields content to initialize */
02723 
02733 int C_GetPKIMsgFields (
02734   PKI_MSG_OBJ     pkiMsgObj,    /* (in)  message object             */
02735   PKI_MSG_FIELDS  *pMsgFields); /* (out) fields content to retrieve */
02736 
02746 int C_SetPKICertRequestFields (
02747   PKI_MSG_OBJ         certRequest,      /* (mod) certification request object  */
02748   PKI_CERTREQ_FIELDS  *pRequestFields); /* (in)  request fields content to set */
02749 
02759 int C_GetPKICertRequestFields (
02760   PKI_MSG_OBJ         certRequest,      /* (in)  certification request object        */
02761   PKI_CERTREQ_FIELDS  *pRequestFields); /* (out) request fields content to retrieve  */
02762 
02772 int C_SetPKICertResponseFields (
02773   PKI_MSG_OBJ         certResponse,     /* (mod) certification response object         */
02774   PKI_CERTRESP_FIELDS *pResponseFields);/* (in)  response fields content to initialize */
02775 
02785 int C_GetPKICertResponseFields (
02786   PKI_MSG_OBJ         certResponse,     /* (in)  certification response object         */
02787   PKI_CERTRESP_FIELDS *pResponseFields);/* (out) response fields content to retrieve   */
02788 
02798 int C_RequestPKICert (
02799   CERTC_CTX         ctx,            /* (in)  Cert-C context                 */
02800   char              *pki,           /* (in)  PKI protocol handler name      */
02801   PKI_MSG_OBJ       certRequest,    /* (in)  certification request object   */
02802   PKI_PROTECT_INFO  *pProtectInfo,  /* (in)  protection/integrity info      */
02803   SERVICE           db,             /* (out) where to put keys, certs, crls */
02804   PKI_MSG_OBJ       response);      /* (out) response message object        */
02805 
02834 int C_WritePKICertRequestMsg (
02835   CERTC_CTX         ctx,            /* (in)  Cert-C context               */
02836   char              *pki,           /* (in)  PKI protocol handler name    */
02837   PKI_MSG_OBJ       request,        /* (in)  certification request object */
02838   PKI_PROTECT_INFO  *pProtectInfo,  /* (in)  protection/integrity info    */
02839   ITEM              *pEncodedMsg);  /* (out) serialized request           */
02840 
02878 int C_SendPKIMsg (
02879   CERTC_CTX        ctx,             /* (in)  Cert-C context                 */
02880   char            *pki,             /* (in)  PKI protocol handler name      */
02881   ITEM            *pEncodedRequest, /* (in)  encoded request message        */
02882   ITEM            *pEncodedResponse,/* (out) encoded response message       */
02883   PKI_STATUS_INFO *pStatusInfo);    /* (out) out-of-band status information */
02884 
02893 int C_ReadPKICertResponseMsg (
02894   CERTC_CTX         ctx,            /* (in)  Cert-C context            */
02895   char              *pki,           /* (in)  PKI protocol handler name */
02896   ITEM              *pEncodedMsg,   /* (in)  serialized response       */
02897   PKI_PROTECT_INFO  *pProtectInfo,  /* (in)  protection/integrity info */
02898   PKI_MSG_OBJ       certResponse);  /* (out) response message object   */
02899 
02908 int C_GeneratePKIProofOfPossession (
02909   CERTC_CTX         ctx,            /* (in)  Cert-C context               */
02910   char              *pki,           /* (in)  PKI protocol handler name    */
02911   PKI_MSG_OBJ       certRequest,    /* (mod) certification request object */
02912   B_KEY_OBJ         privateKey,     /* (in)  private key                  */
02913   PKI_POP_GEN_INFO  *pPopGenInfo);  /* (in)  determined by POP type       */
02914 
02925 int C_ValidatePKIProofOfPossession(
02926   CERTC_CTX         ctx,            /* (in)  Cert-C context                   */
02927   char              *pki,           /* (in)  PKI protocol handler name        */
02928   PKI_MSG_OBJ       msg,            /* (in)  PKI message object */
02929   PKI_POP_VAL_INFO  *pPopValInfo,   /* (in)  private info to open response    */
02930   B_KEY_OBJ         privateKey);    /* (out) subject's private key            */
02931 
02932 /*
02933  * END OF DEPRECATED APIs
02934  */
02935 #ifdef __cplusplus
02936 }
02937 #endif
02938 
02939 #endif /* _PKI_MSG_H_ */
pkimsg.h
