The NIST S/MIME Test Facility (NSMTF) Instructions for Use
Introduction:
This page describes the basic operational details of the NIST S/MIME Test Facility (NSMTF) for testing implementations of S/MIME Version 3 as profiled by the Federal S/MIME V3 Profile. The NSMTF provides an automated email responder that allows each remote tester (RT) to send and receive SignedData and EnvelopedData SMIME V3 ASN.1 encoded data. The NSMTF responds to e-mail from users, where the subject line describes the operation to be performed. The SMTP "FROM" indicates the email address of the RT. The NSMTF performs the requested operation and responds with e-mail to the RT. The e-mail response from the NSMTF will contain the data requested or a message of success or error.
All interaction with the NSMTF is by email exchange. (There is no direct web interface.) The NSMTF operates in a command-response mode with the remote tester (RT). The “Subject” line of each valid message sent to the NMSTF contains a command to instruct the NSMTF how to respond. For example the RT may send a message to the NSMTF with a Subject Line of:
“SIGN:1234567:SinglePart:RSA”
This Subject Line is a command instructing the NSMTF to respond with an email message that consists of signed, single-part (opaque) body. The signature algorithm to be used by the NSMTF is RSA. The signed message is sent back to the email address of the remote tester. The part of the subject line that contains “1234567” is an example of a “Retrieval Identifier” (RetID) of a RT. Each RetID is unique to the address used by each remote tester. The RetID is assigned by the NSMTF as part of an initial exchange of messages used by a RT to establish a testing environment with the NSMTF.
Operational Status:
The NIST S/MIME V3 Test Facility is now open for limited-use testing. Due to decreases in funding and available manpower, further development of and support for the test facility has been indefinitely suspended. NIST plans to have the test facility remain on-line indefinitely and be available on an "as is" basis, i.e., with little to no NIST support available.
As of 23 July 2004, the operating version of NSMTF is release 2.2. There are no scheduled maintenance periods (i.e., system “down time”) currently established, and the system should be up and running almost all of the time. However, there may be short outages for maintenance and power failures.
Introduction
All remote testing interaction with the NSMTF is by email exchange. The NSMTF operates in a command-response mode with the remote tester. The “Subject” line of each valid message from the remote tester to the NSMTF carries a “command” to be followed by a “response” (in the form of an email message) from the NSMTF to the remote tester.
Before testing of S/MIME
operations can begin, each remote tester must be given a “Retrieval Identifier”
(RetID). RetID’s are generated randomly
by the NSMTF. Once assigned, each
RetID is uniquely bound to a single email address associated with a remote
tester (RT). Once a RetID has been bound to an email address, subsequent email
messages from that email address will be IGNORED (no error message) unless the
RetID is included in these subsequent messages!
Subject Line Formatting
On the subject line of each “command” sent to the NSMTF, the remote tester may append at least one colon character and any free form text to the command line. The NMSTF will include this same text to the RT in the “command response” message. Thus RTs can use this free form text to add short comments or identifying information to each command so that they can easily correlate commands and responses sent to and received from the NSMTF. (Note: It is possible that responses from the NSMTF may not be returned to the remote tester in the same order as the corresponding “commands” were sent to the NSMTF.)
To allow for ease of readability of the command/response lines, the NSMTF allows for one or more spaces between fields of the “command” message. Thus in the example cited in the “Introduction” above, rather than send a message to the NSMTF with a Subject Line of:
“SIGN:1234567:SinglePart:RSA”, the RT could send the equivalent message of:
Addresses of the NSMTF
The email addresses of the NSMTF are:
All email to the NSMTF must be sent to one of these addresses. Responses will come from the address to which the email message was directed. Any of the commands described below may be sent to any of the email addresses. The email addresses only differ in the contents of the certificates that have been issued to them. The nisttest1@smime2.nist.gov address is the address that will be most commonly used.
In the certificates associated with the nisttest1, nisttest3, and nisttest4 addresses, the email address appears in the subjectAltName extension. In the certificates associated with the nisttest2 address, the email address appears as an RDN in the subject field. For example, the certificates associated with nisttest1 have the subject name “cn=NIST Test1, ou=NIST, o=U.S. Government, c=US” and they include subjectAltName extensions with a single value of type rfc822Name, “nistTest1@smime2.nist.gov”. The certificates associated with nisttest2, on the other hand, have the subject name “e=nistTest2@smime2.nist.gov, cn=NIST Test2, ou=NIST, o=U.S. Government, c=US” and have no subjectAltName extension.
The DSA certificates issued for the nisttest1, nisttest3, and
nisttest4 addresses inherit DSA parameters to allow for DSA parameter
inheritance testing. For the nisttest2@smime2.nist.gov address,
the DSA parameters are included in the DSA certificate.
The certificates issued for nisttest3@smime2.nist.gov are all revoked, so that the remote tester
can test his/her implementations for S/MIME certificate revocation
handling. The certificates issued for nisttest4@smime2.nist.gov are all expired to allow testing for S/MIME
certificate expiration handling.
The “To:” line of all messages sent to the NSMTF should contain one and
only one of the addresses above. (Do
not put any other addresses on the “To:” line.) If you wish to send an exact copy of your test message to another
address, please use the “cc:” line.
Establishment of the
Remote Tester’s Credentials
To establish a RetID, the RT must send a BuildCertificates command to the NSMTF. The message must originate from the email address that is to be used for testing. If a correctly formatted BuildCertificates command is sent to the NSMTF, the NSMTF will respond not only with the RetID but also with PKCS12 packages that include the X.509 certificates and private keys for the RT to use in subsequent S/MIME messages. Two certificates will be issued – each contained in a single PKCS12 package. One certificate has key usage set to “Digital Signature and Non-Repudiation”; the other has key usage set to “Key Encipherment”. The certificates have the email address of the RT bound to both the “Subject” field of the cert and bound to the “Subject Alternative NameRFC822 Name” field. Here is an example of a certificate “Subject” field: E = RemoteUser@RemoteSite.com, OU = RSAEncrypter, CN = NIST RSA Test User, OU = RSA, O = U.S. Government, C = US. The corresponding Subject Alternative Name field has the value: RFC822 Name= RemoteUser@RemoteSite.com.
Note that the BuildCertificates command itself is sent in a non-S/MIME message. The password used in all PKCS12 packages is “password”. (There is no need for a secret password for the testing.)
There are currently two variants of the BuildCertificates command. One generates DSA-signed certs; the other RSA-signed certs. Either one may be used first, but the second one used must include the RetID returned in response to the first.
Once the PKCS12 packages have been received, the RT administrator should install the certs and private keys as appropriate for the PKI environment on the RT.
Establishment of the NSMTF’s Certificates
To allow the RT to establish a trust path back to the NSMTF, it is necessary to install the NSMTF’s self-signed root certificate and intermediate CA certificates. These certs can be retrieved with the NCTRetrieveCertificates commands. These are: “COMMAND:RetrieveNCTCertificates:RetID:DSA” and “COMMAND:RetrieveNCTCertificates:RetID:RSA”
The files returned to the RT include the Certificate Path items for the NSMTF signing/encrypting certificate(s). This includes the NMSTF End Entity issuer, the issuer’s issuer (i.e., in this case the NIST Test CA root certificate), and any appropriate CRLs. In addition, a final binary SignedData file is provided that contains all of these other files in the certificate/CRLs element for direct import.
“COMMAND:RetrieveNCTCertificates:RetID:DSA” retrieves the following files:
“COMMAND:RetrieveNCTCertificates:RetID:RSA” retrieves the following files:
This message is used to request the NSMTF to respond with a message with signed content data and produce either single-part (also known as “opaque” signed) or multi-part message (also known as “clear” signed) according to the subject line command request. The subject line request format is: SIGN:RetID:PartType:Alg
For example:
The specified AlgType(s) for that retrieval id will be used to sign the content. The body of the user message is used for the signature. The single or multi-part signed data e-mail is returned to the user for this request if successful. Otherwise, an error message is sent.
Verify Signed Data SMTP
Message
This message is used to request the NSMTF to verify a message that is signed by the remote tester. The subject line request is VerifySignedData:RetID. The message may be sent either multipart (“clear”) or singlepart (“opaque”). The NSMTF will attempt to verify the message and respond with the results of the verification.
For example:
This message is used to request the NSMTF to encrypt data. The subject line request format is: ENCRYPT:RetID:ContentAlg
For example:
It is important to specify the correct RetID and to specify a valid ContentAlg for establishment of the desired content encryption algorithm for encryption. (Currently “3DES”, “AES128”, “AES192”, “AES256” are supported.) The response message from the NSMTF is encrypted through use of the SMTP “FROM” RSA key encipherment certificate.
The response from the NSMTF contains encrypted data according to the request. The encrypted data is an envelopedData e-mail returned to the user for this request if successful. Otherwise, an error message is sent.
This message is used to request the NSMTF to decrypt data contained in an S/MIME message sent to the NSMTF. The subject line request format is: DECRYPT:RetID.
For example:
The requesting message must have the remote tester in RecipientInfo in order for the decryption to succeed.
The response from the NSMTF
contains decrypted data. The decrypted
data details are in a single bodypart of the response message returned to the remote
tester (RT) for this request if successful.
Otherwise, an error message is sent.
Sign Encrypt SMTP Message
This message is used to request the NSMTF to sign and then encrypt data contained in the S/MIME message sent to the NSMTF. The subject line request format is: SignEncrypt:RetID:SignAlg:ContentAlg.
For example:
The response message is first signed by the NSMTF DSA or RSA private key (based on “SignAlg”), and then encrypted through use of the SMTP “FROM” RSA key encipherment certificate (and optionally the NMSTF RSA certificate as well).
The signing algorithm is specified by “SignAlg”. It can be either “DSA”, “RSA”, or “BOTH”. The content encryption is specified by “ContentAlg”. It can be either “3DES”, “AES128”, “AES192”, or “AES256”. The signed and encrypted data are in the envelopedData of the response message returned to the remote tester (RT) if successful. Otherwise, an error message is sent. This application will produce ONLY MIME SinglePart (Opaque) signed messages. It will process both MIME SinglePart (Opaque) and MIME Multipart (Clear) signed messages for the DecryptVerify command.
This message is used to request the NSMTF to decrypt and then verify signed data contained in the S/MIME message sent to the NSMTF. The subject line request format is: DecryptVerify:RetID
For example:
The request message must have the remote tester (RT) in RecipientInfo in order for the decryption to succeed. The decryption process must succeed before the SignedData can be verified.
The NSMTF response message includes the decryption and verification details in a single body part if the request message can successfully be decrypted and verified. Otherwise, an error message is sent.
The NSMTF will
process both MIME SinglePart (Opaque) and MIME Multipart (Clear) signed
messages sent in a DecryptVerify request.
This message is used to request the NSMTF to sign, encrypt, then re-sign data according to the subject line request. The subject line request format is: TripleWrap:RetID:SigningAlg:ContentAlg
For Example:
RSA is the currently the only supported key encipherment algorithm. The message is first signed by the NIST server signing private key(s), then encrypted to the specified SMTP “FROM” user certificate (and optionally the NIST RSA certificate as well), then finally re-signed. Only the specified signing algorithm is used for both the inner and outer signatures; the SigningAlg can be “RSA”, “DSA”, or “BOTH”.
The format of the NSMTF response message is defined in RFC 2634, “Enhanced Security Services for S/MIME”, June 1999. The signed, encrypted, and re-signed data are in the single-part MIME wrapped signedData of the e-mail response message returned to the remote tester (RT) for the Triple Wrap request if successful. Otherwise, an error message is sent.
This message is used to
request the NSMTF to sign, encrypt, then re-sign data according to the subject
line request. The subject line request
format is: TripleUnwrap:RetID. The message content is expected to be a single-part
SignedData, MIME encoded.
For Example:
The NSMTF will attempt to verify, decrypt, and verify the enclosed signed, encrypted, and re-signed message. It is important that the remote tester (RT) encrypted a RecipientInfo using the NSMTF RSA key encipherment certificate. If not, then the decryption operation will fail and an appropriate error message will be sent back to the RT. If successful, a report indicating the inner and outer signature verification, attribute list and decryption results will be sent back to the RT.
NSMTF Directory: All interaction with the NSMTF is by email exchange, although there is an LDAP directory at smime2.nist.gov (Port 389). The self-signed root and intermediate certificates issued by the NSMTF are publicly available at this directory. The user (remote tester) certificates issued by the NSMTF are not published in this directory. They are stored internally to the NSMTF and are intended to be used only by remote testers and only for testing purposes with the NSMTF.
These instructions were updated 23 July 2004 by Michael Chernick.
NSMTF SMTP Message Formats Summary Table
This table summarizes all of the messages
that are exchanged between a remote tester (RT) and the NIST S/MIME Test
Facility (NSMTF)
|
Description |
Subject |
SMTP MIME Message Details |
Body Contents |
|
Build/Retrieve Certificates |
COMMAND:SubCommands:RetID:AlgType:Size:ExpDate Notes for current version of NMSTF:AlgType Is “RSA” or “DSA”, Size is”1024”, ExpDate is expiration date in format shown in examples below. Size and ExpDate may be omitted and default to 1024 and 11/24/04 respectively |
Single-part MIME (RetID is optional on the 1st BuildCertificates command) |
Empty Body |
|
Sub-Commands |
|||
|
COMMAND:BuildCertificates:DSA:1024:01/01/2001 |
|||
|
COMMAND:BuildCertificates:RetID:RSA:1024:01/01/2001 |
|||
|
COMMAND:RetrieveNCTCertificates:RetID:DSA |
|||
|
COMMAND:RetrieveNCTCertificates:RetID:RSA |
|||
|
COMMAND:RetrieveCertificates:RetID:DSA |
|||
|
COMMAND:RetrieveCertificates:RetID:RSA |
|||
|
Signed Data SMTP Message |
SIGN:RetID:SinglePart:Alg Example: Sign:100:SinglePart:RSA |
Single-part MIME |
Content to be Signed |
|
SIGN:RetID:Multipart:Alg Example: Sign:100:Multipart:DSA |
Multi-part MIME |
||
|
Verify SignedData SMTP Message |
VerifySignedData:RetID Example: VerifySignedData:100 |
Single-part/Multi-part MIME |
Single/Multi-part |
|
Encrypt SMTP Message |
ENCRYPT:RetID:ContentAlg Note: 3DES, AES128, AES192, AES256 are currently the only supported algorithms. Example: ENCRYPT:100:3DES |
Single-part MIME |
Content to be Encrypted |
|
Decrypt SMTP Message |
DECRYPT:RetID Example: DECRYPT:100 |
Single-part MIME |
Single-part EnvelopedData |
|
Sign Encrypt SMTP Message |
SignEncrypt:RetID:SignAlg:ContentAlg Example: SignEncrypt:100:RSA:3DES |
Single-part MIME |
Content to be Signed, then Encrypted |
|
Decrypt Verify SMTP Message |
DecryptVerify:RetID Example: DecryptVerify:100 |
Single-part MIME |
Single-part EnvelopedData to be Decrypted, then Single-Part Signed or Multi-part Signed contents to be Verified |
|
TripleWrap SMTP Message |
TripleWrap:RetID:SigningAlg:ContentAlg Example: TripleWrap:100:RSA:3DES |
Single-part MIME |
Content to be inner-signed. |
|
TripleUnwrap SMTP Message |
TripleUnwrap:RetID Example: TripleUnwrap:100 |
Single-part MIME |
Single-part SignedData |