keyinfo

Home Download News Documentation FAQ Tutorial API reference Examples XML Digital Signature Online Verifier XML Encryption XML Canonicalization Reporting Bugs Mailing list Related Authors
# keyinfo ## Name keyinfo -- <dsig:KeyInfo/> node parser. ## Synopsis
    #define             XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND
    #define             XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION
    #define             XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN
    #define             XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD
    #define             XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF
    #define             XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF
    #define             XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE
    #define             XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD
    #define             XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS
    #define             XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS
    #define             XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT
    #define             XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT
    #define             XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD
    xmlSecKeyDataIdxmlSecKeyDataEncryptedKeyGetKlass   (void);
    #define             xmlSecKeyDataEncryptedKeyId
    xmlSecKeyDataIdxmlSecKeyDataNameGetKlass           (void);
    #define             xmlSecKeyDataNameId
    xmlSecKeyDataIdxmlSecKeyDataRetrievalMethodGetKlass
                                                            (void);
    #define             xmlSecKeyDataRetrievalMethodId
    xmlSecKeyDataIdxmlSecKeyDataValueGetKlass          (void);
    #define             xmlSecKeyDataValueId
    struct              xmlSecKeyInfoCtx;
    intxmlSecKeyInfoCtxCopyUserPref        (xmlSecKeyInfoCtxPtr dst,
                                                             xmlSecKeyInfoCtxPtr src);
    xmlSecKeyInfoCtxPtrxmlSecKeyInfoCtxCreate              (xmlSecKeysMngrPtr keysMngr);
    intxmlSecKeyInfoCtxCreateEncCtx        (xmlSecKeyInfoCtxPtr keyInfoCtx);
    voidxmlSecKeyInfoCtxDebugDump           (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                             FILE *output);
    voidxmlSecKeyInfoCtxDebugXmlDump        (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                             FILE *output);
    voidxmlSecKeyInfoCtxDestroy             (xmlSecKeyInfoCtxPtr keyInfoCtx);
    voidxmlSecKeyInfoCtxFinalize            (xmlSecKeyInfoCtxPtr keyInfoCtx);
    intxmlSecKeyInfoCtxInitialize          (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                             xmlSecKeysMngrPtr keysMngr);
    voidxmlSecKeyInfoCtxReset               (xmlSecKeyInfoCtxPtr keyInfoCtx);
    enum                xmlSecKeyInfoMode;
    intxmlSecKeyInfoNodeRead               (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyPtr key,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
    intxmlSecKeyInfoNodeWrite              (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyPtr key,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
## Description <dsig:KeyInfo/> node parser. ## Details ### XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND
    #define XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND             0x00000001
If flag is set then we will continue reading <dsig:KeyInfo /> element even when key is already found. ### XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION
    #define XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION 0x00001000
If the flag is set then we'll stop when <enc:EncryptedKey /> element processing fails. ### XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN
    #define XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN            0x00000004
If flags is set then we abort if an unknown key name (content of <dsig:KeyName /> element) is found. ### XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD
    #define XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD     0x00000008
If flags is set then we abort if an unknown <dsig:KeyValue /> child is found. ### XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF
    #define XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF   0x00000020
If flag is set then we abort if an href attribute <dsig:RetrievalMethod /> element does not match the real key data type. ### XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF
    #define XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF    0x00000010
If flag is set then we abort if an unknown href attribute of <dsig:RetrievalMethod /> element is found. ### XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE
    #define XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE                 0x00002000
If the flag is set then we'll stop when we found an empty node. Otherwise we just ignore it. ### XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD
    #define XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD              0x00000002
If flag is set then we abort if an unknown <dsig:KeyInfo /> child is found. ### XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS
    #define XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS         0x00000200
If flag is set then we'll load certificates from <dsig:X509Data /> element without verification. ### XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS
    #define XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS        0x00004000
If the flag is set then we'll skip strict checking of certs and CRLs ### XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT
    #define XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT      0x00000800
If the flag is set then we'll stop when <dsig:X509Data /> element processing does not return a verified certificate. ### XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT
    #define XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT      0x00000400
If flag is set then we'll stop when we could not resolve reference to certificate from <dsig:X509IssuerSerial />, <dsig:X509SKI /> or <dsig:X509SubjectName /> elements. ### XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD
    #define XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD     0x00000100
If flags is set then we abort if an unknown <dsig:X509Data /> child is found. ### xmlSecKeyDataEncryptedKeyGetKlass ()
    xmlSecKeyDataId     xmlSecKeyDataEncryptedKeyGetKlass   (void);
The <enc:EncryptedKey/> element key data klass (http://www.w3.org/TR/xmlenc-core/sec-EncryptedKey): The EncryptedKey element is used to transport encryption keys from the originator to a known recipient(s). It may be used as a stand-alone XML document, be placed within an application document, or appear inside an EncryptedData element as a child of a ds:KeyInfo element. The key value is always encrypted to the recipient(s). When EncryptedKey is decrypted the resulting octets are made available to the EncryptionMethod algorithm without any additional processing.
Returns : | the <enc:EncryptedKey/> element processing key data klass.
### xmlSecKeyDataEncryptedKeyId
    #define xmlSecKeyDataEncryptedKeyId     xmlSecKeyDataEncryptedKeyGetKlass()
The <enc:EncryptedKey> processing class. ### xmlSecKeyDataNameGetKlass ()
    xmlSecKeyDataId     xmlSecKeyDataNameGetKlass           (void);
The <dsig:KeyName/> element key data klass (http://www.w3.org/TR/xmldsig-core/sec-KeyName): The KeyName element contains a string value (in which white space is significant) which may be used by the signer to communicate a key identifier to the recipient. Typically, KeyName contains an identifier related to the key pair used to sign the message, but it may contain other protocol-related information that indirectly identifies a key pair. (Common uses of KeyName include simple string names for keys, a key index, a distinguished name (DN), an email address, etc.)
Returns : | the <dsig:KeyName/> element processing key data klass.
### xmlSecKeyDataNameId
    #define xmlSecKeyDataNameId             xmlSecKeyDataNameGetKlass()
The <dsig:KeyName> processing class. ### xmlSecKeyDataRetrievalMethodGetKlass ()
    xmlSecKeyDataId     xmlSecKeyDataRetrievalMethodGetKlass
                                                            (void);
The <dsig:RetrievalMethod/> element key data klass (http://www.w3.org/TR/xmldsig-core/sec-RetrievalMethod): A RetrievalMethod element within KeyInfo is used to convey a reference to KeyInfo information that is stored at another location. For example, several signatures in a document might use a key verified by an X.509v3 certificate chain appearing once in the document or remotely outside the document; each signature's KeyInfo can reference this chain using a single RetrievalMethod element instead of including the entire chain with a sequence of X509Certificate elements. RetrievalMethod uses the same syntax and dereferencing behavior as Reference's URI and The Reference Processing Model.
Returns : | the <dsig:RetrievalMethod/> element processing key data klass.
### xmlSecKeyDataRetrievalMethodId
    #define xmlSecKeyDataRetrievalMethodId  xmlSecKeyDataRetrievalMethodGetKlass()
The <dsig:RetrievalMethod> processing class. ### xmlSecKeyDataValueGetKlass ()
    xmlSecKeyDataId     xmlSecKeyDataValueGetKlass          (void);
The <dsig:KeyValue/> element key data klass (http://www.w3.org/TR/xmldsig-core/sec-KeyValue): The KeyValue element contains a single public key that may be useful in validating the signature.
Returns : | the <dsig:KeyValue/> element processing key data klass.
### xmlSecKeyDataValueId
    #define xmlSecKeyDataValueId            xmlSecKeyDataValueGetKlass()
The <dsig:KeyValue> processing class. ### struct xmlSecKeyInfoCtx
    struct xmlSecKeyInfoCtx {
        void*                               userData;
        unsigned int                        flags;
        unsigned int                        flags2;
        xmlSecKeysMngrPtr                   keysMngr;
        xmlSecKeyInfoMode                   mode;
        xmlSecPtrList                       enabledKeyData;
        int                                 base64LineSize;

        /* RetrievalMethod */
        xmlSecTransformCtx                  retrievalMethodCtx;
        int                                 maxRetrievalMethodLevel;

        /* EncryptedKey */
        xmlSecEncCtxPtr                     encCtx;
        int                                 maxEncryptedKeyLevel;

        /* x509 certificates */
        time_t                              certsVerificationTime;
        int                                 certsVerificationDepth;

        /* PGP */
        void*                               pgpReserved;    /* TODO */

        /* internal data */
        int                                 curRetrievalMethodLevel;
        int                                 curEncryptedKeyLevel;
        xmlSecKeyReq                        keyReq;

        /* for the future */
        void*                               reserved0;
        void*                               reserved1;
    };
The <dsig:KeyInfo /> reading or writing context.
void *`userData`; | the pointer to user data (xmlsec and xmlsec-crypto never touch this).
unsigned int `flags`; | the bit mask for flags that control processin.
unsigned int `flags2`; | reserved for future.
xmlSecKeysMngrPtr `keysMngr`; | the pointer to current keys manager.
xmlSecKeyInfoMode `mode`; | do we read or write <dsig:KeyInfo /> element.
xmlSecPtrList `enabledKeyData`; | the list of enabled `xmlSecKeyDataId` (if list is empty then all data ids are enabled).
int `base64LineSize`; | the max columns size for base64 encoding.
xmlSecTransformCtx `retrievalMethodCtx`; | the transforms context for <dsig:RetrievalMethod /> element processing.
int `maxRetrievalMethodLevel`; | the max recursion level when processing <dsig:RetrievalMethod /> element; default level is 1 (see also `curRetrievalMethodLevel`).
xmlSecEncCtxPtr `encCtx`; | the encryption context for <dsig:EncryptedKey /> element processing.
int `maxEncryptedKeyLevel`; | the max recursion level when processing <enc:EncryptedKey /> element; default level is 1 (see `curEncryptedKeyLevel`).
time_t `certsVerificationTime`; | the time to use for X509 certificates verification ("not valid before" and "not valid after" checks); if `certsVerificationTime` is equal to 0 (default) then we verify certificates against the system's clock "now".
int `certsVerificationDepth`; | the max certifications chain length (default is 9).
void *`pgpReserved`; | reserved for PGP.
int `curRetrievalMethodLevel`; | the current <dsig:RetrievalMethod /> element processing level (see `maxRetrievalMethodLevel`).
int `curEncryptedKeyLevel`; | the current <enc:EncryptedKey /> element processing level (see `maxEncryptedKeyLevel`).
xmlSecKeyReq `keyReq`; | the current key requirements.
void *`reserved0`; | reserved for the future.
void *`reserved1`; | reserved for the future.
### xmlSecKeyInfoCtxCopyUserPref ()
    int                 xmlSecKeyInfoCtxCopyUserPref        (xmlSecKeyInfoCtxPtr dst,
                                                             xmlSecKeyInfoCtxPtr src);
Copies user preferences from `src` context to `dst` context.
`dst` : | the pointer to destination context object.
`src` : | the pointer to source context object.
Returns : | 0 on success and a negative value if an error occurs.
### xmlSecKeyInfoCtxCreate ()
    xmlSecKeyInfoCtxPtr xmlSecKeyInfoCtxCreate              (xmlSecKeysMngrPtr keysMngr);
Allocates and initializes <dsig:KeyInfo/> element processing context. Caller is responsible for freeing it by calling xmlSecKeyInfoCtxDestroy function.
`keysMngr` : | the pointer to keys manager (may be NULL).
Returns : | pointer to newly allocated object or NULL if an error occurs.
### xmlSecKeyInfoCtxCreateEncCtx ()
    int                 xmlSecKeyInfoCtxCreateEncCtx        (xmlSecKeyInfoCtxPtr keyInfoCtx);
Creates encryption context form processing <enc:EncryptedKey/> child of <dsig:KeyInfo/> element.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
Returns : | 0 on success and a negative value if an error occurs.
### xmlSecKeyInfoCtxDebugDump ()
    void                xmlSecKeyInfoCtxDebugDump           (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                             FILE *output);
Prints user settings and current context state to `output`.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
`output` : | the output file pointer.
### xmlSecKeyInfoCtxDebugXmlDump ()
    void                xmlSecKeyInfoCtxDebugXmlDump        (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                             FILE *output);
Prints user settings and current context state in XML format to `output`.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
`output` : | the output file pointer.
### xmlSecKeyInfoCtxDestroy ()
    void                xmlSecKeyInfoCtxDestroy             (xmlSecKeyInfoCtxPtr keyInfoCtx);
Destroys `keyInfoCtx` object created with xmlSecKeyInfoCtxCreate function.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
### xmlSecKeyInfoCtxFinalize ()
    void                xmlSecKeyInfoCtxFinalize            (xmlSecKeyInfoCtxPtr keyInfoCtx);
Cleans up the `keyInfoCtx` initialized with xmlSecKeyInfoCtxInitialize function.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
### xmlSecKeyInfoCtxInitialize ()
    int                 xmlSecKeyInfoCtxInitialize          (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                             xmlSecKeysMngrPtr keysMngr);
Initializes <dsig:KeyInfo/> element processing context. Caller is responsible for cleaning it up by xmlSecKeyInfoCtxFinalize function.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
`keysMngr` : | the pointer to keys manager (may be NULL).
Returns : | 0 on success and a negative value if an error occurs.
### xmlSecKeyInfoCtxReset ()
    void                xmlSecKeyInfoCtxReset               (xmlSecKeyInfoCtxPtr keyInfoCtx);
Resets the `keyInfoCtx` state. User settings are not changed.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
### enum xmlSecKeyInfoMode
    typedef enum {
        xmlSecKeyInfoModeRead = 0,
        xmlSecKeyInfoModeWrite
    } xmlSecKeyInfoMode;
The `xmlSecKeyInfoCtx` operation mode (read or write).
`xmlSecKeyInfoModeRead` | read <dsig:KeyInfo /> element.
`xmlSecKeyInfoModeWrite` | write <dsig:KeyInfo /> element.
### xmlSecKeyInfoNodeRead ()
    int                 xmlSecKeyInfoNodeRead               (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyPtr key,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
Parses the <dsig:KeyInfo/> element `keyInfoNode`, extracts the key data and stores into `key`.
`keyInfoNode` : | the pointer to <dsig:KeyInfo/> node.
`key` : | the pointer to result key object.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
Returns : | 0 on success or -1 if an error occurs.
### xmlSecKeyInfoNodeWrite ()
    int                 xmlSecKeyInfoNodeWrite              (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyPtr key,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
Writes the `key` into the <dsig:KeyInfo/> element template `keyInfoNode`.
`keyInfoNode` : | the pointer to <dsig:KeyInfo/> node.
`key` : | the pointer to key object.
`keyInfoCtx` : | the pointer to <dsig:KeyInfo/> element processing context.
Returns : | 0 on success or -1 if an error occurs.