Document Reader SDK: Certificate Pinning

Use Certificate Pinning to enhance server identity trust in mobile apps, establishing a secure connection and mitigating man-in-the-middle risks.

Certificate Pinning on Mobile schema

AndroidiOS

In this guide, we'll walk you through the process of SSL pinning on Android, focusing on the generation of a certificate public hash key and its integration into the Android Network Security Configuration.

1. In the OpenSSL command line tool, enter the following command to generate the .der file. Make sure to replace your-server with the one you want to generate.

openssl s_client -connect your-server.com:443 -showcerts < /dev/null | openssl x509 -outform der > server_cert.der

2. After generating the certificate, create a public key in a pem file. Replace the name server_cert with the name generated in step 1.

openssl x509 -inform der -in server_cert.der -pubkey -noout > server_cert_public_key.pem

3. Now you need to hash the certificate with a hashing algorithm. In the example below, we use SHA256 to hash our key. Replace the server_cert_public_key.pem name with the one you provided.

cat server_cert_public_key.pem | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

4. To insert the public hash key into Android network security configuration, open your AndroidManifest.xml file and add the following <network-security-config> block within the <application> element:

<application>
    <!-- ... -->
    <meta-data
        android:name="android.security.net.config"
        android:resource="@xml/network_security_config" />
    <!-- ... -->
</application>

5. Create a new XML file (for example, network_security_config.xml) in the res/xml directory with the following content:

<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">api.regulaforensics.com</domain>
        <pin-set>
            <pin digest="SHA-256">/5RKFaPkCjAzvsEZHOlYqncYADaLIG5VfTmhsBbkaBk=</pin>
        </pin-set>
    </domain-config>
</network-security-config>

Insert the obtained public hash key as the value of the <pin> element.

6. To test SSL pinning, intentionally change a character in the pin value to make it invalid. When making a request, the system should detect the incorrect pin and terminate the process.

In this guide, we'll walk you through the process of SSL pinning, focusing on the generation and integration of a certificate public hash key.

1. Open your terminal and enter the following command to generate the .cer file. Replace your-server with your desired server.

openssl s_client -connect your-server.com:443 -showcerts < /dev/null | openssl x509 -outform der > server_cert.cer

2. After generating the certificate, create a public key in a .pem file. Replace the name server_cert with the one generated in step 1.

openssl x509 -inform der -in server_cert.cer -pubkey -noout > server_cert_public_key.pem

3. Hash the certificate with a hashing algorithm. In the example below, we use SHA256 to hash our key. Replace the server_cert_public_key.pem name with your provided name.

cat server_cert_public_key.pem | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

4. To integrate the public hash key into iOS, open your Xcode project and update target Info.plist so it includes the NSPinnedDomains section in the NSAppTransportSecurity settings:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSPinnedDomains</key>
    <dict>
        <key>your-server.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSPinnedLeafIdentities</key>
            <array>
                <dict>
                    <key>SPKI-SHA256-BASE64</key>
                    <string>r/mIkG3eEpVdm+u/ko/cwxzOMo1bk4TyHIlByibiA5E=</string>
                </dict>
            </array>
        </dict>
    </dict>
</dict>

Replace your-server.com with your actual server domain.

Replace SHA-256 hash key in the NSPinnedLeafIdentities array with generated one.

5. To test SSL pinning, intentionally change a character in the public hash key value to make it invalid. When making a request, the system should detect the incorrect pin and terminate the process.

Examples

See the sample projects, demonstrating usage of Certificate Pinning:

iOS
Android