# Using a Serbian ID Card (MUP RS) for Digital Signing on macOS

A guide for using the qualified electronic certificate on a Serbian ID card (lična karta) on macOS — including signing documents for APR and authenticating on government portals like eUprava and ePorezi.

> ⚠️ **MUP does not officially support macOS.** This guide uses open-source tools created by [Nikola Ubavić](https://github.com/ubavic) as a replacement for the Windows-only TrustEdgeID middleware.

> Tested on: Apple Silicon (M3) + macOS Sequoia 15.x, April 2026.

---

## Prerequisites

| Item | Description |
|------|-------------|
| **Serbian ID card (lična karta)** | With a qualified electronic certificate written to the chip |
| **Smart card reader** | USB reader (e.g. Gemalto/Thales) |
| **macOS** | Apple Silicon (M1/M2/M3/M4) or Intel |

---

## Step 1: Install the PKCS#11 Middleware

Your Mac needs a PKCS#11 library to communicate with the smart card chip. On Windows, MUP provides TrustEdgeID for this. On macOS, we use the open-source [srb-id-pkcs11](https://github.com/ubavic/srb-id-pkcs11).

1. Go to [github.com/ubavic/srb-id-pkcs11/releases](https://github.com/ubavic/srb-id-pkcs11/releases)
2. Download the `.dylib` file for your architecture:
   - **Apple Silicon (M1/M2/M3/M4):** `libsrb-id-pkcs11.arm.x.x.x.dylib`
   - **Intel Mac:** `libsrb-id-pkcs11.x64.x.x.x.dylib`
3. Save it to a permanent location on your Mac. You'll need to reference this path later.

> If macOS blocks the `.dylib` from running, go to **System Settings → Privacy & Security** and click **Allow Anyway**. Alternatively, you can build the project locally with Zig — see the project README for instructions.

---

## Step 2: Verify Your Card Reader Works (Optional)

[Baš Čelik](https://github.com/ubavic/bas-celik) is a tool for reading data from Serbian ID cards (name, address, photo, etc.). It's not required for signing, but useful for confirming your reader and card work on macOS.

1. Go to [github.com/ubavic/bas-celik/releases](https://github.com/ubavic/bas-celik/releases)
2. Download the macOS version
3. Install and run it
4. Insert your ID card — it should display your personal data

If Baš Čelik reads the card successfully, your hardware setup is working.

---

## Step 3: Set Up Firefox for Government Portals

Firefox is required for authenticating on Serbian government portals (eUprava, ePorezi, etc.). It needs to be configured to use the PKCS#11 library.

1. Open Firefox
2. Go to **Settings → Privacy & Security**
3. Scroll to **Security Devices** (at the bottom)
4. Click **Load**
5. For **Module Name**, enter: `Serbian ID PKCS11`
6. For **Module filename**, enter the full path to your `.dylib` file
7. Click **OK**
8. Restart Firefox

You can now use your ID card for authentication on:
- [eUprava](https://euprava.gov.rs)
- [ePorezi](https://eporezi.purs.gov.rs)
- Other portals that support qualified electronic certificates

---

## Step 4: Set Up Adobe Acrobat Reader for PDF Signing (Optional)

If you want to sign PDFs directly in Adobe Acrobat Reader without using APR's NexU-APR application. Adobe Acrobat Reader is free: [get.adobe.com/reader](https://get.adobe.com/reader/).

### 4.1: Disable Acrobat's Security Sandbox

This is required — without it, the "Attach Module" button will be grayed out.

1. Open Adobe Acrobat and go to **Preferences** (`Cmd + ,`)
2. Select **Security (Enhanced)** on the left sidebar
3. Uncheck **Enable Protected Mode at startup**. If the Attach Module button is still grayed out later, also uncheck **Enable Enhanced Security**.
4. Click **OK**, then quit Acrobat completely (`Cmd + Q`) and reopen it

### 4.2: Attach the PKCS#11 Module

1. Open **Preferences** (`Cmd + ,`)
2. Select **Signatures** on the left
3. Under **Identities & Trusted Certificates**, click **More...**
4. In the new window, select **PKCS#11 Modules and Tokens** on the left
5. Click **Attach Module** at the top
6. When the file browser opens, press `Cmd + Shift + G`
7. Paste the full path to your `.dylib` file and press Return
8. Click **Open**

### 4.3: Configure Signing Preferences

1. Go to **Preferences** (`Cmd + ,`) → **Signatures**
2. Under **Creation & Appearance**, click **More...**
3. Set **Default Signing Format** to **CAdES-Equivalent**
4. Check **Include signature's revocation status** (this embeds OCSP/CRL data — requires internet during signing)
5. Click **OK**

### 4.4: Configure Verification Preferences

1. Go to **Preferences** (`Cmd + ,`) → **Signatures**
2. Under **Verification**, click **More...**
3. Check **Verify signatures when the document is opened**
4. Check **Require certificate revocation checking to succeed whenever possible during signature verification**
5. Under **Windows Integration** (at the bottom), check both:
   - **Validating Signatures**
   - **Validating Certified Documents**
6. Click **OK**

### 4.5: Trust the MUP Root Certificates in macOS

macOS doesn't trust Serbian government certificates by default.

1. Download the MUP root CA certificates from the [MUP CA website](https://ca.mup.gov.rs)
2. Double-click each `.crt` file
3. When prompted, set the Keychain dropdown to **System** and click **Add**
4. Open **Keychain Access** (`Cmd + Space`, search for it)
5. Select **System** on the left sidebar
6. Find the MUP certificates you just added
7. Double-click each certificate to open its settings
8. Expand the **Trust** section (click the triangle)
9. Change the top dropdown to **Always Trust**
10. Close the window and enter your Mac password to confirm

Repeat for both the Root CA and any Intermediate CA certificates.

### 4.6: Sign a PDF in Adobe Acrobat

1. Insert your ID card into the reader
2. Open the PDF you want to sign in Adobe Acrobat
3. Go to the PKCS#11 Modules and Tokens menu (Preferences → Signatures → Identities & Trusted Certificates → More...)
4. Expand your loaded module to reveal your smart card token
5. Select your token and click **Login** — enter your 4-digit PIN
6. Close Preferences, then go to **More Tools → Certificates**
7. Click **Digitally Sign** in the toolbar
8. Draw a rectangle on the PDF where you want the signature to appear
9. In the **Sign with a Digital ID** dialog, select the certificate marked for **Digital Signature - Non Repudiation** (not the authentication certificate)
10. Check **Lock document after signing**
11. Click **Sign**, choose where to save the signed PDF, and enter your PIN again when prompted

> **Important:** Your ID card may contain two certificates — one for authentication and one for signing. Always select the one designated for digital signing (Non Repudiation).

---

## Step 5: Set Up NexU-APR for APR Document Signing (Optional)

NexU-APR is APR's own signing application, used when submitting documents through APR's e-applications. It requires Java 8 with JavaFX.

### 5.1: Install Java 8 with JavaFX

Standard OpenJDK 8 builds (Temurin, regular Zulu) **do not include JavaFX** and will not work — NexU-APR will crash on launch with `NoClassDefFoundError: javafx/application/Application`. You need the **JDK FX** variant specifically.

1. Go to [azul.com/downloads](https://www.azul.com/downloads/)
2. Filter by: **Java 8** → **macOS** → **ARM 64-bit** (or x64 for Intel) → **JDK FX**
3. Download the **.dmg** file and install it

Verify the installation:

```bash
/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home/bin/java -version
```

Verify JavaFX is included:

```bash
ls /Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home/jre/lib/ext/jfxrt.jar
```

If the file exists, Java is ready.

### 5.2: Configure JAVA_HOME

NexU-APR needs to find Java 8. If you have other Java versions installed, you have two options:

**Option A — Set Java 8 as the system default:**

Add to your shell config (e.g. `~/.zshrc`):

```bash
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home
export PATH="$JAVA_HOME/bin:$PATH"
```

Run `source ~/.zshrc` to apply. This changes `java` globally — other Java versions you have installed will no longer be the default.

**Option B — Launch NexU with Java 8 without changing the system default:**

Add an alias to your shell config (e.g. `~/.zshrc`):

```bash
alias nexu='JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home /Applications/NexuAPR.app/Contents/MacOS/NexuAPR &'
```

Run `source ~/.zshrc` to apply. Then launch NexU from the terminal by typing `nexu`. Your default Java remains unchanged.

### 5.3: Install NexU-APR

1. Download: [http://dl.apr.gov.rs/NexUAPR.dmg](http://dl.apr.gov.rs/NexUAPR.dmg)
2. Open the DMG and drag **NexUAPR** to **Applications**
3. First launch: Finder → Applications → **Control-click** on NexuAPR → **Open** (to bypass Gatekeeper)
4. A proxy settings dialog will appear — leave all fields empty and click **U Redu**
5. The NexU icon will appear in the menu bar (top right)

### 5.4: Verify Browser Can See NexU

1. Open your browser and go to: `https://localhost:9889/favicon.ico`
2. If you get a security warning:
   - Firefox: click **Advanced → Accept the Risk and Continue**
   - Chrome/Edge: click **Advanced → Proceed to localhost**
3. You should see the NexU-APR icon — this confirms the application is running

### 5.5: Sign a Document via APR

1. Insert your ID card into the reader
2. Make sure NexU-APR is running
3. Open: [https://aplikacije3.apr.gov.rs/ElektronskoPotpisivanje](https://aplikacije3.apr.gov.rs/ElektronskoPotpisivanje)
4. Click **Pokreni potpisivanje**
5. Select the PDF file you want to sign
6. On the **Metod pristupa tokenu** screen:
   - Select **MUP** from the certification authority list
   - Select **Direktan pristup smart kartici (PKCS #11)**
   - Click **Detaljna Podešavanja**
   - Click **Izmeni**
   - Click **Odaberi** and browse to your `.dylib` file
   - Click **Prihvati**
7. Click **Nastavi**
8. Enter your PIN
9. Select the qualified certificate (marked with a green icon) and click **Nastavi**
10. Optionally check "Dodaj sliku potpisa u dokument" to add a visible signature
11. Click **Nastavi** and save the signed PDF

> NexU-APR remembers the `.dylib` path, so you only need to configure it once.

---

## Troubleshooting

### NexU-APR crashes on launch

Most likely using the wrong Java version or a Java 8 build without JavaFX. Launch from the terminal to see the error:

```bash
JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home /Applications/NexuAPR.app/Contents/MacOS/NexuAPR
```

If you see `NoClassDefFoundError: javafx/application/Application`, you need the **JDK FX** variant from Azul, not a regular JDK 8.

### Card reader not detected

- Verify the reader is plugged in and the card is inserted
- Test with **Baš Čelik** first — if it reads the card, the hardware works
- Try a different USB port
- Check that the `.dylib` path in NexU/Adobe/Firefox is correct

### Firefox doesn't see the certificate

- Verify the PKCS#11 module is loaded: Settings → Privacy & Security → Security Devices
- Restart Firefox after adding the module
- Your card has two certificates — authentication and signing. Government portals use the authentication certificate.

### macOS blocks the `.dylib` file

Go to **System Settings → Privacy & Security** and click **Allow Anyway**. Alternatively, build the project locally with Zig (see the srb-id-pkcs11 README).

### Adobe Acrobat shows signature as "unknown" or "invalid"

- Make sure you installed and trusted the MUP Root CA certificates in Keychain Access (Step 4.5)
- Verify your system clock, date, and timezone are correct (CET/CEST)
- Ensure **Include signature's revocation status** is checked in Acrobat's signing preferences
- Internet access is required during signing for OCSP/CRL checks

### "Arch not recognized aarch64" warnings in NexU log

Harmless. NexU-APR doesn't recognize the Apple Silicon architecture label but runs correctly.

---

## Links

| Resource | URL |
|----------|-----|
| srb-id-pkcs11 (PKCS#11 middleware) | [github.com/ubavic/srb-id-pkcs11](https://github.com/ubavic/srb-id-pkcs11) |
| Baš Čelik (ID card reader) | [github.com/ubavic/bas-celik](https://github.com/ubavic/bas-celik) |
| Ubavić blog — e-documents | [ubavic.rs/e-documents](https://ubavic.rs/e-documents/) |
| NexU-APR download | [dl.apr.gov.rs](http://dl.apr.gov.rs) |
| APR electronic signing page | [aplikacije3.apr.gov.rs/ElektronskoPotpisivanje](https://aplikacije3.apr.gov.rs/ElektronskoPotpisivanje) |
| Azul Zulu FX download | [azul.com/downloads](https://www.azul.com/downloads/) |
| Adobe Acrobat Reader | [get.adobe.com/reader](https://get.adobe.com/reader/) |
| MUP CA certificates | [ca.mup.gov.rs](https://ca.mup.gov.rs) |
| APR tech support | sd@apr.gov.rs / 011-418-2000 |

---

## Credits

This guide would not be possible without [Nikola Ubavić](https://github.com/ubavic)'s open-source work on [srb-id-pkcs11](https://github.com/ubavic/srb-id-pkcs11) and [Baš Čelik](https://github.com/ubavic/bas-celik).

---

*Last updated: April 2026*