- 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 --

## Synopsis

    int         xmlSecKeyInfoNodeRead           (xmlNodePtr keyInfoNode,
                                                 xmlSecKeyPtr key,
                                                 xmlSecKeyInfoCtxPtr keyInfoCtx);
    int         xmlSecKeyInfoNodeWrite          (xmlNodePtr keyInfoNode,
                                                 xmlSecKeyPtr key,
                                                 xmlSecKeyInfoCtxPtr keyInfoCtx);
    enum        xmlSecKeyInfoMode;
    #define     XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND
    #define     XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD
    #define     XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN
    #define     XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD
    #define     XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF
    #define     XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF
    #define     XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD
    #define     XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS
    #define     XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT
    #define     XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT
    #define     XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION
    #define     XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE
    #define     XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS
    struct      xmlSecKeyInfoCtx;
    xmlSecKeyInfoCtxPtr xmlSecKeyInfoCtxCreate  (xmlSecKeysMngrPtr keysMngr);
    void        xmlSecKeyInfoCtxDestroy         (xmlSecKeyInfoCtxPtr keyInfoCtx);
    int         xmlSecKeyInfoCtxInitialize      (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                 xmlSecKeysMngrPtr keysMngr);
    void        xmlSecKeyInfoCtxFinalize        (xmlSecKeyInfoCtxPtr keyInfoCtx);
    void        xmlSecKeyInfoCtxReset           (xmlSecKeyInfoCtxPtr keyInfoCtx);
    int         xmlSecKeyInfoCtxCopyUserPref    (xmlSecKeyInfoCtxPtr dst,
                                                 xmlSecKeyInfoCtxPtr src);
    int         xmlSecKeyInfoCtxCreateEncCtx    (xmlSecKeyInfoCtxPtr keyInfoCtx);
    void        xmlSecKeyInfoCtxDebugDump       (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                 FILE *output);
    void        xmlSecKeyInfoCtxDebugXmlDump    (xmlSecKeyInfoCtxPtr keyInfoCtx,
                                                 FILE *output);
    #define     xmlSecKeyDataNameId
    xmlSecKeyDataId xmlSecKeyDataNameGetKlass   (void);
    #define     xmlSecKeyDataValueId
    xmlSecKeyDataId xmlSecKeyDataValueGetKlass  (void);
    #define     xmlSecKeyDataRetrievalMethodId
    xmlSecKeyDataId xmlSecKeyDataRetrievalMethodGetKlass
                                                (void);
    #define     xmlSecKeyDataEncryptedKeyId
    xmlSecKeyDataId xmlSecKeyDataEncryptedKeyGetKlass
                                                (void);

## Description

## Details

### 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.

### 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.

### 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_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_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_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_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_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.

### 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_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_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_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_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_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

### 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.

### 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.

### xmlSecKeyInfoCtxDestroy ()

    void        xmlSecKeyInfoCtxDestroy         (xmlSecKeyInfoCtxPtr keyInfoCtx);

Destroys keyInfoCtx object created with xmlSecKeyInfoCtxCreate 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.

### xmlSecKeyInfoCtxFinalize ()

    void        xmlSecKeyInfoCtxFinalize        (xmlSecKeyInfoCtxPtr keyInfoCtx);

Cleans up the keyInfoCtx initialized with xmlSecKeyInfoCtxInitialize function.

keyInfoCtx : | the pointer to <dsig:KeyInfo/> element processing context.

### xmlSecKeyInfoCtxReset ()

    void        xmlSecKeyInfoCtxReset           (xmlSecKeyInfoCtxPtr keyInfoCtx);

Resets the keyInfoCtx state. User settings are not changed.

keyInfoCtx : | the pointer to <dsig:KeyInfo/> element processing context.

### 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.

### 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.

### xmlSecKeyDataNameId

    #define xmlSecKeyDataNameId 		xmlSecKeyDataNameGetKlass()

The <dsig:KeyName> 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.

### xmlSecKeyDataValueId

    #define xmlSecKeyDataValueId		xmlSecKeyDataValueGetKlass()

The <dsig:KeyValue> 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.

### xmlSecKeyDataRetrievalMethodId

    #define xmlSecKeyDataRetrievalMethodId	xmlSecKeyDataRetrievalMethodGetKlass()

The <dsig:RetrievalMethod> 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.

### xmlSecKeyDataEncryptedKeyId

    #define xmlSecKeyDataEncryptedKeyId	xmlSecKeyDataEncryptedKeyGetKlass()

The <enc:EncryptedKey> processing class.

### 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.