SSL Trusted Certificates and SSL Pinning

Describes how to implement SSL trusted certificates and SSL pinning using the Mobile SDK and MAG.
mag42
Describes how to implement SSL trusted certificates and SSL pinning using the Mobile SDK and MAG.
SSL Pinning: An Extra Layer of Security
Implementing SSL pinning ensures that the Mobile SDK checks the server certificate against a list of known (trusted) certificates. Because enterprise channels use protocols like VPN, SSL, and TLS, they are vulnerable to attacks of trust like "man in the middle" eavesdropping. SSL pinning prevents someone from using a false SSL certificate to breach the trust between users, developers, and applications.
Typically, during the SSL or TLS handshake, when a client connects to a server, the server sends its digital certificate. If the certificate is issued by a Certificate Authority that is trusted by the mobile device OS, the connection is allowed. The data is sent through the connection, and is encrypted with the server’s public key. This process establishes a trust relationship. An attacker performing a “man in the middle” attack, makes the mobile device trust the attacker’s certificate. Typically, an attacker's certificate is not signed by a Certificate Authority trusted by the mobile device OS, but there is no certainty. In iOS 4.3.5, there was a vulnerability where "an attacker with a privileged network position" could capture or modify data in sessions that were protected by SSL/TLS. Mobile users also pose threats as attackers by trying to inspect encrypted network traffic. Users can easily manually install a trusted certificate, and potentially use it for such purposes. Using SSL Pinning avoids this type of traffic snooping.
SSL Certificate Methods
The Mobile SDK and MAG supports the following methods for SSL certificate security:
The MAG provides the attributes and certificates using the msso_config.json file, and the Mobile SDK provides the validation logic.
Although you can implement one or more of the following SSL certificate methods,
you must implement at least one to secure calls to APIs.
SSL Trusted Certificates
msso_config.json Attribute
trusted_public_pki
This method provides minimum level of security. During SSL or TLS handshake, the Mobile SDK evaluates the certificate presented by the server against the list of trusted root certificates on the device. If the certificate is not signed by a trusted Certificate Authority (CA), the connection is rejected.
Boolean: Validates/does not validate the server certificate against the list of trusted root certificates on the device.
Notes
:
  • If the MAG's certificate is
    self-signed,
    any requests from the SDK will fail because the certificate is not signed by a trusted Certificate Authority (CA).
  • The OAuth Manager exports only the leaf certificate – even if there are multiple certificates in the chain. For example, many publically signed CA certificates come with 2-4 certificates (root, mid, leaf); they are not automatically exported into the msso_config.json file. If your implementation requires validation against the entire chain, use a tool like
    openssl
    to export the chain and add them to the "server_certs" array in the msso_config.json file.
Enable SSL Trusted Certificates in Policy Manager
  1. Go to:
    Policy Manager
    ,
    MAG
    ,
    Policy Fragments
    ,
    configuration
    ,
    MAG Variable Configuration
    .
  2. Copy the Set Context Variable
    accept_public_pki
    assertion.
  3. Open the
    #MAG Variable Configuration
    policy and paste the assertion; additionally, set the value to
    true
    .
  4. Save and Activate
    .
The
enable_public_key_pinning
implementation is deprecated.
SSL Certificate Pinning 
There is no policy configuration for SSL certificate pinning. It is always enabled and cannot be disabled. If the
server_
certs[]
attribute is defined, pinning is performed; if not defined, pinning is not performed.
Certificate pinning (DER/CER format) is the most secure pinning method because it allows you to specify pinned certificate(s) in the trusted certificate list. The Mobile SDK validates and allows SSL connections only to servers that present certificates with the exact match of all information in the leaf certificate, including the expired date.
In this release, the Mobile SDK supports SSL pinning certificates generated:
  • By MAG in the
    server.server_certs
    of the msso_config.json file
    and/or
  • Using the property from the
    MASSecurityConfiguration
    object for a specific host
msso_config.json Attribute
server_certs[]
String: The trusted certificate(s) of the MAG server. The Mobile SDK automatically extracts this certificate (sample below), and sets it for the trusted certificate for pinning when the SDK connects to the MAG.
"server_certs":[ [ "-----BEGIN CERTIFICATE-----", "MIIDHDCCAgSgAwIBAgIIZYheF/Eg1vowDQYJKoZIhvcNAQEMBQAwLDEqMCgGA1UEAxMhbW9iaWxl", "LXN0YWdpbmctc2FuZGJveC5sN3RlY2guY29tMB4XDTE3MDExOTE4NDkyOVoXDTI3MDExNzE4NDky", "OVowLDEqMCgGA1UEAxMhbW9iaWxlLXN0YWdpbmctc2FuZGJveC5sN3RlY2guY29tMIIBIjANBgkq", "hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoXbHc5tCd6FganbGKtfpGnaXVPpEZ8Mxan1DR6CuCpO4", "fiCz1WdcPg8MKRkoSO5unZa+Ke9E3wMutVeStfwgsGyBdvbFijU2k5aeN7mS0IVtxCcvQ0PwUtb0", "LqSPVbuKnijauKboN1lclEpXNIN9n24eNdVN4h8Q1qpMv4FLT/qM8SOJwmMWrsKznFSjYR/eYy3c", "Vqqq5g4vpw9y01sjWZpe348+HuIY6IUZ6+2xRi5WslUaPNoQ1JkD9nkAG7Vge3t5pqFJxgade8LL", "oAxUklIhOtGjvEfhauDeHowPAg+YsZwrftmFexyQHaXCG1W9sQnwuhTfY57zuE4BEl+fUQIDAQAB", "o0IwQDAdBgNVHQ4EFgQUZDTpoe+A2yWclm635UO1GbbKoaUwHwYDVR0jBBgwFoAUZDTpoe+A2yWc", "lm635UO1GbbKoaUwDQYJKoZIhvcNAQEMBQADggEBAGxWTT5yk1fdoS6gA+A0iRzcIPs9YvtJ0R4U", "/ltsFiUK+KAI7nGkCP0wjX45HiGhFOwk6ECW01Zf5URuKtJuCeSRbhBloq/u0w1zV2B+ca15mW0p", "wIF5VUCeJyuIIu82iUsbL5Vma01zK2S+gRzY72gLTkcnw/7S44F5A0C7gOFjxi4eLVbtxQpDrRA7", "SdfOgTuwt72lf630U8paAG3wGpKHfEJ6eDfGqnEpf6Wr//EIy44f3GvAT6ogVrkRQu0tOlxH2HuP", "FqmeN7MybPSpKK2uiLm/bnmT+DpBByE5VfsbTeNNdYJ3h6og1rYJj7KxsXeEYGyjrTInO+aiInej", "osk=", "-----END CERTIFICATE-----" ] ]
SSL Public Key Hash Pinning
: Public Key Hash pinning is always enabled and cannot be disabled. If the
trusted_cert_hashes
attribute is defined, pinning is performed; if not defined, pinning is not performed.
Description
msso_config.json Attribute
The Mobile SDK extracts the public keys from the certificate from the server and validates against a list of strings that contains pinned public key hashes in base-64 format.
Note
: In this release, the supported Certificate Signature algorithm is
SHA256
with
RSA 2048
bits. SSL pinning fails if you use an unsupported algorithm.
trusted_cert_hashes[]
String: The trusted public key hashes of the server's certificates.
Enable SSL Public Key Hash Pinning in Policy Manager
  1. Go to:
    Policy Manager
    ,
    MAG
    ,
    Policy Fragments
    ,
    configuration
    ,
    MAG Variable Configuration
    .
  2. Copy the Set Context Variable
    trusted_
    cert_hashes
    assertion.
  3. Open the
    #MAG Variable Configuration
    policy and paste the assertion; additionally, provide the values of the trusted public key hashes as a string array.
  4. Save and Activate
    .
Additional Notes
The Mobile Client SDK performs SSL pinning based on the existence of
trusted_cert_hashes[]
(public key hash pinning) or
server_certs[]
(pinning using certificates)
values.
MAS Mobile SDK SSL Pinning.png