1 /** 

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

     3  *

     4  * Keys.

     5  *

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

     7  * distribution for preciese wording.

     8  * 

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

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

    11  */

    12 #ifndef __XMLSEC_KEYS_H__

    13 #define __XMLSEC_KEYS_H__    

    14 

    15 #ifdef __cplusplus

    16 extern "C" {

    17 #endif /* __cplusplus */ 

    18 

    19 #include <time.h>

    20 

    21 #include "xmlsec_config.h"

    22 

    23 #include "xmlsec_xmlsec.h"

    24 #include "xmlsec_list.h"

    25 #include "xmlsec_keysdata.h"

    26 

    27 

    28 /**

    29  * xmlSecKeyUsage:

    30  *

    31  * The key usage.

    32  */

    33 typedef unsigned int 			xmlSecKeyUsage;

    34 

    35 /**

    36  * xmlSecKeyUsageSign:

    37  * 

    38  * Key can be used in any way.

    39 

    40  */

    41 #define	xmlSecKeyUsageSign		0x00000001

    42 

    43 /**

    44  * xmlSecKeyUsageVerify:

    45  *

    46  * Key for signing.

    47  */

    48 #define	xmlSecKeyUsageVerify		0x00000002

    49 

    50 /**

    51  * xmlSecKeyUsageEncrypt:

    52  *

    53  * Key for signature verification.

    54  */

    55 #define	xmlSecKeyUsageEncrypt		0x00000004

    56 

    57 /**

    58  * xmlSecKeyUsageDecrypt:

    59  *

    60  * An encryption key.

    61  */

    62 #define	xmlSecKeyUsageDecrypt		0x00000008

    63 

    64 /**

    65  * xmlSecKeyUsageKeyExchange:

    66  *

    67  * The key is used for key exchange.

    68  */

    69 #define	xmlSecKeyUsageKeyExchange	0x00000010

    70 

    71 /**

    72  * xmlSecKeyUsageAny:

    73  *

    74  * A decryption key.

    75  */

    76 #define	xmlSecKeyUsageAny		0xFFFFFFFF

    77 

    78 

    79 /**************************************************************************

    80  *

    81  * xmlSecKeyUseWith

    82  *

    83  *************************************************************************/

    84 typedef struct _xmlSecKeyUseWith		xmlSecKeyUseWith, *xmlSecKeyUseWithPtr; 

    85 XMLSEC_EXPORT int	xmlSecKeyUseWithInitialize		(xmlSecKeyUseWithPtr keyUseWith);

    86 XMLSEC_EXPORT void	xmlSecKeyUseWithFinalize		(xmlSecKeyUseWithPtr keyUseWith);

    87 XMLSEC_EXPORT void	xmlSecKeyUseWithReset			(xmlSecKeyUseWithPtr keyUseWith);

    88 XMLSEC_EXPORT int	xmlSecKeyUseWithCopy			(xmlSecKeyUseWithPtr dst,

    89 								 xmlSecKeyUseWithPtr src);

    90 XMLSEC_EXPORT xmlSecKeyUseWithPtr xmlSecKeyUseWithCreate	(const xmlChar* application,

    91                                                                  const xmlChar* identifier);

    92 XMLSEC_EXPORT xmlSecKeyUseWithPtr xmlSecKeyUseWithDuplicate	(xmlSecKeyUseWithPtr keyUseWith);

    93 XMLSEC_EXPORT void	xmlSecKeyUseWithDestroy			(xmlSecKeyUseWithPtr keyUseWith);

    94 XMLSEC_EXPORT int	xmlSecKeyUseWithSet			(xmlSecKeyUseWithPtr keyUseWith,

    95 								 const xmlChar* application,

    96                                                                  const xmlChar* identifier);

    97 XMLSEC_EXPORT void	xmlSecKeyUseWithDebugDump		(xmlSecKeyUseWithPtr keyUseWith,

    98 								 FILE* output);

    99 XMLSEC_EXPORT void	xmlSecKeyUseWithDebugXmlDump		(xmlSecKeyUseWithPtr keyUseWith,

   100 								 FILE* output);

   101 

   102 /**

   103  * xmlSecKeyUseWith:

   104  * @application:        the application.

   105  * @identifier:         the identifier.

   106  *

   107  * Information about application and user of the key.

   108  */

   109 struct _xmlSecKeyUseWith {

   110     xmlChar*                    application;

   111     xmlChar*                    identifier;

   112 

   113     void*                       reserved1;

   114     void*                       reserved2;

   115 };

   116 

   117 /** 

   118  * xmlSecKeyUseWithPtrListId:

   119  * 

   120  * The keys list klass.

   121  */

   122 #define xmlSecKeyUseWithPtrListId	xmlSecKeyUseWithPtrListGetKlass()

   123 XMLSEC_EXPORT xmlSecPtrListId	xmlSecKeyUseWithPtrListGetKlass	(void);

   124 

   125 /**************************************************************************

   126  *

   127  * xmlSecKeyReq - what key are we looking for?

   128  *

   129  *************************************************************************/

   130 typedef struct _xmlSecKeyReq 			xmlSecKeyReq, *xmlSecKeyReqPtr; 

   131 

   132 /**

   133  * xmlSecKeyReq:

   134  * @keyId:		the desired key value klass.

   135  * @keyType:		the desired key type.

   136  * @keyUsage:		the desired key usage.

   137  * @keyBitsSize:	the desired key size (in bits!).

   138  * @keyUseWith:         the desired key use with application/identifier information.

   139 

   140  * The key requirements information.

   141  */

   142 struct _xmlSecKeyReq {

   143     xmlSecKeyDataId	        keyId;

   144     xmlSecKeyDataType		keyType;

   145     xmlSecKeyUsage		keyUsage;

   146     xmlSecSize			keyBitsSize;

   147     xmlSecPtrList               keyUseWithList;    

   148 

   149     void*                       reserved1;

   150     void*                       eserved2;

   151 };

   152 

   153 XMLSEC_EXPORT int	xmlSecKeyReqInitialize			(xmlSecKeyReqPtr keyReq);

   154 XMLSEC_EXPORT void	xmlSecKeyReqFinalize			(xmlSecKeyReqPtr keyReq);

   155 XMLSEC_EXPORT void	xmlSecKeyReqReset			(xmlSecKeyReqPtr keyReq);

   156 XMLSEC_EXPORT int	xmlSecKeyReqCopy			(xmlSecKeyReqPtr dst,

   157 								 xmlSecKeyReqPtr src);

   158 XMLSEC_EXPORT int	xmlSecKeyReqMatchKey			(xmlSecKeyReqPtr keyReq,

   159 								 xmlSecKeyPtr key);

   160 XMLSEC_EXPORT int	xmlSecKeyReqMatchKeyValue		(xmlSecKeyReqPtr keyReq,

   161 								 xmlSecKeyDataPtr value);

   162 XMLSEC_EXPORT void	xmlSecKeyReqDebugDump		        (xmlSecKeyReqPtr keyReq,

   163 								 FILE* output);

   164 XMLSEC_EXPORT void	xmlSecKeyReqDebugXmlDump	        (xmlSecKeyReqPtr keyReq,

   165 								 FILE* output);

   166 

   167 /**

   168  * xmlSecKey:

   169  * @name: 		the key name.

   170  * @value:		the key value.

   171  * @dataList:		the key data list.

   172  * @usage:		the key usage.

   173  * @notValidBefore:	the start key validity interval.

   174  * @notValidAfter:	the end key validity interval.

   175  *

   176  * The key.

   177  */

   178 struct _xmlSecKey {

   179     xmlChar*				name;

   180     xmlSecKeyDataPtr			value;

   181     xmlSecPtrListPtr			dataList;

   182     xmlSecKeyUsage			usage;

   183     time_t				notValidBefore;

   184     time_t				notValidAfter;    

   185 };

   186 

   187 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyCreate		(void);

   188 XMLSEC_EXPORT void		xmlSecKeyDestroy	(xmlSecKeyPtr key);

   189 XMLSEC_EXPORT void		xmlSecKeyEmpty		(xmlSecKeyPtr key);

   190 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyDuplicate	(xmlSecKeyPtr key);

   191 XMLSEC_EXPORT int		xmlSecKeyCopy		(xmlSecKeyPtr keyDst,

   192 							 xmlSecKeyPtr keySrc);

   193 

   194 XMLSEC_EXPORT const xmlChar*	xmlSecKeyGetName	(xmlSecKeyPtr key);

   195 XMLSEC_EXPORT int		xmlSecKeySetName	(xmlSecKeyPtr key,

   196 							 const xmlChar* name);

   197 

   198 XMLSEC_EXPORT xmlSecKeyDataType	xmlSecKeyGetType	(xmlSecKeyPtr key);

   199 

   200 XMLSEC_EXPORT xmlSecKeyDataPtr	xmlSecKeyGetValue	(xmlSecKeyPtr key);

   201 XMLSEC_EXPORT int		xmlSecKeySetValue	(xmlSecKeyPtr key,

   202 							 xmlSecKeyDataPtr value);

   203 

   204 XMLSEC_EXPORT xmlSecKeyDataPtr 	xmlSecKeyGetData	(xmlSecKeyPtr key, 

   205 							 xmlSecKeyDataId dataId);

   206 XMLSEC_EXPORT xmlSecKeyDataPtr 	xmlSecKeyEnsureData	(xmlSecKeyPtr key, 

   207 							 xmlSecKeyDataId dataId);

   208 XMLSEC_EXPORT int		xmlSecKeyAdoptData	(xmlSecKeyPtr key,

   209 							 xmlSecKeyDataPtr data);

   210 

   211 XMLSEC_EXPORT void		xmlSecKeyDebugDump	(xmlSecKeyPtr key,

   212 							 FILE *output);

   213 XMLSEC_EXPORT void		xmlSecKeyDebugXmlDump	(xmlSecKeyPtr key,

   214 							 FILE *output);

   215 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyGenerate	(xmlSecKeyDataId dataId,

   216 							 xmlSecSize sizeBits,

   217 							 xmlSecKeyDataType type);

   218 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyGenerateByName (const xmlChar* name,

   219 							 xmlSecSize sizeBits,

   220 							 xmlSecKeyDataType type);

   221 

   222 

   223 XMLSEC_EXPORT int		xmlSecKeyMatch		(xmlSecKeyPtr key, 

   224 							 const xmlChar *name,

   225 							 xmlSecKeyReqPtr keyReq);

   226 

   227 XMLSEC_EXPORT xmlSecKeyPtr  	xmlSecKeyReadBuffer	(xmlSecKeyDataId dataId,

   228                             				 xmlSecBuffer* buffer);

   229 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyReadBinaryFile	(xmlSecKeyDataId dataId,

   230 							 const char* filename);

   231 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyReadMemory	(xmlSecKeyDataId dataId,

   232 							 const xmlSecByte* data,

   233 							 xmlSecSize dataSize);

   234 

   235 							 

   236 /**

   237  * xmlSecKeyIsValid:

   238  * @key: the pointer to key.

   239  *

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

   241  * or 0 otherwise.

   242  */ 

   243 #define xmlSecKeyIsValid(key) \

   244 	((( key ) != NULL) && \

   245 	 (( key )->value != NULL) && \

   246 	 ((( key )->value->id) != NULL))

   247 /**

   248  * xmlSecKeyCheckId:

   249  * @key: the pointer to key.

   250  * @keyId: the key Id.

   251  *

   252  * Macro. Returns 1 if @key is valid and @key's id is equal to @keyId.

   253  */

   254 #define xmlSecKeyCheckId(key, keyId) \

   255  	(xmlSecKeyIsValid(( key )) && \

   256 	((( key )->value->id) == ( keyId )))

   257 

   258 

   259 /***********************************************************************

   260  *

   261  * Keys list

   262  *

   263  **********************************************************************/

   264 /** 

   265  * xmlSecKeyPtrListId:

   266  * 

   267  * The keys list klass.

   268  */

   269 #define xmlSecKeyPtrListId	xmlSecKeyPtrListGetKlass()

   270 XMLSEC_EXPORT xmlSecPtrListId	xmlSecKeyPtrListGetKlass		(void);

   271 

   272 #ifdef __cplusplus

   273 }

   274 #endif /* __cplusplus */

   275 

   276 #endif /* __XMLSEC_KEYS_H__ */

   277