JniKeychain ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- com.entrust.toolkit.keychain.JniKeychain

public abstract class JniKeychain
extends java.lang.Object

Class for interfacing with native Keychain code.

Since:: 7.2

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addCertificate(X509Certificate certificate, boolean isRoot)`
`static void`	`addKeyPair(X509Certificate certificate, java.lang.String certificateLabel, byte[] privateKeyData, java.lang.String privateKeyLabel, boolean privateKeyExportable, java.lang.String keychainName, SecureStringBuffer securedPassword)`
`static X509Certificate[]`	`buildCertificateChain(X509Certificate certificate)`
`static X509Certificate[]`	`buildCertificateChainWithRoots(X509Certificate certificate, X509Certificate[] rootCertificates)` Build a certificate chain with provided a list of root certificates which are to be considered trusted anchors by Apple API.
`static byte[]`	`createDecryptedData(KeychainPrivateKey key, byte[] cipherText)` Decrypt the given CipherText using an RSA private key.
`static byte[]`	`createEncryptedData(KeychainPrivateKey key, byte[] plainText)` Encrypt the given data using an RSA Private key.
`static long`	`createEntrustKeychainRefUserPrompt(java.lang.String keychainName)` Create a new named keychain or get the copy of the default keychain.
`static boolean`	`createKeychain(java.lang.String keychainName, SecureStringBuffer securedPassword)`
`static byte[]`	`createRSASignaturePKCS1v15Raw(KeychainPrivateKey key, byte[] encodedDigestInfoToSign)` Create the RSA PKCS1 v1.5 signature given the KeychainPrivateKey, the encoded digest info data.
`static byte[]`	`createSignature(KeychainPrivateKey key, byte[] dataToSign)` Create the signature given the KeychainPrivateKey, the data to Sign and the algorithm to use for the Signature.
`static boolean`	`deleteEntrustKeychain(java.lang.String keychainName)` delete Entrust Keychain folder from keychain
`static void`	`deleteKeychainKey(KeychainPrivateKey privateKeyChainKey)` delete the private key by given the KeychainPrivateKey
`static void`	`deleteOmittedCertificates()`
`static void`	`deleteUserKeyPairs(java.lang.String userDN)` delete the key pairs with specified certificate's subject DN
`static byte[]`	`encryptData(long publicKeyRef, java.lang.String keychainAlgID, byte[] plainText)` Encrypt the given data using an RSA public key.
`static byte[]`	`encryptForSmartCardDriver(byte[] publicKeyHash, byte[] serialNumber, SecureByteArray securedPlainText)`
`static X509Certificate[]`	`enumerateCertificates()`
`static X509Certificate[]`	`enumerateRootCertificates()` Enumerate all of the root certificates (both local and system) from the keychain.
`static byte[]`	`exportRSAPrivateKeyInfo(long rsaPrivatekeyRef)` Export the private key info out of the given private key.
`static byte[]`	`exportRSAPublicKeyInfo(long rsaPrivatekeyRef)` Export the public key info out of the given private key.
`static long`	`generateRSAPrivateKeychainKeyRef(long keychainRef, int keySize, boolean backup, boolean exportable)` Generate a random RSA key pair in the specified keychain.
`static java.lang.String`	`getApplicationName()` retrieve .app bundle name.
`static java.lang.String`	`getApplicationSupportFolder()` On the Mac, retrieve application support directory which store persistent user-related files for your application
`static java.lang.String`	`getEPFLoginIDWithCertificate(X509Certificate certificate)`
`static X509Certificate[]`	`getMyCertificates()`
`static X509Certificate[]`	`getMyEncryptionCertificates()`
`static X509Certificate[]`	`getMySigningCertificates()`
`static X509Certificate[]`	`getMySmartCardCertificates(java.lang.String tokenID)` Retrieve the smart card certificates from the keychain based on the token ID.
`static KeychainKey`	`getPrivateKeyChainKey(X509Certificate certificate)` Return the a new KeychainKey that wraps the handled to the private key stored in the Keychain.
`static long`	`getPublicKeyChainKey(X509Certificate certificate)`
`static byte[]`	`hashPublicKey(X509Certificate certificate)`
`static long`	`importPublicKeyInfo(byte[] publicKeyInfoData)` Import the public key info and return public key reference.
`static void`	`initializeKeychain()` Load the default Keychain native library.
`static void`	`initializeKeychain(java.lang.String libraryPath)` Loads the Keychain native library from the given path.
`static boolean`	`isCertMarkedAsTrusted(X509Certificate certificate)` Check to see if the certificate is marked as trusted in the keychain.
`static boolean`	`isImportToDefaultKeychain()`
`static boolean`	`isKeychainInitialized()` Returns `true` if the native Keychain library has been successfully loaded and initialized, `false` otherwise.
`static boolean`	`isKeychainSynchronizationEnabled()`
`static byte[]`	`keyAgree(long privateKeyChainKey, long publicKeyChainKey, byte[] encodedSharedInfo, int secretSize, java.lang.String kdfAlgorithmOID)`
`static void`	`lockEntrustKeychain(java.lang.String keychainName)`
`static long`	`openEntrustKeychainRefUserPrompt(java.lang.String keychainName)` Open a named keychain or get the copy of the default keychain.
`static void`	`releaseEntrustKeychainRef(long keychainRef)` Release the keychaiRef which is acquired through createEntrustKeychainRefUserPrompt() call.
`static void`	`releaseKeyChainKey(long keyChainKey)` Release the handle to the Keychainkey
`static void`	`setDeleteOmittedCertificates(boolean deleteOmittedCertificates)` Determines whether any certificates in the omitCertificatePath will also be explicitly deleted if present during each synchronization.
`static void`	`setImportToDefaultKeychain(boolean importToDefaultKeychain)`
`static void`	`setKeychainSynchronizationEnabled(boolean keychainSynchronizationEnabled)` Determines whether perform the keychain synchronization without checking the policy.
`static void`	`setOmitCertificatePath(java.lang.String omitCertificatesPath)` Sets the path to the certificates that will not be added to the keychain during synchronization.
`static boolean`	`verifySignature(long publicKeyChainKey, byte[] signature, byte[] dataToSign, java.lang.String algorithmOID)` Verify the Signature using the Keychain
`static void`	`viewCertificate(X509Certificate certificate)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - initializeKeychain
```
public static void initializeKeychain()
                               throws java.lang.UnsatisfiedLinkError
```
    Load the default Keychain native library. The default library name is "libEntrustKeychain.jnilib", and it must be found on the path.
    Multiple initialization is not allowed, this method has no effect if the library has already been initialized successfully.
    
    Throws:
    
    java.lang.UnsatisfiedLinkError - If the library cannot be loaded.
  - initializeKeychain
```
public static void initializeKeychain(java.lang.String libraryPath)
                               throws java.lang.UnsatisfiedLinkError
```
    Loads the Keychain native library from the given path.
    Multiple initialization is not allowed, this method has no effect if the library has already been initialized successfully.
    
    The default library method is not supported. A name must be specified. Though on Mac OS X the name can be provided without a path.
    
    Parameters:
    
    libraryPath - Full path to the Keychain native library to load.
    
    Throws:
    
    java.lang.UnsatisfiedLinkError - If the specified library cannot be loaded.
  - setOmitCertificatePath
```
public static void setOmitCertificatePath(java.lang.String omitCertificatesPath)
```
    Sets the path to the certificates that will not be added to the keychain during synchronization.
    
    Parameters:
    
    omitCertificatesPath -
  - setDeleteOmittedCertificates
```
public static void setDeleteOmittedCertificates(boolean deleteOmittedCertificates)
```
    Determines whether any certificates in the omitCertificatePath will also be explicitly deleted if present during each synchronization.
    
    Parameters:
    
    deleteOmittedCertificates -
  - isKeychainInitialized
```
public static boolean isKeychainInitialized()
```
    Returns true if the native Keychain library has been successfully loaded and initialized, false otherwise.
    
    Returns:
    
    true if the native Keychain library has been successfully loaded and initialized, false otherwise.
  - hashPublicKey
```
public static byte[] hashPublicKey(X509Certificate certificate)
                            throws java.security.NoSuchAlgorithmException,
                                   java.security.NoSuchProviderException,
                                   CodingException
```
    Throws:
    
    java.security.NoSuchAlgorithmException
    
    java.security.NoSuchProviderException
    
    CodingException
  - deleteOmittedCertificates
```
public static void deleteOmittedCertificates()
```
  - setKeychainSynchronizationEnabled
```
public static void setKeychainSynchronizationEnabled(boolean keychainSynchronizationEnabled)
```
    Determines whether perform the keychain synchronization without checking the policy.
    
    Parameters:
    
    keychainSynchronizationEnabled -
  - isKeychainSynchronizationEnabled
```
public static boolean isKeychainSynchronizationEnabled()
```
  - setImportToDefaultKeychain
```
public static void setImportToDefaultKeychain(boolean importToDefaultKeychain)
```
  - isImportToDefaultKeychain
```
public static boolean isImportToDefaultKeychain()
```
  - addCertificate
```
public static void addCertificate(X509Certificate certificate,
                                  boolean isRoot)
                           throws java.security.NoSuchAlgorithmException,
                                  java.security.NoSuchProviderException,
                                  CodingException
```
    Throws:
    
    java.security.NoSuchAlgorithmException
    
    java.security.NoSuchProviderException
    
    CodingException
  - addKeyPair
```
public static void addKeyPair(X509Certificate certificate,
                              java.lang.String certificateLabel,
                              byte[] privateKeyData,
                              java.lang.String privateKeyLabel,
                              boolean privateKeyExportable,
                              java.lang.String keychainName,
                              SecureStringBuffer securedPassword)
                       throws java.security.NoSuchAlgorithmException,
                              java.security.NoSuchProviderException,
                              CodingException
```
    Throws:
    
    java.security.NoSuchAlgorithmException
    
    java.security.NoSuchProviderException
    
    CodingException
  - createKeychain
```
public static boolean createKeychain(java.lang.String keychainName,
                                     SecureStringBuffer securedPassword)
```
  - createEntrustKeychainRefUserPrompt
```
public static long createEntrustKeychainRefUserPrompt(java.lang.String keychainName)
```
    Create a new named keychain or get the copy of the default keychain.
    
    Parameters:
    
    keychainName - The name of the keychain for which a keychain is created or copied of the default keychain if no name is provided.
    
    Returns:
    
    The SecKeychainRef casted as long, or 0 if failed to create the named keychain or copy the default keychain. Call releaseEntrustKeychainRef() to release the SecKeychainRef after it is no longer needed.
  - openEntrustKeychainRefUserPrompt
```
public static long openEntrustKeychainRefUserPrompt(java.lang.String keychainName)
```
    Open a named keychain or get the copy of the default keychain.
    
    Parameters:
    
    keychainName - The name of the keychain for which the keychain is opened or copied of the default keychain if no name is provided.
    
    Returns:
    
    The SecKeychainRef casted as long, or 0 if failed to open the named keychain or copy the default keychain. Call releaseEntrustKeychainRef() to release the SecKeychainRef after it is no longer needed.
  - releaseEntrustKeychainRef
```
public static void releaseEntrustKeychainRef(long keychainRef)
```
    Release the keychaiRef which is acquired through createEntrustKeychainRefUserPrompt() call.
    
    Parameters:
    
    keychainRef -
  - lockEntrustKeychain
```
public static void lockEntrustKeychain(java.lang.String keychainName)
```
  - getMyEncryptionCertificates
```
public static X509Certificate[] getMyEncryptionCertificates()
```
  - getMySigningCertificates
```
public static X509Certificate[] getMySigningCertificates()
```
  - getMyCertificates
```
public static X509Certificate[] getMyCertificates()
```
  - enumerateCertificates
```
public static X509Certificate[] enumerateCertificates()
```
  - enumerateRootCertificates
```
public static X509Certificate[] enumerateRootCertificates()
```
    Enumerate all of the root certificates (both local and system) from the keychain.
    
    Returns:
    
    - a list of root certificates
  - viewCertificate
```
public static void viewCertificate(X509Certificate certificate)
```
  - buildCertificateChain
```
public static X509Certificate[] buildCertificateChain(X509Certificate certificate)
```
  - buildCertificateChainWithRoots
```
public static X509Certificate[] buildCertificateChainWithRoots(X509Certificate certificate,
                                                               X509Certificate[] rootCertificates)
```
    Build a certificate chain with provided a list of root certificates which are to be considered trusted anchors by Apple API.
    
    Parameters:
    
    certificate - - to be built the chain
    
    rootCertificates - - a list of root certificates
    
    Returns:
    
    a certificate chain
  - getPrivateKeyChainKey
```
public static KeychainKey getPrivateKeyChainKey(X509Certificate certificate)
```
    Return the a new KeychainKey that wraps the handled to the private key stored in the Keychain.
    
    Parameters:
    
    certificate - the X509Certificate of the public key for the private KeychainKey being retrieved from the Keychain
    
    Returns:
    
    The KeychainKey
  - getPublicKeyChainKey
```
public static long getPublicKeyChainKey(X509Certificate certificate)
```
  - releaseKeyChainKey
```
public static void releaseKeyChainKey(long keyChainKey)
```
    Release the handle to the Keychainkey
    
    Parameters:
    
    keyChainKey -
  - generateRSAPrivateKeychainKeyRef
```
public static long generateRSAPrivateKeychainKeyRef(long keychainRef,
                                                    int keySize,
                                                    boolean backup,
                                                    boolean exportable)
```
    Generate a random RSA key pair in the specified keychain.
    
    Parameters:
    
    keychainRef - - the keychain to store the generated key
    
    keySize - - RSA key size in bits
    
    backup - - whether the key needs backup
    
    exportable - - whether the key is exportable
    
    Returns:
    
    The generated SecKeyRef casted as long
  - exportRSAPublicKeyInfo
```
public static byte[] exportRSAPublicKeyInfo(long rsaPrivatekeyRef)
```
    Export the public key info out of the given private key.
    
    Parameters:
    
    rsaPrivatekeyRef -
    
    Returns:
    
    bytes[].
  - importPublicKeyInfo
```
public static long importPublicKeyInfo(byte[] publicKeyInfoData)
```
    Import the public key info and return public key reference.
    
    Parameters:
    
    public - key info bytes
    
    Returns:
    
    publicKeyRef.
  - exportRSAPrivateKeyInfo
```
public static byte[] exportRSAPrivateKeyInfo(long rsaPrivatekeyRef)
```
    Export the private key info out of the given private key.
    
    Parameters:
    
    rsaPrivatekeyRef -
    
    Returns:
    
    bytes[]
  - createSignature
```
public static byte[] createSignature(KeychainPrivateKey key,
                                     byte[] dataToSign)
                              throws KeychainException
```
    Create the signature given the KeychainPrivateKey, the data to Sign and the algorithm to use for the Signature. This function requires a SHA1 or SHA2 digest value only, and relies on the Keychain to perform the PKCS1v1.5 encoding.
    
    Parameters:
    
    key - The KeychainPrivate Key to use for signing
    
    dataToSign - The data to sign for the key
    
    algorithmOID - The string AlgorithmID
    
    Returns:
    
    the array of bytes representing the signature
    
    Throws:
    
    KeychainException
  - createRSASignaturePKCS1v15Raw
```
public static byte[] createRSASignaturePKCS1v15Raw(KeychainPrivateKey key,
                                                   byte[] encodedDigestInfoToSign)
                                            throws KeychainException
```
    Create the RSA PKCS1 v1.5 signature given the KeychainPrivateKey, the encoded digest info data.
    
    Parameters:
    
    key - The KeychainPrivate Key to use for signing
    
    encodedDigestInfoToSign - The data to sign. This data should be an encoded digest info if caller wants to generate a signature for CMS based on PKCS1v1.5. Note 1: There is no checking of the encodedDigestInfoToSign length or algorithm OID within it. Note 2: API createSignature() will take a digest data and SHA1 or SHA2 algorithmID OID to create a RSA PKCS1V1.5 signature. The keychain will encode digest info first and then do the signing against the encoded digest info.
    
    Returns:
    
    the array of bytes representing the signature
    
    Throws:
    
    KeychainException
  - verifySignature
```
public static boolean verifySignature(long publicKeyChainKey,
                                      byte[] signature,
                                      byte[] dataToSign,
                                      java.lang.String algorithmOID)
```
    Verify the Signature using the Keychain
    
    Parameters:
    
    publicKeyChainKey -
    
    signature -
    
    dataToSign -
    
    algorithmOID -
    
    Returns:
  - createEncryptedData
```
public static byte[] createEncryptedData(KeychainPrivateKey key,
                                         byte[] plainText)
                                  throws KeychainException
```
    Encrypt the given data using an RSA Private key. Usually an encryption operation will require a public key, but this API uses a private key and therefore will perform a signing operation. Note: This will only work with a Cipher operation
    
    Parameters:
    
    key - the KeychainPrivate Key
    
    plainText - the plainText to be encrypted
    
    Returns:
    
    the encrypted cipherText
    
    Throws:
    
    KeychainException
  - encryptData
```
public static byte[] encryptData(long publicKeyRef,
                                 java.lang.String keychainAlgID,
                                 byte[] plainText)
                          throws KeychainException
```
    Encrypt the given data using an RSA public key.
    
    Parameters:
    
    key: - The public key reference.
    
    plainText: - The plainText to be encrypted
    
    Returns:
    
    Encrypted cipherText
    
    Throws:
    
    KeychainException
  - createDecryptedData
```
public static byte[] createDecryptedData(KeychainPrivateKey key,
                                         byte[] cipherText)
                                  throws KeychainException
```
    Decrypt the given CipherText using an RSA private key.
    
    Parameters:
    
    key - the KeychainPrivate Key
    
    cipherText - the plainText to be encrypted
    
    Returns:
    
    the decrypted plainText
    
    Throws:
    
    KeychainException
  - keyAgree
```
public static byte[] keyAgree(long privateKeyChainKey,
                              long publicKeyChainKey,
                              byte[] encodedSharedInfo,
                              int secretSize,
                              java.lang.String kdfAlgorithmOID)
```
  - deleteKeychainKey
```
public static void deleteKeychainKey(KeychainPrivateKey privateKeyChainKey)
```
    delete the private key by given the KeychainPrivateKey
    
    Parameters:
    
    key - - The KeychainPrivate Key to be deleted
  - deleteUserKeyPairs
```
public static void deleteUserKeyPairs(java.lang.String userDN)
```
    delete the key pairs with specified certificate's subject DN
    
    Parameters:
    
    userDN - - user's certificate's subject DN
  - deleteEntrustKeychain
```
public static boolean deleteEntrustKeychain(java.lang.String keychainName)
```
    delete Entrust Keychain folder from keychain
    
    Parameters:
    
    keychainName - - name of Entrust keychain
    
    Returns:
    
    return true if it is deleted successfully. Otherwise return false. It is also retrun false if Entrust keychain does not exist.
  - getApplicationSupportFolder
```
public static java.lang.String getApplicationSupportFolder()
```
    On the Mac, retrieve application support directory which store persistent user-related files for your application
    
    Returns:
    
    application support directory
  - getApplicationName
```
public static java.lang.String getApplicationName()
```
    retrieve .app bundle name. If the process is not .app, retrieve the process name. If the process name is "java", "Entrust" as application name.
    
    Returns:
    
    .app bundle name
  - getEPFLoginIDWithCertificate
```
public static java.lang.String getEPFLoginIDWithCertificate(X509Certificate certificate)
                                                     throws java.security.NoSuchAlgorithmException,
                                                            java.security.NoSuchProviderException,
                                                            CodingException
```
    Throws:
    
    java.security.NoSuchAlgorithmException
    
    java.security.NoSuchProviderException
    
    CodingException
  - encryptForSmartCardDriver
```
public static byte[] encryptForSmartCardDriver(byte[] publicKeyHash,
                                               byte[] serialNumber,
                                               SecureByteArray securedPlainText)
```
  - getMySmartCardCertificates
```
public static X509Certificate[] getMySmartCardCertificates(java.lang.String tokenID)
```
    Retrieve the smart card certificates from the keychain based on the token ID.
    
    Parameters:
    
    tokenID - - the identifier of the token
    
    Returns:
    
    - a list of smart card certificates
  - isCertMarkedAsTrusted
```
public static boolean isCertMarkedAsTrusted(X509Certificate certificate)
```
    Check to see if the certificate is marked as trusted in the keychain.
    
    Parameters:
    
    certificate - - to be checked if it is marked as trusted in the keychain
    
    Returns:
    
    - The function returns true if the certificate is marked as trusted. Otherwise it returns false.

Class JniKeychain

Method Summary

Methods inherited from class java.lang.Object

Method Detail

initializeKeychain

initializeKeychain

setOmitCertificatePath

setDeleteOmittedCertificates

isKeychainInitialized

hashPublicKey

deleteOmittedCertificates

setKeychainSynchronizationEnabled

isKeychainSynchronizationEnabled

setImportToDefaultKeychain

isImportToDefaultKeychain

addCertificate

addKeyPair

createKeychain

createEntrustKeychainRefUserPrompt

openEntrustKeychainRefUserPrompt

releaseEntrustKeychainRef

lockEntrustKeychain

getMyEncryptionCertificates

getMySigningCertificates

getMyCertificates

enumerateCertificates

enumerateRootCertificates

viewCertificate

buildCertificateChain

buildCertificateChainWithRoots

getPrivateKeyChainKey

getPublicKeyChainKey

releaseKeyChainKey

generateRSAPrivateKeychainKeyRef

exportRSAPublicKeyInfo

importPublicKeyInfo

exportRSAPrivateKeyInfo

createSignature

createRSASignaturePKCS1v15Raw

verifySignature

createEncryptedData

encryptData

createDecryptedData

keyAgree

deleteKeychainKey

deleteUserKeyPairs

deleteEntrustKeychain

getApplicationSupportFolder

getApplicationName

getEPFLoginIDWithCertificate

encryptForSmartCardDriver

getMySmartCardCertificates

isCertMarkedAsTrusted