はじめに

IBM Cloud上のAPI Connectを試してみた時の作業ログです。
今回はバックエンドのサービスとしてz/OS Connect,CICSにアクセスする構成で、API Connect - z/OS Connect間をTLS(HTTPS)で接続するための構成を試してみます。

参考情報

z/OS Connect側: How to configure TLS with RACF key rings
API Connect側: TLSプロファイル

ちなみに、証明書の有効期間短縮の動きが出てきているのでニュース記事引用しておきます。
https://www.itmedia.co.jp/enterprise/articles/2006/30/news064.html

Googleは2020年9月1日以降に発行されるTLSサーバ証明書について、有効期間を398日以下に短縮する方針を示した。既に同様の変更を表明しているAppleやMozillaに追随する措置だ。これで証明書の有効期間を13カ月とする措置が主要Webブラウザで出そろうことになり、Webサイト運営者は証明書更新の際に対応が必要になる。
...
　Google傘下のChromiumプロジェクトページに掲載された情報によると、2020年9月1日以降に発行されたTLSサーバ証明書については、有効期間が398日を超える場合は不正な証明書として扱われることになる。こうした証明書を使っているWebサイトはエラー表示が出て、アクセスできなくなる可能性がある。

全体像

z/OS Connect が提供するセキュリティー関連機能は各種ありますが、ここではz/OS Connectをプロバイダーとした時の、API Connect-z/OS Connect間通信にHTTPS(TLS)を使用する構成をやってみます。

今回API Connectとz/OS Connect間はSecure Gatewayを使用して暗号化はされているはずですが、SecureGatewayを使っていない場合や、サーバー認証、クライアント認証が必要なケースも想定して、当構成をやってみます。

HTTPS(TLS)の認証のパターンとしては、(1)サーバー認証のみ、(2)サーバー認証&クライアント認証、2つのケースの構成例を示します。
また、TLSで使用する証明書にてては、RACFを認証局(CA)としてRACFから発行されたものを使用することにします。CA証明書は自己署名証明書を使います。

(1) TLS/サーバー認証のみ

サーバー認証のみの構成の場合に必要な証明書を整理するとこんな感じになります。

【サーバー側(z/OS Connect側)】
CA証明書を使って署名されたサーバー証明書をキーストアに保持している必要があります。

【クライアント側(API Connect側】
サーバーから送られてきたサーバー証明書が信頼されたものかを検証するために、CA証明書をトラストストアに保持している必要があります。

サーバー側(z/OS Connect側)設定

今回z/OS Connect側の証明書関連で作成するオブジェクトのイメージを、ネーミングも含めてもう少し具体化すると以下のようなイメージとなります。

証明書は、z/OS Connectインスタンス実行ユーザー(LIBSRV)に関連付いたKeyRing(Keyring.ZOSCONN)に保持するようにします。
また、CA証明書はクライアント側に転送する必要があるので、SAMにExportします。
以下、具体的な手順を示します。

キーリング作成

01_createKeyRing.sh

#!/bin/sh
tsocmd "RACDCERT ID(LIBSRV) ADDRING(Keyring.ZOSCONN)"
tsocmd "RACDCERT ID(LIBSRV) LISTRING(*)"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./01_createKeyRing.sh
RACDCERT ID(LIBSRV) ADDRING(Keyring.ZOSCONN)
RACDCERT ID(LIBSRV) LISTRING(*)

Digital ring information for user LIBSRV:
...

  Ring:
       >Keyring.ZOSCONN<
  *** No certificates connected ***

CA証明書(自己署名証明書)作成 & キーリングに紐づけ

02_createCAcert.sh

#!/bin/sh

tsocmd "RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('CA for zosConnect') O('IBM') OU('zosConnect') C('US')) SIZE(2048) WITHLABEL('zosConnectCA') NOTAFTER(DATE(2120-12-31))"
tsocmd "RACDCERT ID(LIBSRV) CONNECT(RING(Keyring.ZOSCONN) LABEL('zosConnectCA') CERTAUTH) "

tsocmd "RACDCERT ID(LIBSRV) LISTRING(Keyring.ZOSCONN)"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./02_createCAcert.sh
RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('CA for zosConnect') O('IBM') OU('zosConnect') C('US')) SIZE(2048) WITHLABEL('zosConnectCA') NOTAFTER(DATE(2120-12-31))
IRRD175I The new profile for DIGTCERT will not be in effect until a SETROPTS REFRESH has been issued.
RACDCERT ID(LIBSRV) CONNECT(RING(Keyring.ZOSCONN) LABEL('zosConnectCA') CERTAUTH)
RACDCERT ID(LIBSRV) LISTRING(Keyring.ZOSCONN)

Digital ring information for user LIBSRV:

  Ring:
       >Keyring.ZOSCONN<
  Certificate Label Name             Cert Owner     USAGE      DEFAULT
  --------------------------------   ------------   --------   -------
  zosConnectCA                       CERTAUTH       CERTAUTH     NO

CA証明書で署名されたサーバー証明書を作成 & キーリングに紐づけ

サーバー証明書作成のオプションで、ALTNAMEで、z/OS Connectが稼働するIPアドレスやDNS名を指定しています。
※IPアドレス部分はxx.xx.xx.xxというようにマスキングしています。

サーバー証明書のDOMAIN指定について
TLSのクライアント(ChromeやAPI Connect)側では、アクセスしたURLのドメイン名と、そこから送られてくるサーバー証明書に含まれるドメイン名をチェックしているようです。従ってそこがマッチしていないとTLSの通信がうまくできません。
このドメイン名は、RACFで証明書を作成する際はRACDCERT GENCERTの ALTNAME(DOMAIN(xxx)...) で指定します。
ここで注意が必要なのは、ローカルでブラウザからテストする場合と、API ConnectがSecure Gateway経由でアクセスする場合で、URLのドメイン名が異なることになります。
TLSの証明書では、マルチドメインという指定の仕方があるようで、複数のドメイン名を証明書の中に持たせることができるようです。ただし、RACFのRACDCERT GENCERTコマンドで直接複数のDOMAIN名を指定することはできないようです(ここでは試していませんが、request-data-setを作って生成する、別のユーティリティを使うといった代替策はあるようです)。ここではワイルドカードの指定をしています(ワイルドカードは万能ではなくドット(.)区切りの階層にまたがることはできないので注意が必要です)。

参考:
1枚で複数サイトを常時SSL化！ワイルドカード証明書やマルチドメイン証明書とは？
Multi-Domain Certificate

03_createServerCert2.sh

#!/bin/sh

tsocmd "RACDCERT ID(LIBSRV) GENCERT SUBJECTSDN(CN('myServer2.host.com') O('IBM') OU('zosConnect') C('US')) SIZE(2048) SIGNWITH(CERTAUTH LABEL('zosConnectCA')) WITHLABEL('zosConnectServerCert2') NOTAFTER(DATE(2120-12-31)) ALTNAME(IP(xx.xx.xx.xx) DOMAIN('*.securegateway.appdomain.cloud'))"
tsocmd "RACDCERT ID(LIBSRV) CONNECT(RING(Keyring.ZOSCONN) LABEL('zosConnectServerCert2'))"

tsocmd "RACDCERT ID(LIBSRV) LISTRING(Keyring.ZOSCONN)"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./03_createServerCert2.sh
RACDCERT ID(LIBSRV) GENCERT SUBJECTSDN(CN('myServer2.host.com') O('IBM') OU('zosConnect') C('US')) SIZE(2048) SIGNWITH(CERTAUTH LABEL('zosConnectCA')) WITHLABEL('zosConnectServerCert2') NOTAFTER(DATE(2120-12-31)) ALTNAME(IP(xx.xx.xx.xx) DOMAIN('*.securegateway.appdomain.cloud'))
IRRD175I The new profile for DIGTCERT will not be in effect until a SETROPTS REFRESH has been issued.
RACDCERT ID(LIBSRV) CONNECT(RING(Keyring.ZOSCONN) LABEL('zosConnectServerCert2'))
RACDCERT ID(LIBSRV) LISTRING(Keyring.ZOSCONN)

Digital ring information for user LIBSRV:

  Ring:
       >Keyring.ZOSCONN<
  Certificate Label Name             Cert Owner     USAGE      DEFAULT
  --------------------------------   ------------   --------   -------
  zosConnectCA                       CERTAUTH       CERTAUTH     NO

  zosConnectServerCert2              ID(LIBSRV)     PERSONAL     NO

生成された証明書の中身確認

04_listCert.sh

#!/bin/sh

tsocmd "RACDCERT CERTAUTH LIST(LABEL('zosConnectCA'))"
tsocmd "RACDCERT ID(LIBSRV) LIST(LABEL('zosConnectServerCert2'))"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./04_listCert.sh
RACDCERT CERTAUTH LIST(LABEL('zosConnectCA'))

Digital certificate information for CERTAUTH:

  Label: zosConnectCA
  Certificate ID: 2QiJmZmDhZmjgamWosOWlZWFg6PDwUBA
  Status: TRUST
  Start Date: 2020/06/30 00:00:00
  End Date:   2120/12/31 23:59:59
  Serial Number:
       >00<
  Issuer's Name:
       >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US<
  Subject's Name:
       >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US<
  Signing Algorithm: sha256RSA
  Key Usage: CERTSIGN
  Key Type: RSA
  Key Size: 2048
  Private Key: YES
  Ring Associations:
    Ring Owner: LIBSRV
    Ring:
       >Keyring.ZOSCONN<

RACDCERT ID(LIBSRV) LIST(LABEL('zosConnectServerCert2'))

Digital certificate information for user LIBSRV:

  Label: zosConnectServerCert2
  Certificate ID: 2QbTycLi2eWplqLDlpWVhYOj4oWZpYWZw4WZo/JA
  Status: TRUST
  Start Date: 2020/07/09 00:00:00
  End Date:   2120/12/31 23:59:59
  Serial Number:
       >07<
  Issuer's Name:
       >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US<
  Subject's Name:
       >CN=myServer2.host.com.OU=zosConnect.O=IBM.C=US<
  Subject's AltNames:
    IP: xx.xx.xx.xx
    Domain: *.securegateway.appdomain.cloud
  Signing Algorithm: sha256RSA
  Key Type: RSA
  Key Size: 2048
  Private Key: YES
  Ring Associations:
    Ring Owner: LIBSRV
    Ring:
       >Keyring.ZOSCONN<

ここでは、DOMAIN名として*.securegateway.appdomain.cloudというようにSecure Gatewayのドメイン名に合わせてワイルドカード指定しました。
Secure Gateway経由のアクセスの場合はそのままでよいですし、ローカルのブラウザから確認する時はターゲットのIPアドレスに対して 'eplex1.securegateway.appdomain.cloud'というようなホスト名をhostsファイルに割り当ててそれでアクセスすることを想定しています。

CA証明書のExport

クライアント側に転送するために、SAMとしてExportしておきます(PKCS#12フォーマット)。
※API Connectがサポートしている形式がPKCS#12なので、それに合わせたフォーマットでExportします。

05_exportCAcert.sh

#!/bin/sh

tsocmd "RACDCERT CERTAUTH EXPORT(LABEL('zosConnectCA')) DSN('CICSSHR.CICS004.CERTS.ZCCA.P12') FORMAT(PKCS12DER) PASSWORD('zcon00')"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./05_exportCAcert.sh
RACDCERT CERTAUTH EXPORT(LABEL('zosConnectCA')) DSN('CICSSHR.CICS004.CERTS.ZCCA.P12') FORMAT(PKCS12DER) PASSWORD('zcon00')

z/OS Connect(server.xml)の設定

対象スコープのエレメントで、requireSecure="true"を指定します(ここでは全体に有効にするためにzosconnect_zosConnectManagerで指定)。
keyStoreにて type="JCERACFKS"を指定することで、RACF上のKeyRingを指定することができます。この時passwordは使用されないので任意の文字列を指定しておけばよいです。

server.xml

...
    <httpEndpoint id="defaultHttpEndpoint"
                  host="*"
                  httpPort="30682"
                  httpsPort="30642" />

    <zosconnect_zosConnectManager 
        setUTF8ResponseEncoding="true" 
        requireSecure="true" requireAuth="false"/>

    <ssl id="defaultSSLConfig" 
         keyStoreRef="defaultKeyStore" 
         clientAuthentication="false"/>
    <keyStore id="defaultKeyStore"
      fileBased="false"
      location="safkeyring:///Keyring.ZOSCONN"
      password="password"
      readOnly="true"
      type="JCERACFKS" />
...

※server.xmlを変更したらz/OS Connectを再起動してください。

ブラウザでの簡易確認1(CA証明書なし)

API Connectから接続確認をする前に、ブラウザで簡易的にアクセスして動作確認をしてみます。
hostsにて、eplex1.securegateway.appdomain.cloudを指定して、ターゲットのバックエンドサーバーのIPアドレスにこの名前でアクセスできるようにしておきます。

まず、CA証明書が登録されていない状態で、ブラウザからhttpsでアクセスしてみます。
(画面キャプチャのeplexaはeplex1.securegateway.appdomain.cloudに読み替えてください)

送られてきたサーバー証明書の署名が信頼できるものかどうか判断できないので、上のような警告が出ています。想定通りの挙動です。

ブラウザでの簡易確認2(CA証明書あり)

PCにCA証明書(zosConnectCA.p12)をダウンロードして、それを信頼された証明書として登録します。
MVS Dataset上にExportされたCA証明書(CICSSHR.CICS04.CERTS.ZCCA.P12)をバイナリでFTP転送し、PC上にzosConnectorCA.p12というファイル名で保存します。

Chrome - 設定 - セキュリティから証明書の管理を選択

信頼されたルート証明機関タブでインポート

ダウンロードしたCA証明書のファイル(zosConnectCA.p12)を指定

CA証明書をExportする時に指定したパスワードを入力

完了

はい

※CA証明書を登録したらブラウザを再起動してください(キャッシュクリアだけではなく)。

この後ブラウザからhttpsでアクセスすると、セキュリティの警告や保護されていない通信のアラートが消えました！
(画面キャプチャのeplex1はeplex1.securegateway.appdomain.cloudに読み替えてください)

※参考
アクセスしているホスト名と、サーバー証明書に含まれているドメイン名の指定が合っていないとChromeの場合以下のようなエラーになる。

Secure Gateway 設定

ACL設定追加

HTTPS用のアドレス+ポート追加

ACLFile.txt

acl allow eplex1:30681
acl allow eplex1:30682
acl allow eplex1:30642

Secure Gateway

Secure Gatewayの設定も、API Connect - z/OS Connect間接続構成に合わせて設定する必要があるようです。

宛先とプロトコル、TLS option辺りを以下のように変更。

ブラウザからの簡易確認(Secure Gateway経由)

Chromeのプラグイン"Talend API Tester"から確認。

これで、Secure Gateway経由でのアクセスも確認できました。

クライアント側(API Connect側)設定

TLSプロファイル作成

API Connect側には、CA証明書をトラストストアに保持させる必要があります。
TLSの証明書周りの管理には、まずTLSプロファイルというものを作る必要があるようです。
また、API Connectでサポートされるファイル形式としては、トラストストアはPKCS#12 or PEM, キーストアはPKDS#12のみのようです。

トップの「>>」のメニューから、管理を選択します。

セキュリティー - TLSプロファイル - 追加

適当な名前をつけて作成したら、それを編集画面を開きます。
「トラストストア内の指定CAに対して証明書を要求して検証」を有効化して、トラストストア以下の証明書のアップロードをクリックします。

ダウンロードしたCA証明書(zosConnectCA.p12)を選択し、Export時に指定したパスワードを指定し、アップロード。

保存

アセンブル

呼び出し(Invoke)のURLでhttps://を指定し、TLSプロファイルに上で作成したプロファイルを指定します。

テスト

アセンブルの画面からテストして、リクエストがきちんと通ることが確認できました。

(2) TLS/サーバー認証&クライアント認証

サーバー認証&クライアント認証の構成の場合に必要な証明書を整理するとこんな感じになります。

【サーバー側(z/OS Connect側)】
CA証明書1を使って署名されたサーバー証明書をキーストアに保持している必要があります。
クライアントから送られてきたサーバー証明書が信頼されたものかを検証するために、CA証明書2をトラストストアに保持している必要があります。

【クライアント側(API Connect側】
CA証明書2を使って署名されたクライアント証明書をキーストアに保持している必要があります。
サーバーから送られてきたサーバー証明書が信頼されたものかを検証するために、CA証明書をトラストストアに保持している必要があります。

サーバー証明書のみの構成の際に必要なセットを両側でそれぞれ持つイメージです。
ここで、サーバー証明書とクライアント証明書を発行するCAが別の可能性もあるので区別してCA証明書1,2と記載していますが、ここでの手順ではどちらもRACFをCAとして使用することにします(CA証明書1=CA証明書2)。
ここでは、上のサーバー認証の構成は済んでいる前提で、それにクライアント認証の構成を追加していくことにします。

サーバー側(z/OS Connect側)設定

クライアント証明書を検証するために、クライアント証明書に署名しているCA証明書を取り込む必要がありますが、今回はどちらもRACFをCAとして使用する想定なので、その操作は不要です(既にKeyRingにCA証明書が存在)。
あとはこのCA証明書をトラストストアとしても認識させればよいことになります。

z/OS Connect(server.xml)の設定

clientAuthentication="true"に設定し、trustStoreの定義を追加します。

CA証明書で署名されたクライアント証明書を作成 & Export

クライアント証明書もRACFで作成しますので、これはz/OS側で準備してクライアント側に転送することになります。

まず、先に作成したCA証明書で署名したクライアント証明書を作成します。

06_createClientCert.sh

#!/bin/sh

tsocmd "RACDCERT ID(LIBSRV) GENCERT SUBJECTSDN(CN('myClient.host.com') O('IBM') OU('zosConnect') C('US')) SIZE(2048) SIGNWITH(CERTAUTH LABEL('zosConnectCA')) WITHLABEL('zosConnectClientCert') NOTAFTER(DATE(2120-12-31))"

tsocmd "RACDCERT ID(LIBSRV) LIST(LABEL('zosConnectClientCert'))"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./06_createClientCert.sh
RACDCERT ID(LIBSRV) GENCERT SUBJECTSDN(CN('myClient.host.com') O('IBM') OU('zosConnect') C('US')) SIZE(2048) SIGNWITH(CERTAUTH LABEL('zosConnectCA')) WITHLABEL('zosConnectClientCert') NOTAFTER(DATE(2120-12-31))
IRRD175I The new profile for DIGTCERT will not be in effect until a SETROPTS REFRESH has been issued.
RACDCERT ID(LIBSRV) LIST(LABEL('zosConnectClientCert'))

Digital certificate information for user LIBSRV:

  Label: zosConnectClientCert
  Certificate ID: 2QbTycLi2eWplqLDlpWVhYOjw5OJhZWjw4WZo0BA
  Status: TRUST
  Start Date: 2020/07/09 00:00:00
  End Date:   2120/12/31 23:59:59
  Serial Number:
       >03<
  Issuer's Name:
       >CN=CA for zosConnect.OU=zosConnect.O=IBM.C=US<
  Subject's Name:
       >CN=myClient.host.com.OU=zosConnect.O=IBM.C=US<
  Signing Algorithm: sha256RSA
  Key Type: RSA
  Key Size: 2048
  Private Key: YES
  Ring Associations:
  *** No rings associated ***

これをPKCS#12フォーマットでExportします。

07_exportClientcert.sh

#!/bin/sh

tsocmd "RACDCERT ID(LIBSRV) EXPORT(LABEL('zosConnectClientCert')) DSN('CICSSHR.CICS004.CERTS.ZCCLI.P12') FORMAT(PKCS12DER) PASSWORD('zcon00')"

実行例

[CICS004@EPLEX1:/u/cics004/RACF/APIC] ./07_exportClientcert.sh
RACDCERT ID(LIBSRV) EXPORT(LABEL('zosConnectClientCert')) DSN('CICSSHR.CICS004.CERTS.ZCCLI.P12') FORMAT(PKCS12DER) PASSWORD('zcon00')

CICSSHR.CICS004.CERTS.ZCCLI.P12にExportされるので、これをPCにzosConnectClientCert.p12というファイル名でバイナリで転送しておきます。

ブラウザでの簡易確認

クライアント証明書を設定していない状態でChromeからz/OS Connectにアクセスしてみると、以下のようにエラーではじかれるようになりました。
(画面キャプチャのeplex1はeplex1.securegateway.appdomain.cloudに読み替えてください)

Chrome - 設定 - セキュリティから証明書の管理を選択

インポート

入手したクライアント証明書を指定

Export時に指定したパスワードを入力

完了

これで、Chromeを立ち上げなおして、再度z/OS Connectにアクセスしてみます。
すると、以下のように証明書選択の画面が表示されるので、取り込んだクライアント証明書を選択してOK

うまくリクエストが流れるのが確認できました！

Secure Gateway設定

Secure Gatewayは、サーバー認証のみのケースと特に変更はありません。

クライアント側(API Connect側)設定

トップの「>>」のメニューから、管理を選択し、セキュリティー - TLSプロファイルから、先に作成していたプロファイルを編集します。
証明書のアップロードを選択して、先にダウンロードしていたクライアント証明書(zosConnectClientCert.p12)をアップロードします(Export時に指定したパスワードが必要)。

テスト

探索の画面からテストして、リクエストがきちんと通ることが確認できました。

IBM API Connect 関連メモ - (6)API Connect-z/OS Connect間TLS接続

はじめに

関連記事

参考情報

全体像

(1) TLS/サーバー認証のみ

サーバー側(z/OS Connect側)設定

キーリング作成

CA証明書(自己署名証明書)作成 & キーリングに紐づけ

CA証明書で署名されたサーバー証明書を作成 & キーリングに紐づけ

CA証明書のExport

z/OS Connect(server.xml)の設定

ブラウザでの簡易確認1(CA証明書なし)

ブラウザでの簡易確認2(CA証明書あり)

Secure Gateway 設定

ACL設定追加

Secure Gateway

ブラウザからの簡易確認(Secure Gateway経由)

クライアント側(API Connect側)設定

TLSプロファイル作成

アセンブル

テスト

(2) TLS/サーバー認証&クライアント認証

サーバー側(z/OS Connect側)設定

z/OS Connect(server.xml)の設定

CA証明書で署名されたクライアント証明書を作成 & Export

ブラウザでの簡易確認

Secure Gateway設定

クライアント側(API Connect側)設定

テスト