documentation.htm

Revision 53, 63.5 kB (checked in by lrousseau, 4 years ago)
clean HTML code (thanks to tidy(1) for the errors list)

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2	<HTML>
3	<HEAD>
4	<meta name="vs_showGrid" content="True">
5	<title>PyKCS11 Documentation - A Python wrapper for the PKCS#11 API</title>
6	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7	<style type="text/css">
8	<!--
9	.typename {
10	color: #3366FF;
11	font-weight: bold;
12	}
13	.functionname {
14	font-weight: bold;
15	color: #FF0000;
16	}
17	.codesnipet {
18	font-family: "Courier New", Courier, mono;
19	color: #006600;
20	}
21	.parametername {
22	font-weight: bold;
23	color: #0000CC;
24	}
25	-->
26	</style>
27	</HEAD>
28	<body>
29	<h1>PyKCS11, a Python wrapper for the PKCS#11 API</h1>
30	<p>Copyright (C) 2004 Midori (<a href="http:/www.paipai.net/texts/components.htm">http:/www.paipai.net/</a>)<br>
31	Verbatim copying and distribution of this entire article are permitted worldwide,
32	without royalty, in any medium, provided this notice, and the copyright notice,
33	are preserved.</p>
34	<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
35	<input type="hidden" name="cmd" value="_s-xclick">
36	<input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but04.gif" name="submit" alt="Please support free software: make a donation using PayPal.">
37	<input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----MIIHRwYJKoZIhvcNAQcEoIIHODCCBzQCAQExggEwMIIBLAIBADCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwDQYJKoZIhvcNAQEBBQAEgYAIt90Qm2jMluEGDUco0DNzzPlnCP6iFlE3RV5saEbBY3SBv+tWRC7m3/4KoUCalFT4iiL5sZH8O35/smWXHSR76LovsFpNqc4Egzte4VqOAoj8X79h6fp2Y9kQpNl1waDoQVjktA7pWHd2uxoY4i3rsi6/pekwnd570qI/hMotTDELMAkGBSsOAwIaBQAwgcQGCSqGSIb3DQEHATAUBggqhkiG9w0DBwQIW1WvEqGDmG2AgaAJfiVa+/aiKsSEQ3R+FR/E7ogpIJgtUyESEDR4UDELDH6RCk2nAw48jb0Qc1m8eXvxhMxqOcZAI73isuRx6fRletfKW8+duHJhdl/+TNyxKxxJln04cZvRZ7v2V2SXQyNkJHE60bOKBuEHfu8WQ3HWzPQzv/gpKPd9G6epTRrUt5qO8YR/vSSrZhmUSVplrUESVSGVIk5ZnxqgQRDoDrrWoIIDhzCCA4MwggLsoAMCAQICAQAwDQYJKoZIhvcNAQEFBQAwgY4xCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzEUMBIGA1UEChMLUGF5UGFsIEluYy4xEzARBgNVBAsUCmxpdmVfY2VydHMxETAPBgNVBAMUCGxpdmVfYXBpMRwwGgYJKoZIhvcNAQkBFg1yZUBwYXlwYWwuY29tMB4XDTA0MDIxMzEwMTMxNVoXDTM1MDIxMzEwMTMxNVowgY4xCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzEUMBIGA1UEChMLUGF5UGFsIEluYy4xEzARBgNVBAsUCmxpdmVfY2VydHMxETAPBgNVBAMUCGxpdmVfYXBpMRwwGgYJKoZIhvcNAQkBFg1yZUBwYXlwYWwuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDBR07d/ETMS1ycjtkpkvjXZe9k+6CieLuLsPumsJ7QC1odNz3sJiCbs2wC0nLE0uLGaEtXynIgRqIddYCHx88pb5HTXv4SZeuv0Rqq4+axW9PLAAATU8w04qqjaSXgbGLP3NmohqM6bV9kZZwZLR/klDaQGo1u9uDb9lr4Yn+rBQIDAQABo4HuMIHrMB0GA1UdDgQWBBSWn3y7xm8XvVk/UtcKG+wQ1mSUazCBuwYDVR0jBIGzMIGwgBSWn3y7xm8XvVk/UtcKG+wQ1mSUa6GBlKSBkTCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb22CAQAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQCBXzpWmoBa5e9fo6ujionW1hUhPkOBakTr3YCDjbYfvJEiv/2P+IobhOGJr85+XHhN0v4gUkEDI8r2/rNk1m0GA8HKddvTjyGw/XqXa+LSTlDYkqI8OwR8GEYj4efEtcRpRYBxV8KxAW93YDWzFGvruKnnLbDAF6VR5w/cCMn5hzGCAZowggGWAgEBMIGUMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbQIBADAJBgUrDgMCGgUAoF0wGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMDUwMjI2MTUxMTQ4WjAjBgkqhkiG9w0BCQQxFgQUGPsZ2G5YM0tEa6SekFHB15rL/1YwDQYJKoZIhvcNAQEBBQAEgYAWrGOSPBVDRLy7TQxZ3KNa4uF5jLrZcwLmQus4rsFjPmCa/QFwDlvyeFGldf96bSzfN8k+13W1eY/Hr2lSYLNMfSBGjD75Wi61PkWIpX9KEpWTuI/HnCXIlQLbDXjqSpkpEdx7Tg9a/oJv8VC5AxYanuWZ9yfKbOWcW4z5YNdQZA==-----END PKCS7-----
38	">
39	</form>
40	<p>Contents:</p>
41	<ul>
42	<li><a href="#Foreword">Foreword</a>
43	<ul>
44	<li><a href="#AboutDocumentation">About this documentation</a></li>
45	</ul>
46	</li>
47	<li><a href="#generalrules">Basic principles used to write this wrapper</a> <strong>(Python
48	and PKCS#11 gurus: start here)</strong></li>
49	<li><a href="#reference">PyKCS11 Reference</a>
50	<ul>
51	<li><a href="#how_to_call">How to call PyKCS11</a></li>
52	<li><a href="#ObjectsAndTypes">PyKCS11 Objects and Types</a></li>
53	<li><a href="#CK_ATTRIBUTE_SMARTReference">CK_ATTRIBUTE_SMART Reference</a></li>
54	<li><a href="#CPKCS11LibReference">CPKCS11Lib Reference</a>
55	<ul>
56	<li><a href="#CPKCS11LibSpecific">CPKCS11Lib specific methods
57	</a> (loading and unloading a PKCS#11 module)
58	<ul>
59	<li><a href="#Load">Load()</a></li>
60	<li><a href="#Unload">Unload()</a></li>
61	<li><a href="#notes_multiple_load">Notes on loading same Library more than once inside
62	the same process</a></li>
63	</ul>
64	</li>
65	<li><a href="#GeneralPurpose">General purpose Methods
66	</a> <ul>
67	<li><a href="#C_Initialize">C_Initialize()</a></li>
68	<li><a href="#C_Initialize">C_Finalize()</a></li>
69	<li><a href="#C_Initialize">C_GetInfo()</a></li>
70	</ul>
71	</li>
72	<li><a href="#SlotManagement">Slot management Methods
73	</a> <ul>
74	<li><a href="#C_GetSlotList">C_GetSlotList()</a></li>
75	<li><a href="#C_GetSlotInfo">C_GetSlotInfo()</a></li>
76	</ul>
77	</li>
78	<li><a href="#TokenManagement">Token management Methods </a> <ul>
79	<li><a href="#C_InitToken">C_InitToken()</a></li>
80	<li><a href="#C_GetTokenInfo">C_GetTokenInfo()</a></li>
81	<li><a href="#C_SetPin">C_SetPin()</a></li>
82	<li><a href="#C_InitPin">C_InitPin()</a></li>
83	</ul>
84	</li>
85	<li><a href="#SessionManagement">Session management Methods</a> <ul>
86	<li><a href="#C_OpenSession">C_OpenSession()</a></li>
87	<li><a href="#C_GetSessionInfo">C_GetSessionInfo()</a></li>
88	<li><a href="#C_CloseSession">C_CloseSession()</a></li>
89	<li><a href="#C_CloseAllSessions">C_CloseAllSessions()</a></li>
90	<li><a href="#C_Login">C_Login()</a></li>
91	<li><a href="#C_Logout">C_Logout()</a></li>
92	</ul>
93	</li>
94	<li><a href="#ObjectManagement%20">Object management Methods
95	</a> <ul>
96	<li><a href="#C_FindObjectsInit">C_FindObjectsInit</a>()</li>
97	<li><a href="#C_FindObjects">C_FindObjects</a>()</li>
98	<li><a href="#C_FindObjectsFinal">C_FindObjectsFinal</a>()</li>
99	<li><a href="#C_GetAttributeValue">C_GetAttributeValue</a>()</li>
100	<li><a href="#C_SetAttributeValue">C_SetAttributeValue</a>()</li>
101	<li><a href="#C_CreateObject">C_CreateObject</a>()</li>
102	<li><a href="#C_GenerateKeyPair">C_GenerateKeyPair</a>()</li>
103	<li><a href="#C_DestroyObject">C_DestroyObject</a>()</li>
104	<li><a href="#C_GetObjectSize">C_GetObjectSize</a>()</li>
105	</ul>
106	</li>
107	<li><a href="#Cryptographic">Cryptographic Methods</a> <ul>
108	<li><a href="#C_SignInit">C_SignInit</a>()</li>
109	<li><a href="#C_Sign">C_Sign</a>()</li>
110	<li><a href="#C_DecryptInit">C_DecryptInit</a>()</li>
111	<li><a href="#C_Decrypt">C_Decrypt</a>()</li>
112	<li><a href="#C_EncryptInit">C_EncryptInit</a>()</li>
113	<li><a href="#C_Encrypt">C_Encrypt</a>()</li>
114	</ul>
115	</li>
116	<li><a href="#OtherMethods">Other Methods</a></li>
117	</ul>
118	</li>
119	</ul>
120	</li>
121	</ul>
122	<p> </p>
123	<h2>Foreword<a name="Foreword"></a></h2>
124	<p>This wrapper has been generated with the help of the <a href="http://www.swig.org/"><strong>SWIG</strong></a> compiler, a wrapper
125	generator.<br>
126	Just differences from original PKCS#11 API are documented.
127	Anything not documented here can be found on the <a href="http://www.rsasecurity.com/rsalabs/node.asp?id=2133">PKCS#11
128	specification</a>.<br>
129	Please don't think about this documentation as a replacement for the PKCS#11
130	manual :)</p>
131	<p>The PKCS#11 API is very C oriented,
132	so a C++ wrapper over the original PKCS#11 API has been created<br>
133	This C++ wrapper exports the interface of
134	some PKCS#11 function in a
135	more "Python oriented" way (using stl collections, that are well
136	wrapped by SWIG and are easy to use with Python because are very
137	similar to <strong>Lists
138	and Tuples</strong>).<br>
139	The C++ has been chosen as wrapping language because SWIG supports it very
140	well.</p>
141	<p> </p>
142	<h3>About this documentation <a name="AboutDocumentation"></a></h3>
143	<p>This document <strong>ISN'T A PKCS#11 API reference replacement</strong>.
144	<strong>You</strong><em><strong> NEED</strong></em> to know most of the PKCS#11
145	API you need if you want to use <strong>PyKCS11</strong>.<br>
146	The PKCS#11 reference contained in
147	this document just shows differences between PyKCS11 and the original
148	PKCS#11 API.<br>
149	Please don't ask us how to use the PKCS#11 API, consult instead the
150	original RSA PKCS#11 documentation:<br>
151	<a href="http://www.rsasecurity.com/rsalabs">http://www.rsasecurity.com/rsalabs</a><br>
152	<a href="http://www.rsasecurity.com/rsalabs/node.asp?id=2133">http://www.rsasecurity.com/rsalabs/node.asp?id=2133</a><br>
153	<a href="ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-11/v211/pkcs-11v2-11r1.pdf">ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-11/v2-20/pkcs-11v2-20.pdf</a></p>
154	<p> </p>
155	<h2> Basic principles used to write this wrapper<a name="generalrules"></a></h2>
156	<p><br>
157	<strong>1)</strong> Since most PKCS#11 structures are read only, s<strong>trings
158	located inside such a structure</strong> (i.e. a fixed length string padded
159	with space character, <strong>not</strong> null
160	terminated) is not accessed directly, but
161	using an accessor function named <strong><font color="#FF0000">Get</font></strong><em><font color="#0000FF">TheOriginalNameOfTheStringVar</font></em>(),
162	that convert the PKCS#11 padded string to a Python string.</p>
163	<p><strong>Example:</strong><br>
164	typedef struct <span class="typename">CK_INFO</span> {<br>
165	<span class="typename">CK_VERSION</span> cryptokiVersion;<br>
166	unsigned char manufacturerID[32];<br>
167	unsigned long flags;<br>
168	unsigned char libraryDescription[32];<br>
169	<span class="typename">CK_VERSION</span> libraryVersion;<br>
170	} <span class="typename">CK_INFO</span>;<br>
171	</p>
172	<p>The <strong><em>manufacturerID</em></strong> field is accessed using the <span class="functionname"><strong>Get<em>ManufacturerI</em>D</strong></span><strong>()</strong>
173	method of a CK_INFO instance.<br>
174	The <strong><em>libraryDescription</em></strong> field is accessed using the <strong>
175	<span class="functionname">Get<em>LibraryDescription</em></span>()</strong> method of a CK_INFO instance.<br>
176	<br>
177	ckInfo =<span class="typename"> PyKCS11.CK_INFO</span>()<br>
178	...<br>
179	print "Manufacturer is: ", ckInfo.<span class="functionname"><strong>Get<em>ManufacturerI</em>D</strong></span><strong>()</strong></p>
180	<p><br>
181	<strong>2)</strong> Any <strong>string input parameter</strong> passed as
182	array/length pair is wrapped as
183	<strong>Python <span class="typename">string</span></strong></p>
184	<p>In example, the <span class="functionname">C_Login</span> function:<br>
185	<strong>C_Login's <em>original</em> prototype</strong>: <span class="functionname">C_Login</span>(<span class="typename">CK_SESSION_HANDLE</span> hSession, CK_CHAR*
186	pPin, CK_ULONG ulPinLen)<br>
187	<strong>C_Login's <em>prototype</em> in PyKCS11</strong>: <span class="functionname">C_Login</span>(<span class="typename">CK_SESSION_HANDLE</span> hSession, <span class="typename">String</span> Pin)</p>
188	<p>So in a Python script:</p>
189	<p class="codesnipet"> p11Lib = PyKCS11.CPKCS11Lib()<br>
190	# ... other P11 calls ...<br>
191	Pin = "123456"
192	<br>
193	rv = p11Lib.C_Login(PyKCS11.CKU_USER, Pin)<br>
194	print "C_Login returned ", rv</p>
195	<p><strong>3)</strong> All input and output bytes array parameters are
196	passed as
197	<span class="typename">ckbytelist</span>
198	type, instead of <STRONG>array/length pair</STRONG>.<br>
199	The <span class="typename">ckbytelist</span>
200	is much like a Python <STRONG>list</STRONG>.<br>
201	The PKCS#11 API uses a <STRONG>convention to retrieve unknown length data</STRONG>;
202	usually this convention is leaved <strong>unchanged</strong> (an exception
203	is the <strong>C_GetSlotList</strong> function).<BR>
204	<STRONG>Why that</STRONG>? This wrapper does not have the purpose to simplify
205	the usage of the PKCS#11 API inside Python. It just is a tool to
206	call the PKCS#11 in the way you would do using C (that is, the
207	extension is designed to be a PKCS#11 testing tool to create
208	test script in a simpler way).<br>
209	So, to retrieve unknown length byte array you should create an empty <span class="typename">ckbytelist</span> object;<STRONG> </STRONG>then
210	you should call the PKCS#11 function a first time:
211	this first call just returns the data length; now
212	you should call the function again using exactly same parameters
213	to retrieve actual data.</p>
214	<p><strong>4)</strong> <strong>PKCS#11 Templates</strong> (<span class="typename">CK_ATTRIBUTE</span> arrays)
215	are passed as <span class="typename">ckattrlist</span> type. The <span class="typename">ckattrlist</span> is
216	much like a Python list.<br>
217	<span class="typename">ckattrlist</span> is a list of <span class="typename">CK_ATTRIBUTE_SMART</span> structures,
218	a <span class="typename">CK_ATTRIBUTE</span> extension; <span class="typename">CK_ATTRIBUTE_SMART</span> has
219	some helper method that let you
220	set and get values using Python basic types.<br>
221	<strong>Additional notes</strong> about the <span class="functionname"><a href="#C_GetAttributeValue">C_GetAttributeValue</a></span>()
222	function, the only one that uses attribute templates as output.
223	This function should be called twice, once to know the values' length and another
224	time to retrieve actual values.</p>
225	<p><strong>5) </strong>PKCS#11 wrapped functions returns the PKCS#11 <strong>error
226	codes</strong> unchanged.
227	No exceptions are thrown while a PKCS#11 error is returned, you should
228	check return value for errors exactly as you would do in
229	C.</p>
230	<p><strong>6) </strong>All PKCS#11 <strong>defines</strong> (return codes,
231	attribute types, mechanism types, etc) are declared as <strong>constants</strong> in
232	the PyKCS11 module. The name of each constant
233	is
234	exactly the C define name (i.e. <strong>CKR_OK</strong>, <strong>CKA_LABEL</strong>, <strong>CKM_RSA_PKCS</strong>,
235	<strong>CKU_USER</strong>, etc.)</p>
236	<p> </p>
237	<h2>PyKCS11 Reference<a name="reference"></a></h2>
238	<h3>How to call PyKCS11<a name="how_to_call"></a></h3>
239	<p>PyKCS11 is composed by 2 Python modules, <strong>_PyKCS11.dll</strong> (or
240	.so, or any other Dynamic Library extension your OS uses) and <strong>PyKCS11.py</strong>.<br>
241	<strong>_PyKCS11.dll</strong> is the native code wrapper, a native
242	Python module that calls the PKCS#11 API. <strong>PyKCS11.py</strong> is
243	a pure-Python helper module that just encapsulates <strong>_PyKCS11.dll</strong> functions
244	inside nice Python <strong>objects</strong> (that is, <strong>_PyKCS11.dll</strong> interface
245	is not object oriented, while <strong>PyKCS11.py</strong> does).<br>
246	<br>
247	To call <strong>PyKCS11</strong>, you should place<strong>_PyKCS11.dll</strong> and <strong>PyKCS11.py </strong> files
248	inside the Python's libraries folder or in the script folder, then you should
249	import the <strong>PyKCS11 module</strong> in your script, i.e. like this:</p>
250	<p class="codesnipet">import PyKCS11</p>
251	<p> </p>
252	<h3>PyKCS11 Objects and Types<a name="ObjectsAndTypes"></a></h3>
253	<p>PyKCS11 module defines some custom data type, used i.e. to return session
254	and object handles, list of slots and binary data.<br>
255	There is also a group of wrappers for all PKCS#11 structures, such as
256	<span class="typename">CK_SESSION_INFO</span>.</p>
257	<table summary="CK_SESSION_INFO" width="100%" border="0" cellspacing="4" cellpadding="4">
258	<tr>
259	<td valign="top" class="typename">ck[...]list<br>
260	</td>
261	<td><p>The <span class="typename">ck[...]list</span> types are used
262	by <strong>PyKCS11</strong> to
263	receive or return collections of data. i.e. the <span class="typename">ckintlist</span> is
264	used to get
265	or pass list of numeric values, while <span class="typename">ckbytelist</span> is
266	just like a byte array and is used to pass or get binary data.<br>
267	Each <span class="typename">ck[...]list</span> type has a really
268	similar interface. You can use them as Python lists, using them
269	in iterations or accessing it
270	with []:</p>
271	<p class="codesnipet"> Example 1:<br>
272	slotList = PyKCS11.ckintlist()<br>
273	p11Lib.C_GetSlotList(0, slotList) <br>
274	for x in range(len(slotList)):<br>
275	print "SlotID:", slotList[x]</p>
276	<p class="codesnipet">Example 2:<br>
277	ToBeSignedBuffer = PyKCS11.ckintlist(1024)<br>
278	SignatureBuffer = PyKCS11.ckintlist()<br>
279	[...]<br>
280	rv = p11Lib.C_Sign(Session, ToBeSignedBuffer, SignatureBuffer)<br>
281	rv = p11Lib.C_Sign(Session,
282	ToBeSignedBuffer, SignatureBuffer)<br>
283	[...]</p>
284	<p>There is also some other method, as <span class="functionname">size</span>() and <span class="functionname">clear</span>(). Usually
285	you don't need to call that methods while using this types with <strong>PyKCS11</strong>,
286	so they are not documented (you can see them in the <strong>PyKCS11.py</strong> file)</p></td>
287	</tr>
288	<tr>
289	<td width="23%" valign="top" class="typename">ckintlist</td>
290	<td width="77%"><p>A list of numeric values. Is used to pass or get lists
291	of numeric value; i.e. is used by C_GetSlotList() to return a list
292	of available slots (as a list of SlotIDs).<br>
293	</p>
294	</td>
295	</tr>
296	<tr>
297	<td valign="top" class="typename">ckbytelist</td>
298	<td>Represents an array of bytes; is used every time a binary buffer should
299	be passed to a PKCS#11 function. Can be used as a list, so you can
300	iterate on it like this:<br>
301	<p><strong>Note</strong>: <em>to avoid the double call mechanism</em> you can use the <span class="typename">ckintlist</span>'s
302	method <span
303	class="functionname">reserve(new_list_len)</span> or you can specify an initial length when
304	you create the <span class="typename">ckintlist</span> instance:</p>
305	<p class="codesnipet">ToBeSignedBuffer = PyKCS11.ckbytelist(1024)<br>
306	SignatureBuffer = PyKCS11.ckbytelist()<br>
307	# fills the ToBeSignedBuffer<br>
308	SignatureBuffer.reserve(128)<br>
309	rv = p11Lib.C_Sign(Session,ToBeSignedBuffer, SignatureBuffer)<br>
310	[...]<br>
311	<br>
312	</p></td>
313	</tr>
314	<tr>
315	<td valign="top" class="typename">ckattrlist</td>
316	<td>Represents an array of <span class="typename">CK_ATTRIBUTE_SMART</span> objects.
317	Is used every time a PKCS#11 Template is involved. The <a href="#C_GetAttributeValue">C_GetAttributeValue</a>()
318	function is the <strong>only</strong> one that use this type as <strong>output</strong>.</td>
319	</tr>
320	<tr>
321	<td valign="top" class="typename">CK_ATTRIBUTE_SMART</td>
322	<td><p>Is an extension for the PKCS#11 structure CK_ATTRIBUTE.
323	The CK_ATTRIBUTE structure (se
324	also PKCS#11 templates) is widely used in the PKCS#11 API to
325	set or
326	get Object's
327	attributes or while creating objects or generating keys. A CK_ATTRIBUTE
328	can contain any type of value as internally it is stored ad a
329	byte array.<br>
330	Since CK_ATTRUBUTE structure is very C oriented, this wrapper was
331	created to let assign or get variables in a more friendly way;
332	it extends the
333	CK_ATTRIBUTE type adding some helper function that let you set
334	or get the internal
335	CK_ATTRIBUTE value
336	using Python basic types, such as numeric, string and tuple.<br>
337	Please see <a href="#CK_ATTRIBUTE_SMARTReference">next paragraph</a> for a complete <span class="typename">CK_ATTRIBUTE_SMART</span> interface
338	reference.</p>
339	</td>
340	</tr>
341	<tr>
342	<td valign="top" class="typename">CK_VERSION</td>
343	<td>See the PKCS#11 API reference</td>
344	</tr>
345	<tr>
346	<td valign="top" class="typename">CK_INFO</td>
347	<td>The manufacturerID and libraryDescription fields can be accessed using
348	<span class="functionname">GetManufacturerID</span>() and <span class="functionname">GetLibraryVersion</span>() methods. For more details
349	about this structure please consult the PKCS#11 API reference.</td>
350	</tr>
351	<tr>
352	<td valign="top" class="typename">CK_SLOT_INFO</td>
353	<td>The manufacturerID, slotDescription, hardwareVersion and firmwareVersion
354	fields can be accessed using <span class="functionname">GetManufacturerID</span>(), <span class="functionname">GetSlotDescription</span>(),
355	<span class="functionname">GetHardwareVersion</span>() and <span class="functionname">GetFirmwareVersion</span>() methods.
356	For more details
357	about this structure please consult the PKCS#11 API reference.</td>
358	</tr>
359	<tr>
360	<td valign="top" class="typename">CK_TOKEN_INFO</td>
361	<td>The manufacturerID, model and firmwareVersion
362	fields can be accessed using <span class="functionname">GetManufacturerID</span>(), <span class="functionname">GetModel</span>()
363	and <span class="functionname">GetFirmwareVersion</span>() methods. For
364	more details about this structure please consult the PKCS#11 API reference.</td>
365	</tr>
366	<tr>
367	<td valign="top" class="typename">CK_SESSION_INFO</td>
368	<td>See the PKCS#11 API reference</td>
369	</tr>
370	<tr>
371	<td valign="top" class="typename">CK_DATE</td>
372	<td>The year, month and day fields can be accessed using <span class="functionname">GetYear</span>(), <span class="functionname">GetMonth</span>()
373	and <span class="functionname">GetDay</span>() methods. For
374	more details about this structure please consult the PKCS#11 API reference.</td>
375	</tr>
376	<tr>
377	<td valign="top" class="typename">CK_MECHANISM</td>
378	<td>See the PKCS#11 API reference</td>
379	</tr>
380	<tr>
381	<td valign="top" class="typename">CK_MECHANISM_INFO</td>
382	<td>See the PKCS#11 API reference</td>
383	</tr>
384	</table>
385	<h3><br>
386	<br>
387	CK_ATTRIBUTE_SMART Reference<a name="CK_ATTRIBUTE_SMARTReference"></a><br>
388	</h3>
389	<p><span class="typename">CK_ATTRIBUTE_SMART</span> Methods:</p>
390	<table summary="CK_ATTRIBUTE_SMART" width="100%" border="0" cellspacing="0" cellpadding="0">
391	<tr>
392	<td width="24%" class="functionname">Reset()</td>
393	<td width="76%">Make the object instance empty: reset the value and the
394	type</td>
395	</tr>
396	<tr>
397	<td class="functionname">ResetValue()</td>
398	<td>Just make the value empty, leaving the type unchanged.</td>
399	</tr>
400	<tr>
401	<td class="functionname">Reserve(numeric <span class="parametername">len</span>)</td>
402	<td>Allocates enough space to store a number of bytes specified in the
403	<span class="parametername">len</span> parameter.</td>
404	</tr>
405	<tr>
406	<td class="functionname">GetType()</td>
407	<td>Returns the Attribute Type (look for CK_ATTRIBUTE_TYPE in the PKCS#11
408	API Reference)</td>
409	</tr>
410	<tr>
411	<td class="functionname">SetType()</td>
412	<td>Set the Attribute Type</td>
413	</tr>
414	<tr>
415	<td class="functionname">GetLen()</td>
416	<td>Get the Attribute size expressed in bytes</td>
417	</tr>
418	<tr>
419	<td class="functionname">IsString()</td>
420	<td>Returns true if the value contained is a string (the type contained
421	is detected using the Attribute Type value)</td>
422	</tr>
423	<tr>
424	<td class="functionname">IsBool()</td>
425	<td>Returns true if the value contained is boolean (the type contained
426	is detected using the Attribute Type value)</td>
427	</tr>
428	<tr>
429	<td class="functionname">IsNum()</td>
430	<td>Returns true if the value contained is numeric (the type contained
431	is detected using the Attribute Type value)</td>
432	</tr>
433	<tr>
434	<td class="functionname">IsBin()</td>
435	<td>Returns true if the value contained isn't boolean, string or
436	numeric (equivalent to not <span class="functionname">IsNum</span>() and not <span class="functionname">IsBool</span>() and not <span class="functionname">IsString</span>()
437	)</td>
438	</tr>
439	<tr>
440	<td class="functionname">GetString()</td>
441	<td>Returns the contained value as string (no conversion is performed:
442	if the value contained is not a PKCS#11 string, invalid data may
443	be returned)</td>
444	</tr>
445	<tr>
446	<td class="functionname">SetString(string <span class="parametername">new_value</span>)</td>
447	<td>Set the Attribute value to the string <span class="parametername">new_value</span></td>
448	</tr>
449	<tr>
450	<td class="functionname">GetNum()</td>
451	<td>Returns the contained value as Numeric. Note that if the Attribute
452	doesn't contains a numeric value, always 0 is returned.</td>
453	</tr>
454	<tr>
455	<td class="functionname">SetNum(numeric <span class="parametername">new_value</span>)</td>
456	<td>Set the Attribute value to the numeric <span class="parametername">new_value</span></td>
457	</tr>
458	<tr>
459	<td class="functionname">GetBool()</td>
460	<td>Returns the contained value as Boolean. Note that if the Attribute
461	doesn't contains a Boolean value, always false is returned.</td>
462	</tr>
463	<tr>
464	<td class="functionname">SetBool()</td>
465	<td>Set the Attribute value to the boolean <span class="parametername">new_value</span></td>
466	</tr>
467	<tr>
468	<td class="functionname">GetBin()</td>
469	<td>Return the raw Attribute Value, as a tuple of byte (returns
470	a <span class="typename">ckbytelist</span> object)</td>
471	</tr>
472	<tr>
473	<td class="functionname">SetBin(list/tuple <span class="parametername">new_value</span>)</td>
474	<td>Set the Attribute value to the raw <span class="parametername">new_value</span>.
475	The <span class="parametername">new_value</span> should be a list or
476	tuple</td>
477	</tr>
478	</table>
479	<p> </p>
480	<h3>CPKCS11Lib Reference<a name="CPKCS11LibReference"></a></h3>
481	<p><strong>CPKCS11Lib</strong> represents a PKCS#11 library instance. It almost
482	exposes the complete PKCS#11 interface and some additional methods
483	as <a href="#Load">Load</a>() and <a href="#Unload">Unload</a>().</p>
484	<p><br>
485	Example of use: </p>
486	<p class="codesnipet"><br>
487	import PyKCS11</p>
488	<p class="codesnipet">p11Lib = PyKCS11.CPKCS11Lib() # creates a <strong>CPKCS11Lib</strong> instance<br>
489	lib_path = "PKCS11Lib.dll"<br>
490	info = PyKCS11.CK_INFO() # creates a CK_INFO instance<br>
491	slotInfo = PyKCS11.CK_SLOT_INFO() # creates a CK_SLOT_INFO instance<br>
492	slotList = PyKCS11.ckintlist() # creates a ckintlist instance to store the
493	SlotList<br>
494	rv = p11Lib.Load(lib_path,
495	1)<br>
496	print "Load():", rv<br>
497	rv = p11Lib.C_GetInfo(info)<br>
498	print "C_GetInfo():", rv <br>
499	print "manufacturerID:", info.GetManufacturerID()<br>
500	del info<br>
501	rv = p11Lib.C_GetSlotList(0, slotList) <br>
502	print "C_GetSlotList():", rv <br>
503	print "\tAvailable Slots: " + str(len(slotList))<br>
504	</p>
505	<p>  </p>
506	<h4>CPKCS11Lib specific methods (loading and unloading a PKCS#11 module)<a name="CPKCS11LibSpecific"></a></h4>
507	<p><strong>bool CPKCS11Lib.<span class="functionname">Load</span>(string szLib, bool bAutoCallInitialize)<a name="Load"></a></strong></p>
508	<p>Loads a PKCS#11 Library.</p>
509	<table summary="CPKCS11Lib.Load" width="100%" border="0" cellspacing="0" cellpadding="0">
510	<tr>
511	<td width="25%" bgcolor="#eeeeee"><strong>szLib</strong></td>
512	<td>The library to load (name or full path)</td>
513	</tr>
514	<tr>
515	<td width="25%" bgcolor="#eeeeee"><strong>bAutoCallInitialize</strong></td>
516	<td>Automatically calls C_Initialize(), if needed</td>
517	</tr>
518	<tr>
519	<td bgcolor="#d5ffd5">Returns</td>
520	<td>True if the load succeeded</td>
521	</tr>
522	</table>
523	<p><strong>bool CPKCS11Lib.<span class="functionname">Unload</span>()<a name="Unload"></a></strong></p>
524	<p>Unloads a PKCS#11 Library.</p>
525	<table summary="CPKCS11Lib.Unload" width="100%" border="0" cellspacing="0" cellpadding="0">
526	<tr>
527	<td width="25%" bgcolor="#d5ffd5">Returns</td>
528	<td>Nothing</td>
529	</tr>
530	</table>
531	<p class="codesnipet">Example of use:<br>
532	import PyKCS11 <br>
533	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
534	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
535	...<br>
536	if bLoadResult: p11.Unload()</p>
537	<h4>Notes on loading same Library more than once inside the same process<a name="notes_multiple_load"></a></h4>
538	<p><strong>Abstract of what follows</strong>: PKCS#11 API is not designed to
539	be used by different modules that runs inside a single process,
540	if that modules doesn't
541	are aware of each other presence!</p>
542	<p><strong>PyKCS11</strong> is able to load same PKCS#11 Library<em> more than
543	once </em>in a transparent
544	way if you pass the <strong>bAutoCallInitialize</strong> parameter as <em>true</em>.<br>
545	PKCS#11 API says that the <span class="functionname">C_Initialize</span>()
546	<em>MUST</em> be called <em>only
547	once</em> by
548	a single process; if you call it more than once, an error is reported;
549	but this is not the problem.<br>
550	Problems begins when <span class="functionname">C_Finalize</span>() is called!
551	The library became unusable when <span class="functionname">C_Finalize</span>()
552	is called, so if you load same library more than once
553	the <span class="functionname">C_Finalize</span>() MUST be called only when
554	there is no more code that needs to use the Library.<br>
555	So, if you call the <span class="functionname">Load</span>() method using the <strong>bAutoCallInitialize</strong> parameter
556	set to <em>true</em>, the <span class="functionname">C_Finalize</span>() is called only when the last <strong>CPKCS11Lib</strong> instance
557	is deleted.<br>
558	Some issue still exists:</p>
559	<ol>
560	<li>Some <em>"other code"</em> in the process loads a
561	library and calls <span class="functionname">C_Initialize</span>() <strong>BEFORE</strong> PyKCS11
562	does. PyKCS11 would detect this scenario and never calls the <span class="functionname">C_Finalize</span>(),
563	that should be called by that <em>"other code"</em>. <br>
564	If that <em>"other code"</em> calls <span class="functionname">C_Finalize</span>()
565	while PyKCS11 is using the library, PyKCS11 detects this and calls <span class="functionname">C_Initialize</span>()
566	automatically. This avoids the invalidation of ALL
567	PyKCS11 instances, but can't avoid the invalidation of all sessions
568	and object handles (that is, all sessions are closed and all objects
569	must be searched again or recreated).</li>
570	<li>Some <em>"other code"</em> in the process loads a library
571	and calls <span class="functionname">C_Initialize</span>()
572	<strong>AFTER</strong> PyKCS11 did. This <em>"other code"</em> should
573	get an error calling <span class="functionname">C_Initialize</span>()
574	and in most cases it just doesn't works. If that <em>"other code"</em> expected
575	this error and so continue working fine, it can make a call
576	to <span class="functionname">C_Finalize</span>()
577	while PyKCS11 is using the library. PyKCS11 detects this and calls <span class="functionname">C_Initialize</span>()
578	automatically. This avoids the invalidation of ALL PyKCS11 instances,
579	but can't avoid the invalidation of all sessions and object handles
580	(that is, all sessions are closed and all objects must be searched
581	again or recreated).</li>
582	</ol>
583	<h4>General purpose Methods<a name="GeneralPurpose"></a></h4>
584	<p><strong>CK_RV CPKCS11Lib.<span class="functionname">C_Initialize</span>()<a name="C_Initialize"></a><br>
585	</strong>Initializes the loaded library. Doesn't take any parameter (the
586	original PKCS#11 takes void* parameter; NULL will be passed to the PKCS#11
587	library)<br>
588	<br>
589	<strong>CK_RV CPKCS11Lib.<span class="functionname">C_Finalize</span>()<a name="C_Finalize"></a><br>
590	</strong>Finalize the loaded library. Doesn't take any parameter (the
591	original PKCS#11 takes void* parameter; NULL will be passed to the PKCS#11
592	library)<strong><br>
593	<br>
594	CK_RV CPKCS11Lib.<span class="functionname">C_GetInfo</span>(<span class="typename">CK_INFO</span> Info)<a name="C_GetInfo"></a><br>
595	</strong>Get Library information. Can be used to detect if the library is
596	Initialized (CKR_CRYPTOKI_NOT_INITIALIZED is returned if C_Initialize
597	needs to be called)<br>
598	Takes a <span class="typename">CK_INFO</span> instance as parameter.</p>
599	<p><span class="codesnipet">Example of use:<br>
600	import PyKCS11 <br>
601	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
602	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
603	info = PyKCS11.CK_INFO()<br>
604	rv = p11.C_GetInfo(info)</span></p>
605	<p> </p>
606	<h4>Slot management Methods<a name="SlotManagement"></a></h4>
607	<p><br>
608	<strong>CK_RV CPKCS11Lib.<span class="functionname">C_GetSlotList</span> (bool <span class="parametername">TokenPresent</span>, <span class="typename">ckintlist</span> <span class="parametername">slotList</span>)</strong><a name="C_GetSlotList"></a><br>
609	Get a list of available slots. The list is placed inside the
610	<span class="parametername">slotList</span> parameter. The function
611	can be called passing a <span class="parametername">slotList</span> instance
612	of any length: it would be resized to contain the actual slot
613	list size (this is an exception to the normal behavior)<br>
614	<span class="parametername">slotList</span> parameter is used
615	instead of the pair <em>CK_SLOT_ID* pSlotList </em>and<em> CK_UNLOG
616	uCount</em> PKCS#11 original parameters.</p>
617	<p><span class="codesnipet">Example of use:<br>
618	import PyKCS11<br>
619	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
620	slotList = PyKCS11.ckintlist()<br>
621	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
622	rv = p11.C_GetSlotList(0, slotList) <br>
623	print "C_GetSlotList():", rv <br>
624	print "\tAvailable Slots: " + str(len(slotList))</span></p>
625	<p><strong><br>
626	CK_RV CPKCS11Lib.<span class="functionname">C_GetSlotInfo</span> ( int <span class="parametername">slotID</span>, <span class="typename">CK_SLOT_INFO</span> <span class="parametername">pInfo</span> )</strong><a name="C_GetSlotInfo"></a><br>
627	Get information about a slot. Accept a slot id (see <span class="functionname"><strong><a href="#C_GetSlotList">C_GetSlotList</a></strong></span>()
628	function, a value contained in the <strong><span class="parametername">slotList</span></strong> parameter),
629	and a <span class="typename"><strong>CK_SLOT_INFO</strong></span> instance.</p>
630	<p><span class="codesnipet">Example of use:<br>
631	import PyKCS11<br>
632	<span class="codesnipet">SlotInfos = PyKCS11</span>.CK_SLOT_INFO()<br>
633	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
634	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
635	rv = p11.C_GetSlotList(0, slotList) <br>
636	print "C_GetSlotList():", rv<br>
637	print "\tAvailable Slots: " + str(len(slotList))<br>
638	rv = p11.C_GetSlotInfo(</span><span class="codesnipet">slotList[0], <span class="codesnipet">SlotInfos</span>)<br>
639	print "\tSlot ", slotList[0], " name:", <span class="codesnipet">SlotInfos</span>.GetSlotDescription()<br>
640	</span><br>
641	</p>
642	<p><strong>Token management Methods<a name="TokenManagement"></a></strong></p>
643	<p><strong><br>
644	CK_RV CPKCS11Lib.<span class="functionname">C_GetTokenInfo</span> ( int <span class="parametername">slotID</span>, <span class="typename">CK_Token_INFO</span><span class="parametername"> Info</span> )</strong><a name="C_GetTokenInfo"></a><br>
645	Get information about a Token placed in a slot. Accept a slot id (see <span class="functionname"><strong><a href="#C_GetSlotList">C_GetSlotList</a></strong></span>()
646	function, a value contained in the <strong><span class="parametername">slotList</span></strong> parameter),
647	and a <span class="typename"><strong>CK_TOKEN_INFO</strong></span> instance.</p>
648	<p><span class="codesnipet">Example of use:<br>
649	import PyKCS11<br>
650	<span class="codesnipet">TokenInfos = PyKCS11</span>.CK_TOKEN_INFO()<br>
651	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
652	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
653	rv = p11.C_GetSlotList(0, slotList) <br>
654	print "C_GetSlotList():", rv<br>
655	print "\tAvailable Slots: " + str(len(slotList))<br>
656	rv = p11.C_GetTokenInfo(</span><span class="codesnipet">slotList[0], <span class="codesnipet">TokenInfos</span>)<br>
657	print "\tSlot ", slotList[0], " name:", <span class="codesnipet">TokenInfos</span>.GetSlotDescription()</span></p>
658	<p><strong>CK_RV CPKCS11Lib.<span class="functionname">C_InitToken</span>(int <span class="parametername">slotID</span>, string <span class="parametername">Pin</span>, string <span class="parametername">Label</span>)<a name="C_InitToken"></a><br>
659	</strong>Initialize a Token. Accept a slot id (see <span class="functionname"><strong><a href="#C_GetSlotList">C_GetSlotList</a></strong></span>()
660	function, a value contained in the <strong><span class="parametername">slotList</span></strong> parameter),
661	a <span class="parametername">Pin</span> and a token <span class="parametername">Label</span>.<br>
662	The original PKCS#11 function takes a pair "<em>CK_CHAR* pPin, CK_ULONG
663	uPunLen</em>", that became a Python string, passed as <span class="parametername">Pin</span> parameter;
664	and another parameter "CK_CHAR Label[32]", a fixed length string
665	padded with the blanks (ASCII space character, 0x20), that became a Python
666	string
667	passed as <span class="parametername">Label</span> parameter. <span class="parametername">Label</span> length
668	can be between 0 and 32.</p>
669	<p><strong>CK_RV CPKCS11Lib.<span class="functionname">C_InitPIN</span> (<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, string <span class="parametername">Pin</span>)</strong><a name="C_InitPIN"></a><br>
670	Initialize or reset the user Pin. Accept a session handle as first parameter
671	(<span class="parametername">hSession</span>), and a new <span class="parametername">Pin</span>.<br>
672	The
673	original PKCS#11 function takes a pair "<em>CK_CHAR* pPin, CK_ULONG
674	uPunLen</em>", that became a Python string, passed as <span class="parametername">Pin</span> parameter.</p>
675	<p> <strong>CK_RV CPKCS11Lib.<span class="functionname">C_SetPIN</span> (<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, string <span class="parametername">OldPin</span>,
676	string<span class="parametername"> NewPin</span> )<a name="C_SetPIN"></a><br>
677	</strong>Changes a Pin. Accept a session handle as first
678	parameter (<span class="parametername">hSession</span>) and the strings <span class="parametername">OldPin</span> and
679	the
680	<span class="parametername">NewPin</span>.<br>
681	The original PKCS#11 function takes a pair "<em>CK_CHAR* pOldPin, CK_ULONG
682	uOldPunLen</em>", that became a Python string, passed as <span class="parametername">OldPin</span> parameter;
683	and takes a pair "<em>CK_CHAR* pNewPin, CK_ULONG
684	uNewPunLen</em>", that became a Python string, passed as <span class="parametername">NewPin</span> parameter.</p>
685	<h4>Session management Methods<a name="SessionManagement"></a></h4>
686	<p><strong>CK_RV</strong> <strong>CPKCS11Lib</strong>.<span class="functionname">C_OpenSession</span> (int
687	<span class="parametername">slotID</span>, int <span class="parametername">flags</span>, <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">newhSession</span> ) <a name="C_OpenSession"></a></p>
688	<p>Open a new session on a Token. In the original prototype the <span class="parametername">newhSession</span> parameter
689	was a <span class="typename">CK_SESSION_HANDLE</span> pointer.</p>
690	<p><strong>CK_RV</strong> <strong>CPKCS11Lib</strong>.<span class="functionname">C_CloseSession</span>(
691	<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span> )<a name="C_CloseSession"></a></p>
692	<p>Closes a session opened using <a href="#C_OpenSession">C_OpenSession</a>.</p>
693	<p> <strong>CK_RV</strong> <strong>CPKCS11Lib</strong>.<span class="functionname">C_CloseAllSessions</span> ( int <span class="parametername">slotID</span> )<a name="C_CloseAllSessions"></a></p>
694	<p>Closes all session opened on a Token.</p>
695	<p><strong>CK_RV</strong> <strong>CPKCS11Lib</strong>.<span class="functionname">C_Login</span> (<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, int <span class="parametername">userType</span>, string <span class="parametername">Pin</span> )<a name="C_Login"></a></p>
696	<p>Login a user on all sessions open on a Token. Accept a session handle obtained
697	calling the <a href="#C_OpenSession">C_OpenSession</a> function, the type
698	of user to login and the Pin to use.</p>
699	<p> <strong>CK_RV</strong> <strong>CPKCS11Lib</strong>.<span class="functionname">C_Logout</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span> )<a name="C_Logout"></a></p>
700	<p>Logout all sessions open on a Token. Accept a session handle obtained
701	calling the <a href="#C_OpenSession">C_OpenSession</a>.</p>
702	<p><strong>CK_RV CPKCS11Lib.<span class="functionname">C_GetSessionInfo</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_SESSION_INFO</span> <span class="parametername">Info</span> )<a name="C_GetSessionInfo"></a></strong></p>
703	<p>Get some information about the specified session and copy them in the Info
704	object. In the original prototype the <strong><span class="parametername">Info</span></strong> was
705	a <strong><span class="typename">CK_SESSION_INFO</span></strong> pointer.<br>
706	<br>
707	<span class="codesnipet"><br>
708	Example of use:<br>
709	import PyKCS11<br>
710	<span class="codesnipet">TokenInfos = PyKCS11</span>.CK_TOKEN_INFO()<br>
711	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
712	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
713	rv = p11.C_GetSlotList(0, slotList) </span><span class="codesnipet"><br>
714	session = <span class="codesnipet">PyKCS11</span>.CK_SESSION_HANDLE()<br>
715	sessionInfo = <span class="codesnipet">PyKCS11</span>.CK_SESSION_INFO()<br>
716	rv = p11.C_OpenSession(</span><span class="codesnipet">slotList[0], PyKCS11.CKF_SERIAL_SESSION,
717	session)<br>
718	</span>
719	<span class="codesnipet">rv = p11.C_Login(</span><span class="codesnipet">session,
720	PyKCS11.CKU_USER,
721	"123456")</span> <br>
722	<span class="codesnipet">rv = p11.C_GetSessionInfo(</span><span class="codesnipet">session,
723	sessionInfo)<br>
724	rv = p11.C_Logout(</span><span class="codesnipet">session)</span><br>
725	<span class="codesnipet">rv = p11.C_CloseSession(</span><br>
726	</p>
727	<h4>Object management Methods<a name="ObjectManagement"></a></h4>
728	<p>
729	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_CreateObject</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">vectorattr</span> <span class="parametername">Template</span>, <span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">outhObject</span> )<strong><a name="C_CreateObject"></a></strong></p>
730	<p>This method can be used to create a new object. The Object template (that
731	is, object's attributes) is passed using the <span class="parametername">Template</span> argument,
732	while the object handle is placed in the <span class="parametername">outhObject</span> argument.
733	In the original prototype, <span class="parametername">Template</span> was
734	a pair of arguments: a CK_TEMPLATE array and a numeric length of array,
735	while <span class="parametername">outhObject</span> was
736	a <span class="typename">CK_OBJECT_HANDLE</span> pointer.<br>
737	Template is a <span class="typename">vectorattr</span> object type, a list
738	of <span class="typename">CK_ATTRIBUTE_SMART</span> objects.</p>
739	<p class="codesnipet">Example of use:<br>
740	import PyKCS11<br>
741	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
742	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
743	rv = p11.C_GetSlotList(0, slotList) <br>
744	session = PyKCS11.CK_SESSION_HANDLE()<br>
745	sessionInfo = PyKCS11.CK_SESSION_INFO()<br>
746	rv = p11.C_OpenSession(slotList[0], <span class="codesnipet">PyKCS11.</span>CKF_SERIAL_SESSION,
747	session)<br>
748	rv = p11.C_Login(session,
749	PyKCS11.CKU_USER, "123456") <br>
750	objTemplate = PyKCS11.vectorattr(4)<br>
751	objValues = PyKCS11.vectorattr(2)<br>
752	newObjValues = PyKCS11.vectorattr(1)<br>
753	hObject = PyKCS11.CK_OBJECT_HANDLE()<br>
754	objTemplate(0).SetBool(PyKCS11.CKA_TOKEN, 1)<br>
755	objTemplate(1).SetNum(PyKCS11.CKA_CLASS, PyKCS11.CKO_DATA)<br>
756	objTemplate(2).SetString(PyKCS11.CKA_LABEL, "TestDataObject")<br>
757	objTemplate(3).SetString(PyKCS11.CKA_VALUE, "This is a sample Data Object")<br>
758	rv = p11.C_CreateObject(session,
759	objTemplate, hObject)<br>
760	objValues(0).SetType(PyKCS11.CKA_MODIFIABLE)<br>
761	objValues(1).SetType(PyKCS11.CKA_PRIVATE)<br>
762	rv = p11.C_GetAttributeValue(session, hObject,
763	objValues) # first call: just get sizes<br>
764	rv = p11.C_GetAttributeValue(session,
765	hObject, objValues) # second call: get actual data<br>
766	newObjValues(0).SetString(PyKCS11.CKA_APPLICATION, "Test")<br>
767	rv = p11.C_SetAttributeValue(session, hObject, newObjValues)<br>
768	rv = p11.C_DestroyObject(session, hObject)<br>
769	rv = p11.C_Logout(session)<br>
770	rv = p11.C_CloseSession(session)</p>
771	<p>
772	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_DestroyObject</span>(<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hObject</span>)<strong><a name="C_DestroyObject"></a></strong></p>
773	<p>This function destroys an object. You specify the object to destroy passing
774	an object handle previously obtained by <a href="#C_FindObjects">C_FindObjects</a>()
775	or any object creation function, such as <a href="#C_CreateObject">C_CreateObject</a>().<br>
776	<br>
777	Example of use: see <a href="#C_CreateObject">C_CreateObject</a>(). </p>
778	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_GetObjectSize</span> (<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hObject</span>,
779	int <span class="parametername">outulSize</span>)<strong><a name="C_GetObjectSize"></a></strong></p>
780	<p>Return the size of an object. The object's size is returned in the <span class="parametername">outulSize</span> argument. In
781	the original prototype the <span class="parametername">outulSize</span> was
782	a pointer to an unsigned long.<br>
783	<br>
784	Example of use: see <a href="#C_CreateObject">C_CreateObject</a>(). </p>
785	<p>
786	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_GetAttributeValue</span> (<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>,
787	<span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hObject</span>, <span class="typename">vectorattr</span> <span class="parametername">outTemplate</span>)<strong><a name="C_GetAttributeValue"></a></strong></p>
788	<p>Get object's attributes. <span class="parametername">outTemplate</span> is
789	a <span class="typename">vectorattr</span> object type, a list
790	of <span class="typename">CK_ATTRIBUTE_SMART</span> objects. In the original
791	prototype <span class="parametername">outTemplate</span> was a pair of arguments:
792	a CK_TEMPLATE array and a numeric length of that array.<br>
793	<br>
794	Example of use: see <a href="#C_CreateObject">C_CreateObject</a>(). </p>
795	<p>
796	<br>
797	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_SetAttributeValue</span>(<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hObject</span>, <span class="typename">vectorattr</span> <span class="parametername">Template</span> )<strong><a name="C_SetAttributeValue"></a></strong></p>
798	<p>Assign new values to object's attributes. Template is
799	a <span class="typename">vectorattr</span> object type, a list of <span class="typename">CK_ATTRIBUTE_SMART</span> objects.
800	In the original prototype <span class="parametername">outTemplate</span> was
801	a pair of arguments: a CK_TEMPLATE array and a numeric length of that
802	array.<br>
803	<br>
804	Example of use: see <a href="#C_CreateObject">C_CreateObject</a>(). <br>
805	</p>
806	<p>
807	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_FindObjectsInit</span>( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">vectorattr</span> <span class="parametername">Template</span> )<a name="C_FindObjectsInit"></a></p>
808	<p>Begin a search on a session using Template as search filter. In the original
809	prototype <span class="parametername">Template</span> was a pair of arguments:
810	a CK_TEMPLATE array and a numeric length of that array.</p>
811	<p class="codesnipet">Example of use:<br>
812	import PyKCS11<br>
813	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
814	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
815	rv = p11.C_GetSlotList(0, slotList) <br>
816	session = PyKCS11.CK_SESSION_HANDLE()<br>
817	rv = p11.C_OpenSession(slotList[0], <span class="codesnipet">PyKCS11.</span>CKF_SERIAL_SESSION, session)<br>
818	rv = p11.C_Login(session, PyKCS11.CKU_USER, "123456")<br>
819	SearchResult = PyKCS11.ckintlist(10) <br>
820	searchTemplate = PyKCS11.vectorattr(2)<br>
821	searchTemplate[0].SetBool(PyKCS11.CKA_TOKEN, 1)<br>
822	searchTemplate[1].SetNum(PyKCS11.CKA_CLASS, PyKCS11.CKO_CERTIFICATE) <br>
823	rv = p11.C_FindObjectsInit(session, searchTemplate) <br>
824	rv = p11.C_FindObjects(session, SearchResult)<br>
825	rv = p11.C_FindObjectsFinal(session)<br>
826	for x in SearchResult:<br>
827	print "object " + hex(x)<br>
828	valTemplate = PyKCS11.ckattrlist(1)<br>
829	valTemplate[0].SetType(PyKCS11.CKA_LABEL)<br>
830	rv = p11.C_GetAttributeValue(session,
831	x, valTemplate)<br>
832	print "CKA_LABEL: ", valTemplate[0].GetString()<br>
833	</p>
834	<p>  </p>
835	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_FindObjects</span>( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">ckintlist</span> <span class="parametername">outObjectsList</span> )<a name="C_FindObjects"></a></p>
836	<p>Continue a search operation started by <a href="#C_FindObjectsInit">C_FindObjectsInit</a>()
837	on a session. Returns a list of object handles in the <span class="parametername">outObjectsList</span> argument.
838	In the original prototype <span class="parametername">outObjectsList</span> was
839	a pair of arguments: an array of CK_OBJECT_HANDLE and a numeric length
840	of that array.</p>
841	<p>Example of use: see <a href="#C_FindObjectsInit">C_FindObjectsInit</a>().<br>
842	</p>
843	<p>
844	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_FindObjectsFinal</span>( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span> )<a name="C_FindObjectsFinal"></a></p>
845	<p>Ends a search started on a session by <a href="#C_FindObjectsInit">C_FindObjectsInit</a>().</p>
846	<p>Example of use: see <a href="#C_FindObjectsInit">C_FindObjectsInit</a>().</p>
847	<p> </p>
848	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_GenerateKeyPair</span>(
849	<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_MECHANISM</span> <span class="parametername">Mechanism</span>,
850	<span class="typename">ckattrlist</span> <span class="parametername">PublicKeyTemplate</span>, <span class="typename">ckattrlist</span> <span class="parametername">PrivateKeyTemplate</span>,
851	<span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">outhPublicKey</span>,<br>
852	<span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">outhPrivateKey</span> )<a name="C_GenerateKeyPair"></a></p>
853	<p>Generate a new key pair using the specified templates for private and public
854	keys. The generated object handles are placed in <span class="parametername">outhPublicKey</span> and
855	<span class="parametername">outhPrivateKey</span>.<br>
856	In the original prototype <span class="parametername">PublicKeyTemplate</span>/<span class="parametername">PrivateKeyTemplate</span> was a
857	pair of arguments: an array of CK_ATTRIBUTE and a numeric length of
858	that array. While <span class="parametername">outhPublicKey/outhPrivateKey</span> was
859	a CK_OBJECT_HANDLE pointer.</p>
860	<p>Example of use: the use of this function is very similar to <a href="#C_CreateObject">C_CreateObject</a>().</p>
861	<h4> </h4>
862	<h4>Cryptographic Methods<a name="Cryptographic"></a></h4>
863	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_SignInit</span>( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_MECHANISM</span> <span class="parametername">Mechanism</span>, <span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hKey</span> )<a name="C_SignInit"></a></p>
864	<p>Start a signature on a session using the specified key.</p>
865	<p>Example of use: see <a href="#C_Sign">C_Sign</a>(). </p>
866	<p> <strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_Sign</span>(
867	<span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">ckbytelist</span> <span class="parametername">inData</span>,
868	<span class="typename">ckbytelist</span> <span class="parametername">outSignature</span> )<a name="C_Sign"></a></p>
869	<p>Perform a signature operation. <span class="parametername">inData</span> contains
870	the data to sign; after a successful call <span class="parametername">outSignature</span> should
871	contain the signed data.<br>
872	In the original prototype <span class="parametername">inData</span> was
873	a pair of arguments: an array of CK_BYTE and a numeric length of that array;
874	while <span class="parametername">outSignature</span> was another pair of
875	arguments: an array of CK_BYTE and a numeric length of that array used
876	to pass array
877	size and to get actual data length.<br>
878	</p>
879	<p class="codesnipet">Example of use:<br>
880	import PyKCS11<br>
881	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
882	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
883	rv = p11.C_GetSlotList(0, slotList) <br>
884	session = PyKCS11.CK_SESSION_HANDLE()<br>
885	rv = p11.C_OpenSession(slotList[0], <span class="codesnipet">PyKCS11.</span>CKF_SERIAL_SESSION,
886	session)<br>
887	rv = p11.C_Login(session, PyKCS11.CKU_USER, "123456")<br>
888	SearchResult = PyKCS11.ckintlist(10) <br>
889	searchTemplate = PyKCS11.vectorattr(2)<br>
890	searchTemplate[0].SetBool(PyKCS11.CKA_TOKEN, 1)<br>
891	searchTemplate[1].SetNum(PyKCS11.CKA_CLASS, PyKCS11.CKO_PRIVATE_KEY) <br>
892	rv = p11.C_FindObjectsInit(session, searchTemplate) <br>
893	rv = p11.C_FindObjects(session, SearchResult)<br>
894	rv = p11.C_FindObjectsFinal(session)<br>
895	DataToSign = PyKCS11.ckbytelist(5)<br>
896	Signature = PyKCS11.ckbytelist() <br>
897	DataToSign[0] = 1<br>
898	DataToSign[1] = 2<br>
899	DataToSign[2] = 3<br>
900	DataToSign[3] = 4<br>
901	DataToSign[4] = 5<br>
902	Mechanism = PyKCS11.CK_MECHANISM()<br>
903	Mechanism.mechanism = PyKCS11.CKM_RSA_PKCS<br>
904	for x in SearchResult:<br>
905	rv = p11.C_SignInit(session, Mechanism, x)<br>
906	rv = p11.C_Sign(session, DataToSign, Signature) # first
907	call get size<br>
908	rv = p11.C_Sign(session, DataToSign, Signature) # second
909	call get the signature</p>
910	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_DecryptInit</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_MECHANISM</span> <span class="parametername">Mechanism</span>, <span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hKey</span>) <a name="C_DecryptInit"></a></p>
911	<p>Start a decryption on a session using the specified key.</p>
912	<p>Example of use: see <a href="#C_Decrypt">C_Decrypt</a>(). </p>
913	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_Decrypt</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>,
914	<span class="typename">ckbytelist</span> <span class="parametername">inEncryptedData</span>, <span class="typename">ckbytelist</span> <span class="parametername">outData</span> )<a name="C_Decrypt"></a></p>
915	<p>Perform a decryption on the specified session. <span class="parametername">inEncryptedData</span> is
916	the data to decrypt, <span class="parametername">outData</span> is where the
917	decrypted data would be placed.<br>
918	In the original prototype <span class="parametername">inEncryptedData</span> was
919	a pair of arguments: an array of CK_BYTE and a numeric length of that array;
920	while <span class="parametername">outData</span> was
921	another pair of arguments: an array of CK_BYTE and a numeric
922	length of that array used to pass array size and to get actual data length.</p>
923	<p class="codesnipet">Example of use:<br>
924	import PyKCS11<br>
925	p11 = PyKCS11.CPKCS11Lib() #create a lib instance<br>
926	bLoadResult = p11.Load("p11lib.dll", true) #load a lib and calls C_Initialize.<br>
927	rv = p11.C_GetSlotList(0, slotList) <br>
928	session = PyKCS11.CK_SESSION_HANDLE()<br>
929	rv = p11.C_OpenSession(slotList[0], <span class="codesnipet">PyKCS11.</span>CKF_SERIAL_SESSION, session)<br>
930	rv = p11.C_Login(session, PyKCS11.CKU_USER, "123456")<br>
931	SearchResult = PyKCS11.ckintlist(10) <br>
932	searchTemplate = PyKCS11.vectorattr(2)<br>
933	searchTemplate[0].SetBool(PyKCS11.CKA_TOKEN, 1)<br>
934	searchTemplate[1].SetNum(PyKCS11.CKA_CLASS, PyKCS11.CKO_PRIVATE_KEY) <br>
935	rv = p11.C_FindObjectsInit(session, searchTemplate) <br>
936	rv = p11.C_FindObjects(session, SearchResult)<br>
937	rv = p11.C_FindObjectsFinal(session)<br>
938	DataToDecrypt =
939	PyKCS11.ckbytelist(128)<br>
940	DecryptedData = PyKCS11.ckbytelist() <br>
941	# ... fill the
942	DataToDecrypt variable<br>
943	Mechanism = PyKCS11.CK_MECHANISM()<br>
944	Mechanism.mechanism = PyKCS11.CKM_RSA_PKCS<br>
945	for x in SearchResult:<br>
946	rv = p11.C_DecryptInit(session, Mechanism, x)<br>
947	rv = p11.C_Decrypt(session, DataToDecrypt, DecryptedData) #
948	first call get the size<br>
949	rv = p11.C_Decrypt(session, DataToDecrypt, DecryptedData) #
950	second call get the data<br>
951	<strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_EncryptInit</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">CK_MECHANISM</span> <span class="parametername">Mechanism</span>,
952	<span class="typename">CK_OBJECT_HANDLE</span> <span class="parametername">hKey</span> )<a name="C_EncryptInit"></a></p>
953	<p>Start an encryption on a session using the specified key.</p>
954	<p>Example of use: see <a href="#C_Encrypt">C_Encrypt</a>().</p>
955	<p> </p>
956	<p><strong>CK_RV CPKCS11Lib.</strong><span class="functionname">C_Encrypt</span> ( <span class="typename">CK_SESSION_HANDLE</span> <span class="parametername">hSession</span>, <span class="typename">ckbytelist</span> <span class="parametername">inData</span>, <span class="typename">ckbytelist</span> <span class="parametername">outEncryptedData</span> )<a name="C_Encrypt"></a></p>
957	<p>Perform an encryption on the specified session. <span class="parametername">inData</span> is
958	the data to decrypt, <span class="parametername">outEncryptedData</span> is where
959	the decrypted data would be placed.<br>
960	In the original prototype <span class="parametername">inData</span> was
961	a pair of arguments: an array of CK_BYTE and a numeric length of that array;
962	while <span class="parametername">outEncryptedData</span> was another pair of arguments:
963	an array of CK_BYTE and a numeric length of that array used to pass array size
964	and to get actual data length.</p>
965	<p>Example of use: the usage is very similar to <a href="#C_Decrypt">C_Encrypt</a>().</p>
966	<p> </p>
967	<h4>Other Methods<a name="OtherMethods"></a></h4>
968	<p>This reference ends here.<br>
969	We think that the above documentation is enough
970	to understand how to use all function of this wrapper; if you
971	need to know how to use other methods, please see the <a href="#generalrules">basic
972	principles used to create this wrapper</a> and the official PKCS#11 manual
973	from RSA.</p>
974	<p> </p>
975	<p>Copyright (C) 2004 Midori (<a href="http:/www.paipai.net/texts/components.htm">http:/www.paipai.net/</a>)<br>
976	Verbatim copying and distribution of this entire article are permitted worldwide,
977	without royalty, in any medium, provided this notice, and the copyright notice,
978	are preserved.</p>
979	</body>
980	</HTML>

Note: See TracBrowser for help on using the browser.

root/pykcs11/trunk/documentation.htm

Download in other formats: