Project Setup

Set up your TrustPin project and configure certificate pinning for your mobile application.

Prerequisites

Before you begin, ensure you have:

• A TrustPin account (Sign up )
• Access to your server’s SSL certificates
• Admin access to your domains
• A mobile application (iOS, Android, or Flutter)

Step 1: Create Your Account

Sign Up / Sign In

1. Visit app.trustpin.cloud 
2. Click Sign In or Start Free Trial.
3. Sign in using Google, GitHub, or create an account.
4. After signing in, you’ll be taken to the TrustPin Dashboard.

Step 2: Create a Project

Projects organize your certificate pinning configurations by application.

Create New Project

1. From the dashboard, click Create a new project
2. Enter your project details:
   • Organization: If you belong to multiple organizations, select the one for this project.
   • Project name: e.g., “MyApp (Testing)”
3. Click Next
4. Select a type of Key Management and then click Next. You can choose between:
   • Cloud Managed Key: Keys are created in your browser and encrypted with a password. The encrypted keys are stored server-side and can only be decrypted with your password. This option is especially useful for development and testing environments.
   • Bring Your Own Key: Create and store an ECDSA P-256 key that is never uploaded. When required, use our CLI tool to sign your configurations locally and securely. The recommended choice for production applications.
   • FIDO Protected Keys: Alternative key protection using FIDO security keys (advanced option).
5. This next step depends on the selected key management type.
6. After key management selection, enter a list of domains and/or sub-domains separated by comma.
7. Click Create project

Cloud Managed Key

1. Enter your master password. This password will be used to sign your project’s configuration. Store it securely.
2. The generated public key corresponds to a private key generated in your browser.
3. Click Next.

Bring Your Own Key

1. Assign your key a Key ID.
2. Generate the key pair using the suggested code.
3. Copy the public key in PEM format where it’s required.
4. Don’t forget to safely store your keypair, and never share the private key.
5. Click Next.

FIDO Protected Keys

1. Follow the on-screen instructions for FIDO authentication.
2. Click Next and continue with the project setup.

Project Credentials

For any given project you will have:

• Organization ID: Your organization identifier
• Project ID: Unique project identifier
• Public Key: Base64-encoded ECDSA P-256 public key for signature verification

Important: You’ll need these to initialize the SDK. None of these three elements are considered sensitive information.

Step 3: Add Domains

Configure the domains your application will connect to.

Add a Domain

1. Navigate to your project
2. In the workflow steps on the left side, click Set up domains
3. Click Add domain
4. Enter your domain:

   api.example.com

5. Click Add Domain

Domain Configuration

Click Edit to modify domains and their certificates. For each domain, you can add one or more certificates (for example, current and future certificates).

To add a new certificate to a domain, click Add Certificate. You can delete a specific certificate by clicking Delete in its box, or remove the entire domain by clicking Delete domain.

Each certificate can include the following fields:

• Expiration: When this certificate expires. If left blank, it will not expire.
• Fingerprint and SPKI: Information about the leaf certificate
• Issuer: Who issued this certificate
• Serial Number (optional): Serial number of the certificate
• Certificate Transparency Logs

At least one of the following should be defined in order to have a valid configuration:

• SHA256 fingerprint
• SHA512 fingerprint
• SPKI SHA256
• SPKI SHA512

Certificate fingerprint has precedence over SPKI info. For example:

• If you define the four fields, the SDK will do SHA256 fingerprint first.
• If you define one fingerprint and one SPKI, the SDK will test the fingerprint first.
• If you want to use SPKI, do not specify either SHA256 or SHA512.

Important: After making any changes, click Apply changes. These changes will be saved locally and not sent to devices. Your configuration reaches users’ devices only when you publish your configuration.

Pinning Methods

Why SPKI Pinning is Preferred

SPKI (Subject Public Key Info) pinning is the OWASP-recommended approach for certificate pinning:

Advantages of SPKI Pinning:

• OWASP best practice: Industry-standard recommendation per OWASP Mobile Security Testing Guide
• Universal compatibility: Works with all certificate providers (AWS ACM, Let’s Encrypt, Cloudflare, self-managed)
• Dynamic rotation: TrustPin’s remote pin updates enable zero-downtime certificate rotation without app releases
• Pins the public key: More flexible than pinning entire certificates

How Certificate Renewal Works with SPKI Pinning:

Most certificate services handle key rotation in one of two ways:

1. Key Rotation (Default Behavior - Most Common):

• AWS ACM: Always generates new key pairs on renewal
• Let’s Encrypt: Generates new key pairs by default
• Cloudflare: Generates new key pairs by default

When keys rotate, the SPKI pin changes. TrustPin handles this seamlessly through dynamic pin updates—you add the new pin before the old certificate expires, and mobile apps fetch the updated configuration automatically.

2. Key Reuse (Optional - Manual Configuration):

• Let’s Encrypt: Use certbot renew --reuse-key to keep the same key pair
• Self-Managed: Reuse your private key when requesting certificate renewals

When keys are reused, the SPKI pin remains unchanged, and no TrustPin configuration update is needed.

Recommendation: Use SPKI pinning with TrustPin’s dynamic updates regardless of whether your certificate provider rotates keys. This gives you the OWASP-recommended approach plus zero-downtime rotation capability.

When to Use Leaf Certificate Pinning:

• Compliance requirements mandate full certificate fingerprinting
• You need to validate certificate metadata (serial number, issuer)
• Strictest validation is required

For all auto-renewal systems, SPKI pinning + TrustPin’s dynamic updates is the recommended approach to avoid service disruptions.

Hash Algorithm Selection

Recommendation: Use SPKI SHA-256 for most applications. Upgrade to SPKI SHA-512 only if your security requirements specifically mandate stronger cryptographic guarantees.

Step 4: Publishing configuration

1. In the workflow steps on the left side, click Publish config. This page provides an overview of your project status.

You can see the public key and the configuration file hosted on the CDN. The online configuration file has the information used by the SDK in your application to do certificate pinning.

When your project configuration differs from the online version, you can publish the new changes. After reviewing the configuration, click Publish.

Publishing the configuration may be disabled in the web dashboard if you selected Bring Your Own Key (BYOK). Remember that BYOK should be used alongside the CLI to sign configurations.

For Cloud Managed Keys and FIDO Keys click on Publish. Your master password or FIDO key will be required. After that, your configuration file will be updated.

Step 5: SDK Integration

Integrate TrustPin into your mobile application.

Choose Your Platform

Select the appropriate SDK for your platform and follow the instructions:

• iOS/Swift SDK
• Android/Kotlin SDK
• Flutter SDK

Best Practices

Security

1. Never commit credentials to version control
2. Use environment variables for sensitive data
3. Enable strict mode in production
4. Rotate pins before expiration
5. Monitor pin validation failures

Configuration Management

1. Separate projects for each environment
2. Document domain configurations
3. Keep certificates up to date
4. Test in staging before production
5. Use version control for configuration

Development Workflow

1. Start with permissive mode during development
2. Test all API endpoints with pinning enabled
3. Validate configurations in staging environment
4. Switch to strict mode before production release
5. Monitor logs for issues

Troubleshooting Setup

Cannot Create Project

Issue: Project creation fails

Solutions:

• Check account permissions
• Verify email is confirmed
• Contact support if issue persists

Invalid Credentials Error

Issue: SDK initialization fails with INVALID_PROJECT_CONFIG

Solutions:

• Verify Organization ID is correct
• Check Project ID matches dashboard
• Ensure Public Key is properly base64-encoded
• Remove any whitespace from credentials

Certificate Upload Fails

Issue: Certificate upload returns error

Solutions:

• Verify certificate format (PEM, DER, etc.)
• Check certificate is valid (not expired)
• Ensure certificate matches domain
• Try uploading via different method (file vs paste)

Domain Not Accessible

Issue: Cannot add domain to project

Solutions:

• Verify domain ownership
• Check DNS is configured correctly
• Ensure domain uses HTTPS
• Verify firewall allows access

Next Steps

After completing setup:

1. Deploy Your Application
2. Learn How Certificate Pinning Works
3. Explore CLI Tools
4. Review Troubleshooting Guide

Support

Need help with setup?

• 📧 Email: support@trustpin.cloud
• 💬 Documentation: docs.trustpin.cloud 
• 🎯 Dashboard: app.trustpin.cloud