インタフェースObjectInputFilter

関数型インタフェース:

これは関数型インタフェースなので、ラ� ダ式またはメソッド参照の代入先として使用できます。

@FunctionalInterface public interface ObjectInputFilter

直列化復元中にクラス、配列の長さおよびグラフ・メトリックをフィルタします。

警告: 信� �できないデータの直列化復元は、本質的に危険であり、回避する必要があります。 「Java SEに対するセキュア・コーディングのガイドライン」の"直列化および直列化復元"セクションに従って、信� �できないデータを慎重に検証する必要があります。 「直列化フィルタリング」では、シリアル・フィルタの使いやすさに関するベスト・プラクティスについて説明します。

アプリケーション開発者は、直列化復元の脆弱性から保護するために、各コンポーネントまたはライブラリで直列化復元できるオブジェクトを明確に記述する必要があります。 コンテキストおよびユースケースごとに、開発者は適切なフィルタを作成して適用する必要があります。

直列化復元フィルタリング・ファクトリおよびフィルタ

直列化復元フィルタリングの部分は、フィルタ、コンポジット・フィルタおよびフィルタ・ファクトリです。 各フィルタでは、クラスとリソース制限のチェックが実行され、ステータスが否認済、許可済または未決定として決定されます。 フィルタは、他のフィルタから構成でき、結果をマージまたは結合できます。 フィルタ・ファクトリは、各ObjectInputStreamのフィルタの確立および更新を担当します。

単純なケースの� �合、フィルタ・ファクトリを設定せずに、アプリケーション全体に対して静的なJVM全体のフィルタを設定できます。 JVM全体のフィルタは、コマンドラインでシステ� ・プロパティを使用するか、Config.setSerialFilterを呼び出して設定できます。 カスタ� ・フィルタ・ファクトリを指定する必要はありません。組込みフィルタ・ファクトリにデフォルト設定されます。 組込みフィルタ・ファクトリは、ObjectInputStreamごとに「静的JVM全体のフィルタ」を提供します。

たとえば、サンプル・クラスを許可し、java.baseモジュールのクラスを許可し、他のすべてのクラスを拒否するフィルタを設定できます : コマンドライン・プロパティとして:

    % java -Djdk.serialFilter="example.*;java.base/*;!*" ...

またはプログラ� 的に:

    var filter = ObjectInputFilter.Config.createFilter("example.*;java.base/*;!*")
    ObjectInputFilter.Config.setSerialFilter(filter);

複数の実行コンテキストを持つアプリケーションでは、アプリケーションごとにカスタ� ・フィルタを提供することで、個々のコンテキストを保護するための「フィルタ・ファクトリ」を提供できます。 ストリー� が作成されると、フィルタ・ファクトリがコールされ、現在のスレッド・ローカル状態、コール元の階層、ライブラリ、モジュールおよびクラス・ローダーなど、使用可能な情� �から実行コンテキストが識別されます。 その時点で、フィルタを作成または選択するためのフィルタ・ファクトリ・ポリシーは、コンテキストに基づいて特定のフィルタまたはフィルタの構成を選択できます。 JVM全体の直列化復元フィルタ・ファクトリにより、コンテキスト固有の直列化復元フィルタをすべてのObjectInputStreamに設定でき、ストリー� から読み取られるすべてのオブジェクトをチェックできます。

フィルタ・ファクトリの起動

JVM全体のフィルタ・ファクトリは、各ObjectInputStreamが「構成され」、「ストリー� 固有のフィルタが設定された」の� �合に呼び出される関数です。 パラメータは現在のフィルタとリクエストされたフィルタで、ストリー� に使用されるフィルタを返します。 「ObjectInputStreamコンストラクタ」から起動すると、最初のパラメータはnullで、2番目のパラメータは「静的JVM全体のフィルタ」です。 ObjectInputStream.setObjectInputFilterから呼び出されると、最初のパラメータはストリー� (コンストラクタで設定されたもの)で現在設定されているフィルタで、2番目のパラメータはObjectInputStream.setObjectInputFilterに指定されたフィルタです。 現在および新しいフィルタはそれぞれnullで、ファクトリはnullを返します。 フィルタ・ファクトリの実装では、アプリケーション・スレッド・コンテキストまたはそのコール・スタックから抽出されたコンテキスト情� �を自由に使用して、新しいフィルタを作成して組み合せることもできます。 2つのパラメータのみを使用するわけではありません。

アクティブな直列化復元フィルタ・ファクトリは、次のいずれかです:

• アプリケーション固有のフィルタ・ファクトリは、ObjectInputFilter.Config.setSerialFilterFactory(BinaryOperator)、システ� ・プロパティjdk.serialFilterFactoryまたはセキュリティ・プロパティjdk.serialFilterFactoryによって設定されます。
• それ以外の� �合、組み込みの直列化復元フィルタ・ファクトリは、「ObjectInputStreamコンストラクタ」から起動されたときに「静的JVM全体のフィルタ」を提供し、ObjectInputStream.setObjectInputFilter(ObjectInputFilter)から起動されたときに静的フィルタを置き換えます。 getSerialFilterFactoryを参照してく� さい。

フィルタ

フィルタは、「パターン文字列」から、または「クラスの述語」からallowまたはrejectクラスに基づいて作成できます。

フィルタcheckInput(FilterInfo)メソッドは、「オブジェクトの読取り」中にゼロ回以上呼び出されます。 メソッドは、クラス、各配列の長さ、ストリー� から読み取られるオブジェクト数、グラフの深さおよびストリー� から読み取られたバイトの合計数を検証するためにコールされます。

複合フィルタは、他のフィルタの結果を結合またはチェックします。 merge(filter, anotherFilter)フィルタは、2つのフィルタのステータス値を組み合せます。 rejectUndecidedClass(filter)は、ステータスがUNDECIDEDの� �合に、クラスのフィルタの結果をチェックします。 多くの� �合、フィルタによるALLOWEDではないクラスはREJECTEDにする必要があります。

直列化復元フィルタにより、引数を許可するか拒否するかを決定し、適切なステータスを返します: ALLOWEDまたはREJECTED。 フィルタがステータスを判別できない� �合は、UNDECIDEDを返します。 フィルタは、特定のユース・ケースおよび予想されるタイプ用に設計する必要があります。 特定の用途向けに設計されたフィルタは、フィルタの範囲外のクラスに渡される� �合があります。 フィルタの目的がクラスを拒否することである� �合は、他の候補クラスでUNDECIDEDを照合し、レポートする候補クラスを拒否できます。 フィルタは、クラスがnull、arrayLengthが -1、深さ、参照数およびストリー� ・サイズと等しい状態でコールされ、1つまたは一部の値のみを反� するステータスを返します。 これにより、フィルタをレポートしている選択肢に特定でき、許可または否認済ステータスを強制せずに他のフィルタを使用できます。

フィルタ・モデルの例

単純なアプリケーションの� �合、許可または拒否されたクラスをリストする単一の事前定義済フィルタで、予期しないクラスの直列化復元のリスクを管理できる可能性があります。

複数のモジュールまたはライブラリから構成されるアプリケーションでは、アプリケーションの構� を使用して、アプリケーションの各コンテキストで許可または拒否するクラスを各ObjectInputStreamで識別できます。 各ストリー� の構成時に直列化復元フィルタ・ファクトリが起動され、スレッドまたはプログラ� を確認して適用するコンテキスト固有のフィルタを決定できます。 考えられる例:

• スレッド・ローカル状態は、ストリー� 固有のフィルタで適用または構成するフィルタを保持できます。 フィルタは、アプリケーションまたはライブラリによって管理される仮想フィルタのスタックからプッシュおよびポップアップできます。
• フィルタ・ファクトリは、直列化復元メソッドの呼出し元を識別し、モジュールまたはライブラリ・コンテキストを使用してフィルタを選択するか、適切なコンテキスト固有のフィルタを構成できます。 メカニズ� は、直列化されたクラスに対する制限付きアクセスまたは無制限のアクセスを持つ呼び出し元を識別し、それに応じてフィルタを選択できます。

スレッドのすべての直列化復元をフィルタする例

このクラスは、アプリケーション提供のフィルタ・ファクトリがフィルタを組み合せて、スレッドで実行されるすべての直列化復元操作をチェックする方法を示します。 スレッド固有のフィルタを保持するスレッド・ローカル変数を定義し、静的JVM全体のフィルタおよびストリー� 固有のフィルタでフィルタを構成するフィルタ・ファクトリを構成し、これら2つのフィルタで処理されないクラスを拒否します。 ストリー� 固有のフィルタが設定され、クラスを受け入れたり拒否したりしない� �合、JVM全体のフィルタとスレッド・フィルタを組み合わせて適用されます。 doWithSerialFilterメソッドは、スレッド固有のフィルタの設定を行い、アプリケーションRunnableを起動します。

public static final class FilterInThread implements BinaryOperator<ObjectInputFilter> {

    private final ThreadLocal<ObjectInputFilter> filterThreadLocal = new ThreadLocal<>();

    // Construct a FilterInThread deserialization filter factory.
    public FilterInThread() {}

    // Returns a composite filter of the static JVM-wide filter, a thread-specific filter,
    // and the stream-specific filter.
    public ObjectInputFilter apply(ObjectInputFilter curr, ObjectInputFilter next) {
        if (curr == null) {
            // Called from the OIS constructor or perhaps OIS.setObjectInputFilter with no current filter
            var filter = filterThreadLocal.get();
            if (filter != null) {
                // Merge to invoke the thread local filter and then the JVM-wide filter (if any)
                filter = ObjectInputFilter.merge(filter, next);
                return ObjectInputFilter.rejectUndecidedClass(filter);
            }
            return (next == null) ? null : ObjectInputFilter.rejectUndecidedClass(next);
        } else {
            // Called from OIS.setObjectInputFilter with a current filter and a stream-specific filter.
            // The curr filter already incorporates the thread filter and static JVM-wide filter
            // and rejection of undecided classes
            // If there is a stream-specific filter merge to invoke it and then the current filter.
            if (next != null) {
                return ObjectInputFilter.merge(next, curr);
            }
            return curr;
        }
    }

    // Applies the filter to the thread and invokes the runnable.
    public void doWithSerialFilter(ObjectInputFilter filter, Runnable runnable) {
        var prevFilter = filterThreadLocal.get();
        try {
            filterThreadLocal.set(filter);
            runnable.run();
        } finally {
            filterThreadLocal.set(prevFilter);
        }
    }
}

フィルタ・ファクトリの使用

FilterInThreadユーティリティを使用するには、インスタンスを作成し、JVM全体のフィルタ・ファクトリとして構成します。 doWithSerialFilterメソッドは、サンプル・アプリケーションとコア・クラスを許可するフィルタで呼び出されます:

       // Create a FilterInThread filter factory and set
       var filterInThread = new FilterInThread();
       ObjectInputFilter.Config.setSerialFilterFactory(filterInThread);

       // Create a filter to allow example.* classes and reject all others
       var filter = ObjectInputFilter.Config.createFilter("example.*;java.base/*;!*");
       filterInThread.doWithSerialFilter(filter, () -> {
             byte[] bytes = ...;
             var o = deserializeObject(bytes);
       });

特に記載がないかぎり、このインタフェースおよびそのネストされたクラスのメソッドにnull引数を渡すと、NullPointerExceptionがスローされます。

導入されたバージョン:

9

関連� �目:

• ObjectInputStream.setObjectInputFilter(ObjectInputFilter)

ネストされたクラスのサマリー

ネストされたクラス

修飾子と型	インタフェース	説明
static final class	ObjectInputFilter.Config	JVM全体の直列化復元フィルタ・ファクトリを設定および取得するユーティリティ・クラス、静的なJVM全体のフィルタ、またはパターン文字列からフィルタを作成するユーティリティ・クラス。
static interface	ObjectInputFilter.FilterInfo	FilterInfoは、直列化復元されている現在のオブジェクトに関する情� �とObjectInputStreamのステータスへのアクセスを提供します。
static enum	ObjectInputFilter.Status	クラスのチェックのステータス、配列の長さ、参照数、深さおよびストリー� ・サイズ。

メソッドのサマリー

修飾子と型	メソッド	説明
static ObjectInputFilter	allowFilter(Predicate<Class<?>> predicate, ObjectInputFilter.Status otherStatus)	クラスの述語がtrueの� �合、Status.ALLOWEDを返すフィルタを返します。
ObjectInputFilter.Status	checkInput(ObjectInputFilter.FilterInfo filterInfo)	クラス、配列の長さ、オブジェクト参照の数、深さ、ストリー� ・サイズ、およびその他の使用可能なフィルタリング情� �を確認します。
static ObjectInputFilter	merge(ObjectInputFilter filter, ObjectInputFilter anotherFilter)	フィルタと別のフィルタのステータスをマージするフィルタを返します。
static ObjectInputFilter	rejectFilter(Predicate<Class<?>> predicate, ObjectInputFilter.Status otherStatus)	クラスの述語がtrueの� �合、Status.REJECTEDを返すフィルタを返します。
static ObjectInputFilter	rejectUndecidedClass(ObjectInputFilter filter)	特定のフィルタを起動し、クラスについてUNDECIDEDをREJECTEDにマップするフィルタを特殊なケースとともに返し、それ以外の� �合はステータスを返します。

メソッドの詳細

checkInput

ObjectInputFilter.Status checkInput(ObjectInputFilter.FilterInfo filterInfo)

クラス、配列の長さ、オブジェクト参照の数、深さ、ストリー� ・サイズ、およびその他の使用可能なフィルタリング情� �を確認します。 このメソッドの実装では、直列化復元中に作成されるオブジェクト・グラフの内容を確認します。 フィルタはStatus.ALLOWED、Status.REJECTED、またはStatus.UNDECIDEDを返します。

filterInfo.serialClass()がnon-nullの� �合、チェックするクラスがあります。 serialClass()がnullの� �合、クラスがなく、この情� �には、直列化復元されるグラフの深さ、参照の数およびストリー� 読取りサイズに関連するメトリックのみが含まれます。

APIのノート:

checkInputを実装する各フィルタは、ObjectInputFilter.Statusの値のいずれかを返します。 nullを返すと、NullPointerExceptionやその他の予期しない動作が発生する可能性があります。

パラメータ:

filterInfo - 直列化復元される現在のオブジェクト(存在する� �合)およびObjectInputStreamのステータスに関する情� �を提供

戻り値:

受け入れられた� �合はStatus.ALLOWED、拒否された� �合はStatus.REJECTED、未決定の� �合はStatus.UNDECIDED。

allowFilter

static ObjectInputFilter allowFilter(Predicate<Class<?>> predicate, ObjectInputFilter.Status otherStatus)

クラスの述語がtrueの� �合、Status.ALLOWEDを返すフィルタを返します。 フィルタは、non-nullクラスの述語に基づいてALLOWEDまたはotherStatusを返し、クラスがnullの� �合はUNDECIDEDを返します。

フィルタcheckInput(info)メソッドが起動されると、述語がinfo.serialClass()に適用されます。戻りステータスは次のとおりです:

• UNDECIDED (serialClassがnullの� �合)
• ALLOWED(クラスの述語がtrueを返す� �合)
• それ以外の� �合は、otherStatusを返します。

たとえば、プラットフォー� またはブートストラップ・クラス・ローダーからロードされたクラスを許可するフィルタを作成します。

    ObjectInputFilter f
        = allowFilter(cl -> cl.getClassLoader() == ClassLoader.getPlatformClassLoader() ||
                      cl.getClassLoader() == null, Status.UNDECIDED);

パラメータ:

predicate - nullでないクラスをテストする条件

otherStatus - 述語がfalseの� �合に使用するステータス

戻り値:

クラスの述語がtrueの� �合、ALLOWEDを返すフィルタ

導入されたバージョン:

17

rejectFilter

static ObjectInputFilter rejectFilter(Predicate<Class<?>> predicate, ObjectInputFilter.Status otherStatus)

クラスの述語がtrueの� �合、Status.REJECTEDを返すフィルタを返します。 フィルタは、non-nullクラスの述語に基づいてREJECTEDまたはotherStatusを返し、クラスがnullの� �合はUNDECIDEDを返します。 フィルタcheckInput(info)メソッドが起動されると、述語がserialClass()に適用されます。戻りステータスは次のとおりです:

• UNDECIDED (serialClassがnullの� �合)
• REJECTED(クラスの述語がtrueを返す� �合)
• それ以外の� �合は、otherStatusを返します。

たとえば、アプリケーション・クラス・ローダーからロードしたクラスを拒否するフィルタを作成します。

    ObjectInputFilter f = rejectFilter(cl ->
         cl.getClassLoader() == ClassLoader.ClassLoader.getSystemClassLoader(), Status.UNDECIDED);

パラメータ:

predicate - nullでないクラスをテストする条件

otherStatus - 述語がfalseの� �合に使用するステータス

戻り値:

クラスの述語がtrueの� �合、REJECTEDを返すフィルタを返します

導入されたバージョン:

17

merge

static ObjectInputFilter merge(ObjectInputFilter filter, ObjectInputFilter anotherFilter)

フィルタと別のフィルタのステータスをマージするフィルタを返します。 anotherフィルタがnullの� �合、filterが返されます。 それ以外の� �合は、non-nullフィルタのペアをマージするためにfilterが返されます。 返されるフィルタは、次のようにcheckInput(FilterInfo)メソッドを実装します:

• FilterInfoでfilterを呼び出してstatusを取得
• statusがREJECTEDの� �合、REJECTEDを返します
• anotherFilterを呼び出してotherStatusを取得
• otherStatusがREJECTEDの� �合、REJECTEDを返します
• statusまたはotherStatusのいずれかがALLOWEDの� �合は、ALLOWEDを返します。
• それ以外の� �合は、UNDECIDEDを返します

パラメータ:

filter - フィルタ

anotherFilter - フィルタとマージするフィルタ(null)

戻り値:

フィルタと別のフィルタのステータスをマージするObjectInputFilter

導入されたバージョン:

17

rejectUndecidedClass

static ObjectInputFilter rejectUndecidedClass(ObjectInputFilter filter)

特定のフィルタを起動し、クラスについてUNDECIDEDをREJECTEDにマップするフィルタを特殊なケースとともに返し、それ以外の� �合はステータスを返します。 クラスがプリミティブ・クラスではなく配列の� �合、返されるステータスはREJECTEDです。 クラスがプリミティブ・クラスまたは配列クラスの追� チェックが実行される� �合は、次のリストを参照してく� さい。

フィルタがUNDECIDEDを返す� �合、オブジェクトの直列化復元はクラスを受け入れます。 許可または拒否されていないクラスに対して決定されていない結果を拒否するフィルタを追� すると、クラスがフィルタを通過しないようにすることができます。

実装要件:

返されるフィルタは、次のようにcheckInput(FilterInfo)メソッドを実装します:

• FilterInfoでフィルタを起動して、そのstatusを取得
• ステータスがREJECTEDまたはALLOWEDの� �合、statusを返します
• filterInfo.getSerialClass() serialClassがnullの� �合、UNDECIDEDを返します
• クラスが「配列」でない� �合、REJECTEDを返します
• serialClassが「配列」の� �合、ベース・コンポーネント・タイプを決定
• ベース・コンポーネント・タイプが「プリミティブ・クラス」の� �合は、UNDECIDEDを返します
• base component typeでフィルタを起動して、そのcomponent statusを取得
• コンポーネント・ステータスがALLOWEDの� �合は、ALLOWEDを返します
• それ以外の� �合は、REJECTEDを返します。

パラメータ:

filter - フィルタ

戻り値:

クラスのObjectInputFilter.Status.UNDECIDEDステータスをObjectInputFilter.Status.REJECTEDにマップするObjectInputFilterで、それ以外の� �合はフィルタ・ステータスを返します

導入されたバージョン:

17