1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<chapter id="xmlsec-notes-x509">
<title>Using X509 Certificates.</title>
<sect1 id="xmlsec-notes-x509-overview">
<title>Overview.</title>
<para>X509 certificate is one of many possible keys data object that can be
associated with a key. Application may read and write X509 data
from/to XML file. The X509 certificates management policies significantly
vary from one crypto library to another. The examples in this chapter
were tested with OpenSSL and they might be broken if anither crypto
engine is used. Check API reference documentation for more specific
information about your crypto engine.
</para>
</sect1>
<sect1 id="xmlsec-notes-sign-x509" >
<title>Signing data with X509 certificate.</title>
<para>To sign a file using X509 certificate,
an application need to associate the certificate (or certificates)
with the private key using one of the following functions:
<itemizedlist>
<listitem><para>
<link linkend="xmlSecOpenSSLAppKeyCertLoad">xmlSecOpenSSLAppKeyCertLoad</link> - loads
certificate from a file and adds to the key;
</para></listitem>
<listitem><para>
<link linkend="xmlSecOpenSSLAppPkcs12Load">xmlSecOpenSSLAppPkcs12Load</link> -
loads private key and all the certificates associated with it from a PKCS12 file;
</para></listitem>
<listitem><para>
<link linkend="xmlSecKeyAdoptData">xmlSecKeyAdoptData</link> - low level
function to add key data (including X509 key data) to the key.
</para></listitem>
</itemizedlist>
<example>
<title>Loading private key and X509 certificate.</title>
<programlisting><![CDATA[
/* load private key, assuming that there is not password */
key = xmlSecCryptoAppKeyLoad(key_file, xmlSecKeyDataFormatPem, NULL, NULL, NULL);
if(key == NULL) {
fprintf(stderr,"Error: failed to load private pem key from \"%s\"\n", key_file);
goto done;
}
/* load certificate and add to the key */
if(xmlSecCryptoAppKeyCertLoad(key, cert_file, xmlSecKeyDataFormatPem) < 0) {
fprintf(stderr,"Error: failed to load pem certificate \"%s\"\n", cert_file);
goto done;
}
]]></programlisting>
<simpara><link linkend="xmlsec-example-sign3">Full program listing</link></simpara>
</example>
</para>
<para>Next step is to prepare signature template with <dsig:X509Data/>
child of the <dsig:KeyInfo/> element. When XML Security Library finds
this node in the template, it automaticaly creates <dsig:X509Certificate/>
children of the <dsig:X509Data/> element and writes to result XML document
all the certificates associated with the signature key.
<example>
<title>Dynamicaly creating a signature template for signing document using X509 certificate.</title>
<programlisting><![CDATA[
/* create signature template for RSA-SHA1 enveloped signature */
signNode = xmlSecTmplSignatureCreate(doc, xmlSecTransformExclC14NId,
xmlSecTransformRsaSha1Id, NULL);
if(signNode == NULL) {
fprintf(stderr, "Error: failed to create signature template\n");
goto done;
}
/* add <dsig:Signature/> node to the doc */
xmlAddChild(xmlDocGetRootElement(doc), signNode);
/* add reference */
refNode = xmlSecTmplSignatureAddReference(signNode, xmlSecTransformSha1Id,
NULL, NULL, NULL);
if(refNode == NULL) {
fprintf(stderr, "Error: failed to add reference to signature template\n");
goto done;
}
/* add enveloped transform */
if(xmlSecTmplReferenceAddTransform(refNode, xmlSecTransformEnvelopedId) == NULL) {
fprintf(stderr, "Error: failed to add enveloped transform to reference\n");
goto done;
}
/* add <dsig:KeyInfo/> and <dsig:X509Data/> */
keyInfoNode = xmlSecTmplSignatureEnsureKeyInfo(signNode, NULL);
if(keyInfoNode == NULL) {
fprintf(stderr, "Error: failed to add key info\n");
goto done;
}
if(xmlSecTmplKeyInfoAddX509Data(keyInfoNode) == NULL) {
fprintf(stderr, "Error: failed to add X509Data node\n");
goto done;
}
]]></programlisting>
<simpara><link linkend="xmlsec-example-sign3">Full program listing</link></simpara>
</example>
</para>
</sect1>
<sect1 id="xmlsec-notes-verify-x509" >
<title>Verifing document signed with X509 certificates.</title>
<para>
If the document is signed with an X509 certificate then the signature
verification consist of two steps:
<itemizedlist>
<listitem><para>Creating and verifing X509 certificates chain.
</para></listitem>
<listitem><para>Verifing signature itself using key exrtacted from
a certificate verified on previous step.
</para></listitem>
</itemizedlist>
Certificates chain is constructed from certificates in a way that
each certificate in the chain is signed with previous one:
<figure>
<title>Certificates chain.</title>
<programlisting>
Certificate A (signed with B) <- Certificate B (signed with C) <- ... <- Root Certificate (signed by itself)
</programlisting>
</figure>
At the end of the chain there is a "Root Certificate" which
is signed by itself. There is no way to verify the validity of the
root certificate and application have to "trust" it
(another name for root certificates is "trusted" certificates).
</para>
<para>
Application can use <link linkend="xmlSecCryptoAppKeysMngrCertLoad">xmlSecCryptoAppKeysMngrCertLoad</link>
function to load both "trusted" and "un-trusted"
certificates. However, the selection of "trusted"
certificates is very sensitive process and this function might be
not implemented for some crypto engines. In this case, the
"trusted" certificates list is loaded during initialization
or specified in crypto engine configuration files.
Check XML Security Library API reference for more details.
<example>
<title>Loading trusted X509 certificate.</title>
<programlisting><![CDATA[
/**
* load_trusted_certs:
* @files: the list of filenames.
* @files_size: the number of filenames in #files.
*
* Creates simple keys manager and load trusted certificates from PEM #files.
* The caller is responsible for destroing returned keys manager using
* @xmlSecKeysMngrDestroy.
*
* Returns the pointer to newly created keys manager or NULL if an error
* occurs.
*/
xmlSecKeysMngrPtr
load_trusted_certs(char** files, int files_size) {
xmlSecKeysMngrPtr mngr;
int i;
assert(files);
assert(files_size > 0);
/* create and initialize keys manager, we use a simple list based
* keys manager, implement your own xmlSecKeysStore klass if you need
* something more sophisticated
*/
mngr = xmlSecKeysMngrCreate();
if(mngr == NULL) {
fprintf(stderr, "Error: failed to create keys manager.\n");
return(NULL);
}
if(xmlSecCryptoAppDefaultKeysMngrInit(mngr) < 0) {
fprintf(stderr, "Error: failed to initialize keys manager.\n");
xmlSecKeysMngrDestroy(mngr);
return(NULL);
}
for(i = 0; i < files_size; ++i) {
assert(files[i]);
/* load trusted cert */
if(xmlSecCryptoAppKeysMngrCertLoad(mngr, files[i], xmlSecKeyDataFormatPem, xmlSecKeyDataTypeTrusted) < 0) {
fprintf(stderr,"Error: failed to load pem certificate from \"%s\"\n", files[i]);
xmlSecKeysMngrDestroy(mngr);
return(NULL);
}
}
return(mngr);
}
]]></programlisting>
<simpara><link linkend="xmlsec-example-verify3">Full program listing</link></simpara>
</example>
</para>
</sect1>
</chapter>
|
