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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenSC Manual Pages: Section 5</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><style type="text/css"><!--
body {
font-family: Verdana, Arial;
font-size: 0.9em;
}
.title {
font-size: 1.5em;
text-align: center;
}
.toc b {
font-size: 1.2em;
border-bottom: dashed 1px black;
}
a {
color: blue;
text-decoration: none;
}
a:visited {
color: blue;
text-decoration: none;
}
pre.programlisting {
font-size: 1.1em;
background-color: #EEEEEE ;
border: 1px solid #006600 ;
padding: 1em;
}
span.symbol {
font-weight: bold;
}
span.errorname {
font-weight: bold;
}
span.errortext {
font-style: italic;
}
--></style></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="id-1"></a>OpenSC Manual Pages: Section 5</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="refentrytitle"><a href="#opensc.conf">opensc.conf</a></span><span class="refpurpose"> — configuration file for OpenSC</span></dt><dt><span class="refentrytitle"><a href="#pkcs15-profile">pkcs15-profile</a></span><span class="refpurpose"> — format of profile for <span class="command"><strong>pkcs15-init</strong></span></span></dt></dl></div><div class="refentry"><a name="opensc.conf"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>opensc.conf — configuration file for OpenSC</p></div><div class="refsect1"><a name="id-1.2.3"></a><h2>Description</h2><p>
OpenSC obtains configuration data from the following sources in the following order
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
command-line options
</p></li><li class="listitem"><p>
environment variables
</p></li><li class="listitem"><p>
Windows registry key in
<code class="literal">HKEY_CURRENT_USER</code> (if available)
</p></li><li class="listitem"><p>
Windows registry key in
<code class="literal">HKEY_LOCAL_MACHINE</code> (if available)
</p></li><li class="listitem"><p>
system-wide configuration file
(<code class="literal">/etc/opensc.conf</code>)
</p></li></ol></div><p>
</p><p>
The configuration file, <code class="literal">opensc.conf</code>, is composed
of <em class="replaceable"><code>block</code></em>s, which, in general, have the
following format:
</p><pre class="programlisting">
<em class="replaceable"><code>key</code></em> [, <em class="replaceable"><code>name</code></em>...] {
<em class="replaceable"><code>block_contents</code></em>
}
</pre><p>
<em class="replaceable"><code>block_contents</code></em> is one or more
<em class="replaceable"><code>block_item</code></em>s where a
<em class="replaceable"><code>block_item</code></em> is one of
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
# <em class="replaceable"><code>comment string</code></em>
</p></li><li class="listitem"><p>
<em class="replaceable"><code>key</code></em> [, <em class="replaceable"><code>name</code></em>...] = <em class="replaceable"><code>value</code></em>;
</p></li><li class="listitem"><p>
<em class="replaceable"><code>block</code></em>
</p></li></ul></div><p>
</p><p>
At the root level, <code class="literal">opensc.conf</code> should contain
one or more application specific configuration blocks:
</p><pre class="programlisting">
app <em class="replaceable"><code>application</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</pre><p>
<em class="replaceable"><code>application</code></em>
specifies one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal"><em class="replaceable"><code>filename</code></em></code>: Configuration block for the application with specified file path.
</p></li><li class="listitem"><p>
<code class="literal">default</code>: The fall-back configuration block for all applications
</p></li><li class="listitem"><p>
<code class="literal">opensc-pkcs11</code>: Configuration block for the PKCS#11 module (<code class="filename">opensc-pkcs11.so</code>)
</p></li><li class="listitem"><p>
<code class="literal">onepin-opensc-pkcs11</code>: Configuration block for the PKCS#11 one-PIN-module (<code class="filename">onepin-opensc-pkcs11.so</code>)
</p></li><li class="listitem"><p>
<code class="literal">cardmod</code>: Configuration block for Windows' minidriver (<code class="filename">opensc-minidriver.dll</code>)
</p></li><li class="listitem"><p>
<code class="literal">tokend</code>: Configuration block for macOS' tokend (<span class="application">OpenSC.tokend</span>)
</p></li><li class="listitem"><p>
<code class="literal">cardos-tool</code>,
<code class="literal">cryptoflex-tool</code>,
<code class="literal">dnie-tool</code>,
<code class="literal">egk-tool</code>,
<code class="literal">eidenv</code>,
<code class="literal">gids-tool</code>,
<code class="literal">iasecc-tool</code>,
<code class="literal">netkey-tool</code>,
<code class="literal">npa-tool</code>,
<code class="literal">openpgp-tool</code>,
<code class="literal">opensc-asn1</code>,
<code class="literal">opensc-explorer</code>,
<code class="literal">opensc-notify</code>,
<code class="literal">opensc-tool</code>,
<code class="literal">piv-tool</code>,
<code class="literal">pkcs11-tool</code>,
<code class="literal">pkcs15-crypt</code>,
<code class="literal">pkcs15-init</code>,
<code class="literal">pkcs15-tool</code>,
<code class="literal">sc-hsm-tool</code>,
<code class="literal">westcos-tool</code>:
Configuration block for OpenSC tools
</p></li></ul></div><p>
</p></div><div class="refsect1"><a name="id-1.2.4"></a><h2>Configuration Options</h2><div class="variablelist"><dl class="variablelist"><dt><a name="debug"></a><span class="term">
<code class="option">debug = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Amount of debug info to print (Default:
<code class="literal">0</code>). A greater value means more
debug info.
</p><p>
The environment variable
<code class="envar">OPENSC_DEBUG</code> overwrites this
setting.
</p></dd><dt><span class="term">
<code class="option">debug_file = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
The file to which debug output will be written
(Default: <code class="literal">stderr</code>). Special
values <code class="literal">stdout</code> and
<code class="literal">stderr</code> are recognized.
</p></dd><dt><span class="term">
<code class="option">profile_dir = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
PKCS#15 initialization/personalization profiles
directory for
<span class="citerefentry"><span class="refentrytitle">pkcs15-init</span>(1).
</span>
(Default: <code class="literal">/usr/share/opensc</code>).
</p><p>
If this configuration value is not found on
Windows, the registry key
<code class="filename">Software\OpenSC
Project\OpenSC\ProfileDir</code> is
checked.
</p></dd><dt><span class="term">
<code class="option">disable_colors = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Disable colors of log messages (Default:
<code class="literal">false</code> if attached to a console,
<code class="literal">true</code> otherwise).
</p></dd><dt><span class="term">
<code class="option">disable_popups = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Disable pop-ups of built-in GUI (Default: <code class="literal">false</code>).
</p></dd><dt><span class="term">
<code class="option">enable_default_driver = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Enable default card driver (Default:
<code class="literal">false</code>). Default card driver is
explicitly enabled for
<span class="citerefentry"><span class="refentrytitle">opensc-explorer</span>(1).
</span>
and
<span class="citerefentry"><span class="refentrytitle">opensc-tool</span>(1).
</span>
</p></dd><dt><a name="card_drivers"></a><span class="term">
<code class="option">card_drivers = <em class="replaceable"><code>name</code></em>... ;</code>
</span></dt><dd><p>
Allowlist of card drivers to load at start-up.
The special value <code class="literal">internal</code> (the
default) will load all statically linked drivers.
</p><p>
If an unknown (i.e. not internal or old) driver is
supplied, a separate configuration
block has to be written for the driver. A special
value <code class="literal">old</code> will load all
statically linked drivers that may be removed in
the future.
</p><p>
The list of supported card driver names can be
retrieved from the output of <span class="command"><strong>opensc-tool
--list-drivers</strong></span>.
</p><p>
The environment variable
<code class="envar">OPENSC_DRIVER</code> overwrites this
setting.
</p></dd><dt><span class="term">
<code class="option">ignored_readers = <em class="replaceable"><code>name</code></em>... ;</code>
</span></dt><dd><p>
List of readers to ignore (Default: empty). If any
of the comma separated strings listed is matched in
a reader name (case sensitive, partial matching
possible), the reader is ignored by OpenSC. Use
<span class="command"><strong>opensc-tool --list-readers</strong></span> to
see all currently connected readers.
</p></dd><dt><span class="term">
<code class="option">reader_driver <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Configuration of the smart card reader driver where <em class="replaceable"><code>name</code></em> is one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">ctapi</code>: See <a class="xref" href="#ctapi" title="Configuration of CT-API Readers">the section called “Configuration of CT-API Readers”</a>
</p></li><li class="listitem"><p>
<code class="literal">pcsc</code>: See <a class="xref" href="#pcsc" title="Configuration of PC/SC Readers">the section called “Configuration of PC/SC Readers”</a>
</p></li><li class="listitem"><p>
<code class="literal">openct</code>: See <a class="xref" href="#openct" title="Configuration of OpenCT Readers">the section called “Configuration of OpenCT Readers”</a>
</p></li><li class="listitem"><p>
<code class="literal">cryptotokenkit</code>: Configuration block for CryptoTokenKit readers
</p></li></ul></div><p>
</p><p>
See <a class="xref" href="#reader_driver" title="Configuration of Smart Card Reader Driver">the section called “Configuration of Smart Card Reader Driver”</a>.
</p></dd><dt><span class="term">
<code class="option">card_driver <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Configuration of the card driver where <em class="replaceable"><code>name</code></em> is one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">npa</code>: See <a class="xref" href="#npa" title="Configuration Options for German ID Card">the section called “Configuration Options for German ID Card”</a>
</p></li><li class="listitem"><p>
<code class="literal">dnie</code>: See <a class="xref" href="#dnie" title="Configuration Options for DNIe">the section called “Configuration Options for DNIe”</a>
</p></li><li class="listitem"><p>
<code class="literal">edo</code>: See <a class="xref" href="#edo" title="Configuration Options for Polish eID Card">the section called “Configuration Options for Polish eID Card”</a>
</p></li><li class="listitem"><p>
<code class="literal">eoi</code>: See <a class="xref" href="#eoi" title="Configuration Options for Slovenian eID Card">the section called “Configuration Options for Slovenian eID Card”</a>
</p></li><li class="listitem"><p>
<code class="literal">myeid</code>: See <a class="xref" href="#myeid" title="Configuration Options for MyEID Card">the section called “Configuration Options for MyEID Card”</a>
</p></li><li class="listitem"><p>
Any other value: Configuration block for an externally loaded card driver
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">card_atr <em class="replaceable"><code>hexstring</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
In addition to the built-in list of known cards in
the card driver, you can configure a new card for
the driver using the <code class="option">card_atr</code>
block.
</p><p>
For details see <a class="xref" href="#card_atr" title="Configuration based on ATR">the section called “Configuration based on ATR”</a>.
</p></dd><dt><span class="term">
<code class="option">disable_hw_pkcs1_padding = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Disabling PKCS#1 v1.5 padding in HW when card supports doing raw RSA operations.
Known parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">no</code>: PKCS#1 v1.5 padding is enabled in HW when card supports it.
</p></li><li class="listitem"><p>
<code class="literal">sign</code>: PKCS#1 v1.5 padding
is disabled only for signatures (PKCS#1 v1.5 type 1).
</p></li><li class="listitem"><p>
<code class="literal">decipher</code>: PKCS#1 v1.5 padding
is disabled only for decryption (PKCS#1 v1.5 type 2).
</p></li><li class="listitem"><p>
<code class="literal">both</code>: PKCS#1 v1.5 padding
is disabled both for signatures and decryption (PKCS#1 v1.5 type 1 and 2).
</p></li></ul></div><p>
(Default: <code class="literal">decipher</code>).
</p></dd><dt><span class="term">
<code class="option">secure_messaging <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Configuration options for the secure messaging profile <em class="replaceable"><code>name</code></em>:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">module_name = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
Name of external SM module (Default: libsmm-local.so).
</p></dd><dt><span class="term">
<code class="option">module_path = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
Directory with external SM module
(Default: /usr/lib64).
</p><p>
If this configuration value is not
found on Windows, the registry key
<code class="filename">Software\OpenSC
Project\OpenSC\SmDir</code> is
checked.
</p></dd><dt><span class="term">
<code class="option">module_data = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Specific data to tune the module initialization.
</p></dd><dt><span class="term">
<code class="option">mode = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Secure messaging mode. Known parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">transmit</code>:
In this mode the
procedure to securize
an APDU is called by
the OpenSC general APDU
transmit procedure. In
this mode all APDUs,
except the ones
filtered by the card
specific procedure, are
securized.
</p></li><li class="listitem"><p>
<code class="literal">acl</code>:
In this mode APDU are
securized only if
needed by the ACLs of
the command to be
executed.
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">flags = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Secure messaging type specific flags.
</p></dd><dt><span class="term">
<code class="option">kmc = <em class="replaceable"><code>hexstring</code></em>;</code>
</span></dt><dd><p>
Default KMC of the GP Card Manager for the Oberthur's Java cards.
</p></dd><dt><span class="term">
<code class="option">ifd_serial = <em class="replaceable"><code>hexstring</code></em>;</code>
</span></dt><dd></dd><dt><span class="term">
<code class="option">keyset[_<em class="replaceable"><code>aid</code></em>]_<em class="replaceable"><code>num</code></em>_enc =
<em class="replaceable"><code>value</code></em>;</code>
<code class="option">keyset[_<em class="replaceable"><code>aid</code></em>]_<em class="replaceable"><code>num</code></em>_mac =
<em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Keyset values from IAM profiles of
the Gemalto IAS/ECC cards with an
optional application identifier
</p></dd></dl></div></dd><dt><span class="term">
<code class="option">framework <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Internal configuration options where <em class="replaceable"><code>name</code></em> is one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">pkcs15</code>: See <a class="xref" href="#framework%20pkcs15" title="Configuration of PKCS#15 Framework">the section called “Configuration of PKCS#15 Framework”</a>
</p></li><li class="listitem"><p>
<code class="literal">tokend</code>: See <a class="xref" href="#framework%20tokend" title="Configuration of Tokend">the section called “Configuration of Tokend”</a>
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">pkcs11 {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Parameters for the OpenSC PKCS11 module.
</p><p>
For details see <a class="xref" href="#pkcs11" title="Configuration of PKCS#11">the section called “Configuration of PKCS#11”</a>.
</p></dd></dl></div><div class="refsect2"><a name="reader_driver"></a><h3>Configuration of Smart Card Reader Driver</h3><div class="refsect3"><a name="id-1.2.4.3.2"></a><h4>Configuration Options for all Reader Drivers</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">max_send_size = <em class="replaceable"><code>num</code></em>;</code>
<code class="option">max_recv_size = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Limit command and response sizes
(Default:
<code class="option">max_send_size</code>
= <code class="literal">255</code>,
<code class="option">max_recv_size</code>
= <code class="literal">256</code>) . Some
Readers don't propagate their
transceive capabilities correctly.
max_send_size and max_recv_size
allow setting the limits manually,
for example to enable extended
length capabilities.
</p></dd><dt><span class="term">
<code class="option">enable_escape <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Detect reader capabilities with
escape commands (wrapped APDUs with
CLA=0xFF as defined by PC/SC pt. 3
and BSI TR-03119, e.g. for getting
the UID, escaped PIN commands and
the reader's firmware version,
Default: <code class="literal">false</code>)
</p></dd></dl></div></div><div class="refsect3"><a name="ctapi"></a><h4>Configuration of CT-API Readers</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">module <em class="replaceable"><code>filename</code></em> {
ports = <em class="replaceable"><code>nums</code></em>;
}
</code>
</span></dt><dd><p>
Load the specified CT-API module with the specified number of ports.
</p></dd></dl></div></div><div class="refsect3"><a name="pcsc"></a><h4>Configuration of PC/SC Readers</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">connect_exclusive = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Connect to reader in exclusive mode
(Default: <code class="literal">false</code>)?
This option has no effect in Windows' minidriver.
</p></dd><dt><span class="term">
<code class="option">disconnect_action = <em class="replaceable"><code>action</code></em>;</code>
</span></dt><dd><p>
What to do when disconnecting from
a card (SCardDisconnect). Valid
values are
<code class="literal">leave</code>,
<code class="literal">reset</code>,
<code class="literal">unpower</code> (Default:
<code class="literal">leave</code>).
This option has no effect in Windows' minidriver.
</p></dd><dt><span class="term">
<code class="option">transaction_end_action = <em class="replaceable"><code>action</code></em>;</code>
</span></dt><dd><p>
What to do at the end of a
transaction (SCardEndTransaction).
Valid values
are <code class="literal">leave</code>,
<code class="literal">reset</code>,
<code class="literal">unpower</code> (Default:
<code class="literal">leave</code>).
This option has no effect in Windows' minidriver.
</p></dd><dt><span class="term">
<code class="option">reconnect_action = <em class="replaceable"><code>action</code></em>;</code>
</span></dt><dd><p>
What to do when reconnection to a
card (SCardReconnect). Valid values
are <code class="literal">leave</code>,
<code class="literal">reset</code>,
<code class="literal">unpower</code> (Default:
<code class="literal">leave</code>).
This option has no effect in Windows' minidriver.
</p></dd><dt><span class="term">
<code class="option">enable_pinpad = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Enable pinpad if detected (PC/SC
v2.0.2 Part 10, Default:
<code class="literal">true</code>)
</p></dd><dt><span class="term">
<code class="option">fixed_pinlength = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Some pinpad readers can only handle
one exact length of the PIN.
<code class="option">fixed_pinlength</code>
sets this value so that OpenSC
expands the padding to this length
(Default: <code class="literal">0</code>,
i.e. not fixed).
</p></dd><dt><span class="term">
<code class="option">provider_library = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
Use specific PC/SC provider
(Default:
<code class="literal">libpcsclite.so.1</code>).
</p></dd></dl></div></div><div class="refsect3"><a name="openct"></a><h4>Configuration of OpenCT Readers</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">readers = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Virtual readers to allocate (Default: <code class="literal">2</code>).
</p></dd></dl></div></div></div><div class="refsect2"><a name="myeid"></a><h3>Configuration Options for MyEID Card</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">disable_hw_pkcs1_padding = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
The MyEID card can internally
encapsulate the data (hash code)
into a DigestInfo ASN.1 structure
according to the selected hash
algorithm (currently only for SHA1).
DigestInfo is padded to RSA key
modulus length according to PKCS#1
v1.5, block type 01h. Size of the
DigestInfo must not exceed 40%
of the RSA key modulus length. If
this limit is unsatisfactory (for
example someone needs RSA 1024
with SHA512), the user can disable
this feature. In this case, the
card driver will do everything
necessary before sending the data
(hash code) to the card.
</p><p>
PKCS#1 v1.5 padding in HW can be globally disabled by option <code class="literal">disable_hw_pkcs1_padding</code>.
When the global option is used to disable padding, the padding will be disabled even though the MyEID-specific option does not turn it off.
</p></dd></dl></div></div><div class="refsect2"><a name="npa"></a><h3>Configuration Options for German ID Card</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">can = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
German ID card requires the CAN to
be verified before QES PIN. This,
however, is not part of the PKCS#15
profile of the card. So for
verifying the QES PIN we actually
need both. The CAN may be given
here. If the CAN is not given here,
it will be prompted on the command
line or on the reader (depending on
the reader's capabilities).
</p></dd><dt><span class="term">
<code class="option">st_dv_certificate = <em class="replaceable"><code>filename</code></em>;</code>
<code class="option">st_certificate = <em class="replaceable"><code>filename</code></em>;</code>
<code class="option">st_key = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
QES is only possible with a Comfort
Reader (CAT-K), which holds a
cryptographic key to authenticate
itself as signature terminal (ST).
We usually will use the reader's
capability to sign the data.
However, during development you
may specify soft certificates and
keys for a ST.
</p><p>
An example PKI can be found in the
example data for the
<a class="ulink" href="https://github.com/frankmorgner/vsmartcard/tree/master/virtualsmartcard/npa-example-data" target="_top">German
ID card emulator</a>
</p></dd></dl></div></div><div class="refsect2"><a name="dnie"></a><h3>Configuration Options for DNIe</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">user_consent_enabled = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Configure the warning message when
performing a signature operation
with the DNIe. Only used if
compiled with
<code class="option">--enable-dnie-ui</code>
</p></dd><dt><span class="term">
<code class="option">user_consent_app = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
Specify the pinentry application to
use if warning is configured to be
displayed using pinentry (Default:
<code class="literal">/usr/bin/pinentry</code>).
Only used if compiled with
<code class="option">--enable-dnie-ui</code>
</p></dd></dl></div></div><div class="refsect2"><a name="edo"></a><h3>Configuration Options for Polish eID Card</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">can = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
CAN (Card Access Number – 6 digit number
printed on the right bottom corner of the
front side of the document) is required
to establish connection with the card.
It might be overwritten by <code class="literal">EDO_CAN</code>
environment variable. Currently, it is not
possible to set it in any other way.
</p></dd></dl></div></div><div class="refsect2"><a name="eoi"></a><h3>Configuration Options for Slovenian eID Card</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">can = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
CAN (Card Access Number – 6 digit number
printed on the right bottom corner of the
front side of the document) is required
to establish connection with the card.
It might be overwritten by <code class="literal">EOI_CAN</code>
environment variable. As CAN is also stored on the card
(in encrypted form) it can be used to automatically establish
secure connection, but only if the card is accessed over the
contact interface.
</p></dd></dl></div></div><div class="refsect2"><a name="piv"></a><h3>Configuration Options for PIV Card</h3><div class="variablelist"><dl class="variablelist"></dl></div></div><div class="refsect2"><a name="card_atr"></a><h3>Configuration based on ATR</h3><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">atrmask = <em class="replaceable"><code>hexstring</code></em>;</code>
</span></dt><dd><p>
The mask is logically AND'd with an
card ATR prior to comparison with
the ATR reference value above.
Using this mask allows identifying
and configuring multiple ATRs as
the same card model.
</p></dd><dt><span class="term">
<code class="option">driver = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
When enabled, overrides all
possible settings from the card
drivers built-in card configuration
list.
</p></dd><dt><span class="term">
<code class="option">name = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Set card name for card drivers that
allows it.
</p></dd><dt><span class="term">
<code class="option">type = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Allows setting the exact type of
the card internally used by the
card driver. Allowed values can be
found in the source code of
<code class="filename">cards.h</code>.
</p></dd><dt><span class="term">
<code class="option">flags = <em class="replaceable"><code>value</code></em>... ;</code>
</span></dt><dd><p>
Card flags as an hex value.
Multiple values are OR'd together.
Depending on card driver, this
allows fine-tuning the capabilities
in the card driver for your card.
</p><p>
Optionally, some known parameters
can be specified as strings:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">rng</code>:
On-board random number
source
</p></li><li class="listitem"><p>
<code class="literal">keep_alive</code>:
Request the card driver
to send a "keep alive"
command before each
transaction to make
sure that the required
applet is still
selected.
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">pkcs15emu = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
When using PKCS#15 emulation, force
the emulation driver for specific
cards. Required for external
drivers, but can be used with
built-in drivers, too.
</p></dd><dt><span class="term">
<code class="option">force_protocol = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Force protocol selection for
specific cards. Known parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">t0</code>
</p></li><li class="listitem"><p>
<code class="literal">t1</code>
</p></li><li class="listitem"><p>
<code class="literal">raw</code>
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">read_only = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Mark card as read/only card in
PKCS#11/Minidriver/BaseCSP interface
(Default: <code class="literal">false</code>).
</p></dd><dt><span class="term">
<code class="option">md_supports_X509_enrollment = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Indicate X509 enrollment support at
Minidriver/BaseCSP interface
(Default: <code class="literal">false</code>).
</p></dd><dt><span class="term">
<code class="option">md_guid_as_id = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Use the GUID generated for the key
as id in the PKCS#15 structure
(Default: <code class="literal">false</code>, i.e. auto generated)
</p></dd><dt><span class="term">
<code class="option">md_guid_as_label = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Use the GUID generated for the key
as label in the PKCS#15 structure
(Default: <code class="literal">false</code>,
i.e. no label set).
</p></dd><dt><span class="term">
<code class="option">md_supports_container_key_gen = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Card allows generating key pairs on the card (Default: <code class="literal">false</code>).
</p></dd><dt><span class="term">
<code class="option">md_supports_container_key_import = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Card allows importing private keys
(Default: <code class="literal">false</code>).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_title = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Window title of the PIN pad dialog
(Default: <code class="literal">"Windows
Security"</code>).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_icon = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
Filename of the icon for the PIN
pad dialog; use
<code class="literal">""</code> for no icon
(Default: Built-in smart card icon).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_main = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Main instruction of the PIN pad
dialog (Default: <code class="literal">"OpenSC
Smart Card Provider"</code>).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_content_user = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Content of the PIN pad dialog for
role "user" (Default:
<code class="literal">"Please enter your PIN on the PIN
pad."</code>).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_content_user_sign = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Content of the PIN pad dialog for
role "user+signature" (Default:
<code class="literal">"Please enter your digital signature
PIN on the PIN pad."</code>).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_content_admin = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Content of the PIN pad dialog for
role "admin" (Default:
<code class="literal">"Please enter your PIN to unblock the
user PIN on the PIN pad."</code>)
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_expanded = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Expanded information of the PIN pad
dialog (Default: <code class="literal">"This window will be
closed automatically after the PIN has been
submitted on the PIN pad (timeout typically
after 30 seconds)."</code>)
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_enable_cancel = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Allow the user to cancel the PIN
pad dialog (Default:
<code class="literal">false</code>).
If this value is set to
<code class="literal">true</code>, the user needs to
click "OK" to start the PIN verification on the
PIN pad. The user can choose the default
behavior by enabling or disabling the checkbox
of the dialog. The setting is saved by the
program's full path
(<em class="replaceable"><code>program_path</code></em>) that
uses OpenSC.
</p><p>
The registry key <code class="filename">HKCU\Software\OpenSC
Project\OpenSC\md_pinpad_dlg_enable_cancel\<em class="replaceable"><code>program_path</code></em></code>
overwrites this setting with a
<code class="literal">DWORD</code> set to either
<code class="literal">1</code> (enabled) or
<code class="literal">0</code> (disabled).
</p></dd><dt><span class="term">
<code class="option">md_pinpad_dlg_timeout = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Time in seconds for the progress
bar of the PIN pad dialog to tick.
<code class="literal">0</code> removes the
progress bar (Default:
<code class="literal">30</code>).
</p></dd><dt><span class="term">
<code class="option">notify_card_inserted = <em class="replaceable"><code>value</code></em>;</code>
<code class="option">notify_card_inserted_text = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Notification title and text when
card was inserted (Default:
<code class="literal">"Smart card
detected"</code>, ATR of
the card).
</p></dd><dt><span class="term">
<code class="option">notify_card_removed = <em class="replaceable"><code>value</code></em>;</code>
<code class="option">notify_card_removed_text = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Notification title and text when
card was removed (Default:
<code class="literal">"Smart card
removed"</code>, name of
smart card reader).
</p></dd><dt><span class="term">
<code class="option">notify_pin_good = <em class="replaceable"><code>value</code></em>;</code>
<code class="option">notify_pin_good_text = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Notification title and text when
PIN was verified (Default:
<code class="literal">"PIN verified"</code>,
<code class="literal">"Smart card is
unlocked"</code>).
</p></dd><dt><span class="term">
<code class="option">notify_pin_bad = <em class="replaceable"><code>value</code></em>;</code>
<code class="option">notify_pin_bad_text = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Notification title and text when
PIN was wrong (Default:
<code class="literal">"PIN not
verified"</code>,
<code class="literal">"Smart card is
locked"</code>).
</p></dd></dl></div><p>
</p></div><div class="refsect2"><a name="framework%20pkcs15"></a><h3>Configuration of PKCS#15 Framework</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">use_file_caching = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Whether to cache the card's files (e.g.
certificates) on disk in
<code class="option">file_cache_dir</code>.
Possible parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">yes</code>: Cache all files (public and private).
</p></li><li class="listitem"><p>
<code class="literal">public</code>: Cache only public files.
</p></li><li class="listitem"><p>
<code class="literal">no</code>: File caching disabled.
</p></li></ul></div><p>
(Default: <code class="literal">public</code>
for the following card drivers
<code class="literal">atrust-acos</code> (deactivated driver),
<code class="literal">belpic</code>,
<code class="literal">cac1</code>,
<code class="literal">cac</code>,
<code class="literal">coolkey</code>,
<code class="literal">dnie</code>,
<code class="literal">edo</code>,
<code class="literal">esteid2018</code>,
<code class="literal">flex</code> (deactivated driver),
<code class="literal">cyberflex</code> (deactivated driver),
<code class="literal">gemsafeV1</code>,
<code class="literal">idprime</code>,
<code class="literal">itacns</code>,
<code class="literal">jpki</code>,
<code class="literal">MaskTech</code>,
<code class="literal">mcrd</code> (deactivated driver),
<code class="literal">npa</code>,
<code class="literal">nqapplet</code>,
<code class="literal">tcos</code> and otherwise <code class="literal">no</code>).
</p><p>
If caching is done by a system process, the
cached files may be placed inaccessible from
the user account. Use a globally readable and
writable location if you wish to share the
cached information. Note that the cached files
may contain personal data such as name and mail
address.
</p></dd><dt><span class="term">
<code class="option">file_cache_dir = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
Where to cache the card's files. The default values are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="filename"><code class="envar">$XDG_CACHE_HOME</code>/opensc/</code> (If <code class="envar">$XDG_CACHE_HOME</code> is defined)
</p></li><li class="listitem"><p>
<code class="filename"><code class="envar">$HOME</code>/.cache/opensc/</code> (Unix)
</p></li><li class="listitem"><p>
<code class="filename"><code class="envar">$USERPROFILE</code>\.eid-cache\</code> (Windows)
</p></li></ul></div><p>
</p><p>
If caching is done by a system process, the
cached files may be placed inaccessible from
a user account. Use a globally readable and
writable location if you wish to share the
cached information. Note that the cached files
may contain personal data such as name and mail
address.
</p><p>
The PIV-II card driver supports the history object's
list of retired keys and certificates if they are
readable in the file cache directory.
If the specified object's URL is
<code class="literal">"http://"</code><em class="replaceable"><code>DNS name</code></em><code class="literal">"/"</code><em class="replaceable"><code>ASCII-HEX OffCardKeyHistoryFile</code></em>,
then the searches for the file name
<em class="replaceable"><code>OffCardKeyHistoryFile</code></em>
in the cache directory.
</p></dd><dt><span class="term">
<code class="option">use_pin_caching = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Use PIN caching (Default: <code class="literal">true</code>)?
</p></dd><dt><span class="term">
<code class="option">pin_cache_counter = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
How many times to use a PIN from cache before
re-authenticating it (Default:
<code class="literal">10</code>)?
</p></dd><dt><span class="term">
<code class="option">pin_cache_ignore_user_consent = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Older PKCS#11 applications not supporting
<code class="literal">CKA_ALWAYS_AUTHENTICATE</code> may
need to set this to get signatures to work with
some cards (Default: <code class="literal">false</code>).
</p><p>
It is recommended to enable also PIN caching using
<code class="literal">use_pin_caching</code> option for OpenSC
to be able to provide PIN for the card when needed.
</p></dd><dt><span class="term">
<code class="option">pin_protected_certificate = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
How to handle a PIN-protected certificate. Known
parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">protect</code>: The certificate stays PIN-protected.
</p></li><li class="listitem"><p>
<code class="literal">declassify</code>: Allow
reading the certificate without
enforcing verification of the PIN.
</p></li><li class="listitem"><p>
<code class="literal">ignore</code>: Ignore PIN-protected certificates.
</p></li></ul></div><p>
(Default: <code class="literal">ignore</code> in Tokend,
<code class="literal">protect</code> otherwise).
</p></dd><dt><span class="term">
<code class="option">enable_pkcs15_emulation = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Enable pkcs15 emulation (Default:
<code class="literal">true</code>).
</p></dd><dt><span class="term">
<code class="option">try_emulation_first = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Prefer pkcs15 emulation code before the normal
pkcs15 processing (Default:
<code class="literal">no</code>). Some cards work in
emu-only mode, and do not depend on this
option.
</p></dd><dt><span class="term">
<code class="option">enable_builtin_emulation = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Enable builtin emulators (Default:
<code class="literal">true</code>).
</p></dd><dt><span class="term">
<code class="option">builtin_emulators = <em class="replaceable"><code>emulators</code></em>;</code>
</span></dt><dd><p>
List of the builtin pkcs15 emulators to test
(Default: <code class="literal">internal</code>)
</p><p>
Special value of <code class="literal">internal</code> will try all not disabled builtin pkcs15 emulators.
</p><p>
Special value of <code class="literal">old</code> will try all disabled pkcs15 emulators.
</p></dd><dt><span class="term">
<code class="option">pkcs11_enable_InitToken = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Enable initialization and card recognition
(Default: <code class="literal">false</code>).
</p></dd><dt><span class="term">
<code class="option">emulate <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Configuration options for a PKCS#15 emulator
where <em class="replaceable"><code>name</code></em> is a
short name for an external card driver.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">module = <em class="replaceable"><code>filename</code></em>;</code>
</span></dt><dd><p>
For pkcs15 emulators loaded from an
external shared library/DLL, you need to
specify the path name of the module and
customize the card_atr example above
correctly.
</p></dd><dt><span class="term">
<code class="option">function = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Get the init function name of the
emulator (Default:
<code class="literal">sc_pkcs15_init_func_ex</code>)
</p></dd></dl></div></dd><dt><span class="term">
<code class="option">application <em class="replaceable"><code>hexstring</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Configuration of the on-card-application where
<em class="replaceable"><code>hexstring</code></em> is the
application identifier (AID).
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">type = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Type of application where
<em class="replaceable"><code>name</code></em> is one
of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">generic</code>
</p></li><li class="listitem"><p>
<code class="literal">protected</code>
</p></li></ul></div><p>
</p><p>
Used to distinguish the common access
application and application for which
authentication to perform some
operation cannot be obtained with the
common procedures (ex. object creation
protected by secure messaging). Used
by PKCS#11 module configured to expose
restricted number of slots. (for ex.
configured to expose only User PIN
slot, User and Sign PINs slots, ...)
</p></dd><dt><span class="term">
<code class="option">model = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd></dd><dt><span class="term">
<code class="option">disable = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Do not expose application in PKCS#15
framework (Default:
<code class="literal">false</code>)
</p></dd><dt><span class="term">
<code class="option">user_pin = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Name of the User PIN object that will be used as the main PIN.
</p></dd><dt><span class="term">
<code class="option">sign_pin = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Name of the PIN object that will be used for signing.
</p></dd></dl></div></dd></dl></div></div><div class="refsect2"><a name="framework%20tokend"></a><h3>Configuration of Tokend</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">score = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Score for <span class="application">OpenSC.tokend</span>
(Default: <code class="literal">300</code>). The tokend with
the highest score shall be used.
</p></dd></dl></div></div><div class="refsect2"><a name="pkcs11"></a><h3>Configuration of PKCS#11</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">max_virtual_slots = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Maximum Number of virtual slots (Default:
<code class="literal">16</code>). If there are more slots
than defined here, the remaining slots will be
hidden from PKCS#11.
</p></dd><dt><span class="term">
<code class="option">slots_per_card = <em class="replaceable"><code>num</code></em>;</code>
</span></dt><dd><p>
Maximum number of PIN slots per smart card (Default:
<code class="literal">4</code>). If the card has fewer PINs
than defined here, the remaining number of slots
will be empty. For Firefox, Chrome and Chromium, the
<code class="option">slots_per_card</code> is set to <code class="literal">1</code>,
to avoid prompting for unrelated PINs. Typically, this
effectively disables signature PINs and keys.
</p></dd><dt><span class="term">
<code class="option">lock_login = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
By default, the OpenSC PKCS#11 module will not lock
your card once you authenticate to the card via
<code class="literal">C_Login</code> (Default:
<code class="literal">false</code>).
Thus the other users or other applications is not
prevented from connecting to the card and perform
crypto operations (which may be possible because
you have already authenticated with the card). This
setting is not very secure.
</p><p>
Also, if your card is not locked, you can enconter
problems due to limitation of the OpenSC framework,
that still is not thoroughly tested in the multi
threads environment.
</p><p>
Your settings will be more secure if you choose to
lock your card. Nevertheless this behavior is a
known violation of PKCS#11 specification. Now once
one application has started using your card with
<code class="literal">C_Login</code>, no other application
can use it, until the first is done and calls
<code class="literal">C_Logout</code> or
<code class="literal">C_Finalize</code>. In the case of many
PKCS#11 application this does not happen until you
exit the application.
</p><p>
Thus it is impossible to use several smart card
aware applications at the same time, e.g. you
cannot run both <span class="application">Firefox</span>
and <span class="application">Thunderbird</span> at the
same time, if both are configured to use your smart
card.
</p></dd><dt><span class="term">
<code class="option">atomic = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
By default, interacting with the OpenSC PKCS#11
module may change the state of the token, e.g.
whether a user is logged in or not (Default:
<code class="literal">false</code>).
</p><p>
Thus other users or other applications may change
or use the state of the token unknowingly. Other
applications may create signatures abusing an
existing login or they may logout unnoticed.
</p><p>
With this setting enabled the login state of the
token is tracked and cached (including the PIN).
Every transaction is preceded by restoring the
login state. After every transaction a logout is
performed. This setting by default also enables
<code class="option">lock_login</code> to disable access for
other applications during the atomic transactions.
</p><p>
Please note that any PIN-pad should be disabled
(see <code class="option">enable_pinpad</code>), because the
user would have to input his PIN for every
transaction.
</p></dd><dt><span class="term">
<code class="option">init_sloppy = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
With this setting disabled, the OpenSC PKCS#11
module will initialize the slots available when the
application calls <code class="literal">C_GetSlotList</code>.
With this setting enabled, the slots will also get
initialized when <code class="literal">C_GetSlotInfo</code>
is called (Default: <code class="literal">true</code>).
</p><p>
This setting is a workaround for
<span class="application">Java</span> which does not call
<code class="literal">C_GetSlotList</code> when configured
with a static <code class="literal">slot</code> instead of
<code class="literal">slotListIndex</code>.
</p></dd><dt><span class="term">
<code class="option">user_pin_unblock_style = <em class="replaceable"><code>mode</code></em>;</code>
</span></dt><dd><p>
User PIN unblock style <em class="replaceable"><code>mode</code></em>
is one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">none</code> (Default): PIN
unblock is not possible with PKCS#11 API
</p></li><li class="listitem"><p>
<code class="literal">set_pin_in_unlogged_session</code>:
<code class="literal">C_SetPIN</code> in unlogged
session: PUK is passed as the
<code class="literal">OldPin</code> argument of the
<code class="literal">C_SetPIN</code> call.
</p></li><li class="listitem"><p>
<code class="literal">set_pin_in_specific_context</code>:
<code class="literal">C_SetPIN</code> in the
<code class="literal">CKU_SPECIFIC_CONTEXT</code>
logged session: PUK is passed as the
<code class="literal">OldPin</code> argument of the
<code class="literal">C_SetPIN</code> call.
</p></li><li class="listitem"><p>
<code class="literal">init_pin_in_so_session</code>:
<code class="literal">C_InitPIN</code> in
<code class="literal">CKU_SO</code> logged session:
User PIN 'UNBLOCK' is protected by SOPIN.
(PUK == SOPIN).
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">create_puk_slot = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Create slot for unblocking PIN with PUK (Default:
<code class="literal">false</code>). This way PKCS#11 API can
be used to login with PUK and change a PIN. May
cause problems with some applications like
<span class="application">Firefox</span> and
<span class="application">Thunderbird</span>.
</p></dd><dt><span class="term">
<code class="option">create_slots_for_pins = <em class="replaceable"><code>mode</code></em>... ;</code>
</span></dt><dd><p>
Symbolic names of PINs for which slots are created
where <em class="replaceable"><code>mode</code></em> is a list of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">all</code> (Default): All
non-SO-PIN, non-unblocking PINs
</p></li><li class="listitem"><p>
<code class="literal">user</code>: The first
global or first local PIN
</p></li><li class="listitem"><p>
<code class="literal">sign</code>: The second PIN
(first local, second global or second
local)
</p></li></ul></div><p>
</p><p>
Card can contain more then one PINs or more then
one on-card application with its own PINs.
Normally, to access all of them with the PKCS#11
API a slot has to be created for all of them. Many
slots could be annoying for some of widely used
application, like FireFox. This configuration
parameter allows to select the PIN(s) for which
PKCS#11 slot will be created.
</p><p>
Only PINs initialised, non-SO-PIN, non-unblocking
are associated with symbolic name.
</p><p>
For the module to simulate the opensc-onepin module
behavior the following option
<code class="option">create_slots_for_pins = "user";</code>
</p></dd></dl></div></div></div><div class="refsect1"><a name="id-1.2.5"></a><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="envar">OPENSC_CONF</code>
</span></dt><dd><p>
Filename for a user defined configuration file
</p><p>
If this environment variable is not found on
Windows, the registry key
<code class="filename">Software\OpenSC
Project\OpenSC\ConfigFile</code> is
checked.
</p></dd><dt><span class="term">
<code class="envar">OPENSC_DEBUG</code>
</span></dt><dd><p>
See <a class="xref" href="#debug">
<code class="option">debug = <em class="replaceable"><code>num</code></em>;</code>
</a>
</p></dd><dt><span class="term">
<code class="envar">OPENSC_DRIVER</code>
</span></dt><dd><p>
See <a class="xref" href="#card_drivers">
<code class="option">card_drivers = <em class="replaceable"><code>name</code></em>... ;</code>
</a>
</p></dd><dt><span class="term">
<code class="envar">CARDMOD_LOW_LEVEL_DEBUG</code>
</span></dt><dd><p>
Write minidriver debug information to
<code class="filename">C:\tmp\md.log</code>, if set to
<code class="literal">1</code>.
</p><p>
If this environment variable is not found on
Windows, the registry key
<code class="filename">Software\OpenSC
Project\OpenSC\MiniDriverDebug</code> is
checked.
</p></dd><dt><span class="term">
<code class="envar">PIV_EXT_AUTH_KEY</code>,
<code class="envar">PIV_9A_KEY</code>,
<code class="envar">PIV_9C_KEY</code>,
<code class="envar">PIV_9D_KEY</code>,
<code class="envar">PIV_9E_KEY</code>
</span></dt><dd><p>
PIV configuration during initialization with
<span class="application">piv-tool</span>.
</p></dd><dt><span class="term">
<code class="envar">PIV_USE_SM</code>,
<code class="envar">PIV_PAIRING_CODE</code>
</span></dt><dd><p>
PIV configuration during initialization
See Configuration Options for PIV Card.
</p></dd></dl></div></div><div class="refsect1"><a name="id-1.2.6"></a><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="filename">/etc/opensc.conf</code>
</span></dt><dd><p>
System-wide configuration file
</p></dd><dt><span class="term">
<code class="filename">/usr/share/doc/opensc/opensc.conf</code>
</span></dt><dd><p>
Extended example configuration file
</p></dd></dl></div></div></div><div class="refentry"><div class="refentry.separator"><hr></div><a name="pkcs15-profile"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>pkcs15-profile — format of profile for <span class="command"><strong>pkcs15-init</strong></span></p></div><div class="refsect1"><a name="id-1.3.3"></a><h2>Description</h2><p>
The <span class="command"><strong>pkcs15-init</strong></span> utility for PKCS #15 smart card
personalization is controlled via profiles. When starting, it will read two
such profiles at the moment, a generic application profile, and a card
specific profile. The generic profile must be specified on the command line,
while the card-specific file is selected based on the type of card detected.
</p><p>
The generic application profile defines general information about the card
layout, such as the path of the application DF, various PKCS #15 files within
that directory, and the access conditions on these files. It also defines
general information about PIN, key and certificate objects. Currently, there
is only one such generic profile, <code class="filename">pkcs15.profile</code>.
</p><p>
The card specific profile contains additional information required during
card initialization, such as location of PIN files, key references etc.
Profiles currently reside in <code class="filename">/usr/share/opensc</code>
</p><p>
Basic PKCS#15 terminology:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
MF (Master File) is root of the filesystem hierarchy
</p></li><li class="listitem"><p>
DF(PKCS#15) is directory containing the PKCS#15 files and directories
</p></li><li class="listitem"><p>
EF(ODF) (Object Directory File) is elementary file containing pointers
to other elementary files (PrKDFs, PuKDFs, SKDFs, CDFs, DODFs, AODFs)
</p></li><li class="listitem"><p>
PrKDF (Private Key Directory File) is elementary file containing
pointers to the private keys and additional information about the private keys
</p></li><li class="listitem"><p>
PubKDF (Public Key Directory File) is elementary file containing pointers to the public
keys and additional information about the public keys
</p></li><li class="listitem"><p>
CDF (Certificate Directory File) is elementary file containing pointers to the
certificates and additional information about the certificates
</p></li><li class="listitem"><p>
EF(TokenInfo) is elementary file with generic information about the card
</p></li></ol></div><p>
</p></div><div class="refsect1"><a name="id-1.3.4"></a><h2>Syntax and semantics</h2><p>
The block syntax of profile files is in general similar to the configuration file.
The profile file, is composed of blocks, which, in general, have the following format:
</p><pre class="programlisting">
<em class="replaceable"><code>key</code></em> [, <em class="replaceable"><code>name</code></em>...] {
<em class="replaceable"><code>block_contents</code></em>
}
</pre><p>
<em class="replaceable"><code>block_contents</code></em> is one or more
<em class="replaceable"><code>block_item</code></em>s where a
<em class="replaceable"><code>block_item</code></em> is one of
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
# <em class="replaceable"><code>comment string</code></em>
</p></li><li class="listitem"><p>
<em class="replaceable"><code>key</code></em> [, <em class="replaceable"><code>name</code></em>...] = <em class="replaceable"><code>value</code></em>;
</p></li><li class="listitem"><p>
<em class="replaceable"><code>block</code></em>
</p></li></ul></div><p>
</p><p>
At the root level, the profile contains several configuration blocks.
The block keys are as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">cardinfo</code>: Configuration for general information about card.
</p></li><li class="listitem"><p>
<code class="literal">pkcs15</code>: Control for some of the general aspects of the PKCS#15 put onto the card.
</p></li><li class="listitem"><p>
<code class="literal">option</code>: Profile options to modify the behavior of profile.
</p></li><li class="listitem"><p>
<code class="literal">PIN</code>: Configuration and limits for particular PIN type.
</p></li><li class="listitem"><p>
<code class="literal">filesystem</code>: Specification for filesystem that is to be created on the card.
</p></li><li class="listitem"><p>
<code class="literal">macros</code>
</p></li></ul></div><p>
</p><div class="refsect2"><a name="profile"></a><h3>Profile file configuration</h3><div class="refsect3"><a name="id-1.3.4.4.2"></a><h4>Configuration of Card Information</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">cardinfo {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Configuration for general information about card:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">label = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Card label (Default: <code class="literal">OpenSC Card</code>).
</p></dd><dt><span class="term">
<code class="option">manufacturer = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
Card manufacturer (Default: <code class="literal">OpenSC Project</code>).
</p></dd><dt><span class="term">
<code class="option">min-pin-length = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Minimal length of PIN (Default: <code class="literal">4</code>).
</p></dd><dt><span class="term">
<code class="option">max-pin-length = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Maximal length of PIN, should be overridden in the per-card profile
(Default: <code class="literal">8</code>).
</p></dd><dt><span class="term">
<code class="option">pin-encoding = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Encoding type of PIN. Known parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">BCD</code>:
binary-coded decimal
</p></li><li class="listitem"><p>
<code class="literal">ascii-numeric</code>:
ASCII numerical values
</p></li><li class="listitem"><p>
<code class="literal">utf8</code>
</p></li><li class="listitem"><p>
<code class="literal">half-nibble-bcd</code>
</p></li><li class="listitem"><p>
<code class="literal">iso9564-1</code>
</p></li></ul></div><p>
(Default: <code class="literal">ascii-numeric</code>).
</p></dd><dt><span class="term">
<code class="option">pin-pad-char = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Character used for padding the PIN when needed (Default: <code class="literal">0x00</code>).
</p></dd><dt><span class="term">
<code class="option">pin-domains = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Some cards need to keep all their PINs in separate directories.
The particular keys in that domain will be put below the DF of the specified PIN.
(Default: <code class="literal">no</code>)
</p></dd></dl></div></dd></dl></div></div><div class="refsect3"><a name="id-1.3.4.4.3"></a><h4>Configuration of PKCS#15</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">pkcs15 {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
</span></dt><dd><p>
Control for some of the general aspects of the PKCS#15 put onto the card.
Parameters in this block are:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">direct-certificates = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
The PKCS#15 system must contain at least one CDF, it contains the certificates
directly or references to certificates. This options defines whether the certificates
should be put directly in the CDF itself or not (Default: <code class="literal">no</code>).
</p></dd><dt><span class="term">
<code class="option">encode-df-length = <em class="replaceable"><code>bool</code></em>;</code>
</span></dt><dd><p>
Save length of DF into ODF file. Useful if we store certificates directly in the CDF
for better better performance and robustness (Default: <code class="literal">no</code>).
</p></dd><dt><span class="term">
<code class="option">do-last-update = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Store information about last update in the EF(TokenInfo) (Default: <code class="literal">yes</code>).
</p></dd><dt><span class="term">
<code class="option">pkcs15-id-style = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Method to calculate ID of the crypto objects. Known parameters:
</p><div class="itemizedlist"><code class="literal">native</code><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">native</code>:
'E' + number_of_present_objects_of_the_same_type
</p></li><li class="listitem"><p>
<code class="literal">mozilla</code>:
SHA1(modulus) for RSA
</p></li><li class="listitem"><p>
<code class="literal">rfc2459</code>
SHA1(SequenceASN1 of public key components as ASN1 integers)
</p></li></ul></div><p>
</p></dd><dt><span class="term">
<code class="option">minidriver-support-style = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Style of pkcs15-init support of minidriver. Known parameters:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">none</code>
</p></li><li class="listitem"><p>
<code class="literal">gemalto</code>
</p></li></ul></div><p>
(Default: <code class="literal">none</code>)
</p></dd></dl></div></dd></dl></div></div><div class="refsect3"><a name="id-1.3.4.4.4"></a><h4>Configuration of Profile Option</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">option <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
<p>
The <code class="literal">name</code> specifies profile options to modify the behavior of profile, it can be
</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">default</code>:
option specifies default settings and this block with option is always processed,
</p></li><li class="listitem"><p>
<code class="literal">onepin</code>:
option for using 1 user PIN, creation/deletion/generation is controlled by the user PIN and thus by the user (as a result, only 1 user PIN is possible),
</p></li><li class="listitem"><p>
<code class="literal">small</code>
option suitable for cards with small memory.
</p></li></ul></div><p>
</p>
<p>
The options are used by <code class="literal">pkcs15-init</code> tool by <code class="literal">--profile name, -p name</code>:
</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">pkcs15+default</code>:
the default (not needed to specify it)
</p></li><li class="listitem"><p>
<code class="literal">pkcs15+onepin</code>:
for the onepin profile option
</p></li><li class="listitem"><p>
<code class="literal">pkcs15+small</code>
for the small profile option
</p></li></ul></div><p>
</p>
<p>
The option block can contain following sub-blocks:
</p>
</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">macros { block_contents }</code>
</span></dt><dd><p>
Macros are specified in form of <code class="literal">name = value;</code> pairs.
</p></dd><dt><span class="term">
<code class="option">pkcs15 { block_contents }</code>
</span></dt><dd><p>
Inner block for configuration of PKCS#15 structure.
</p></dd></dl></div></dd></dl></div></div><div class="refsect3"><a name="id-1.3.4.4.5"></a><h4>Configuration of PINs</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">PIN <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
<p>
The <code class="literal">name</code> specifies PIN type, it can be
</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">pin</code> or <code class="literal">user-pin</code>
(no need to set file path or reference as it is done dynamically)
</p></li><li class="listitem"><p>
<code class="literal">puk</code> or <code class="literal">user-puk</code>
</p></li><li class="listitem"><p>
<code class="literal">sopin</code> or <code class="literal">so-pin</code>
</p></li><li class="listitem"><p>
<code class="literal">sopuk</code> or <code class="literal">so-puk</code>
</p></li></ul></div><p>
</p>
</span></dt><dd><p>
Known parameters are:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">attempts = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Defines number of attempts for the given PIN (Default: <code class="literal">3</code>).
</p></dd><dt><span class="term">
<code class="option">flags = <em class="replaceable"><code>value...</code></em>;</code>
</span></dt><dd><p>
Flags define properties of the PIN. Possible flags:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">case-sensitive</code>
</p></li><li class="listitem"><p>
<code class="literal">local</code>
</p></li><li class="listitem"><p>
<code class="literal">change-disabled</code>
</p></li><li class="listitem"><p>
<code class="literal">unblock-disabled</code>
</p></li><li class="listitem"><p>
<code class="literal">initialized</code>
</p></li><li class="listitem"><p>
<code class="literal">needs-padding</code>
</p></li><li class="listitem"><p>
<code class="literal">unblockingPin</code>
</p></li><li class="listitem"><p>
<code class="literal">soPin</code>
</p></li><li class="listitem"><p>
<code class="literal">disable-allowed</code>
</p></li><li class="listitem"><p>
<code class="literal">integrity-protected</code>
</p></li><li class="listitem"><p>
<code class="literal">confidentiality-protected</code>
</p></li><li class="listitem"><p>
<code class="literal">exchangeRefData</code>
</p></li></ul></div><p>
(Default: <code class="literal">local,initialized,needs-padding</code>).
</p></dd><dt><span class="term">
<code class="option">auth-id = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Value used for auth ID (Default: <code class="literal">0</code>).
</p></dd><dt><span class="term">
<code class="option">min-length = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Minimal length of PIN (Default: value <code class="literal">min-pin-length</code> set in <code class="literal">cardinfo</code> block).
</p></dd><dt><span class="term">
<code class="option">max-length = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Maximal length of PIN (Default: value <code class="literal">max-pin-length</code> set in <code class="literal">cardinfo</code> block).
</p></dd><dt><span class="term">
<code class="option">reference = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Value of reference of the PIN (Default: set in particular card driver).
</p></dd><dt><span class="term">
<code class="option">file = <em class="replaceable"><code>name</code></em>;</code>
</span></dt><dd><p>
File with PIN, obsolete option (Default: None).
</p></dd><dt><span class="term">
<code class="option">offset = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Offset of PIN in PIN file, obsolete option (Default: <code class="literal">0</code>).
</p></dd><dt><span class="term">
<code class="option">encoding = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Encoding type of PIN. Possible values:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">BCD</code>
</p></li><li class="listitem"><p>
<code class="literal">ascii-numeric</code>
</p></li><li class="listitem"><p>
<code class="literal">utf8</code>
</p></li><li class="listitem"><p>
<code class="literal">half-nibble-bcd</code>
</p></li><li class="listitem"><p>
<code class="literal">iso9564-1</code>
</p></li></ul></div><p>
(Default: value <code class="literal">pin-encoding</code> set in <code class="literal">cardinfo</code> block).
</p></dd><dt><span class="term">
<code class="option">stored-length = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
(Default: value <code class="literal">max-pin-length</code> set in <code class="literal">cardinfo</code> block).
</p></dd><dt><span class="term">
<code class="option">max-unlocks = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
(Default: <code class="literal">0</code>).
</p></dd></dl></div></dd></dl></div><p>
Values in this block can be set by macros. That allows to specify the particular values with the usage of option.
</p></div><div class="refsect3"><a name="id-1.3.4.4.6"></a><h4>Configuration of Filesystem</h4><code class="option">filesystem {
<em class="replaceable"><code>block_contents</code></em>
}
</code><p>
This block contains the specification for filesystem that is to be created on the card.
The <code class="literal">filesystem</code> consists of several nested blocks representing <code class="literal">DF</code> and <code class="literal">EF</code> files.
When the DFs or EFs are specified in card specific profile, this is added to the file system info specified in the main profile.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">EF <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
<p>
This block defines elementary file in PKCS#15 file hierarchy.
The name can be one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">PKCS15-TokenInfo</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-ODF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-UnusedSpace</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-PRKDF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-PUKDF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-PUKDF-TRUSTED</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-SKDF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-CDF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-CDF-TRUSTED</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-CDF-USEFUL</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-DODF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-AODF</code>
</p></li></ul></div><p>
</p>
<p>
The <code class="literal">EF</code> block can contain:
</p>
</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">type = <em class="replaceable"><code>EF</code></em>;</code>
</span></dt><dd><p>
Type must match type of file.
</p></dd><dt><span class="term">
<code class="option">acl = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Value of ACL (Access Control List) (Default: <code class="literal">NONE</code>)
</p></dd><dt><span class="term">
<code class="option">file-id = <em class="replaceable"><code>EF</code></em>;</code>
</span></dt><dd><p>
File ID, relative path.
</p></dd><dt><span class="term">
<code class="option">structure = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
File structure is one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">TRANSPARENT</code>
</p></li><li class="listitem"><p>
<code class="literal">LINEAR-FIXED</code>
</p></li><li class="listitem"><p>
<code class="literal">LINEAR-FIXED-TLV</code>
</p></li><li class="listitem"><p>
<code class="literal">LINEAR-VARIABLE</code>
</p></li><li class="listitem"><p>
<code class="literal">LINEAR-VARIABLE-TLV</code>
</p></li><li class="listitem"><p>
<code class="literal">CYCLIC</code>
</p></li><li class="listitem"><p>
<code class="literal">CYCLIC-TLV</code>
</p></li></ul></div><p>
</p></dd></dl></div></dd><dt><span class="term">
<code class="option">DF <em class="replaceable"><code>name</code></em> {
<em class="replaceable"><code>block_contents</code></em>
}
</code>
<p>
This block defines directory file in PKCS#15 file hierarchy.
The name can be one of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">MF</code>
</p></li><li class="listitem"><p>
<code class="literal">PKCS15-AppDF</code>
</p></li><li class="listitem"><p>
Special cases for those DFs handled separately by the PKCS15 logic
</p></li></ul></div><p>
</p>
<p>
The <code class="literal">DF</code> block can contain:
</p>
</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<code class="option">type = <em class="replaceable"><code>DF</code></em>;</code>
</span></dt><dd><p>
Type must match type of file.
</p></dd><dt><span class="term">
<code class="option">path = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Specification of path of the directory file.
</p></dd><dt><span class="term">
<code class="option">file-id = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
File ID, relative path.
</p></dd><dt><span class="term">
<code class="option">aid = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Value of AID, in <code class="literal">XX:XX:XX:...:XX:XX:XX</code> notation.
</p></dd><dt><span class="term">
<code class="option">acl = <em class="replaceable"><code>value</code></em>;</code>
</span></dt><dd><p>
Type must match type of file.
</p></dd><dt><span class="term">
<code class="option">size = <em class="replaceable"><code>int</code></em>;</code>
</span></dt><dd><p>
Size of the file in bytes.
</p></dd><dt><span class="term">
<code class="option">EF <em class="replaceable"><code>name</code></em> { block_contents }</code>
</span></dt><dd><p>
Block specifying nested elementary file.
</p></dd></dl></div><p>
Typically, the root <code class="literal">DF</code> is <code class="literal">MF</code>.
</p><p>
It is mandatory that profile file contains <code class="literal">DF</code> entry for <code class="literal">MF</code> (Master File).
Otherwise the profile file is incomplete and cannot be used.
</p></dd></dl></div><p>
The <code class="literal">DF</code> can contain other <code class="literal">DF</code> or <code class="literal">MF</code> blocks.
For examples how the filesystem structure may look like,
please refer to <code class="literal">pkcs15.profile</code> or any other present profile file.
</p></div></div></div><div class="refsect1"><a name="id-1.3.5"></a><h2>See also</h2><p>
<span class="citerefentry"><span class="refentrytitle">pkcs15-init</span>(1)</span>,
<span class="citerefentry"><span class="refentrytitle">pkcs15-crypt</span>(1)</span>
</p></div></div></div></body></html>
|
