| Oracle® Security Developer Tools Reference 10g (10.1.4.0.1) Part Number B28165-01 |
|
|
View PDF |
| Oracle® Security Developer Tools Reference 10g (10.1.4.0.1) Part Number B28165-01 |
|
|
View PDF |
Extensible Markup Language (XML) is an application of Standard Generalized Markup Language (SGML). XML is a meta-language that allows implementors to define their own self-describing markup. Implementors use XML to define their own set of custom tags. The tags are similar to those found in an HTML document; like XML, HTML is also an application of SGML.
For a document to be valid, it must conform to all the constraints imposed by a given Document Type Definition (DTD) or schema. A valid XML document is said to be semantically correct.
XML security refers to standard security requirements of XML documents such as confidentiality, integrity, message authentication, and non-repudiation. The need for digital signature and encryption standards for XML documents prompted the World Wide Web Consortium (W3C) to put forth an XML Signature standard and an XML Encryption standard. The XML Signature standard is the product of a joint working group that also includes the Internet Engineering Task Force (IETF). In addition, the W3C and IETF have also jointly proposed an XML Key Management Specification (XKMS) that defines protocols for distributing and registering public keys associated with XML signatures and XML encryption.
This chapter describes key features and benefits of Oracle XML Security, and explains how to set up your environment to use Oracle XML Security.
This chapter contains these topics:
|
See Also: The following resources provide more information about XML and XML standards:
Links to these resources are available in Appendix A, "References". |
The Oracle XML Security SDK is a pure Java solution which provides the following features:
Support for the XML Signature standard
Support for the XML Encryption standard
Support for the Decryption Transform standard
Support for the XML Canonicalization standard
Support for the Exclusive XML Canonicalization standard
Compatibility with a wide range of JAXP 1.1 compliant XML parsers and XSLT engines
Links to these standards are available in Appendix A, "References".
The Oracle Security Developer Tools are installed with Oracle Application Server in ORACLE_HOME.
This section explains how to set up your environment for Oracle XML Security. It contains these topics:
In order to use Oracle XML Security, your system must have the following components installed:
The Java Development Kit (JDK) version 1.2.2 or higher
A JAXP-compatible XML parser and XSLT processor
Oracle XML Security has been tested with the following implementations:
Apache Xalan-Java (with Xerces-J)
Oracle XDK for Java
|
Note: If you have questions regarding compatibility with other parsers, see the Oracle Technology Network Web Site athttp://www.oracle.com/technology/index.html. |
Apache Libraries
Sun JDK 1.4.x distributions contain an embedded version of the Apache Crimson parser and an older version of the Apache Xalan XSLT engine. Oracle does not recommend using these versions, as they contain a number of bugs and incompatibilities that can result in signature and encryption failures. If you are using JDK 1.4.x with an Apache XML parser, the XSLT engine, or both, put the Apache library JAR files in your JRE's /lib/endorsed directory to override the JRE's built-in version of Apache.
Your CLASSPATH environment variable must contain the full path and file names to all of the required jar and class files. Make sure the following items are included in your CLASSPATH:
osdt_core.jar
osdt_cert.jar
osdt_xmlsec.jar
jaxen.jar, which is included in the $ORACLE_HOME/jlib directory of the security tools distribution. Oracle XML Security relies on the Jaxen XPath engine for XPath processing.
The appropriate XML parser and XSLT processor implementations, unless you have installed them in your JRE's /lib/ext or /lib/endorsed directory.
|
Note: The Jaxen library included in the Oracle XML Security distribution is a modified version of the Jaxen 1.0 FCS release. If you also have an earlier Jaxen release in yourCLASSPATH, you must ensure that the version from this distribution appears first. |
If you are installing Oracle XML Security on Windows, set your CLASSPATH as follows:
In your Windows Control Panel, select System.
In the System Properties dialog, select the Advanced tab.
Click Environment Variables.
In the User Variables section, click New to add a CLASSPATH environment variable for your user profile. If a CLASSPATH environment variable already exists, select it and click Edit.
Add the full path and file names for all the required jar and class files to the CLASSPATH.
For example, your CLASSPATH might look like this:
%CLASSPATH%;C:\ORACLE_HOME\jlib\osdt_core.jar; C:\ORACLE_HOME\jlib\osdt_cert.jar; C:\ORACLE_HOME\jlib\osdt_xmlsec.jar; C:\ORACLE_HOME\jlib\jaxen.jar;
Click OK.
On UNIX, set your CLASSPATH environment variable to include the full path and file name of all the required jar and class files. For example:
setenv CLASSPATH $CLASSPATH:$ORACLE_HOME/jlib/osdt_core.jar:\ $ORACLE_HOME/jlib/osdt_cert.jar:\ $ORACLE_HOME/jlib/osdt_xmlsec.jar:\ $ORACLE_HOME/jlib/jaxen.jar:
This section describes classes in the XML Security API. It includes:
This section describes core classes, illustrates how to create class instances, and uses code samples to illustrate the capabilities of each class.
This class represents the top-level Signature element of the XML Signature schema. Creating an instance of this class is the first step in creating a new signature or in verifying an existing signature.
To create a new signature, you create a new instance of the XSSignature class by calling the static newInstance() method:
Example 8-1 Creating a Signature with XSSignature
XSSignature sig = XSSignature.newInstance("MySignatureID");
To obtain Signature elements from an XML document to verify a signature, you first obtain an org.w3c.dom.NodeList object that contains all the Signature elements as instances of org.w3c.dom.Node. You can then iterate through the NodeList and convert each node to an instance of XSSignature, as the following example illustrates:
Example 8-2 Verifying a Signature with XSSignature
Document doc = Instance of org.w3c.dom.Document;
// Get list of all XML Signatures in the document.
NodeList sigList = doc.getElementsByTagNameNS(XMLURI.ns_xmldsig, "Signature");
if (sigList.getLength() == 0)
System.err.println("No XML-DSIG Signature elements found.");
// Convert each org.w3c.dom.Node object to a oracle.security.xmlsec.dsig.XSSignature
// object and perform verification
for (int s = 0, n = sigList.getLength(); s < n; ++s)
{
XSSignature sig = new XSSignature((Element)sigList.item(s));
//Perform signature verification for this signature
...
}
This class represents the SignedInfo element of the XML Signature schema. As with XSSignature, you must use this class to both create and verify signatures. In signature creation, you create an instance of this class with the following code:
Example 8-3 Creating a Signature with XSSignedInfo
XSignature sig = XSSignature.newInstance("MySignatureID");
XSSignedInfo si = sig.createSignedInfo("MySignedInfoID");
When performing verification, you first obtain an instance of XSSignature as shown in Example 8-2, then obtain the SignedInfo element from the top-level Signature with the following code:
This class represents the Reference element of the XML Signature schema. You must use this class when creating and verifying signatures. In signature creation, you create an instance of this class with the following code:
Example 8-5 Creating Signature Reference Elements with XSReference
XSignature sig = XSSignature.newInstance("MySignatureID");
String uri = "the URI of the data object you want to reference";
String type = "the type of the data object you want to reference (optional)";
XSAlgorithmIdentifier digestAlg =
the digest algorithm identifier (e.g., XMLURI.alg_sha1);
XSReference ref =
sig.createReference("MyReferenceID", uri, type, digestAlg);
When performing verification, you first obtain an instance of XSSignature as shown in Example 8-2, then obtain the Reference elements from the top-level Signature with the following code:
This class represents the KeyInfo element of the XML Signature schema. You may use this class for signature creation as well as signature verification.
In signature creation, you create an instance of this class with the following code:
Example 8-7 Creating Key Information Elements with XSKeyInfo
XSignature sig = XSSignature.newInstance("MySignatureID");
XSKeyInfo si = sig.createKeyInfo("MyKeyInfoID");
A KeyInfo element can have various child elements that contain the actual key data. The classes that support these KeyInfo children are found in the oracle.security.xmlsec.keys package.
For example, to create an RSAKeyValue element containing a signer's public key, you can use the following code:
Example 8-8 Creating an RSAKeyValue Element with the Signer's Public Key
X509 cert = An instance of the oracle.security.crypto.cert.X509 class; XSKeyInfo ki = An instance of the XSKeyInfo class; RSAKeyValue rsaKeyValue = ki.createKeyValue(cert.getPublicKey()); ki.addKeyInfoData(rsaKeyValue);
When performing verification, you first obtain an instance of XSSignature as shown in Example 8-2, then obtain the KeyInfo element from the top-level Signature with the following code:
This class represents the EncryptedData element of the XML encryption schema. You must create an instance of this class when encrypting or decrypting arbitrary data or an entire XML document.
When encrypting, you create an instance of this class with the following code:
Example 8-10 Using XEEncryptedData for Encryption
Document doc = Instance of org.w3c.dom.Document; String dataType = Either XMLURI.obj_content (content only) or XMLURI.obj_Element (entire element); XEEncryptedData encData = XEEncryptedData.newInstance(doc, "MyEncryptedDataID", dataType);
When decrypting, you can obtain the EncryptedData elements from an XML document with the following code:
Example 8-11 Using XEEncryptedData for Decryption
Document doc = Instance of org.w3c.dom.Document;
// Get list of all XML EncryptedData elements in the document.
NodeList encDataList =
doc.getElementsByTagNameNS(XMLURI.ns_xmlenc, "EncryptedData");
if (encDataList.getLength() == 0)
System.err.println("No XML-ENC EncryptedData elements found.");
// Convert each org.w3c.dom.Node object to a
// oracle.security.xmlsec.enc.XEEncryptedData
// object and perform decryption
for (int s = 0, n = encDataList.getLength(); s < n; ++s)
{
XEEncryptedData = new XEEncryptedData((Element)encDataList.item(s));
//TODO: Perform decryption of the encrypted data
//contained in this element
}
This class represents the EncryptedKey element of the XML Encryption Schema. You can use an instance of this class to encrypt and decrypt cryptographic key material.
When encrypting a key, you create an instance of this class with the following code:
Example 8-12 Using XEEncryptedKey for Key Encryption
Document doc = Instance of org.w3c.dom.Document; XEEncryptedKey encKey = XEEncryptedKey.newInstance(doc, "MyEncryptedKeyID");
When decrypting a key, you first obtain the XEEncryptedData from an XML document using the code in Example 8-11, then obtain the EncryptedKey elements with the following code:
This class represents the EncryptionMethod element of the XML encryption schema. It contains the algorithm and parameters used in encrypting data or encrypting a key.
When encrypting, you create an instance of this class with the following code:
Example 8-14 Using XEEncryptionMethod for Encryption
String algURI = "String containing the URI of the encryption algorithm"; XEEncryptedObject encObj = Instance of XEEncryptedData or XEEncryptedKey; XEEncryptionMethod em = encObj.createEncryptionMethod(algURI);
When decrypting, you first obtain an EncryptedData element using Example 8-11, or an EncryptedKey element using Example 8-13, then obtain an EncryptionMethod element with the following code:
This class represents the CipherData element that provides the encrypted data. It either stores the encrypted data in the CipherValue element or refers to a source containing the data through the CipherReference element. When performing encryption, you create an instance of XEEncryptedData or XEEncryptedKey, then create an instance of XECipherData with the following code:
Example 8-16 Using XECipherData when Encrypting
XEEncryptedObject encObj; //Create an instance of XEEncryptedData (see class example earlier) //XEEncryptedKey (see example 8-12) XECipherData cd = encObj.createCipherData();
When decrypting, you first obtain an EncryptedData element using Example 8-11, or an EncryptedKey element using Example 8-13, then obtain an instance of an XECipherData element with the following code:
This section describes additional classes and interfaces in the Oracle XML Security SDK.
This section answers frequently asked questions about XML security and about using Oracle XML Security. It addresses these areas:
This section describes common issues related to keys and certificates.
What is the DER format? The PEM format? How are these formats used?
DER is an abbreviation for ASN.1 Distinguished Encoding Rules. DER is a binary format that is used to encode certificates and private keys. Oracle XML Security SDK uses DER as its native format, as do most commercial products that use certificates and private keys.
Many other formats used to encode certificates and private keys, including PEM, PKCS #7, and PKCS #12, are transformations of DER encoding. For example, PEM (Privacy Enhanced Mail) is a text format that is the Base 64 encoding of the DER binary format. The PEM format also specifies the use of text BEGIN and END lines that indicate the type of content that is being encoded.
I received a certificate in my email in a text format. It has several lines of text characters that don't seem to mean anything. How do I convert it into the format that Oracle XML Security uses?
If you received the certificate in your email, it is in PEM format. You need to convert the certificate from PEM (Privacy-Enhanced Mail) format to ASN.1 DER (Distinguished Encoding Rules) format.
How do I use a certificate that is exported from a browser?
If you have exported the certificate from a browser, it is most likely in PKCS #12 format (*.p12 or *.pfx). You must parse the PKCS #12 object into its component parts.
This section describes common questions about keys and certificates.
What signature algorithms does Oracle XML Security support?
Oracle XML Security supports the following signature algorithms:
DSA with SHA1
RSA with SHA1
|
See Also: For more information about these algorithms, refer to the links for DSA-SHA and RSA-SHA in Appendix A, "References". |
This section describes common issues related to keys and certificates.
What data encryption algorithms does Oracle XML Security support?
Oracle XML Security supports the following signature algorithms:
AES-128 in CBC mode
AES-192 in CBC mode
AES-256 in CBC mode
DES EDE in CBC mode
Links to these standards are available in Appendix A, "References".
What key wrapping algorithms does Oracle XML Security support?
Oracle XML Security supports the following key wrapping algorithms:
AES-128
AES-192
AES-256
DES-EDE
Links to these standards are available in Appendix A, "References".
What key transport algorithms does Oracle XML Security support?
Oracle XML Security supports the following key transport algorithms:
RSAES-OAEP-ENCRYPT with MGF1
RSAES-PKCS1-v1_5
Links to these standards are available in Appendix A, "References".
What key agreement algorithms does Oracle XML Security support?
Oracle XML Security supports the Diffie-Hellman key agreement algorithm.
The Oracle XML Security API (Javadoc) is available at:
Oracle Security Developer Tools XML Security Java API Reference
For example programs using the Oracle Security Developer Tools, see the Oracle Technology Network Web Site at http://www.oracle.com/technology/index.html.
