The Security Group
The Security group is comprised of developers who participate in the design, implementation, and maintenance of Java Security components.
The current members of the Security Group are listed in the census.
Submitting Vulnerabilities
If you have any potential vulnerability to report, please see Oracle's Reporting Security Vulnerabilities page or the OpenJDK Vulnerabilities page.
Introduction
The term "Security" has broad meanings and interpretations. It spans a wide range of areas, including cryptography, public key infrastructure, secure communication, authentication, and access control. The security component thus comprises a large set of APIs, tools, and implementations of commonly-used security algorithms and protocols.
The security area does not cover security features of the other primary component areas (language features and virtual machine implementations, core libraries, graphics subsystems, hotspot, serviceability, etc). For a more detailed treatment, please see the corresponding component pages.
The primary emphasis of these pages is to explore the core security components source bases, and hopefully, get developers up to speed quickly.
The Security Source Layout
The Java security components have been developed and expanded over the years, so the hierarchy may seem complicated simply due to the large number of source files and directories. But the files generally follow fairly straightforward patterns.
For general information about the OpenJDK repositories, and how to clone and build the JDK, see the OpenJDK Developer's Guide.
All of the security component source code is included in the
OpenJDK project under the src
subtree. As there are
many different components, they are split into many subdirectories
across several modules, generally based on functional area. In most
cases, the main API and implementation-independent classes live in
the java/*
or javax/*
hierarchy, and the
implementation classes are in the sun/*
hierarchy.
Like any software projects, there are exceptions to this
guidance.
src/java.base/share/classes/java/security
src/java.base/share/classes/sun/security
The majority of the core security classes live in these two major subdirectories of the
java.base
module (access control, certificates, keys, message digests, permissions, policy, security managers, secure random number generation, etc). The public API for these classes is in thejava/security
hierarchy.The implementation-specific code is fairly extensive within the
sun/security
hierarchy. Some subdirectories of note:ec
- Elliptic Curve Cryptography implementation classes.jca
- Classes to support the*.getInstance()
methods. The OpenJDK implements a delayed provider selection mechanism, and the actual provider is selected as close to the actual use as possible. This mechanism is useful for transient tokens such as smart cards.pkcs
- Miscellaneous, general PKCS support classes.pkcs10
- PKCS10 classes.pkcs12
- The PKCS12 keystore implementation.provider
- TheSUN
JCA provider. Many basic cryptographic services (besides encipherment) are implemented here.provider/certpath
- Certification Path builder and validator classes.rsa
- TheSunRsaSign
provider. These classes implement RSA-signatures and a very limited cipher algorithm. Note that RSA is not specified for bulk encipherment, and would be too slow anyway.ssl
- The SSL/TLS implementation code. See also the SSL/TLS section below for more details.timestamp
- Routines to support certificate timestamping.tools
- The source code for keytool.util
- A variety of utility classes (resource files, data structure manipulations, DER (ASN.1 encoding rules), and so on).validator
- Various certificate validators for https, codesigning, CertPath, and keystores.x509
- The major implementation classes for X509 certificates.
-
src/java.base/share/classes/java/lang/SecurityException.java
src/java.base/share/classes/java/lang/SecurityManager.java
Classes related to the Security Manager.
src/java.base/share/classes/javax/crypto
src/java.base/share/classes/com/sun/crypto/provider
These directories contain the core cryptography framework and
SunJCE
provider.SunJCE
contains Java implementations of many popular algorithms.src/java.base/share/classes/javax/net
src/java.base/share/classes/com/sun/net/ssl
src/java.base/share/classes/sun/security/ssl
src/java.base/share/classes/sun/net/www/protocol/https
The majority of the core SSL/TLS classes. The
javax/net
contains the APIs and platform-independent code. The SSL/TLS implementation is found insun/security/ssl
. The "https" provider is directly based on the JDK "http" provider, which is located in thesun/net/www/protocol
directory.-
src/java.base/share/classes/javax/security/auth
src/java.base/share/classes/com/sun/security
Classes for JAAS authentication.
src/java.base/share/conf/security
src/java.base/share/lib/security
Security configuration files. (java.policy, java.security, default.policy)
src/java.base/share/data/cacerts
src/java.base/share/data/publicsuffixlist
CA cert data files, public suffix list.
-
src/java.base/unix/classes/sun/security
src/java.base/windows/classes/sun/security
src/java.base/macosx/classes/apple/security
Platform-specific Java Code. Platform-independent code is found in
src/java.base/share
. Platform-dependent code is found insrc/{arch}
For example, theApple
provider can be found insrc/java.base/macosx/classes/apple/security
. -
src/java.base/share/native/libjava/AccessController.c
src/java.base/share/native/libjava/SecurityManager.c
Native method implementations are found in the native directories.
Note that the code currently supports all versions of the various platforms. That includes the various releases of Linux, Windows and macOS. Consult the current supported architectures guidelines for more information.
-
src/java.base/share/classes/javax/security/cert
The old JSSE 1.x certificate classes, also here only for compatibility. These APIs should be avoided in favor of the
java.security.cert
equivalent classes. -
src/java.security.jgss/share/classes/org/ietf/jgss
src/java.security.jgss/share/classes/javax/security/auth/kerberos
src/java.security.jgss/share/classes/sun/security/krb5
src/java.security.jgss/share/classes/sun/security/jgss
src/java.security.jgss/share/classes/sun/net/www/protocol/http/spnego
src/java.security.jgss/share/classes/native/libj2gss
Classes and native code for the
java.security.jgss
module which include the Java bindings of GSS-API, Kerberos APIs, and implementations of the Kerberos v5 and SPNEGO GSS-API mechanisms. -
src/java.security.sasl/share/classes/javax/security/sasl
src/java.security.sasl/share/classes/com/sun/security/sasl
Classes for the
java.security.sasl
module which include the SASL API and implementations of the DIGEST-MD5, CRAM-MD5, and NTLM mechanisms. -
src/java.smartcardio/share/classes/javax/smartcardio
src/java.smartcardio/share/classes/sun/security/smartcardio
src/java.smartcardio/share/native/libj2pcsc
Classes and native code for the
java.smartcardio
module which include the Smart Card I/O API andSunPCSC
provider implementation. -
src/java.xml.crypto/share/classes/javax/xml/crypto
src/java.xml.crypto/share/classes/org/jcp/xml/dsig/internal
src/java.xml.crypto/share/classes/com/sun/org/apache/xml/internal/security
Classes for the
java.xml.crypto
module which include the XML Digital Signature API andXMLDSigRI
provider implementation. -
src/jdk.crypto.cryptoki/share/classes/sun/security/pkcs11
src/jdk.crypto.cryptoki/share/native/libj2pkcs11
Classes and native code for the
jdk.crypto.cryptoki
module which contains theSunPKCS11
provider implementation. TheSunPKCS11
provider allows calls made through the standard Java cryptography APIs to be routed into a native PKCS11 library. -
src/jdk.crypto.mscapi/windows/classes/sun/security/mscapi
src/jdk.crypto.mscapi/native/libsunmscapi
Classes and native code for the
jdk.crypto.mscapi
module which contains theSunMSCAPI
provider implementation. -
src/jdk.jartool/share/classes/jdk/security/jarsigner
src/jdk.jartool/share/classes/sun/security/tools/jarsigner
Classes for the
jdk.jartool
module which contains the JarSigner API and source code for jarsigner. -
src/jdk.security.auth/share/classes/com/sun/security/auth
src/jdk.security.auth/unix/native/libjaas
src/jdk.security.auth/windows/native/libjaas
Classes and native code for the
jdk.security.auth
module which contains implementations of thejavax.security.auth
interfaces and various authentication modules. -
src/jdk.security.jgss/share/classes/com/sun/security/jgss
src/jdk.security.jgss/share/classes/com/sun/security/sasl/gsskerb
Classes for the
jdk.security.jgss
module which contains JDK extensions to the GSS-API and an implementation of the SASL GSSAPI mechanism.
Cryptographic Cautions
Anyone who has worked in cryptography knows the import/export of cryptographic code involves complicated legal issues. The JCE in OpenJDK has an open cryptographic interface, meaning it does not restrict which providers can be used. Compliance with United States export controls and with local law governing the import/export of products incorporating the JCE in the OpenJDK is the responsibility of the licensee.
Testing your changes
As a rule, unit tests for fixes and new functionality are pretty much mandatory. However, before submitting changes, you should run the relevant regression tests to make sure that the existing tests continue to pass. For the security component, at a minimum you should run:
- test/jdk/*/net
- test/jdk/*/security
- test/jdk/javax/crypto
- test/jdk/com/sun/crypto
- test/jdk/javax/xml/crypto
- test/jdk/javax/smartcardio
- test/jdk/com/sun/security
- test/jdk/com/sun/org/apache/xml/internal/security
- test/jdk/security/infra
You can run the security tests with make test
:
make test TEST="jdk_security jdk_security_infra"
To run a single test, specify the pathname of the test, ex:
make test
TEST="test/jdk/java/security/Provider/GetInstance.java"
It is also a good idea to run all tests in tier1 and tier2 for more assurance that your change won't break other parts of the JDK:
make test TEST="tier1 tier2"
See the Testing the JDK section of the OpenJDK Developer's Guide for more details on how to write and run tests. If your changes break something, it will be a lot more work to diagnose, and then fix or back out. Do as much testing as possible.
Issues
Issues are tracked in the JDK Bug System. Security bugs are tracked in thesecurity-libs
component. There are several
subcomponents depending on what area the issue affects:
java.security
, javax.security
,
javax.net.ssl
, javax.crypto
,
javax.crypto:pkcs11
, org.ietf.jgss
,
org.ietf.jgss:krb5
, javax.xml.crypto
,
javax.smartcardio
, and jdk.security
.
Documentation
- The Java Security Overview (SE 21 version, part of the Security Documentation below) is probably the best place to start learning about the overall Java security architecture and implementation.
- The Java SE 21 Security Documentation provides much more detailed information, and should be understood before undertaking any work in this area.
- The book Inside the Java 2 Platform Security, Second Edition by Li Gong (et.al.) is dated (circa JDK 1.4), but provides valuable information and rationale for some of the JDK design decisions.
Community
- Mailing lists
- security-dev
This mailing list is sponsored by the members of the OpenJDK Security community and is comprised of developers interested in the design, implementation, and maintenance of the various Java Standard Edition (Java SE) security components. It is not for general JDK support.
- security-dev