/** 

 * XML Security Library (http://www.aleksey.com/xmlsec).

 *

 * Key data.

 *

 * This is free software; see Copyright file in the source

 * distribution for preciese wording.

 * 

 * Copyright (C) 2002-2003 Aleksey Sanin <aleksey@aleksey.com>

 * Portion Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. 

 */

#ifndef __XMLSEC_KEYSDATA_H__

#define __XMLSEC_KEYSDATA_H__    

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */ 

#include "xmlsec_config.h"

#include "xmlsec_xmlsec.h"

#include "xmlsec_buffer.h"

#include "xmlsec_list.h"

/**

 * Forward declarations

 */

typedef const struct _xmlSecKeyDataKlass 		xmlSecKeyDataKlass, 

							*xmlSecKeyDataId; 						

typedef const struct _xmlSecKeyDataStoreKlass 		xmlSecKeyDataStoreKlass, 

							*xmlSecKeyDataStoreId; 

typedef struct _xmlSecKeyDataList 			xmlSecKeyDataList, 

							*xmlSecKeyDataListPtr; 

/**************************************************************************

 *

 * xmlSecKeyDataUsage

 *

 *************************************************************************/

/** 

 * xmlSecKeyDataUsage:

 *

 * The bits mask that determines possible keys data usage.

 */

typedef unsigned int					xmlSecKeyDataUsage;

/**

 * xmlSecKeyDataUsageUnknown:

 *

 * The key data usage is unknown.

 */

#define xmlSecKeyDataUsageUnknown			0x00000

/**

 * xmlSecKeyDataUsageKeyInfoNodeRead:

 *

 * The key data could be read from a <dsig:KeyInfo/> child.

 */

#define xmlSecKeyDataUsageKeyInfoNodeRead		0x00001

/**

 * xmlSecKeyDataUsageKeyInfoNodeWrite:

 *

 * The key data could be written to a <dsig:KeyInfo /> child.

 */

#define xmlSecKeyDataUsageKeyInfoNodeWrite		0x00002

/**

 * xmlSecKeyDataUsageKeyValueNodeRead:

 *

 * The key data could be read from a <dsig:KeyValue /> child.

 */

#define xmlSecKeyDataUsageKeyValueNodeRead		0x00004

/**

 * xmlSecKeyDataUsageKeyValueNodeWrite:

 *

 * The key data could be written to a <dsig:KeyValue /> child.

 */

#define xmlSecKeyDataUsageKeyValueNodeWrite		0x00008

/**

 * xmlSecKeyDataUsageRetrievalMethodNodeXml:

 *

 * The key data could be retrieved using <dsig:RetrievalMethod /> node

 * in XML format.

 */

#define xmlSecKeyDataUsageRetrievalMethodNodeXml	0x00010

/**

 * xmlSecKeyDataUsageRetrievalMethodNodeBin:

 *

 * The key data could be retrieved using <dsig:RetrievalMethod /> node

 * in binary format.

 */

#define xmlSecKeyDataUsageRetrievalMethodNodeBin	0x00020

/**

 * xmlSecKeyDataUsageAny:

 *

 * Any key data usage.

 */

#define xmlSecKeyDataUsageAny				0xFFFFF

/**

 * xmlSecKeyDataUsageKeyInfoNode:

 *

 * The key data could be read and written from/to a <dsig:KeyInfo /> child.

 */

#define xmlSecKeyDataUsageKeyInfoNode			\

	(xmlSecKeyDataUsageKeyInfoNodeRead | xmlSecKeyDataUsageKeyInfoNodeWrite)

/**

 * xmlSecKeyDataUsageKeyValueNode:

 *

 * The key data could be read and written from/to a <dsig:KeyValue /> child.

 */

#define xmlSecKeyDataUsageKeyValueNode			\

	(xmlSecKeyDataUsageKeyValueNodeRead | xmlSecKeyDataUsageKeyValueNodeWrite)

/**

 * xmlSecKeyDataUsageRetrievalMethodNode:

 *

 * The key data could be retrieved using <dsig:RetrievalMethod /> node

 * in any format.

 */

#define xmlSecKeyDataUsageRetrievalMethodNode		\

	(xmlSecKeyDataUsageRetrievalMethodNodeXml | xmlSecKeyDataUsageRetrievalMethodNodeBin)

/**************************************************************************

 *

 * xmlSecKeyDataType

 *

 *************************************************************************/

/**

 * xmlSecKeyDataType:

 *

 * The key data type (public/private, session/permanet, etc.).

 */

typedef unsigned int				xmlSecKeyDataType;

/**

 * xmlSecKeyDataTypeUnknown:

 *

 * The key data type is unknown (same as #xmlSecKeyDataTypeNone).

 */

#define xmlSecKeyDataTypeUnknown			0x0000

/**

 * xmlSecKeyDataTypeNone:

 *

 * The key data type is unknown (same as #xmlSecKeyDataTypeUnknown).

 */

#define xmlSecKeyDataTypeNone				xmlSecKeyDataTypeUnknown

/**

 * xmlSecKeyDataTypePublic:

 *

 * The key data contain a public key.

 */

#define xmlSecKeyDataTypePublic				0x0001

/**

 * xmlSecKeyDataTypePrivate:

 *

 * The key data contain a private key.

 */

#define xmlSecKeyDataTypePrivate			0x0002

/**

 * xmlSecKeyDataTypeSymmetric:

 *

 * The key data contain a symmetric key.

 */

#define xmlSecKeyDataTypeSymmetric			0x0004

/**

 * xmlSecKeyDataTypeSession:

 *

 * The key data contain session key (one time key, not stored in keys manager).

 */

#define xmlSecKeyDataTypeSession			0x0008

/**

 * xmlSecKeyDataTypePermanent:

 *

 * The key data contain permanent key (stored in keys manager).

 */

#define xmlSecKeyDataTypePermanent			0x0010

/**

 * xmlSecKeyDataTypeTrusted:

 *

 * The key data is trusted.

 */

#define xmlSecKeyDataTypeTrusted			0x0100

/**

 * xmlSecKeyDataTypeAny:

 *

 * Any key data.

 */

#define xmlSecKeyDataTypeAny				0xFFFF

/**************************************************************************

 *

 * xmlSecKeyDataFormat

 *

 *************************************************************************/

/**

 * xmlSecKeyDataFormat:

 * @xmlSecKeyDataFormatUnknown:		the key data format is unknown.

 * @xmlSecKeyDataFormatBinary:		the binary key data.

 * @xmlSecKeyDataFormatPem:		the PEM key data (cert or public/private key).

 * @xmlSecKeyDataFormatDer:		the DER key data (cert or public/private key).

 * @xmlSecKeyDataFormatPkcs8Pem:	the PKCS#8 PEM private key.

 * @xmlSecKeyDataFormatPkcs8Der:	the PKCS#8 DER private key. 

 * @xmlSecKeyDataFormatPkcs12:		the PKCS12 format (bag of keys and certs)

 * @xmlSecKeyDataFormatCertPem:		the PEM cert.

 * @xmlSecKeyDataFormatCertDer:		the DER cert.

 *

 * The key data format (binary, der, pem, etc.).

 */

typedef enum {

    xmlSecKeyDataFormatUnknown = 0,

    xmlSecKeyDataFormatBinary,

    xmlSecKeyDataFormatPem,

    xmlSecKeyDataFormatDer,

    xmlSecKeyDataFormatPkcs8Pem,

    xmlSecKeyDataFormatPkcs8Der,

    xmlSecKeyDataFormatPkcs12,

    xmlSecKeyDataFormatCertPem,

    xmlSecKeyDataFormatCertDer

} xmlSecKeyDataFormat;

/**************************************************************************

 *

 * Global xmlSecKeyDataIds methods

 *

 *************************************************************************/

XMLSEC_EXPORT xmlSecPtrListPtr	xmlSecKeyDataIdsGet		(void);

XMLSEC_EXPORT int		xmlSecKeyDataIdsInit		(void);

XMLSEC_EXPORT void		xmlSecKeyDataIdsShutdown	(void);

XMLSEC_EXPORT int 		xmlSecKeyDataIdsRegisterDefault	(void);

XMLSEC_EXPORT int 		xmlSecKeyDataIdsRegister	(xmlSecKeyDataId id);

/**************************************************************************

 *

 * xmlSecKeyData

 *

 *************************************************************************/

/**

 * xmlSecKeyData:

 * @id: 		the data id (#xmlSecKeyDataId).

 * @reserved0: 		reserved for the future.

 * @reserved1: 		reserved for the future.

 *

 * The key data: key value (crypto material), x509 data, pgp data, etc.  

 */

struct _xmlSecKeyData {

    xmlSecKeyDataId			id;

    void*				reserved0;

    void*				reserved1;

};

XMLSEC_EXPORT xmlSecKeyDataPtr	xmlSecKeyDataCreate		(xmlSecKeyDataId id);

XMLSEC_EXPORT xmlSecKeyDataPtr	xmlSecKeyDataDuplicate		(xmlSecKeyDataPtr data);

XMLSEC_EXPORT void		xmlSecKeyDataDestroy		(xmlSecKeyDataPtr data);

XMLSEC_EXPORT int		xmlSecKeyDataGenerate		(xmlSecKeyDataPtr data,

								 xmlSecSize sizeBits,

								 xmlSecKeyDataType type);

XMLSEC_EXPORT xmlSecKeyDataType	xmlSecKeyDataGetType		(xmlSecKeyDataPtr data);

XMLSEC_EXPORT xmlSecSize	xmlSecKeyDataGetSize		(xmlSecKeyDataPtr data);

XMLSEC_EXPORT const xmlChar*	xmlSecKeyDataGetIdentifier	(xmlSecKeyDataPtr data);

XMLSEC_EXPORT void		xmlSecKeyDataDebugDump		(xmlSecKeyDataPtr data,

								 FILE *output);

XMLSEC_EXPORT void		xmlSecKeyDataDebugXmlDump	(xmlSecKeyDataPtr data,

								 FILE *output);

XMLSEC_EXPORT int		xmlSecKeyDataXmlRead		(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 xmlNodePtr node,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

XMLSEC_EXPORT int		xmlSecKeyDataXmlWrite		(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 xmlNodePtr node,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

XMLSEC_EXPORT int		xmlSecKeyDataBinRead		(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 const xmlSecByte* buf,

								 xmlSecSize bufSize,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

XMLSEC_EXPORT int		xmlSecKeyDataBinWrite		(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 xmlSecByte** buf,

								 xmlSecSize* bufSize,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

/**

 * xmlSecKeyDataGetName:

 * @data: 		the pointer to key data.

 *

 * Macro. Returns the key data name.

 */

#define xmlSecKeyDataGetName(data) \

	((xmlSecKeyDataIsValid((data))) ? \

	  xmlSecKeyDataKlassGetName((data)->id) : NULL)

/**

 * xmlSecKeyDataIsValid:

 * @data: 		the pointer to data.

 *

 * Macro. Returns 1 if @data is not NULL and @data->id is not NULL

 * or 0 otherwise.

 */ 

#define xmlSecKeyDataIsValid(data) \

	((( data ) != NULL) && \

	 (( data )->id != NULL) && \

	 (( data )->id->klassSize >= sizeof(xmlSecKeyDataKlass)) && \

	 (( data )->id->objSize >= sizeof(xmlSecKeyData)) && \

	 (( data )->id->name != NULL))

/**

 * xmlSecKeyDataCheckId:

 * @data: 		the pointer to data.

 * @dataId: 		the data Id.

 *

 * Macro. Returns 1 if @data is valid and @data's id is equal to @dataId.

 */

#define xmlSecKeyDataCheckId(data, dataId) \

 	(xmlSecKeyDataIsValid(( data )) && \

	((( data )->id) == ( dataId )))

/**

 * xmlSecKeyDataCheckUsage:

 * @data: 		the pointer to data.

 * @usg: 		the data usage.

 *

 * Macro. Returns 1 if @data is valid and could be used for @usg.

 */

#define xmlSecKeyDataCheckUsage(data, usg) \

 	(xmlSecKeyDataIsValid(( data )) && \

	(((( data )->id->usage) & ( usg )) != 0))

/**

 * xmlSecKeyDataCheckSize:

 * @data: 		the pointer to data.

 * @size: 		the expected size.

 *

 * Macro. Returns 1 if @data is valid and @data's object has at least @size bytes.

 */

#define xmlSecKeyDataCheckSize(data, size) \

 	(xmlSecKeyDataIsValid(( data )) && \

	 (( data )->id->objSize >= size))

/**************************************************************************

 *

 * xmlSecKeyDataKlass

 *

 *************************************************************************/

/**

 * xmlSecKeyDataIdUnknown:

 *

 * The "unknown" id.

 */

#define xmlSecKeyDataIdUnknown 			((xmlSecKeyDataId)NULL)

/** 

 * xmlSecKeyDataInitMethod:

 * @data: 		the pointer to key data.

 *

 * Key data specific initialization method.

 *

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataInitMethod)	(xmlSecKeyDataPtr data);

/** 

 * xmlSecKeyDataDuplicateMethod:

 * @dst: 		the pointer to destination key data.

 * @src: 		the poiniter to source key data.

 *

 * Key data specific duplication (copy) method.

 *

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataDuplicateMethod)	(xmlSecKeyDataPtr dst,

								 xmlSecKeyDataPtr src);

/** 

 * xmlSecKeyDataFinalizeMethod:

 * @data: 		the data.

 *

 * Key data specific finalization method. All the objects and resources allocated

 * by the key data object must be freed inside this method.

 */

typedef void			(*xmlSecKeyDataFinalizeMethod)	(xmlSecKeyDataPtr data);

/** 

 * xmlSecKeyDataXmlReadMethod:

 * @id: 		the data id.

 * @key: 		the key.

 * @node: 		the pointer to data's value XML node.

 * @keyInfoCtx: 	the <dsig:KeyInfo/> node processing context.

 *

 * Key data specific method for reading XML node. 

 * 

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataXmlReadMethod)	(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 xmlNodePtr node,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

/** 

 * xmlSecKeyDataXmlWriteMethod:

 * @id: 		the data id.

 * @key: 		the key.

 * @node: 		the pointer to data's value XML node.

 * @keyInfoCtx: 	the <dsig:KeyInfo> node processing context.

 *

 * Key data specific method for writing XML node.

 * 

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataXmlWriteMethod)	(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 xmlNodePtr node,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

/** 

 * xmlSecKeyDataBinReadMethod:

 * @id: 		the data id.

 * @key: 		the key.

 * @buf: 		the input buffer.

 * @bufSize:		the buffer size.

 * @keyInfoCtx: 	the <dsig:KeyInfo/> node processing context.

 *

 * Key data specific method for reading binary buffer.

 * 

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataBinReadMethod)	(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 const xmlSecByte* buf,

								 xmlSecSize bufSize,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

/** 

 * xmlSecKeyDataBinWriteMethod:

 * @id: 		the data id.

 * @key: 		the key.

 * @buf: 		the output buffer.

 * @bufSize: 		the buffer size.

 * @keyInfoCtx: 	the <dsig:KeyInfo/> node processing context.

 *

 * Key data specific method for reading binary buffer. 

 * 

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataBinWriteMethod)	(xmlSecKeyDataId id,

								 xmlSecKeyPtr key,

								 xmlSecByte** buf,

								 xmlSecSize* bufSize,

								 xmlSecKeyInfoCtxPtr keyInfoCtx);

/** 

 * xmlSecKeyDataGenerateMethod:

 * @data: 		the pointer to key data.

 * @sizeBits: 		the key data specific size.

 * @type:		the required key type (session/permanent, etc.)

 *

 * Key data specific method for generating new key data.

 *

 * Returns 0 on success or a negative value if an error occurs.

 */

typedef int			(*xmlSecKeyDataGenerateMethod)	(xmlSecKeyDataPtr data,

								 xmlSecSize sizeBits,

								 xmlSecKeyDataType type);

/** 

 * xmlSecKeyDataGetTypeMethod:

 * @data:		 the data.

 *

 * Key data specific method to get the key type.

 *

 * Returns the key type.

 */

typedef xmlSecKeyDataType	(*xmlSecKeyDataGetTypeMethod)	(xmlSecKeyDataPtr data);

/** 

 * xmlSecKeyDataGetSizeMethod:

 * @data: 		the pointer to key data.

 *

 * Key data specific method to get the key size.

 *

 * Returns the key size in bits.

 */

typedef xmlSecSize		(*xmlSecKeyDataGetSizeMethod)	(xmlSecKeyDataPtr data);

/** 

 * xmlSecKeyDataGetIdentifierMethod:

 * @data: 		the pointer to key data.

 *

 * Key data specific method to get the key data identifier string (for example,

 * X509 data identifier is the subject of the verified cert).

 *

 * Returns the identifier string or NULL if an error occurs.

 */

typedef const xmlChar*		(*xmlSecKeyDataGetIdentifierMethod) (xmlSecKeyDataPtr data);

/** 

 * xmlSecKeyDataDebugDumpMethod:

 * @data: 		the data.

 * @output: 		the FILE to print debug info (should be open for writing).

 *

 * Key data specific method for printing debug info.

 */

typedef void			(*xmlSecKeyDataDebugDumpMethod)	(xmlSecKeyDataPtr data,

								 FILE* output);

/**

 * xmlSecKeyDataKlass:

 * @klassSize:		the klass size.

 * @objSize:		the object size.

 * @name:		the object name.

 * @usage:		the allowed data usage.

 * @href:		the identification string (href).

 * @dataNodeName:	the data's XML node name.

 * @dataNodeNs:		the data's XML node namespace.

 * @initialize:		the initialization method.