{"type":"doc","content":[{"type":"bodiedExtension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"details","parameters":{"macroParams":{"hidden":{"value":"true"}},"macroMetadata":{"macroId":{"value":"87a661e756d05fd1bd12cfaccae13bfd"},"schemaVersion":{"value":"1"},"title":"Page Properties"}},"localId":"a8d9604f-4e66-4f43-9fdf-c9295aff1d10"},"content":[{"type":"table","attrs":{"layout":"default","localId":"3aced34c-0764-4c2b-9fab-3e91aa1472d5"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[620.0]},"content":[{"type":"paragraph","content":[{"text":"Status","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[597.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"green","style":"bold","text":"approved","localId":"86ca50ab-6b69-4f59-a67c-91519f75dbe4"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[620.0]},"content":[{"type":"paragraph","content":[{"text":"Approver","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[597.0]},"content":[{"type":"paragraph","content":[{"type":"mention","attrs":{"id":"5c7642abe73ff946487628c5","text":"@Alpar Szotyori (Unlicensed)"}},{"text":" ","type":"text"}]}]}]}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"6"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"29f89de7-4f88-4e7d-bac0-ebf6da8b218f"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"fd5ab055-1900-4aa0-b149-abeb34fe3de7"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Public key pinning is provided using the ","type":"text"},{"text":"Android Network Security Configuration","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.android.com/training/articles/security-config.html"}}]},{"text":" and ","type":"text"},{"text":"TrustKit","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/datatheorem/TrustKit-Android"}}]},{"text":". To use public key pinning, you can either create an ","type":"text"},{"text":"Android network security configuration","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.android.com/training/articles/security-config.html"}}]},{"text":" XML file or set a custom ","type":"text"},{"text":"TrustManager","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.android.com/reference/javax/net/ssl/TrustManager"}}]},{"text":" implementation. The network security configuration is supported natively on Android Nougat (API Level 24) and higher. For versions between API Level 21 and 23, the Gini SDK relies on ","type":"text"},{"text":"TrustKit","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/datatheorem/TrustKit-Android"}}]},{"text":". The custom ","type":"text"},{"text":"TrustManager","type":"text","marks":[{"type":"code"}]},{"text":" is supported on all Android versions. We recommend reading the ","type":"text"},{"text":"Android Network Security Configuration","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.android.com/training/articles/security-config.html"}}]},{"text":" guide and the ","type":"text"},{"text":"TrustKit limitations for API Levels 21 to 23","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/datatheorem/TrustKit-Android#limitations"}}]},{"text":".","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configure pinning","type":"text"}]},{"type":"paragraph","content":[{"text":"The following sample configuration shows how to set the public key pin for two domains. The Gini Capture SDK’s default networking implementation uses by default ","type":"text"},{"text":"pay-api.gini.net","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"user.gini.net","type":"text","marks":[{"type":"code"}]},{"text":". It should be saved under ","type":"text"},{"text":"res/xml/network_security_config.xml","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n pay-api.gini.net\n \n \n cNzbGowA+LNeQ681yMm8ulHxXiGojHE8qAjI+M7bIxU=\n \n zEVdOCzXU8euGVuMJYPr3DUU/d1CaKevtr0dW0XzZNo=\n \n \n \n user.gini.net\n \n \n","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"If you set different base URLs when instantiating with the ","type":"text"},{"text":"GiniCaptureDefaultNetworkService.Builder","type":"text","marks":[{"type":"code"}]},{"text":", make sure you set matching domains in the network security configuration XML.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"The above digests serve as an example only. You should ","type":"text"},{"text":"always","type":"text","marks":[{"type":"strong"}]},{"text":" create the digest yourself from the Gini API’s public key and use that one (see ","type":"text"},{"text":"Extract hash from pay-api.gini.net","type":"text","marks":[{"type":"link","attrs":{"href":"http://Extract-hash-from-pay-api.gini.net"}}]},{"text":"). If you receiv a digest from us, ","type":"text"},{"text":"always","type":"text","marks":[{"type":"strong"}]},{"text":" validate it by comparing it to the digest you created from the public key (see ","type":"text"},{"text":"Extract hash from public key","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]},{"text":"). Failing to validate a digest might lead to security vulnerabilities.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"TrustKit","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"TrustKit","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/datatheorem/TrustKit-Android"}}]},{"text":" configuration tag ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" is required in order to deactivate TrustKit reporting and to enforce public key pinning. This is important because without it TrustKit doesn’t throw ","type":"text"},{"text":"CertificateExceptions","type":"text","marks":[{"type":"code"}]},{"text":" if the local public keys don’t match any of the remote ones, effectively deactivating pinning. The only downside of enforcing pinning is that two public key hashes are required. In the example above, we created and used a “zero” key hash as a placeholder. Setting the same key hash twice doesn’t help because key hashes are stored in a set. Ideally, you should use a backup public key hash as the second one.","type":"text"}]},{"type":"paragraph","content":[{"text":"In your ","type":"text"},{"text":"AndroidManifest.xml","type":"text","marks":[{"type":"code"}]},{"text":" you need to set the ","type":"text"},{"text":"android:networkSecurityConfig","type":"text","marks":[{"type":"code"}]},{"text":" attribute on the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" tag to point to the XML:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n ...\n \n ...\n","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enable pinning with a network security configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"For the library to know about the XML, set the XML resource id using the ","type":"text"},{"text":"GiniCaptureDefaultNetworkService.Builder.setNetworkSecurityConfigResId()","type":"text","marks":[{"type":"code"}]},{"text":" method:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"kotlin"},"content":[{"text":"val defaultNetworkService = GiniCaptureDefaultNetworkService.builder(context)\n .setClientCredentials(\"gini-client-id\", \"GiniClientSecret\", \"example.com\")\n .setNetworkSecurityConfigResId(R.xml.network_security_config)\n .build();","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enable pinning with a custom TrustManager implementation","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also control which certificates to trust by passing your ","type":"text"},{"text":"TrustManager","type":"text","marks":[{"type":"code"}]},{"text":" implementation to the ","type":"text"},{"text":"GiniCaptureDefaultNetworkService.Builder.setTrustManager()","type":"text","marks":[{"type":"code"}]},{"text":" method:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"kotlin"},"content":[{"text":"val defaultNetworkService = GiniCaptureDefaultNetworkService.builder(context)\n .setClientCredentials(\"gini-client-id\", \"GiniClientSecret\", \"example.com\")\n .setTrustManager(yourTrustManager)\n .build();","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Setting a custom ","type":"text"},{"text":"TrustManager","type":"text","marks":[{"type":"code"}]},{"text":" overrides the network security configuration.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Extract hash from pay-api.gini.net","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ openssl s_client -servername pay-api.gini.net -connect pay-api.gini.net:443 | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Extract hash from public key","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also extract the hash from a public key. The following example shows how to extract it from a public key named ","type":"text"},{"text":"pay-api.gini.pub","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ cat pay-api.gini.pub | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported