Skip to content

Commit df8ccd6

Browse files
cedulauy: add contactless (PACE) support
The contactless interface of the IAS Classic v5 cedula is protected with PACE using the MRZ as password. It is only matched once PACE with the MRZ and selecting the eID application succeed. The MRZ is stored with the new cedulauy-tool, either read over the contact interface or entered by hand, or given in the CEDULAUY_MRZ environment variable. Thanks to @macarenapineiro for testing the contactless ATR on her card, which made it possible to tighten the ATR mask. Co-authored-by: Frank Morgner <frankmorgner@gmail.com>
1 parent 72406af commit df8ccd6

15 files changed

Lines changed: 984 additions & 162 deletions

‎doc/tools/cedulauy-tool.1.xml‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<refentry id="cedulauy-tool">
3+
<refmeta>
4+
<refentrytitle>cedulauy-tool</refentrytitle>
5+
<manvolnum>1</manvolnum>
6+
<refmiscinfo class="productname">OpenSC</refmiscinfo>
7+
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
8+
<refmiscinfo class="source">opensc</refmiscinfo>
9+
</refmeta>
10+
11+
<refnamediv>
12+
<refname>cedulauy-tool</refname>
13+
<refpurpose>Uruguayan eID card (cédula de identidad) setup utility</refpurpose>
14+
</refnamediv>
15+
16+
<refsynopsisdiv>
17+
<cmdsynopsis>
18+
<command>cedulauy-tool</command>
19+
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
20+
</cmdsynopsis>
21+
</refsynopsisdiv>
22+
23+
<refsect1>
24+
<title>Description</title>
25+
<para>
26+
The <command>cedulauy-tool</command> utility sets up the Uruguayan eID card for use
27+
over its contactless (NFC) interface. That interface is protected with PACE, and the
28+
only password the card accepts is the machine readable zone (MRZ) of the document:
29+
the three lines of 30 characters printed on the back. OpenSC only recognizes the card
30+
over NFC once its MRZ is known, so this tool has to be run before the card can be used
31+
contactless.
32+
</para>
33+
<para>
34+
The MRZ is stored in the OpenSC file cache directory (see
35+
<literal>file_cache_dir</literal> in <citerefentry><refentrytitle>opensc.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
36+
The file holds the MRZ, and with it the document number, name and date of birth, in
37+
the clear; it is created readable only by the user. Alternatively, the MRZ can be
38+
given in the <literal>CEDULAUY_MRZ</literal> environment variable, which takes
39+
precedence over the stored one.
40+
</para>
41+
</refsect1>
42+
43+
<refsect1>
44+
<title>Options</title>
45+
<para>
46+
<variablelist>
47+
<varlistentry>
48+
<term>
49+
<option>--help</option>,
50+
<option>-h</option>
51+
</term>
52+
<listitem><para>Display tool options.</para></listitem>
53+
</varlistentry>
54+
55+
<varlistentry>
56+
<term>
57+
<option>--verbose</option>,
58+
<option>-v</option>
59+
</term>
60+
<listitem><para>Causes <command>cedulauy-tool</command> to be more verbose.
61+
Specify this flag several times to enable debug output.</para></listitem>
62+
</varlistentry>
63+
64+
<varlistentry>
65+
<term>
66+
<option>--reader</option> <replaceable>arg</replaceable>,
67+
<option>-r</option> <replaceable>arg</replaceable>
68+
</term>
69+
<listitem>
70+
<para>
71+
Number of the reader to use with <option>--read-mrz</option>.
72+
By default, the first reader with a present card is used. If
73+
<replaceable>arg</replaceable> is an ATR, the
74+
reader with a matching card will be chosen.
75+
</para>
76+
</listitem>
77+
</varlistentry>
78+
79+
<varlistentry>
80+
<term>
81+
<option>--wait</option>,
82+
<option>-w</option>
83+
</term>
84+
<listitem><para>Causes <command>cedulauy-tool</command> to wait for the card
85+
to be inserted into the reader.</para>
86+
</listitem>
87+
</varlistentry>
88+
89+
<varlistentry>
90+
<term>
91+
<option>--read-mrz</option>,
92+
<option>-c</option>
93+
</term>
94+
<listitem>
95+
<para>
96+
Read the MRZ from the card in a contact reader, where it is
97+
accessible without a PIN, and store it.
98+
</para>
99+
</listitem>
100+
</varlistentry>
101+
102+
<varlistentry>
103+
<term>
104+
<option>--delete</option>,
105+
<option>-d</option>
106+
</term>
107+
<listitem>
108+
<para>
109+
Delete the stored MRZ.
110+
</para>
111+
</listitem>
112+
</varlistentry>
113+
</variablelist>
114+
</para>
115+
</refsect1>
116+
117+
<refsect1>
118+
<title>See also</title>
119+
<para>
120+
<citerefentry>
121+
<refentrytitle>opensc.conf</refentrytitle>
122+
<manvolnum>5</manvolnum>
123+
</citerefentry>
124+
</para>
125+
</refsect1>
126+
127+
<refsect1>
128+
<title>Authors</title>
129+
<para><command>cedulauy-tool</command> was written by
130+
Nicolás Gutiérrez <email>ngutierreztassano@gmail.com</email>.</para>
131+
</refsect1>
132+
133+
</refentry>

‎doc/tools/tools.html‎

Lines changed: 148 additions & 99 deletions
Large diffs are not rendered by default.

‎doc/tools/tools.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
<title>OpenSC Manual Pages: Section 1</title>
77

88
<xi:include href="cardos-tool.1.xml"/>
9+
<xi:include href="cedulauy-tool.1.xml"/>
910
<xi:include href="cryptoflex-tool.1.xml"/>
1011
<xi:include href="dnie-tool.1.xml"/>
1112
<xi:include href="egk-tool.1.xml"/>

‎packaging/opensc.spec‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,8 @@ rm -f $RPM_BUILD_ROOT%{_libdir}/libsmm-local.so
133133
%if 0%{?rhel}
134134
rm -rf %{buildroot}%{_bindir}/npa-tool
135135
rm -rf %{buildroot}%{_mandir}/man1/npa-tool.1*
136+
rm -rf %{buildroot}%{_bindir}/cedulauy-tool
137+
rm -rf %{buildroot}%{_mandir}/man1/cedulauy-tool.1*
136138
%endif
137139

138140
# the pkcs11-register is not applicable to Fedora/RHEL where we use p11-kit
@@ -161,6 +163,7 @@ rm %{buildroot}%{_mandir}/man1/ctk-tool.1*
161163
%{_bindir}/netkey-tool
162164
%if ! 0%{?rhel}
163165
%{_bindir}/npa-tool
166+
%{_bindir}/cedulauy-tool
164167
%endif
165168
%{_bindir}/openpgp-tool
166169
%{_bindir}/opensc-explorer
@@ -188,6 +191,7 @@ rm %{buildroot}%{_mandir}/man1/ctk-tool.1*
188191
%{_mandir}/man1/netkey-tool.1*
189192
%if ! 0%{?rhel}
190193
%{_mandir}/man1/npa-tool.1*
194+
%{_mandir}/man1/cedulauy-tool.1*
191195
%endif
192196
%{_mandir}/man1/openpgp-tool.1*
193197
%{_mandir}/man1/opensc-explorer.*

‎src/libopensc/Makefile.am‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ noinst_HEADERS = cards.h ctbcs.h internal.h muscle.h muscle-filesystem.h \
1313
authentic.h iasecc.h iasecc-sdo.h sm.h card-sc-hsm.h \
1414
pace.h cwa14890.h cwa-dnie.h card-gids.h aux-data.h \
1515
jpki.h sc-ossl-compat.h card-npa.h card-openpgp.h \
16-
card-eoi.h card-dtrust.h card-srbeid.h ccid-types.h reader-tr03119.h \
16+
card-eoi.h card-dtrust.h card-srbeid.h card-cedulauy-cache.h card-cedulauy.h ccid-types.h reader-tr03119.h \
1717
card-cac-common.h card-cardos-common.h
1818

1919
AM_CPPFLAGS = -D'OPENSC_CONF_PATH="$(sysconfdir)/opensc.conf"' \
Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
/*
2+
* card-cedulauy-cache.h: MRZ cache of the Uruguayan eID card (cédula de identidad)
3+
*
4+
* Copyright (C) 2026 Nicolás Gutiérrez <ngutierreztassano@gmail.com>
5+
*
6+
* This library is free software; you can redistribute it and/or
7+
* modify it under the terms of the GNU Lesser General Public
8+
* License as published by the Free Software Foundation; either
9+
* version 2.1 of the License, or (at your option) any later version.
10+
*
11+
* This library is distributed in the hope that it will be useful,
12+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14+
* Lesser General Public License for more details.
15+
*
16+
* You should have received a copy of the GNU Lesser General Public
17+
* License along with this library; if not, write to the Free Software
18+
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19+
*/
20+
21+
#ifndef _CARD_CEDULAUY_CACHE_H
22+
#define _CARD_CEDULAUY_CACHE_H
23+
24+
#include <errno.h>
25+
#include <limits.h>
26+
#include <stdio.h>
27+
#include <string.h>
28+
#ifndef _WIN32
29+
#include <fcntl.h>
30+
#include <sys/stat.h>
31+
#include <unistd.h>
32+
#endif
33+
34+
#include "common/compat_strlcat.h"
35+
#include "libopensc/log.h"
36+
#include "libopensc/opensc.h"
37+
38+
/* the three TD1 lines of 30 characters, concatenated */
39+
#define CEDULAUY_MRZ_LEN 90
40+
#define CEDULAUY_MRZ_CACHE_FILE "cedulauy_mrz"
41+
42+
static inline int
43+
cedulauy_mrz_cache_path(sc_context_t *ctx, char *buf, size_t buflen)
44+
{
45+
int r = sc_get_cache_dir(ctx, buf, buflen);
46+
if (r < 0)
47+
return r;
48+
49+
if (strlcat(buf, "/" CEDULAUY_MRZ_CACHE_FILE, buflen) >= buflen)
50+
return SC_ERROR_BUFFER_TOO_SMALL;
51+
52+
return SC_SUCCESS;
53+
}
54+
55+
static inline FILE *
56+
cedulauy_create_mrz_cache(sc_context_t *ctx, const char *path)
57+
{
58+
#ifdef _WIN32
59+
(void)ctx;
60+
/* the profile directory ACL already restricts access to the user */
61+
return fopen(path, "wb");
62+
#else
63+
FILE *f;
64+
int fd = open(path, O_WRONLY | O_CREAT | O_TRUNC, S_IRUSR | S_IWUSR);
65+
66+
if (fd < 0)
67+
return NULL;
68+
69+
/* O_CREAT does not change the mode of an existing file */
70+
if (fchmod(fd, S_IRUSR | S_IWUSR) < 0)
71+
sc_log(ctx, "Cannot restrict the permissions of %s", path);
72+
73+
f = fdopen(fd, "wb");
74+
if (f == NULL)
75+
close(fd);
76+
77+
return f;
78+
#endif
79+
}
80+
81+
/* returns 1 if a complete MRZ was read, 0 otherwise */
82+
static inline int
83+
cedulauy_read_mrz_cache(sc_context_t *ctx, unsigned char mrz[CEDULAUY_MRZ_LEN])
84+
{
85+
char path[PATH_MAX];
86+
FILE *f;
87+
size_t got;
88+
89+
if (cedulauy_mrz_cache_path(ctx, path, sizeof path) < 0)
90+
return 0;
91+
92+
f = fopen(path, "rb");
93+
if (f == NULL)
94+
return 0;
95+
96+
got = fread(mrz, 1, CEDULAUY_MRZ_LEN, f);
97+
fclose(f);
98+
99+
if (got != CEDULAUY_MRZ_LEN) {
100+
sc_log(ctx, "Ignoring %s, it is not %d characters long", path, CEDULAUY_MRZ_LEN);
101+
return 0;
102+
}
103+
104+
return 1;
105+
}
106+
107+
static inline int
108+
cedulauy_write_mrz_cache(sc_context_t *ctx, const unsigned char mrz[CEDULAUY_MRZ_LEN])
109+
{
110+
char path[PATH_MAX];
111+
FILE *f;
112+
size_t written;
113+
int r;
114+
115+
LOG_FUNC_CALLED(ctx);
116+
117+
r = cedulauy_mrz_cache_path(ctx, path, sizeof path);
118+
LOG_TEST_RET(ctx, r, "Cannot determine the cache directory");
119+
120+
f = cedulauy_create_mrz_cache(ctx, path);
121+
if (f == NULL && errno == ENOENT) {
122+
r = sc_make_cache_dir(ctx);
123+
LOG_TEST_RET(ctx, r, "Cannot create the cache directory");
124+
f = cedulauy_create_mrz_cache(ctx, path);
125+
}
126+
if (f == NULL) {
127+
sc_log(ctx, "Cannot open %s: %s", path, strerror(errno));
128+
LOG_FUNC_RETURN(ctx, SC_ERROR_INTERNAL);
129+
}
130+
131+
written = fwrite(mrz, 1, CEDULAUY_MRZ_LEN, f);
132+
if (fclose(f) != 0 || written != CEDULAUY_MRZ_LEN) {
133+
sc_log(ctx, "Cannot write %s: %s", path, strerror(errno));
134+
LOG_FUNC_RETURN(ctx, SC_ERROR_INTERNAL);
135+
}
136+
137+
sc_log(ctx, "MRZ stored in %s", path);
138+
LOG_FUNC_RETURN(ctx, SC_SUCCESS);
139+
}
140+
141+
static inline int
142+
cedulauy_delete_mrz_cache(sc_context_t *ctx)
143+
{
144+
char path[PATH_MAX];
145+
int r;
146+
147+
LOG_FUNC_CALLED(ctx);
148+
149+
r = cedulauy_mrz_cache_path(ctx, path, sizeof path);
150+
LOG_TEST_RET(ctx, r, "Cannot determine the cache directory");
151+
152+
if (remove(path) != 0) {
153+
int err = errno;
154+
sc_log(ctx, "Cannot remove %s: %s", path, strerror(err));
155+
LOG_FUNC_RETURN(ctx, err == ENOENT ? SC_ERROR_FILE_NOT_FOUND : SC_ERROR_INTERNAL);
156+
}
157+
158+
sc_log(ctx, "MRZ removed from %s", path);
159+
LOG_FUNC_RETURN(ctx, SC_SUCCESS);
160+
}
161+
162+
#endif

0 commit comments

Comments
 (0)