Skip to content

Instantly share code, notes, and snippets.

@milanstevanovic

milanstevanovic/serbian-digital-certificate-macos-guide.md

Created April 1, 2026 12:48
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save milanstevanovic/0c45d50713af150207382de751fd7bc9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save milanstevanovic/0c45d50713af150207382de751fd7bc9 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
serbian-digital-certificate-macos-guide.md

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ć 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.

  1. Go to 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 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
  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
  • ePorezi
  • 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.

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
  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
  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:

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

Verify JavaFX is included:

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):

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):

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
  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
  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:

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
Baš Čelik (ID card reader) github.com/ubavic/bas-celik
Ubavić blog — e-documents ubavic.rs/e-documents
NexU-APR download dl.apr.gov.rs
APR electronic signing page aplikacije3.apr.gov.rs/ElektronskoPotpisivanje
Azul Zulu FX download azul.com/downloads
Adobe Acrobat Reader get.adobe.com/reader
MUP CA certificates ca.mup.gov.rs
APR tech support sd@apr.gov.rs / 011-418-2000

Credits

This guide would not be possible without Nikola Ubavić's open-source work on srb-id-pkcs11 and Baš Čelik.

Last updated: April 2026

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment