XML Security Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# keys.h

## Name

keys.h -- The keys helper functions.

## Synopsis

    typedef     xmlSecKeyId;
    enum        xmlSecKeyType;
    enum        xmlSecKeyUsage;
    typedef     xmlSecKeyOrigin;
    #define     xmlSecKeyOriginDefault
    #define     xmlSecKeyOriginKeyManager
    #define     xmlSecKeyOriginKeyName
    #define     xmlSecKeyOriginKeyValue
    #define     xmlSecKeyOriginRetrievalDocument
    #define     xmlSecKeyOriginRetrievalRemote
    #define     xmlSecKeyOriginX509
    #define     xmlSecKeyOriginPGP
    #define     xmlSecKeyOriginEncryptedKey
    #define     xmlSecKeyOriginAll
    #define     xmlSecKeyIdUnknown
    struct      xmlSecKey;
    xmlSecKeyPtr xmlSecKeyCreate                (xmlSecKeyId id,
                                                 xmlSecKeyOrigin origin);
    void        xmlSecKeyDestroy                (xmlSecKeyPtr key);
    xmlSecKeyPtr xmlSecKeyDuplicate             (xmlSecKeyPtr key,
                                                 xmlSecKeyOrigin origin);
    int         xmlSecVerifyKey                 (xmlSecKeyPtr key,
                                                 const xmlChar *name,
                                                 xmlSecKeyId id,
                                                 xmlSecKeyType type);
    void        xmlSecKeyDebugDump              (xmlSecKeyPtr key,
                                                 FILE *output);
    int         xmlSecKeyReadPemCert            (xmlSecKeyPtr key,
                                                 const char *filename);
    struct      xmlSecKeysMngr;
    xmlSecKeyPtr (*xmlSecGetKeyCallback)        (xmlNodePtr keyInfoNode,
                                                 xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlSecKeyId keyId,
                                                 xmlSecKeyType type,
                                                 xmlSecKeyUsage usage,
                                                 time_t certsVerificationTime);
    xmlSecKeyPtr (*xmlSecFindKeyCallback)       (xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 const xmlChar *name,
                                                 xmlSecKeyId id,
                                                 xmlSecKeyType type,
                                                 xmlSecKeyUsage usage);
    xmlSecX509DataPtr (*xmlSecX509FindCallback) (xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlChar *subjectName,
                                                 xmlChar *issuerName,
                                                 xmlChar *issuerSerial,
                                                 xmlChar *ski,
                                                 xmlSecX509DataPtr cert);
    int         (*xmlSecX509VerifyCallback)     (xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlSecX509DataPtr cert);
    xmlSecKeyPtr xmlSecKeysMngrGetKey           (xmlNodePtr keyInfoNode,
                                                 xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlSecKeyId keyId,
                                                 xmlSecKeyType keyType,
                                                 xmlSecKeyUsage keyUsage,
                                                 time_t certsVerificationTime);

## Description

## Details

### xmlSecKeyId

    typedef const struct _xmlSecKeyIdStruct	*xmlSecKeyId;

The key id (key type information).

### enum xmlSecKeyType

    typedef enum  {
        xmlSecKeyTypePublic = 0,
        xmlSecKeyTypePrivate,
        xmlSecKeyTypeAny
    } xmlSecKeyType;

The key type (public/private).

`xmlSecKeyTypePublic` | the public key.
`xmlSecKeyTypePrivate` | the private key.
`xmlSecKeyTypeAny` | any key.

### enum xmlSecKeyUsage

    typedef enum  {
        xmlSecKeyUsageAny = 0,
        xmlSecKeyUsageSign,
        xmlSecKeyUsageVerify,
        xmlSecKeyUsageEncrypt,
        xmlSecKeyUsageDecrypt
    } xmlSecKeyUsage;

The key usage.

`xmlSecKeyUsageAny` | the key can be used in any way.
`xmlSecKeyUsageSign` | the key for signing.
`xmlSecKeyUsageVerify` | the key for signature verification.
`xmlSecKeyUsageEncrypt` | the encryption key.
`xmlSecKeyUsageDecrypt` | the decryption key.

### xmlSecKeyOrigin

    typedef long				xmlSecKeyOrigin;

The key origin (keys manager, remote document, cert, etc.).

### xmlSecKeyOriginDefault

    #define xmlSecKeyOriginDefault			0

Default origin (unknown).

### xmlSecKeyOriginKeyManager

    #define xmlSecKeyOriginKeyManager		1

The key was found in the keys manager.

### xmlSecKeyOriginKeyName

    #define xmlSecKeyOriginKeyName			2

The key was found in the keys manager via key name specified in the <dsig:KeyName> node. (useless w/o xmlSecKeyOriginKeyManager).

### xmlSecKeyOriginKeyValue

    #define xmlSecKeyOriginKeyValue			4

The key was extracted from <dsig:KeyValue> node.

### xmlSecKeyOriginRetrievalDocument

    #define xmlSecKeyOriginRetrievalDocument	8

The key was extracted thru <dsig:RetrievalMethod> pointing in the same document.

### xmlSecKeyOriginRetrievalRemote

    #define xmlSecKeyOriginRetrievalRemote		16

The key was extracted thru <dsig:RetrievalMethod> pointing to another document.

### xmlSecKeyOriginX509

    #define xmlSecKeyOriginX509			32

The key was extracted from X509 certificate in the <dsig:X509Data> node.

### xmlSecKeyOriginPGP

    #define xmlSecKeyOriginPGP			64

The PGP key from <dsig:PGPData> node. Not used.

### xmlSecKeyOriginEncryptedKey

    #define xmlSecKeyOriginEncryptedKey		128

The key was extracted from <enc:EncryptedKey> node.

### xmlSecKeyOriginAll

    #define     xmlSecKeyOriginAll

All of the above.

### xmlSecKeyIdUnknown

    #define xmlSecKeyIdUnknown 			NULL

The "unknown" id.

### struct xmlSecKey

    struct xmlSecKey {
        xmlSecKeyId				id;
        xmlSecKeyType			type;
        xmlChar				*name;
        xmlSecKeyOrigin			origin;
        xmlSecX509DataPtr			x509Data;
        void				*keyData;
    };

The key.

xmlSecKeyId `id` | the key id (xmlSecKeyId).
xmlSecKeyType `type` | the key type (private/public).
xmlChar *`name` | the key name (may be NULL).
xmlSecKeyOrigin `origin` | the key origin.
xmlSecX509DataPtr `x509Data` | the pointer to X509 cert data (if key was extracted from a cert).
void *`keyData` | key specific data.

### xmlSecKeyCreate ()

    xmlSecKeyPtr xmlSecKeyCreate                (xmlSecKeyId id,
                                                 xmlSecKeyOrigin origin);

Creates new key of the specified type `id`.

`id` : | the key id.
`origin` : | the key origins.
Returns : | the pointer to newly allocated xmlSecKey structure or NULL if an error occurs.

### xmlSecKeyDestroy ()

    void        xmlSecKeyDestroy                (xmlSecKeyPtr key);

Destroys the key and frees all allocated memory.

`key` : | the pointer to the xmlSecKey structure.

### xmlSecKeyDuplicate ()

    xmlSecKeyPtr xmlSecKeyDuplicate             (xmlSecKeyPtr key,
                                                 xmlSecKeyOrigin origin);

Creates a duplicate of the given `key`.

`key` : | the pointer to the xmlSecKey structure.
`origin` : | the key origins.
Returns : | the pointer to newly allocated xmlSecKey structure or NULL if an error occurs.

### xmlSecVerifyKey ()

    int         xmlSecVerifyKey                 (xmlSecKeyPtr key,
                                                 const xmlChar *name,
                                                 xmlSecKeyId id,
                                                 xmlSecKeyType type);

Checks whether the `key` matches the given criteria (key name is equal to `name`, key id is equal to `id`, key type is `type`).

`key` : | the pointer to the xmlSecKey structure.
`name` : | the pointer to key name (may be NULL).
`id` : | the key id (may be "any").
`type` : | the key type to write (public/private).
Returns : | 1 if the key satisfies the given criteria or 0 otherwise.

### xmlSecKeyDebugDump ()

    void        xmlSecKeyDebugDump              (xmlSecKeyPtr key,
                                                 FILE *output);

Prints the information about the `key` to the `output`.

`key` : | the pointer to the xmlSecKey structure.
`output` : | the destination FILE pointer.

### xmlSecKeyReadPemCert ()

    int         xmlSecKeyReadPemCert            (xmlSecKeyPtr key,
                                                 const char *filename);

Reads the cert from a PEM file and assigns the cert to the key.

`key` : | the pointer to the xmlSecKey structure.
`filename` : | the PEM cert file name.
Returns : | 0 on success or a negative value otherwise.

### struct xmlSecKeysMngr

    struct xmlSecKeysMngr {
        xmlSecGetKeyCallback		getKey;
        xmlSecKeyOrigin 			allowedOrigins;
        int 				maxRetrievalsLevel;
        int					maxEncKeysLevel;

        /* low level keys */
        xmlSecFindKeyCallback		findKey;
        void 				*keysData;

        /* x509 certs */
        int					failIfCertNotFound;
        xmlSecX509FindCallback		findX509;
        xmlSecX509VerifyCallback		verifyX509;
        void				*x509Data;
    };

The keys manager structure.

xmlSecGetKeyCallback `getKey` | the callback used to read <dsig:KeyInfo> node.
xmlSecKeyOrigin `allowedOrigins` | the allowed origins bits mask.
int `maxRetrievalsLevel` | the max allowed <dsig:RetrievalMethod> level to prevent DOS attack.
int `maxEncKeysLevel` | the max allowed <enc:EncryptedKey> level to prevent DOS attack.
xmlSecFindKeyCallback `findKey` | the callback used to serach for key in the keys manager.
void *`keysData` | the keys manager data.
int `failIfCertNotFound` | the flag.
xmlSecX509FindCallback `findX509` | the callback used to search for a cert.
xmlSecX509VerifyCallback `verifyX509` | the callback used to verify a cert.
void *`x509Data` | the X509 certificates manager specific data.

### xmlSecGetKeyCallback ()

    xmlSecKeyPtr (*xmlSecGetKeyCallback)        (xmlNodePtr keyInfoNode,
                                                 xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlSecKeyId keyId,
                                                 xmlSecKeyType type,
                                                 xmlSecKeyUsage usage,
                                                 time_t certsVerificationTime);

Reads the <dsig:KeyInfo> node `keyInfoNode` and extracts the key.

`keyInfoNode` : | the pointer to <dsig:KeyInfo> node.
`mngr` : | the keys manager.
`context` : | the pointer to application specific data.
`keyId` : | the required key Id (or NULL for "any").
`type` : | the required key (may be "any").
`usage` : | the required key usage.
`certsVerificationTime` : |
Returns : | the pointer to key or NULL if the key is not found or an error occurs.

### xmlSecFindKeyCallback ()

    xmlSecKeyPtr (*xmlSecFindKeyCallback)       (xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 const xmlChar *name,
                                                 xmlSecKeyId id,
                                                 xmlSecKeyType type,
                                                 xmlSecKeyUsage usage);

Searches the keys manager for specified key.

`mngr` : | the keys manager.
`context` : | the pointer to application specific data.
`name` : | the required key name (or NULL for "any").
`id` : | the required key Id (or NULL for "any").
`type` : | the required key (may be "any").
`usage` : | the required key usage.
Returns : | the pointer to key or NULL if the key is not found or an error occurs.

### xmlSecX509FindCallback ()

    xmlSecX509DataPtr (*xmlSecX509FindCallback) (xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlChar *subjectName,
                                                 xmlChar *issuerName,
                                                 xmlChar *issuerSerial,
                                                 xmlChar *ski,
                                                 xmlSecX509DataPtr cert);

Searches for matching certificate in the keys manager.

`mngr` : | the keys manager.
`context` : | the pointer application specific data.
`subjectName` : | the subject name string.
`issuerName` : | the issuer name string.
`issuerSerial` : | the issuer serial.
`ski` : | the SKI string.
`cert` : | the current X509 certs data (may be NULL).
Returns : | the pointer to certificate that matches given criteria or NULL if an error occurs or certificate not found.

### xmlSecX509VerifyCallback ()

    int         (*xmlSecX509VerifyCallback)     (xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlSecX509DataPtr cert);

Validates certificate.

`mngr` : | the keys manager.
`context` : | the pointer to application specific data.
`cert` : | the cert to verify.
Returns : | 1 if the cert is trusted, 0 if it is not trusted and -1 if an error occurs.

### xmlSecKeysMngrGetKey ()

    xmlSecKeyPtr xmlSecKeysMngrGetKey           (xmlNodePtr keyInfoNode,
                                                 xmlSecKeysMngrPtr mngr,
                                                 void *context,
                                                 xmlSecKeyId keyId,
                                                 xmlSecKeyType keyType,
                                                 xmlSecKeyUsage keyUsage,
                                                 time_t certsVerificationTime);

Reads the <dsig:KeyInfo> node `keyInfoNode` and extracts the key.

`keyInfoNode` : | the pointer to <dsig:KeyInfo> node.
`mngr` : | the keys manager.
`context` : | the pointer to application specific data.
`keyId` : | the required key Id (or NULL for "any").
`keyType` : | the required key (may be "any").
`keyUsage` : | the required key usage.
`certsVerificationTime` : |
Returns : | the pointer to key or NULL if the key is not found or an error occurs.

<<< Previous Page | Home | Up | Next Page >>>
keyinfo.h | keysmngr.h