SunPKCS11プロバイダは、モジュールjdk.crypto.cryptokiにあります。このプロバイダを使用するには、まずそれを静的にまたはプログラムでインストールする必要があります。

このプロバイダを静的にインストールするには、Javaセキュリティのプロパティ・ファイル(java-home/conf/security/java.security)にプロバイダを追加します。

たとえば次は、SunPKCS11プロバイダを構成ファイル/opt/bar/cfg/pkcs11.cfgとともにインストールするjava.securityファイルの一部です。

# configuration for security providers 1-12 omitted
security.provider.13=SunPKCS11 /opt/bar/cfg/pkcs11.cfg

このプロバイダを動的にインストールするには、適切な構成ファイル名を使用してプロバイダのインスタンスを作成し、インストールします。次に例を示します。

    String configName = "/opt/bar/cfg/pkcs11.cfg";
    Provider p = Security.getProvider("SunPKCS11");
    p = p.configure(configName);
    Security.addProvider(p);

    p = p.configure(configName);
    Security.addProvider(p);

    p.configure(configName);
    Security.addProvider(p);

PKCS#11実装あたり複数のスロットを使用する場合や、複数のPKCS#11実装を使用する場合は、適切な構成ファイルでそれぞれのインストールを繰り返すだけです。これにより、それぞれのPKCS#11実装の各スロットに対してSunPKCS11プロバイダのインスタンスが1つ作成されることになります。

構成ファイルはテキスト・ファイルであり、これには次の形式でエントリが含まれています。

attributeとvalueの有効な値については、この項内の表で説明しています。

次に、構成ファイルの例を示します。

name = FooAccelerator
library = /opt/foo/lib/libpkcs11.so

コメントは、# (シャープ)記号で始まる行に記述します。

enabledMechanisms = {
  CKM_RSA_PKCS
  CKM_RSA_PKCS_KEY_PAIR_GEN
}

属性の構成

attributesオプションは、PKCS#11キー・オブジェクトの作成時に設定される追加のPKCS#11属性を指定するために使用できます。デフォルトでSun PKCS#11プロバイダでは、オブジェクトの作成時に必須のPKCS#11属性を指定するだけです。たとえばRSA公開キーでは、キー・タイプおよびアルゴリズム(CKA_CLASSおよびCKA_KEY_TYPE)と、RSA公開キーのキーの値(CKA_MODULUSおよびCKA_PUBLIC_EXPONENT)を指定します。使用しているPKCS#11ライブラリでは、実装固有のデフォルト値をRSA公開キーのその他の属性に割り当てます。たとえば、メッセージの暗号化と検証にキーを使用できます(CKA_ENCRYPTおよびCKA_VERIFY = true)。

attributesオプションは、PKCS#11実装で割り当てたデフォルト値を使用しない場合や、PKCS#11実装でデフォルト値をサポートしないために、明示的に値を指定する必要がある場合に使用します。使用しているPKCS#11実装でサポートしない属性や、該当するキー・タイプで無効な属性を指定すると、実行時に操作が失敗する原因となります。

このオプションはゼロ回以上指定できます。これらのオプションは、構成ファイルで指定されている順序で処理されます。attributesオプションは次の書式です。

attributes(operation, keytype, keyalgorithm) = {
  name1 = value1
  [...]
}

operationの有効な値は次のとおりです。

• generate。KeyPairGeneratorまたはKeyGeneratorによって生成されたキー用
• import。KeyFactoryまたはSecretKeyFactoryによって作成されたキー用。暗号化操作の初期化メソッド(Signature.initSign()など)に渡されるときにPKCS#11キー・オブジェクトに自動的に変換されるJava Softwareキーにも適用される。
• *。生成操作または作成操作のどちらかで作成されたキー用。

keytypeの有効な値は、CKO_PUBLIC_KEY、CKO_PRIVATE_KEY、およびCKO_SECRET_KEYで、それぞれ公開キー、非公開キー、および秘密キーに対応しています。また、任意のキー・タイプに一致する*もあります。

keyalgorithmの有効な値は、PKCS#11仕様に定義されたCKK_xxx定数のいずれか1つ、または任意のキー・アルゴリズムに一致する*です。「SunPKCS11プロバイダでサポートされているアルゴリズム」を参照してください。

属性の名前と値は、1つまたは複数の名前と値のペアのリストとして指定されます。nameはPKCS#11仕様のCKA_xxx定数(CKA_SENSITIVEなど)でなければなりません。valueは、次のいずれかになります。

• ブール値。trueまたはfalse
• 整数値。10進数表記(デフォルト)または0xで始まる16進数表記。
• null。この属性はオブジェクトの作成時に指定してはならないことを示す。

attributesオプションを複数回指定すると、エントリは、まとめられた属性で指定された順序で、あとの属性が前の属性をオーバーライドして処理されます。たとえば、次の構成ファイルを考えてみます。

attributes(*,CKO_PRIVATE_KEY,*) = {
  CKA_SIGN = true
}

attributes(*,CKO_PRIVATE_KEY,CKK_DH) = {
  CKA_SIGN = null
}

attributes(*,CKO_PRIVATE_KEY,CKK_RSA) = {
  CKA_DECRYPT = true
}

1番目のエントリでは、すべての秘密キーに対してCKA_SIGN = trueを指定しています。2番目のオプションでは、Diffie-Hellman秘密キーについてnullでオーバーライドするため、CKA_SIGN属性はDiffie-Hellman秘密キーに対してまったく指定されません。最後に、3番目のオプションでは、RSA秘密キーに対してCKA_DECRYPT = trueを指定しています。つまりRSA秘密キーには、CKA_SIGN = trueとCKA_DECRYPT = true両方のセットがあることになります。

attributesオプションには特殊な形式もあります。構成ファイルにattributes = compatibilityと書くことができます。これは、属性ステートメントのセット全体に対するショートカットです。これはプロバイダが既存のJavaアプリケーションとの互換性を最大限に保つことを目的としています。これにより、Javaアプリケーションでは、たとえばすべてのキー・コンポーネントにアクセス可能で、秘密キーを暗号化および復号化の両方に使用可能であることが期待されます。compatibility属性の行は、他のattributes行とともに使用できます。この場合は先に説明したような、同様のアグリゲーションおよびオーバーライドの規則が適用されます。

ネットワーク・セキュリティ・サービス(NSS)は一連のオープン・ソース・セキュリティ・ライブラリであり、その暗号化APIは、PKCS#11に基づいていますが、PKCS#11標準ではない特別な機能を含んでいます。SunPKCS11プロバイダには、NSS固有の機能(複数のNSS固有の構成ディレクティブなど)と連携するコードが含まれています。

最適な結果を得るために、使用可能な最新バージョンのNSSを使用することをお薦めします。少なくともバージョン3.12になります。

表5-2で説明されているnss構成ディレクティブのいずれかが使用されている場合、SunPKCS11プロバイダはNSS固有のコードを使用します。この場合、通常の構成コマンドlibrary、slot、およびslotListIndexは使用できません。

PKCS#11に問題が発生し、デバッグが必要になることがあります。ライブラリ、スロット、トークンおよびメカニズムのデバッグ情報を表示するには、「SunPKCS11の構成」で説明しているように静的または動的に指定したSunPKCS11プロバイダ構成ファイルにshowInfo=trueを追加します。

その他のデバッグ情報については、次のいずれかのオプションを指定してJavaプロセスを起動または再起動してください。

• SunPKCS11プロバイダの一般的なデバッグ情報:

  -Djava.security.debug=sunpkcs11

• PKCS#11キーストア固有のデバッグ情報の場合:

  -Djava.security.debug=pkcs11keystore

PKCS#11プロバイダの無効化

特定のJavaインストールで実行されるすべてのJavaプロセスに対してPKCS#11プロバイダを無効にするには、これらのステップに従います:

1. 「SunPKCS11の構成」の説明に従って、PKCS#11プロバイダをインストールしたことを確認します。これらのステップでは、次のことが前提です:

   • PKCS#11プロバイダの名前はMyOwnです。

   • 構成ファイルの名前はjava-home/conf/security/myown.cfgで、次の内容が含まれています。

     name = MyOwn
     description = A PKCS11 provider accessing a specific PKCS11 binary implementation
     library = Pathname of MyOwn PKCS11 implementation

   • 次のようにJavaセキュリティ・プロパティ・ファイル(java-home/conf/security/java.security)を変更しました。

     #
     # List of providers and their preference orders:
     #
     security.provider.1=SUN
     security.provider.2=SunRsaSign
     security.provider.3=SunPKCS11 myOwn.cfg
     security.provider.4=SunEC
     security.provider.5=SunJSSE
     ...

2. このJavaインストールでMyOwn PKCS#11プロバイダを静的に無効化するには、Javaセキュリティ・プロパティ・ファイルを編集し、プロバイダが登録されている行をコメント・アウトしてから、それに続くプロバイダの優先順位を再番号付けします。

   #
   # List of providers and their preference orders:
   #
   security.provider.1=SUN
   security.provider.2=SunRsaSign
   #security.provider.3=SunPKCS11 myOwn.cfg
   security.provider.3=SunEC
   security.provider.4=SunJSSE
   ...

3. このJavaインストールでMyOwn PKCS#11プロバイダを動的に無効化するには、アプリケーションで次を呼び出します。

       Security.removeProvider("SunPKCS11-MyOwn");

特定のメカニズムの無効化

PKCS#11のメカニズムのいずれかで問題が発生した場合、PKCS#11プロバイダ全体ではなく、その特定のメカニズムのみを無効にすることにより、問題を解決できます(それまでにPKCS#11プロバイダを無効にしていた場合は、再度有効にすることを忘れないでください)。

disabledMechanisms = {
    SecureRandom
}

jdk.security.jarsigner APIおよびPKCS#11トークンでのJARファイルの署名

jdk.security.jarsigner APIおよびPKCS#11トークンをキーストアとしてJARファイルに署名するには、次のステップに従います:

1. 「トークン・ログイン」の説明に従って、PKCS#11トークンのキーストアにアクセスします。

       char[] pin = ...; 
       KeyStore ks = KeyStore.getInstance("PKCS11");
       ks.load(null, pin); 
       KeyStore ks = builder.getKeyStore();
       Key key = ks.getKey(alias, null);

2. JarSigner.Builder(Keystore.PrivateKeyEntry)コンストラクタを使用してJarSignerオブジェクトを作成します。

       JarSigner mySigner = JarSigner.Builder(key).build();

3. JARファイルに署名します。

       try (ZipFile in = new ZipFile(inputFile);
       FileOutputStream out = new FileOutputStream(outputFile)) {
           mySigner.sign(in, out);
       }

Elliptic Curveメカニズムでは、SunPKCS11プロバイダは、パラメータのエンコーディングとしてnamedCurveの選択を使用するキーのみを使用し、圧縮されていない形式のみを許可します。SunPKCS11プロバイダでは、標準名が付けられたすべてのドメイン・パラメータをトークンがサポートしていることが前提となります。

次の表のPKCS#11メカニズムの詳細は、「PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 3.0」を参照してください。

読取り専用アクセス

PKCS#11トークンに保存された既存のオブジェクトをKeyStoreエントリにマッピングするため、SunPKCS11プロバイダのKeyStore実装は次の操作を実行します。

1. C_FindObjects[Init|Final]を呼び出して、トークン上のすべての秘密キー・オブジェクトを検索します。検索テンプレートには、次の属性があります。
   • CKA_TOKEN = true
   • CKA_CLASS = CKO_PRIVATE_KEY
2. C_FindObjects[Init|Final]を呼び出して、トークン上のすべての証明書オブジェクトを検索します。検索テンプレートには、次の属性があります。
   • CKA_TOKEN = true
   • CKA_CLASS = CKO_CERTIFICATE
3. それぞれのCKA_ID属性を取得することで、各秘密キー・オブジェクトを対応する証明書と一致させます。一致するペアは、同じ一意のCKA_IDを共有する必要があります。

   一致するペアごとに、発行者 ->サブジェクトのパスに従って証明書チェーンが作成されます。エンド・エンティティ証明書から、次の属性を持つ検索テンプレートを使用したC_FindObjects[Init|Final]が呼び出されます。

   • CKA_TOKEN = true
   • CKA_CLASS = CKO_CERTIFICATE
   • CKA_SUBJECT = [DN of certificate issuer]

   この検索は、発行者の証明書が見つからないか、自己署名証明書が見つかるまで継続します。複数の証明書が見つかった場合は、最初の証明書が使用されます。

   秘密キーと証明書が一致して証明書チェーンが作成されると、エンド・エンティティ証明書のCKA_LABELの値をKeyStoreの別名として、秘密キー・エントリに情報が保存されます。

   エンド・エンティティ証明書にCKA_LABELがない場合は、別名はCKA_IDから作成されます。CKA_IDが出力可能文字からのみ構成される場合は、CKA_IDのバイトをUTF-8文字セットを使用してデコードして、Stringの別名を作成します。または、16進数のString別名を、CKA_IDバイトから作成します(例: 「0xFFFF」)。

   複数の証明書が同一のCKA_LABELを共有する場合、別名はCKA_LABELに加え、エンド・エンティティ証明書の発行者およびシリアル番号(例: "MyCert/CN=foobar/1234")から作成されます。

4. (エンド・エンティティ証明書として)秘密キー・エントリの一部ではない各証明書は、信頼できるかどうかチェックされます。CKA_TRUSTED属性がtrueの場合、CKA_LABEL値をKeyStoreの別名とする、KeyStoreの信頼できる証明書エントリが作成されます。証明書にCKA_LABELがない場合、または複数の証明書が同じCKA_LABELを共有する場合、別名は上述のように作成されます。

   CKA_TRUSTED属性がサポートされていない場合は、信頼できる証明書エントリは作成されません。

5. 秘密キー・エントリまたは信頼できる証明書エントリの一部ではない秘密キーまたは証明書オブジェクトは、すべて無視されます。
6. C_FindObjects[Init|Final]を呼び出して、トークン上のすべての秘密キーオブジェクトを検索します。検索テンプレートには、次の属性があります。
   • CKA_TOKEN = true
   • CKA_CLASS = CKO_SECRET_KEY

   各秘密キーオブジェクトに対して、CKA_LABEL値をKeyStoreの別名とするKeyStore秘密キーエントリが作成されます。各秘密キーオブジェクトには、固有のCKA_LABELが必要です。

書込みアクセス

PKCS#11トークンにKeyStoreエントリに対する新しいKeyStoreエントリを作成するため、SunPKCS11プロバイダのKeyStore実装は次の操作を実行します。

1. KeyStoreエントリを作成するときには(KeyStore.setEntryなどの使用中)、CKA_TOKEN=trueとしてC_CreateObjectが呼び出され、エントリの内容それぞれに対してトークン・オブジェクトが作成されます。

   秘密キー・オブジェクトは、CKA_PRIVATE=trueで保存されます。KeyStoreの別名(UTF-8エンコード)は、秘密キーと対応するエンド・エンティティ証明書の両方でCKA_IDとして設定されます。KeyStoreの別名では、エンド・エンティティ証明書オブジェクトにCKA_LABELが設定されます。

   秘密キー・エントリのチェーン内の各証明書も保存されます。CKA_LABELは、CA証明書には設定されません。CA証明書がトークン内にある場合、複製は保存されません。

   秘密キーオブジェクトは、CKA_PRIVATE=trueで保存されます。KeyStoreの別名は、CKA_LABELとして設定されます。

2. セッション・オブジェクトをトークン・オブジェクトに変換しようとする場合(KeyStore.setEntryが呼び出され、指定されたエントリの秘密キー・オブジェクトがセッション・オブジェクトである場合など)、C_CopyObjectがCKA_TOKEN=trueとして呼び出されます。
3. トークン内に複数の証明書が見つかり、同じCKA_LABELを共有する場合は、トークンへの書込み機能は無効になります。
4. PKCS#11仕様では一般のアプリケーションでCKA_TRUSTED=trueと設定することが許可されないため(トークン初期化アプリケーションのみが可能)、信頼できる証明書エントリを作成できません。

その他

前述の検索内容に加え、SunPKCS11プロバイダのKeyStore実装で次の検索を使用して内部関数を実行できます。具体的には、次のどの属性テンプレートを使用しても、C_FindObjects[Init|Final]を呼び出すことができます。

•     CKA_TOKEN    true
      CKA_CLASS    CKO_CERTIFICATE
      CKA_SUBJECT  [subject DN]

•     CKA_TOKEN    true
      CKA_CLASS    CKO_SECRET_KEY
      CKA_LABEL    [label]

•     CKA_TOKEN    true
      CKA_CLASS    CKO_CERTIFICATE or CKO_PRIVATE_KEY
      CKA_ID       [cka_id]

package com.foo;

import java.io.*;
import java.lang.reflect.*;
import java.security.*;
import javax.crypto.*;

/**
 * Example provider that demonstrates some Provider class features.
 *
 *  . Implement multiple different algorithms in a single class.
 *    Previously each algorithm needed to be implemented in a separate class
 *    (e.g. one for SHA-256, one for SHA-384, etc.)
 *
 *  . Multiple concurrent instances of the provider frontend class each
 *    associated with a different backend.
 *
 *  . It uses "unextractable" keys and lets the framework know which key
 *    objects it can and cannot support
 *
 * Note that this is only a simple example provider designed to demonstrate
 * several of the new features. It is not explicitly designed for efficiency.
 */
public final class ExampleProvider extends Provider {

    // Reference to the crypto backend that implements all the algorithms.
    final CryptoBackend cryptoBackend;

    public ExampleProvider(String name, CryptoBackend cryptoBackend) {
        super(name, 1.0, "JCA/JCE provider for " + name);
        this.cryptoBackend = cryptoBackend;
        // register the algorithms we support (SHA-256, SHA-384, DESede, and AES)
        putService(new MyService
            (this, "MessageDigest", "SHA-256", "com.foo.ExampleProvider$MyMessageDigest"));
        putService(new MyService
            (this, "MessageDigest", "SHA-384", "com.foo.ExampleProvider$MyMessageDigest"));
        putService(new MyCipherService
            (this, "Cipher", "DES", "com.foo.ExampleProvider$MyCipher"));
        putService(new MyCipherService
            (this, "Cipher", "AES", "com.foo.ExampleProvider$MyCipher"));
    }

    // The API of our fictitious crypto backend.
    static abstract class CryptoBackend {
        abstract byte[] digest(String algorithm, byte[] data);
        abstract byte[] encrypt(String algorithm, KeyHandle key, byte[] data);
        abstract byte[] decrypt(String algorithm, KeyHandle key, byte[] data);
        abstract KeyHandle createKey(String algorithm, byte[] keyData);
    }

    // The shell of the representation the crypto backend uses for keys.
    private static final class KeyHandle {
        // fill in code
    }

    // We have our own ServiceDescription implementation that overrides newInstance()
    // that calls the (Provider, String) constructor instead of the no-args constructor.
    private static class MyService extends Service {

        private static final Class[] paramTypes = {Provider.class, String.class};

        MyService(Provider provider, String type, String algorithm,
                String className) {
            super(provider, type, algorithm, className, null, null);
        }

        public Object newInstance(Object param) throws NoSuchAlgorithmException {
            try {
                // Get the Class object for the implementation class.
                Class clazz;
                Provider provider = getProvider();
                ClassLoader loader = provider.getClass().getClassLoader();
                if (loader == null) {
                    clazz = Class.forName(getClassName());
                } else {
                    clazz = loader.loadClass(getClassName());
                }
                // Fetch the (Provider, String) constructor.
                Constructor cons = clazz.getConstructor(paramTypes);
                // Invoke constructor and return the SPI object.
                Object obj = cons.newInstance(new Object[] {provider, getAlgorithm()});
                return obj;
            } catch (Exception e) {
                throw new NoSuchAlgorithmException("Could not instantiate service", e);
            }
        }
    }

    // Custom ServiceDescription class for Cipher objects. See supportsParameter().
    private static class MyCipherService extends MyService {
        MyCipherService(Provider provider, String type, String algorithm,
                String className) {
            super(provider, type, algorithm, className);
        }
        // We override supportsParameter() to let the framework know which
        // keys we can support. We support instances of MySecretKey, if they
        // are stored in our provider backend, plus SecretKeys with a RAW encoding.
        public boolean supportsParameter(Object obj) {
            if (obj instanceof SecretKey == false) {
                return false;
            }
            SecretKey key = (SecretKey)obj;
            if (key.getAlgorithm().equals(getAlgorithm()) == false) {
                return false;
            }
            if (key instanceof MySecretKey) {
                MySecretKey myKey = (MySecretKey)key;
                return myKey.provider == getProvider();
            } else {
                return "RAW".equals(key.getFormat());
            }
        }
    }

    // Our generic MessageDigest implementation. It implements all digest
    // algorithms in a single class. We only implement the bare minimum
    // of MessageDigestSpi methods.
    private static final class MyMessageDigest extends MessageDigestSpi {
        private final ExampleProvider provider;
        private final String algorithm;
        private ByteArrayOutputStream buffer;
        MyMessageDigest(Provider provider, String algorithm) {
            super();
            this.provider = (ExampleProvider)provider;
            this.algorithm = algorithm;
            engineReset();
        }
        protected void engineReset() {
            buffer = new ByteArrayOutputStream();
        }
        protected void engineUpdate(byte b) {
            buffer.write(b);
        }
        protected void engineUpdate(byte[] b, int ofs, int len) {
            buffer.write(b, ofs, len);
        }
        protected byte[] engineDigest() {
            byte[] data = buffer.toByteArray();
            byte[] digest = provider.cryptoBackend.digest(algorithm, data);
            engineReset();
            return digest;
        }
    }

    // our generic Cipher implementation, only partially complete. It implements
    // all cipher algorithms in a single class. We implement only as many of the
    // CipherSpi methods as required to show how it could work
    private static abstract class MyCipher extends CipherSpi {
        private final ExampleProvider provider;
        private final String algorithm;
        private int opmode;
        private MySecretKey myKey;
        private ByteArrayOutputStream buffer;
        MyCipher(Provider provider, String algorithm) {
            super();
            this.provider = (ExampleProvider)provider;
            this.algorithm = algorithm;
        }
        protected void engineInit(int opmode, Key key, SecureRandom random)
                throws InvalidKeyException {
            this.opmode = opmode;
            myKey = MySecretKey.getKey(provider, algorithm, key);
            if (myKey == null) {
                throw new InvalidKeyException();
            }
            buffer = new ByteArrayOutputStream();
        }
        protected byte[] engineUpdate(byte[] b, int ofs, int len) {
            buffer.write(b, ofs, len);
            return new byte[0];
        }
        protected int engineUpdate(byte[] b, int ofs, int len, byte[] out, int outOfs) {
            buffer.write(b, ofs, len);
            return 0;
        }
        protected byte[] engineDoFinal(byte[] b, int ofs, int len) {
            buffer.write(b, ofs, len);
            byte[] in = buffer.toByteArray();
            byte[] out;
            if (opmode == Cipher.ENCRYPT_MODE) {
                out = provider.cryptoBackend.encrypt(algorithm, myKey.handle, in);
            } else {
                out = provider.cryptoBackend.decrypt(algorithm, myKey.handle, in);
            }
            buffer = new ByteArrayOutputStream();
            return out;
        }
        // code for remaining CipherSpi methods goes here
    }

    // our SecretKey implementation. All our keys are stored in our crypto
    // backend, we only have an opaque handle available. There is no
    // encoded form of these keys.
    private static final class MySecretKey implements SecretKey {

        final String algorithm;
        final Provider provider;
        final KeyHandle handle;

        MySecretKey(Provider provider, String algorithm, KeyHandle handle) {
            super();
            this.provider = provider;
            this.algorithm = algorithm;
            this.handle = handle;
        }
        public String getAlgorithm() {
            return algorithm;
        }
        public String getFormat() {
            return null; // this key has no encoded form
        }
        public byte[] getEncoded() {
            return null; // this key has no encoded form
        }
        // Convert the given key to a key of the specified provider, if possible
        static MySecretKey getKey(ExampleProvider provider, String algorithm, Key key) {
            if (key instanceof SecretKey == false) {
                return null;
            }
            // algorithm name must match
            if (!key.getAlgorithm().equals(algorithm)) {
                return null;
            }
            // if key is already an instance of MySecretKey and is stored
            // on this provider, return it right away
            if (key instanceof MySecretKey) {
                MySecretKey myKey = (MySecretKey)key;
                if (myKey.provider == provider) {
                    return myKey;
                }
            }
            // otherwise, if the input key has a RAW encoding, convert it
            if (!"RAW".equals(key.getFormat())) {
                return null;
            }
            byte[] encoded = key.getEncoded();
            KeyHandle handle = provider.cryptoBackend.createKey(algorithm, encoded);
            return new MySecretKey(provider, algorithm, handle);
        }
    }
}