Previous | Next | Trail Map | Security in JDK 1.2  | Summaries

API Classes and Interfaces

The main JDK 1.2 Security API classes and interfaces are shown below. Each is in the java.security package unless otherwise stated.

Access Control Classes
Permission Classes
Policy
AccessController
AccessControlContext
PrivilegedAction and PrivilegedExceptionAction
CodeSoure
ProtectionDomain
SecureClassLoader

Cryptography Classes
Provider
Signature
MessageDigest
Key Interfaces and Classes
Key Specification Interfaces and Classes
Algorithm Parameter Classes
Algorithm Parameter Specification Interfaces and Classes
Certificate Classes
SecureRandom

Security

SecurityManager

Access Control Classes

Permission Classes

The permission classes represent accesses to system resources. The
    java.security.Permission
class is an abstract class and is subclassed, as appropriate, to represent specific accesses.

Clients can easily define their own new permissions, by subclassing either from the Permission class or one of its subclasses, such as

    java.security.BasicPermission
Subclassed permissions (other than BasicPermission) generally belong to their own packages. Thus, FilePermission is found in the java.io package.

The built-in JDK 1.2 permission types (classes) are

  • java.security.AllPermission
  • ,

  • java.io.FilePermission
  • ,

  • java.net.SocketPermission
  • ,

  • java.net.NetPermission
  • ,

  • java.security.SecurityPermission
  • ,

  • java.lang.RuntimePermission
  • ,

  • java.util.PropertyPermission
  • ,

  • java.awt.AWTPermission
  • ,

  • java.lang.reflect.ReflectPermission
  • , and

  • java.io.SerializablePermission
  • .

Permissions typically have a "name" and sometimes an "action". Classes like FilePermission and SocketPermission that have a more complicated name syntax than that used by BasicPermission subclass directly from Permission rather than from BasicPermission. For example, for a java.io.FilePermission object, the permission name is the pathname of a file (or directory), while the permission name for a BasicPermission is simply the name of the given permission (for example, "exitVM", "setFactory", "queuePrintJob", etc).

Some of the permission classes have an "actions" list that tells the actions that are permitted for the object. For example, for a java.io.FilePermission object, the actions list (such as "read, write") specifies which actions are granted for the specified file (or for files in the specified directory).

Other permission classes are for "named" permissions - ones that contain a name but no actions list; you either have the named permission or you don't. BasicPermission is commonly used as the base class for "named" permissions, since in it, the action string (inherited from Permission) is unused. Subclasses may implement actions on top of BasicPermission, if desired.

Policy

The policy for a Java application environment (specifying which permissions are available for code from various sources) is represented by a Policy object. More specifically, it is represented by a Policy subclass providing an implementation of the abstract methods in the Policy class.

The source location for the policy information utilized by the Policy object is up to the Policy implementation. The default Policy implementation included with the JDK obtains its information from static policy configuration files.

AccessController

The AccessController class is used for three purposes:

  • The checkPermission method decides whether an access to a critical system resource is to be allowed or denied, based on the security policy currently in effect. This is invoked by the SecurityManager checkPermission method.

  • The doPrivileged methods mark code as being privileged, thus affecting subsequent access determinations.

  • The getContext method obtains a "snapshot" of the current calling context so access-control decisions from a different context can be made with respect to the saved context.

AccessControlContext

An AccessControlContext is used to make system resource access decisions based on the context it encapsulates.The purpose of AccessControlContext is for those situations where a security check that should be made within a given context actually needs to be done from within a different context (for example, from within a worker thread).

PrivilegedAction and PrivilegedExceptionAction

PrivilegedAction represents a computation to be performed with privileges enabled. The computation is performed by invoking the AccessController doPrivileged method on the PrivilegedAction object.

The PrivilegedAction interface is used only for computations that do not throw checked exceptions; computations that throw checked exceptions must use PrivilegedExceptionAction instead.

CodeSource

Code being executed is always considered to come from a particular "code source" (represented by an object of type CodeSource). A CodeSource consists of a URL (specifying the location where the code originated from) and a set of certificates containing the public key(s) corresponding to the private key(s) used to sign the code (if the code was signed).

ProtectionDomain

This class encapulates the characteristics of a domain, which encloses a set of classes whose instances are granted the same set of permissions.

In addition to a set of permissions, a domain is comprised of a CodeSource, which is a set of PublicKeys together with a codebase (in the form of a URL). Thus, classes signed by the same keys and from the same URL are placed in the same domain.

SecureClassLoader

This is a concrete implementation of java.lang.Classloader that also handles loading remote classes (e.g., from URL and InputStream). All applets and applications (except for system classes) are loaded by a SecureClassLoader either directly or indirectly.

Cryptography Classes

Provider

The term "Cryptographic Service Provider" ("provider" for short) is used to refer to a package or set of packages that supply a concrete implementation of a subset of the cryptography aspects of the JDK Security API. The Provider class is the interface to such a package or set of packages. It has methods for accessing the provider name, version number, and other information.

There are several types of services that can be implemented by provider packages - see the Engine Classes.

Signature

The Signature class is an engine class designed to provide the functionality of a digital signature algorithm such as DSA or RSA with MD5. A signature algorithm takes arbitrary-sized input and a private key and generates a relatively short (often fixed-size) string of bytes, called the signature, with the following properties:
  • Given the public key corresponding to the private key used to generate the signature, it should be possible to verify the authenticity and integrity of the input.

  • The signature and the public key do not reveal anything about the private key.

A Signature object can be used to generate a digital signature for data. It can also be used to verify whether or not an alleged signature is in fact the authentic signature of the data associated with it.

MessageDigest

The MessageDigest class is an engine class designed to provide the functionality of cryptographically secure message digests such as SHA-1 or MD5. A cryptographically secure message digest takes arbitrary-sized input (a byte array), and generates a fixed-size output, called a digest. A digest has the following properties:

  • It should be computationally infeasible to find another input string that will generate the same digest.

  • The digest does not reveal anything about the input that was used to generate it.

Message digests are used to produce unique and reliable identifiers of data. They are sometimes called the "digital fingerprints" of data.

Key Interfaces and Classes

Key

The Key interface is the top-level interface for all opaque keys. It defines the functionality shared by all opaque key objects.

It gives you limited access to the key - just the three methods defined by the Key interface: getAlgorithm, getFormat, and getEncoded.

Keys are generally obtained through key generators, certificates, key specifications (using a KeyFactory), or a KeyStore implementation accessing a "keystore" database used to manage keys.

It is possible to parse encoded keys, in an algorithm-dependent manner, using a KeyFactory.

PublicKey and PrivateKey

The PublicKey and PrivateKey interfaces (which both extend the Key interface) are method-less interfaces, used for type-safety and type-identification for public keys and private keys.

KeyPair

The KeyPair class is a simple holder for a key pair (a public key and a private key). It has two public methods, one for returning the private key, and the other for returning the public key.

KeyPairGenerator

The KeyPairGenerator class is an engine class used to generate pairs of public and private keys.

KeyFactory

The KeyFactory class is an engine class designed to provide conversions between opaque cryptographic keys (of type Key) and key specifications (transparent representations of the underlying key material).

Key factories are bi-directional, i.e., they allow you to build an opaque key object from a given key specification (key material), or to retrieve the underlying key material of a key object in a suitable format.

KeyStore

A database called a "keystore" can be used to manage a repository of keys and certificates.

The KeyStore class is an engine class that supplies well-defined interfaces to access and modify the information in a keystore. It is possible for there to be multiple different concrete implementations, where each implementation is that for a particular type of keystore.

There is a built-in default implementation, provided by Sun Microsystems. It implements the keystore as a file, utilizing a proprietary keystore type (format) named "JKS". It protects each private key with its individual password, and also protects the integrity of the entire keystore with a (possibly different) password.

Key Specification Interfaces and Classes

Key specifications are transparent representations of the key material that constitutes a key.

A transparent representation of keys means that you can access each key material value individually, through one of the "get" methods defined in the corresponding specification class.

A key may be specified in an algorithm-specific way, or in an algorithm-independent encoding format (such as ASN.1). For example, a DSA private key may be specified by its components x, p, q, and g (see DSAPrivateKeySpec), or it may be specified using its DER encoding (see PKCS8EncodedKeySpec).

The key specification interfaces and classes appear in the java.security.spec package. They are described below.

KeySpec

This interface contains no methods or constants. Its only purpose is to group (and provide type safety for) all key specifications. All key specifications must implement this interface.

DSAPrivateKeySpec

This class (which implements the KeySpec Interface) specifies a DSA private key with its associated parameters.

DSAPublicKeySpec

This class (which implements the KeySpec Interface) specifies a DSA public key with its associated parameters.

RSAPrivateKeySpec

This class (which implements the KeySpec Interface) specifies an RSA private key.

RSAPrivateCrtKeySpec

This class (which extends the RSAPrivateKeySpec class) specifies an RSA private key, as defined in the PKCS#1 standard, using the Chinese Remainder Theorem (CRT) information values.

RSAPublicKeySpec

This class (which implements the KeySpec Interface) specifies an RSA public key.

EncodedKeySpec

This abstract class (which implements the KeySpec Interface) represents a public or private key in encoded format.

PKCS8EncodedKeySpec

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a private key, according to the format specified in the PKCS #8 standard.

X509EncodedKeySpec

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a public or private key, according to the format specified in the X.509 standard.

Algorithm Parameter Classes

AlgorithmParameters

The AlgorithmParameters class is an engine class that provides an opaque representation of cryptographic parameters.

An opaque representation is one in which you have no direct access to the parameter fields; you can only get the name of the algorithm associated with the parameter set and some kind of encoding for the parameter set.

AlgorithmParameterGenerator

The AlgorithmParameterGenerator class is an engine class used to generate a set of parameters to be used with a certain algorithm (the algorithm specified when an AlgorithmParameterGenerator instance is created).

Algorithm Parameter Specification Interfaces and Classes

An algorithm parameter specification is a transparent representation of the sets of parameters used with an algorithm.

A transparent representation of parameters means that you can access each value individually, through one of the "get" methods defined in the corresponding specification class.

The algorithm parameter specification interfaces and classes that appear in the java.security.spec package are described below.

AlgorithmParameterSpec

AlgorithmParameterSpec is an interface to a transparent specification of cryptographic parameters. This interface contains no methods or constants. Its only purpose is to group (and provide type safety for) all parameter specifications. All parameter specifications must implement this interface.

DSAParameterSpec

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters used with the DSA algorithm.

Certificate Classes

Certificate

The java.security.cert.Certificate class is an abstraction for certificates that have different formats but important common uses. For example, different types of certificates, such as X.509 and PGP, share general certificate functionality (like encoding and verifying) and some types of information (like a public key).

CertificateFactory

The java.security.cert.CertificateFactory class is an engine class that defines the functionality of a certificate factory, which is used to generate certificate and certificate revocation list (CRL) objects from their encodings.

X509Certificate

The java.security.cert.X509Certificate class is an abstract class for X.509 certificates. It provides a standard way to access all the attributes of an X.509 certificate.

SecureRandom

The SecureRandom class is an engine class that provides the functionality of a random number generator.

Security

The Security class manages installed providers and security-wide properties. It only contains static methods and is never instantiated.

SecurityManager

java.lang.SecurityManager is a class that allows applications to implement a security policy. It allows an application to determine, before performing a possibly unsafe or sensitive operation, what the operation is, and to decide whether or not to allow execution of the operation.

The SecurityManager class contains many methods with names that begin with the word check. These methods are called by various methods in the runtime libraries before those methods perform certain potentially sensitive operations.

As of JDK 1.2, the default implementation of each of the checkXXX methods is to call the special SecurityManager checkPermission(java.security.Permission perm) method, passing it the permission required in order to perform the requested operation. The checkPermission method then determines whether the access request indicated by the specified permission should be granted or denied by calling

   AccessController.checkPermission(perm);

If a requested access is allowed, checkPermission returns quietly. If denied, a SecurityException is thrown.


Previous | Next | Trail Map | Security in JDK 1.2  | Summaries