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.