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

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


enum xmlSecKeyUsage

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

The key usage.


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.


xmlSecKeyCreate ()

xmlSecKeyPtr xmlSecKeyCreate                (xmlSecKeyId id,
                                             xmlSecKeyOrigin origin);

Creates new key of the specified type id.


xmlSecKeyDestroy ()

void        xmlSecKeyDestroy                (xmlSecKeyPtr key);

Destroys the key and frees all allocated memory.


xmlSecKeyDuplicate ()

xmlSecKeyPtr xmlSecKeyDuplicate             (xmlSecKeyPtr key,
                                             xmlSecKeyOrigin origin);

Creates a duplicate of the given key.


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


xmlSecKeyDebugDump ()

void        xmlSecKeyDebugDump              (xmlSecKeyPtr key,
                                             FILE *output);

Prints the information about the key to the output.


xmlSecKeyReadPemCert ()

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

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


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

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

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


xmlSecFindKeyCallback ()

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

Searches the keys manager for specified key.


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.


xmlSecX509VerifyCallback ()

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

Validates certificate.


xmlSecKeysMngrGetKey ()

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

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