• Java Software
• Java SE Downloads
• Java SE 8 Documentation

Search

1 Introduction

The Java™ platform was designed with a strong emphasis onsecurity. At its core, the Java language itself is type-safe andprovides automatic garbage collection, enhancing the robustness ofapplication code. A secure class loading and verification mechanismensures that only legitimate Java code is executed.

The initial version of the Java platform created a safeenvironment for running potentially untrusted code, such as Javaapplets downloaded from a public network. As the platform has grownand widened its range of deployment, the Java security architecturehas correspondingly evolved to support an increasing set ofservices. Today the architecture includes a large set ofapplication programming interfaces (APIs), tools, andimplementations of commonly-used security algorithms, mechanisms,and protocols. This provides the developer a comprehensive securityframework for writing applications, and also provides the user oradministrator a set of tools to securely manage applications.

The Java security APIs span a wide range of areas. Cryptographicand public key infrastructure (PKI) interfaces provide theunderlying basis for developing secure applications. Interfaces forperforming authentication and access control enable applications toguard against unauthorized access to protected resources.

The APIs allow for multiple interoperable implementations ofalgorithms and other security services. Services are implemented inproviders, which are plugged into the Java platform via astandard interface that makes it easy for applications to obtainsecurity services without having to know anything about theirimplementations. This allows developers to focus on how tointegrate security into their applications, rather than on how toactually implement complex security mechanisms.

The Java platform includes a number of providers that implementa core set of security services. It also allows for additionalcustom providers to be installed. This enables developers to extendthe platform with new security mechanisms.

This paper gives a broad overview of security in the Javaplatform, from secure language features to the security APIs,tools, and built-in provider services, highlighting key packagesand classes where applicable. Note that this paper is based onJava™ SE version 8.

2 Java Language Security and Bytecode Verification

The Java language is designed to be type-safe and easy to use.It provides automatic memory management, garbage collection, andrange-checking on arrays. This reduces the overall programmingburden placed on developers, leading to fewer subtle programmingerrors and to safer, more robust code.

In addition, the Java language defines different accessmodifiers that can be assigned to Java classes, methods, andfields, enabling developers to restrict access to their classimplementations as appropriate. Specifically, the language definesfour distinct access levels:private,protected,public, and, if unspecified,package. The most open access specifier ispublic access is allowed to anyone. The mostrestrictive modifier isprivate access is not allowedoutside the particular class in which the private member (a method,for example) is defined. Theprotected modifier allowsaccess to any subclass, or to other classes within the samepackage. Package-level access only allows access to classes withinthe same package.

A compiler translates Java programs into a machine-independentbytecode representation. A bytecode verifier is invoked to ensurethat only legitimate bytecodes are executed in the Java runtime. Itchecks that the bytecodes conform to the Java LanguageSpecification and do not violate Java language rules or namespacerestrictions. The verifier also checks for memory managementviolations, stack underflows or overflows, and illegal datatypecasts. Once bytecodes have been verified, the Java runtimeprepares them for execution.

3 Basic Security Architecture

The Java platform defines a set of APIs spanning major securityareas, including cryptography, public key infrastructure,authentication, secure communication, and access control. TheseAPIs allow developers to easily integrate security into theirapplication code. They were designed around the followingprinciples:

Implementation independence

Applications do not need to implement security themselves.Rather, they can request security services from the Java platform.Security services are implemented in providers (see below), whichare plugged into the Java platform via a standard interface. Anapplication may rely on multiple independent providers for securityfunctionality.

Implementation interoperability

Providers are interoperable across applications. Specifically,an application is not bound to a specific provider, and a provideris not bound to a specific application.

Algorithm extensibility

The Java platform includes a number of built-in providers thatimplement a basic set of security services that are widely usedtoday. However, some applications may rely on emerging standardsnot yet implemented, or on proprietary services. The Java platformsupports the installation of custom providers that implement suchservices.

Security Providers

Thejava.security.Provider class encapsulates thenotion of a security provider in the Java platform. It specifiesthe provider's name and lists the security services it implements.Multiple providers may be configured at the same time, and arelisted in order of preference. When a security service isrequested, the highest priority provider that implements thatservice is selected.

Applications rely on the relevantgetInstancemethod to obtain a security service from an underlying provider.For example, message digest creation represents one type of serviceavailable from providers. (Section 4 discusses message digests andother cryptographic services.) An application invokes thegetInstance method in thejava.security.MessageDigest class to obtain animplementation of a specific message digest algorithm, such asSHA-256.

MessageDigest md = MessageDigest.getInstance("SHA-256");

The program may optionally request an implementation from aspecific provider, by indicating the provider name, as in thefollowing:

MessageDigest md =     MessageDigest.getInstance("SHA-256", "ProviderC");

Figures 1 and 2 illustrate these options for requesting anSHA-256 message digest implementation. Both figures show threeproviders that implement message digest algorithms. The providersare ordered by preference from left to right (1-3). In Figure 1, anapplication requests an SHA-256 algorithm implementation withoutspecifying a provider name. The providers are searched inpreference order and the implementation from the first providersupplying that particular algorithm, ProviderB, is returned. InFigure 2, the application requests the SHA-256 algorithmimplementation from a specific provider, ProviderC. This time theimplementation from that provider is returned, even though aprovider with a higher preference order, ProviderB, also suppliesan SHA-256 implementation.

Figure 1 Provider searching	Figure 2 Specific providerrequested

The Java platform implementation from Oracle includes a numberof pre-configured default providers that implement a basic set ofsecurity services that can be used by applications. Note that othervendor implementations of the Java platform may include differentsets of providers that encapsulate vendor-specific sets of securityservices. When this paper mentions built-in default providers, itis referencing those available in Oracle's implementation.

The sections below on the various security areas (cryptography,authentication, etc.) each include descriptions of the relevantservices supplied by the default providers. A table in Appendix Csummarizes all of the default providers.

File Locations

Certain aspects of Java security mentioned in this paper,including the configuration of providers, may be customized bysetting security properties. You may set security propertiesstatically in the security properties file, which by default is thejava.security file in thelib/security directory ofthe directory where the Java™ Runtime Environment (JRE) isinstalled. Security properties may also be set dynamically bycalling appropriate methods of theSecurity class (inthejava.security package).

Note: Properties in thejava.securityfile are typically parsed only once. If you have modified any property in thisfile, restart your applications to ensure that the changes are properlyreflected.

The tools and commands mentioned in this paper are all in the<jre>/bin directory, where<jre> stands for the directory in which the JRE isinstalled. Thecacerts file mentioned in Section 5 is in<jre>/lib/security.

4 Cryptography

The Java cryptography architecture is a framework for accessingand developing cryptographic functionality for the Java platform.It includes APIs for a large variety of cryptographic services,including

• Message digest algorithms
• Digital signature algorithms
• Symmetric bulk encryption
• Symmetric stream encryption
• Asymmetric encryption
• Password-based encryption (PBE)
• Elliptic Curve Cryptography (ECC)
• Key agreement algorithms
• Key generators
• Message Authentication Codes (MACs)
• (Pseudo-)random number generators

For historical (export control) reasons, the cryptography APIsare organized into two distinct packages. Thejava.security package contains classes that arenot subject to export controls (likeSignatureandMessageDigest). Thejavax.cryptopackage contains classes that are subject to export controls (likeCipher andKeyAgreement).

The cryptographic interfaces are provider-based, allowing formultiple and interoperable cryptography implementations. Someproviders may perform cryptographic operations in software; othersmay perform the operations on a hardware token (for example, on asmartcard device or on a hardware cryptographic accelerator).Providers that implement export-controlled services must bedigitally signed.

The Java platform includes built-in providers for many of the most commonly usedcryptographic algorithms, including the RSA, DSA, and ECDSA signaturealgorithms, the AES encryption algorithm, the SHA-2 message digest algorithms,and the Diffie-Hellman (DH) and Elliptic Curve Diffie-Hellman (ECDH) keyagreement algorithms. Most of the built-in providers implement cryptographicalgorithms in Java code.

The Java platform also includes a built-in provider that acts asa bridge to a native PKCS#11 (v2.x) token. This provider, namedSunPKCS11, allows Java applications to seamlesslyaccess cryptographic services located on PKCS#11-complianttokens.

On Windows, the Java platform includes a built-in provider thatacts as a bridge to the native Microsoft CryptoAPI. This provider,named SunMSCAPI, allows Java applications to seamlessly accesscryptographic services on Windows through the CryptoAPI.

5 Public Key Infrastructure

Public Key Infrastructure (PKI) is a term used for a frameworkthat enables secure exchange of information based on public keycryptography. It allows identities (of people, organizations, etc.)to be bound to digital certificates and provides a means ofverifying the authenticity of certificates. PKI encompasses keys,certificates, public key encryption, and trusted CertificationAuthorities (CAs) who generate and digitally sign certificates.

The Java platform includes APIs and provider support for X.509digital certificates and Certificate Revocation Lists (CRLs), aswell as PKIX-compliant certification path building and validation.The classes related to PKI are located in thejava.security andjava.security.certpackages.

Key and Certificate Storage

The Java platform provides for long-term persistent storage ofcryptographic keys and certificates via key and certificate stores.Specifically, thejava.security.KeyStore classrepresents akey store, a secure repository of cryptographickeys and/or trusted certificates (to be used, for example, duringcertification path validation), and thejava.security.cert.CertStore class represents acertificate store, a public and potentially vast repositoryof unrelated and typically untrusted certificates. ACertStore may also store CRLs.

KeyStore andCertStore implementationsare distinguished by types. The Java platform includes the standardPKCS11 andPKCS12 key store types (whoseimplementations are compliant with the corresponding PKCSspecifications from RSA Security). It also contains a proprietaryfile-based key store type calledJKS (which stands for "JavaKey Store"), and a type called DKS ("Domain Key Store") which is acollection of keystores that are presented as a single logicalkeystore.

The Java platform includes a special built-in JKS key store,cacerts, that contains a number of certificates forwell-known, trusted CAs. The keytool utility is able to list thecertificates included incacerts (see the security featuresdocumentation link in Section 10).

The SunPKCS11 provider mentioned in the "Cryptography" section(Section 4) includes aPKCS11KeyStoreimplementation. This means that keys and certificates residing insecure hardware (such as a smartcard) can be accessed and used byJava applications via theKeyStore API. Note thatsmartcard keys may not be permitted to leave the device. In suchcases, thejava.security.Key object reference returnedby theKeyStore API may simply be a reference to thekey (that is, it would not contain the actual key material). Such aKey object can only be used to perform cryptographicoperations on the device where the actual key resides.

The Java platform also includes anLDAP certificate storetype (for accessing certificates stored in an LDAP directory), aswell as an in-memoryCollection certificate store type (foraccessing certificates managed in ajava.util.Collection object).

PKI Tools

There are two built-in tools for working with keys,certificates, and key stores:

keytool is used to create and manage key stores. Itcan

• Create public/private key pairs
• Display, import, and export X.509 v1, v2, and v3 certificatesstored as files
• Create self-signed certificates
• Issue certificate (PKCS#10) requests to be sent to CAs
• Create certificates based on certificate requests
• Import certificate replies (obtained from the CAs sentcertificate requests)
• Designate public key certificates as trusted
• Accept a password and store it securely as a secret key

Thejarsigner tool is used to sign JAR files, or toverify signatures on signed JAR files. The Java ARchive (JAR) fileformat enables the bundling of multiple files into a single file.Typically a JAR file contains the class files and auxiliaryresources associated with applets and applications. When you wantto digitally sign code, you first use keytool to generate or importappropriate keys and certificates into your key store (if they arenot there already), then use thejar tool to place the codein a JAR file, and finally use the jarsigner tool to sign the JARfile. The jarsigner tool accesses a key store to find any keys andcertificates needed to sign a JAR file or to verify the signatureof a signed JAR file. Note:jarsigner can optionallygenerate signatures that include a timestamp. Systems (such as JavaPlug-in) that verify JAR file signatures can check the timestampand accept a JAR file that was signed while the signing certificatewas valid rather than requiring the certificate to be current.(Certificates typically expire annually, and it is not reasonableto expect JAR file creators to re-sign deployed JAR filesannually.)

6 Authentication

Authentication is the process of determining the identity of auser. In the context of the Java runtime environment, it is theprocess of identifying the user of an executing Java program. Incertain cases, this process may rely on the services described inthe "Cryptography" section (Section 4).

The Java platform provides APIs that enable an application toperform user authentication via pluggable login modules.Applications call into theLoginContext class (in thejavax.security.auth.login package), which in turnreferences a configuration. The configuration specifies which loginmodule (an implementation of thejavax.security.auth.spi.LoginModule interface) is tobe used to perform the actual authentication.

Since applications solely talk to the standardLoginContext API, they can remain independent from theunderlying plug-in modules. New or updated modules can be pluggedin for an application without having to modify the applicationitself. Figure 3 illustrates the independence between applicationsand underlying login modules:

Figure 3 Authentication loginmodules plugging into the authentication framework

It is important to note that although login modules arepluggable components that can be configured into the Java platform,they are not plugged in via security Providers. Therefore, they donot follow the Provider searching model described in Section 3.Instead, as is shown in the above diagram, login modules areadministered by their own unique configuration.

The Java platform provides the following built-in LoginModules,all in thecom.sun.security.auth.module package:

• Krb5LoginModule for authentication using Kerberosprotocols
• JndiLoginModule for user name/passwordauthentication using LDAP or NIS databases
• KeyStoreLoginModule for logging into any type ofkey store, including a PKCS#11 token key store

Authentication can also be achieved during the process ofestablishing a secure communication channel between two peers. TheJava platform provides implementations of a number of standardcommunication protocols, which are discussed in the followingsection.

7 Secure Communication

The data that travels across a network can be accessed bysomeone who is not the intended recipient. When the data includesprivate information, such as passwords and credit card numbers,steps must be taken to make the data unintelligible to unauthorizedparties. It is also important to ensure that you are sending thedata to the appropriate party, and that the data has not beenmodified, either intentionally or unintentionally, duringtransport.

Cryptography forms the basis required for secure communication,and that is described in Section 4. The Java platform also providesAPI support and provider implementations for a number of standardsecure communication protocols.

SSL/TLS

The Java platform provides APIs and an implementation of the SSLand TLS protocols that includes functionality for data encryption,message integrity, server authentication, and optional clientauthentication. Applications can use SSL/TLS to provide for thesecure passage of data between two peers over any applicationprotocol, such as HTTP on top of TCP/IP.

Thejavax.net.ssl.SSLSocket class represents anetwork socket that encapsulates SSL/TLS support on top of a normalstream socket (java.net.Socket). Some applicationsmight want to use alternate data transport abstractions (e.g.,New-I/O); thejavax.net.ssl.SSLEngine class isavailable to produce and consume SSL/TLS packets.

The Java platform also includes APIs that support the notion ofpluggable (provider-based) key managers and trust managers.Akey manager is encapsulated by thejavax.net.ssl.KeyManager class, and manages the keysused to perform authentication. Atrust manager isencapsulated by theTrustManager class (in the samepackage), and makes decisions about who to trust based oncertificates in the key store it manages.

The Java platform includes a built-in provider that implementsthe SSL/TLS protocols:

• SSLv3
• TLSv1
• TLSv1.1
• TLSv1.2

SASL

Simple Authentication and Security Layer (SASL) is an Internetstandard that specifies a protocol for authentication and optionalestablishment of a security layer between client and serverapplications. SASL defines how authentication data is to beexchanged, but does not itself specify the contents of that data.It is a framework into which specific authentication mechanismsthat specify the contents and semantics of the authentication datacan fit. There are a number of standard SASL mechanisms defined bythe Internet community for various security levels and deploymentscenarios.

The Java SASL API defines classes and interfaces forapplications that use SASL mechanisms. It is defined to bemechanism-neutral; an application that uses the API need not behardwired into using any particular SASL mechanism. Applicationscan select the mechanism to use based on desired security features.The API supports both client and server applications. Thejavax.security.sasl.Sasl class is used to createSaslClient andSaslServer objects.

SASL mechanism implementations are supplied in providerpackages. Each provider may support one or more SASL mechanisms andis registered and invoked via the standard providerarchitecture.

The Java platform includes a built-in provider that implementsthe following SASL mechanisms:

• CRAM-MD5, DIGEST-MD5, EXTERNAL, GSSAPI, NTLM, and PLAIN clientmechanisms
• CRAM-MD5, DIGEST-MD5, GSSAPI, and NTLM server mechanisms

GSS-API and Kerberos

The Java platform contains an API with the Java languagebindings for the Generic Security Service Application ProgrammingInterface (GSS-API). GSS-API offers application programmers uniformaccess to security services atop a variety of underlying securitymechanisms. The Java GSS-API currently requires use of a Kerberosv5 mechanism, and the Java platform includes a built-inimplementation of this mechanism. At this time, it is not possibleto plug in additional mechanisms. Note: TheKrb5LoginModule mentioned in Section 6 can be used inconjunction with the GSS Kerberos mechanism.

The Java platform also includes a built-in implementation of theSimple and Protected GSSAPI Negotiation Mechanism (SPNEGO) GSS-APImechanism.

Before two applications can use the Java GSS-API to securelyexchange messages between them, they must establish a jointsecurity context. The context encapsulates shared state informationthat might include, for example, cryptographic keys. Bothapplications create and use anorg.ietf.jgss.GSSContext object to establish andmaintain the shared information that makes up the security context.Once a security context has been established, it can be used toprepare secure messages for exchange.

The Java GSS APIs are in theorg.ietf.jgss package.The Java platform also defines basic Kerberos classes, likeKerberosPrincipal,KerberosTicket,KerberosKey, andKeyTab, which arelocated in thejavax.security.auth.kerberospackage.

8 Access Control

The access control architecture in the Java platform protectsaccess to sensitive resources (for example, local files) orsensitive application code (for example, methods in a class). Allaccess control decisions are mediated by a security manager,represented by thejava.lang.SecurityManager class. ASecurityManager must be installed into the Javaruntime in order to activate the access control checks.

Java applets and Java™ Web Start applications areautomatically run with aSecurityManager installed.However, local applications executed via thejava commandare by default not run with aSecurityManagerinstalled. In order to run local applications with aSecurityManager, either the application itself mustprogrammatically set one via thesetSecurityManagermethod (in thejava.lang.System class), orjavamust be invoked with a-Djava.security.managerargument on the command line.

Permissions

When Java code is loaded by a class loader into the Javaruntime, the class loader automatically associates the followinginformation with that code:

• Where the code was loaded from
• Who signed the code (if anyone)
• Default permissions granted to the code

This information is associated with the code regardless ofwhether the code is downloaded over an untrusted network (e.g., anapplet) or loaded from the file system (e.g., a local application).The location from which the code was loaded is represented by aURL, the code signer is represented by the signer's certificatechain, and default permissions are represented byjava.security.Permission objects.

The default permissions automatically granted to downloaded codeinclude the ability to make network connections back to the hostfrom which it originated. The default permissions automaticallygranted to code loaded from the local file system include theability to read files from the directory it came from, and alsofrom subdirectories of that directory.

Note that the identity of the user executing the code is notavailable at class loading time. It is the responsibility ofapplication code to authenticate the end user if necessary (forexample, as described in Section 6). Once the user has beenauthenticated, the application can dynamically associate that userwith executing code by invoking thedoAs method in thejavax.security.auth.Subject class.

Policy

As mentioned earlier, a limited set of default permissions aregranted to code by class loaders. Administrators have the abilityto flexibly manage additional code permissions via a securitypolicy.

The Java platform encapsulates the notion of a security policyin thejava.security.Policy class. There is only onePolicy object installed into the Java runtime at anygiven time. The basic responsibility of thePolicyobject is to determine whether access to a protected resource ispermitted to code (characterized by where it was loaded from, whosigned it, and who is executing it). How aPolicyobject makes this determination is implementation-dependent. Forexample, it may consult a database containing authorization data,or it may contact another service.

The Java platform includes a defaultPolicyimplementation that reads its authorization data from one or moreASCII (UTF-8) files configured in the security properties file.These policy files contain the exact sets of permissions granted tocode: specifically, the exact sets of permissions granted to codeloaded from particular locations, signed by particular entities,and executing as particular users. The policy entries in each filemust conform to a documented proprietary syntax, and may becomposed via a simple text editor or the graphicalpolicytool utility.

Access Control Enforcement

The Java runtime keeps track of the sequence of Java calls thatare made as a program executes. When access to a protected resourceis requested, the entire call stack, by default, is evaluated todetermine whether the requested access is permitted.

As mentioned earlier, resources are protected by theSecurityManager. Security-sensitive code in the Javaplatform and in applications protects access to resources via codelike the following:

SecurityManager sm = System.getSecurityManager();if (sm != null) {   sm.checkPermission(perm);}

where perm is the Permission object that corresponds to therequested access. For example, if an attempt is made to read thefile/tmp/abc, the permission may be constructed asfollows:

Permission perm =     new java.io.FilePermission("/tmp/abc", "read");

The default implementation ofSecurityManagerdelegates its decision to thejava.security.AccessController implementation. TheAccessController traverses the call stack, passing tothe installed securityPolicy each code element in thestack, along with the requested permission (for example, theFilePermission in the above example). ThePolicy determines whether the requested access isgranted, based on the permissions configured by the administrator.If access is not granted, theAccessController throwsajava.lang.SecurityException.

Figure 4 illustrates access control enforcement. In thisparticular example, there are initially two elements on the callstack, ClassA and ClassB. ClassA invokes a method in ClassB, whichthen attempts to access the file/tmp/abc by creating aninstance ofjava.io.FileInputStream. TheFileInputStream constructor creates aFilePermission,perm, as shown above, andthen passesperm to theSecurityManager'scheckPermission method. In this particular case, onlythe permissions for ClassA and ClassB need to be checked, becauseall system code, includingFileInputStream,SecurityManager, andAccessController,automatically receives all permissions.

In this example, ClassA and ClassB have different codecharacteristics – they come from different locations and havedifferent signers. Each may have been granted a different set ofpermissions. TheAccessController only grants accessto the requested file if thePolicy indicates thatboth classes have been granted the requiredFilePermission.

Figure 4 Controlling access toresources

9 XML Signature

The Java XML Digital Signature API is a standard Java API forgenerating and validating XML Signatures.

XML Signatures can be applied to data of any type, XML or binary(seehttp://www.w3.org/TR/xmldsig-core/).The resulting signature is represented in XML. An XML Signature canbe used to secure your data and provide data integrity, messageauthentication, and signer authentication.

The API is designed to support all of the required orrecommended features of the W3C Recommendation for XML-SignatureSyntax and Processing. The API is extensible and pluggable and isbased on the Java Cryptography Service Provider Architecture.

The Java XML Digital Signature APIs consist of six packages:

• javax.xml.crypto
• javax.xml.crypto.dsig
• javax.xml.crypto.dsig.keyinfo
• javax.xml.crypto.dsig.spec
• javax.xml.crypto.dom
• javax.xml.crypto.dsig.dom

10 Java API for XML Processing (JAXP)

Java API for XML Processing (JAXP) is for processing XML data using Java applications. It includes support for Simple API for XML (SAX), Document Object Models (DOM) and Streaming API for XML (StAX) parsers, XML Schema Validation, and Extensible Stylesheet Language Transformations (XSLT). In addition, JAXP provides secure processing features that can help safeguard your applications and system from XML-related attacks. SeeJava API for XML Processing (JAXP) Security Guide.

Note:Secure Coding Guidelines for Java SE contains additional recommendations that can help defend against XML-related attacks.

11 For More Information

Additional Java security documentation can be found onlineat

Java SE Security

and in the bookInsideJava 2 Platform Security, Second Edition: Architecture, API Designand Implementation.

Note: Historically, as new types of security serviceswere added to the Java platform (sometimes initially asextensions), various acronyms were used to refer to them. Sincethese acronyms are still in use in the Java security documentation,here is an explanation of what they represent: JSSE (Java™Secure Socket Extension) refers to the SSL-related servicesdescribed in Section 7, JCE (Java™ Cryptography Extension)refers to cryptographic services (Section 4), and JAAS (Java™Authentication and Authorization Service) refers to theauthentication and user-based access control services described inSections 6 and 8, respectively.

Appendix A Classes Summary

Table 1 summarizes the names, packages, and usage of the Javasecurity classes and interfaces mentioned in this paper.

Table 1 Key Java securitypackages and classes

Appendix B Tools Summary

Table 2 summarizes the tools mentioned in this paper.

Table 2 Java security tools

There are also three Kerberos-related tools that are shippedwith the Java platform for Windows. Equivalent functionality isprovided in tools of the same name that are automatically part ofthe Solaris and Linux operating environments. Table 3 summarizesthe Kerberos tools.

Table 3 Kerberos-relatedtools

Appendix C Built-in Providers

The Java platform implementation from Oracle includes a numberof built-in provider packages. For details, see theJava™ Cryptography Architecture OracleProviders Documentation.