Skip to content

Added support for client side certificates (mTLS)#125

Open
cat101 wants to merge 4 commits intojensomato:developfrom
cat101:develop
Open

Added support for client side certificates (mTLS)#125
cat101 wants to merge 4 commits intojensomato:developfrom
cat101:develop

Conversation

@cat101
Copy link
Copy Markdown

@cat101 cat101 commented Oct 5, 2025

I use HAProxy to expose my self-hosted services to the Internet. In order prevent unauthorized access and discourage bots I use mutual authentication (mTLS). As of know the Readeck app would fail to connect to mTLS backend.

I have done this PR purelly using RooCode/Claude. I have 30 years of programming experience but I have never worked on Android. I have built the apk, sideloaded it to my device and verifyed that it works.

The rest is the PR description written by Claude and reviewed by me 😄

Summary

This PR adds support for mutual TLS (mTLS) client certificate authentication, enabling the app to connect to servers (like HAProxy) that require client certificates during the TLS handshake.

Problem

When connecting to servers configured with mTLS authentication, the app would fail with:

Network error: Read error: ssl=0x4000070c0e1fb08: Failure in SSL library, 
usually a protocol error
error:1000045c:SSL routines:OPENSSL_internal:TLSV1_ALERT_CERTIFICATE_REQUIRED

This occurred because the app wasn't providing a client certificate when the server requested one during the TLS handshake.

Solution

Implemented a complete mTLS solution that:

  • ✅ Integrates with Android's system KeyChain for secure certificate access
  • ✅ Provides native certificate picker dialog (same UX as Chrome)
  • ✅ Stores only certificate alias (not the certificate itself) for security
  • ✅ Remembers user's certificate selection

Changes

New Components

SSL/Certificate Management (app/src/main/java/de/readeckapp/io/rest/ssl/):

  • ClientCertificateManager.kt - Manages certificate selection and KeyChain integration
  • CustomX509KeyManager.kt - Provides certificates during TLS handshake
  • SSLConfigurationProvider.kt - Configures OkHttp with SSL support
  • CertificateSelectionHelper.kt - UI-friendly helper for certificate operations

Modified Components

Network Layer:

  • NetworkModule.kt - Integrated SSL configuration with OkHttp client
  • SettingsDataStore.kt & SettingsDataStoreImpl.kt - Added certificate alias storage

UI Layer:

  • AccountSettingsScreen.kt - Added certificate selection UI with "Select Client Certificate" button
  • AccountSettingsViewModel.kt - Added certificate selection and management logic

How It Works

  1. Certificate Installation: User installs client certificate in Android system settings
  2. Certificate Selection: In Account Settings, user taps "Select Client Certificate"
  3. System Dialog: Android shows native certificate picker with installed certificates
  4. Secure Storage: App stores only the certificate alias in EncryptedSharedPreferences
  5. Automatic Authentication: During HTTPS requests, app automatically provides certificate during TLS handshake
  6. Server Validation: Server validates certificate and allows connection

@cat101
Copy link
Copy Markdown
Author

cat101 commented Feb 27, 2026

I have pulled the latest changes from your repo and updated the PR. BTW: I have been using my build with mTLS support since October with no problems

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant