Download AFRD Third Party Toolkit for S/MIME - CitiDirect

CitiDirect® Online Banking
Automated File and Report Delivery
User Guide: Third Party Toolkit for S/MIME
August 2003
Proprietary and Confidential
These materials are proprietary and confidential to Citibank, N.A. and are
intended for the exclusive use of CitiDirect® Online Banking customers. The
foregoing statement shall appear on all copies of these materials made by you in
whatever form and by whatever means, electronic or mechanical, including
photocopying or in any information storage system. In addition, no copy of these
materials shall be disclosed to third parties without express written authorization
of Citibank, N.A.
Please Note:
The information contained in this section is intended to assist you in establishing the environment
and configuration required to successfully use CitiDirect Online Banking Automated File and
Report Delivery (AFRD).
Table of Contents
Introduction ..................................................................................................................... 4
S/MIME Technology Overview ....................................................................................... 6
Toolkits ............................................................................................................................ 7
Entrust Java Toolkit........................................................................................................ 8
Wedgetail JCSI S/MIME Toolkit for Java..................................................................... 13
Phaos S/MIME Toolkit for Java .................................................................................... 19
IAIK Java Toolkit ........................................................................................................... 23
Bouncy Castle Java Toolkit ......................................................................................... 26
Third Party Toolkits for S/MIME File Processing
Page 3 of 30
Introduction
This document describes the various third party vendor toolkits that support Secure Multipurpose
Internet Mail Extensions (S/MIME) messaging with CitiDirect® Online Banking’s Automated File &
Report Delivery (AFRD) service. CitiDirect AFRD provides the ability to schedule the generation
and delivery of files and reports to/from CitiDirect central servers.
The aim of this document is to facilitate the process of developing a custom application solution,
employing a toolkit that adheres to the widely accepted S/MIME version 3 and PKCS# 7 standard
for secure messaging, to enable automation of:
•
•
The file encryption and signing procedure on payment files destined to Citigroup
The file decryption and signature verification procedure on account balance data from
Citigroup
The code samples in this document have been tested with the CitiDirect AFRD service. The
documentation of the sample code should reduce your development, integration and deployment
time which result in savings for you. Moreover, to minimize the development lifecycle and costs
associated with the effort, the sample code has been developed using various vendor toolkits to
ensure the maximum level of interoperability between the CitiDirect AFRD and your automated
system.
This document describes software development specifics of building the core-messaging
infrastructure required for integration with the AFRD S/MIME secure messaging solution. A
software application or system intended to communicate with the CitiDirect AFRD has to adhere
to the S/MIME version 3 message specification.
This document is targeted to clients who fit the following profile:
•
•
•
•
High transaction (payment activity and/or numerous account balances) volume on a
regular basis.
Desires an additional layer of file security over the standard SSL (Secure Sockets Layer)
communications protocol.
Experienced with manual execution of file import and/or export via CitiDirect Online
Banking. In addition, has practiced manual execution of file encryption/decryption with
the Entrust Entelligence Software.
Possesses technical/development resources that:
o Have proficiency in the following technologies: Java, C/C++, VB, scripting.
o Understand cryptography concepts.
o Have familiarity with MIME processing, digital certificates and the Public Key
Infrastructure (e.g., public/private keys, encryption & signing).
o Skilled in Web Server Installation & Configuration (e.g., Microsoft® IIS, Apache,
Netscape® iPlanet).
o Basic knowledge of the HTTP protocol.
It is recommended that you approach the implementation of CitiDirect AFRD in the following
manner to build an adequate level of knowledge around the entire process and achieve a
smoother overall experience:
1. Establish that file import and/or exports can be executed manually in-session (e.g., signed-on
within the CitiDirect platform).
Third Party Toolkits for S/MIME File Processing
Page 4 of 30
2. Establish that manual encryption (for file imports) and/or decryption (for file exports) can be
performed with the Entrust Entelligence Software. As well, confirm the same files can be
delivered via CitiDirect AFRD.
3. Establish that the Web Server can successfully send/receive files with CitiDirect AFRD.
4. Create a customized solution, employing the desired toolkit, to automate step#2.
Notice this document does not demonstrate how to develop a solution for unattended secure file
import/export. This document will explain how to employ select S/MIME toolkits to perform
electronic security development. However, you will continue to be required to manually sign-on to
CitiDirect to confirm the processing status of payments. Specifically, on file imports, you need to
sign-on to CitiDirect to ensure the scheduled event executed and payments were submitted
successfully.
Third Party Toolkits for S/MIME File Processing
Page 5 of 30
S/MIME Technology Overview
The S/MIME (Secure Multipurpose Internet Mail Extensions) standard uses sophisticated publickey encryption technology to protect messages from unauthorized interception and forgery —
providing data privacy and authenticity. Designed for security and interoperability, S/MIME has
emerged as the de facto industry protocol for secure messaging applications. Properly
implementing a complex protocol like S/MIME is not a trivial task. The security infrastructure and
the underlying cryptographic algorithms pose a formidable and time-intensive project for any
development organization.
Secure multipurpose Internet mail extensions (S/MIME) versions 2 and 3 is a widely used
application of PKCS #7 specification for exchanging messages and data by transport protocols
capable of conveying MIME data, such as e-mail and HTTP/HTTPS. S/MIME offers
authentication, using digital signatures to validate a sender's identity, and privacy, using
encryption to protect a message against unauthorized access. Following the syntax described in
PKCS #7, S/MIME specifies how to include encryption information and a digital certificate as part
of an e-mail message.
It is important to understand the distinction between S/MIME and PKCS #7. PKCS#7 is a generic
specification for secure messaging that can be used with a variety of security mechanisms.
S/MIME is an application of PKCS #7, specifically designed for MIME messaging.
For additional information on S/MIME messaging refer to the following:
S/MIME version 2 Message Specification (RFC 2311) and S/MIME version 2
Certificate Handling (RFC 2312)
http://www.ietf.org/rfc/rfc2311.txt
http://www.ietf.org/rfc/rfc2312.txt
S/MIME version 3 Message Specification (RFC 2633) and S/MIME version 3 Certificate Handling
(RFC 2632)
http://www.ietf.org/rfc/rfc2633.txt
http://www.ietf.org/rfc/rfc2632.txt
Internet X.509 Public Key Infrastructure Certificate and CRL Profile (RFC 2459)
http://www.ietf.org/rfc/rfc2459.txt
CitiDirect® Online Banking secure messaging supports S/MIME version 2 and 3 for incoming files
(File Import) and version 3 for outgoing files (File Export and Reports).
Third Party Toolkits for S/MIME File Processing
Page 6 of 30
Toolkits
The following toolkit solutions have been tested with CitiDirect application:
•
Entrust Java Toolkit
•
Phaos S/MIME Toolkit for Java
•
Wedgetail JCSI S/MIME Toolkit
•
IAIK S/MIME Toolkit
Technical support for the tested toolkits is provided directly from the vendors. You are advised to
establish a relationship with them for assistance with the toolkit during the initial implementation
and post-implementation stages.
Citigroup does not recommend one toolkit over another. One of the reasons we have designed
CitiDirect AFRD to be consistent with the S/MIME version 3 and PKCS #7 standard is we do not
want you to depend on one specific technology.
Third Party Toolkits for S/MIME File Processing
Page 7 of 30
Entrust Java Toolkit
Overview
Entrust Java Toolkit is a pure-Java implementation of the cryptographic and secure messaging
APIs used by applications that protect privacy, integrity, and authenticity of information.
Supported functionality includes generation, transmission, and storage of its users' cryptographic
keys, using a Certification Authority (CA) and Public Key Infrastructure (PKI), secure encryption
and decryption algorithms to provide privacy, and digital signatures to assure the integrity and
authenticity of the data.
Only clients with their own PKI infrastructure relationship with Entrust Technologies can obtain
the toolkit. This toolkit is appropriate for clients that have or plan to establish an Entrust
relationship. This toolkit is also appropriate for internal Citigroup entities, which can obtain the
toolkit from Citigroup PKI Engineering.
Vendor
Entrust Technologies
Product Name and Version
Entrust Toolkit for Java 6.0 sp2 (Service Pack 2)
http://www.entrust.com/authority/java/specs.htm
Environment
The sample applications have been tested on the following operating systems. For specifics on
all the operating systems the toolkit is compatible with contact the vendor.
•
•
•
Microsoft® Windows® NT 4.0 (Service Pack 6a)
Microsoft Windows 2000 Professional Edition (Service Pack 2)
SUN Solaris™ 8
In addition to Entrust Toolkit for Java 6.0 Service Pack 2, the following software products are
necessary to use the sample applications:
Sun Microsystems Java 2 Software Development Kit (J2SDK) 1.3.1
http://java.sun.com/j2se/1.3/
Sun Microsystems JavaBeans Activation Framework (JAF) 1.0.2
http://java.sun.com/products/javabeans/glasgow/jaf.html
Sun Microsystems JavaMail API
http://java.sun.com/products/javamail/index.html
Third Party Toolkits for S/MIME File Processing
Page 8 of 30
Utilizing an online PKI supports clients in maintenance of the digital certificates via their PKI
infrastructure. If you plan to use online PKI, the following is necessary:
Java Naming and Directory Interface (JNDI) and LDAP Service Provider
http://java.sun.com/products/jndi/index.html
Product Setup
Refer to the Entrust documentation (ettkjava_readme.html, ettkjava_relnotes.html,
ettkjava_prog_guide.pdf) for the specifics on installing and configuring the toolkit.
The following custom cryptographic service providers are supplied with the Entrust Java Toolkit:
•
•
The Entrust cryptographic service Provider — supports specialized implementations of
the RSA and DSA algorithms
The IAIK cryptographic service Provider — implements key generation and other utilities,
as well as the most commonly used symmetric encryption algorithms and message
digests (hash functions)
Message Specification
The following MIME types are supported:
multipart/signed
application/x-pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs10
application/pkcs7-signature
application/pkcs7-mime
application/pkcs10
Sample S/MIME v3 message header
Message-ID: <1156004.1044290443213.JavaMail.ab01234@111GECDW1234>
Date: Mon, 3 Feb 2003 11:40:43 -0500 (EST)
Mime-Version: 1.0
Content-Type: application/pkcs7-mime; smime-type=enveloped-data; name=".\\data\\1.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=".\\data\\1.pdf"
Third Party Toolkits for S/MIME File Processing
Page 9 of 30
MIME Message Structure
The following MIME message structure is supported by the sample code:
S/MIME envelope
Encrypted Content (PKCS#7)
Signed Content
MIME multipart
MIME bodypart
Data file
Development Settings
Required Libraries
Entrust Java Toolkit (located in etjava\lib\application directory)
entbase.jar
entuser.jar
entp7.jar
JavaMail
mail.jar
JavaBeans Activation Framework
activaton.jar
Optional Libraries
JNDI
jndi.jar
LDAP Provider
ldap.jar
providerutil.jar
Classpath
Make sure your CLASSPATH environment variable includes the required jar files.
An application using the S/MIME API must have all the necessary MIME types registered in its
command map. The example programs manage the required command map entries, there is no
need to setup and maintain the "mailcap" file.
Commands
The Entrust code samples make use of the Entrust profile (epf) to create digital signatures. The
Entrust profile has to be set up before using the sample code.
Third Party Toolkits for S/MIME File Processing
Page 10 of 30
The following steps will help you get started with the sample code:
Set your CLASSPATH environment variable to include the required Entrust Java Toolkit jar files,
JavaMail and JavaBeans Activation Framework (JAF) jar files.
In the java code examples, review the “mailcap” section to make sure it reflects your specific mail
system configuration for content types and content handlers.
The following steps show how to create a signed and encrypted s/mime file, then verify the
signature and certificate and view the decrypted contents:
1. Open a command prompt window, and change the current directory to the folder you copied
the sample code into.
2. Compile the sample programs using Java compiler:
javac SendSMIMEFile.java
javac ReceiveSMIMEFile.java
3. Create a signed and encrypted S/MIME file:
Command line parameters
java SendSMIMEFile myprofile.epf mypassword .\data\msg.txt .\data\msg.txt.p7m recipient.cer
myprofile.epf – name of the Entrust profile file you use. This is the sender’s profile.
mypassword – password for myprofile.epf
msg.txt – the data file to be signed and encrypted in S/MIME format
msg.txt.p7m – signed and encrypted data with S/MIME message headers
recipient.cer – recipient’s valid X.509 certificate in DER format (e.g., for CitiDirect® Online
Banking AFRD, this would be the CitiDirect public key downloaded from the S/MIME
Administration Service Class within CitiDirect).
Substitute your own profile name, password and the data file names to run the example. The data
file will be signed with the signing certificate in the Entrust profile and encrypted with the
recipient’s certificate. The data is also encrypted with the sender’s certificate (encryption
certificate in the Entrust profile), so the sender can decrypt messages they sent to other parties.
4. Decode the signed and encrypted S/MIME file, decrypt the content, verify message signature
and signer’s certificate:
Third Party Toolkits for S/MIME File Processing
Page 11 of 30
Command line parameters
java ReceiveSMIMEFile theirprofile.epf theirpassword .\data\msg.txt.p7m .\data\msg2.txt
The sender can decrypt messages they sent to other parties. If you have only one Entrust profile,
you still can use it for message decryption. Substitute the Entrust profile you will use for
theirprofile.epf. The sender’s digital certificate is attached to the message. It will be verified using
the chain of trust and credentials available in the Entrust profile you use.
theirprofile.epf – name of the Entrust profile file you use, can be the same as myprofile.epf
theirpassword – password for theirprofile.epf
msg.txt.p7m – signed and encrypted data with S/MIME message headers
msg2.txt – decoded data file
Sample Code
Message encoding
SendSMIMEFile.java
Message decoding
ReceiveSMIMEFile.java
Sample Encoded Data File
msg.txt.p7m
Third Party Toolkits for S/MIME File Processing
Page 12 of 30
Wedgetail JCSI S/MIME Toolkit for Java
Overview
Wedgetail JCSI S/MIME Toolkit for Java is a pure-Java implementation of the cryptographic and
secure messaging APIs used by applications that protect privacy, integrity, and authenticity of
information.
Vendor
Wedgetail Communications.
Product Name and Version
JCSI SMIME (Java Crypto and Security Implementation SMIME)
http://www.wedgetail.com/jcsi/smime/index.html
Environment
The sample applications have been tested on the following operating system. For specifics on all
the operating systems the toolkit is compatible with contact the vendor.
•
Microsoft® Windows® 2000 Professional Edition (Service Pack 2)
In addition to Wedgetail S/MIME Toolkit for Java platform 2 (standard and enterprise edition, 1.2
and above), the following software products are necessary to use the sample applications:
Sun Microsystems Java 2 Software Development Kit (J2SDK) 1.3.1
http://java.sun.com/j2se/1.3/
Sun Microsystems JavaBeans Activation Framework (JAF) 1.0.2
http://java.sun.com/products/javabeans/glasgow/jaf.html
Sun Microsystems JavaMail API
http://java.sun.com/products/javamail/index.html
Wedgetail JCSI Provider 2.2
http://www.wedgetail.com/jcsi/2.2/provider
Product Setup
Refer to the Wedgetail JCSI SMIME documentation and user's guides supplied with the toolkit for
the specifics on installing and configuring the toolkit.
Third Party Toolkits for S/MIME File Processing
Page 13 of 30
Message Specification
The following MIME types are supported:
• multipart/signed,
• application/pkcs7-mime; smime-type=enveloped-data
• application/pkcs7-mime; smime-type=signed-data
Sample S/MIME v3 message header
Message-ID: <4126736.1044656024009.JavaMail.an94706@111GECDW8119>
Mime-Version: 1.0
Content-Disposition: attachment; filename="smime.p7m"
Content-Description: S/MIME Encrypted Message
Date: Fri, 7 Feb 2003 17:13:40 -0500 (EST)
From: [email protected]
To: [email protected]
Content-Type: application/pkcs7-mime; smime-type=enveloped-data
Content-Transfer-Encoding: base64
MIME Message Structure
The following MIME message structure is supported by the sample code:
S/MIME envelope
Encrypted Content (PKCS#7)
Signed Content
MIME multipart
MIME bodypart
Data file
Development Settings
These are java API jar files which need to be in the classpath. CLASSPATH is a system.
environment variable which should have path to these jar files wherever they are physically
located on the system.
Required Libraries
Wedgetail JCSI S/MIME Toolkit for Java
jcsi_smime.jar
If not JDK 1.4 or above, you need JCE 1.2.1-compatible framework
jcsi_jce.jar
JavaMail
mail.jar
JavaBeans Activation Framework
activaton.jar
JCSI Provider 2.2
jcsi_provider.jar
Third Party Toolkits for S/MIME File Processing
Page 14 of 30
JCSI Base 2.2.1 libraries
jcsi_base.jar and jcsi_license.jar
Classpath
Make sure your CLASSPATH environment variable includes the required jar files.
An application using the S/MIME API must have all the necessary MIME types registered in its
command map. The example programs manage the required command map entries, there is no
need to set up and maintain the "mailcap" file.
Third Party Toolkits for S/MIME File Processing
Page 15 of 30
Commands
The samples make use of the Personal Information Exchange PKCS#12 profile (p12/pfx) to
create digital signatures. The p12 profile has to be set up before using the sample code.
The following steps will help you get started with the sample code:
Set your CLASSPATH environment variable to include the required Wedgetail JCSI SMIME
Toolkit jar files, JavaMail and JavaBeans Activation Framework (JAF) jar files.
In the java code examples, review the “mailcap” section to make sure it reflects your specific mail
system configuration for content types and content handlers. It is present in function
createMessage in file Send.java
The following steps show how to create a signed and encrypted S/MIME file, then verify the
signature and certificate and view the decrypted contents:
1. Open a command prompt window, and change the current directory to the folder you copied
the sample code into.
2. Compile the sample programs using Java compiler:
javac Send.java
javac Receive.java
3. Create a signed and encrypted S/MIME file:
Command line parameters
java SMimeSend seb [email protected] [email protected] global.cer thawte.pfx terminator tIssuer.cer c:/testdata/rsa/smime_dg1.pdf
a) seb - if you want to process binary files, otherwise application will treat the file as text
file (This is not optional. SEB shows seb shows three functionalities depending on what
we are looking for. If we provide s, then it will only sign it, if we provide e, it will only
encrypt it. If we provide only b [for processing binary files], that is not allowed. Here are
the possible values ‘s’, ‘se’, ‘sb’, ‘eb’, ‘seb’, ‘e’).
b) sender email address
c) rcpt email address
d) rcpt certificate (For File Import to CitiDirect® Online Banking AFRD, this the CitiDirect
public certificate downloaded from S/MIME Administration Service Class)
e) sender .pfx file
f) password
g) sender Issuer Cert - to be added
h) InputFileName
java Send se myemail uremail urcert.cer mycert.cer CACert mykey.p12 mypassword Infile
OutFile.p7m
se – s for signing, e for encrypting.
myemail – sender e-mail address
uremail – recipient e-mail
urcert – recipient certificate
Mykey.p12 – the private key file of sender
Third Party Toolkits for S/MIME File Processing
Page 16 of 30
Mypassword – password for p12 file
CACert – The trust point certificate (This is the Citigroup public root certificate)
Infile – input plain file name
OutFile.p7m – output file [SMIME encoded]
Substitute your own profile name, password and the data file names to run the example. The data
file will be signed with the signing certificate in the PKCS#12 file and encrypted with the
recipient’s certificate. The data is also encrypted with the sender’s certificate (encryption
certificate in the PKCS#12 file), so the sender can decrypt messages they sent to other parties.
Note: In the sample application, Send contains info for sender certificates, and Receive holds info
for recipient key and certificates. The user ‘thawte’ is sender and user ‘global’ is recipient.
java Receive theircert.p12 theirpassword urcert.cer CACert.cer msg.p7m msg
4. Decode the signed and encrypted s/mime file, decrypt the content, verify message signature
and signer’s certificate:
Command line parameters
java Receive pfxfile password sendercert senderissuercert input output
a) rcpt .pfx file
b) password
c) sender certificate
d) sender issuer certificate for trust point
e) input S/MIME file name
f) output file name
Note: In the sample application, Send contains info for sender certificates, and Receive holds info
for recipient key and certificates. The user ‘thawte’ is sender and user ‘global’ is recipient.
java Receive theircert.p12 theirpassword urcert.cer CACert.cer msg.p7m msg
The sender can decrypt messages they sent to other parties. If you have only one PKCS#12 file,
you still can use it for message decryption. Substitute the PKCS#12 file you will use for
theircert.p12. The sender’s digital certificate is attached to the message. It will be verified using
the chain of trust and credentials available in the PKCS#12 file you use.
rcptcert.p12 – name of the PKCS#12 file you use, can be the same as mycert.p12
rcptpassword – password for theircert.p12
msg.p7m – signed and encrypted data with S/MIME message headers
msg – decoded data file
urcert.cer – sender certificate
CACert – The trust point certificate
Sample Code
Message encoding
SMimeSend.java
Message decoding
Third Party Toolkits for S/MIME File Processing
Page 17 of 30
Receive.java
Sample Encoded Data File
wedge.txt.p7m
Third Party Toolkits for S/MIME File Processing
Page 18 of 30
Phaos S/MIME Toolkit for Java
Overview
Phaos S/MIME Toolkit for Java is a pure-Java implementation of the cryptographic and secure
messaging APIs used by applications that protect privacy, integrity, and authenticity of
information.
Vendor
Phaos Technology Corp.
Product Name and Version
Phaos S/MIME Secure Messaging Toolkit for Java
http://www.phaos.com/products/smime/smime.html
Environment
The sample applications have been tested on the following operating systems. For specifics on
all the operating systems the toolkit is compatible with contact the vendor.
•
•
•
Microsoft® Windows® NT 4.0 (Service Pack 6a)
Microsoft Windows 2000 Professional Edition (Service Pack 2)
SUN Solaris™ 8
In addition to Phaos S/MIME Toolkit for Java 2.2, the following software products are necessary
to use the sample applications:
Sun Microsystems Java 2 Software Development Kit (J2SDK) 1.3.1
http://java.sun.com/j2se/1.3/
Sun Microsystems JavaBeans Activation Framework (JAF) 1.0.2
http://java.sun.com/products/javabeans/glasgow/jaf.html
Sun Microsystems JavaMail API
http://java.sun.com/products/javamail/index.html
Phaos Security Engine 2.2.3
http://www.phaos.com/products/security_engine/pse.html
Third Party Toolkits for S/MIME File Processing
Page 19 of 30
Product Setup
Refer to the Phaos documentation and user's guides supplied with the toolkit for the specifics on
installing and configuring the toolkit.
Message Specification
The following MIME types are supported:
multipart/signed
application/x-pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs10
application/pkcs7-signature
application/pkcs7-mime
application/pkcs10
Sample S/MIME v3 message header
Message-ID: <1156004.1044290443213.JavaMail.ab01234@111GECDW1234>
Date: Mon, 3 Feb 2003 11:40:43 -0500 (EST)
Mime-Version: 1.0
Content-Type: application/pkcs7-mime; smime-type=enveloped-data; name=".\\data\\1.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=".\\data\\1.pdf"
MIME Message Structure
The following MIME message structure is supported by the sample code:
S/MIME envelope
Encrypted Content (PKCS#7)
Signed Content
MIME multipart
MIME bodypart
Data file
Third Party Toolkits for S/MIME File Processing
Page 20 of 30
Development Settings
Required Libraries
Phaos S/MIME Toolkit for Java (located in \Phaos_SMIME_2.2\lib directory)
Phaos_SMIME.jar
Phaos Security Engine (located in \Phaos_Security_Engine_2.2.3\lib directory)
Phaos_Security_Engine.jar
JavaMail
mail.jar
JavaBeans Activation Framework
activaton.jar
Classpath
Make sure your CLASSPATH environment variable includes the required jar files.
An application using the S/MIME API must have all the necessary MIME types registered in its
command map. The example programs manage the required command map entries, there is no
need to set up and maintain the "mailcap" file.
Commands
The Phaos toolkit code samples make use of the Personal Information Exchange PKCS#12
profile (p12/pfx) to create digital signatures. The p12 profile has to be set up before using the
sample code.
The following steps will help you get started with the sample code:
Set your CLASSPATH environment variable to include the required Phaos Java Toolkit jar files,
JavaMail and JavaBeans Activation Framework (JAF) jar files.
In the java code examples, review the “mailcap” section to make sure it reflects your specific mail
system configuration for content types and content handlers.
The following steps show how to create a signed and encrypted S/MIME file, then verify the
signature and certificate and view the decrypted contents:
1. Open a command prompt window, and change the current directory to the folder you copied
the sample code into.
2. Compile the sample programs using Java compiler:
javac SendMsg.java
javac ReceiveMsg.java
3. Create a signed and encrypted s/mime file:
Third Party Toolkits for S/MIME File Processing
Page 21 of 30
Command line parameters
java SendMsg mycert.p12 mypassword .\data\msg.txt .\data\msg.txt.p7m .\cert\recipient.cer
mycert.p12 – name of the PKCS#12 profile file you use. This is the sender’s profile.
mypassword – password for myprofile.epf
msg.txt – the data file to be signed and encrypted in S/MIME format
msg.txt.p7m – signed and encrypted data with S/MIME message headers
recipient.cer – recipient’s valid X.509 certificate in DER format
Substitute your own profile name, password and the data file names to run the example. The data
file will be signed with the signing certificate in the PKCS#12 file and encrypted with the
recipient’s certificate. The data is also encrypted with the sender’s certificate (encryption
certificate in the PKCS#12 file), so the sender can decrypt messages they sent to other parties.
4. Decode the signed and encrypted s/mime file, decrypt the content, verify message signature
and signer’s certificate:
java ReceiveMsg theircert.p12 theirpassword .\data\msg.txt.p7m .\data\msg.txt
The sender can decrypt messages they sent to other parties. If you have only one PKCS#12 file,
you still can use it for message decryption. Substitute the PKCS#12 file you will use for
theircert.p12. The sender’s digital certificate is attached to the message. It will be verified using
the chain of trust and credentials available in the PKCS#12 file you use.
theircert.p12 – name of the PKCS#12 file you use, can be the same as mycert.p12
theirpassword – password for theircert.p12
msg.txt.p7m – signed and encrypted data with S/MIME message headers
msg2.txt – decoded data file
Sample Code
Message encoding
SendMsg.java
Message decoding
ReceiveMsg.java
Sample Encoded Data File
msg.txt.p7m
Third Party Toolkits for S/MIME File Processing
Page 22 of 30
IAIK Java Toolkit
Overview
IAIK-S/MIME toolkit is a pure-Java implementation of the cryptographic and secure messaging
APIs used by applications that protect privacy, integrity, and authenticity of information. IAIKS/MIME is a Java Implementation of the S/MIME v2 standard. IAIK-S/MIME operates on top of
the IAIK-JCE Java Cryptography Extension APIs. The IAIK Java Cryptography Extension (IAIKJCE) is a set of APIs and implementations of cryptographic functions, including symmetric,
asymmetric, stream, and block encryption methods. It supplements the security functionality of
the default Java JDK 1.1.x / JDK 1.2, which itself includes digital signatures (DSA) and message
digests (MD5, SHA).
Vendor
Institute for Applied Information Processing and Communications (IAIK)
Graz University of Technology
Product Name and Version
IAIK-S/MIME version 2.6
http://jce.iaik.tugraz.at/products/03_smime/index.php
Environment
The sample applications have been tested on the following operating systems. For specifics on
all the operating systems the toolkit is compatible with contact the vendor.
•
•
•
Microsoft® Windows® NT 4.0 (Service Pack 6a)
Microsoft Windows 2000 Professional Edition (Service Pack 2)
SUN Solaris™ 8
In addition to IAIK-S/MIME version 2.6, the following software products are necessary to use the
sample applications:
Sun Microsystems Java 2 Software Development Kit (J2SDK) 1.3.1
http://java.sun.com/j2se/1.3/
Sun Microsystems JavaBeans Activation Framework (JAF) 1.0.2
http://java.sun.com/products/javabeans/glasgow/jaf.html
Sun Microsystems JavaMail API
http://java.sun.com/products/javamail/index.html
Product Setup
Refer to the IAIK documentation for the specifics on installing and configuring the toolkit.
Third Party Toolkits for S/MIME File Processing
Page 23 of 30
The following custom cryptographic service providers are supplied with the IAIK Java Toolkit:
•
The IAIK cryptographic service Provider — implements key generation and other utilities,
as well as the most commonly used symmetric encryption algorithms and message
digests (hash functions)
Message Specification
The following MIME types are supported:
multipart/signed
application/x-pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs10
application/pkcs7-signature
application/pkcs7-mime
application/pkcs10
Sample S/MIME v3 message header
Message-ID: <6478569.1046270359274.JavaMail.an94706@111GECDW8119>
Date: Wed, 26 Feb 2003 09:39:13 -0500 (EST)
Mime-Version: 1.0
Content-Type: application/x-pkcs7-mime; smime-type=enveloped-data; name=smime.p7m
Content-Transfer-Encoding: base64
MIME Message Structure
The following MIME message structure is supported by the sample code:
S/MIME envelope
Encrypted Content (PKCS#7)
Signed Content
MIME Multipart
MIME Bodypart
Data File
Development Settings
Classpath
Make sure your CLASSPATH environment variable includes the required IAIK jar files.
An application using the S/MIME API must have all the necessary MIME types registered in its
command map. The example programs manage the required command map entries, there is no
need to setup and maintain the "mailcap" file.
Third Party Toolkits for S/MIME File Processing
Page 24 of 30
Command line parameters
java SMIMESend <PFXFileName> <PFXPassword> <EncryptionCert> <InputFileName>
java SMimeReceive <pfx file> <password> <smime file> <decoded file> <verification cert>
Sample Code
Message encoding
SMimeSend.java
Message decoding
SMimeReceive.java
Sample Encoded Data File
testing-2-1.txt.p7m
Third Party Toolkits for S/MIME File Processing
Page 25 of 30
Bouncy Castle Java Toolkit
Overview
Bouncy Castle Java Toolkit is a pure-Java implementation of the cryptographic and secure
messaging APIs used by applications that protect privacy, integrity, and authenticity of
information. Supported functionality includes generation, transmission, and storage of its users'
cryptographic keys, using a Certification Authority (CA) and Public Key Infrastructure (PKI),
secure encryption and decryption algorithms to provide privacy, and digital signatures to assure
the integrity and authenticity of the data.
The toolkit contains a light-weight API suitable for use in any environment with the additional
infrastructure to conform the algorithms to the JCE framework.
Bouncy Castle Java Toolkit is a freeware and therefore the software is provided “as is” with
limited access to support online.
See the legal/license disclaimer (http://www.bouncycastle.org/license.html).
Vendor
The Legion Of The Bouncy Castle
Product Name and Version
Bouncy Castle JCE 1.1.8 and CMS/SMIME 1.1.8 Toolkit for Java 1.4.1
http://www.bouncycastle.org/latest_releases.html
Environment
The sample applications have been tested on the following operating systems:
•
•
•
Microsoft® Windows® NT 4.0 (Service Pack 6a)
Microsoft Windows 2000 Professional Edition (Service Pack 2)
SUN Solaris™ 8
Being pure Java implementation, Bouncy Castle applications are platform-independent.
In addition to the Bouncy Castle toolkit, the following software products are necessary to use the
sample applications:
Bouncy Castle Crypto Provider 1.1.8 for JDK 1.4.1
http://www.bouncycastle.org/latest_releases.html
Sun Microsystems Java 2 Software Development Kit (J2SDK) 1.4.1
http://java.sun.com/j2se/1.4/
Sun Microsystems JavaBeans Activation Framework (JAF) 1.0.2
http://java.sun.com/products/javabeans/glasgow/jaf.html
Sun Microsystems JavaMail API
Third Party Toolkits for S/MIME File Processing
Page 26 of 30
http://java.sun.com/products/javamail/index.html
If you plan to use online PKI, the following is necessary:
Java Naming and Directory Interface (JNDI) and LDAP Service Provider
http://java.sun.com/products/jndi/index.html
Product Setup
Refer to the Bouncy Castle documentation (readme.html) for the specifics on installing and
configuring components.
Message Specification
The following MIME types are supported:
multipart/signed
application/x-pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs10
application/pkcs7-signature
application/pkcs7-mime
application/pkcs10
Sample S/MIME v3 message header
Message-ID: <1156004.1044290443213.JavaMail.ab01234@111GECDW1234>
Date: Mon, 3 Feb 2003 11:40:43 -0500 (EST)
Mime-Version: 1.0
Content-Type: application/pkcs7-mime; smime-type=enveloped-data; name=".\\data\\1.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=".\\data\\1.pdf"
MIME Message Structure
The following MIME message structure is supported by the sample code:
S/MIME envelope
Encrypted Content (PKCS#7)
Signed Content
MIME multipart
MIME bodypart
Data file
Development Settings
Required Libraries
Bouncy Castle Java Toolkit
bcmail-jdk14-118.jar
Bouncy Castle Crypto Provider 1.1.8
bcprov-jdk14-118.jar
Third Party Toolkits for S/MIME File Processing
Page 27 of 30
JavaMail
mail.jar
JavaBeans Activation Framework
activaton.jar
Optional Libraries
JNDI
jndi.jar
LDAP Provider
ldap.jar
providerutil.jar
Classpath
Make sure your CLASSPATH environment variable includes the required jar files.
An application using the S/MIME API must have all the necessary MIME types registered in its
command map. The example programs manage the required command map entries, there is no
need to set up and maintain the "mailcap" file.
Sample Code
Message encoding
SendMessage.java
Message decoding
ReceiveMessage.java
Command line parameters
java SendMessage test.pfx password your.cer inputfilename
java ReceiveMessage theirprofile.epf theirpassword msg.txt.p7m msg.txt
Third Party Toolkits for S/MIME File Processing
Page 28 of 30
Sample Encoded Data File
testBC.txt.p7m
Comments
The BC code samples make use of the PKCS12 file (pfx or p12) to create digital signatures.
The following steps will help you get started with the sample code:
Set your CLASSPATH environment variable to include the required BC Java Toolkit jar files,
Junit, JavaMail and JavaBeans Activation Framework (JAF) jar files.
The following steps show how to create a signed and encrypted S/MIME file, then verify the
signature and certificate and view the decrypted contents:
1. Open a command prompt window, and change the current directory to the folder you copied
the sample code into.
2. Compile the sample programs using Java compiler:
javac SendMessage.java
javac ReceiveMessage.java
3. Create a signed and encrypted s/mime file:
java SendMessage myprofile.pfx mypassword .\data\msg.txt recipient.cer
myprofile.pfx – name of the PFX file you use. This is the sender’s profile.
mypassword – password for myprofile.pfx
msg.txt – the data file to be signed and encrypted in S/MIME format
recipient.cer – recipient’s valid X.509 certificate in DER format
Substitute your own profile name, password and the data file names to run the example. The data
file will be signed with the signing certificate in the PFX file and encrypted with the recipient’s
certificate. The data is also encrypted with the sender’s certificate (encryption certificate in the
PFX File), so the sender can decrypt messages they sent to other parties.
4. Decode the signed and encrypted s/mime file, decrypt the content, verify message signature
and signer’s certificate:
java ReceiveMessage theirprofile.pfx theirpassword .\data\msg.txt.p7m .\data\msg2.txt
The sender can decrypt messages they sent to other parties.
theirprofile.pfx – name of the PFX file you use, can be the same as theirpassword – password for
theirprofile.pfx
msg.txt.p7m – signed and encrypted data with S/MIME message headers
msg2.txt – decoded data file
Third Party Toolkits for S/MIME File Processing
Page 29 of 30
Disclaimer
The authoritative and official text of this CitiDirect® Online Banking documentation shall be in the
English language as used in the United States of America. Any translation of any CitiDirect
documentation from English to another language is done solely for the convenience of the reader,
and any inconsistencies, or inaccuracies between the English text and that translation shall be
resolved in favor of the English text.
These materials are proprietary and confidential to Citibank, N.A., and are intended for the
exclusive use of CitiDirect Online Banking customers. The foregoing statement shall appear on all
copies of these materials made by you in whatever form and by whatever means, electronic or
mechanical, including photocopying or in any information storage system. In addition, no copy of
these materials shall be disclosed to third parties without express written authorization of
Citibank, N.A.
Customer shall be solely responsible for the use of any User identifications, passwords and
authentication codes that may be provided to it, from time to time, in connection with CitiDirect
Online Banking (collectively, "User IDs"). Customer agrees to keep all User IDs strictly
confidential at all times. Customer shall immediately cease use of CitiDirect Online Banking if it
receives notification from Citibank, or otherwise becomes aware of, or suspects, a technical
failure or security breach. Customer shall immediately notify Citibank if it becomes aware of, or
suspects, a technical failure or
security breach.
July, 2003
© 2003 Citibank, N.A. All rights reserved.
CITIDIRECT, CITIGROUP, and the Umbrella Device are trademarks and service marks of
Citicorp or its affiliates and are used and registered throughout the world.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation
in the United States and/or other countries. All other brands, products, and service names
mentioned are trademarks or registered trademarks of their respective owners.