KBS Cloud for GCP Windows をリリースしました

バージョン18 でREST APIに必要な署名(signature)が標準関数でほぼ網羅

FileMaker はバージョン16で curl による外部接続が可能になりました。
REST APIを提供するほとんどのサービスとFileMakerをつなぐことができるようになりました。
Amazon API や Google Cloud API など高度なAPIを利用するときは必要なリクエストのときに 署名(signature)を付与する必要があります。

バージョン18で CryptGenerateSignature 関数が新たに追加されました。
これで HMAC、RSA 署名の作成が標準の関数でできるようになり、
ECDSA 署名はまだREST APIでほとんど使われていないので、
現時点のREST APIに必要な署名(signature)が標準関数でほぼ網羅したと言っても過言ではありません。

今回は署名の基本知識とFileMakerの標準関数をどのように使うかを解説したいと思います。

共通鍵方式(HMAC)と公開鍵方式(RSA)

署名は鍵の持ち方で大きくわけて2種類あります。
鍵といってもファイルの拡張子はさまざまですが実際の中身はテキストです。

「共通鍵方式(HMAC)」は署名をする側(リクエストする側)と、
署名が正しいか検証する側(リクエストを受けてレスポンスを返すAPIサービス側)で、
同じ鍵を使います。

「公開鍵方式(RSA)」は署名をする側には「秘密鍵(Private Key)」、
署名が正しいか検証する側には「公開鍵(Publish Key)」をもちます。
秘密鍵は施錠だけしかできない鍵、
公開鍵はその秘密鍵でかけた鍵だけを解錠できる鍵の一対のものになります。

そして物理的な鍵にもいろんな種類があるとおり、
どちらの鍵についても鍵の複雑さを選ぶことができます。
SHA-1 hashやSHA-256 hashなどが一般的ですが、
SHA-1 hashはもう解除方法が見つかっているので最近はSHA-256 hashが使われているケースが多いです。

いずれにしてもREST API提供側になるのであればきちんと理解して適材適所で使い分ける必要があると思いますが、
REST APIサービスを利用する側からすれば、APIの仕様で決められた方式に沿ってそれを利用すればよいだけです。

深く考えず次にすすみましょう。

HS256 と RS256 をFileMakerで作成する

これまでの解説の通り署名には鍵の方式と複雑度があります。
一般的によく使われているが HS256 と RS256 です。

HS256 は HMAC using SHA-256 hash のこと、RS256 は RSA using SHA-256 hash のことです。
FileMakerではHS*** と表記される HMAC 署名はバージョン16で追加された CryptAuthCode 関数で作成することができ、
RS*** と表記される RSA 署名はバージョン18で追加された CryptGenerateSignature 関数で作成することができます。

CryptAuthCode (データ ; アルゴリズム ; キー) 関数

1つ目の引数は署名すべきデータです。
2つ目の引数はヘルプに書いてある8つのいずれかのhashを設定します。HS256であれば”SHA256″を指定します。
3つ目の引数は共通鍵になります。各REST APIサービスからダウンロードしたkeyファイルをFileMakerのフィールドに格納して指定してもいいですし、keyファイルの中身の文字列をこの第3引数に文字列でそのまま設定しても構いません。
戻り値はオブジェクトになります。

CryptGenerateSignature (データ ; アルゴリズム ; プライベート RSA キー ; キーパスワード) 関数

1つ目の引数は署名すべきデータです。
2つ目の引数はヘルプに書いてある8つのいずれかのhashを設定します。RS256であれば”SHA256″を指定します。
3つ目の引数は秘密鍵になります。各REST APIサービスからダウンロードしたkeyファイルをFileMakerのフィールドに格納して指定してもいいですし、keyファイルの中身の文字列をこの第3引数に文字列でそのまま設定しても構いません。
4つ目の引数は秘密鍵にパスワードがかかっている時にそのパスワードを指定します。パスワードが特になければ “” を指定します。
戻り値はオブジェクトになります。

Base64Encode と URL-Safe の置換

いろんなAPIでは完成した署名をBase64エンコードしてAPIのリクエストに含めるよう仕様になっているのがほとんどだと思います。
FileMaker では Base64Encode 関数か Base64EncodeRFC 関数が使用できます。
基本的に同じなのですが、Base64EncodeRFC 関数は改行の書式が指定できるようになっています。
ちなみに Base64Encode(データ) は Base64EncodeRFC(2045;データ)と同じです。
この署名をリクエストに含める場合は余計な改行は不要になるので、Base64EncodeRFC ( “4648” ; データ ) を使用すると良いでしょう。

次にBase64エンコードされた文字には/や=などリクエストパラメータに含めると間違った区切り文字として解釈される恐れがあるため、
「 URL-Safe な Base64エンコード(Base64urlエンコード)」をするような仕様になっているのがほとんどだと思います。
+ を – に、 / を _ に置換、 = は取り除く必要があります。
結局「RS256で署名し URL-Safe な Base64エンコード」する式は次のようになります。

Substitute (
    Base64EncodeRFC (
        "4648"
      ; CryptGenerateSignature ( $データ ; "SHA256" ; $privateKey ; "" )
    )
    ; [ "+" ; "-" ] ; [ "/" ; "_" ] ; [ "=" ; "" ]
)

鍵の管理に注意

REST APIサービスから受け取った共通鍵方式(HMAC)の共通鍵(キー)や秘密鍵(Private Key)は、
外部にもれないようFileMaker内に保存するときには注意しましょう。
一番手軽なのはレコードやフィールドに保存せず、
スクリプト内に直接keyのテキストを$変数に入れておくと管理がしやすいです。

さいごに

REST APIでの認証では一般的なOAuth2.0では署名は不要ですが、
OAuth1.0やJWT ( JSON Web Token )では必須になります。
JWTの方が使い勝手がよかったり、JWTによる認証しか許されないREST APIもありますが、
バージョン18を使えばどのタイプにも対応できます。

楽しい API ライフを!

 

 

 

【 開発者募集中 】
弊社では FileMaker を使った高度な技術力で、モバイルデバイスのビジネス利用を楽しく発展させていく仲間を随時募集しています。詳しくは採用ページをご覧ください。