Omiseのライブラリとサーバー証明書の更新

概要

Omiseの公式ライブラリは、以前は証明書ピンニング(certificate pinning)というセキュリティ手法を採用していました。これは、想定されるサーバー証明書をライブラリ自体にハードコードしておく手法です。証明書ピンニングは現在ベストプラクティスとはみなされていないため、Omiseのライブラリからは削除されました。ただし、ピン留めされた古いバージョンのライブラリを引き続き使用している場合、ピン留めされた証明書が更新されると、Omiseのサーバーを信頼できなくなります。実際には、古いバージョンのライブラリを使用していると、チャージ作成を含むAPIリクエストが警告なく失敗する可能性があるということです。

これに関連して、もう一つの問題があります。OmiseのTLS証明書チェーンは、DigiCert G2証明書をルートとしています。ほとんどのシステムはすでにこの証明書を信頼していますが、古いサーバーやパッチ適用の頻度が低いサーバーでは信頼されていない場合があり、その場合は手動でインストールする必要があります。

バージョンの確認と修正:3つのステップ

1. プロジェクトの依存関係ファイルで、現在使用しているライブラリのバージョンを確認します(確認方法が分からない場合は、このページ末尾のFAQを参照してください)。
2. お使いのライブラリの必要な最小バージョンと比較します。
3. 現在のバージョンが最小バージョンを下回っている場合は、お使いの言語の更新手順に従って更新し、その後修正内容を確認してください。

修正前に問題を診断する

何かを変更する前に実際の問題を確認したい場合は、ターミナルからサーバーが現在認識している証明書チェーンを調べてください。

openssl s_client -connect api.omise.co:443 -showcerts

出力された証明書チェーンを確認してください。チェーンがシステムに認識されていないルート証明書で終わっている場合、またはハンドシェイク自体が失敗する場合は、証明書の信頼に関する問題であると確認できます(ネットワーク/ファイアウォールによるブロック、DNSの問題、アプリケーション側のバグなどではないということです)。このコマンドは、使用している言語やライブラリに関係なく、TLS接続そのものを直接テストするため、同じように機能します。

ライブラリの必要な最小バージョン

以下の表は、各ライブラリの必要な最小バージョン、リリース日、および完全な変更履歴(changelog)へのリンクを示しています。掲載されているバージョンに達していない場合は、統合に影響が出る前に更新してください。

この表に記載のないライブラリは、影響を受けることが確認されていません。ただし今後のリリースで状況が変わる可能性があるため、このページを定期的にご確認ください。

各ライブラリの更新方法

各セクションでは、基本的な更新例を示しています。実際のビルド環境は異なる場合がありますが、必要な最小バージョン以上にできる方法であればどのような手順でも構いません。

移動先: Android · iOS · Go · Java · PHP · Python · Ruby

SDK: Android

アプリのbuild.gradleファイルでバージョンを更新します:

dependencies {
    implementation 'co.omise:omise-android:3.0.0'
}

• TLS 1.1のサポート終了(2.6.5 → 2.6.6): 今後はTLS 1.2以上を使用してください。詳細についてはOmise社内のTLS廃止に関する通知を参照するか、詳細情報が必要でアクセス権がない場合はsupport@omise.coまでお問い合わせください。

SDK: iOS

Swift Package Manager向けのアップグレード手順をご覧ください。4.xブランチではiOS 10およびSwift 4のサポートが終了しています。

ライブラリ: Go

最新バージョンに更新する場合:

go get github.com/omise/omise-go

特定のバージョンに更新する場合:

go get github.com/omise/omise-go@v1.0.5

ライブラリ: Java

アプリのbuild.gradleファイルでバージョンを更新します:

dependencies {
    implementation 'co.omise:omise-java:3.1.1'
}

• 後方互換性のある変更のみ(4.x → 最新版): スムーズにアップグレードできるはずです。
• 後方互換性のない変更あり(3.1.1 → 4.0): 移行ガイドを参照してください。まだ最新版に移行できない場合は、少なくとも3.1.1にアップグレードしてください。

ライブラリ: PHP

composer.json内のバージョンを必要な最小バージョン以上に更新し、以下のコマンドを実行します:

composer update omise-php

2.x系の古いバージョンからアップグレードする場合は、更新前にchangelogを確認してください。3.0.0へのアップグレードは複数のリリースをまたぐため、単純な置き換えと考えず、現在お使いのバージョンに応じた変更内容を確認することをおすすめします。可能であればサポートが終了していない(non-EOL)PHPバージョンをご使用ください。

ライブラリ: Python

requirements.txt内のバージョンを必要な最小バージョン以上に更新し、以下のコマンドを実行します:

pip install --upgrade omise

どのバージョンからの更新も、後方互換性のない変更がないためスムーズに行えます。可能であればサポートが終了していない(non-EOL)Pythonバージョンをご使用ください。

ライブラリ: Ruby

Gemfile内のバージョンを必要な最小バージョン以上に更新し、以下のコマンドを実行します:

bundle update omise

どのバージョンからの更新も、後方互換性のない変更がないためスムーズに行えます。可能であればサポートが終了していない(non-EOL)Rubyバージョンをご使用ください。

Omiseのライブラリを使用していない場合

証明書ピンニングの問題は、このページに記載されているライブラリにのみ影響します。一方、DigiCertのルート証明書に関する問題はライブラリに依存せず、TLS接続そのものに影響するため、curlや生のHTTPクライアント、あるいはこのページに記載のない言語・フレームワークからOmiseのAPIを直接呼び出している場合でも影響を受ける可能性があります。

この状況に該当する場合、最小バージョンの表や各ライブラリ向けの手順は関係ありませんが、診断コマンドとこのページ後半で説明するサーバーのルート証明書の更新は引き続き関係します。まずは診断を実行し、実際にこれが該当する問題かどうかを確認してください。

PHPベースのプラグインの更新

EC-CUBE

インストールおよび設定の詳細については、EC-CUBEプラグインの公式ドキュメントをご覧ください。

Magento

インストールおよび設定の詳細については、Magentoプラグインの公式ドキュメントをご覧ください。

OpenCart

インストールおよび設定の詳細については、OpenCartプラグインの公式ドキュメントをご覧ください。

PrestaShop

インストールおよび設定の詳細については、PrestaShopプラグインの公式ドキュメントをご覧ください。

WooCommerce

インストールおよび設定の詳細については、WooCommerceプラグインの公式ドキュメントをご覧ください。

サーバーのルート証明書の更新

ライブラリを最新の状態に更新してもAPIリクエストが失敗し続ける場合、サーバーが信頼するルート証明書が古くなっている可能性があります。OmiseはDigiCert Global Root G2を証明書チェーンのルートとしています。背景情報についてはDigiCertのルート証明書更新に関するアドバイザリをご覧ください。

Linuxの場合

LinuxはCA証明書を/etc/ssl/certs/に保存しており、通常のOSアップデートによって自動的に更新されます。手動で更新する場合:

RHELおよびその派生版

1. /etc/pki/ca-trust/source/anchorsディレクトリがまだ存在しない場合は作成します。
2. DigiCert Global Root G2証明書をダウンロードします。
3. ダウンロードしたPEMファイルを/etc/pki/ca-trust/source/anchorsにコピーします。
4. システムのトラストストアに追加します:

sudo update-ca-trust extract

Debianおよびその派生版

1. /usr/local/share/ca-certificatesディレクトリがまだ存在しない場合は作成します。
2. DigiCert Global Root G2証明書をダウンロードします。
3. ダウンロードしたPEMファイルを/usr/local/share/ca-certificatesにコピーし、拡張子を.crtに変更します。
4. システムのトラストストアに追加します:

sudo update-ca-certificates

macOSの場合

通常のmacOSアップデートによってルート証明書は自動的に更新されます。手動で証明書を追加する場合は、DigiCert Global Root G2証明書をダウンロードし、Systemキーチェーンに追加してSSL用に信頼するよう設定します。以下のコマンド内のファイル名は、実際にダウンロードしたファイル名に合わせて変更してください:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain path/to/downloaded-certificate.crt

Windowsの場合

通常のOSアップデートによってルート証明書は自動的に更新されます。手動で更新する場合:

ステップ1: コマンドプロンプトを管理者として開きます。

ステップ2: 作業用フォルダ(例:C:\Temp)に移動します。

ステップ3: 以下のコマンドを実行します。このコマンドは、そのフォルダ内にRootstore.sstという名前のファイルとして、最新のルート証明書更新情報をダウンロードします。

CertUtil --generateSSTFromWU Rootstore.sst

ステップ4: 対象のサーバーがインターネットに接続されていない場合は、そのフォルダからRootstore.sstをオフラインのマシンにコピーし、そのマシン上でコマンドを直接実行する代わりに、ファイルをインポートしてください。

修正内容の確認

ライブラリ、サーバーのルート証明書、またはその両方を更新した後は、次に進む前に修正が正しく行われたことを確認してください。

1. テストリクエストを送信します。テストモードでのチャージ作成が、最も直接的な確認方法です。これが失敗しやすいリクエストだからです。
2. 証明書や接続に関するエラーなく成功すれば、対応は完了です。
3. 同じように失敗し続ける場合は、まだ対応していない方の修正を行ってください。ほとんどの場合はライブラリの更新のみで十分ですが、サーバーによってはルート証明書の更新も必要です。
4. 両方の対応後も失敗が続く場合は、status.omise.coで大規模な障害が発生していないか確認したうえで、正確なエラーメッセージとともにOmiseサポートまでお問い合わせください。

よくある質問

Q: 現在使用しているライブラリのバージョンはどのように確認できますか? A: 依存関係マニフェスト(composer.json、requirements.txt、Gemfile、build.gradle、またはgo.mod/Podfileなど、ご利用のパッケージマネージャーに応じたファイル)で、固定されているOmiseライブラリのバージョンを確認するか、使用している言語のパッケージマネージャーでインストール済みパッケージを直接確認してください。

Q: 表に自分のライブラリが記載されていません。影響を受けますか? A: 現時点でOmiseが把握している限りでは影響はありませんが、今後のリリースでリストが変更される可能性があるため、このページを定期的にご確認ください。

Q: ライブラリを更新しましたが、リクエストが失敗し続けます。次に何を確認すべきですか? A: 次に、サーバーが信頼するルート証明書を更新してください。詳しくはサーバーのルート証明書の更新をご覧ください。サーバー側のトラストストアが古いことが、次に多い原因です。

Q: ホスト型チェックアウトやリダイレクト方式のみを使用しており、ライブラリをインストールしていません。何か対応が必要ですか? A: いいえ。この内容は、Omise提供のライブラリまたはプラグインを使用している統合にのみ関係します。

Q: curl、生のHTTPクライアント、またはこのページに記載のない言語からOmiseのAPIを直接呼び出しています。影響を受けますか? A: ライブラリのバージョンに関する問題はOmise自身のライブラリに固有のものであるため、影響を受けません。一方、サーバーのルート証明書に関する問題はTLS接続そのものに関わるため、引き続き影響を受ける可能性があります。詳しくはOmiseのライブラリを使用していない場合をご覧ください。

Q: アプリは最新のOmise SDKを使用していますが、古いスマートフォンを使うユーザーで依然として証明書エラーが発生します。なぜですか? A: AndroidとiOSはいずれも、アプリのSDKバージョンとは別に、デバイス自体のOSレベルのトラストストアを使って証明書を検証します。非常に古いOSバージョンのデバイスでは、どのSDKバージョンを使用していても、現在のルート証明書を信頼できない場合があります。この場合、アプリ側で解決する方法はなく、該当するユーザーにデバイスのOSを更新してもらうよう案内する以外に対応策はありません。

Q: 更新しない場合、実際にどのような問題が起きますか? A: ライブラリがピン留めしている証明書が無効になった時点で、チャージ作成を含むAPIリクエストが警告なく失敗し始める可能性があります。

関連コンテンツ

• クレジットカード決済
• カード情報の取得
• プラグイン、ライブラリ、SDK
• Omise APIステータス

さらにご質問がありますか?Omiseサポートまでお問い合わせください。