# KeyInfo Processing **API Group:** `xmlsec_core_keyinfo` node processing. node parser functions. [KeyInfo](https://www.w3.org/TR/xmldsig-core/#sec-KeyInfo) is an optional element that enables the recipient(s) to obtain the key needed to validate the signature. KeyInfo may contain keys, names, certificates and other public key management information, such as in-band key distribution or key agreement data. Schema Definition: ```c ``` DTD: ```c ``` ## Macros ### `XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND` *Defined as:* `0x00000001` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L52) Continue reading KeyInfo after key is found. If flag is set then we will continue reading element even when key is already found. --- ### `XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD` *Defined as:* `0x00000002` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L59) Abort on unknown KeyInfo child element. If flag is set then we abort if an unknown child is found. --- ### `XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN` *Defined as:* `0x00000004` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L66) Abort on unknown KeyName content. If flags is set then we abort if an unknown key name (content of element) is found. --- ### `XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD` *Defined as:* `0x00000008` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L73) Abort on unknown KeyValue child element. If flags is set then we abort if an unknown child is found. --- ### `XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF` *Defined as:* `0x00000010` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L80) Abort on unknown RetrievalMethod href. If flag is set then we abort if an unknown href attribute of element is found. --- ### `XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF` *Defined as:* `0x00000020` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L87) Abort when href doesn't match actual key data type. If flag is set then we abort if an href attribute element does not match the real key data type. --- ### `XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD` *Defined as:* `0x00000100` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L94) Abort on unknown X509Data child element. If flags is set then we abort if an unknown child is found. --- ### `XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS` *Defined as:* `0x00000200` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L101) Load certificates/CRLs without verification. If flag is set then we'll load certificates or CRLs from element without verification. --- ### `XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT` *Defined as:* `0x00000400` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L109) Stop on unresolved X509 certificate reference. If flag is set then we'll stop when we could not resolve reference to certificate from , or elements. --- ### `XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT` *Defined as:* `0x00000800` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L116) Stop when X509Data returns no verified certificate. If the flag is set then we'll stop when element processing does not return a verified certificate. --- ### `XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION` *Defined as:* `0x00001000` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L123) Stop when EncryptedKey element processing fails. If the flag is set then we'll stop when element processing fails. --- ### `XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE` *Defined as:* `0x00002000` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L130) Stop when an empty node is found. If the flag is set then we'll stop when we found an empty node. Otherwise we just ignore it. --- ### `XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS` *Defined as:* `0x00004000` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L136) Skip strict checking of certificates and CRLs. If the flag is set then we'll skip strict checking of certs and CRLs --- ### `XMLSEC_KEYINFO_FLAGS_LAX_KEY_SEARCH` *Defined as:* `0x00008000` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L145) Try any key matching requirements, not just referenced keys. If the flag is set then we'll try to find any key that matches requirements (e.g. *any* RSA public key). In the default strict key search mode, only keys referenced in (e.g. by KeyName value) are used. --- ### `XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_TIME_CHECKS` *Defined as:* `0x00010000` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L151) Skip time checks of certificates and CRLs. If the flag is set then we'll skip time checks of certs and CRLs --- ### `xmlSecKeyDataNameId` *Defined as:* `xmlSecKeyDataNameGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L216) The dsig:KeyName processing class. --- ### `xmlSecKeyDataValueId` *Defined as:* `xmlSecKeyDataValueGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L222) The dsig:KeyValue processing class. --- ### `xmlSecKeyDataRetrievalMethodId` *Defined as:* `xmlSecKeyDataRetrievalMethodGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L228) The dsig:RetrievalMethod processing class. --- ### `xmlSecKeyDataKeyInfoReferenceId` *Defined as:* `xmlSecKeyDataKeyInfoReferenceGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L234) The dsig11:KeyInfoReference processing class. --- ### `xmlSecKeyDataEncryptedKeyId` *Defined as:* `xmlSecKeyDataEncryptedKeyGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L241) The enc:EncryptedKey element processing class. --- ### `xmlSecKeyDataAgreementMethodId` *Defined as:* `xmlSecKeyDataAgreementMethodGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L247) The enc:AgreementMethod processing class. --- ### `xmlSecKeyDataDerivedKeyId` *Defined as:* `xmlSecKeyDataDerivedKeyGetKlass()` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L253) The enc11:DerivedKey processing class. --- ## Enumerations ### `xmlSecKeyInfoMode` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L42) The KeyInfo context operation mode. The xmlSecKeyInfoCtx operation mode (read or write). | Value | Initializer | Description | |-------|-------------|-------------| | `xmlSecKeyInfoModeRead` | `= 0` | | | `xmlSecKeyInfoModeWrite` | `` | | --- ## Functions ### `xmlSecKeyInfoNodeRead` ```c int xmlSecKeyInfoNodeRead(xmlNodePtr keyInfoNode, xmlSecKeyPtr key, xmlSecKeyInfoCtxPtr keyInfoCtx); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L31) Reads and parses a KeyInfo node to extract key data. Parses the element `keyInfoNode`, extracts the key data and stores into `key`. **Parameters:** - `keyInfoNode` — the pointer to node. - `key` — the pointer to result key object. - `keyInfoCtx` — the pointer to element processing context. **Returns:** 0 on success or -1 if an error occurs. --- ### `xmlSecKeyInfoNodeWrite` ```c int xmlSecKeyInfoNodeWrite(xmlNodePtr keyInfoNode, xmlSecKeyPtr key, xmlSecKeyInfoCtxPtr keyInfoCtx); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L34) Writes a key into a KeyInfo node template. Writes the `key` into the element template `keyInfoNode`. **Parameters:** - `keyInfoNode` — the pointer to node. - `key` — the pointer to key object. - `keyInfoCtx` — the pointer to element processing context. **Returns:** 0 on success or -1 if an error occurs. --- ### `xmlSecKeyInfoCtxCreate` ```c xmlSecKeyInfoCtxPtr xmlSecKeyInfoCtxCreate(xmlSecKeysMngrPtr keysMngr); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L200) Allocates and initializes a KeyInfo processing context. Allocates and initializes element processing context. Caller is responsible for freeing it by calling `xmlSecKeyInfoCtxDestroy` function. **Parameters:** - `keysMngr` — the pointer to keys manager (may be NULL). **Returns:** pointer to newly allocated object or NULL if an error occurs. --- ### `xmlSecKeyInfoCtxDestroy` ```c void xmlSecKeyInfoCtxDestroy(xmlSecKeyInfoCtxPtr keyInfoCtx); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L201) Destroys a KeyInfo processing context. Destroys `keyInfoCtx` object created with `xmlSecKeyInfoCtxCreate` function. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. --- ### `xmlSecKeyInfoCtxInitialize` ```c int xmlSecKeyInfoCtxInitialize(xmlSecKeyInfoCtxPtr keyInfoCtx, xmlSecKeysMngrPtr keysMngr); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L202) Initializes a KeyInfo processing context. Initializes element processing context. Caller is responsible for cleaning it up by `xmlSecKeyInfoCtxFinalize` function. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. - `keysMngr` — the pointer to keys manager (may be NULL). **Returns:** 0 on success and a negative value if an error occurs. --- ### `xmlSecKeyInfoCtxFinalize` ```c void xmlSecKeyInfoCtxFinalize(xmlSecKeyInfoCtxPtr keyInfoCtx); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L204) Cleans up a KeyInfo processing context. Cleans up the `keyInfoCtx` initialized with `xmlSecKeyInfoCtxInitialize` function. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. --- ### `xmlSecKeyInfoCtxReset` ```c void xmlSecKeyInfoCtxReset(xmlSecKeyInfoCtxPtr keyInfoCtx); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L205) Resets the KeyInfo context state. Resets the `keyInfoCtx` state. User settings are not changed. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. --- ### `xmlSecKeyInfoCtxCopyUserPref` ```c int xmlSecKeyInfoCtxCopyUserPref(xmlSecKeyInfoCtxPtr dst, xmlSecKeyInfoCtxPtr src); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L206) Copies user preferences between KeyInfo contexts. Copies user preferences from `src` context to `dst` context. **Parameters:** - `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. --- ### `xmlSecKeyInfoCtxCreateEncCtx` ```c int xmlSecKeyInfoCtxCreateEncCtx(xmlSecKeyInfoCtxPtr keyInfoCtx); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L208) Creates an encryption context for KeyInfo processing. Creates encryption context form processing child of element. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. **Returns:** 0 on success and a negative value if an error occurs. --- ### `xmlSecKeyInfoCtxDebugDump` ```c void xmlSecKeyInfoCtxDebugDump(xmlSecKeyInfoCtxPtr keyInfoCtx, FILE *output); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L209) Prints KeyInfo context state for debugging. Prints user settings and current context state to `output`. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. - `output` — the output file pointer. --- ### `xmlSecKeyInfoCtxDebugXmlDump` ```c void xmlSecKeyInfoCtxDebugXmlDump(xmlSecKeyInfoCtxPtr keyInfoCtx, FILE *output); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L211) Prints KeyInfo context state in XML format for debugging. Prints user settings and current context state in XML format to `output`. **Parameters:** - `keyInfoCtx` — the pointer to element processing context. - `output` — the output file pointer. --- ### `xmlSecKeyDataNameGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataNameGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L217) Gets the KeyName element key data klass. The element key data klass ([http://www.w3.org/TR/xmldsig-core/#sec-KeyName](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 element processing key data klass. --- ### `xmlSecKeyDataValueGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataValueGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L223) Gets the KeyValue element key data klass. The element key data klass ([http://www.w3.org/TR/xmldsig-core/#sec-KeyValue](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 element processing key data klass. --- ### `xmlSecKeyDataRetrievalMethodGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataRetrievalMethodGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L229) Gets the RetrievalMethod element key data klass. The element key data klass ([http://www.w3.org/TR/xmldsig-core/#sec-RetrievalMethod](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 element processing key data klass. --- ### `xmlSecKeyDataKeyInfoReferenceGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataKeyInfoReferenceGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L235) Gets the KeyInfoReference element key data klass. A KeyInfoReference element within KeyInfo is used to convey a reference to a KeyInfo element at another location in the same or different document. KeyInfoReference uses the same syntax and dereferencing behavior as Reference's URI and the Reference Processing Model except that there are no child elements and the presence of the URI attribute is mandatory. The result of dereferencing a KeyInfoReference MUST be a KeyInfo element, or an XML document with a KeyInfo element as the root. ```c ``` [https://www.w3.org/TR/xmldsig-core1/#sec-KeyInfoReference](https://www.w3.org/TR/xmldsig-core1/#sec-KeyInfoReference) **Returns:** the element processing key data klass. --- ### `xmlSecKeyDataEncryptedKeyGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataEncryptedKeyGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L242) Gets the EncryptedKey element key data klass. The element key data klass ([http://www.w3.org/TR/xmlenc-core/#sec-EncryptedKey](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 element processing key data klass. --- ### `xmlSecKeyDataAgreementMethodGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataAgreementMethodGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L248) Gets the AgreementMethod element key data klass. The element key data klass ([https://www.w3.org/TR/xmlenc-core1/#sec-Alg-KeyAgreement](https://www.w3.org/TR/xmlenc-core1/#sec-Alg-KeyAgreement)) A Key Agreement algorithm provides for the derivation of a shared secret key based on a shared secret computed from certain types of compatible public keys from both the sender and the recipient. Information from the originator to determine the secret is indicated by an optional OriginatorKeyInfo parameter child of an AgreementMethod element while that associated with the recipient is indicated by an optional RecipientKeyInfo. A shared key is derived from this shared secret by a method determined by the Key Agreement algorithm. **Returns:** the element processing key data klass. --- ### `xmlSecKeyDataDerivedKeyGetKlass` ```c xmlSecKeyDataId xmlSecKeyDataDerivedKeyGetKlass(void); ``` *Source:* [include/xmlsec/keyinfo.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/keyinfo.h#L254) Gets the DerivedKey element key data klass. The element key data klass ([https://www.w3.org/TR/xmlenc-core1/#sec-DerivedKey](https://www.w3.org/TR/xmlenc-core1/#sec-DerivedKey)) The DerivedKey element is used to transport information about a derived key from the originator to recipient(s). It may be used as a stand-alone XML document, be placed within an application document, or appear inside an EncryptedData or Signature element as a child of a ds:KeyInfo element. The key value itself is never sent by the originator. Rather, the originator provides information to the recipient(s) by which the recipient(s) can derive the same key value. When the key has been derived the resulting octets are made available to the EncryptionMethod or SignatureMethod algorithm without any additional processing. **Returns:** the element processing key data klass. ---