1 /** 

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

     3  *

     4  * <dsig:KeyInfo> element processing 

     5  * (http://www.w3.org/TR/xmlSec-core/#sec-KeyInfo:

     6  *

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

     8  * distribution for preciese wording.

     9  * 

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

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

    12  */

    13 #ifndef __XMLSEC_KEYINFO_H__

    14 #define __XMLSEC_KEYINFO_H__    

    15 

    16 #ifdef __cplusplus

    17 extern "C" {

    18 #endif /* __cplusplus */ 

    19 

    20 #include <time.h>

    21 

    22 #include <libxml2_tree.h>

    23 #include "xmlsec_config.h"

    24 #include "xmlsec_xmlsec.h"

    25 #include "xmlsec_list.h"

    26 #include "xmlsec_keysdata.h"

    27 #include "xmlsec_keys.h"

    28 #include "xmlsec_transforms.h"

    29 

    30 /**

    31  * Hi level functions

    32  */

    33 XMLSEC_EXPORT int	 	xmlSecKeyInfoNodeRead		(xmlNodePtr keyInfoNode,

    34 								 xmlSecKeyPtr key,

    35 								 xmlSecKeyInfoCtxPtr keyInfoCtx);

    36 XMLSEC_EXPORT int 		xmlSecKeyInfoNodeWrite		(xmlNodePtr keyInfoNode,

    37 								 xmlSecKeyPtr key,

    38 								 xmlSecKeyInfoCtxPtr keyInfoCtx);

    39 

    40 /** 

    41  * xmlSecKeyInfoMode:

    42  * @xmlSecKeyInfoModeRead: read <dsig:KeyInfo /> element.

    43  * @xmlSecKeyInfoModeWrite: write <dsig:KeyInfo /> element.

    44  *

    45  * The @xmlSecKeyInfoCtx operation mode (read or write).

    46  */

    47 typedef enum {

    48     xmlSecKeyInfoModeRead = 0,

    49     xmlSecKeyInfoModeWrite

    50 } xmlSecKeyInfoMode;

    51 

    52 /**

    53  * XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND:

    54  *

    55  * If flag is set then we will continue reading <dsig:KeyInfo /> 

    56  * element even when key is already found.

    57  */

    58 #define XMLSEC_KEYINFO_FLAGS_DONT_STOP_ON_KEY_FOUND		0x00000001

    59 

    60 /**

    61  * XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD:

    62  *

    63  * If flag is set then we abort if an unknown <dsig:KeyInfo /> 

    64  * child is found.

    65  */

    66 #define XMLSEC_KEYINFO_FLAGS_STOP_ON_UNKNOWN_CHILD		0x00000002

    67 

    68 /** 

    69  * XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN:

    70  *

    71  * If flags is set then we abort if an unknown key name 

    72  * (content of <dsig:KeyName /> element) is found.

    73  */

    74 #define XMLSEC_KEYINFO_FLAGS_KEYNAME_STOP_ON_UNKNOWN		0x00000004

    75 

    76 /** 

    77  * XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD:

    78  *

    79  * If flags is set then we abort if an unknown <dsig:KeyValue /> 

    80  * child is found.

    81  */

    82 #define XMLSEC_KEYINFO_FLAGS_KEYVALUE_STOP_ON_UNKNOWN_CHILD	0x00000008

    83 

    84 /** 

    85  * XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF:

    86  *

    87  * If flag is set then we abort if an unknown href attribute

    88  * of <dsig:RetrievalMethod /> element is found.

    89  */

    90 #define XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_UNKNOWN_HREF	0x00000010

    91 

    92 /** 

    93  * XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF:

    94  *

    95  * If flag is set then we abort if an href attribute <dsig:RetrievalMethod /> 

    96  * element does not match the real key data type.

    97  */

    98 #define XMLSEC_KEYINFO_FLAGS_RETRMETHOD_STOP_ON_MISMATCH_HREF	0x00000020

    99 

   100 /** 

   101  * XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD:

   102  *

   103  * If flags is set then we abort if an unknown <dsig:X509Data /> 

   104  * child is found.

   105  */

   106 #define XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CHILD	0x00000100

   107 

   108 /** 

   109  * XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS:

   110  * 

   111  * If flag is set then we'll load certificates from <dsig:X509Data />

   112  * element without verification.

   113  */

   114 #define XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS		0x00000200

   115 

   116 /** 

   117  * XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT:

   118  * 

   119  * If flag is set then we'll stop when we could not resolve reference

   120  * to certificate from <dsig:X509IssuerSerial />, <dsig:X509SKI /> or 

   121  * <dsig:X509SubjectName /> elements.

   122  */

   123 #define XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_UNKNOWN_CERT	0x00000400

   124 

   125 /** 

   126  * XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT:

   127  *

   128  * If the flag is set then we'll stop when <dsig:X509Data /> element

   129  * processing does not return a verified certificate.

   130  */

   131 #define XMLSEC_KEYINFO_FLAGS_X509DATA_STOP_ON_INVALID_CERT	0x00000800

   132 

   133 /** 

   134  * XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION:

   135  *

   136  * If the flag is set then we'll stop when <enc:EncryptedKey /> element

   137  * processing fails.

   138  */

   139 #define XMLSEC_KEYINFO_FLAGS_ENCKEY_DONT_STOP_ON_FAILED_DECRYPTION 0x00001000

   140 

   141 /** 

   142  * XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE:

   143  *

   144  * If the flag is set then we'll stop when we found an empty node.

   145  * Otherwise we just ignore it.

   146  */

   147 #define XMLSEC_KEYINFO_FLAGS_STOP_ON_EMPTY_NODE			0x00002000

   148 

   149 /** 

   150  * XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS:

   151  *

   152  * If the flag is set then we'll skip strict checking of certs and CRLs

   153  */

   154 #define XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS	0x00004000

   155 

   156 /**		

   157  * xmlSecKeyInfoCtx:

   158  * @userData:		the pointer to user data (xmlsec and xmlsec-crypto 

   159  *			never touch this).

   160  * @flags: 		the bit mask for flags that control processin.

   161  * @flags2: 		reserved for future.

   162  * @mode: 		do we read or write <dsig:KeyInfo /> element.

   163  * @keysMngr:		the pointer to current keys manager.

   164  * @enabledKeyData: 	the list of enabled @xmlSecKeyDataId (if list is 

   165  *			empty then all data ids are enabled).

   166  * @base64LineSize:	the max columns size for base64 encoding.

   167  * @retrievalMethodCtx: the transforms context for <dsig:RetrievalMethod />

   168  * 			element processing.

   169  * @maxRetrievalMethodLevel: the max recursion level when processing

   170  *			<dsig:RetrievalMethod /> element; default level is 1 

   171  *			(see also @curRetrievalMethodLevel).

   172  * @encCtx:		the encryption context for <dsig:EncryptedKey /> element

   173  *			processing.

   174  * @maxEncryptedKeyLevel: the max recursion level when processing 

   175  *			<enc:EncryptedKey /> element; default level is 1 

   176  *			(see @curEncryptedKeyLevel).

   177  * @certsVerificationTime: the time to use for X509 certificates verification

   178  *			("not valid before" and "not valid after" checks);

   179  *			if @certsVerificationTime is equal to 0 (default) 

   180  *			then we verify certificates against the system's 

   181  *			clock "now".

   182  * @certsVerificationDepth: the max certifications chain length (default is 9).

   183  * @pgpReserved:	reserved for PGP.

   184  * @curRetrievalMethodLevel: the current <dsig:RetrievalMethod /> element 

   185  *			processing level (see @maxRetrievalMethodLevel).

   186  * @curEncryptedKeyLevel: the current <enc:EncryptedKey /> element

   187  *			processing level (see @maxEncryptedKeyLevel).

   188  * @keyReq:		the current key requirements.

   189  * @reserved0:		reserved for the future.

   190  * @reserved1:		reserved for the future.

   191  *

   192  * The <dsig:KeyInfo /> reading or writing context.

   193  */

   194 struct _xmlSecKeyInfoCtx {

   195     void*				userData;

   196     unsigned int			flags;

   197     unsigned int			flags2;

   198     xmlSecKeysMngrPtr			keysMngr;

   199     xmlSecKeyInfoMode			mode;

   200     xmlSecPtrList			enabledKeyData;

   201     int					base64LineSize;

   202         

   203     /* RetrievalMethod */

   204     xmlSecTransformCtx			retrievalMethodCtx;

   205     int 				maxRetrievalMethodLevel;

   206 

   207 #ifndef XMLSEC_NO_XMLENC

   208     /* EncryptedKey */

   209     xmlSecEncCtxPtr			encCtx;

   210     int					maxEncryptedKeyLevel; 

   211 #endif /* XMLSEC_NO_XMLENC */

   212 	    

   213 #ifndef XMLSEC_NO_X509

   214     /* x509 certificates */

   215     time_t				certsVerificationTime;

   216     int					certsVerificationDepth;

   217 #endif /* XMLSEC_NO_X509 */

   218 

   219     /* PGP */

   220     void*				pgpReserved;	

   221         

   222     /* internal data */

   223     int 				curRetrievalMethodLevel;

   224     int					curEncryptedKeyLevel;                

   225     xmlSecKeyReq			keyReq;

   226 

   227     /* for the future */

   228     void*				reserved0;

   229     void*				reserved1;

   230 };

   231 

   232 XMLSEC_EXPORT xmlSecKeyInfoCtxPtr 	xmlSecKeyInfoCtxCreate		(xmlSecKeysMngrPtr keysMngr);

   233 XMLSEC_EXPORT void			xmlSecKeyInfoCtxDestroy		(xmlSecKeyInfoCtxPtr keyInfoCtx);

   234 XMLSEC_EXPORT int			xmlSecKeyInfoCtxInitialize	(xmlSecKeyInfoCtxPtr keyInfoCtx,

   235 									 xmlSecKeysMngrPtr keysMngr);

   236 XMLSEC_EXPORT void			xmlSecKeyInfoCtxFinalize	(xmlSecKeyInfoCtxPtr keyInfoCtx);

   237 XMLSEC_EXPORT void			xmlSecKeyInfoCtxReset		(xmlSecKeyInfoCtxPtr keyInfoCtx);

   238 XMLSEC_EXPORT int			xmlSecKeyInfoCtxCopyUserPref	(xmlSecKeyInfoCtxPtr dst,

   239 									 xmlSecKeyInfoCtxPtr src);

   240 XMLSEC_EXPORT int 			xmlSecKeyInfoCtxCreateEncCtx	(xmlSecKeyInfoCtxPtr keyInfoCtx);

   241 XMLSEC_EXPORT void			xmlSecKeyInfoCtxDebugDump	(xmlSecKeyInfoCtxPtr keyInfoCtx,

   242 									 FILE* output);

   243 XMLSEC_EXPORT void			xmlSecKeyInfoCtxDebugXmlDump	(xmlSecKeyInfoCtxPtr keyInfoCtx,

   244 									 FILE* output);

   245 /**

   246  * xmlSecKeyDataNameId

   247  *

   248  * The <dsig:KeyName> processing class.

   249  */

   250 #define xmlSecKeyDataNameId 		xmlSecKeyDataNameGetKlass()

   251 XMLSEC_EXPORT xmlSecKeyDataId 		xmlSecKeyDataNameGetKlass	(void);

   252 

   253 /**

   254  * xmlSecKeyDataValueId

   255  *

   256  * The <dsig:KeyValue> processing class.

   257  */

   258 #define xmlSecKeyDataValueId		xmlSecKeyDataValueGetKlass()

   259 XMLSEC_EXPORT xmlSecKeyDataId		xmlSecKeyDataValueGetKlass	(void);

   260 

   261 /**

   262  * xmlSecKeyDataRetrievalMethodId

   263  *

   264  * The <dsig:RetrievalMethod> processing class.

   265  */

   266 #define xmlSecKeyDataRetrievalMethodId	xmlSecKeyDataRetrievalMethodGetKlass()

   267 XMLSEC_EXPORT xmlSecKeyDataId		xmlSecKeyDataRetrievalMethodGetKlass(void);

   268 

   269 #ifndef XMLSEC_NO_XMLENC

   270 /**

   271  * xmlSecKeyDataEncryptedKeyId

   272  *

   273  * The <enc:EncryptedKey> processing class.

   274  */

   275 #define xmlSecKeyDataEncryptedKeyId	xmlSecKeyDataEncryptedKeyGetKlass()

   276 XMLSEC_EXPORT xmlSecKeyDataId		xmlSecKeyDataEncryptedKeyGetKlass(void);

   277 #endif /* XMLSEC_NO_XMLENC */

   278 

   279 #ifdef __cplusplus

   280 }

   281 #endif /* __cplusplus */

   282 

   283 #endif /* __XMLSEC_KEYINFO_H__ */

   284