1/28

Contents

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

1 General Security

• Java Security Overview
  • Introduction to Java Security
  • Java Language Security and Bytecode Verification
  • Basic Security Architecture
    • Security Providers
    • File Locations
  • Java Cryptography
  • Public Key Infrastructure
    • Key and Certificate Storage
    • Public Key Infrastructure Tools
  • Authentication
  • Secure Communication
    • SSL, TLS, and DTLS Protocols
    • Simple Authentication and Security Layer (SASL)
    • Generic Security Service API and Kerberos
  • Access Control
    • Permissions
    • Security Policy
    • Access Control Enforcement
  • XML Signature
  • Additional Information about Java Security
  • Java Security Classes Summary
  • Deprecated Security APIs Marked for Removal
  • Security Tools Summary
  • Built-In Providers
• Security Architecture
• Standard Algorithm Names
• Permissions in the Java Development Kit (JDK)
  • Permission Descriptions and Risks
    • NIO-Related Targets
    • Methods and the Required Permissions
    • java.lang.SecurityManager Method Permission Checks
  • Default Policy Implementation and Policy File Syntax
    • Default Policy Implementation
    • Default Policy File Locations
    • Modifying the Policy Implementation
    • Policy File Syntax
      • Keystore Entry
      • Grant Entries
      • The SignedBy, Principal, and CodeBase Fields
      • KeyStore Alias Replacement
      • The Permission Entries
      • File Path Specifications on Windows Systems
    • Policy File Examples
    • Property Expansion in Policy Files
    • Windows Systems, File Paths, and Property Expansion
    • Path-Name Canonicalization
    • General Expansion in Policy Files
  • API for Privileged Blocks
    • Using the doPrivileged API
      • No Return Value, No Exception Thrown
      • Returning Values
      • Accessing Local Variables
      • Handling Exceptions
      • Asserting a Subset of Privileges
      • Least Privilege
      • More Privilege
    • What It Means to Have Privileged Code
    • Reflection
• Troubleshooting Security

2 Java Cryptography Architecture (JCA) Reference Guide

• Introduction to Java Cryptography Architecture
  • JCA Design Principles
  • Provider Architecture
    • Cryptographic Service Providers
    • How Providers Are Actually Implemented
    • Keystores
  • Engine Classes and Algorithms
• Core Classes and Interfaces
  • The Provider Class
    • How Provider Implementations Are Requested and Supplied
    • Installing Providers
    • Provider Class Methods
  • The Security Class
    • Managing Providers
    • Security Properties
  • The SecureRandom Class
    • Creating a SecureRandom Object
    • Seeding or Re-Seeding the SecureRandom Object
    • Using a SecureRandom Object
    • Generating Seed Bytes
  • The MessageDigest Class
    • Creating a MessageDigest Object
    • Updating a Message Digest Object
    • Computing the Digest
  • The Signature Class
    • Signature Object States
    • Creating a Signature Object
    • Initializing a Signature Object
    • Signing with a Signature Object
    • Verifying with a Signature Object
  • The Cipher Class
  • Other Cipher-based Classes
    • The Cipher Stream Classes
    • The SealedObject Class
  • The Mac Class
  • Key Interfaces
  • The KeyPair Class
  • Key Specification Interfaces and Classes
    • The KeySpec Interface
    • The KeySpec Subinterfaces
    • The EncodedKeySpec Class
      • The PKCS8EncodedKeySpec Class
      • The X509EncodedKeySpec Class
  • Generators and Factories
    • The KeyFactory Class
    • The SecretKeyFactory Class
    • The KeyPairGenerator Class
    • The KeyGenerator Class
  • The KeyAgreement Class
  • Key Management
    • The KeyStore Class
  • Algorithm Parameters Classes
    • The AlgorithmParameterSpec Interface
    • The AlgorithmParameters Class
    • The AlgorithmParameterGenerator Class
  • The CertificateFactory Class
• How the JCA Might Be Used in a SSL/TLS Implementation
• Cryptographic Strength Configuration
• Jurisdiction Policy File Format
• How to Make Applications Exempt from Cryptographic Restrictions
• Standard Names
• Packaging Your Application
• Additional JCA Code Samples
  • Computing a MessageDigest Object
  • Generating a Pair of Keys
  • Generating and Verifying a Signature Using Generated Keys
  • Generating/Verifying Signatures Using Key Specifications and KeyFactory
  • Generating Random Numbers
  • Determining If Two Keys Are Equal
  • Reading Base64-Encoded Certificates
  • Parsing a Certificate Reply
  • Using Encryption
  • Using Password-Based Encryption
• Sample Programs for Diffie-Hellman Key Exchange, AES/GCM, and HMAC-SHA256
  • Diffie-Hellman Key Exchange between 2 Parties
  • Diffie-Hellman Key Exchange between 3 Parties
  • AES/GCM Example
  • HMAC-SHA256 Example

3 How to Implement a Provider in the Java Cryptography Architecture

• Who Should Read This Document
• Notes on Terminology
• Introduction to Implementing Providers
• Engine Classes and Corresponding Service Provider Interface Classes
• Steps to Implement and Integrate a Provider
  • Step 1: Write your Service Implementation Code
    • Step 1.1: Consider Additional JCA Provider Requirements and Recommendations for Encryption Implementations
  • Step 2: Give your Provider a Name
  • Step 3: Write Your Master Class, a Subclass of Provider
    • Step 3.1: Create a Provider That Uses String Objects to Register Its Services
    • Step 3.2: Create a Provider That Uses Provider.Service
    • Step 3.3: Specify Additional Information for Cipher Implementations
  • Step 4: Create a Module Declaration for Your Provider
  • Step 5: Compile Your Code
  • Step 6: Place Your Provider in a JAR File
  • Step 7: Sign Your JAR File, If Necessary
    • Step 7.1: Get a Code-Signing Certificate
    • Step 7.2: Sign Your Provider
  • Step 8: Prepare for Testing
    • Step 8.1: Configure the Provider
    • Step 8.2: Set Provider Permissions
  • Step 9: Write and Compile Your Test Programs
  • Step 10: Run Your Test Programs
  • Step 11: Apply for U.S. Government Export Approval If Required
  • Step 12: Document Your Provider and Its Supported Services
    • Step 12.1: Indicate Whether Your Implementation is Cloneable for Message Digests and MACs
  • Step 13: Make Your Class Files and Documentation Available to Clients
• Further Implementation Details and Requirements
  • Alias Names
  • Service Interdependencies
  • Default Initialization
  • Default Key Pair Generator Parameter Requirements
  • The Provider.Service Class
  • Signature Formats
  • DSA Interfaces and their Required Implementations
  • RSA Interfaces and their Required Implementations
  • Diffie-Hellman Interfaces and their Required Implementations
  • Interfaces for Other Algorithm Types
  • Algorithm Parameter Specification Interfaces and Classes
  • Key Specification Interfaces and Classes Required by Key Factories
  • Secret-Key Generation
  • Adding New Object Identifiers
  • Ensuring Exportability
• Sample Code for MyProvider

4 JDK Providers Documentation

• Introduction to JDK Providers
• Import Limits on Cryptographic Algorithms
• Cipher Transformations
• SecureRandom Implementations
• The SunPKCS11 Provider
• The SUN Provider
• The SunRsaSign Provider
• The SunJSSE Provider
• The SunJCE Provider
• The SunJGSS Provider
• The SunSASL Provider
• The XMLDSig Provider
• The SunPCSC Provider
• The SunMSCAPI Provider
• The SunEC Provider
• The OracleUcrypto Provider
• The Apple Provider
• The JdkLDAP Provider
• The JdkSASL Provider

5 PKCS#11 Reference Guide

• SunPKCS11 Provider
• SunPKCS11 Requirements
• SunPKCS11 Configuration
• Accessing Network Security Services (NSS)
• Troubleshooting PKCS#11
• Disabling PKCS#11 Providers and/or Individual PKCS#11 Mechanisms
• Application Developers
  • Token Login
  • Token Keys
  • Delayed Provider Selection
  • JAAS KeyStoreLoginModule
  • Tokens as JSSE Keystore and Trust Stores
• Using keytool and jarsigner with PKCS#11 Tokens
• Policy Tool
• Provider Developers
  • Provider Services
  • Parameter Support
• SunPKCS11 Provider Supported Algorithms
• SunPKCS11 Provider KeyStore Requirements
• Example Provider

6 Java Authentication and Authorization Service (JAAS)

• JAAS Reference Guide
• JAAS Tutorials
• Java Authentication and Authorization Service (JAAS): LoginModule Developer's Guide
  • Introduction to LoginModule
  • Steps to Implement a LoginModule
    • Step 1: Understand the Authentication Technology
    • Step 2: Name the LoginModule Implementation
    • Step 3: Implement the Abstract LoginModule Methods
    • Step 4: Choose or Write a Sample Application
    • Step 5: Compile the LoginModule and Application
    • Step 6: Prepare for Testing
    • Step 7: Test Use of the LoginModule
    • Step 8: Document Your LoginModule Implementation
    • Step 9: Make LoginModule JAR File and Documents Available

7 Java Generic Security Services (Java GSS-API)

• Java GSS-API and JAAS Tutorials for Use with Kerberos
• Single Sign-on Using Kerberos in Java
• Java GSS Advanced Security Programming
• The Kerberos 5 GSS-API Mechanism

8 Java Secure Socket Extension (JSSE) Reference Guide

• Introduction to JSSE
  • JSSE Features and Benefits
  • JSSE Standard API
  • SunJSSE Provider
  • JSSE Related Documentation
• Terms and Definitions
• Secure Sockets Layer (SSL) Protocol Overview
  • Why Use SSL?
  • How SSL Works
  • Cryptographic Processes
    • Secret-Key Cryptography
    • Public-Key Cryptography
    • Comparison Between Secret-Key and Public-Key Cryptography
    • Public Key Certificates
    • Cryptographic Hash Functions
    • Message Authentication Code
    • Digital Signatures
  • The SSL Handshake
  • The SSL Protocol
    • Handshaking Again (Renegotiation)
    • Cipher Suite Choice and Remote Entity Verification
• Client-Driven OCSP and OCSP Stapling
  • Client-Driven OCSP and Certificate Revocation
    • Setting up a Java Client to use Client-Driven OCSP
  • OCSP Stapling and Certificate Revocation
    • Setting Up a Java Client to Use OCSP Stapling
    • Setting Up a Java Server to Use OCSP Stapling
  • OCSP Stapling Configuration Properties
• JSSE Classes and Interfaces
  • JSSE Core Classes and Interfaces
  • SocketFactory and ServerSocketFactory Classes
  • SSLSocketFactory and SSLServerSocketFactory Classes
    • Obtaining an SSLSocketFactory
  • SSLSocket and SSLServerSocket Classes
    • Obtaining an SSLSocket
  • SSLEngine Class
    • Creating an SSLEngine Object
    • Generating and Processing SSL/TLS Data
    • Datagram Transport Layer Security (DTLS) Protocol
      • The DTLS Handshake
      • Handling Retransmissions in DTLS Connections
    • Creating an SSLEngine Object for DTLS
    • Generating and Processing DTLS Data
    • Understanding SSLEngine Operation Statuses
    • Dealing With Blocking Tasks
    • Shutting Down a SSL/TLS/DTLS Connection
  • SSLSession and ExtendedSSLSession
  • HttpsURLConnection Class
    • Setting the Assigned SSLSocketFactory
    • Setting the Assigned HostnameVerifier
  • Support Classes and Interfaces
    • The SSLContext Class
      • Obtaining and Initializing the SSLContext Class
      • Creating an SSLContext Object
    • The TrustManager Interface
    • The TrustManagerFactory Class
      • Creating a TrustManagerFactory
      • PKIX TrustManager Support
    • The X509TrustManager Interface
      • Creating an X509TrustManager
      • Creating Your Own X509TrustManager
      • Updating the Keystore Dynamically
    • X509ExtendedTrustManager Class
      • Creating an X509ExtendedTrustManager
      • Creating Your Own X509ExtendedTrustManager
    • The KeyManager Interface
    • The KeyManagerFactory Class
      • Creating a KeyManagerFactory
    • The X509KeyManager Interface
      • Creating an X509KeyManager
      • Creating Your Own X509KeyManager
    • The X509ExtendedKeyManager Class
    • Relationship Between a TrustManager and a KeyManager
  • Secondary Support Classes and Interfaces
    • The SSLParameters Class
      • Cipher Suite Preference
    • The SSLSessionContext Interface
    • The SSLSessionBindingListener Interface
    • The SSLSessionBindingEvent Class
    • The HandShakeCompletedListener Interface
    • The HandShakeCompletedEvent Class
    • The HostnameVerifier Interface
    • The X509Certificate Class
    • The AlgorithmConstraints Interface
    • The StandardConstants Class
    • The SNIServerName Class
    • The SNIMatcher Class
    • The SNIHostName Class
• Customizing JSSE
  • How to Specify a java.lang.System Property
  • How to Specify a java.security.Security Property
  • Customizing the X509Certificate Implementation
  • Specifying an Alternative HTTPS Protocol Implementation
  • Customizing the Provider Implementation
  • Registering the Cryptographic Provider Statically
  • Registering the Cryptographic Service Provider Dynamically
  • Provider Configuration
  • Configuring the Preferred Provider for Specific Algorithms
  • Customizing the Default Keystores and Truststores, Store Types, and Store Passwords
  • Customizing the Default Key Managers and Trust Managers
  • Disabled and Restricted Cryptographic Algorithms
  • Customizing the Encryption Algorithm Providers
  • Customizing Size of Ephemeral Diffie-Hellman Keys
  • Customizing Maximum Fragment Length Negotiation (MFLN) Extension
  • Configuring the Maximum and Minimum Packet Size
• Transport Layer Security (TLS) Renegotiation Issue
  • Phased Approach to Fixing This Issue
  • Description of the Phase 2 Fix
  • Workarounds and Alternatives to SSL/TLS Renegotiation
  • TLS Implementation Details
  • Description of the Phase 1 Fix
  • Allow Unsafe Server Certificate Change in SSL/TLS Renegotiations
• Hardware Acceleration and Smartcard Support
  • Configuring JSSE to Use Smartcards as Keystores and Truststores
  • Multiple and Dynamic Keystores
• Kerberos Cipher Suites
  • Kerberos Requirements
  • Peer Identity Information
  • Security Manager
• Additional Keystore Formats (PKCS12)
• Server Name Indication (SNI) Extension
• TLS Application Layer Protocol Negotiation
  • Setting up ALPN on the Client
  • Setting up Default ALPN on the Server
  • Setting up Custom ALPN on the Server
  • Determining Negotiated ALPN Value during Handshaking
  • ALPN Related Classes and Methods
• Troubleshooting JSSE
  • Configuration Problems
    • CertificateException While Handshaking
    • Runtime Exception: SSL Service Not Available
    • Runtime Exception: "No available certificate corresponding to the SSL cipher suites which are enabled"
    • Runtime Exception: No Cipher Suites in Common
    • Socket Disconnected After Sending ClientHello Message
    • SunJSSE Cannot Find a JCA Provider That Supports a Required Algorithm and Causes a NoSuchAlgorithmException
    • FailedDownloadException Thrown When Trying to Obtain Application Resources from Web Server over SSL
    • IllegalArgumentException When RC4 Cipher Suites are Configured for DTLS
  • Debugging Utilities
    • Debugging SSL/TLS Connections
• Code Examples
  • Converting an Unsecure Socket to a Secure Socket
  • Running the JSSE Sample Code
  • Creating a Keystore to Use with JSSE
  • Using the Server Name Indication (SNI) Extension
    • Typical Client-Side Usage Examples
    • Typical Server-Side Usage Examples
    • Working with Virtual Infrastructures
• Standard Names
• Provider Pluggability
• JSSE Cipher Suite Parameters

9 Java PKI Programmers Guide

• PKI Programmers Guide Overview
  • Introduction to Public Key Certificates
  • X.509 Certificates and Certificate Revocation Lists (CRLs)
• Core Classes and Interfaces
  • Basic Certification Path Classes
    • The CertPath Class
    • The CertificateFactory Class
    • The CertPathParameters Interface
  • Certification Path Validation Classes
    • The CertPathValidator Class
    • The CertPathValidatorResult Interface
  • Certification Path Building Classes
    • The CertPathBuilder Class
    • The CertPathBuilderResult Interface
  • Certificate/CRL Storage Classes
    • The CertStore Class
    • The CertStoreParameters Interface
    • The CertSelector and CRLSelector Interfaces
      • The X509CertSelector Class
      • The X509CRLSelector Class
  • PKIX Classes
    • The TrustAnchor Class
    • The PKIXParameters Class
    • The PKIXCertPathValidatorResult Class
    • The PolicyNode Interface and PolicyQualifierInfo Class
    • The PKIXBuilderParameters Class
    • The PKIXCertPathBuilderResult Class
    • The PKIXCertPathChecker Class
    • Using PKIXCertPathChecker in Certificate Path Validation
      • Check Revocation Status of Certificates with PKIXRevocationChecker Class
• Implementing a Service Provider
  • Steps to Implement and Integrate a Provider
    • Service Interdependencies
    • Certification Path Parameter Specification Interfaces
    • Certification Path Result Specification Interfaces
    • Certification Path Exception Classes
• Appendix A: Standard Names
• Appendix B: CertPath Implementation in SUN Provider
• Appendix C: OCSP Support
• Appendix D: CertPath Implementation in JdkLDAP Provider
• Appendix E: Disabling Cryptographic Algorithms

10 Java SASL API Programming and Deployment Guide

• Java SASL API Overview
  • Creating the Mechanisms
  • Passing Input to the Mechanisms
  • Using the Mechanisms
  • Using the Negotiated Security Layer
• How SASL Mechanisms are Installed and Selected
• The SunSASL Provider
  • The SunSASL Provider Client Mechanisms
  • The SunSASL Provider Server Mechanisms
  • Debugging and Monitoring
• The JdkSASL Provider
  • The JdkSASL Provider Client Mechanism
  • The JdkSASL Provider Server Mechanism
• Implementing a SASL Security Provider

11 XML Digital Signature

• Java XML Digital Signature API Specification
  • Acknowledgements
  • Requirements
  • API Dependencies
  • Non-Goals
  • Package Overview
  • Service Providers
  • DOM Mechanism Requirements
  • Open API Issues
  • Programming Examples
• XML Digital Signature API Overview and Tutorial
  • Package Hierarchy
  • Service Providers
  • Introduction to XML Signatures
  • Example of an XML Signature
  • XML Digital Signature API Examples
    • Validate Example
      • Validating an XML Signature
      • Instantiating the Document that Contains the Signature
      • Specifying the Signature Element to be Validated
      • Creating a Validation Context
      • Unmarshalling the XML Signature
      • Validating the XML Signature
      • Using KeySelectors
    • GenEnveloped Example
      • Generating an XML Signature
      • Instantiating the Document to be Signed
      • Creating a Public Key Pair
      • Creating a Signing Context
      • Assembling the XML Signature
      • Generating the XML Signature
      • Printing or Displaying the Resulting Document

12 Security API Specification

13 Deprecated Security APIs Marked for Removal

14 Security Tools

15 Security Tutorials