FileDocCategorySizeDatePackage
Security.javaAPI DocAndroid 1.5 API23240Wed May 06 22:41:06 BST 2009java.security

Security

public final class Security extends Object
{@code Security} is the central class in the Java Security API. It manages the list of security {@code Provider} that have been installed into this runtime environment.
since
Android 1.0

Fields Summary
private static Properties
secprops
Constructors Summary
private Security()
This class can't be instantiated.


    // static initialization
    // - load security properties files
    // - load statically registered providers
    // - if no provider description file found then load default providers
     
        AccessController.doPrivileged(new java.security.PrivilegedAction<Void>() {
            public Void run() {
                boolean loaded = false;
                
                // BEGIN android-added
                /*
                 * Android only uses a local "security.properties" resource
                 * for configuration. TODO: Reevaluate this decision.
                 */
                try {
                    InputStream configStream =
                        getClass().getResourceAsStream("security.properties"); //$NON-NLS-1$
                    InputStream input =
                        new BufferedInputStream(configStream, 8192);
                    secprops.load(input);
                    loaded = true;
                    configStream.close();
                } catch (Exception ex) {
                    Logger.global.log(Level.SEVERE,
                            "Could not load Security properties.", ex);
                }
                // END android-added

                // BEGIN android-removed
                // File f = new File(System.getProperty("java.home") //$NON-NLS-1$
                //         + File.separator + "lib" + File.separator //$NON-NLS-1$
                //         + "security" + File.separator + "java.security"); //$NON-NLS-1$ //$NON-NLS-2$
                // if (f.exists()) {
                //     try {
                //         FileInputStream fis = new FileInputStream(f);
                //         InputStream is = new BufferedInputStream(fis);
                //         secprops.load(is);
                //         loaded = true;
                //         is.close();
                //     } catch (IOException e) {
                ////         System.err.println("Could not load Security properties file: "
                ////                         + e);
                //     }
                // }
                //
                // if ("true".equalsIgnoreCase(secprops.getProperty("security.allowCustomPropertiesFile", "true"))) { //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
                //     String securityFile = System.getProperty("java.security.properties"); //$NON-NLS-1$
                //     if (securityFile != null) {
                //         if (securityFile.startsWith("=")) { // overwrite //$NON-NLS-1$
                //            secprops = new Properties();
                //            loaded = false;
                //            securityFile = securityFile.substring(1);
                //         }
                //         try {
                //             securityFile = PolicyUtils.expand(securityFile, System.getProperties());
                //         } catch (PolicyUtils.ExpansionFailedException e) {
                ////            System.err.println("Could not load custom Security properties file "
                ////                     + securityFile +": " + e);
                //         }
                //         f = new File(securityFile);
                //         InputStream is;
                //         try {
                //             if (f.exists()) {
                //                 FileInputStream fis = new FileInputStream(f);
                //                 is = new BufferedInputStream(fis);
                //             } else {
                //                 URL url = new URL(securityFile);
                //                 is = new BufferedInputStream(url.openStream());
                //             }
                //             secprops.load(is);
                //             loaded = true;
                //             is.close();
                //         } catch (IOException e) {
                // //             System.err.println("Could not load custom Security properties file "
                // //                    + securityFile +": " + e);
                //         }
                //     }
                // }
                // END android-removed

                if (!loaded) {
                    registerDefaultProviders();
                }
                Engine.door = new SecurityDoor();
                return null;
            }
        });
    
    
Methods Summary
public static intaddProvider(java.security.Provider provider)
Adds the given {@code provider} to the collection of providers at the next available position.

If a {@code SecurityManager} is installed, code calling this method needs the {@code SecurityPermission} {@code insertProvider.NAME} (where NAME is the provider name) to be granted, otherwise a {@code SecurityException} will be thrown.

param
provider the provider to be added.
return
the actual position or {@code -1} if the given {@code provider} was already in the list.
throws
SecurityException if a {@code SecurityManager} is installed and the caller does not have permission to invoke this method.
since
Android 1.0

        return insertProviderAt(provider, 0);
    
public static java.lang.StringgetAlgorithmProperty(java.lang.String algName, java.lang.String propName)
Returns value for the specified algorithm with the specified name.

param
algName the name of the algorithm.
param
propName the name of the property.
return
value of the property.
deprecated
Use {@link AlgorithmParameters} and {@link KeyFactory} instead.
since
Android 1.0

        if (algName == null || propName == null) {
            return null;
        }
        // BEGIN android-changed
        String prop = "Alg." + propName + "." + algName; //$NON-NLS-1$
        // END android-changed
        Provider[] providers = getProviders();
        for (int i = 0; i < providers.length; i++) {
            for (Enumeration e = providers[i].propertyNames(); e
                    .hasMoreElements();) {
                String pname = (String) e.nextElement();
                if (prop.equalsIgnoreCase(pname)) {
                    return providers[i].getProperty(pname);
                }
            }
        }
        return null;
    
public static java.util.SetgetAlgorithms(java.lang.String serviceName)
Returns a {@code Set} of all registered algorithms for the specified cryptographic service. {@code "Signature"}, {@code "Cipher"} and {@code "KeyStore"} are examples for such kind of services.

param
serviceName the case-insensitive name of the service.
return
a {@code Set} of all registered algorithms for the specified cryptographic service, or an empty {@code Set} if {@code serviceName} is {@code null} or if no registered provider provides the requested service.
since
Android 1.0

        Set<String> result = new HashSet<String>();
        Provider[] p = getProviders();
        for (int i = 0; i < p.length; i++) {
            for (Iterator it = p[i].getServices().iterator(); it.hasNext();) {
                Provider.Service s = (Provider.Service) it.next();
                if (s.getType().equalsIgnoreCase(serviceName)) {
                    result.add(s.getAlgorithm());
                }
            }
        }
        return result;
    
public static java.lang.StringgetProperty(java.lang.String key)
Returns the value of the security property named by the argument.

If a {@code SecurityManager} is installed, code calling this method needs the {@code SecurityPermission} {@code getProperty.KEY} (where KEY is the specified {@code key}) to be granted, otherwise a {@code SecurityException} will be thrown.

param
key the name of the requested security property.
return
the value of the security property.
throws
SecurityException if a {@code SecurityManager} is installed and the caller does not have permission to invoke this method.
since
Android 1.0

        if (key == null) {
            throw new NullPointerException(Messages.getString("security.2C")); //$NON-NLS-1$
        }
        SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            sm.checkSecurityAccess("getProperty." + key); //$NON-NLS-1$
        }
        return secprops.getProperty(key);
    
public static synchronized java.security.ProvidergetProvider(java.lang.String name)
Returns the {@code Provider} with the specified name. Returns {@code null} if name is {@code null} or no provider with the specified name is installed.

param
name the name of the requested provider.
return
the provider with the specified name, maybe {@code null}.
since
Android 1.0

        return Services.getProvider(name);
    
public static synchronized java.security.Provider[]getProviders(java.util.Map filter)
Returns the array of providers which meet the user supplied set of filters. The filter must be supplied in one of two formats:
  • CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE

    for example: "MessageDigest.SHA" The value associated with the key must be an empty string.

  • CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE ATTR_NAME:ATTR_VALUE

    for example: "Signature.MD2withRSA KeySize:512" where "KeySize:512" is the value of the filter map entry.

    param
    filter case-insensitive filter.
    return
    the providers which meet the user supplied string filter {@code filter}. A {@code null} value signifies that none of the installed providers meets the filter specification.
    throws
    InvalidParameterException if an unusable filter is supplied.
    throws
    NullPointerException if {@code filter} is {@code null}.
    since
    Android 1.0

            if (filter == null) {
                throw new NullPointerException(Messages.getString("security.2A")); //$NON-NLS-1$
            }
            if (filter.isEmpty()) {
                return null;
            }
            java.util.List<Provider> result = Services.getProvidersList();
            Set keys = filter.entrySet();
            Map.Entry entry;
            for (Iterator it = keys.iterator(); it.hasNext();) {
                entry = (Map.Entry) it.next();
                String key = (String) entry.getKey();
                String val = (String) entry.getValue();
                String attribute = null;
                int i = key.indexOf(" "); //$NON-NLS-1$
                int j = key.indexOf("."); //$NON-NLS-1$
                if (j == -1) {
                    throw new InvalidParameterException(
                            Messages.getString("security.2B")); //$NON-NLS-1$
                }
                if (i == -1) { // <crypto_service>.<algorithm_or_type>
                    if (val.length() != 0) {
                        throw new InvalidParameterException(
                                Messages.getString("security.2B")); //$NON-NLS-1$
                    }
                } else { // <crypto_service>.<algorithm_or_type> <attribute_name>
                    if (val.length() == 0) {
                        throw new InvalidParameterException(
                                Messages.getString("security.2B")); //$NON-NLS-1$
                    }
                    attribute = key.substring(i + 1);
                    if (attribute.trim().length() == 0) {
                        throw new InvalidParameterException(
                                Messages.getString("security.2B")); //$NON-NLS-1$
                    }
                    key = key.substring(0, i);
                }
                String serv = key.substring(0, j);
                String alg = key.substring(j + 1);
                if (serv.length() == 0 || alg.length() == 0) {
                    throw new InvalidParameterException(
                            Messages.getString("security.2B")); //$NON-NLS-1$
                }
                Provider p;
                for (int k = 0; k < result.size(); k++) {
                    try {
                        p = (Provider) result.get(k);
                    } catch (IndexOutOfBoundsException e) {
                        break;
                    }
                    if (!p.implementsAlg(serv, alg, attribute, val)) {
                        result.remove(p);
                        k--;
                    }
                }
            }
            if (result.size() > 0) {
                return result.toArray(new Provider[result.size()]);
            } else {
                return null;
            }
        
  • public static synchronized java.security.Provider[]getProviders()
    Returns an array containing all installed providers. The providers are ordered according their preference order.

    return
    an array containing all installed providers.
    since
    Android 1.0

            return Services.getProviders();
        
    public static java.security.Provider[]getProviders(java.lang.String filter)
    Returns the array of providers which meet the user supplied string filter. The specified filter must be supplied in one of two formats:
  • CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE

    (for example: "MessageDigest.SHA")

  • CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE ATTR_NAME:ATTR_VALUE

    (for example: "Signature.MD2withRSA KeySize:512")

    param
    filter case-insensitive filter.
    return
    the providers which meet the user supplied string filter {@code filter}. A {@code null} value signifies that none of the installed providers meets the filter specification.
    throws
    InvalidParameterException if an unusable filter is supplied.
    throws
    NullPointerException if {@code filter} is {@code null}.
    since
    Android 1.0

            if (filter == null) {
                throw new NullPointerException(Messages.getString("security.2A")); //$NON-NLS-1$
            }
            if (filter.length() == 0) {
                throw new InvalidParameterException(
                        Messages.getString("security.2B")); //$NON-NLS-1$
            }
            HashMap<String, String> hm = new HashMap<String, String>();
            int i = filter.indexOf(":"); //$NON-NLS-1$
            if ((i == filter.length() - 1) || (i == 0)) {
                throw new InvalidParameterException(
                        Messages.getString("security.2B")); //$NON-NLS-1$
            }
            if (i < 1) {
                hm.put(filter, ""); //$NON-NLS-1$
            } else {
                hm.put(filter.substring(0, i), filter.substring(i + 1));
            }
            return getProviders(hm);
        
  • public static synchronized intinsertProviderAt(java.security.Provider provider, int position)
    Insert the given {@code Provider} at the specified {@code position}. The positions define the preference order in which providers are searched for requested algorithms.

    If a {@code SecurityManager} is installed, code calling this method needs the {@code SecurityPermission} {@code insertProvider.NAME} (where NAME is the provider name) to be granted, otherwise a {@code SecurityException} will be thrown.

    param
    provider the provider to insert.
    param
    position the position (starting from 1).
    return
    the actual position or {@code -1} if the given {@code provider} was already in the list. The actual position may be different from the desired position.
    throws
    SecurityException if a {@code SecurityManager} is installed and the caller does not have permission to invoke this method.
    since
    Android 1.0

            // check security access; check that provider is not already
            // installed, else return -1; if (position <1) or (position > max
            // position) position = max position + 1; insert provider, shift up
            // one position for next providers; Note: The position is 1-based
            SecurityManager sm = System.getSecurityManager();
            if (sm != null) {
                sm.checkSecurityAccess("insertProvider." + provider.getName()); //$NON-NLS-1$
            }
            if (getProvider(provider.getName()) != null) {
                return -1;
            }
            int result = Services.insertProviderAt(provider, position);
            renumProviders();
            return result;
        
    private static voidregisterDefaultProviders()

            secprops.put("security.provider.1", "org.apache.harmony.security.provider.cert.DRLCertFactory");  //$NON-NLS-1$ //$NON-NLS-2$
            secprops.put("security.provider.2", "org.apache.harmony.security.provider.crypto.CryptoProvider");  //$NON-NLS-1$ //$NON-NLS-2$
            secprops.put("security.provider.3", "org.apache.harmony.xnet.provider.jsse.JSSEProvider");  //$NON-NLS-1$ //$NON-NLS-2$
            secprops.put("security.provider.4", "org.bouncycastle.jce.provider.BouncyCastleProvider");  //$NON-NLS-1$ //$NON-NLS-2$
        
    public static synchronized voidremoveProvider(java.lang.String name)
    Removes the {@code Provider} with the specified name form the collection of providers. If the the {@code Provider} with the specified name is removed, all provider at a greater position are shifted down one position.

    Returns silently if {@code name} is {@code null} or no provider with the specified name is installed.

    If a {@code SecurityManager} is installed, code calling this method needs the {@code SecurityPermission} {@code removeProvider.NAME} (where NAME is the provider name) to be granted, otherwise a {@code SecurityException} will be thrown.

    param
    name the name of the provider to remove.
    throws
    SecurityException if a {@code SecurityManager} is installed and the caller does not have permission to invoke this method.
    since
    Android 1.0

            // It is not clear from spec.:
            // 1. if name is null, should we checkSecurityAccess or not? 
            //    throw SecurityException or not?
            // 2. as 1 but provider is not installed
            // 3. behavior if name is empty string?
    
            Provider p;
            if ((name == null) || (name.length() == 0)) {
                return;
            }
            p = getProvider(name);
            if (p == null) {
                return;
            }
            SecurityManager sm = System.getSecurityManager();
            if (sm != null) {
                sm.checkSecurityAccess("removeProvider." + name); //$NON-NLS-1$
            }
            Services.removeProvider(p.getProviderNumber());
            renumProviders();
            p.setProviderNumber(-1);
        
    private static voidrenumProviders()
    Update sequence numbers of all providers.

            Provider[] p = Services.getProviders();
            for (int i = 0; i < p.length; i++) {
                p[i].setProviderNumber(i + 1);
            }
        
    public static voidsetProperty(java.lang.String key, java.lang.String datnum)
    Sets the value of the specified security property.

    If a {@code SecurityManager} is installed, code calling this method needs the {@code SecurityPermission} {@code setProperty.KEY} (where KEY is the specified {@code key}) to be granted, otherwise a {@code SecurityException} will be thrown.

    param
    key the name of the security property.
    param
    datnum the value of the security property.
    throws
    SecurityException if a {@code SecurityManager} is installed and the caller does not have permission to invoke this method.
    since
    Android 1.0

            SecurityManager sm = System.getSecurityManager();
            if (sm != null) {
                sm.checkSecurityAccess("setProperty." + key); //$NON-NLS-1$
            }
            secprops.put(key, datnum);