# Java Security API Overview

Last updated February 12, 1997

## Introduction

> The Java Security API is a new Java core API, built around the `java.security` package (and its subpackages). This first release includes primarily cryptography functionality, which can be incorporated into Java-based applications. Future releases of this API will include more primitives supporting system security and secure distributed computing.

> The cryptography framework in the Java Security API is designed so that a new algorithm can be added later on without much difficulty and can be utilized in the same fashion as existing algorithms. For example, although DSA is the only built-in digital signature algorithm in this release, the framework can easily accommodate another algorithm such as RSA.

> APIs for data encryption and other functionality, together with their implementations, will be released separately in a "Java Cryptography Extension" (JCE) as an add-on package to JDK, in accordance with U.S. export control regulations. Those APIs include block and stream cipher, symmetric and asymmetric encryption, and support for multiple modes of operation and multiple encryption.

> The first release of Java Security, available in JDK 1.1, contains APIs for:

> Digital Signatures
>   Digital signature algorithms, such as DSA. The functionality includes generating public/private key pairs as well as signing and verifying arbitrary digital data.

> Message Digests
>   Cryptographically secure message digests, such as MD5 and SHA-1. These algorithms, also called one-way hash algorithms, are useful for producing "digital fingerprints" of data, which are frequently used in digital signatures and other applications that need unique and unforgeable identifiers for digital data.

> Key Management
>   A set of abstractions for managing principals (entities such as individual users or groups), their keys, and their certificates. It allows applications to design their own key management systems, and to interoperate with other systems at a high level. Note that support for specific certificate formats such as X.509 v3 is not available but will be part of a future JDK release.

> Access Control Lists
>   A set of abstractions for managing principals and their access permissions. A high-level overview is available. This API is not used internally for JDK system security. Also, it will undergo substantial revision and extension in the next release to provide full access control support.

## Architecture and Design

> The Java Security API was designed around these principles:

> - implementation independence and interoperability

> - algorithm independence and extensibility

> Implementation independence and algorithm independence are complementary: their aim is to let users of the API utilize cryptographic concepts, such as digital signatures and message digests, without concern for the implementations or even the algorithms being used to implement these concepts. When complete algorithm-independence is not possible, developers are provided with standardized algorithm-specific APIs. When implementation-independence is not desirable, developers can indicate the specific implementations they require.

> Implementation independence is achieved using a "provider"-based architecture. A Cryptography Package Provider ("provider" for short) is a package or set of packages that implement specific algorithms, such as the Digital Signature Algorithm (DSA) or the RSA Cryptosystem (RSA). Applications may simply request a particular type of object, such as a DSA object, and get an implementation from an installed provider. If desired, an application may instead request an implementation from a specific provider.

> Algorithm independence is achieved by defining types of cryptographic "engines" (algorithms), and defining classes that provide the functionality of these cryptographic engines. These classes are referred to as engine classes, and examples include the MessageDigest and Signature classes.

> Implementation interoperability means that various implementations can work with each other, use each other's keys, or verify each other's signatures. This would mean, for example, that for the same algorithms, a key generated by one provider would be usable by another, and a signature generated by one provider would be verifiable by another.

> Algorithm extensibility means that new algorithms that fit in one of the supported engine classes can be added easily.

## Cryptography Package Providers

> Java Security is essentially an abstract layer, and introduces the notion of a Cryptography Package Provider ("provider" for short). This term refers to a package (or a set of packages) providing a concrete implementation of a subset of the cryptography aspects of the Java Security API. Java users and clients may install specific provider packages according to their taste and preference.

> JDK 1.1 comes standard with a default provider, named "SUN".

> Each JDK installation has one or more provider packages installed. New providers may be added either statically or dynamically:

> - Statically: An authorized administrator or user can add a provider to the persistent list of providers that are available to all programs.

> - Dynamically: An authorized program can add a provider at runtime for its private temporary use.
> Users can call methods to query which providers are installed.

> Providers are packages that implement specific algorithms, such as the Digital Signature Algorithm (DSA), or the RSA Cryptosystem (RSA). Applications may simply request a particular type of object, such as a DSA object, and get an implementation from one of the installed providers. If desired, a client may instead request an implementation from a specific provider.

> When clients configure their system with different providers, they specify a preference order for each. The preference order is the order in which providers are searched for requested algorithms when no specific provider is requested.

> Clients that wish to obtain and utilize algorithm implementations do so by calling Java Security API (`java.security`) methods. They never need to (and in fact should not) directly invoke provider code.

> ### The "SUN" Provider

> In JDK 1.1, there is one default provider, called "SUN". The "SUN" provider package includes:

> - An implementation of the Digital Signature Algorithm (NIST FIPS 186).

> - An implementation of the MD5 (RFC 1321) and SHA-1 (NIST FIPS 180-1) message digest algorithms.

> In the default environment that comes with the JDK, whenever any of these types of algorithms are requested, implementations from the "SUN" provider will be utilized if "SUN" is the requested service provider or if no service provider is explicitly specified. In other words, "SUN" is the highest-priority (default) provider that provides the default implementation. This preference order is configurable.

> The "SUN" provider also supplies a simple system key and trust management mechanism, including a persistent database of principals, keys, and X.509 v1 certificates. The javakey tool interfaces with this persistent database.

## Java Security Documentation

> For further information, see:

> - The Java Cryptography Architecture API Specification and Reference

> - The Reference documentation for the Security API packages:
>   - java.security package
>   - java.security.acl package
>   - java.security.interfaces package

> - A simple step-by-step demo of how you can experiment with code signing, using the JDK 1.1 tools (javakey, jar, and appletviewer). This demo is on our public Web site at http://java.sun.com/security/signExample/

Copyright © 1996, 1997 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All rights reserved.
Please send comments to: java-security@java.sun.com