DRAFT S/MIME Freeware Library Software Design Description Version 0.1 10 March 1998 Produced By: J.G. Van Dyke & Associates, Inc. 6550 Rock Spring Dr, Suite 360 Bethesda, MD 20817 http://www.jgvandyke.com Revision History Table of Contents 1. Scope…………………….…………………………………….…….………. 1 1.1. Identification………………………..………………….…..….………. 1 1.2. System Overview…………………….……………….………………. 1 1.3. Document Overview………..……….……………………………….. 1 2. Referenced Documents………..………………………………………. 2 3. System Design Requirements ....……………………………………. 3 3.1. CMS/ESS Support….……………………..….……………..…….…. 3 3.2. Distribution………………..……………….…..………………………. 3 3.3. Supported Operating Systems…………………….………………. 4 3.4. Cryptographic Algorithms…………………………………………. 4 3.5. X.509 Certificate and CRL Support…………….…………….…. 5 3.6. Future Capabilities……………………………….……………….…. 5 4. Architectural Design…………………………………….….…………. 5 4.1. Overview…………………………………………….……………….…. 5 4.2. SFL High-Level Library.………………………………..……….…... 7 4.3. SFL ASN.1 Library.…….………………………………..……….….. 7 4.4. SFL BSAFE Library……………………………….……………….…. 8 4.5. SFL Crypto++ Library…………….…………..….……………….…. 8 4.6. SFL Fortezza Library…………….…………………………..…….…. 8 4.7. External Interfaces…………….………………….…..…………….…. 9 5. Point of Contact……………………………………….….….…….….... 1. Scope 1.1. Identification This draft Software Design Description (SDD) describes the functionality and high-level design of the Secure/Multipurpose Internet Mail Extensions (S/MIME) Freeware Library (SFL) being developed by J.G. Van Dyke and Associates, Inc (VDA). 1.2. System Overview The SFL is a reference implementation of the Cryptographic Message Syntax [CMS] that is the basis for the S/MIME Version 3 Message Specification [SMIME3]. CMS is based on the Public Key Cryptography Standard #7 [PKCS7] specification. In conjunction with CMS, the SFL implements the Enhanced Security Services for S/MIME [ESS] that provides Message Security Protocol 4.0 [MSP] equivalent security features such as: signed receipts, security labels, algorithm independence and Mail List (ML) Expansion History information. The MSP 4.0 specification is also known as [ACP120]. It is anticipated that the Internet Engineering Task Force (IETF) will adopt [CMS], [ESS] and [SMIME3] as Internet standard specifications. Organizations can use the SFL as part of their S/MIME applications without paying any royalties or licensing fees. It is being provided at no cost to encourage organizations to include MSP-equivalent optional security features in their commercial S/MIME v3 products and other products that use CMS. It facilitates the use of both commercial and US Government cryptographic algorithms. It can be used in conjunction with external cryptographic libraries to provide the following security services: - authentication, data integrity and proof of origin using digital signatures; - authenticated proof of delivery using digitally signed receipts; and - confidentiality using encryption (note: some key management algorithms, such as the Key Exchange Algorithm (KEA), also provide data origin authentication). 1.3. Document Overview The target audience for the SDD is the set of developers who are creating applications that require CMS and ESS security services. It is recommended that [CMS] and [ESS] should be reviewed before reading this SDD. This draft SDD will be updated as needed as changes are made to [CMS] and [ESS]. It will not be finalized until those documents are accepted by the IETF as final or stable draft specifications. In addition to this SDD, an SFL Application Programming Interface (API) document provides details of the interaction between the application and SFL. Also, a SFL Software Maintenance Document will be developed which will include information required to enhance and maintain the SFL source code such as adding support for additional cryptographic libraries. There are no restrictions on the use or distribution of this document 2. Referenced Documents [ACP120] Allied Communications Publication 120, Common Security Protocol, Oct 1997. [CMAPI] Certificate Management API, v1.0, 11 September 1997, http://www.armadillo.huntsville.al.us/software/certmgmt/index.html. [CMS] Cryptographic Message Syntax, Internet Draft, December 1997, ftp://ds.internic.net/internet-drafts/draft-ietf-smime-cms-02.txt. [ESS] Enhanced Security Services, Internet Draft, 4 January 1998, ftp://ds.internic.net/internet-drafts/draft-ietf-smime-ess-01.txt. [MSP] Message Security Protocol 4.0, SDN.701, Rev A, 1997-02-06, http://www.armadillo.huntsville.al.us/Fortezza_docs/missi2.html#specs. [PKCS7] Public Key Cryptography Standard #7 v1.5, Cryptographic Message Syntax Standard, Internet Draft, ftp://ds.internic.net/internet-drafts/draft-hoffman-pkcs-crypt- msg-03.txt. [PKCS8] Public Key Cryptography Standard #8 v1.2, Private-Key Information Syntax Standard, http://www.rsa.com/pub/pkcs/ascii/pkcs-8.asc. [PKIX] Internet Public Key Infrastructure X.509 Certificate and CRL Profile Internet Draft, IETF PKIX Working Group, October 14, 1997, ftp://ds.internic.net/internet- drafts/draft-ietf-pkix-ipki-part1-06.txt. [SMIME2] S/MIME Message Specification, Internet Draft, 17 November 1997, http://www.imc.org/ietf-smime/draft-dusse-smime-msg. [SMIME3] S/MIME Version 3 Message Specification, Internet Draft, 20 November 1997, ftp://ds.internic.net/internet-drafts/draft-ietf-smime-msg-00.txt. [SMIMEC] S/MIME Version 3 Certificate Handling, Internet Draft, 20 November 1997, ftp://ds.internet.net/internet-drafts/draft-ietf-smime-cert-00.txt 3. System Design Requirements 3.1. CMS/ESS Support The SFL implements [CMS] and [ESS] to provide equivalent security services as provided by MSP 4.0/ACP120. The SFL performs all Abstract Syntax Notation.1 (ASN.1) encoding and decoding of the supported CMS and ESS objects. [CMS] is backward compatible with [PKCS7], so this enables the SFL to be used to support applications that comply with [SMIME2] and [SMIME3]. The SFL protects data independent of the encapsulated content format, so any type of data can be protected. In addition to S/MIME applications, the SFL can be used to support applications implementing protocols such as X.400, File Transfer Protocol (FTP), Secure Socket Layer (SSL), etc. The SFL does not parse the data to be protected. For example, it does not build or parse a MIME header. The SFL implements the CMS SignedData content type to provide the digital signature service. This service supports multiple digital signatures on a single content and optionally on authenticated attributes. The SFL implements the following attributes defined in CMS: contentType, messageDigest, signingTime and counterSignature. It can be used to generate and process a SignedData object that contains only X.509 Certificates and/or X.509 Certificate Revocation Lists (CRL) (i.e. no content). It can be used to generate and validate SignedData objects that include multiple SignerInfos (i.e. multiple signatures on the content). It can be used to add a SignerInfo to an existing SignedData object (equivalent to MSP Additional Signature feature). The SFL implements the CMS EnvelopedData content type to provide the encryption service. This service supports the encryption of any content and the encryption of the content-encryption key for one or more recipients. For each recipient the content- encryption key may be encrypted with a different key management algorithm. The SFL implements the optional OriginatorInfo field in the EnvelopedData syntax to support key management algorithms such as the Diffie-Hellman (DH) algorithm and KEA. The SFL does not implement the CMS EncryptedData or DigestedData content types. The SFL supports the following ESS security services: signed receipts, security labels, and secure mailing lists. It implements the ESS Receipt content type. It implements the following attributes defined in [ESS]: securityLabel, receiptRequest, mlExpansionHistory, contentHints, contentIdentifier and encapsulatedContentType. The SFL implements the SMIMECapabilities attribute defined in [SMIME3]. 3.2. Distribution The SFL serves as a reference implementation of functions that build and process CMS/ESS objects. All source code for the SFL is provided at no cost and with no limitations regarding its use and distribution. Organizations can use the SFL as part of their applications without paying any royalties or licensing fees. The SFL is being provided at no cost to encourage organizations to include MSP-equivalent optional security features in their S/MIME v3 products. 3.3. Supported Operating Systems The SFL is developed to operate on Sun OS 4.1.3, MS Windows 95 and MS Windows NT. It will be thoroughly tested on these platforms. The tested libraries (in addition to the source code) will be provided for these platforms. It is developed to maximize portability to 32-bit operating systems. In the future, support may be added for other operating systems such as Macintosh, HP/UX 9.x/10.x, IBM AIX 3.2, Sun Solaris 2.6 and SCO ODT 3.0/5.0. 3.4. Cryptographic Algorithms In this document, the term “crypto token” is used to refer to the software and/or hardware used to implement a set of crypto algorithms. The Fortezza Card is an example of a crypto token. The crypto software modules contained within the BSAFE and Crypto++ libraries are examples of crypto tokens. The term “crypto token library” is used to refer to an external library used by the SFL to access the crypto algorithms and related security services provided by a crypto token. The Fortezza Cryptologic Interface (CI) Library, BSAFE and Crypto++ are examples of crypto token libraries. The term “Crypto Token Interface (CTI) Library” is used to refer to an internal SFL library that provides abstracted crypto services using one or more crypto token libraries. For example, there is a SFL Fortezza CTI Library that calls the Fortezza CI Library to access the DSA, KEA, and Skipjack algorithms. There is a SFL Crypto++ CTI Library that calls the Crypto++ library to access the DSA, DES, D-H and SHA1 algorithms. There is a SFL BSAFE CTI Library that calls the BSAFE library to access the MD5, MD2, RSA, and RC2 algorithms. The SFL maximizes crypto algorithm-independence and modularity by calling internal generic functions that are mapped to algorithm-specific CTI Library functions that call crypto token libraries to access the crypto algorithms. Integrating the Fortezza CI Library, BSAFE and Crypto++ crypto token libraries demonstrates the crypto token independence and modularity of the SFL and shows how other crypto token libraries may be added. The underlying crypto token libraries are not distributed as part of the SFL source code. The application developer independently obtains these libraries and then links them with the SFL. This strategy allows the SFL source code to be freely distributed to the entire Internet community because it does not contain software that directly implements any crypto algorithms that are copyrighted or export controlled. 3.5. X.509 Certificate and CRL Support The S/MIME v3 Certificate Handling Specification [SMIMEC] mandates that v1 and v3 X.509 Certificates must be supported by S/MIME agents. It also states that X.509 Certificates and CRLs as profiled by the PKIX Working Group will be used to support authentication and key management. The PKIX X.509 Certificate and CRL Profile [PKIX] provides more information. The SFL supports X.509 v1 and v3 Certificates, X.509 Attribute Certificates (AC), and X.509 v2 CRLs. [SMIMEC] states that PKCS #6 Extended Certificates must not be used, so they are not supported by the SFL. 3.6. Future Capabilities The initial release of the SFL does not generate or process certificate management messages. However, the SFL can be used to protect certificate management messages within CMS objects. A future release of the SFL may include the capability to generate and process certificate management messages. Currently, the SFL does not transfer private key material, so it does not implement PKCS #12: Personal Information Exchange Syntax Standard. In the future, the SFL may be enhanced to implement PKCS #12. In the future, SFL CTI Libraries may be developed for the RSAREF library and Microsoft Crypto API. 4. Architectural Design 4.1. Overview The SFL is designed in a modular architecture using object-oriented techniques. It is a modular design with two components, the High-Level and CTI. The High-Level API contains CMS and ESS objects and functions necessary for Sign, Verify, Encrypt, Decrypt, and ASN.1 encoding/decoding operations. Those object types are broken down further into specific sub-types and described in the SFL API document. The CTI API provides a generic interface to external Crypto Token libraries. The CTI libraries can be used to support other security protocols such as MSP, SSL, etc. In summary, the High- Level library does not include algorithm-specific logic and the CTI libraries do not contain S/MIME-specific logic. The architecture for the SFL as depicted in Figure 1. The lines on the diagram indicate function calls. The external freeware Certificate Management (CM) Library is shown as an optional (dotted line) source for X.509 Certificate management. The CM Library is described in [CMAPI]. The SFL does not directly use the CM library. Several of the SFL component libraries will provide both C and C++ APIs. Initially, only the C++ API will be provided. In later releases of the SFL, the C API will be added. The C API will be a simple wrapping of the C++ Objects/Methods in C API functions. This maximizes the usefulness of the SFL because it can support applications that can call upon C and/or C++ functions. The SFL is designed to take full advantage of the rich features of the C++ language. In this architecture, the application must be aware of the crypto token library(s) that are available. For example, it must know that RSA algorithms are available through the BSAFE crypto token library. When the application starts, it directly queries the appropriate CTI library that it requires through the C++ API. The SFL CTI library that is queried obtains initialization information from the appropriate Crypto Token library and returns a class pointer to be used as a parameter when calling SFL High-Level functions. By doing this, the SFL High-Level functions can call functions in the appropriate SFL CTI Library in a manner that is entirely algorithm independent. Implementation of the SFL BSAFE, SFL Crypto++ and SFL Fortezza CTI Libraries demonstrates the crypto token independence of the architecture (i.e. new crypto tokens can be integrated without re-compiling the SFL high-level functions). 4.2. SFL High-Level Library The SFL High-Level library utilizes a set of objects to perform all CMS and ESS operations. These objects are designed for specific operations such as Sign, Verify, Encrypt, and Decrypt. They hide low level complexity from the application. The SFL High-Level objects do not use algorithm specific logic. Algorithm-unique features are hidden in the CTI information that is passed in as a parameter. ASN.1 encoded objects are exchanged between the application and SFL High-Level objects to minimize the dependence of the application on SFL-unique data structures. The security services provided by the crypto tokens are abstracted from the SFL High-Level functions in a manner such that alternate or additional crypto tokens may be integrated without requiring modification or recompilation of the High-Level library. Each SFL High-Level function processes a single CMS object. For example, when receiving a message protected by nested CMS security headings, the application must recursively parse the received message and use the appropriate SFL High-level object to process each layer of the nested CMS security headings. 4.3. SFL ASN.1 Library The SFL uses the freeware SNACC version 1.3 C++ ASN.1 Compiler and Library to perform all encoding and decoding required by the SFL. This includes the supported ESS and CMS objects: Data, SignedData, EnvelopedData, and Receipt. It also includes the aforementioned list of supported attributes. The following X.509 objects are also supported: Certificate (v1 and v3), CRL (v2), and AC. The SFL uses the C++ classes created by the SNACC Compiler throughout the SFL software. The application can use SFL high-level objects to minimize its interaction with the SNACC-generated C++ classes or it can directly access the SNACC-generated C++ classes through the SFL low- level C++ classes. The SFL C API will include functions that convert the SNACC C++ structures to C structures and vice versa. The SNACC ASN.1 Compiler and Library are used since all of the source code can be provided free of charge and there are no limitations regarding its use and distribution. Using the SNACC ASN.1 freeware in conjunction with the SFL maximizes the usefulness of the SFL to the Internet community; thereby, promoting the adoption of CMS and ESS throughout that community. VDA is enhancing SNACC to implement the Distinguished Encoding Rules (DER) and will freely distribute the enhanced software. Because the SNACC source code is provided, application developers could further enhance the SNACC Library and Compiler to meet their specific requirements. 4.4. SFL BSAFE CTI Library As depicted in Figure 1, the SFL BSAFE CTI Library is one of the SFL CTI libraries used by the SFL High-Level objects. It provides an interface to the Crypto Token library that provides RSA-specific processing required for RSA security services. It provides both a C and C++ interface. It calls the BSAFE crypto token library to provide the actual RSA crypto services. The BSAFE CTI Library will use the Private Key Information Syntax Standard [PKCS8] to store and protect the private key material it accesses. 4.5. SFL Crypto++ CTI Library The SFL Crypto++ CTI Library is one of the SFL CTI Libraries used by the SFL High- Level objects. It provides an interface to the freeware Crypto++ Crypto Token library which provides the mandatory crypto algorithms specified in [CMS]. The Crypto++ CTI Library will use PKCS #8 to store and protect the private key material it accesses. 4.6. SFL Fortezza CTI Library The SFL Fortezza CTI Library is one of the CTI Libraries used by the SFL High-Level objects. It provides an interface to the Fortezza CI Library that performs the Fortezza- specific processing required to provide Fortezza security services (such as DSA, KEA and Skipjack algorithms). It provides both a C and C++ interface. It calls SHA-1 freeware to perform hashing. It uses the required private keys stored on the Fortezza Card. 4.7. External Interfaces As shown in Figure 1, the SFL uses the following external crypto token libraries: ? Fortezza CI Library (for access to the Fortezza Card providing DSA, KEA and Skipjack); ? SHA-1 freeware; ? BSAFE library (providing algorithms such as RC2, RSA, MD2, and MD5); and ? Crypto++ library (provides SHA-1, MD5, DSA, D-H, and Triple DES). 5. Point of Contact For further information, contact: John Pawling (301) 953-3600 J.G. Van Dyke & Associates, Inc. (410) 880-6095 141 National Business Pkwy, Suite 210 FAX: (301) 953-2901 Annapolis Junction, MD 20701 jsp@jgvandyke.com DRAFT S/MIME FREEWARE LIBRARY SDD 2